SPI Programming Manual (H06.24+, J06.13+)

SPI Programming in TACL
SPI Programming Manual—427506-007
8-18
#SSPUTV
For more information about nonzero status codes, see Appendix A, Errors.
Considerations

If the token length specified by token-id is zero (for instance, if token-id is
ZSPI^TKN^DATALIST, ZSPI^TKN^ERRLIST, ZSPI^TKN^LIST,
ZSPI^TKN^ENDLIST, or ZEMS^TKN^SUBJECT^MARK), you must still supply a
variable for
source-var, but its contents do not matter.

Specifying a count parameter greater than 1 for #SSPUTV is equivalent to calling
#SSPUTV
count number of times in succession with a count of 1 (but supplying
a new
token-value before each call).

The order in which tokens are added to the buffer is not significant except in the
case of (1) #SSPUTV calls with token codes for tokens that start and end lists
(ZSPI^TKN^DATALIST, ZSPI^TKN^ERRLIST, ZSPI^TKN^LIST, and
ZSPI^TKN^ENDLIST), and (2) a few subsystem-specific exceptions mentioned in
the subsystem management programming manuals (for example, the
ZEMS^TKN^SUBJECT^MARK token in an event message).

If the data in source-var is longer than the data area expected by #SSPUTV, the
excess bytes are ignored without any indication. If the data in
source-var is
shorter than the data area expected by #SSPUTV, the remainder of the token
value is set to unspecified values.

If the COUNT count option is specified, the value of source-var is expected to
be an array of
count values of the type of token-value. Variable-length token
values must be word-aligned. For example, the object-name token for extended
SPI subsystems, ZCOM^TKN^OBJNAME, is a variable-length character string. If a
program needs to call #SSPUTV to place in the buffer two object-name tokens
whose values are “abc” and “defgh”, this #DEF defines the correct STRUCT for
source-var:
[#DEF objnames STRUCT
BEGIN
UINT len1 VALUE 3;
CHAR n1(0:3) VALUE abc;
UINT len2 VALUE 5;
CHAR n2(0:5) VALUE defgh;
END;
]

Adding a token to the buffer with #SSPUTV does not affect the current position for
subsequent calls to #SSGET or #SSGETV.

When #SSPUTV is called with a token map for token-id, it uses the null-value
and version information in the token map, if necessary, to update the header token
ZSPI^TKN^MAX^FIELD^VERSION. The token map is not stored in the buffer;
instead, #SSPUTV creates a token code consisting of token type
ZSPI^TYP^STRUCT and the token number from the map.