Event Store

This section describes the System Automation Tools event store, and covers the following topics:

General Information on Event Store

The event store of System Automation Tools is available in conjunction with Entire Operations.

The event store can be used to collect events which may occur during a network run. The collected events can then be transferred to an external event management system for further processing and evaluation. This may be useful to identify error situations or monitor the network run.

You define milestones at which event data are written. These event data are stored in a separate database file. From that file, the event data can be transferred - via a Natural RPC server call - to an external RPC server.

The transfer procedure uses a monitor program which ensures that the events are transferred in chronological order. Information about the success/failure of the transfer is returned from the receiving RPC server to the monitor and stored in the event store file. If an event was not transferred successfully, its transfer will be repeated.

If a network has been started using the Entire Operations business API (B-API), correlation information is written. This information can be used by the external event management system to ascertain which event data are related to which network. Moreover, the event data written for milestones set for a network contain a unique network identification.

Event Store Milestones

The milestones at which events are collected can be:

  • jobs defined as milestone jobs,

  • automatic network milestones,

  • milestones for global messages,

  • user-defined milestones.

Jobs Defined as Milestones Jobs

You can define each job in a network as a milestone job. This is done in the Entire Operations job master definition.

A milestone job can be:

  • a network start job (the first relevant job in a network),

  • a network end job (the last relevant job in a network),

  • any other job.

In each network, there should be only one start job and one end job.

The job-end processing of an "other" milestone job generates a corresponding "OK" or "not OK" milestone.

Automatic Network Milestones

For a network, event information for the following events is collected automatically:

  • network activation,

  • network release,

  • network deactivation.

For an activated network, event information for the following activated jobs is also collected automatically: the job that was started first and the job that ran last.

Milestones for Global Messages

If Entire Operations global messages are activated for a network for which events are written, the globals messages will also be treated as an event. This allows you to store additional error situation information.

The events for which global messages are written are defined in Entire Operations on the Global Messages for Events screen (see Entire Operations documentation).

User-Defined Milestones

The Entire Operations application programming interface (API) NOPUMI1N allows you to define your own milestones. It is described in the Entire Operations User's Guide.

Event Store File

The file in which the events collected by the event store are to be stored has to be specified as file 84 with the Natural parameter LFILE=(84,dbid,fnr) has to be specified, dbid and fnr being the database ID and file number of the event store file.

The database ID and file number of the event store file are displayed in the Entire Operations monitor defaults.

Event Store Administration

This section describes the programs used to control the event store:

All these programs are available in the library SYSSAT.

Deleting Old Events - SAECLE-P

To delete events from the event store file, you use the program SAECLE-P, which is invoked with the following parameters:



Parameter Format/Length Input/Output Explanation
P-RETENTION-DAYS N29 input nn = Delete all successfully transferred events which are older than nnn days.
P-UNPUBLISHED-ALSO A1 input A = Also delete events which have not been transferred. (optional).

If you wish events to be deleted automatically at regular intervals, you can create a specific Entire Operations network which performs an appropriate task.

Sending Commands to the Event Store Monitor - SAECMD-P

The event store monitor checks at regular intervals for commands to be processed. To send a command to the monitor, you use the program SAECMD-P, which is invoked as follows:

SAECMD-P command
Parameter Format/Length Input/Output Explanation
command A8 input Possible values:
  • STOP = Stop the event store monitor.

  • FREE = Clear all sent commands. This may be necessary, if the monitor has stopped without a STOP command having been sent.

Starting the Event Store Monitor - SAEM--0P

The event store monitor is a program which checks at regular intervals if new events have been stored in the event store file. It transfers the events from the event store file to a RPC server program which transfers them to the external event management system.

The event store monitor is started with the following command:



SAEM--0P SAEGWS0N * 3 10 integServer:1971 ESMGWSRV
Parameter Format/Length Input/Output Explanation
P-NAME-UM-SUBP A8 input The name of the client stub subprogram generated for the RPC service. The stub subprogram SAEGWS0N provided in the library SYSSAT should be used.
P-SEL-CORRELATION-SUBSYS A32 input Determines whether events are transferred for:
  • ' ' (blank) = all scheduled networks;

  • '*' = all subsystems;

  • 'subsystem-id' = this correlation subsystem.

P-RETURN-EVENTS I4 input The number of events to be transferred with each call.
P-WAIT-SEC I4 input The time interval between two successful transfers (in seconds).
P-BROKER-ID A70 input The name of the broker or integration server, and the port.
P-SERVICE A32 input The name of the service to be called. This must be ESMGWSRV:

The invoked RPC server program has to implement the following interface (IDL):

/* Generated by Software AG, IDL Extractor for IS
/* from IS package COM_ESM
/* Optimized for usage with Natural Wrapper.
Library 'COM_ESM' Is
	Program 'SAEGWSRV' Is	/* com.esm.listenerService:SAEGWSRV
		1 ESM-EVENT-STORE-ARR (/V) inout
			2 ES-EVENT-ID (AV) 
			2 ES-SUBSYS (AV) 
			2 UM-RC (AV) 
			2 UM-RC-TEXT (AV) 

The parameters are explained below.

Parameter Format/Length Input/Output Explanation
ESM-EVENT-STORE-ARR input/output  
ES-EVENT-ID A36 input The unique event identifiier.
ES-SUBSYS A32 input The system for which the event has been generated.

For example: NOP = Entire Operations.

ES-CORRELATION-SUBSYS A32 input The correlation subsystem. This is defined by the external event management system to determine different messaging queues.
ES-CORRELATION-ID A36 input The correlation ID which identifies the run or job network. This unique ID is supplied by the external event management system.
ES-CORRELATION-TYPE A32 input The correlation type. This is defined in the external event management system as an additional identifier.
ES-ESM-CORRELATION-ID A60 input The unique correlation ID defined by the event store.
ES-CREATION-TIMESTAMP A23 input The timestamp when the event ocurred (in the format YYYYMMDDHHIISSTTT).
ES-PUBLISH-TIMESTAMP A23 output The timestamp when the event was transferred (in the format YYYYMMDDHHIISSTTT).
ES-PUBLISH-STATUS A1 input/output The transfer status: ' ' (blank) = transferred; 'N' = not transferred.
ES-PUBLISH-RCCODE I4 input/output The transfer response code: 0 = transferred successfully; any other value = error during transfer.
ES-PUBLISH-RCTEXT A DYNAMIC output Description of transfer error.
ES-EVENT-TYPE A32 input Entire Operations event type and trigger:
ON_APIname User API with a name that begins with ON_API.
ON_ACTIVATE Network activation.
ON_RELEASE Network release.
ON_DEACTIVATE Network deactivation.
ON_1ST_JOB First job.
ON_LAST_JOB Last job.
ON_MILESTONE_START Job with milestone has been started.
ON_MILESTONE_END Job with milestone has ended.
ON_MILESTONE_OK Job with milestone ended with OK.
ON_MILESTONE_NOT_OK Job with milestone ended with NOT OK.
ON_GLOBAL_MESSAGE For activated global messages.

The format and version of the data contained in ES-EVENT-DATA:

PT.01 = plain text, unformatted;
SX.01 = very simple XML.

See Event Data Format below.

ES-EVENT-DATA A DYNAMIC input Additional event data of the above format.
UM-RC I4 output The error code if the transfer failed completely.

0 = transfer successful.

UM-RC-TEXT A DYNAMIC output The error text(s) of the error(s) occurred.

Event Data Format

Format Explanation
Plain text, unformatted

Code translation of the event data is performed by EntireX during the transfer. For the event data, use only structured formats which to not rely on internal encoding information. Do not use structured data based on line feeds or or carriage returns, as these may be converted to blanks by the EntireX default settings.

Very simple XML

To avoid code-page translation problems as outlined for plain text above, you can use a very simple subset of XML:

Do not use XML headers, XML name spaces, XML attributes, or any XML element names which contain lower-case characters.

Use only single-character encoding, based on the current Natural alphanumeric definition.

For special-character encoding, use only &amp; for "&", &lt; for "<", and &gt; for ">".

Templates to Start the Monitor

On mainframes, the JCL templates SESKLBS2, SESKLMVS and SESKLVSE (for BS2000, z/OS and z/VSE respectively) in the library SYSSAT can be adapted and used to start the event store monitor. On UNIX, the template satserv.bsh.tpl is available for the same purpose.

Checking the Status of the Event Store - SAEYPI0N

To check the status of the event store and obtain various items of status information, you use the application programming interface SAEYPI0N, which is invoked as follows:


It returns the following information:

Parameter Format/Length Input/Output Information Returned

Status of the event store monitor:

A = monitor active.
C = monitor cancelled (stopped).
N = event store not found.

P-STARTED A DYNAMIC output Last start time.
P-BLOCK-SIZE I4 output Current block size of transferred events (number of events transferred per call).
P-WAIT-INTERVAL I4 output Current minimum waiting time (in seconds) between two transfer calls.
P-RETENTION-PERIOD I4 output Retention period after which transferred events are removed from the event store file.
P-UM-RC I4 output Error number (corresponds to the Natural error number; for example: 3061: Check LFILE settings).
P-UM-RC-TEXT A DYNAMIC output Error short text.
P-UM-RC-LONG A DYNAMIC output Error long text.