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 Library Routines - Key)	Picture (32-bit systems)
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:

Bit	Value	Meaning
0-29		Reserved for future use. Must be 0.
30	0	component-name is space-terminated.
	1	component-name is null-terminated. This is ignored if bit 31 is unset.
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
...

Related Topics: