About Adabas Review Reports

Online or as a stand-alone batch job, Adabas Review processes Adabas command log records and generates reports according to user-defined reporting criteria. The flexible reporting structure of Adabas Review allows you to view the same data in many different ways.

It retrieves performance information about Adabas by collecting data in the form of reports, which capture command log information and provide information about both online and batch transactions. Reports collect data about multiple teleprocessing environments and batch programs that are all using the same database.

Adabas Review provides commands to:

  • modify report definitions;

  • modify display programs;

  • control report data collection; and

  • direct report output.

This document covers the following topics:


Detailed vs. Summary Reports

Adabas Review can produce detailed and summary reports.

  • For detailed reports, data is collected continuously while the database is active. Such reports contain a complete recording of the commands processed while the database is active. Detailed reports cannot be viewed online, because the data is not stored in memory. It is directly processed and for example written to an output dataset. However, when fields are defined, a display program is generated that may be used to view history data online if the report collects history data. Results of detailed reports are printed at database termination.

  • For summary reports, data in the report is summarized by a particular field (for example, by command, user ID, or program). Results can be viewed online. The report data is stored in memory as long as the report is not stopped. For more information see Starting and Stopping Reports. Depending on the report definition the data of multiple Adabas command log records will be collected and aggregated in one record, such a record is called an account entry.

Components of a Report

An Adabas Review report has two parts: a definition and a display program.

  • A report definition is a set of parameters that specify the data to be captured and a set of processing rules that identify the conditions under which the data is to be captured.

  • A Natural display program is a Natural program that specifies the appearance of the report output, whether viewed online or downloaded to a personal computer (PC). A detailed report with LOG=Y may be defined without fields. Hence, no display program will be generated.

Report Definition

Adabas Review uses a set of instructions called a report definition to specify the types of data to be collected. Prepared report definitions supplied with Adabas Review may be modified and custom reports may be created.

Report definitions can be created or modified using menu-driven Natural programs. Report options and processing rules allow you to specify the conditions under which the data is to be captured. Report definitions are kept in the Adabas Review repository.

The Edit Report (ER) function is used to create Adabas Review report definitions. In addition, Software AG delivers prepared report definitions called supplied reports with Adabas Review. Supplied reports should be modified to meet the requirements of your particular site. Detailed information about supplied reports is provided in Supplied Report Reference.

An Adabas Review report definition comprises database fields to be monitored, processing rules, and option parameters, all either entered on screens or selected from lists:

  • Database fields from which a report extracts data are listed in the order in which they are to be displayed.

  • Report processing rules identify the conditions under which the data is to be captured by describing how field values are to be extracted for the report.

  • Report option parameters specify whether Adabas Review will perform physical command logging, whether a report may be scheduled to start in the future, and whether data accumulated by the report will be written to a history file. History data may be used when analyzing database performance trends.

Database Fields

The selection of database fields defines the subject of the Adabas Review report.

A field identifies a type of information to be collected by the report; for example, information about an Adabas command, the Natural program issuing the command, the Adabas nucleus, the teleprocessing monitor, or the operating system being used. The PF11 (Flds) option is used to display a list of all available Adabas Review report fields.

Up to 20 fields may be used in a particular report. In mode DISPLAY=BASIC, the number of fields that can be displayed is limited to a total line size of 250 bytes. Fields will be left out, which do not fit in 250 bytes. Note that the first field with all functions (Sum, Min, Max, etc.) will be processed first, then the second field, and so on. In mode DISPLAY=EDITOR, the number of fields that can be displayed is limited to a total line size of 4000 bytes.

Fields to be displayed in a report are entered on the Edit Report screen of the Edit Report (ER) function as shown in the following example:

14:20:46                  A D A B A S  -  R E V I E W                2020-02-07
REVIEW-DB (10,252)               Edit Report                  Hub Target: 296  
                                                                               
Detail/Summary: S   Report Name: ________________________________   DBID: _____
                                                                               
+-----------------------------------------------------------------------------+
|  Field     Order   Sum   Min   Max   Avg   Pct   Rate      Cost      Round  |
|-----------------------------------------------------------------------------|
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
| ________    ___     _     _     _     _     _     _     _ _______    ______ |
+-----------------------------------------------------------------------------+
                                                                               
Command: ______________________________________________________________________
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help  Optns Exit  SOnly Save  Start  -     +    Sched Rules Flds  Menu

Detailed information about individual fields is provided in the Adabas Review User's Guide.

Report Processing Rules

Report processing rules are used to set conditions on or limit the data collected by the report.

Processing rules are entered on the Report Processing Rules screen of the Edit Report (ER) function as shown in the following example:

14:25:05                  A D A B A S  -  R E V I E W                2020-02-07
REVIEW-DB (10,252)          Report Processing Rules           Hub Target: 296  
                                                                                
                                   REPORT ONE                                   
 +-----------------------------------------------------------------------------+
 |  Field    Op        Value                                            And/Or |
 |-----------------------------------------------------------------------------|
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 | ________  __  ________________________________________________________  ___ |
 +---------------------------------- Page 1 ----------------------------------- 
                                                                                
                                                                                
                                                                                
 Command: ______________________________________________________________________
 Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
       Help  Optns Exit  SOnly Save  Start  -     +    Sched       Flds  Menu

An Adabas Review report processing rule is specified by a field, a relational operator (equal to, less than, greater than, not equal to), and a specific value or range of values.

If there are multiple processing rules, the appropriate logical operator (AND or OR) must also be specified.

Fields used in processing rules are not displayed in the report results unless they are listed on the Edit Report screen.

Report Option Parameters

Values for report option parameters can be entered on the Report Options screen of the Edit Report (ER) function as shown in the following example.

Note:
One of two different Report Options screens may appear in Adabas Review, depending on whether you have selected a summary report or a detail report. The following sample is for a summary report.

14:26:48                  A D A B A S  -  R E V I E W                2020-02-07
REVIEW-DB (10,252)              COMMANDS BY HOUR              Hub Target: 296  
                                                                              
+-- Summary Rpt Options ------- Summary Logging ------------ History ---------+
|  AutoStart .......... Y    Summary Log ........ N    History ............ N |
|  Break .............. Y    Summary File ... RVSUM    History Int ... _____1 |
|  Wrapping ........... N    Num of Logs ....... _2    History DBID ... 20000 |
|  Print .............. Y    Log Size ....  __99999    History FNR .... __149 |
|  Rstrt/Intrvl Y  _____1    Log Full Exit ________    History SVC ...... 249 |
|  Max Restarts .. 999999                                                     |
|  Max K ......... _____8    -- Raw Data Output ---    --- Summary Exit ----- |
|  ADALimit ...... _____1    Write Raw Data ..... N    Exit Name ... ________ |
|  Display By ..   SORTED    Write Header ....... N    Cmd ............... CL |
|  Entries ....... 999999    Data Dlmitrs ..... N #    Sum ................ Y |
|  Limit ....... 99999999    Raw Data File .. RAWSM                           |
|  Page/Line .. _55 / 133    Num of Files ...... _2                           |
|                            Log Size ..... ___9999                           |
|                            Switch Exit . ________                           |
+-----------------------------------------------------------------------------+
Command: ______________________________________________________________________
                                                                               
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help        Exit              Accpt        +    Dflts             Menu

The second Report Options screen (press PF8) applies to summary and detail reports.

14:27:43                  A D A B A S  -  R E V I E W                2020-02-07
REVIEW-DB (10,252)              COMMANDS BY HOUR              Hub Target: 296  
                                                                              
+-- Scheduling Options ------------------------------------------------------ +
|  Scheduling Active .. y                                                     |
|  Date/Time From ..... 2017-09-28 10:51                                      |
|  Date/Time To ....... 2017-09-29 10:51                                      |
|  Duration ........... 5_____ M (Min/Hour/Day)                               |
|  Interval ........... 1_____ H (Min/Hour/Day)                               |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
+-----------------------------------------------------------------------------+
                                                                             
Command: ______________________________________________________________________
                                                                             
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help        Exit              Accpt  -          Dflts PrSet Clear Menu

Adabas Review is delivered with report options defaults:

  • You can modify these defaults for all subsequent reports.

  • You can modify the default values for a particular report, either new or existing.

Detailed information about using the Report Options screen is provided in the Adabas Review User documentation.

Report User Exits

Adabas Review provides two report user exits: one for detail reports and one for summary reports.

  • A detail report user exit is driven when a command log record is selected for the report. Only records that pass the processing rules are provided to the user exit. This exit may be used to create SMF records, accounting records, or for any other purpose.

  • A summary report user exit is driven when a specified Adabas command is selected for the report; and/or a report is summarized. You may control the conditions that trigger the exit.

When creating a report, the user exit is specified on the Report Options screen or in the batch REPORT statement. The actual report user exit must be provided in an executable library accessible to Adabas Review.

For more information about these exits, read REVUXDET: Report Exit for Detailed Reports and REVUXSUM: Report Exit for Summary Reports.

Natural Display Program

When a report definition is saved, Adabas Review automatically generates a unique Natural display program, called the Adabas Review report display program. This program determines how the report data will be viewed online or downloaded to a PC. It controls the appearance of the report output for an active database or for historical data.

There is a second way of generating a Natural display program: depending on the setting of the DISPLAY parameter in the CONFIGDB file, a traditional display program will be generated (DISPLAY=BASIC) or a new display program will be generated (DISPLAY=EDITOR). The new display program uses the Software AG Editor for browsing data and is generated in structured mode. For new display programs it is also possible to re-format (extend or reduce) the width of output columns. Both display programs may exist in parallel. You can run this display program:

  • to view data currently being collected by the interactive Adabas Review processor.

  • to retrieve and display or download historical data that has been saved and stored in the Adabas Review repository.

Note:
No display program is created for buffer pool reports.

The Natural display program generates normal Natural FIND and READ statements against an Adabas Review DDM to access the data being collected by Adabas Review. By default, the Natural program displays the data at the Adabas Review user's terminal. Options exist, however, to download the data directly to a personal computer (PC).

You may use the Adabas Review-generated display program as it is created, or you may modify it for your individual needs.

The traditional display program is executed when the VIEW command is issued to display the report results online. The new display program using the Software AG Editor is executed when the VIEWX (VX) command is issued.

Note:
The output of reports that print at database termination is not controlled by a display program. At database termination, a SYSOUT from Adabas is written by REVIEWB. The format of this output cannot be modified by the Adabas Review user.

Note:
No display program will be generated when a detailed report with LOG=Y will be defined without fields.

Starting and Stopping or Scheduling Reports

Reports can be run in either interactive or batch mode:

  • In interactive mode, Adabas or the client address space passes information to Adabas Review about resource usage for each command processed.

  • In batch mode, Adabas Review runs as a batch job that processes sequential Adabas or Adabas Review command log data sets.

Once the report definitions are edited and saved, the report definition is written to the Adabas Review repository file and the reports can be started. Starting a report tells the Adabas Review data collection process to start collecting data based on the report definition parameters. When scheduling data is defined and marked as active, a report may be scheduled, too.

In interactive mode, the reports can be started or scheduled with:

  • the START or SCHEDULE command executed in SYSREVDB or

  • via Batch Natural or

  • via Review Online functions from within Natural Programs or

  • automatically at startup of Adabas Review as Autostarted Reports.

In batch mode, reports are started or scheduled via parameter statement submitted in the job stream.

Detailed reports do not accumulate data. The data is directly saved to a file (RVUPRT, Raw or command log files or the history file); therefore, detailed reports cannot be viewed online.

Summary reports do accumulate data. If the report is stopped, the data is processed differently by Adabas Review, depending on what caused the report to be stopped and on the setting of the report options. If the data is kept, it may be stored in RVUPRT, the Raw or summary log file, or the history file.

Once data has been accumulated for a report, the results can be:

  • saved to a file (by stopping the report),

  • viewed online,

  • downloaded to a personal computer (PC) using Entire Connection, or

  • printed when the Adabas nucleus terminates.

Reports can be stopped using the SYSREVDB CL (close), PS (purge), RF (refresh), or SU(spend) report commands. Reports stop automatically if one of the following report option limits is set and exceeded:

Data is accumulated and written when:

  • The report is stopped using the CL command;

  • The report stops automatically because of an interval event (Intrvl report option);

  • The report has the RESTART=Y option specified and stops automatically because the maximum storage limit (MAX K report option) was exceeded; or

  • Adabas Review terminates. Adabas Review terminates in local mode if the nucleus is stopped via the ADAEND or HALT operator commands or the hub is stopped via the ADAEND operator command.

Such a portion of a data collection is one interval for a report.

Scheduled reports are queued in the so called wait queue and become active or waiting according to the scheduling parameter. Once the last defined interval has been executed, a scheduled report remains in the wait queue until it will be deleted using the PS (purge) command.

Note:
In local mode, data is written with the next Adabas command log record collected by the Adabas Review system.

Data is not written when a report is stopped using the PS or RF commands.

When one of the following situations occurs, the data is kept in storage and may or may not be written, depending on the next actions you take:

  • The report is stopped using the SU command;

  • The report stops automatically because the maximum number of entries that the report can maintain or report has been reached (ENTRIES or LIMIT report option); or

  • The report has the RESTART=N option specified and stops automatically because the maximum storage limit (MAX K report option) was exceeded (the report status is set to "I" in this situation).

Autostarted Reports

Adabas Review reports can be set to start automatically whenever Adabas Review initializes.

Then RAOSAUTO, the Adabas Review autostarted report parameter generation routine, generates the report definition control statements and writes them to one of two parameter files, RVUAUT1 or RVUAUT2, alternating between them by writing to the older file.

When Adabas starts, the files are read by Adabas Review using the RVUAUT1 and RVUAUT2 statements in the job stream.

Note:
Under z/OS, the installation procedure defines the statements RVUAUT1 and RVUAUT2 so that they point to members of a PDS. To avoid constant compression of these data sets, the statements may point to sequential data sets.

RAOSAUTO automatically regenerates the control statements for all autostarted reports when you make changes to an autostarted report, delete an autostarted report, or modify the target definition for the database being monitored by the reports.

In exceptional circumstances (e.g., the source library becomes too full and requires compressing), you can force regeneration of the control statements for all autostarted reports by either issuing the GENAUTO command or entering the parameters manually using batch parameter statements.

Additionally, when you issue the GENCARD command, RAOSAUTO generates report parameter cards for user-specified reports and directs them to a user-specified output file.

In z/OS, RAOSAUTO executes as a subtask of Adabas Review and is only active when:

  • an autostarted report definition is saved in the online system;

  • GENAUTO (or GENCARD) is executed in the online system; or

  • a database target definition is saved in the online system.

For more information about running autostarted reports, read Running Autostarted Reports.

List Report Functions

Adabas Review provides three list functions for reports, which are accessible from the Adabas Review (DB system) menu:

Code List . . . This function lists . . .
LR Report existing Adabas Review reports by name. Reports may be edited, started, and purged using the commands in this function.
LH History Reports reports that have accumulated history data in the Adabas Review repository.
LS Started Reports reports that are currently accumulating data.

The lists displayed by the LH and LS functions are subsets of the list displayed by the LR function.

From the resulting lists, certain commands can be issued against a particular report that allow you to maintain report definitions, manage started reports, and manage the output they produce.

The commands are entered on the selection line preceding the name of the report.

Record Filtering

Adabas Review record filtering can decrease the number of command log (CLOG) records passed from the database to Adabas Review. When filtering is active, only those records needed for report processing will be passed to Adabas Review. Record filtering operation is based upon the reports currently active and cannot be directly controlled. However, the Adabas ADARUN parameter REVFILTER may be used to control whether the database allows filtering. See the appropriate installation documentation for a description of the REVFILTER parameter.

Record filtering is limited to and dependent upon select Adabas Review fields (filter fields). Reports with rules based solely on filter fields are eligible to be filtering reports. Any other report is a non-filtering report. Record filtering will be active only when all reports running are filtering reports. That is, record filtering will stop if any non-filter report is started. An example of a filtering report would be the Exceptional Response Code report, which has a single rule for the RSP field. If this is the only report running, only those command logs with exceptional response codes will be sent to Adabas Review.

Note:
Record filtering is intended for those installations that ordinarily run very few reports (e.g., Exceptional Response Codes) at a time. A large number of active filtering reports will negate the performance benefits of record filtering. If your installation runs many rule-based reports, running with the ADARUN REVFILTER=NO setting is recommended. Some analysis of active reports may be necessary to fully realize filtering performance benefits.

Record Filtering Restrictions

The following restrictions apply for Adabas Review record filtering:

  • For filtering to be activated, all currently active reports must have processing rules based solely on filtering fields.

  • Wildcard values are not permitted. Alphanumeric values containing an asterisk (*) will result in filtering being turned off.

  • EXCLUDE statements are not supported. An EXCLUDE statement will result in filtering being turned off.

  • Special Adabas Review reports are non-filtering reports.

  • CLOGLAYOUT=8 is required for record filtering.

  • Filtering will not be active when running with LOGCLEX=YES.

Adabas Review Fields Eligible for Record Filtering

The following Adabas Review fields can be used in rule processing in order to activate Adabas Review Record Filtering: ACBUSER, ADADURA, ASSOIO, CALLPGM, CID, CMD, CMDTYPE, DATAIO, DBID, FILE, ISN, ISNQ, JOBNAME, NATAPPL, NATPROG, NATSTMT, NATUID, NUCID, RSP, STEPNAME, TOTDURA, TPUSERID, TRANSID, and WORKIO.

The use of any other field in rules for active reports will cause filtering to be stopped. For detailed information about particular fields, see the Field Reference, provided with this documentation.