Event Store

#### Search Results

Search

# 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 | 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:

    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.

### On this page

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