EMS Manual

Distributor Commands and Responses
EMS Manual—426909-005
17-26
GETEVENT Command (ZEMS-CMD-GETEVENT)
Tokens in Response Buffer
ZEMS-TKN-EVENT (type bytestring)
is the actual event message.
ZEMS-TKN-PASSVAL (type int)
if present, is the number following PASS in the PASS statement executed by the
current filter. If you omit the number on the PASS statement, the distributor omits
the ZEMS-TKN-PASSVAL token.
ZSPI-TKN-CONTEXT (type
bytestring)
is the new context block for the event message just returned.
ZSPI-TKN-RETCODE, -ERRLIST, and -ENDLIST
are standard SPI return tokens. See the common tokens description in Object
Support Summary on page 17-3.
Operational Notes

The ZEMS-TKN-EOFSTOP token is a no-wait feature available when collector log
files are the source of event messages. A value of ZSPI-VAL-TRUE causes the
distributor to return:

An event message if one is immediately available.

A ZSPI-TKN-RETCODE value of zero and an error list with the warning error
number ZEMS-WRN-EOF—indicating the application should try again later—if
no event message is immediately available.
If ZEMS-TKN-EOFSTOP is missing or has the value ZSPI-VAL-FALSE,
GETEVENT waits for an event message to become available before responding to
your application.

If you want to limit the time your application waits for an event message, you can
use NOWAIT I/O and later cancel the GETEVENT command. That is, use the
CANCEL or CANCELREQ procedure. For more information, see the Guardian
Procedure Calls Reference Manual.

If the distributor has reached the end of one collector log file and cannot find the
next file, it returns a ZSPI-TKN-RETCODE value of ZEMS-ERR-LOG-ACCESS.
The ZEMS-TKN-ERROR token in the accompanying error list contains the ZEMS-
ERR-FILES-LOST error number. The distributor continues to operate if it finds the
next available log file in the series.
If the distributor fails to find any log file in the series, it shuts down the collector and
returns a ZSPI-TKN-RETCODE value of ZEMS-ERR-COLL-DISCONNECT and
the error lists with the ZEMS-ERR-FILES-LOST error numbers.