CBL_CTF_COMP_PROPERTY_SET

Specifies a value for a component's property.

Syntax:

call "CBL_CTF_COMP_PROPERTY_SET" using by value     flags
                                       by reference component-id
                                       by reference property-name
                                       by reference property-value
                                          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)
`property-name`	pic x(n)	pic x(n)
`property-value`	pic x(n)	pic x(n)
`status-code`	See Library Routines - Key

On Entry:

flags

Control flags:

Bit 0

Value	Meaning
0	Specify a string value. Use bit 1 to determine the string terminator.
1	Specify an integer value. Ignore bit 1.

Bit 1

Value	Meaning
0	String value is space-terminated.
1	String value is null-terminated.

Bits 2-28

Reserved for future use. Must be 0.

Bit 29

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

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 if bit 31 of `flags` is not set, or a pic x(`n`) text identifier if bit 31 of `flags` is set.
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.

property-name

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

property-value

Buffer containing the property value to be set. This is either a pic x( n) field for a value being specified as a string, or a pic x(4) comp-5 field for a value being set as an integer.

On Exit:

status-code

One of:

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

Comments:

Use CBL_CTF_COMP_PROPERTY_SET to set a named property value for the component identified by component-id. If a property with the same name already exists for the component, its value is replaced with the new value. This routine provides equivalent functionality to the mftrace.comp.component-name#property configuration file entry.

Example:

To acquire a tracer handle to trace "mycomp" component events, and set two "mycomp" property values; one a null-terminated string value, the other an integer value:

copy "cbltypes.cpy".
copy "mfctf.cpy".

01 component-id    pic x(7) value "mycomp ".
01 flags           pic x(4) comp-5.
01 prop-integer    pic x(4) comp-5.
01 prop-string     pic x(100).
01 tracer-handle   pic x(4) comp-5.
...
call "CBL_CTF_TRACER_GET" using by value 0
                                by reference component-id
                                by reference tracer-handle
...
compute flags = 78-CTF-FLAG-PROP-STRING-VALUE b-or
                78-CTF-FLAG-PROP-NAME-NULL-TERM
move "xxxx" & x"00" to prop-string

call "CBL_CTF_COMP_PROPERTY_SET" using by value flags
                                       by reference tracer-handle
                                       by reference "prop1 "
                                       by reference prop-string
...
compute flags = 78-CTF-FLAG-PROP-INT-VALUE
move 100 to prop-integer

call "CBL_CTF_COMP_PROPERTY_SET" using by value flags
                                       by reference tracer-handle
                                       by reference "prop2 "
                                       by reference prop-integer
...