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

install-function
Call prototype (see Key):cblt-x4-comp5
Picture: pic x(4) comp-5.
notif-install
Group predefined as cblt-trc-notif-install containing:
01 cblt-trc-notif-install    typedef.
  03 cblte-tni-version       cblt-x4-comp5. *> pic x(4) comp-5.
  03 cblte-tni-handle        cblt-x4-comp5. *> pic x(4) comp-5.
  03 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 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): 0 = structure version

Control flags (cblte-tnpc-flags):
Bit 0
Value Meaning
0 Value is a character string.
1 Value is a pic x(4) comp-5 integer.
Bits 1-31
Reserved for future use.
Notification Type 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.