CBL_CTF_COMP_PROPERTY_GET

Returns a named property value for a component.

Syntax:

call "CBL_CTF_COMP_PROPERTY_GET" using by value     flags
                                       by reference component-id
                                       by reference property-name
                                       by reference property-vallen
                                       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-vallen`	cblt-x4-comp5	pic x(4) comp-5
`property-value`	pic x(n)	pic x(n)
`status-code`	See Library Routines - Key

On Entry:

flags

Control flags:

Bit 0

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

Bit 1

Value	Meaning
0	Return the value as a space-terminated string.
1	Return the value as a null-terminated string.

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.
1	`component-id` is a pic x(`n`) text string. The termination character for the string is defined by bit 30.

component-id

Component whose property value is to be returned. 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-vallen

Length of the property-value buffer in which the property's value is to be returned. The routine will fail if the buffer is too small for the value to be returned. property-vallen is ignored if the value is being returned as an integer.

property-value

If set to null, specifies that the routine is to return (in property-vallen) the length of the buffer required in to hold the property specified by property-name.

On Exit:

property-vallen

Length of returned string value in the property-value buffer, not including the termination character. If property-value is null, or if the specified buffer length is too small for the value to be returned, property-vallen is set to the required buffer length. property-vallen is not set if the value is being returned as an integer.

property-value

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

status-code

One of:

78-CTF-RET-BUFFER-TOO-SMALL
78-CTF-RET-INVALID-COMP-NAME
78-CTF-RET-INVALID-PROP-NAME
78-CTF-RET-INVALID-TRACE-HANDLE
78-CTF-RET-NOT-ENOUGH-MEMORY
78-CTF-RET-PROPERTY-NOT-FOUND
78-CTF-RET-SUCCESS
78-CTF-RET-VALUE-NOT-INTEGER

Example:

Acquire a tracer handle to trace "mycomp" component events, and get two "mycomp" property values; one a null-terminated string value, one 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-len        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 length of prop-string to prop-len

call "CBL_CTF_COMP_PROPERTY_GET" using by value flags
                                       by reference tracer-handle
                                       by reference "prop1 "
                                       by reference prop-len
                                       by reference prop-string
...
compute flags = 78-CTF-FLAG-PROP-INT-VALUE

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