Specifying Reporting Options

This document describes the Adabas Review reporting options you can specify. Adabas Review reporting options are specified on the Report Options screen. Different options are available, depending on whether the report selected is a detailed or a summary report.

For detailed reports, data is collected continuously while the database is active. Such reports are straight recordings of commands processed. Detailed reports cannot be viewed online. However, 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 detailed reports, the following options are available:

11:06:18                  A D A B A S  -  R E V I E W                2020-02-10
REVIEW-DB (10,252)                                            Hub Target: 296  
                                                                               
+--- Detail Rpt Options ------- Detailed Logging ------------- History -------+
|  AutoStart .......... N    Log ................ N    History ............ N |
|  Print .............. Y    File ........... RVDET    History Int ... ______ |
|  Limit ....... 99999999    Num of Logs ....... _2    History DBID ... __123 |
|  Page/Line .. _55 / 133    Log Size ..... __99999    History FNR .... ___45 |
|  Rstrt/Intrvl Y  ______    User Exit ... ________    History SVC ...... 234 |
|                                                                             |
|  -- Raw Data Output ---   ---- Buffers to Log ---   ----- Detail Exit ----- |
|  Write Raw Data...... N    FB: Y    SB: Y   RB: Y    Exit name.... ________ |
|  Write Header ....... N    VB: Y    IB: Y   IO: Y                           |
|  Data Dlmitrs?... N   #                                                     |
|  Raw Data File... RAWDT                                                     |
|  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

11:07:13                  A D A B A S  -  R E V I E W                2020-02-10
REVIEW-DB (10,252)                                            Hub Target: 296  
                                                                               
+-- Scheduling Options ------------------------------------------------------ +
|  Scheduling Active .. Y                                                     |
|  Date/Time From ..... 2018-04-24 13:07                                      |
|  Date/Time To ....... 2018-04-25 13:07                                      |
|  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

Summary reports present a summary of information for a particular field (e.g., command, user ID, program, etc.). Results may be viewed online or printed at database termination. For summary reports, the following options are available:

11:07:57                  A D A B A S  -  R E V I E W                2020-02-10
REVIEW-DB (10,252)                                            Hub Target: 296  
                                                                               
+-- Summary Rpt Options ------- Summary Logging ------------ History ---------+
|  AutoStart .......... N    Summary Log ........ N    History ............ N |
|  Break .............. Y    Summary File ... RVSUM    History Int ... ______ |
|  Wrapping ........... N    Num of Logs ....... _2    History DBID ... __123 |
|  Print .............. Y    Log Size ....  __99999    History FNR .... ___45 |
|  Rstrt/Intrvl Y  ______    Log Full Exit ________    History SVC ...... 234 |
|  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 Scheduling options for summary reports are the same as for detailed reports.

Several categories of reporting options can be specified, although the options differ for detailed and summary reports. For more information, select the option category below.

General Report Options

The following table describes (in alphabetic order) the general report options that can appear on the Report Options screen. The "Valid for Report Type" column in the table indicates whether the option is valid for detailed reports or summary reports (or both).

Logging Options

Three kinds of logging are available for Adabas Review reports, depending on the kind of report you have selected. Some logging options are shared by both types; other logging options are specific to the report type.

• Command logging: When running detailed reports, you can elect to create a log file of detailed command data and, optionally, buffer data from the detailed report. This data can be processed at some later time in an Adabas Review batch run. The output of the command log file depends on the report processing rules specified for the report and includes only parts of the overall Adabas commands being processed. For complete information about the Adabas Review command log files, read Command Log Files.

• Summary logging: When running summary reports, a summary log file can be created containing summary data, but it cannot be processed later in an Adabas Review batch run because the summary data already has a specific layout. This layout is described in Summary Record Layout. For complete information about the Adabas Review summary log files, read Summary Log Files.

• Raw logging: When running detailed or summary reports, you can elect to create a raw log file of the detailed command data or summary data collected by the report. For complete information about the Adabas Review raw log files, read Raw Log Files.

Each log file type has report options specific to its processing. This section covers the following topics:

• Command Log Options

• Summary Log Options

• Raw Log Options

• Determining the Log Size Option Setting

• Logging Guidelines

Command Log Options

For command logging, the logging options determine whether command logging is performed, what information is logged, and where the command log is written. Command log options are listed under the title" Detailed Logging" on the Report Options screen.

The following table describes (in alphabetic order) the command logging options that can appear on the Report Options screen for detailed reports.

The remainder of this section on command log file options covers the following topics:

• Buffers to Log Options (Detailed Reports Only)
• Required Options for Command Logging
• Recommended Options for Command Logging

Buffers to Log Options (Detailed Reports Only)

The Buffers to Log options specify which command log buffers will be included in command logging. These can only be specified for detailed reports.

The basic command log record, the ACBX, and the CLEX (corresponding to the ADARUN LOGACB, LOGCLEX, and LOGUX parameters) will always be logged in the command log file, regardless of the settings of the Buffer to Log options. These are included in the record internally referred to as LORECR. The Buffer to Log options make it possible to log additional buffers such as the record buffer, the format buffer, and others.

You can determine whether data is logged by your report by setting the Adabas Review logging parameter that corresponds to a particular buffer (or set of buffers). The following table briefly describes the Buffers to Log options. These options are only applicable to detailed reports:

Required Options for Command Logging

The following detailed report option settings are required for detailed reports that will log commands to the command log:

Recommended Options for Command Logging

The following detailed report option settings are suggested for efficient command logging operations:

Summary Log Options

For summary report logging, the logging options determine whether summary logging is performed, what information is logged, and where the summary log is written. Summary log options are listed under the title" Summary Logging" on the Report Options screen.

The following table describes (in alphabetic order) the summary logging options that can appear on the Report Options screen for summary reports.

The remainder of this section on summary log file options covers the following topics:

• Required Options for Summary Logging
• Recommended Options for Logging

Required Options for Summary Logging

The following summary report option settings are required for summary logging:

Recommended Options for Logging

The following summary report option settings are suggested for efficient summary logging operations:

Raw Log Options

For raw data logging, the logging options determine whether raw logging is performed, what information is logged, and where the raw log file is written. Raw log data can be logged for both detailed and summary reports.

The following table describes (in alphabetic order) the raw logging options that can appear on the Report Options screen for detailed and summary reports.

The remainder of this section on raw log file options covers the following topics:

• Required Options for Raw Logging

Required Options for Raw Logging

The following summary report option settings are required for raw logging:

Determining the Log Size Option Setting

Use the Log Size reporting option for the command, summary, and raw log files to specify the number of blocks to be allocated to each command log file (detailed reports), summary log file (summary reports), or the raw log file (detailed or summary reports). If more than one log is specified (Num of Logs option), the log will be switched when the specified log size is reached; otherwise the log file will be reused from the beginning when the specified log size is reached.

Because command log records and summary log records vary in length, the number of stored records in a defined log size varies a lot. To better estimate this, consider the following log file descriptions.

• The command log file is used by detailed reports and contains the basic record with or without any additional buffers, such as the record buffer or format buffer, depending on the report options. If only the basic record is stored, the record sizes are 1,452 bytes per record. If other buffers are logged as well the size dependent on the buffer sizes, but the maximum length of any log record written by Adabas Review is 8K (kilobytes).

• The summary log file is used by summary reports and contains summary data. Its layout is described in Summary Record Layout. The record size of summary log records varies, depending on the fields specified for the report. The number of bytes used for each field can be determined by reviewing the Field Reference tables.

• The raw log files are sequential data sets that contain detail or summary report data. The record size of raw log records varies, depending on the fields specified for the report and whether a header is used or not. The number of bytes used for each field can be determined by reviewing the Field Reference tables.

For Adabas Review log files, the internal blocking factor used for calculations is 10,000 bytes per block. The Log Size value can be determined using the following basic formula:

number-of-tracks * records-per-track

The number-of-tracks value can be determined by multiplying number of cylinders to use by the number of tracks per cylinder (provided by the disk vendor): number-of-tracks= number-of-cylinders * vendor-number-tracks-per-cylinder.

The records-per-track value can be calculated by dividing the number of bytes per track (provided by the disk vendor) by the blocking factor of each record and truncating the result (records-per-track = TRUNC (bytes-per-track/10000)).

Fully expanded, this calculation looks like this:

(number-of-cylinders * vendor-number-tracks-per-cylinder) * (TRUNC (bytes-per-track/10000))

The following are approximate values for tracks per cylinder, bytes per track, and records per track for 3380 and 3390 devices:

• 3380: 15 tracks per cylinder; 47,000 bytes per track. For record block factor of 10,000 bytes, this calculates as 4 records per track (TRUNC (47000/10000)).

• 3390: 15 tracks per cylinder; 57,000 bytes per track. For record block factor of 10,000 bytes, this calculates as 5 records per track (TRUNC (57000/10000)).

Example Using a Standard Blocking Factor

For example, the Log Size setting for 10 cylinders of a 3390 device with record blocking factor of 10,000 bytes is determined as follows:

• The number-of-tracks value is calculated by multiplying 15 tracks per cylinder by 10 cylinders (15 x 10), or 150 tracks.

• For a 3390 device, the records-per-track is calculated by dividing 57,000 bytes per track by the blocking factor (10,000 bytes), with a result of 5 records per track (TRUNC (57000/10000).

• The Log Size value would then be calculated as 150 x 5, or 750 blocks.

Example Using a Larger Blocking Factor

To make optimal use of your disk space, you might choose to use a larger block size. If you do this, you must be sure to base the calculation for the Log Size parameter setting on the larger block size to be sure to use all provided space. Remember that Adabas Review's internal algorithm uses a fixed 10,000-byte blocking factor for log records, so when calculating Log Size for a larger block size, you must calculate the records-per-per track using the larger block size, then calculate the total number of bytes per cylinder, adjust that value for the total number of cylinders you need, and, finally, adjust the total number of bytes per cylinder by Adabas Review's required 10,000-byte blocking factor.

For example, the Log Size setting for 10 cylinders of a 3390 device with a data set block size of 27,998 bytes is determined as follows:

• For this 3390 device, the records-per-track is calculated by dividing 57,000 bytes per track by the larger data set block size (27,998 bytes), with a result of 2 records per track (TRUNC (57000/27998)).

  Important:
  It is best to check your device vendor's documentation to see what they document as the number of records-per-track for a specific blocking factor for the device.

• To determine the number of bytes per cylinder required, you must multiply the number of tracks per cylinder (for 3390 devices, this is 15) by the data set block size (for this 3390 device it is set to 27,998 bytes) and by the number of records per track (as previously calculated for this 3390 device, this is 2). So the total number of bytes per cylinder required can be calculated as 15 * 27998 * 2, or 839,940 bytes per cylinder.

• This example requires 10 cylinders, so the total number of bytes needed is calculated as 10 * 839,940, or 8,399,400 bytes.

• Finally, the Log Size value is determined by adjusting the total number of required bytes by the 10,000-byte blocking factor for Adabas Review log records. The calculation would be TRUNC (8399400/10000), or 839 blocks.

Logging Guidelines

• Using the report option parameter PRINT=N, the printed detailed or summary report may be suppressed for a command log or summary log report.

• Processing rules may be used to restrict the collection of data for detailed reports (command logging) to certain values; e.g., all commands that return a nonzero response code.

• Before starting a report that performs detailed command logging, command log data sets must be allocated and the corresponding job control statements must be added to the Adabas startup JCL. Likewise, before starting a report that performs summary logging, summary log data sets must be allocated and the corresponding job control statements must be added to the Adabas startup JCL.

• If you use a user exit to copy a filled command log or summary log to another device, refer to the sample user exit code in the source library member REVvrs.SRCE(REVUXLOG). The command or summary log copy job is provided in JCL library member REVvrs.JCL(REVCLCOP).

History Options

History data is useful for monitoring database performance for a given period of time and for performing trend analysis. History options specify whether history data is collected, when it is collected, and where (that is, in which Adabas Review repository) it is stored.

Although history data may be written for both detailed and summary reports, the report type plays a key role in determining how Adabas Review processes history data.

• A detailed report maintains a one-to-one correspondence between a command log record read or passed to ADARVU and an output record produced by Adabas Review. When the command processed by Adabas Review satisfies the report processing rules, Adabas Review builds the required format and record buffer using the current report definition and immediately stores a record in the Adabas Review repository.

• A summary report has a many-to-one relationship between processed records and the summarized output record. Multiple records are processed (i.e., summarized) to produce one output record. When the Adabas Review interactive processor is running, information is written out to the Adabas Review repository at Adabas termination, when an interval is reached, or when the report is closed. If the Adabas Review batch processor is being executed, the data is written during end-of-file (EOF) processing.

• For both types of reports, Adabas Review generates a Natural display program so that history data may be viewed online.

The history options that determine whether and how Adabas Review writes history data are set when you create or edit the report definition on the Report Options screen. If history data is to be written by a report running in batch mode, the history parameters are provided on the COPY statement.

The following table describes (in alphabetic order) the history options that can appear on the Report Options screen. The "Valid for Report Type" column in the table indicates whether the option is valid for detailed reports or summary reports (or both) -- although, in the case of history options, all options work for both types.

Report Exit Options

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

• A detailed report user exit is called 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 called 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 name (1-8 characters) 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.

Scheduling Options

If reports shall start and stop in out-off-office hours or regularly during a period of time without running permanent to save resources, the scheduling options will be useful.

To handle scheduled reports, which are waiting to be activated, a new wait queue has been setup. This queue can be displayed using the LC command.

The new command SCHEDULE (SC) will schedule a report, which has scheduling options defined and which has been set to active. The existing START (ST) command starts a report to be active permanent, although scheduling options may be defined.

Scheduled reports remain in the wait queue after the last interval ended. Data can still be viewed. When you purge an active or waiting report, it will disappear.

When you schedule a report, where Date/Time From is in the past, it may not be active immediately. It may be placed in the wait queue and will become active when the next calculated interval starts. Scheduled reports, which are suspended, will nevertheless toggle between active and wait queue.

The following table describes the scheduling options that appear on the second Report Options screen.