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.