CBL_EXIT_PROC

Installs or removes a closedown procedure to be invoked automatically when the application terminates.

Syntax:

call "CBL_EXIT_PROC" using     install-flag
                               install-params
                     returning status-code

Parameters

install-flag

Call prototype (see Key): cblt-x1-compx

Picture: pic x comp-x.

install-params

Group predefined as cblt-exit-params containing:

01 cblt-exit-params            typedef.
  03 cblte-ep-install-addr     cblt-ppointer.	*> usage procedure-pointer.
  03 cblte-ep-install-priority cblt-x1-compx.	*> pic x comp-x

status-code

See Library Routines - Key.

On Entry:

install-flag

The operation to be performed:

0	Install closedown procedure with default priority of 64
1	De-install closedown procedure
2	Query priority of installed closedown procedure
3	Install closedown procedure with given priority

cblte-ep-install-addrs

Address of closedown procedure to install, de-install or query.

cblte-ep-install-priority

When install-flag is 3, contains the priority of the closedown procedure being installed, in range 0 to 127. Otherwise, ignored.

On Exit:

cblte-ep-install-priority: When install-flag is set to 2, returns the priority of the selected procedure.

Comments:

The installed closedown procedure is executed whether the application finishes normally (with a STOP RUN) or abnormally (for example, with a keyboard interrupt or RTS error). You can install several closedown procedures for an application by repeated calls of this routine.

A closedown procedure can be written in any language. If it is in COBOL, cblte-ep-install-addrs must be the address of an entry point. You can obtain this address using the statement:

  set install-addrs to entry "entry-name"

A closedown procedure in COBOL can include any legal COBOL, including call statements. The closedown procedure terminates when the main program in the procedure executes an EXIT PROGRAM or GOBACK or when a STOP RUN statement is executed.

A closedown procedure does not have any parameters passed to it when it is called.

Every closedown procedure installed has a priority. This priority determines the order in which the procedures are executed - procedures with the lowest values are processed first. If several procedures have the same priority, they are executed in reverse order of installation - that is the last one installed is executed first.

Procedures installed without a priority (install-flag = 0) are given the default priority of 64. To set your own priority, set install-flag = 3 and set the priority to a value in the range 0 to 127. Priorities 128 to 256 are reserved for use by the COBOL system. You must not set a priority higher than 127 unless your program is a user-written file handler, in which case it must be 200.

If a closedown procedure has already been installed, an attempt to install again fails. However, if the priority used on the second attempt is different to that used when it was installed, its priority is changed. RETURN-CODE is set to zero.

Use install-flag = 2 to find the priority of a previously installed procedure. This returns the priority in cblte-ep-install-priority if it is found The procedure is identified by its cblte-ep-install-addrs. If the procedure cannot be found, RETURN-CODE is set nonzero.