Chapter 19: Run-time Services

In addition to the tools described in earlier chapters, Host Compatibility Option provides other tools that are only invoked when you run or debug your SQL program.

Such run-time tools include the following:

All of these tools are stored in the file mfhcolib.lbr. You do not need copy this file to any other location if you are running under Mainframe Express.

19.1 MFHCOCDS

DB2 Universal Database generally returns the same SQLCODE as DB2 for common errors such as no more rows in table or duplicate index entry. MFHCCODS is a mapping facility provided to support the translation of DB2 Universal Database SQLCODE's to their DB2 equivalent for special situations where the mappings are not the same. The program accesses a user configurable file (see the sample file mfhcocds.sql provided with the software in the \demo subfolder) that can be modified to include additional codes as needed by the application. The file is a line sequential text file and should be placed in the Host Compatibility Option system software folder. It has a format of:

For example, if you want SQLCODE of -30080 (communication error) to be changed to -902 (system error), you would place the following line of text in the file: -30080 -902

19.1.1 Dynamic Bind Utility

The Dynamic Bind Utility enables you to bind dynamically programs that get -805 or -818 SQL errors.

A good example of how you can take advantage of this utility is if your organization has a number of common SQL routines that they share but they use these routines against multiple databases. Someone within the organization, usually the DBA, would have to bind these common modules against each database for them to be used. Another option would be to compile each of these routines against each database. If someone changed one of the common routines, the bind/compile process would have to be repeated for each database!

Host Compatibility Option offers a third option. When you compile an SQL routine, Host Compatibility Option passes additional information to the MFHCOCDS routine when an SQL error occurs. If a -805 or -818 error occurs, Host Compatibility Option tries to find the bind file associated with the routine in error and then bind the package against the database to which the program is currently connected. A message is then displayed reporting whether the bind was successful. The original SQL error is returned to your program so that you need to restart the program or, if you are animating the program, re-execute the SQL statement that originally failed.

To implement this feature, you need to:

The BIND directive creates a bind file for each common routine. When the -805 or -818 SQL error occurs, Host Compatibility Option looks for the bind file using the following search sequence:

  1. Current folder
  2. \data subfolder associated with Mainframe Express project

If you do not want to take advantage of the dynamic bind utility, do one of the following:

19.2 DSNTIAR and DSNTIAC

The Host Compatibility Option DSNTIAR and DSNTIAC routine uses a similar parameter list to the one used by the IBM DSNTIAR and DSNTIAC routines on the mainframe. It is used to convert SQL return codes into more meaningful error messages.

The format for calling DSNTIAR is:

CALL 'DSNTIAR' USING sql-comm-area,error-message,
error-rec-length

where:
 

Parameter
Description
sql-comm-area SQL communications area. Usually set to SQLCA. 
error-message A group item in the Working-Storage Section where the error message is returned. The work area consists of two items, the first being a field defining the length of the error message to be returned. Fields have a value > 0 and < 1,000. The second item is the work area where the error message returns. 
error-rec-length The logical error line length. If the second item were defined as a table, this field would contain the length of each element within the table. Must have a length <= error message length. 

The format for calling DSNTIAC is:

CALL 'DSNTIAC' USING sql-comm-area,error-message,
error-rec-length

The parameters are same as with DSNTIAR.

19.2.1 Example

The following is an example of how to code a call to DSNTIAR:

01 ERR-MSG.
 05 ERR-MSG-LTH  PIC S9(04) COMP VALUE +280.
 05 ERR-MSG-TBL  PIC X(70) OCCURS 4 TIMES.
01 ERR-LINE-LTH  PIC S9(09) COMP VALUE +70.

CALL 'DSNTIAR' USING SQLCA, ERR-MSG, ERR-LINE-LTH

19.2.2 Return Codes

The following is a list of codes returned after calling DSNTIAR or DSNTIAC.
 

Code
Description
0  No error 
8  Logical error line length > error message length 
12  Error message length > 1,000 
16  Critical error - invalid parameter passed to routine or missing parameter 
-1  There is inadequate memory in the system for message formatting services to function. Requested message is not returned. 
-2  The SQLCA does not contain a non-zero SQLCODE 
-3  The SQLCA does not refer to a valid message 
-4  The logical error line length is less than zero 

19.3 MFHCOEBC

This routine converts each character column accessed by your program from ANSI to EBCDIC.

Host Compatibility Option automatically detects whether your environment supports DBCS data. If so, it examines all character strings for SISO characters.


Copyright © 2001 Micro Focus International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.