TACL Reference Manual

Built-In Functions and Variables
HP NonStop TACL Reference Manual—429513-018
9-148
#EMSGETV Built-In Function
If no error occurred, and get-op is token-id, the status code is followed by a space
and the number of token values returned.
Considerations
•
Tokens extracted by #EMSGETV are not deleted or removed from the buffer.
•
When the current position is within a list, all #EMSGETV calls pertain only to
tokens within that list (except that header fields are always accessible). You can
exit from the list by calling #EMSGETV to get the ZSPI^TKN^ENDLIST token.
•
When token-id is ZSPI^TKN^ENDLIST, the index and count parameters have
no effect; however, if you supply them, index must be 0 or 1.
•
When using #EMSGETV with a token map for the token-id parameter, the map
can specify a structure version that is longer or shorter than the structure contained
in the buffer. If the requested version is longer than the version in the buffer,
#EMSGETV calls SSNULL to set to null values the new fields that are not obtained
from the buffer. If the requested version is shorter than the one in the buffer,
#EMSGETV returns only the requested length.
•
If the data returned by #EMSGETV is longer than the data area of the STRUCT
identified by result-var, TACL discards the excess bytes without notification. If
the data is shorter than the data area of result-var, TACL sets the entire
STRUCT to its default values, then overwrites the beginning of the data bytes of
the STRUCT with the returned data. No type conversions of any kind are done.
This means that, for instance, if the token retrieved is of type ZSPI^TYP^INT and
the result-var STRUCT consists of a single field of type INT2, the token value
would be in the high-order 16 bits of the INT2 field, not the low-order 16 bits.
•
If you specified the COUNT option, TACL puts all occurrences of the token value
into the STRUCT exactly as returned by #EMSGETV, subject to the size
constraints mentioned in the previous consideration. If the tokens are variable-
length tokens, each token value consists of a length word followed by the actual
value, and the actual value is word-aligned.
•
To retrieve tokens and convert them to external representation as the result of the
function call, use the #SSGET built-in function.
•
Header tokens, and one special operation, can be passed in token-id to get
corresponding values. They are described under “Header Tokens and Special
Operation for #SSGET and #SSGETV” in the explanation of the #SSGET built-in
function.
Example
To extract a subject token, follow two steps: