CBL_CTF_EMITTER_PROPERTY_GET

Returns a named property value for an emitter.

Syntax:

call "CBL_CTF_EMITTER_PROPERTY_GET" using by value     flags
                                          by reference emitter-name
                                          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
`emitter-name`	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-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

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

Bits 30-31

Reserved for future use. Must be 0.

emitter-name

Space- or null-terminated (depending on the setting of bit 28) case-insensitive emitter name.

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-EMITTER-NOT-FOUND
78-CTF-RET-NOT-ENOUGH-MEMORY
78-CTF-RET-PROPERTY-NOT-FOUND
78-CTF-RET-SUCCESS
78-CTF-RET-VALUE-NOT-INTEGER

Example:

Get two property values associated with the "myemitter" emitter; one a null-terminated string value, one an integer value:

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

01 emitter-name    pic x(10) value "myemitter".
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).
...
compute flags = 78-CTF-FLAG-PROP-STRING-VALUE b-or
                78-CTF-FLAG-PROP-NULL-TERM
move length of prop-string to prop-len

call "CBL_CTF_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "prop1 "
                                    by reference prop-len
                                    by reference prop-string
...
compute flags = 78-CTF-FLAG-PROP-INT-VALUE

call "CBL_CTF_EMITTER_PROPERTY_GET" using
                                    by value flags
                                    by reference emitter-name
                                    by reference "prop2 "
                                    by value 0
                                    by reference prop-integer
...