SQL DESCRIBE ERROR Statement

< > Status Inquiry Statements Query Statements Example Flow Chart Table of Contents

The SQL DESCRIBE ERROR statement returns a group that describes an error returned by the most recent prior InstantSQL statement.

ErrorDescGroup (output). This argument must refer to a group data item that has the same data description as sql-Error-Description defined in the copy file lisqldef.cpy. The description of the error is stored in this group data item. However, if the configuration option AllowErrorMessageOnly is set to "True" and this argument does not refer to a data item with the same length as the sql-ErrorDescription group, only the text of the error message is returned in the specified data item.

SequenceNo (input). This argument must refer to a numeric integer value. Its value specifies the position in the error array from which to return the error information, with the value 1 meaning the first error that occurred for the prior InstantSQL statement other than the SQL DESCRIBE ERROR statement. This argument is optional; if the argument is omitted, the next error in the error array is returned. (Immediately after an InstantSQL statement, other than the SQL DESCRIBE ERROR statement, the next error is the first error in the error array.)

An InstantSQL statement can return multiple errors. The SQL DESCRIBE ERROR statement should be executed in a loop until sql-EndOfData is set to true. Errors are returned in the order they occurred for the prior other statement. Any errors for the SQL DESCRIBE ERROR statement are added to the error array for the prior other statement and returned after all errors for that other statement have been returned. (This presumes that SQL DESCRIBE ERROR statements are subsequently executed that do not cause an error, since the position within the error array is advanced only for successful SQL DESCRIBE ERROR statements.)

When the configuration option ReturnInfoErrorCode is set to "False", ODBC success with informational messages can be described with this statement even though the InstantSQL statement will complete with no indication that the informational messages are available.

Each InstantSQL statement execution, other than SQL DESCRIBE ERROR, deletes the error list for any prior InstantSQL statement. The error list may contain up to 64 entries. If more than 64 errors occur for a single InstantSQL statement, the 65^th call to SQL DESCRIBE ERROR will return adescription indicating that errors were lost.

The SequenceNo argument is useful in a common error handling routine to reset the error array entry so as to return errors from the first error that occurred. When this is done, specific routines that use InstantSQL statements can use the SQL DESCRIBE ERROR statement to check for specific errors they know are related to their known activity. If while doing so an unexpected error is discovered, the common error handling routine that uses this technique will then be able to present all the errors to the user.

The data description entries for the elementary items of an sql-Error-Description group are provided in the copy file lisqlder.cpy. The meanings of the values returned in an sql-Error-Description group are as follows:

20 sql-ErrType         PIC X(01).
88 sql-IsOdbcError            VALUE "O".
88 sql-IsInternalError        VALUE "I".

The value of sql-ErrType is "O" if the error was detected by ODBC or "I" if the error was detected by InstantSQL.

20 sql-ErrStatement PIC X(30).

The value of sql-ErrStatement is the ODBC function name that returned the error for an ODBC error. The value is all spaces for an InstantSQL detected error.

20 sql-ErrSqlState PIC X(07).

The value of sql-ErrSqlState is the SQLSTATE associated with an ODBC error. The value is all spaces for an InstantSQL detected error.

Note In ODBC 3.x, HYxxx SQLSTATEs are returned instead of S1xxx, and 42Sxx SQLSTATEs are returned instead of S00XX. This was done to align with X/Open and ISO standards. In many cases, the mapping is not one-to-one because the standards have redefined the interpretation of several SQLSTATEs. When an ODBC 2.x application is upgraded to an ODBC 3.x application, the application has to be changed to expect ODBC 3.x SQLSTATEs instead of ODBC 2.x SQLSTATEs. InstantSQL, and thus any COBOL application using it, currently runs as an ODBC 2.x application.

20 sql-ErrNo PIC S9(06) LEADING.

The value of sql-ErrNo is the driver specific error number for an ODBC error. The value is the InstantSQL error number for an InstantSQL detected error.

20 sql-ErrMsgGroup.
24 sql-ErrMsgLength PIC S9(04) LEADING.
24 sql-ErrMsg PIC X(500).

The value of sql-ErrMsgLength is the length of the error message text in the sql-ErrMsg data item, which follows.

The value of sql-ErrMsg is the text of the error message. For an ODBC error, this is the text of the message returned by ODBC. For an InstantSQL detected error, this is the InstantSQL text describing the error.

SQL DESCRIBE ERROR Statement Example:

           PERFORM WITH TEST AFTER UNTIL sql-EndOfData
             SQL DESCRIBE ERROR
                 sql-Error-Description
             IF NOT sql-EndOfData
               PERFORM DISPLAY-ERROR-INFO
             END-IF
           END-PERFORM.