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