Adabas Review Processing and Components

Adabas Review runs in:

  • local mode in the Adabas address space;

  • hub mode as a server in its own address space with a client interface in the Adabas address space;

  • batch mode as a batch job that processes sequential Adabas command log data sets; or

  • client mode as a server in its own address space with a client interface with the TSO/batch, CICS, or IMS TP monitors. Client mode is supported in z/OS environments only.

Read Software AG Product Support and Requirements for a matrix of supported Adabas versions and other requirements.

This document covers the following topics:


Collecting Data in Local Mode

In local mode, the Adabas Review processor is installed as an extension to ADALOG.

The data collection process is partly accomplished by the Adabas Review processor. The data is collected by providing code (RAOSLOCL) that runs as an extension to ADALOG. Adabas calls this module and passes information about resource usage for each command processed by the Adabas nucleus.

This module, in conjunction with the Adabas Review processor and an intermediate Adabas Review buffer, accumulates and tabulates the Adabas information based on various user-defined data requirements.

The Adabas Review data may be:

  • displayed in an online environment from the Adabas Review user interface;

  • saved automatically in the Adabas Review repository;

  • printed automatically when the Adabas nucleus terminates; or

  • downloaded directly to a personal computer (PC) using Entire Connection.

The following graphic shows the Adabas Review data collection process for local mode.

graphics/review_process_local.png

In local mode, Adabas Review job control statements should be added to the Adabas nucleus startup job.

Collecting Data in Hub Mode

In hub mode, Adabas Review uses a client/server approach to collecting data:

  • an interface (the client) resides on each Adabas nucleus; and

  • the hub (the server) resides in its own address space, partition, or region.

The interface uses the existing Adabas interregion communication process: ADALNK, Trans-port, ADASVC (ADARER), and ADAMPM. This process is consistent across the targeted platforms for Adabas Review. If systems are networked correctly, hub mode supports a multiple platform, multiple operating system, Adabas database environment.

In hub mode, Adabas Review job control statements should be added to the Adabas Review hub startup job.

Note:
Trans-port is available only in z/OS environments.

The Server Hub

The Adabas Review hub is a centralized data collector and reporting interface that combines proven components of Adabas and Adabas Review.

It handles the data consolidation and reporting functions for monitoring an Adabas database, including usage information related to applications, commands, command response time, I/O activity, buffer efficiency, and others.

The interactive reporting facility allows you to pinpoint problems quickly, providing detailed and summary data about Adabas activities. Specific information about each database is also available.

The centralized collection server has several advantages:

  • A single hub collects information from multiple Adabas nuclei, Adabas Parallel Services clusters, or Adabas Cluster Services (support for IBM's parallel sysplex environment) clusters.

  • Because a single hub can support multiple Adabas nuclei, the number of Adabas Review nuclei required to support an enterprise-wide distribution of Adabas nuclei is reduced. This minimizes resource requirements and increases performance.

  • Isolating the Adabas Review subtask from the Adabas nucleus enhances the performance of the Adabas main task and minimizes the impact of future Adabas releases on the functioning of Adabas Review.

The hub comprises

  • ADAREV, a logic module that manages and supervises the incoming Adabas Review data calls and requests;

  • REVHUB, a module to establish and maintain the environmental settings for Adabas Review; and

  • the Adabas Review DB nucleus and subsystems including RAOSAUTO, the autostarted report parameter generation routine, and RAOSHIST, the historical data population routine.

The Client Interface

The Adabas Review interface constructs and then transmits the Adabas Review data from the Adabas nucleus to the Adabas Review hub. An Adabas Review interface is integrated with each Adabas nucleus that is monitored.

The interface comprises

  • ADALOG, the Adabas command logging module;

  • ADACLX, the Adabas command log extension module that is responsible for acquiring additional information not present in the Adabas command log record; and

  • ADARVU, which handles the environment conditions for ADACLX and the Adabas API requirements for transmitting the Adabas Review data to the Adabas Review hub.

Interface Calls

To maximize performance, the ADARVU module issues an "optimistic" call from an Adabas nucleus to the Adabas Review hub without waiting for a completion or "post" from the hub; ADARVU assumes that the Adabas Review data was successfully passed to the hub.

However, ADARVU does perform an initialization step to ensure that the hub is active prior to any command processing by the Adabas nucleus. If the hub is not active, ADARVU informs you using WTOs or a user exit. If a user exit is used, you are given the option to wait for the hub to be activated, or continue initialization and call the hub only when it is active.

Command log records are normally buffered to reduce the number of calls from the Adabas nucleus to the Adabas Review hub. In low traffic situations, this might lead to a delay of approximately five seconds.

If the communication to the hub results in a non-zero response code (for example response code 151), ADARVU will call user exit 5 if it is available. If a user exit is used, you are given the option to resend the whole buffer (with or without a wait), although parts of the buffer may already be processed. We recommend that you not resend the buffer, but generate a message indicating an error has occurred correct the problem. For more information about user exit 5 read REVUEX5: Adabas Review Hub Event Handler (Adabas Exit 5).

On the hub side of the call, the elimination of the cross-memory "post" call enhances performance by reducing the overhead of active communication with the Adabas clients. This allows the hub to remain a passive data collector.

Example Client/Server Environment

The following graphic shows the major components of the Adabas Review interface (Adabas nucleus address space) and hub (Adabas Review hub address space) in a client/server architecture .

graphics/review_env_os.png

Command Log Processing

The data collection process is partly accomplished by the hub (server) component REVIEWB, the Adabas Review command log processing routine, which runs as an Adabas Review subtask; that is, a unit of work that the operating system treats as separately detachable.

At initialization, REVIEWB reads any autostarted report definitions the user has defined and collects data according to the reports' criteria. REVIEWB also processes requests to start, view, and purge reports from the Adabas Review online system.

In hub mode, Adabas responds to requests and calls the interface module ADARVU from ADALOG (Adabas's command logging module) if REVIEW=dbid is specified in the Adabas initialization parameters. Adabas passes to ADARVU information about resource usage for each command processed by the Adabas nucleus.

Adabas Review link routine exits are used to pass TP system and Natural information from the user's address space (origin of the Adabas call) to the Adabas address space and, using an extension of the Adabas user buffer, on to ADARVU.

ADARVU queues Adabas command log records received from ADALOG to the Adabas Review hub ( server) through an intermediate REVIEW-BUFFER in the Adabas subtask address space. Note that command log records are examined prior to queuing to determine whether record filtering is active. When filtering is active, only command log records that are filtered are sent to the hub.

See Record Filtering for more information.

REVIEWB processes the records, accumulating and tabulating various data according to the criteria specified in any user-defined reports that are active.

The resulting nucleus statistics may be

  • displayed in an online environment from the Adabas Review user interface;

  • saved automatically in an Adabas file called the Adabas Review repository;

  • printed automatically when the Adabas nucleus terminates; or

  • downloaded directly to a personal computer (PC) using Entire Connection.

Example Hub Mode Data Collection Process

The following graphic shows the Adabas Review data collection process for hub mode . When monitoring multiple databases, Adabas Review allows you to switch from one database to another and provide reports for each.

graphics/review_process_hub.png

Collecting History Data

History data collection is controlled by RAOSHIST, the Adabas Review historical data population routine.

The format and length of fields stored in the history data is defined in an internal field table in Adabas Review.

z/OS

  • RAOSHIST executes as a subtask of Adabas Review. At initialization, RAOSHIST reads the RVUALT data set to determine if there are any historical records from the previous Adabas Review session that should be written to the Adabas Review repository. History records are written to RVUALT if the database on which the Adabas Review repository resides is unavailable during Adabas Review termination.

  • During normal execution of Adabas Review, REVIEWB is responsible for adding history records generated by detail history reports and by summary history reports that have a history interval.

Scheduling Reports - Collecting Future Data

If reports need to be started or stopped during out-off-office hours or regularly during a period of time without running permanently, or to save resources, the scheduling feature may be useful. Adabas Review uses operating system timer functions for this task.

To handle scheduled reports a new "wait queue" has been setup. Scheduled reports, which are not currently active, reside in the wait queue. Active reports reside in the "active queue". Scheduled reports with several intervals toggle between active and wait queue.

The scheduling option parameters for online reports will be stored together with the report definition on the Review-DB. When running and scheduling a report as a batch job, the scheduling options must be specified with the REPORT statement.

Whenever a report will be scheduled, there is one timer task attached to it. The timer either elapses when a report waits in the wait queue for activation or the timer elapses when an active report will be put back into the wait queue. The timer is limited to a maximum of 27 weeks; i.e. it allows wait/active times with a maximum of 27 weeks. This means that when a report will be scheduled, the start time must be within the next 27 weeks. And the time how long a report is active (duration) and for simplicity the interval time when a report gets activated must be within 27 weeks too.

Scheduled reports, which are suspended, will nevertheless toggle between active and wait queue. 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.

Processing Data Online Using SYSREVDB

Adabas Review can be accessed online via a standard Natural application that resides in the Natural library SYSREVDB. SYSREVDB can be used as an online administration tool. Using commands and screens provided in SYSREVDB, you can:

  • Perform Adabas Review administration (starting, stopping, and defining reports).

  • Access collected monitoring data from summary reports or history data online.

  • Display buffer pool information.

  • Display active databases.

  • Display active maintenance information and environmental information.

  • Maintain target objects and user profiles.

  • Access Adabas Online System, if it is available.

The format and length of fields shown in online reports is defined in an internal field table in Adabas Review.

For complete information on getting started using SYSREVDB, read Getting Started.

Note:
The ADALNK of the TP monitor running SYSREVDB must include the REVEXIT exits. If these are not included, some features might not work correctly in SYSREVDB.

Important:
If an ADALNK batch link routine has been linked or modified by Software AG product modules or user exits, it cannot be used in any application startups of Adabas utility jobs or Adabas, Entire System Server, Adabas Review Hub, or Entire Net-Work nuclei.

The Adabas Review exits include REVEXIT1 (REVEXITB in BS2000 environments) and REVEXIT2. To obtain data for all Adabas Review fields (TP monitor-specific and Natural-specific fields) that are obtained in the Adabas client address space (ADALNK), the REVEXIT1 entry point of the Adabas Review exit REVEXIT and the ADALNK routines from Adabas are used. To obtain data for all client reporting fields, the REVEXIT2 entry point of REVEXIT and the ADALNK routines must also be used.

Note:
In BS2000 environments, REVEXIT2 is not available, so the functionality supplied by REVEXIT2 is missing on this platform.

These exits should be linked with ADALNK during installation, with the appropriate Adabas link globals table parameters (LGBLSET). The link globals table parameters specified via LGBLSET identify which exit entry points (REVEXIT1 or REVEXIT2) are called. If the LGBLSET parameter REVIEW=YES is set, then the exit is called by ADALNK before the Adabas call as entry point REVEXIT1; if the LGBLSET parameters RVCLNT and REVHID are also specified, then the exit is also called after the Adabas call as entry point REVEXIT2.

The modules used to perform the linkage between REVEXIT and ADALNK are provided with your Adabas Review installation with names in the format RDBLXsys, where sys is a three-character code representing the link environment (for example, MVS for z/OS environments, VSE for z/VSE, COM for Com-plete environments, IMS for IMS environments, and BS2 for BS2000 environments). For more information about performing this linkage, read the appropriate Adabas Review installation documentation.

Processing Data in Batch Mode

As a batch job, the Adabas Review command log processing routine REVIEWB processes Adabas command log records from a sequential data set. This input can either be created by the Adabas server writing command logging or by the Adabas Review online processor writing a command log file. See Command log files in the section Output Files below.

If you use Adabas dual command logging, you must first use the Adabas utility function ADARES CLCOPY to generate a sequential command log data set suitable for input into Adabas Review. The command log data set must be specified in the Adabas Review startup JCL using the symbolic job name (DD name, DLBL name, or SET-FILE-LINK name) RVUSEQ.

When Adabas Review executes as a batch job, input report parameters that define the data collection criteria selected by the user are read from statements in the RVUPARM data set or the RVUAUT1/RVUAUT2 data sets. These statements can be generated using the GENCARD statement.

The storage allocated for reports is exactly the same as that for Adabas Review executing in interactive (online) mode. However, since REVIEWB is reading the command log records directly from a sequential file, no REVIEW-BUFFER is allocated.

The following diagram depicts batch mode processing. It shows how Adabas creates a command log (a BDAM data set) that must then be copied to a sequential output command log (data set) using the ADARES CLCOPY utility function. This sequential command log is then used as input to Adabas Review in batch mode. The ADARUN parameters of the Adabas nucleus influence the data that is stored in the sequential data set and only data in the sequential data set is shown by Adabas Review via batch processing. For example, if the ADARUN LOGCLEX parameter is set to NO for the Adabas database, no CLEX information is available in the sequential command log and Adabas Review cannot report on the CLEX fields (which include fields in the NAT and TP field categories).

graphics/review_process_batch_new.png

Output Files

A variety of different output files can be produced by Adabas Review. For more information about each of them, select the name in the "Output File" column below:

Output File Description
Repositories One or more Adabas files used to store report definitions, historical data, and target definitions.
RVUPRT00 Output Printer An output printer defined in the Adabas Review startup job that contains all the parameters, input statements, and final statistics for all reports.
RVUPRTnn Output Printers A series of output printers defined in theAdabas Review startup job that contain detailed or summary report data.
Command log files One or more log files containing command data and, optionally, buffer data from the detailed reports. Command log files are specific to a given detailed report.
Summary log files One or more log files containing data from the summary reports. Summary log files are specific to a given summary report.
Raw log files One or more log files containing raw data from detailed and summary reports. Raw log files are specific to a given detailed or summary report.

Repositories

The Adabas Review repository is an Adabas file used for storing report definitions, historical data, and target definitions. In hub mode, this file must be located on an Adabas database which will be accessed by the hub using normal Adabas router calls. It must also be accessible to the Natural nucleus that is running SYSREVDB.

Depending on the configuration at your site, more than one Adabas Review repository may be associated with your system. For example, if your site is running Adabas Review against more than one database, you may choose to have an Adabas Review repository for each database.

The command SETFILE (or SET) or SETA may be used to access different Adabas Review repositories and the reports stored on them.

The format and length of fields stored in the historical data in the repository is defined in an internal field table in Adabas Review. This information is available to you in the field tables provided in the Field Reference.

RVUPRT00 Output Printer

This output printer contains the parameters, input statements, and final statistics for all reports. This printer file is updated continuously during the Adabas Review session; final statistics for the session are written when Adabas Review shuts down. The RVUPRT00 statement is the JCL control statement name for the output printer definition in the Adabas Review startup JCL.

RVUPRTnn Output Printers

Both detailed and summary data are written to RVUPRTnn output printers when the PRINT report option is set to "Y" for any report. Each output printer contains the data from the report. RVUPRTnn statements are the JCL control statement names for these output printer definitions in the Adabas Review startup JCL, with values for nn ranging from "01" through "99".

RVUPRTnn output printers are assigned to detailed and summary reports in the following manner:

  • A new RVUPRTnn output printer is written for each individual detailed report running with the PRINT report option set to "Y". The numbers of the RVUPRTnn output printers increment as new detailed reports are started.

  • A single RVUPRTnn output printer is used for all summary reports that are running with the PRINT reporting option set to "Y". The number assigned the summary output printer depends on the order in which detailed and summary reports are started.

    For example, suppose you have several detailed reports and summary reports defined with the PRINT report option set to "Y". If you start one of the summary reports first, before any detailed reports, the RVUPRT01 output printer will be assigned to collect all summary data from all summary reports. However, if you started two detailed reports before you started one of the summary reports, the RVUPRT03 output printer would be used to collect all summary data from all summary reports; RVUPRT01 and RVUPRT02 would be used to collect detailed data for the two started detailed reports.

RVUPRT Summary Report Output

Data from summary reports is displayed in the field order specified in the report definition. For each field marked with an order number a control break will occur. For calculation fields no control break is performed. See the examples below.

REPORT NAME LEVEL BREAK EXAMPLE                                       
REVIEW PERIOD:        2016-07-18  13:47:03 - 2016-07-18  13:50:14     
                        SUM           SUM           SUM               
 5MI  JOB-NAME CMD    COMMANDS        I/O          THTIME             
13:45 BATCH1   L4              1             4       0.000000         
13:45 BATCH1   OP              1             0       0.112625         
13:45 BATCH1   RC              1             0       0.004375         
13:45 BATCH1   **              3             4       0.117000         
                                                                      
13:45 BATCH2   L4          2,468            32       0.000000         
13:45 BATCH2   OP              2             0       0.401500         
13:45 BATCH2   RC              2             0       0.016250         
13:45 BATCH2   **          2,472            32       0.417750         
                                                                      
13:45 DAEFCO   L3             88           120       9.195125         
13:45 DAEFCO   RC              2             0       0.044000         
13:45 DAEFCO   S1              4             9       0.822750         
13:45 DAEFCO   **             94           129      10.061875         
                                                                      
13:45 ******** **          2,569           165      10.596625         
                                                                      
13:50 BATCH3   L4          1,234            12       0.000000         
13:50 BATCH3   OP              1             0       0.200750         
13:50 BATCH3   RC              1             0       0.008000         
13:50 BATCH3   **          1,236            12       0.208750         
                                                                      
13:50 ******** **          1,236            12       0.208750         
                                                                      
***** ******** **          3,805           177      10.805375         
                                                                      
REPORT NAME LEVEL BREAK EXAMPLE                                       
REVIEW PERIOD:        2016-07-18  13:47:03 - 2016-07-18  13:50:14     
    LOG RECORDS:               3805                                   
    LOG RECORDS SELECTED:      3805
LEVEL BREAK ON PRINT OUTPUT                                           
REVIEW PERIOD:        2016-07-18  13:50:14 - 2016-07-18  13:50:14     
                                                                      
 5MI  JOB-NAME CMD  FNR                                               
13:50 BATCH3   L4    100                                              
13:50 BATCH3   L4  *****                                              
                                                                      
13:50 BATCH3   RC    100                                              
13:50 BATCH3   RC  *****                                              
                                                                      
13:50 BATCH3   **  *****                                              
                                                                      
13:50 ******** **  *****                                              
                                                                      
***** ******** **  *****                                              
                                                                      
LEVEL BREAK ON PRINT OUTPUT                                           
REVIEW PERIOD:        2016-07-18  13:50:14 - 2016-07-18  13:50:14     
    LOG RECORDS:                 45                                   
    LOG RECORDS SELECTED:        45

Command Log Files

Command log files contain command data and, optionally, buffer data from the detailed reports if the reports are run with their LOG report options set to "Y". 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 you specify for the detailed report and includes only parts of the overall Adabas commands being processed. If report processing rules are specified for the report, only those commands that meet the criteria of the rules are written to the command log file; if no report processing rules are specified, all commands are logged to the command log file.

An individual command log file is written for each detailed report started. In addition to logging the basic command log record (the ACB or ACBX) and the CLEX (corresponding to the ADARUN LOGACB, LOGCLEX, and LOGUX parameters), you can opt to log the buffers from the commands using the Buffers to Log report options.

Command log files are defined by job control statements in the Adabas Review startup job with control statement names that have prefixes specified by the FILE report option. When Adabas Review is distributed and for all new detailed reports you define, this prefix is " RVDET". It is necessary to create unique prefixes for every detailed or summary report. If this is not the case an appropriate error message will be printed when the second report with the same file definition starts and this report will then be started without logging. The job control statements for these command log files must be defined in the Adabas Review startup job before Adabas Review starts.

You can define more than one command log file for a report. You specify the number of log files using the NUM OF LOGS report option. When one log file fills, the next log file is used. When the last log file fills, the first log file will be overwritten. To avoid this, you can specify the name of a command log user exit (using the USER EXIT report option) that you've set up to automatically copy the data from a COMMAND log file when it fills to another location to ensure your data is not lost.

For complete information about log file reporting options, read Logging Options.

The field layout and the formats and lengths of fields in command log files match the Adabas command logs and are mapped by the LOREC and LORECR DSECTs found in your Adabas source library.

Summary Log Files

Summary log files contain data from the summary reports when they are run with their SUMMARY LOG report options set to "Y". An individual summary log file is written for each summary report started.

Summary log files are defined by job control statements in the Adabas Review startup job with control statement names that have prefixes specified by the SUMMARY FILE report option. When Adabas Review is distributed and for all new summary reports you define, this prefix is " RVSUM". We recommend you create unique prefixes for every summary report you create to avoid having two summary reports write to the same summary log file. Nevertheless, it is possible that two or more summary reports write to the same summary log file. The parameter definitions of the report which is started first will be used for all reports which are started afterwards. At each close of a summary report this report will write to the file. It is under the user´s control to divide the specific records to their specific reports. This can be done using the Header portion of the Summary Record Layout.

The job control statements for these summary log files must be defined in the Adabas Review startup job before Adabas Review starts.

You can define more than one summary log file for a report. You specify the number of log files using the NUM OF LOGS report option. When one log file fills, the next log file is used. When the last log file fills, the first log file will be overwritten. To avoid this, you can specify the name of a summary log user exit (using the LOG FULL EXIT report option) that you've set up to automatically copy the data from a summary log file when it fills to another location to ensure your data is not lost.

For complete information about log file reporting options, read Logging Options.

The format and length of fields stored in the summary log files is described in tables in the Field Reference.

Raw Log Files

Raw log files are sequential files that contain data from detailed and summary reports when they are run with their WRITE RAW DATA report options set to "Y".

Raw log files are defined by job control statements in the Adabas Review startup JCL with control statement names that have prefixes specified by the RAW DATA FILE report option. When Adabas Review is distributed and for all new detailed or summary reports you define, this prefix is " RAWDT" for detailed reports and " RAWSM" for summary reports. It is necessary to create unique prefixes for every detailed or summary report. If this is not the case an appropriate error message will be printed when the second report with the same file definition starts and this report will then be started without logging. The job control statements for these raw log files must be defined in the Adabas Review startup job before Adabas Review starts.

You can define more than one raw log file for a report. You specify the number of log files using the NUM OF LOGS report option. When one log file fills, the next log file is used. When the last log file fills, the first log file will be overwritten. To avoid this, you can specify the name of a raw log user exit (using the SWITCH EXIT report option) that you've set up to automatically copy the data from a raw log file when it fills to another location to ensure your raw data is not lost.

For complete information about log file reporting options, read Logging Options.

The format and length of fields stored in the raw log files is described in tables in the Field Reference.

This section covers the following topics:

Raw Log File Format

The format of the data in the raw file records matches that of the report data.

All raw data records are variable-length records and have a four-byte indicator (the length word) at the beginning of each record in the standard format nn00, where nn is the length of the record, including the length word, in binary format. Data in the record may be delimited by a character of your choosing if you have the two parts of the report option Data Dlmitrs set properly. To delimit the data, set the first part of the report option to "Y" and specify an EBCDIC character to be used as a delimiter for the second part of the report option. For more information, read Raw Log Options. If you choose not to use a delimiter, all the fields in the record are strung together in the raw data record with no separator in between them.

Each raw log file begins with a raw header if the report option Write Header is set to "Y". This header shows how subsequent raw data records are defined. If used, it describes the fields in the data record. The format of the raw header is described next in Raw Log Header Format.

Raw Log Header Format

The raw log header record contains the following items, in the following order:

  1. A four-byte record length field (RDW) in nn00 format, where nn is the length of the record, including the length word, in binary format.

  2. The six-byte string "HEADER".

  3. A six-byte field providing the Adabas Review version that produced the raw data.

  4. A 32-byte field providing the name of the report used to generate the raw data.

  5. A one-byte field indicating whether the report is a detailed (D) or summary (S) report.

  6. A two-byte field specifying the delimiter characteristics for the data in the file. The first byte indicates whether the data in the raw data record is field-delimited. A value of C'Y' indicates that there are delimiter characters separating field data in the output record. If this field is set to C'Y', the next byte contains the value of the EBCDIC character used as the delimiter character. This character and these settings are specified in the report options for the report. For more information, read Logging Options.

  7. Four bytes reserved for future use by Software AG.

  8. The actual field descriptors. These repeat for as many fields as are defined in the raw report, up to a maximum of 20 fields. The field descriptor information is formatted as follows:

    Byte Offset Field Length Description
    0 1 The delimiter character for the field descriptor fields in the header record. This is always C','.
    1 8 Report field name with trailing blanks
    9 1 C','
    10 1 Field class indicator

    C'A' -- Account field – break indicator in summary reports
    C'C' -- COST field
    C'M' -- MIN (minimum) field
    C'P' -- PCT (percent) field
    C'R' -- RATE field
    C'S' -- SUM (summary) field
    C'V' -- AVG (average) field
    C'X' -- MAX (maximum) field

    11 1 C','
    12 1 Data type for the field; C'C' for alphanumeric character or C'B' for binary.
    13 1 C','
    14 2 Length of the field in binary format with leading zeroes. All numeric output fields are 8-byte binary fields.
    16 1 C','
    17 1 Number of decimal places.

    Note:
    The value of this field for character fields will be a blank.

Raw Data Record Layout

The raw data record contains the following items in the order as described:

  1. A four-byte record length field (RDW) in nn00 format, where nn is the length of the record, including the length word, in binary format.

  2. The output values for each field in the report.

    The values appear in the order as they appear in the report. If a header record was requested, this will also describe the order of the fields.

If the delimiters option was chosen, each data field will be separated by a delimiter. The delimiter character is specified on the Report Options screen.

If the delimiters option was not chosen, the data values will be concatenated.

The length of each data field's value can be found in Field Reference.

Example:

For a report with the following fields ...

JOBNAME,CMD,FNR,

... the data records, with delimiters would be formatted as follows:

MYJOB #L3#12345 

i.e.

An 8 byte jobname, followed by the delimiter, followed by a 2 byte command, followed by the delimiter, followed by the FNR.

Example:

For a report with the following fields ...

JOBNAME,CMD,FNR,

... the data records, with no delimiters would be formatted as follows:

MYJOB L312345 

i.e.

An 8 byte jobname, followed by a 2 byte command, followed by the FNR.

Note:
Detail and Summary raw records are formatted the same.

User Profile System

Adabas Review administrators use the user profile system to set up user profiles that define access rules for Adabas Review users. Access rules specify the systems or the functions within systems that a particular user is allowed to use.

Adabas Review provides two default Natural profiles that provide access to SYSREVDB for users who do not have a profile defined for them. Both profiles have administrative privileges when you first access Adabas Review, providing unrestricted access to Adabas Review functions.

  • One of the supplied user profile is called "DEFAULT".

    Note:
    The DEFAULT user profile initially provides unrestricted access to Adabas Review functions. Software AG recommends that you first create a new user profile for the system administrator and other privileged users; then modify the DEFAULT profile so that it conforms to the needs of the majority of users. If the default profile is customized so that the access rules meet the needs of the majority of Adabas Review users, the need for individual user profiles can be eliminated.

    The DEFAULT profile cannot be deleted. In addition, Adabas Review will not allow you to turn the DEFAULT profile or any administrator profile into a non-administrator profile if another administrator profile is not available.

  • The other user profile is saved under the name of the user ID of the user initializing the system (the user who entered MENU).

User profiles can be created for new users, changed for existing users, and purged when no longer required. User profiles can be set up so users have access only to specific DBIDs. If a user has access needs that are different from the majority, a user profile can be created to accommodate those needs. Such a profile is generated by customizing a copy of the default profile.

You can also set up group profiles, based on the groups set up by your Natural Security administrator. Natural Security is only required if you want to use group IDs, but not otherwise.

When a user logs on, Adabas Review looks for a group profile first and then for an individual user profile. It uses the first profile found (group profiles take precedence over individual user profiles). If neither a group nor individual user profile is found, the provided default profile is used.

ADARUN Parameters

Adabas ADARUN initialization parameters define and start the Adabas operating environment. Different ADARUN parameters are useful to the Adabas nucleus and the Adabas Review hub in different operating environments. For more information about the ADARUN parameters specific for Adabas Review, read ADARUN Parameters for Adabas Review

Storage Requirements

Adabas Review must allocate storage to execute. Storage is required for

  • the Adabas Review hub, if used;

  • the REVIEW-BUFFER, used as a queueing area for Adabas command log records;

  • reports that are executing;

  • users accessing the database from the Adabas Review online system; and

  • work areas used in Adabas Review's processing.

The type, purpose, and size of these storage areas is discussed in the following sections.

Adabas Review allocates storage above the line whenever it is permitted by the architecture of the machine and the operating system on which it is executing.

In z/OS environments, Adabas Review allocates all storage from z/OS subpool 5. This allows you to accurately determine the exact amount of storage Adabas Review is using with a z/OS monitoring package.

Storage for the Hub

If you use Adabas Review in hub mode, the hub has a separate storage requirement for its operating queues and working areas. The queues are used to buffer the incoming command log records from the clients until the records can be sent to REVIEWB.

Two queues, both controlled by the database administrator (DBA), are used by the Adabas Review hub: the command queue (sized using the ADARUN parameter NC) and the attached buffer (sized using the ADARUN parameter NAB). For more information, read about these ADARUN parameters in ADARUN Parameters.

Command Queue

The command queue stores information about the client nucleus such as job name, internal ID, etc. Each entry in the command queue represents one command log record from a client.

An entry exists for the time that a command log record is queued and awaiting selection from the hub until the time that the record is sent to REVIEWB. Once the command log record is sent to REVIEWB, the entry is released from the command queue.

This means that the command queue must be large enough to accommodate the backlog of command log records from the client nuclei. If the command queue is too small, it is possible that command log records will be dropped by the hub.

The ADARUN parameter that controls the command queue size is NC. The value of this parameter should be set higher for the hub than it is for individual client nuclei.

The NC value should be set to handle the arrival rate based on:

  • the number of clients;

  • their respective command processing limits;

  • the processing power of the CPU(s); and

  • the priority settings of the nuclei and hub address spaces, partitions, or regions.

Example

If a client nucleus can process 2000 commands per second, then the expected arrival rate at the hub is a maximum of 2000 command log records per second. When possible, buffering occurs in the client nucleus to buffer several command log records and send them with one call to the hub.

There is no general rule for estimating the NC requirements for a particular hub. However, in this example, you could start with NC=1000 and monitor the results.

The Command Queue and Trans-port (z/OS only)

When using Trans-port in z/OS environments, most communication is handled via a fast buffer mechanism using a fixed buffer length. In such cases, the command queue is not used.

Attached Buffer

The attached buffer is used to store the contents of the command log records and their associated data extensions.

As with the command queue, an element within the attached buffer is allocated to hold the command log record for the duration of time that the record is queued for selection, up to the time the record can be sent to REVIEWB. The element is freed once the record is sent to REVIEWB.

Also like the command queue, the attached buffer must be large enough to hold the queued command log records for the time required to stage the records for REVIEWB. Software AG recommends setting the parameter high to ensure that command log data is not dropped by the hub.

The ADARUN parameter controlling the attached buffer size is NAB. The value of this parameter should also be set higher for the hub than it is for individual client nuclei.

The NAB value must be large enough to buffer the data passed by the client nuclei. The amount of data passed by a client nucleus depends upon the Adabas Review report requirements (for example, whether control buffers are required or whether the I/O list option is being used).

Example

The average size of a command log record and extensions, excluding control buffers, is 2500 bytes.

One approach would be to compute:

NAB = (NC * 2500 / 4096)

- where 4096 is the size of one NAB segment. If NC=1000 (see the example) , the starting value would be:

NAB = (1000 * 2500 / 4096) = 610

This computation assumes that there are no control buffers or I/O list elements being passed to the hub.

The Attached Buffer and Trans-port (z/OS only)

When using Trans-port in z/OS environments, most communication is handled via a fast buffer mechanism using a fixed buffer length. The attached buffer area is not used.

Storage for the REVIEW-BUFFER

REVIEW-BUFFER is used to queue Adabas command log records to be sent to REVIEWB. In hub mode, it is located in the hub (server) address space.

The BUFFMB parameter specifies the size of the REVIEW-BUFFER. The buffer is allocated as a circular buffer pool.

BUFFMB is an INPUT statement parameter. It replaces the parameters BUFFERS-4K and BUFFERS-32K. They are still valid in Adabas Review 5.1, but will be ignored in later versions.

Parameter Description Minimum Value Default Value
BUFFMB The size of the Adabas Review buffer pool in MB. 1 10

A larger REVIEW-BUFFER provides a larger queueing area for command log records being sent to REVIEWB and decreases the possibility that Adabas will have to wait for REVIEWB to process these records in the event that REVIEW-BUFFER becomes full.

Storage for Reports

For Control Blocks

When a report is started, either using autostarted report definition parameters or by an online Adabas Review user, storage is allocated for control blocks that define the criteria for the collection of the data.

Typically, the storage allocation for control blocks is two (2) kilobytes, but may be as much as four (4) kilobytes if the report is a history report or the report specifies the collection of many fields.

For Data Collection Areas

In addition to the report control blocks, storage is allocated for the collection of data. The data collection areas are allocated in two (2) kilobyte pieces and a subsequent data collection area is only allocated when the current area is full.

Each collected record requires storage equivalent to the length of the account record plus two (2) additional bytes. A record cannot be split over the 2K line.

You can see the actual length of the account record used for a specific report by entering the IN command on the screen in the online administration tool, SYSREVDB. For more information, read Displaying Active Report Information .

Total Storage Limit

The total storage allocation for a report is limited by the MAXSTORE report parameter in batch reports and by the "Max K" option in online reports. When the total storage allocation for a report is equal to the MAXSTORE or "Max K" value, the report is marked as inactive and stops accumulating data. When a report is purged, all storage associated with the report is deallocated.

For more information about the "Max K" online option, read General Report Options. For more information about the MAXSTORE batch report parameter, read REPORT Statement.

Storage for Sorting of Summary Reports

To sort the result of the data collected by a summary report, a sort area space is allocated. This space is used by all reports. Its size depends on the size of the collected data, which depends on the size of the account records and the number of account records. The maximum size for a specific report is set by the MAXK parameter for that report. If a larger area is needed by a new report, the existing area is deallocated and the larger area is allocated.

Once the summary report sort area space is allocated for the largest report, it is not deallocated.

Storage for Online Users

Adabas Review's online system uses Adabas calls to start, view, or purge a report. Each request requires that Adabas Review perform some processing to fulfill the request.

  • Each request from the Adabas Review online system results in the allocation of a piece of storage (about 500 bytes or one-half kilobyte) that is deallocated when the request has been satisfied.

  • To maintain the integrity of each request, Adabas Review allocates an area for each user requesting Adabas Review to service a request. For example, a request to view a report requires an Adabas call for each record that is to be viewed online.

  • In cases where more than one user is viewing the same or different reports, Adabas Review must remember the status of each user between Adabas calls.

Storage for Work Areas

Adabas Review allocates storage for work areas and areas used for reading from and writing to files. These areas are typically small and are kept and used throughout the time that Adabas Review is active.

Size of Adabas Review in z/VSE Environments (Local Mode Only)

In z/VSE environments, the available GETVIS in the Adabas partition may need to be increased to accommodate Adabas Review. An increase of 500K is normal.