EMS Manual

Reporting Events
EMS Manual—426909-005
8-8
What You Must Provide
subsystem are aware of which tokens in each of your messages are unconditional and
stable—that is, tokens that are fundamental to the meaning of that message and
unlikely to be changed or deleted in future versions of your software. If you must delete
an unconditional token or change its meaning, indicate this by changing the value of
the event-number token.
For subsystems for NonStop server, the management programming manual for each
subsystem indicates which tokens are unconditional (present in all instances of event
messages with that particular event number) and which tokens are not to be assumed
to be always present, either because they are conditional (present in only certain
instances of that event message) or volatile (subject to change or deletion).
Subject Token
The subject token identifies the entity that is most directly involved in the event. The
subject of the event could be a hardware component, such as a controller or processor,
or a software component, such as a process, a protocol layer, or a file. A subject token
should define both the type and the name of the object. For example, a subsystem
could have a subject token called BANK-TKN-ATMNAME of type ZSPI-TYP-STRING.
The token name indicates that the subject is an automated teller machine (ATM), and
the token value contains the name of that ATM in the form of a string.
Because the subject of an event could be virtually any object in the subsystem, and
because object types and object names vary so much from subsystem to subsystem,
subjects in event messages are identified by a marker token. You provide the
appropriate subject token as a parameter to EMSINIT (and EMSADDSUBJECTS if you
are adding additional subjects), and the EMS routine inserts two tokens into the buffer:
a subject mark (ZEMS-TKN-SUBJECT-MARK) and your subject token. This subject
mark is used by EMSGET when the application programmer or filter programmer
requests the subject token using the special token ZEMS-TKN-SUBJECT.
These guidelines can help you define the subjects of your event messages:

One subject token is required in an event message. However, you can include
additional subject tokens, when appropriate, to report that multiple objects were
involved in the event or that several components might have been the subject of
the event, but the specific one is uncertain. Multiple subject tokens are also
appropriate when the subject is known by more than one name.

For the management application or operations staff to control or inquire about the
event subject, the subject must be uniquely identifiable. That is, include enough
detail about the subject and subsystem that the specific instance of the object can
be identified. For most subsystems, the subject name and the subsystem ID
uniquely identify the object. For some subsystems, names are unique only within
each instance of the subsystem. In this case, include the ZSPI-TKN-MANAGER
token to specify which instance of the subsystem the subject belongs to.

The subject of the event does not need to be an object that can be inquired about
through a command message to your subsystem. Sometimes it is appropriate to
be more specific in an event message (for example, to identify a certain ATM