EMS Manual

Retrieving Event Messages Programmatically
EMS Manual—426909-005
4-12
Specifying Multiple Parameters in One Command
Setting the value of GMTTIME or LOGTIME to -1 causes the distributor to use the
default positioning specifications (for collectors, the messages as they are logged; for a
saved log file, the beginning of the file).
Specifying Multiple Parameters in One Command
If you stay within the allowed parameter combinations (for example, if you do not try to
add a log file and a collector at the same time), you can include many environment
parameters in one CONTROL command message. For example, you could load a
filter, specify its parameters, delete three collectors, add a log file, and specify a log file
position, all in one command. However consider this strategy carefully.
The advantage of including several operations in one CONTROL command is fewer
messages. But it has one important disadvantage. If an error occurs—even if you note
the order in which you enter the parameters—it might be hard to determine which
operations completed before the error occurred and which were skipped because of it.
Retrieving Event Information
After you establish the distributor environment, you can begin to retrieve and process
event messages.
Obtaining an Event Message (GETEVENT)
To get an event message from the distributor, issue a GETEVENT command message.
For details on the GETEVENT command, see GETEVENT Command (ZEMS-CMD-
GETEVENT) on page 17-25.
The GETEVENT command has only two parameters, and they have an effect only in
special cases. All other information governing the selection of the event message to be
returned, such as the filter, its parameters, and the log file to access, are already
specified as part of the distributor environment. The two parameters you can specify
with GETEVENT:

ZSPI^TKN^CONTEXT. This token lets the distributor maintain its context in the
sequence of event messages it is returning to your management application. The
context token is returned in every GETEVENT response message, and you need
Note. If a SETTIME command resets the system time to earlier than it was, one or more event
messages will have time stamps out of sequence: earlier than that of the last message before
the reset. This might mean that later the distributor either positions itself in the log file after the
out-of-sequence messages or skips them. To alert the operator to this, the collector compares
the time stamp of each event message to that of the previous message. If the time stamp of
the later message is earlier than that of the earlier message, the collector issues an event
message ZEMS-EVT-LOGTIME-DECREASE. The distributor, in turn, checks each LOGTIME-
DECREASE message, regardless of its time stamp, and (if it is not filtered out) passes it to its
destination. For details, see the description of event message 524: ZEMS-EVT-LOGTIME-
DECREASE on page 20-30.