CBL_CTF_TRACE

Restriction: This routine is supported for native COBOL only.

Syntax:

call "CBL_CTF_TRACE" using by value     flags
                           by reference component-id
                           by reference trace-event
                              returning status-code

Parameters

flags
Call prototype:cblt-x4-comp5
Picture: pic x(4) comp-5.
component-id
Call prototype: pic x(n)
Picture: pic x(n).
trace-event
Group predefined as cblt-trc-event containing:
01 cblt-trc-event              typedef.
  03 cblte-trcevt-version      cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-flags        cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-event-id     cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-level        cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-data-count   cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-trcevt-event-len    cblt-pointer.	 *> pointer
  03 cblte-trcevt-event-type   cblt-pointer.  *> pointer
  03 cblte-trcevt-event-data   cblt-pointer.  *> pointer
status-code
See Library Routines - Key.

On Entry:

flags
Control flags:
Bits 0-11
Reserved for future use. Must be 0.
Bit 12
Value Meaning
0 Output event data only if the component is enabled for tracing, and if the event level specified by cblte-trcevt-level is greater or equal to the tracing level configured for the component.
1 Force the output of the event if the component is enabled for tracing. cblte-trcevt-level and the tracing level configured for the component are ignored.
Bit 13
Value Meaning
0 cblte-trcevt-event-data is an array of pointers to trace data of varying size and type. The corresponding elements of the cblte-trcevt-event-len and cblte-trcevt-event-type arrays need to be defined.
1 cblte-trcevt-event-data is an array of pointers to trace data of the same size and type. Only the first element of cblte-trcevt-event-len and cblte-trcevt-event-type need to be defined.
Bits 14-29
Reserved for future use. Must be 0.
Bit 30
Value Meaning
0 component-id is space-terminated.
1 component-id is null-terminated. This is ignored if bit 31 is unset.
Bit 31
Value Meaning
0 component-id is a pic x(4) comp-5 tracer handle returned from a call to CBL_CTF_TRACER_GET.
1 component-id is a pic x(n) text string. The termination character for the string is defined by bit 30.
component-id
Component identifier. This is either a pic x(4) comp-5 tracer handle (from CBL_CTF_TRACER_GET) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.
cblte-trcevt-version
Structure version. Must be 0.
cblte-trcevt-flags
Control flags. Must be 0.
cblte-trcevt-event-id
Component-specific event identifier used to identify the type of event being output.
cblte-trcevt-event-level
Tracing level of the event being output.
cblte-trcevt-data-count
Number of trace data items, indicating the number of elements in the cblte-trcevt-event-len, cblte-trcevt-event-type, and cblte-trcevt-event-data arrays. This can be 0.
cblte-trcevt-event-len
Pointer to an array of 4-byte comp-5 items. Each array element indicates the length of the corresponding trace data item in the cblte-trcevt-event-data array. This can be NULL if cblte-trcevt-data-count is 0.
cblte-trcevt-event-type
Pointer to an array of 4-byte comp-5 items. Each array element indicates the type of the corresponding trace data item in the cblte-trcevt-event-data array. This can be NULL if cblte-trcevt-data-count is 0.
Value Type
0 Binary
1 Text (local encoding)
2 Address
3 COMP-5
4 COMP-X
5 UTF8
6 Signed COMP-5
7 Signed COMP-X
Any value other than the ones specified above is treated as type 0 (binary).
cblte-trcevt-event-data
Pointer to an array of pointer items. Each array element addresses a trace data item of the type and length indicated by the corresponding element in the cblte-trcevt-event-type and cblte-trcevt-event-len arrays respectively. This can be NULL if cblte-trcevt-data-count is 0.
For address type items, the array element is the address value; not a pointer to the address value.

On Exit:

status-code
One of:
  • 78-CTF-RET-INVALID-COMPONENT-NAME
  • 78-CTF-RET-INVALID-TRACE-HANDLE
  • 78-CTF-RET-INVALID-TRACE-LEVEL
  • 78-CTF-RET-NOT-ENOUGH-MEMORY
  • 78-CTF-RET-NOT-TRACE-ENABLED
  • 78-CTF-RET-NOT-TRACING-LEVEL
  • 78-CTF-RET-OUTPUT-ERROR
  • 78-CTF-RET-SUCCESS

Comments:

CBL_CTF_TRACE() outputs the specified event identified by cblte-trcevt-event-id to one or more output destinations provided that the event level specified in level is greater or equal to that configured for the component.

Example:

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

78 78-EVENT-TYPE-A      value 1.
78 78-EVENT-TYPE-B      value 2.

01 component-id         pic x(7) value "mycomp ".
01 flags                pic x(4) comp-5.
01 trace-event          cblt-trc-event.
01 trace-event-lengths  pic x(4) comp-5 occurs 1.
01 trace-event-pointers pointer occurs 1.
01 trace-event-types    pic x(4) comp-5 occurs 1.
01 trace-info           pic x(10).
01 tracer-handle        pic x(4) comp-5.

...
move low-values to trace-event

set cblte-trcevt-event-len of trace-event to
    address of trace-event-lengths(1)
set cblte-trcevt-event-type of trace-event to
    address of trace-event-types(1)
set cblte-trcevt-event-data of trace-event
    to address of trace-event-pointers(1)

*> 1) Acquire a tracer handle to trace "mycomp" component events, 
*>    then output two informational events; one with event data, 
*>    one without.

call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-id
                                by reference tracer-handle
...
move 0 to flags
move 78-CTF-FLAG-LEVEL-INFO to cblte-trcevt-level of trace-event
move 78-EVENT-TYPE-A to cblte-trcevt-event-id of trace-event
move 1 to cblte-trcevt-data-count of trace-event
move length of trace-info to trace-event-lengths(1)
move 78-TRACE-EVENT-TYPE-TEXT to trace-event-types(1)
set trace-event-pointers(1) to address of trace-info

call "CBL_CTF_TRACE" using by value flags 
                           by reference tracer-handle
                           by reference trace-event
... 
move 78-EVENT-TYPE-B to cblte-trcevt-event-id of trace-event
move 0 to cblte-trcevt-data-count of trace-event

call "CBL_CTF_TRACE" using by value flags
                           by reference tracer-handle
                           by reference trace-event
...

*> 2) Output two informational events for the "mycomp" component 
*>    without acquiring a tracer handle

...
move 78-CTF-FLAG-COMPID-STRING to flags
move 78-CTF-FLAG-LEVEL-INFO to cblte-trcevt-level of trace-event
move 78-EVENT-TYPE-A to cblte-trcevt-event-id of trace-event
move 1 to cblte-trcevt-data-count of trace-event
move length of trace-info to trace-event-lengths(1)
move 78-TRACE-EVENT-TYPE-TEXT to trace-event-types(1)
set trace-event-pointers(1) to address of trace-info

call "CBL_CTF_TRACE" using by value flags
                           by reference component-id
                           by reference trace-event
...
move 78-EVENT-TYPE-B to cblte-trcevt-event-id of trace-event
move 0 to cblte-trcevt-data-count of trace-event

call "CBL_CTF_TRACE" using by value flags
                           by reference component-id
                           by reference trace-event
...