EMS Manual

EMS Procedures
EMS Manual—426909-005
15-14
EMSGET and EMSGETTKN Procedures
count input, output
INT .EXT:ref:1
is normally used as an input and output count parameter:

On the call, it specifies the maximum number of token values to return. The
token-value parameter is an array of count elements, each of which is
described by the token-id. If not supplied, it defaults to 1. If less than zero, it
causes an error.

On return, it specifies the actual number of token values returned.
If a count greater than 1 is specified, EMSGET or EMSGETTKN continues
searching until it either satisfies the requested count or reaches the end of the
buffer or list.
For certain tokens for special operations, EMSGET and EMSGETTKN use the
count parameter to return attribute information such as length, byte offset, or
number of occurrences.
ssid input, output
INT .EXT:ref:6
is a subsystem ID that qualifies the token code (see Section 4, Retrieving Event
Messages Programmatically). If not supplied or equal to zero ( 6*[0] ), ssid
defaults to one of:

If the current position is in a list, the subsystem ID of the current list

If the current position is not in a list, the subsystem ID in the message header
(ZSPI^TKN^SSID)
The version field of this parameter is not used when searching the buffer.
Considerations

Tokens extracted by EMSGET and EMSGETTKN are not deleted or removed from
the buffer.

For checkpoint purposes, calls to EMSGET and EMSGETTKN can modify the
message header. For instance, the header tokens ZSPI^TKN^LASTERR and
ZSPI^TKN^LASTERRCODE change if an SPI error occurs on the call. Positioning
information in the header also changes frequently, and future versions of SPI might
introduce other kinds of change. Programs should always account for the
possibility that any EMSGET or EMSGETTKN operation can change the buffer.

When the current position is within a list, all EMSGET and EMSGETTKN calls
pertain only to tokens within that list, except that the header tokens are always
accessible. If the tokens are EMS tokens, for more information see Section 14,
EMS Definitions. If the tokens are SPI tokens, see the SPI Programming Manual.