CBL_EXIT_PROC

CBL_EXIT_PROC installs, removes, and queries exit procedures to be called automatically when the current run unit terminates normally.

In some cases exit procedures can be called when a run unit generates an error. See the CBL_ERROR_PROC. Routine for error-caused terminations of the run unit.

Usage

CALL "CBL_EXIT_PROC" 
    USING PRIORITY-NUMBER PROGRAM-NAME
    [RETURNING STATUS-CODE]

Parameters

PRIORITY-NUMBER Numeric data item or literal Priority number of the queue or the special value "254" or "255".
PROGRAM-NAME Alphanumeric data item or literal    Name of the exit procedure to be installed, removed, or queried.
STATUS-CODE Any numeric data item Queue number when the exit procedure is queried.

Description

A run unit can dynamically build one or more queues of exit procedures to be called if and when the run unit terminates normally or when an error procedure terminates normally.

Exit procedures are kept in queues, one queue for each priority level. Each run unit has its own set of queues, with priorities ranging from 0 to 127, inclusive. The priority queue for an exit procedure is determined when the procedure is installed. Because it is possible for an error or exit procedure to install or remove error or exit procedures, the priorities and queues can change dynamically. The queues and priorities that apply in the end are those in effect at the time when the runtime chooses an error or exit procedure to call.

When the program calls CBL_EXIT_PROC, if the priority-number is in the range from 0 to 127, inclusive, then:

  1. The exit procedure is removed from the current run unit, if present;
  2. The exit procedure is installed at the beginning of the corresponding queue for the current run unit.

If the priority-number is 254, the exit procedure is simply removed from the current run unit.

If the priority-number is 255, the priority number of the queue in the current run unit containing the exit procedure is returned in status-code (or RETURN-CODE, if no RETURNING phrase is present). RETURN-CODE is described in CALL Statement, General Rule 21 in the ACUCOBOL-GT Reference Manual. If it is not in any queue in the current run unit, the value "255" is returned.

The installed exit procedures for the current run unit are called when the current run unit terminates by executing a STOP RUN, CALL PROGRAM or CHAIN statement.

An exit procedure cannot start a new run unit by executing a CALL RUN or CHAIN statement. If it tries to do so, the runtime displays an error message and stops without calling any other procedures.

An exit procedure must not call STOP RUN. Its effects are undefined.

Exit procedures in queues with lower priority numbers are called before those in queues with higher priority numbers. Exit procedures in the same queue are called in sequential order (the opposite of installation order). Each exit procedure is removed from its queue just before it is called.

An exit procedure may install, remove, or query other exit procedures.

An exit procedure is called as though by a CALL statement and must return by an EXIT PROGRAM statement.

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

No arguments are passed to an exit procedure, and an exit procedure may not return a value.

To prevent the program from entering an infinite loop or non-terminating condition, the total number of 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.