Specifies an output destination by associating (or disassociating) an emitter with (or from) a component or the default emitter list.
Restriction: This routine is not currently supported in COBOL for JVM.
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
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
...
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.