Problem:
Is it possible to change the CTF (Consolidated Tracing Facility) level from within a COBOL program, rather than at the start of the run?
Resolution:
Two API routines, CBL_CTF_LEVEL() and CBL_TRACER_LEVEL_GET(), can be used to interrogate and to change the trace level. These are unsupported at present, and the API interfaces may change in future releases of the product. This information is therefore made available on the grounds that it may be found of interest and/or use.
CBL_CTF_LEVEL() - Specify a Trace Level
call "CBL_CTF_LEVEL" using by value flags
by value trace-level
by reference component-id
returning status-code
Parameters:
Typedef Picture
flags cblt-x4-comp5 pic x(4) comp-5
trace-level cblt-x4-comp5 pic x(4) comp-5
component-id pic x(n) pic x(n)
On Entry:
flags Control flags
Bit Value Meaning
0-29 Reserved for future use (must be 0)
30 0 component-id is space-terminated
1 component-id is null-terminated
(ignored if bit 31 unset)
31 0 component-id is a tracer handle created
by CBL_CTF_TRACER_GET() (pic x(4) comp-5).
1 component-id is a text string (pic x(n)).
The termination character for the string
is defined by bit 30.
component-id Component identifier. This will either be a pic x(4)
comp-5 tracer handle if bit 31 of flags is not set,
or a pic x(n) text identifier if bit 31 of flags is
set.
If a NULL or an empty string is specified, the default
trace level is set.
On Exit:
<nothing>
Function returns:
78-CTF-RET-SUCCESS
78-CTF-RET-INVALID-TRACE-LEVEL
78-CTF-RET-NOT-ENOUGH-MEMORY
78-CTF-RET-INVALID-TRACE-HANDLE
78-CTF-RET-INVALID-COMPONENT-NAME
Remarks:
CBL_CTF_LEVEL() is used to specify the trace level to be used for a specific
component, or the default trace level if a component name is not specified.
This API provides equivalent functionality to the mftrace.level and
mftrace.level.<component-name> configuration file entries.
CBL_CTF_TRACER_LEVEL_GET() - Get Tracer's Threshold Trace Level
call "CBL_CTF_TRACER_LEVEL_GET" using by value flags
by reference component-id
by reference trace-level
returning status-code
Parameters:
Typedef Picture
flags cblt-x4-comp5 pic x(4) comp-5
component-id pic x(n) pic x(n)
trace-level cblt-x4-comp5 pic x(4) comp-5
On Entry:
flags Control flags
Bit Value Meaning
0-29 Reserved for future use (must be 0)
30 0 component-id is space-terminated
1 component-id is null-terminated
(ignored if bit 31 unset)
31 0 component-id is a tracer handle created
by CBL_CTF_TRACER_GET() (pic x(4) comp-5).
1 component-id is a text string (pic x(n)).
The termination character for the string
is defined by bit 30.
component-id Component identifier. This will either be a pic x(4)
comp-5 tracer handle if bit 31 of flags is not set,
or a pic x(n) text identifier if bit 31 of flags is
set.
The default trace level will be returned if a NULL
or empty string is specified
On Exit:
trace-level Value indicating the tracer's threshold trace level
0 Debug
1 Info
2 Warn
3 Error
4 Fatal
0xFFFFFFFF Not enabled for tracing
Function returns:
78-CTF-RET-SUCCESS
78-CTF-RET-INVALID-TRACE-HANDLE
78-CTF-RET-NOT-ENOUGH-MEMORY
78-CTF-RET-INVALID-COMPONENT-NAME
Remarks:
CBL_CTF_TRACER_LEVEL_GET() is used to retrieve the given tracer's current
threshold trace level.
N.B.: There still remains the problem of how to communicate to the program that the CTF trace level needs to be looked at, or altered. One way to do this may be, say, periodically to check for the existence of a file (CBL_CHECK_FILE_EXIST) and to act upon its presence or absence.
