EMS Manual

Reporting Events
EMS Manual—426909-005
8-11
Task 3: Create a Data Definition File

Avoid packing several items as bit fields within a word because such fields can be
difficult for an application to extract.

Follow familiar formats for familiar items. An easy way to ensure compatibility with
NonStop Kernel subsystems and with the expectations of application programmers
retrieving your event messages, is to use the appropriate ZSPIDDL-defined types
for your tokens.

If your subsystem also supports a command-message interface, use the same
tokens in event messages that you have defined for the command interface
wherever the two sets overlap.

To avoid confusion on the part of the application retrieving event information
reported by your subsystem, do not use the same token to represent values whose
interpretations are different even if their formats are the same. A token should have
the same meaning every time it appears in any event message from a given
subsystem. For example, a token defined to contain the name of a source file
should never be used to contain the name of a destination file.

File names should appear in remote form only if the file is on a remote node
relative to the process reporting the event (that is, if the file resides on a system
other than the one designated by the value of ZEMS-TKN-SYSTEM provided by
EMSINIT).

Always try to use names that are independent of the system configuration, if
possible, because the configuration context is not always available to the
application retrieving the event message. For example, do not use logical device
numbers as file names (that is, report $SYSTEM, not $21) because reconfiguring
the system might result in the assignment of different logical device numbers.
Task 3: Create a Data Definition File
Any program can send information to a primary or alternate collector to be written to
the log file associated with that collector. For example, a program can write a simple
text message by doing a WRITE to $0, as described in the Guardian Programmer’s
Guide. However, if you want your program to send SPI-compatible event messages
(event messages containing tokens that aid in filtering and processing the messages
programmatically), your program must use a subsystem ID: a structured value that
uniquely identifies the subsystem.
1. Define the subsystem ID in the Data Definition Language (DDL) source file that
includes all the definitions required for the programmatic interface or interfaces to
your subsystem.
2. Use this file to produce data definition files in the language in which your
subsystem is written and in any languages used to write applications that will
retrieve event messages from your subsystem.