OSI/MHS Management Programming Manual

SPI Programming Considerations for OSI/MHS
OSI/MHS Management Programming Manual—424824-001
3-9
Retrieving and Decoding Event Messages
commands to be issued only by members of the super group or of the user group that
owns the MHS manager. Section 5, Commands and Responses, identifies each
OSI/MHS command as sensitive or nonsensitive.
Retrieving and Decoding Event Messages
The following is a summary of the steps your application must take to retrieve and act
upon event messages:
1. Declare a buffer of appropriate size for the Event Management Service (EMS)
GETEVENT command and its response. (For recommended sizes, see Event-
Management Considerations for OSI/MHS on page 3-10.)
2. Start an EMS consumer distributor and open it with the #ZSPI qualifier.
3. Format an EMS distributor CONTROL programmatic command to load a filter you
have written, and to specify the source and destination of event messages, if desired.
Send the CONTROL command to the consumer distributor using the mechanism
appropriate to your programming language (for example, a WRITEREAD call in
TAL).
4. Read the response from the distributor using the mechanism appropriate to your
programming language (for example, a WRITEREAD call in TAL).
5. Repeat the following steps in a loop:
a. Format and send a GETEVENT command to the consumer distributor to get the
next event message, using the mechanism appropriate to your programming
language (for example, a WRITEREAD call in TAL).
b. Read the response from the distributor using the mechanism appropriate to your
programming language (for example, a WRITEREAD call in TAL).
c. Call SSMOVE or SSMOVETKN to move the context token from the response
buffer into the GETEVENT command buffer. The context token will be needed
when your application resends the command to get the next event.
d. Call SSGET or SSGETTKN to retrieve the token containing the event message
(ZEMS-TKN-EVENT) from the response buffer.
e. Call EMSGET or EMSGETTKN to retrieve the subsystem ID (ZSPI-TKN-
SSID) and the event number (ZEMS-TKN-EVENTNUMBER) from the event
message. Together, these two tokens identify the event message and determine
what information tokens it will contain.
f. Call EMSGET or EMSGETTKN twice to retrieve the subject of the event
message. In the first call, retrieve the subject-mark token (ZEMS-TKN-
SUBJECT-MARK) to get the token code and index of the token identifying the
subject. Then make another call to retrieve the subject token itself.
g. Call EMSGET or EMSGETTKN to retrieve the values of other tokens from the
event message.