CBL_CTF_DEST

Specifies an output destination by associating (or disassociating) an emitter with (or from) a component or the default emitter list.

Syntax:

call "CBL_CTF_DEST" using by value     flags
                          by reference component-id
                          by reference emitter-name
                             returning status-code

Parameters:

	Using call prototype (see Key)	Picture
`flags`	cblt-x4-comp5	pic x(4) comp-5
`component-id`	pic x(n)	pic x(n)
`emitter-name`	pic x(n)	pic x(n)
`status-code`	See Library Routines - Key

On Entry:

flags

Control flags:

Bit 0

Value	Meaning
0	Associate the `emitter-name` with `component-id`
1	Disassociate the `emitter-name` with `component-id`

Bit 1

Value	Meaning
0	Inherit emitters from parent.
1	Do not inherit emitters from parent. This is ignored if bit 0 is set, or if the default emitter list is specified.

Bits 2-27

Reserved for future use. Must be 0.

Bit 28

Value	Meaning
0	`emitter-name` is space-terminated.
1	`emitter-name` is null-terminated.

Bit 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.

emitter-name

Space- or null-terminated (depending on the setting of bit 28) case-insensitive property whose value is to be returned.

On Exit:

status-code

One of:

78-CTF-RET-EMITTER-NOT-FOUND
78-CTF-RET-INVALID-COMP-NAME
78-CTF-RET-INVALID-EMITTER-NAME
78-CTF-RET-INVALID-TRACE-HANDLE
78-CTF-RET-NOT-ENOUGH-MEMORY
78-CTF-RET-SUCCESS

Comments:

CBL_CTF_DEST provides equivalent functionality to the mftrace.dest and mftrace.dest.component-name configuration file entries.

There is always at least one entry in the default emitter list. When the last entry is removed from the default list, the TextFile emitter is implicitly added to it. If a component's emitter list becomes empty, it implicitly inherits its parent's emitters even if bit 1 of flags is set indicating that it does not inherit.

Example:

 copy "cbltypes.cpy".
 copy "mfctf.cpy".
 
 01 component-name  pic x(4).
 01 emitter-name    pic x(10).
 01 flags           pic x(4) comp-5.

*> 1) Add TextFile to the default trace emitter list.

 ...
 move "TextFile" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-ADD
 
 call "CBL_CTF_DEST" using by value flags
                          by value 0
                          by reference emitter-name
 ...

*> 2) Remove TextFile from the default trace emitter list.

 ...
 move "TextFile" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-REMOVE
 
 call "CBL_CTF_DEST" using by value flags
                           by value 0
                           by reference emitter-name
 ...

*> 3) Associate the BinFile trace emitter with the RTS component. 
*>    The RTS component will inherit the default trace emitters.

 ...
 move "RTS" to component-name
 move "ES" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-ADD b-or
                 78-CTF-FLAG-COMPID-STRING
 
 call "CBL_CTF_DEST" using by value flags
                           by reference component-name
                           by reference emitter-name
 ...

*> 4) Make the BinFile trace emitter the only emitter the 
*>    RTS component will use; that is, the RTS component will 
*>    not inherit the default trace emitters.

 ...
 move "RTS" to component-name
 move "BinFile" to emitter-name
 compute flags = 78-CTF-FLAG-DEST-ADD b-or
                 78-CTF-FLAG-DEST-NOINHERIT
                 78-CTF-FLAG-COMPID-STRING

 call "CBL_CTF_DEST" using by value flags
                           by reference component-name
                           by reference emitter-name
 ...