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.