This document provides installation preparation information for Adabas Review under z/OS operating system environments. See the current version of the Adabas Review Release Notes for information about supported versions and release levels.
For information about using Software AG's System Maintenance Aid (SMA) for the installation process, refer to the System Maintenance Aid Manual.
This document covers the following topics:
Adabas Review must allocate storage to execute. Storage is required for
the REVIEW-BUFFER, used as a queueing area for Adabas command log records;
users accessing the database from the Adabas Review online system; and
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.
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.
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.
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.
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.
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).
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.
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.
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 BUFFER-SEGMENTS parameter specifies the size of the REVIEW-BUFFER. Each buffer segment is 512 bytes. When a value for BUFFER-SEGMENTS is specified, the total storage indicated by the specification is split in half between 4K buffers and 32K buffers.
In addition, two INPUT statement parameters have been added as replacements for the BUFFER-SEGMENTS parameter. The BUFFER-SEGMENTS parameter will no longer be supported in a future release of Adabas Review. It is still valid in Adabas Review 4.5, but is ignored if the following parameters are specified:
| Parameter | Description | Minimum Value | Default Value |
|---|---|---|---|
| BUFFERS-4K | The number of buffer pool entries that have a length of 4096 bytes or less. This parameter is usually specified along with the BUFFERS-32K parameter. If this parameter is not specified, any BUFFERS-32K parameter setting is ignored. If a value below the minimum value is specified for this parameter, the default is used. | 124 | 256 |
| BUFFERS-32K | The number of buffer pool entries that have a length of 4097 bytes or greater. This parameter is usually specified along with the BUFFERS-4K parameter. If this parameter is not specified, any BUFFERS-4K parameter setting is ignored. If a value below the minimum value is specified for this parameter, the default is used. | 15 | 30 |
For more information about the interaction of the BUFFER-SEGMENTS, BUFFERS-4K, and BUFFERS-32K parameters, read BUFFER-SEGMENTS Parameter Changes
For z/OS, z/VSE, and BS2000, it is possible to execute with a REVIEW-BUFFER that is one megabyte.
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.
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.
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.
The total storage allocation for a report is limited by the MAXSTORE report parameter. When the total storage allocation for a report is equal to the MAXSTORE value, the report is marked as inactive and stops accumulating data. When a report is purged, all storage associated with the report is deallocated.
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.
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.
This section describes the contents of the Adabas Review installation tape and the space requirements for each data set. Sample JCL to accomplish the transfer is also included.
Refer to the "Report of Tape Creation" for the volume serial number, density, media type, data set names, and data set sequence numbers for the SM level being installed.
The Adabas Review version 4.5 installation tape contains the following data sets:
| Data Set | Created Using... | DCB= | Description |
|---|---|---|---|
| REVvrs.INPL | IEBGENER | (RECFM=VB,LRECL=4624,BLKSIZE=4628) | Adabas Review Natural objects. |
| REVvrs.SYSF | IEBGENER | (RECFM=VB,LRECL=9996,BLKSIZE=1000) | Adabas Review repository file. |
| REVvrs.SRCE | IEBCOPY | (RECFM=FB,LRECL=80,BLKSIZE=23440) | Adabas Review source modules and more installation jobs. |
| REVvrs.JOBS | IEBCOPY | (RECFM=FB,LRECL=80,BLKSIZE=23440) | Adabas Review installation jobs. |
| REVvrs.LOAD | IEBCOPY | (RECFM=U,BLKSIZE=6447) | Adabas Review load library. |
| REVvrs.ZAPS | IEBCOPY | (RECFM=FB,LRECL=80,BLKSIZE=3120) | Zaps required for Adabas Review on this platform. |
The REGION parameter for the Adabas nucleus job step may need to be increased to accommodate Adabas Review. An increase of 1 megabyte is normal.
The space requirements for each data set on the installation tape are given in the following table:
| Data Set Type | Directory Blocks | Cylinders (3390) |
|---|---|---|
| INPL | --- | 8 |
| SYSF | --- | 1 |
| SOURCE | 10 | 1 |
| JOBS | 10 | 1 |
| LOAD | 10 | 1 |
In addition, the alternate history file for Adabas Review and the CICS-dependent load library for CICS installations require additional space as follows:
| Data Set Type | Directory Blocks | Cylinders (3390) |
|---|---|---|
| Alternate history file | --- | 2 |
| CICS-dependent load library | 5 | 1 |
Source library members for Adabas Review are as follows:
| Member | Description |
|---|---|
| AUT1PARM | Sample startup parameters for Adabas Review |
| AUT2PARM | Sample startup parameters for Adabas Review |
| CLEXRUBX | Part of LORECRC macro used in DTLEXIT |
| DTLEXIT | Sample detail report user exit for writing SMF records |
| FILETAB | Part of LORECR macro used in DTLEXIT |
| LOGUEXIT | Sample Assembler source code for an Adabas Review command logging user exit |
| LORECR | Macro of LORECR used in DTLEXIT |
| REVCOST | Sample Adabas Review parameters used to produce an Adabas cost accounting report |
| RVUCARD | Sample parameters for running a batch job |
| RVUEX1 | Sample operating environment control parameters for Adabas Review |
| RVUPARM | Internal use only |
| SAMPUEX5 | Sample user exit 5 program |
| SUMEXIT | Sample summary report user exit |
| UEX5PARM | Macro used in SAMPUEX5 |
| USRPARM | Sample parameters for user-defined fields |
| ZAPOPT | Contains optional zaps for installing Adabas Review |
Jobs library members for Adabas Review are as follows:
| Member | Description |
|---|---|
| BATCHRPT | Sample job to create batch reports with online administration tool SYSREVDB. |
| EXPAND3 | Sample job to upgrade an Adabas Review version 4.4 (or 4.3 ) repository to an Adabas Review version 4.5 repository. |
| HISTCOMP | Sample job to compress history data from a batch Natural execution. |
| HISTDEL | Sample job to delete history data from a batch Natural execution. |
| HISTVIEW | Sample job to view history data from a batch Natural execution. |
| HUBJCL | Sample job to start the Adabas Review hub (not used in local mode). |
| LREVLCIC | For CICS installations; sample job used to link the Adabas Review link routine exit with the CICS Adabas command-level link routine; used when reporting on Natural usage in CICS. |
| LREVLCO | For Com-plete installations; sample job used to link the Adabas Review link routine exit with the Com-plete Adabas link routine; used when reporting on Natural usage in Com-plete. |
| LREVLNK/ LREVLKNR | For TSO installations; sample jobs used to link the Adabas Review link routine exit with the TSO/batch Adabas link routine (reentrant link routine) ; used when reporting on Natural usage in TSO or batch jobs. |
| MAKEALT | Sample JCL to create the RVUALT data set. |
| REVCLCOP | Sample JCL to copy and set end-of-file for a sequential command log created by Adabas Review. |
| REVIEWB | Sample JCL to process a sequential command log by the batch component of Adabas Review. |
| REVINPL | Sample job used to INPL the Adabas Review programs and DDMs from the INPL data set to the Natural system files. |
| REVLOAD | Sample job used to load the Adabas Review repository file. |
Adabas Review is installed in two phases:
Phase 1: Install non-TP-specific components. All steps in this phase are identical regardless of the TP monitor in use:
Install Adabas Review under Natural;
Install the Adabas Review repository;
Install Adabas Review under Adabas;
Install the Adabas Review hub (hub mode only);
Optional installation procedures.
Phase 2: Install TP-specific components. Separate procedures are used to install Adabas Review under each of the supported TP monitors: Com-plete; CICS; TSO or TSS; and IMS/DC.
Phase one procedures are described in Installation: Phase 1; phase two procedures in Installation: Phase 2.
Before you install the product, be sure you have read the Release Notes, paying special attention to the Supported Platforms, Software AG Product Support, Enhancements, Restrictions, and Migration Considerations.
