CBL_CREATE_CORE

Restriction:

This routine is supported in native COBOL only.
This routine is not supported when CHARSET"EBCDIC" is in effect.

Enables a COBOL program to invoke a core dump on demand (that is, without encountering a run-time error).

Syntax:

call "CBL_CREATE_CORE" using by value     flags
                             by value     core-param
                             by reference filename
                             returning    status-code

Parameters:

	Using call prototype (see Key)	Picture
`flags`	cblt-x4-comp5.	pic x(4) comp-5.
`core-param`	cblt-x4-comp5.	pic x(4) comp-5.
`filename`		pic x(`n`).
`status-code`	See Library Routines - Key

On Entry:

flags

Must be set to zero, which indicates that a core file will be produced.

core-param

Sets the process ID for which to create a core file. A value of zero creates a core file from the current process. If you specify a value other than zero, that running process must be owned by the same user as owns the calling process.

filename

This is a null-terminated string representing the name of the core file.

You can specify the following strings within the filename, which will be substituted when the core file is created.

%%: Single %
%d: The date when the core dump was produced, in the format yyyymmdd
%f: The basename of the program for which the core dump was produced
%p: The process ID of the program for which the core dump was produced
%t: The time when the core dump was produced, in the format hhmmss

If a filename is not supplied (that is, this parameter is set to a NULL pointer), then the core_filename tunable value is used for the name of the file. If that tunable is not set either, the filename defaults to a platform default of cblcore (Windows), or core or core.<pid> (UNIX).

On Exit:

status-code

status-code	Meaning
0	Success
1	Bad command line
2	Invalid process ID
3	Need to enable full core support
4	Not supported on this platform
5	Cannot execute OS core dump command
6	Cannot create core file
7	Invalid core file produced

Examples:

The following example will create a core file for the current process. The file will be called "myDump":

01 flags pic x(4) comp-5 value 0. 
01 process pic x(4) comp-5 value 0. 
01 filename pic x(7) value "myDump" & x"00". 
call "CBL_CREATE_CORE" using by value flags 
                             by value process    
                             by reference filename.

This example will create a core file for COBOL application running in a separate process, though started by the same user, with process id 18655, called "myDump.18655":

01 flags pic x(4) comp-5 value 0. 
01 process pic x(4) comp-5 value 18655. 
01 filename pic x(100) value "myDump.%p" & x"00".
call "CBL_CREATE_CORE" using by value flags 
                             by value process 
                             by reference filename.