CBL_CTF_TRACER_GET

Note: This routine is supported for native COBOL only.

Syntax:

call "CBL_CTF_TRACER_GET" using by value     flags
                                by reference component-name
                                by reference tracer-handle
                                   returning status-code

Parameters:

  Using call prototype (see Key) Picture
flags cblt-x4-comp5 pic x(4) comp-5
component-name pic x(n) pic x(n)
tracer-handle cblt-x4-comp5 pic x(4) comp-5
status-code See Library Routines - Key  

On Entry:

flags
Control flags:
Bits 0-29
Reserved for future use. Must be 0.
Bit 30
Value Meaning
0 component-name is space-terminated.
1 component-name is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Reserved for future use. Must be 0.
component-name
Space- or null-terminated (depending on the setting of bit 30) case-insensitive component identifier string.

On Exit:

tracer-handle
Tracer handle to be specified to the other tracing routines.
status-code
One of:
  • 78-CTF-RET-INVALID-COMPONENT-NAME
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-SUCCESS

Comments:

Components should call this routine to acquire a tracer handle before performing any tracing operations. The handle acquired by a call to this routine can be used in calls to routines such as CBL_CTF_COMP_PROPERTY_GET, CBL_CTF_COMP_PROPERTY_SET, CBL_CTF_LEVEL, CBL_CTF_DEST, CBL_CTF_TRACER_LEVEL_GET and CBL_CTF_TRACER_NOTIFY.

Note: It is possible to trace events without first acquiring a tracer handle by specifying a component identifier string instead of a tracer handle. However, specifying a component identifier has an impact on performance because the component identifier is validated each time it is used, so we recommend that you use a tracer handle returned from a call to this routine instead.

Example:

To acquire a tracer handle to trace "mycomp" component events:

copy "cbltypes.cpy".
copy "mfctf.cpy".

01 component-name  pic x(7) value “mycomp”.
01 tracer-handle   pic x(4) comp-5.
...
call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-name
                                by reference tracer-handle
...