CBL_CTF_TRACER_NOTIFY
Installs or uninstalls a tracer configuration callback function.
Syntax:
call "CBL_CTF_TRACE_NOTIFY" using by value install-function
by reference notif-install
returning status-code
Parameters:
|
Using call prototype (see Library Routines - Key) |
Picture (32-bit systems) |
install-function |
cblt-x4-comp5 |
pic x(4) comp-5 |
notif-install |
cblt-trc-notif-install |
Group item containing: |
|
cblte-tni-version |
|
cblt-x4-comp5 |
|
pic x(4) comp-5 |
|
cblte-tni-handle |
|
cblt-x4-comp5 |
|
pic x(4) comp-5 |
|
cblte-tni-callback |
|
cblt-ppointer |
|
procedure-pointer |
status-code |
See Library Routines - Key |
On Entry:
install-function |
The operation to be performed:
0 |
Install a callback |
1 |
Uninstall a callback | |
cblte-tni-version |
Parameter block version number. Must be 0. |
cblte-tni-handle |
Handle of component tracer (returned from a call to CBL_CTF_TRACER_GET)
for which a callback is to be installed or uninstalled. |
cblte-tni-callback |
Callback function to install (if install-function is 0) or uninstall (if
install-function is 1). |
On Exit:
status-code |
One of:
- 78-CTF-RET-FAILURE
- 78-CTF-RET-INVALID-TRACE-HANDLE
- 78-CTF-RET-NOT-ENOUGH-MEMORY
- 78-CTF-RET-SUCCESS
|
Comments:
A tracer configuration callback function is installed by a component to
allow it to be notified when any configuration change to the associated tracer
occurs, such as a threshold level change, or property value change.
The interface to the callback function is as follows:
entry "callback-func" using by value tracer-handle
by value notification-type
by reference notification-param
where tracer-handle and notification-type are pic x(4) comp-5 items,
and notification-param is a pic x(n). All parameters are input only. The
callback function should set return-code to 0 on completion.
Notification Type |
Description |
0 |
A property value change has occurred. notification-param is the address
of a cblt-trc-notif-prop-change item with the following structure:
Field |
Picture |
Call Prototype |
cblte-tnpc-version |
pic x(4) comp-5 |
cblt-x4-comp5 |
cblte-tnpc-flags |
pic x(4) comp-5 |
cblt-x4-comp5 |
cblte-tnpc-namelen |
pic x(4) comp-5 |
cblt-x4-comp5 |
cblte-tnpc-vallen |
pic x(4) comp-5 |
cblt-x4-comp5 |
cblte-tnpc-valint |
pic x(4) comp-5 |
cblt-x4-comp5 |
cblte-tnpc-name |
pointer |
cblt-pointer |
cblte-tnpc-value |
pointer |
cblt-pointer |
Version types (cblte-tnpc-version):
Control flags (cblte-tnpc-flags):
Bit |
Value |
Meaning |
0 |
0 |
Value is a character string. |
|
1 |
Value is a pic x(4) comp-5 integer. |
1-31 |
|
Reserved for future use. | |
1 |
A trace level change has occurred. notification-param is the address of
a pic x(4) comp-5 item indicating the new trace level. |
Example:
To acquire a tracer handle to trace "mycomp" component events and install
a callback to handle threshold level and property change notifications:
copy "cbltypes.cpy".
copy "mfctf.cpy".
01 component-id pic x(7) value "mycomp".
01 install-params cblt-trc-notif-install.
linkage section.
01 lk-tracer-handle pic x(4) comp-5.
01 lk-notif-type pic x(4) comp-5.
01 lk-notif-param pic x.
01 lk-notif-param-level redefines lk-notif-param
pic x(4) comp-5.
01 lk-notif-param-property redefines lk-notif-param
cblt-trc-notif-prop-change
....
*>
*> Acquire tracer handle
*>
call "CBL_CTF_TRACER_GET" using by value 0
by reference component-id
by reference tracer-handle
...
*>
*> Install callback function
*>
move low-values to install-params
move tracer-handle to cblte-tni-handle of install-params
set cblte-tni-callback of install-params to entry "my-callback"
call "CBL_CTF_TRACER_NOTIFY" using by value 0
by reference install-params
...
goback.
*>
*> The callback function to handle trace level and property
*> changes
*>
entry "my-callback" using by value lk-tracer-handle
by value lk-notif-type
by value lk-notif-param.
evaluate lk-notif-type
when 78-TRC-NOTIF-TYPE-LEVEL-CHANGE
....
when 78-TRC-NOTIF-TYPE-PROP-CHANGE
....
end-evaluate
move 0 to return-code
goback.
Related Topics: