cobgeterrorinfo

Restrictions: This function has the following restrictions:

It is only available for COBOL and PL/I programs.
It is not supported for COBOL programs built to INT or GNT.

Provides information about the location of the last fault or error.

Syntax:

#include "cobgeterrorinfo.h"
coberrorinfo_t* cobgeterrorinfo(int flags);

Parameters:

flags

Reserved for future use, set to 0.

On Return:

This function returns NULL if no fault or error was active when the routine was called, otherwise it returns a pointer to a struct of the form:

typedef struct
{
	cbl_os_size_t    symbol_offset;
	const cobchar_t* symbol_name;
	cbl_os_size_t    module_offset;
	const cobchar_t* module_name;
	const cobchar_t* file_name;
	cbl_os_size_t    line_number;

} coberrorinfo_t

where each element is:

symbol-name: A null terminated string containing the name of symbol where the last fault or error occurred.
symbol-offset: The symbol offset to the last fault or error.
module-name: A null terminated string containing the name of the module where the last fault or error occurred.
module-offset: The module offset to the last fault or error.
file-name: A null terminated string containing the 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.

Comments:

In the typical scenario, cobgeterrorinfo 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.

cobgeterrorinfo 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 cobgeterrorinfo is subsequently called, it provides, for the location of the error, the symbol name and the offset from the symbol start. Additionally, cobgeterrorinfo 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.

cobgeterrorinfo creates a structure, which should be destroyed once it is no longer needed. This is done by another function, cobfreeerrorinfo.

The syntax of cobgeterrorinfo is:

#include "cobgeterrorinfo.h"
void cobfreeerrorinfo(coberrorinfo_t* error_info);

error_info: Pointer to a coberrorinfo_t structure returned by cobgeterrorinfo, which is to be destroyed.

In PL/I, this routine can be called in an ON-unit. However, it cannot be called after the ON-unit terminates.

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

cobgeterrorinfo cannot be called from an exit proc.

cobgeterrorinfo does not provide information about asynchronous signals.

Some information may not be available in all circumstances.

File name and line number information requires a program to be compiled for debug.
Compile for debug is needed on 32-bit systems.