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 Library Routines - Key) Picture (32-bit systems)
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 Value Meaning
0 0 Associate the emitter-name with component-id.
1 Disassociate emitter-name from component-id
1 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.
2-27 Reserved for future use. Must be 0.
28 0 emitter-name is space-terminated.
1 emitter-name is null-terminated.
29 Reserved for future use. Must be 0.
30 0 component-id is space-terminated.
1 component-id is null-terminated. This is ignored if bit 31 is unset.
31 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. If component-id is NULL or an empty string is specified, emitter-name is added to (or removed from) the default emitter list.
emitter-name Space- or null-terminated (depending on the setting of bit 28) case-insensitive emitter name.
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
 ...

Related Topics: