Set COBOL Error Handler (QLRSETCE) API

The Set COBOL Error Handler (QLRSETCE) API allows you to specify the identity of a COBOL error-handling program. You can call it from any programming language; however, this API only sets the name of the error handling program that is called when an error occurs in a COBOL/400^® program.

After you call this API, any COBOL/400 program that issues an inquiry message with options C, D, or F will first call the defined error-handling program. This program receives the message identification and substitution text, as well as the name of the program that received it, and a list of valid one-character responses. The defined program is responsible for returning a one-character code (blank, C, D, F, or G) indicating whether the COBOL program should continue or not.

Note: All messages issued by the operating system during the running of a COBOL program are monitored by the COBOL program. Only some of the system messages issued will result in a COBOL inquiry message.

For more information about error handling and the issuing of COBOL inquiry messages, see the chapter on error handling in the WebSphere^® Development Studio: ILE COBOL Programmer's Guide manual.

You can define a different error-handling program for each COBOL run unit, but when a new COBOL run unit starts, it uses the error-handling program from the previous run unit.

Only one error-handling program can be active at a time. If an error occurs in the error-handling program, the COBOL program does not call the error-handling program again. (In other words, recursive calls do not occur.) Instead, the inquiry message would be issued as if no error-handling program were defined.

You cannot change the name of the error-handling program while it is responding to an error in a COBOL program.

If an error occurs during the calling of the error-handling program, an informational message (LBE7430) is issued, and processing continues as if no error-handling program were defined.

The error-handling program is defined by the user. The parameters are described under OPM COBOL Error-Handling Exit Program.

Authorities and Locks

None.

Required Parameter Group

Error-handling exit program name

INPUT; CHAR(20)

The qualified name of the error-handling program.

The 20 characters of this parameter are:

1-10	The name of the program object. Valid values are: *NONE No user-defined COBOL error-handling program exists. program-name The name of the error-handling program. The name can be an extended one.
11-20	The library where the program object exists. Valid values are: *CURLIB The current library is used. *LIBL The API searches the library list to find the object. library-name The name of the library where the program object exists. The name can be an extended one.

Scope of error-handling program

INPUT; CHAR(1)

The program can apply to a current or pending run unit.

Valid values are:

C	Current COBOL run unit
P	Pending COBOL run unit

New error-handling exit program library

OUTPUT; CHAR(10)

The library where the program object exists. If *CURLIB or *LIBL was specified for the error-handling exit program name parameter, the library returned for this parameter shows the library where the program was found. If *CURLIB or *LIBL was not specified, the library returned here should be the same as character 11 through 20 of the error-handling exit program name parameter.

Valid value is:

library-name

The library where the program object exists.

Current or pending error-handling exit program name

OUTPUT; CHAR(20)

The qualified name of the error-handling program that was in place before the current error-handling program was set.

The 20 characters of this parameter are:

1-10	The name of the previous error-handling program object. Valid values are: *NONE No previous current or pending error-handling program existed. program-name The name of the error-handling program.
11-20	The library where the previous error-handling program object existed. Valid value is: library-name The library where the previous error-handling program object existed.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Error Messages

[ Back to top | High-level language APIs | APIs by category ]