Chapter 7: DSNTIAR Facility

The SQL Option DSNTIAR facility, or DSNTIAC for CICS programs, converts an SQL return code into a character string error message (similar to the IBM DSNTIAR and DSNTIAC facility on the mainframe). It takes an SQL return code from the SQLCODE element of comm-area (usually, SQLCA), and converts it to a descriptive character string. The resulting string is placed in the output area error-message, which is an array. The first element of error-message indicates the length of the message to follow. The second element is the actual message, which is usually defined as a string of the logical record length, error-rec-length, occurring n times (see the section Calling DSNTIAR or DSNTIAC).

If at run time, the length of the message to be output is larger than one logical record (error-rec-length), and the message is treated as a set of fixed length records of length error-rec-length. The message is word wrapped and indented based on the logical record length. Every logical record begins with a space for carriage control.

Calling DSNTIAR or DSNTIAC

The format for calling DSNTIAR from a COBOL program is:

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

The format for calling DSNTIAC from a CICS COBOL program is:

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

where:

comm-area

The communications area to be used, generally set to SQLCA. The SQLCODE element of this area should contain the error code for which DSNTIAR will generate a message.

error-message

An array of records of size error-rec-length used to store error message output. The two components of the error-message array are:

error-length	containing an integer indicating the length of the second element, error-text. error-length >= 240.
error-text	which is the actual message. Generally this message is defined as an array of strings, each having a length of error-rec-length, and occurring n times so that error-length is the larger of 240 and error-rec-length * n.

Error-rec-length

A n integer indicating the logical record length of output messages. 72 <= error-rec-length <= 240. If the message is longer than error-rec-length, several logical records will be used to store it.

The following table shows the return codes that result from calling the DSNTIAR or DSNTIAC utility.

Code	Description
0	Successful execution.
4	More data was available than could fit into the provided message area.
8	The error-rec-length was not within acceptable limits. (72 <= error-rec-length <= 240)
12	The message area was not large enough. Message length was >= 240.
16	Error in message routine.

Example

 01 ERROR-MESSAGE. 
     02 ERROR-LENGTH PIC S9(4) COMP VALUE +288. 
     02 ERROR-TEXT PIC X(72) OCCURS 4 TIMES. 
 77 ERROR-REC-LENGTH PIC S9(9) COMP VALUE +72.
    ... 
     CALL 'DSNTIAR' USING SQLCA ERROR-MESSAGE ERROR-REC-LENGTH