EMS Manual

Distributor Commands and Responses
EMS Manual—426909-005
17-23
CONTROL Command (ZEMS-CMD-CONTROL)
examine event messages as they are logged by specifying a ZEMS-TKN-GMTTIME of
-1F.
Using Separate CONTROL Commands for Unrelated Tasks
HP recommends that you use separate ZEMS-CMD-CONTROL command messages
to perform unrelated tasks. For example, use one command message to reposition the
distributor and another message to replace the filter parameters.
However, you can make several configuration changes in one ZEMS-CMD-CONTROL
command. For instance, you can replace a filter, provide new filter parameters, set the
log position, and add one or more source collectors in the same command message.
If you submit multiple configuration changes in a single ZEMS-CMD-CONTROL
command message, regardless of the order of the tokens in the buffer, the distributor
performs them in this order:
1. Filter operations
2. Connects and disconnects of source collectors; adds and deletes of TEXTOUT
destinations
3. Positioning
You can greatly simplify error recovery by restricting each ZEMS-CMD-CONTROL
command message to the tokens of a single configuration change. For example, use
one CONTROL command message to replace a filter and another to add a source
collector. When you use the distributor’s extended programmatic interface,
configuration changes are restricted to the associated ZCOM- commands.
Error-Handling Notes
You must resubmit some or all of a corrected ZEMS-CMD-CONTROL command
message if the value of ZSPI-TKN-RETCODE is nonzero.
Resubmit the entire (corrected) command message if it involved a single operation. If
you submitted a command message that involved unrelated operations (loading a filter
and adding a new TEXTOUT destination, for example), resubmit only those tokens
associated with failed operations.
In some cases, the distributor can recover from a log-file access error by switching to
another log file and resuming event-message processing. The original error is reported
in an error list, followed by a warning—warnings indicate recovery—in another error
list. ZSPI-TKN-RETCODE will be zero, indicating a successful operation.
Note. If a collector has received messages from a forwarding distributor, generation time and
logging time can grow farther apart. The generation time depends on the system where the
message was created. The logging time depends on the system where the message is logged.