TACL Reference Manual

Built-In Functions and Variables
HP NonStop TACL Reference Manual—429513-018
9-378
#SSGETV Built-In Function
Considerations
•
Tokens extracted by #SSGETV are not deleted or removed from the buffer.
•
When the current position is within a particular list, all #SSGETV calls pertain only
to tokens within that list (except that header fields are always accessible). You can
exit from the list by calling #SSGETV 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; count is always
returned as 1.
•
When using #SSGETV 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,
#SSGETV 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,
#SSGETV returns only the requested length.
•
If the data returned by #SSGETV 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.
Consequently, if the token retrieved is of type ZSPI^TYP^INT, for instance, and the
result-var STRUCT consists of a single field of type INT2, the token value
appears 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 #SSGETV, 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.
•
You can pass header tokens and one special operation in token-id to get
corresponding values. They are described under “Header Tokens and Special
Operation for #SSGET and #SSGETV” in the explanation of #SSGET.
Examples
1. This example shows how to declare STRUCTs that allow you to extract individual
fields of the token code or the subsystem ID returned by #SSGETV with the
ZSPI^TKN^NEXTCODE or ZSPI^TKN^NEXTTOKEN option:
?SECTION decompose_ssid STRUCT
BEGIN
SSID ss;
STRUCT z^ssid REDEFINES ss;
BEGIN
CHAR z^owner(0:7);
INT z^number;