EMS Manual

Reporting Events
EMS Manual—426909-005
8-10
What You Can Optionally Provide

Its value distinguishes an action-attention message (the value is TRUE) from an
action-completion message (the value is FALSE).
Identify the resource that needs service by making it the subject of the event message.
Both messages of the action-event pair must identify the same subject, using the same
name and token for that resource.
To distinguish multiple outstanding action requests on the same subject from the same
subsystem, use the ZEMS-TKN-ACTION-ID token, which contains an integer chosen
by the subsystem to make this action request unique. If the action event is already
unique within the subsystem by using the subject name, you must (by convention) still
supply ZEMS-TKN-ACTION-ID but assign it the value 0 (zero).
The event numbers for the attention and completion messages need not be the same.
Thus, a given type of action-attention event could be cleared by any one of several
types of action-completion events, depending on the circumstances.
An application matches an action-completion event with its corresponding action-
attention event by comparing the contents of the tokens ZEMS-TKN-SSID, ZEMS-
TKN-SYSTEM, ZEMS-TKN-ACTION-ID, and the subject of the event message. The
application should ignore the version field of the subsystem ID, however.
What You Can Optionally Provide
In addition to the required information, you should often add other potentially valuable
information to an event message to make it as easy as possible for the message
recipient to extract information. When deciding what additional information to include,
consider:

Additional information about the subject of the event message. For example, it
might be useful to include status information about the subject of the event
message.

Information about the subsystem. For example, an internal program location might
help someone using a listing of the subsystem code as an aid in resolving a
problem.

Additional information about a library procedure or another subsystem’s error that
was directly involved in the event. You can add this information as an error list
within your subsystem’s event message. (See the SPI Programming Manual.)

The generation time of the event if it is important that it not be allowed to default to
the time that EMSINIT was called. (The value for ZEMS-TKN-GENTIME is an
optional parameter to the EMSINIT routine.)
Be conservative about the amount of information you add. You can add tokens later, if
the need arises, without affecting applications and filters that use the existing tokens.
You can choose the format of the information you decide to include in event messages,
but consider these guidelines: