CBL_CTF_TRACER_GET

Returns a tracer handle that can be passed to other tracing routines to identify a component.

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
...