CBL_ERROR

Syntax:

call "CBL_ERROR_PROC" using     install-flag
                                install-addrs
                      returning status-code

Parameters:

install-flag: Call prototype (see Key): cblt-x1-compx; Picture: pic x comp-x.
install-addrs: Call prototype (see Key): cblt-ppointer; Picture: usage procedure-pointer.
status-code: See Library Routines - Key

On Entry:

install-flag: The operation to be performed:; 0: Install error procedure; 1: De-install error procedure
install-addrs: Address of error procedure to install or de-install.

On Exit:

None

Comments:

In the .NET environment, error procedures are only executed for an RTS exception that has not been handled by the application.

You can install several error procedures for an application by repeated calls of this routine.

Once an error procedure has been posted, subsequent attempts to install that error procedure are silently ignored until it is removed either implicitly (for example, during error processing) or explicitly (by calling CBL_ERROR_PROC with install-flag set to "1").

An error procedure can be written in any language. If it is in COBOL, 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

An error procedure in COBOL can include any legal COBOL, including CALL statements.

When an error occurs the installed procedures are executed, starting with the most recently installed and ending with the first one installed. When all have been processed, the RTS error handling procedure is then started.

If you don't want any other error procedures, including the run-time system error handling, to be executed after terminating your error procedure, set RETURN-CODE to zero.

If a program containing an error procedure is canceled, the error procedure is removed.

An error procedure installed in one program can be removed by another program.

An error procedure can install an error procedure.

If an error procedure is installed during error processing (either by itself, or by another error procedure) then it is executed when the error procedure that installed it returns, assuming that it doesn't return with a ZERO return code.

If an RTS error occurs in an error procedure, the procedure is terminated. The RTS then processes the new RTS error, starting with the next error procedure, if there is one.

You must ensure that the procedure-pointer you use to install the procedure is valid.

An error procedure belongs to the run-unit from which it was installed. So the error procedure is executed only by the run-unit that installed it.

Pressing interrupt does not cause any error procedures to be called.

If the error procedure is defined as an entry point in a program that itself could give an error, you must ensure that the program has a Local-Storage Section. This ensures that the program is reentrant and the run-time system will not give error 166 ("Recursive COBOL call is illegal") when trying to execute the error procedure.

Parameter Passed to the Error Procedure

When an installed error procedure is called, the characters of the relevant RTS error message are passed as a parameter.

Define this parameter in the Linkage Section, ensuring that it is large enough to hold the entire message, and then include it in the USING phrase of the entry to the error procedure. Some variable-width encodings (such as Japanese UTF-8) require an item as large as PIC x(1285) to accommodate the largest error message; however, PIC x(325) is sufficient for messages displayed in English.

An example of the RTS error message string follows:

Load Error : file 'prog-name'\n
error code: 173, pc=0, call=-1, seg=0\n
173  Called program file not found in drive/directory\n\0

where \n is a new-line character and \0 is a null (x"00") terminator. This format is described in your Error Messages.

Example

The following is an example of installing an error procedure, and the skeleton of the error procedure that is called if an error occurs.

 working-storage section.
 01 install-flag     pic x comp-x value 0.
 01 install-address  usage procedure-pointer.
 01 status-code      pic 9(4) comp value zeros.

 local-storage section.

 linkage section.
 01 err-msg  pic x(325).

 procedure division.
     set install-address to entry "err-proc".
     call "CBL_ERROR_PROC" using  install-flag
                                  install-address
                                  returning status-code.

 ...
 ...

* Error procedure:
 entry "err-proc" using err-msg.

* Process err-msg to find out the error number.
* Act accordingly.
 ...

* Terminate, but allow other error procedures to be executed.
     move 1 to return-code
     exit program
     stop run.