Event Store

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

General Information on Event Store
Event Store Milestones
Event Store File
Event Store Administration

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:

Deleting Old Events - SAECLE-P
Sending Commands to the Event Store Monitor - SAECMD-P
Starting the Event Store Monitor - SAEM--0P
Checking the Status of the Event Store - SAEYPI0N

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:

SAECLE-P P-RETENTION-DAYS P-UNPUBLISHED-ALSO

Example:

SAECLE-P 20 A

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).

Note:
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 P-NAME-UM-SUBP P-SEL-CORRELATION-SUBSYS P-RETURN-EVENTS P-WAIT-SEC P-BROKER-ID P-SERVICE

Example:

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
		DEFINE DATA PARAMETER
		1 ESM-EVENT-STORE-ARR (/V) inout
			2 ES-EVENT-ID (AV) 
			2 ES-SUBSYS (AV) 
			2 ES-CORRELATION-SUBSYS (AV) 
			2 ES-CORRELATION-ID (AV) 
			2 ES-CORRELATION-TYPE (AV) 
			2 ES-ESM-CORRELATION-ID (AV) 
			2 ES-CREATION-TIMESTAMP (AV) 
			2 ES-PUBLISH-TIMESTAMP (AV)    
			2 ES-PUBLISH-STATUS (AV) 
			2 ES-PUBLISH-RCCODE (AV)    
			2 ES-PUBLISH-RCTEXT (AV 
			2 ES-EVENT-TYPE (AV) 
			2 ES-EVENT-VERSION (AV)
			2 ES-EVENT-DATA (AV) 
		1 UM-SERVER-ERR-BLOCK inout
			2 UM-RC (AV) 
			2 UM-RC-TEXT (AV) 
		END-DEFINE

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.
`ES-EVENT-VERSION`	`A5`	input	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-SERVER-ERR-BLOCK`		output
`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

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 `&` for "&", `<` for "<", and `>` for ">".

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 & for "&", < for "<", and > 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:

CALLNAT 'SAEYPI0N'
  P-STATUS P-STARTED
  P-BLOCK-SIZE P-WAIT-INTERVAL P-RETENTION-PERIOD
  P-UM-RC P-UM-RC-TEXT P-UM-RC-LONG

It returns the following information:

Parameter	Format/Length	Input/Output	Information Returned
`P-STATUS`	`A DYNAMIC`	output	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.