Adabas Extensions for Adabas Analytics

The current version of Adabas includes the following extensions, which enable you to work more easily with Adabas Analytics:

Extention Purpose
ADAELP Event log report. Used to print events from the Adabas Anlytics event log.
EALCONFIG Event Analytics configuration tool. Used to help you set up the Adabas Analytics component.

ADAELP (Event Log Report)

This section describes the utility "ADAELP".

The following topics are covered:

Functional Overview

The ADAELP utility prints events from an event log created by Adabas Analytics.

Note:
Event logging must be enabled and the replication user exit must be loaded in order to write event logs. For further information see the section Concepts.

The ADAELP parameters USER_ID, HOSTNAME and EVENT_TIMESTAMP select a subset of the events in the event log.

In the interactive mode, ADAELP displays the selected events when the keyword LIST is entered. If ADAELP is called with parameters, the selected events are displayed immediately.

Events are displayed as follows: a first line with the event type is followed by lines that contain the field data of the event in question. The display of an event is concluded with the event type being repeated on the last line.

Example output

start read event
  event_timestamp=16-JUL-2015 11:51:01.977020
  dbid=163
  file_number=1
  command_code=L5
  response_code=0
  isn=993
  pid=6772
  hostname=PCST01
  user_id=st
  tsid=68 ba 56 02 fb 1a 05 00
end read event

This utility is a single-function utility.

Procedure Flow

graphics/adaelp.png

Data Set Environment
Variable/
Logical Name
Storage
Medium
Additional Information
Event log ELPELG Disk  
Control statements stdin   see section Control Parameters
ADAELP report stdout    

Checkpoints

The utility writes no checkpoints.

Control Parameters

The following control parameters are available:

D    DBID = number

    EVENT_TIMESTAMP = ([absolute-date][,[absolute-date]])

    HOSTNAME = string

    LIST

    USER_ID = string

DBID

DBID = number

This parameter specifies the database ID of the database for which the event log was written.

EVENT_TIMESTAMP

EVENT_TIMESTAMP = ([absolute-date][,[absolute-date]])

This parameter selects the log records in the range specified by the optional date strings. The date strings must correspond to the following absolute date and time format:

dd-mmm-yyyy[:hh:mm:ss[.mmmmmm]]

Leading zeroes in the date and time specification may be omitted. Any numbers not specified are set to 0, for example 28-jul-2015 is equivalent to 28-jul-2015:00:00:00.000000.

By default, all log records are selected.

Examples:

adaelp: event_timestamp = 8-aug-2015

The event with event_timestamp 8-AUG-2015 00:00:00 is selected.

adaelp: event_timestamp = (8-aug-2015:12,)

All events with time_stamp from 8-AUG-2015 12:00:00 onwards are selected.

adaelp: event_timestamp = (,8-aug-2012:12:34)

All events with time_stamp before 8-AUG-2015 12:34:00 are selected.

adaelp: event_timestamp = (16-JUL-2015 11:51:01.977020, 16-JUL-2015 11:51:02.177000)

All events with event_timestamp from 16-JUL-2015 11:51:01.977020 to 16-JUL-2015 11:51:02.177000 are selected.

HOSTNAME

HOSTNAME = string

This parameter selects all events with the hostname specified by 'string'. The length of the parameter value is limited to 8 characters.

LIST

LIST

This parameter lists the events selected with the parameters DBID, EVENT_TIMESTAMP, HOSTNAME and USER_ID.

USER_ID

USER_ID = string

This parameter selects all events with the user ID specified by 'string'. The length of the parameter value is limited to 8 characters.

Specifying Multiple Selection Criteria

If multiple selection criteria are specified, they are combined by a logical AND, e.g.

event_timestamp=(8-aug-2015:12:34,), user_id = guest, hostname = machine3

This selects all events after 8-aug-2015:12:34 with user_id = guest and hostname = machine3.

EALCONFIG (Event Analytics Configuration Tool)

A simple configuration tool (EALCONFIG) is provided to help you set up the Adabas Analytics component. All configuration parameters are stored in the appropriate DBnnn.INI file in the database directory. The database with a valid DBnnn.INI file must exist.

Using EALCONFIG

The configuration tool will ask you for each parameter one at a time. It does not accept command line parameters.

The following parameters are requested by the configuration tool. The current settings or default values are shown in brackets ([]). Pressing the Enter key without any input will keep the current setting.

Dbid

The database ID of the database to be configured for Adabas Analytics.

Activate

Enable or disable the event logging. Possible values are yes and no, the default is yes.

File name

The fully-qualified path name for the log file. The default is $ADADATADIR/dbnnn/NUCELG or %ADADATADIR%\dbnnn\NUCELG.

Filter for files

A list of file numbers for which the event logging is to be performed. The default is all files. For multiple values, specify the list surrounded by brackets, e.g. '(10,11,12,30-40,100)'; for all files enter an asterisk '*'.

Filter for events

A list of event types which will be logged. The default is all events. For multiple values, specify the list surrounded by brackets, e.g. '(INSERT,UPDATE,COMMIT)', for all events enter an asterisk '*'. For further information about the supported event types, see Adabas Analytics Event Types.

Switch log file after events

The number of events that occur before starting a new log file. The default is never to switch.

Switch log file after time

The number of seconds that elapse before starting a new log file. The default is never to switch.

Example

The following example shows a first run of the configuration tool. The result of this configuration will be: for the files 10,11,12,30 to 40 and 100, the events for insert, update and commit commands are logged in the file /opt/softwareag/Adabas/db199/NUCELG.0001. After 86400 seconds (i. e. 24h) or after 1000000 events (depending on which occurs first), the current NUCELG file will be closed and a new file with an increased suffix will be created (NUCELG.0002, NUCELG.0003, ...).

$> ealconfig

Adabas Analytics Configuration Tool

Current/default values are shown in '[]', press <enter> to keep these values.
Multiple values have to be enclosed in brackets.

Please enter the dbid: 199
Do you want to activate event logging [YES|NO]? [YES] yes

Please enter the file name for the EAL log [/opt/softwareag/Adabas/db199/NUCELG]:

Filter events for files. Only for the specified files the events are logged.
Format: (5,8,10,20-30,40-50), (*) for all files.
Please enter the file list [*]: (10,11,12,30-40,100)

Filter events. Only the specified events are logged.
Available event types: (INSERT, READ, UPDATE, DELETE, COMMIT, ROLLBACK), (*) for all events.
Please enter the event type list [*]: (INSERT,UPDATE,COMMIT)

Log file switching. You can begin a new log file after a number of events occurred and/or after a certain time.
Please enter the number of events ('0' - do not switch) []: 1000000
Please enter the number of seconds ('0' - do not switch) []: 86400

Saving changes to DB199.INI file.

Terminated.

The resulting DB199.INI file then contains the following entry:

[EVENT_ANALYTICS]
  ACTION                   = YES
  SWITCH_AFTER_EVENTS      = 1000000
  SWITCH_AFTER_TIME        = 86400

  [FILTER]
    FILES                  = (10,11,12,30-40,100)
    EVENT_TYPES            = (INSERT,UPDATE,COMMIT)
  [FILTER-END]
[EVENT_ANALYTICS-END]

Parameters of Adabas Analytics in the Configuration File DBnnn.INI

Adabas Analytics uses a new topic ([EVENT_ANALYTICS]) in the configuration file DBnnn.INI. An example of how this topic might look is shown below:

[EVENT_ANALYTICS]
  ACTION                   = YES
  SWITCH_AFTER_EVENTS      = 1000000
  SWITCH_AFTER_TIME        = 86400

  [FILTER]
    FILES                  = (10,11,12,30-40,100)
    EVENT_TYPES            = (INSERT,UPDATE,COMMIT)
  [FILTER-END]
[EVENT_ANALYTICS-END]

This section describes the keywords and subtopics contained in the [EVENT_ANALYTICS] topic.

Note:
All of the keywords and subtopics are optional.

ACTION = YES/NO

This keyword activates/deactivates Adabas Analytics. If this keyword is omitted, Adabas Analytics is switched off. Valid keywords are YES and NO.

SWITCH_AFTER_EVENTS = <count>

This keyword is used to switch to a new NUCELG file after <count> events have been written to the NUCELG file. If this keyword is omitted, all events are logged to a single NUCELG file.

SWITCH_AFTER_TIME = <time in seconds>

This keyword is used to switch to a new NUCELG file after <time in seconds> has passed and a new event is to be generated. If this keyword is omitted, all events are logged to a single NUCELG file.

Subtopic FILTER

The subtopic FILTER has 2 keywords: FILES and EVENT_TYPES. These keywords are used to determine which types of events are generated for which Adabas files.

FILES = (<file1>, <file2>, <file3> - <file4>)

This keyword specifies the Adabas files that are to be active for eventing. You can specify a list of files; the list can contain single files (<file1>, <file2>) or a range of files (<file3> - <file4>). If this keyword is omitted, events are generated for all Adabas files in the database.

EVENT_TYPES = (INSERT,READ,UPDATE,DELETE,COMMIT,ROLLBACK)

This keyword specifies the types of events that are generated. The details of each event type are described in the section Adabas Analytics Event Types. If this keyword is omitted, all event types are generated for the files specified by the FILES keyword.

Adabas Analytics Filter Mechanism

The filter mechanism gives you control over the events that are generated.

You can filter the events by the following criteria:

  • Adabas file number;

  • Event type.

You can filter by Adabas file number only, by event type only or you can combine both filters. For further information about the syntax and semantics of the filters for FILES and EVENT_TYPES, see the section Parameters of Adabas Analytics in the Configuration File DBnnn.INI.

The file DBnnn.INI contains the topic EVENT_ANALYTICS and the subtopic FILTER.

Example entry in DBnnn.INI:

[EVENT_ANALYTICS]
  ACTION                   = YES
  SWITCH_AFTER_EVENTS      = 1000000
  SWITCH_AFTER_TIME        = 86400

  [FILTER]
    FILES                  = (10,11,12,30-40,100)
    EVENT_TYPES            = (INSERT,UPDATE,COMMIT)
  [FILTER-END]
[EVENT_ANALYTICS-END]

This entry results in events being generated for the Adabas files 10,11,12,30-40 and 100. The events are limited to the types insert, update and commit. After 86400 seconds (24 hours) or after 1000000 events (depending on which comes first), the current NUCELG file will be closed, and a new file with an increased suffix will be created (NUCELG.0002, NUCELG.0003 ...).

Adabas Analytics Event Types

Adabas Analytics currently supports 6 types of events related to Adabas calls:

INSERT

A new record has been created, triggered by Adabas commands of the type Nx.

READ

A record has been searched, triggered by Adabas commands of the types Lx and Sx.

In the case of Read commands (Lx) with the multifetch option specified, a read event will be generated for each record that can be read. If a record cannot be read because it is held exclusively by another user, a read event with response code 145 will be triggered for this record, but only if the return option (O) was specified.

UPDATE

A record has been modified, triggered by an Adabas command of the type A1.

DELETE

A record has been removed, triggered by an Adabas command of the type E1.

COMMIT

A transaction has been committed, triggered by Adabas commands of the types ET and CL.

ROLLBACK

A transaction has been backed out, triggered by an Adabas command of the type BT, and also by any other command that results in the nucleus response code 9.

The fields in the event types (which can be displayed using the utility ADAELP) contain the following information:

Field Information Contained
event_timestamp Creation time of this event.
dbid Adabas database ID.
file_number Adabas file number.
command_code Adabas command code.
response_code Adabas response code.
isn Adabas ISN.
pid Process ID of the Adabas client.
hostname Machine name of the Adabas client.
user_id User ID of the Adabas client.
tsid Unique marker of the Adabas client.