Outputs an event to one or more output destinations.
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
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
...
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.