CBL_ERROR_PROC

CBL_ERROR_PROC installs or removes error procedures to be called automatically if and when the current run unit generates any of certain runtime errors. This implementation calls error procedures only when a run unit generates what is called an intermediate runtime error. The list of intermediate runtime errors includes:

File error #
File error # on #
Illegal MERGE
Illegal RELEASE
Illegal RETURN
Illegal SORT
Index out of bounds
INSPECT REPLACING size mismatch
Invalid or missing parameter
Non-numeric data in numeric field
Passed USING item smaller than corresponding LINKAGE item
Program missing or inaccessible
Reference modifier range error
Transaction error #
Transaction error # on #
Use of a LINKAGE data item not passed by the caller

The "#" signs are replaced at run time by error names, numbers, or other information.

Usage

CALL "CBL_ERROR_PROC" 
    USING INSTALL-FLAG PROGRAM-NAME
    [RETURNING STATUS-CODE]

Parameters

INSTALL-FLAG Numeric data item or literal	Zero if the error procedure is to be installed; nonzero if it is to be removed.
PROGRAM-NAME Alphanumeric data item or literal	Name of the error procedure to be installed or removed.
STATUS-CODE Any numeric data item	Always zero. (It is returned only for Micro Focus compatibility.)

Description

A run unit can dynamically build a single queue of one or more error procedures to be called if and when the run unit generates any of certain runtime errors. Not all runtime errors are treated in this way. Some, such as memory allocation errors, are so severe that the runtime cannot continue and must be aborted. Others, such as size errors, are handled by ordinary COBOL code. Runtime errors which call error procedures are called intermediate errors.

When an error procedure is installed, it is placed at the beginning of the queue (or moved to the beginning if it is already in the queue).

When an intermediate runtime error occurs, and there are error or exit procedures in the queues, the error procedures in the queue are called, one by one, as though by a CALL statement, in sequential order (the opposite of installation order), with a single PIC X(325) argument containing the text of an appropriate error message. This error message may contain newline characters and is null-terminated like a C string. Each procedure is removed from the queue just before it is called.

Note: You can cause the runtime to also include the program name and the address of the program failure in the string passed to the error procedure by setting the INCLUDE_PGM_INFO runtime configuration variable. See the entry for INCLUDE_PGM_INFO in Appendix H.

An error procedure must end with an EXIT PROGRAM RETURNING statement which contains an appropriate return value. If the return value is zero, then subsequent error procedures are removed from the queue and are not called.

After all error procedures are called, the exit procedures, if any, are called. Then the run unit is terminated.

If an error procedure generates an intermediate runtime error, it is terminated and the remaining error procedures, if any, are called. Then the exit procedures, if any, are called, and the run unit is terminated.

If an intermediate runtime error occurs when there are no error or exit procedures in the queues, it is handled in the usual way. In some cases, the error is ignored. In other cases, the runtime issues an error message and terminates the entire application, not just the run unit which generated the error.

Note: An error procedure may install or remove exit procedures and other error procedures. This practice is not generally recommended, however, because it may lead to hard-to-predict behaviors resulting in part from the runtime modifications employed in the handling of error and exit procedures.

Error procedure names are case-insensitive and must not contain spaces.

To prevent the program from entering an infinite loop or non-terminating condition, the total number of error and exit procedures installed or called is limited to the value of the configuration parameter MAX_ERROR_AND_EXIT_PROCS. The default value is 64. Any attempt to exceed this limit aborts the application.