CBL_GET_ERROR_INFO

Restrictions: This routine has the following restrictions:
  • It is only available on Linux platforms, for COBOL and PL/I programs.
  • It is not supported when CHARSET"EBCDIC" is in effect.
  • It is not supported in programs built to INT or GNT.
Provides information about the location of the last fault or error.

Syntax:

call "CBL_GET_ERROR_INFO" using by value flags
                            by reference symbol-info 
                            by reference module-info
                            by reference file-info
        returning status-code.

Parameters:

flags
01 flags     cblt-os-flags.
symbol-info
01 symbol-info 
	  03 symbol-offset            cblt-os-size.
	  03 symbol-name-size         cblt-os-size.
	  03 symbol-name              pic x(n).
module-info
01 module-info 
	  03 module-offset            cblt-os-size.
	  03 module-name-size         cblt-os-size.
	  03 module-name              pic x(n).
file-info
01 file-info 
	  03 line-number            cblt-os-size.
	  03 file-name-size         cblt-os-size.
	  03 file-name              pic x(n).

On Entry:

flags
Reserved for future use, set to 0.
symbol-name-size
Size n of the symbol-name pic x(n) provided. If this is too small for the information being returned, the routine fails.
module-name-size
Size n of the module-name pic x(n) provided. If this is too small for the information being returned, the routine fails.
file-name-size

Size n of the file-name pic x(n) provided. If this is too small for the information being returned, the routine fails.

On Exit:

symbol-offset
The symbol offset to the last fault or error.
symbol-name-size
Size of the symbol name returned.

If CBL_GET_ERROR_INFO fails because on entry symbol-name-size specified a buffer that was too small, symbol-name-size will be set to the minimum buffer size that was required.

symbol-name
Name of the symbol where the last fault or error occurred.
module-name-size
Size of the module name returned.

If CBL_GET_ERROR_INFO fails because on entry module-name-size specified a buffer that was too small, module-name-size will be set to the minimum buffer size that was required.

module-name
The filesystem path to the module where the last fault or error occurred.
module-offset
The module offset to the last fault or error.
file-name-size
Size of the file name returned.

If CBL_GET_ERROR_INFO fails because on entry file-name-size specified a buffer that was too small, file-name-size will be set to the minimum buffer size that was required.

file-name
Name of the file where the last fault or error occurred.
line-number
The line in the file where the last fault or error occurred.
status-code
Status of operation:
Value Status
0 Success
1006 Routine unsupported on this platform or environment.
1011 No fault or error was active when the routine was called.
1017 Buffer too small for information to be returned.

Comments:

In the typical scenario, CBL_GET_ERROR_INFO is used in an error proc, a PL/I ON-unit or a synchronous signal handler and provides information about the location of the last fault or error.

CBL_GET_ERROR_INFO offers similar functionality to the CEE3GRN and CEE3GRO routines, and is expected to be used in similar circumstances. Similarly to these two mainframe calls, when an error occurs, and CBL_GET_ERROR_INFO is subsequently called, it provides, for the location of the error, the symbol name and the offset from the symbol start. Additionally, CBL_GET_ERROR_INFO provides the name of the module, the file name and line number. This additional information makes it easier to identify the location of a fault/error.

PL/I programs must be compiled with the -proginfo option in order to use CBL_GET_ERROR_INFO.

Int code and gnt code are not supported in this release.

CBL_GET_ERROR_INFO cannot be called from an exit proc.

CBL_GET_ERROR_INFO does not provide information about asynchronous signals.

Some information may not be available in all circumstances; for example, file name and line number information is only available if a program was compiled for debug.