Version 4.5.1
 —  Installation and Operations for z/OS  —

Operations

This document describes operational procedures and processes for Adabas Review after it has been installed and initialized.


Processing Abends

Note:
This section applies only when using Adabas Review in local mode.

If Adabas Review processing terminates abnormally (abends) in RAOSLOCL, the Adabas Review ESTAE routine is given control.

This routine traps the abend, and prints diagnostic information and a dump to expedite the analysis and resolution of the abend to ADASNAP.

The routine also disables Adabas Review processing for the remainder of the Adabas nucleus session.

If you need help resolving the abend, contact your Software AG technical support representative with the printed information.

Abend Protection for Adabas

Adabas is protected from termination if Adabas Review abends. Adabas processing continues without interruption.

Note:
Although Adabas is temporarily unavailable during dump processing, it continues processing as usual once the dump has completed.

Message to Adabas Review users

Users attempting to access Adabas Review following a trapped abend receive the following message:

Review not installed on database

Messages to the Console

The progress of the error handling routine is reported by messages written to the console. For z/OS, the following are example sequences of console messages sent during abend processing:

REV20122 - REVIEW ESTAE EXIT DRIVEN
REV20122 - REVIEW NOW DISABLED
REV20122 - ABEND 000C1000 PSW 078D2000 80129E98
REV20122 - R0  00000002 - R1  0D652DD0 - R2  000FD240 - R3  000FBCC0
REV20122 - R4  00129C48 - R5  0D50AFA8 - R6  0D6E8000 - R7  001331F8
REV20122 - R8  0D50B0E8 - R9  800E93E0 - R10 00042000 - R11 0D5007E0
REV20122 - R12 80128C48 - R13 00128D68 - R14 001294BA - R15 8000DD10
REV20122 - DUMP HAS BEEN TAKEN
REV20126 - REVIEW SUB-TASK DETACHED
REV20129 - HISTORY SUB-TASK DETACHED

Top of page

Adding Adabas Startup Statements at Installation

Note:
This section applies only when using Adabas Review in local mode.

Statements must be added to the Adabas startup job to accommodate Adabas Review. These statements are added during the installation of Adabas Review.

The added statements control many of the operating features of Adabas Review. Some identify parameter files that may be edited by the Review administrator.

The startup statements may be edited, or additional statements may be needed, depending upon the needs of your site. However, deleting any of these statements affects the functioning of Adabas Review and is, therefore, not recommended.

Adabas Startup Statements

The following is a listing of the statements added to the Adabas startup job during Adabas Review installation.

For z/OS, the following statements are added to the Adabas startup JCL:

//RVUEXI   DD DISP=SHR,DSN=REVvrs.SRCE(RVUEXI)
//RVUEXP   DD SYSOUT=X,LRECL=80,RECFM=FBA
//RVUALT   DD DISP=SHR,DSN=REVvrs.ALTHIST
//RVUAUT1  DD DISP=SHR,DSN=REVvrs.SRCE(AUT1PARM)
//RVUAUT2  DD DISP=SHR,DSN=REVvrs.SRCE(AUT2PARM)
//RVUCARD  DD DISP=SHR,DSN=REVvrs.SRCE(RVUCARD)
//RVUFLD   DD DISP=SHR,DSN=REVvrs.SRCE(USRPARM)
//RVUPARM  DD DUMMY
//RVUPRT00 DD SYSOUT=X,LRECL=133,RECFM=FBA
//RVUPRT01 DD SYSOUT=X,LRECL=133,RECFM=FBA
//RVUPRT02 DD SYSOUT=X,LRECL=133,RECFM=FBA
//RVUPRT03 DD SYSOUT=X,LRECL=133,RECFM=FBA
//ADASNAP  DD SYSOUT=X

, where vrs is the current version, revision, and system maintenance level of Adabas Review.

The Adabas startup statements listed above identify files that are used by Adabas Review. Each of these files is described in the following section, Files Used by Adabas Review.

Top of page

Files Used by Adabas Review

This section describes the files used by Adabas Review:

RVLOG01 and RVLOG02 Command Logging Files

RVLOG01 and RVLOG02 are the default names for the sequential command logging files. Each report performing command logging must reference a unique file name prefix and a number of command log files associated with that file name prefix.

Note:
All command log data sets for a particular report must be the same size.

Adabas Review allows each report to have up to 99 command log files and writes to these files in sequential order. A DD statement must be added to the JCL for each command log file. The names of these command log files are made up of the file name prefix and a sequential number. The data sets for these command log files may be allocated using IEFBR14 with the following DCB attributes:

RECFM=VB,BLKSIZE=10000,LRECL=9996,DSORG=PS

Note:
While RECFM and DSORG cannot be altered, the combination of LRECL and BLKSIZE can be altered (for example, LRECL=27998, BLKSIZE=27994) to make better use of disk storage.

Refer to the section Command Logging Considerations for more information.

RVSUM01 and RVSUM02 Summary Logging Files

RVSUM01 and RVSUM02 are the default names for the sequential summary logging files. Each report performing summary logging must reference a unique file name prefix and a number of summary log files associated with that file name prefix.

Note:
All summary log data sets for a particular report must be the same size.

Adabas Review allows each report to have up to 99 summary log files and writes to these files in sequential order. A DD statement must be added to the JCL for each summary log file. The names of these summary log files are made up of the file name prefix and a sequential number. The data sets for these summary log files may be allocated using IEFBR14 with the following DCB attributes:

RECFM=VB,BLKSIZE=10000,LRECL=9996,DSORG=PS

Note:
While RECFM and DSORG cannot be altered, the combination of LRECL and BLKSIZE can be altered (for example, LRECL=27998, BLKSIZE=27994) to make better use of disk storage.

Refer to the section Summary Logging Considerations for more information.

RVUALT History File

Adabas Review reports may specify whether the data accumulated by the report will also be written to the Adabas Review repository. Historical data is useful for monitoring database performance and for performing trend analysis.

The parameters that determine whether Adabas Review writes historical data are set when a user creates or edits a report definition. These history parameters appear on the Report Options screen of the Edit Report (ER) function.

If historical data is to be written by a report running in batch mode, the history parameters make up the COPY statement.

A RVUALT job control statement can identify an alternate sequential file to which historical data may be written when it cannot be written to the Adabas Review repository.

RVUALT data sets must be allocated:

The RVUALT history file is allocated using the following DCB attributes:

RECFM=VB,BLKSIZE=10000,LRECL=9996,DSORG=PS
Warning:
Use IEBGENER to allocate the RVUALT file, since an EOF (end-of-file) must be written for the file. Allocation with IEFBR14 will not write the EOF mark. In hub mode, the sample JCL member MAKEALT will do this.

Adabas Review receives a response code 148 (Adabas not active) and writes the data to the file specified by the RVUALT job control statement (if it has been assigned in the job stream) in situations where the Adabas Review repository is:

The next time the Adabas Review hub is started, another subtask is started to copy the historical data from the RVUALT file to the Adabas Review repository.

RVUAUT1 and RVUAUT2 Report Definition Data Sets

RVUAUT1 and RVUAUT2 are data sets that contain the report definition control statements for autostarted reports. Adabas Review generates the statements and writes them to these files. When Adabas is initialized, the reports are started automatically.

The installation procedure for z/OS defines DD statements RVUAUT1 and RVUAUT2 so that they point to members of a PDS. To avoid constant compression of these data sets, the DD statements may be modified to point to sequential data sets.

Note:
In a future release of Adabas Review, RVUAUT2 will no longer be supported. RVUAUT1 only will be used for autostarted reports.

RVUCARD Data Set for the GENCARD Command

RVUCARD is a data set used by the GENCARD command. The GENCARD command creates batch parameter statements from report definitions created online.

The command requires the user to supply a DDNAME, and the generated statements are written to the corresponding file.

RVUEX1 Parameter File

RVUEXI is a parameter file that contains parameters to control the Adabas Review operating environment. The Adabas Review administrator may edit the RVUEXI parameters according to the specific needs of the site.

Refer to the section Editing the RVUEXI Parameter File for more information.

RVUEXP Companion Output File

RVUEXP is a companion file to RVUEXI and if specified, any parameter processing errors encountered in RVUEXI will be written to the RVUEXP output file.

RVUFLD User Field Parameter Data Set

The RVUFLD data set contains parameter control statements for creating user-defined fields. Parameters in this data set define the length, type, and location of reporting fields to be determined by the user.

RVUPARM Dummy Data Set

The recommended procedure is to set RVUPARM to "dummy". In previous releases, batch parameter statements were read from this file. Because these statements may now be generated using the GENCARD command, you no longer need to code batch parameters manually. Parameters may be coded in this data set if desired, and Adabas Review will access this data set prior to accessing data sets specified by RVUAUT1 and RVUAUT2.

When RVUPARM has been "dummied", the following message is displayed:

REV20164 - Open failed for RVUPARM	

In this case, the message is normal and should be ignored. The message does not occur if instead you create a RVUPARM data set that contains only an asterisk.

RVUPRTnn Logical Printer Files

The following logical printer files are used by Adabas Review:

RVUPRT00 for Adabas Review Statistics

RVUPRT00 is the Adabas Review logical printer for statistics about Adabas Review operations, such as number of reports, number of records processed, etc.

RVUPRTnn Files for Reports

graphics/review_rvuprt.png

RVUPRT01 and above are Adabas Review logical printers used for reports. One logical printer is shared by all summary reports; each detail report requires its own logical printer. A job control statement corresponding to each logical printer must be added to the Adabas Review hub (in local mode, to the Adabas) startup job control (JCL).

Assignment of reports to logical printers is as follows:

Top of page

Editing the RVUEX1 Parameter File

The RVUEXI file contains parameters to control the Adabas Review operating environment. The Adabas Review administrator may edit the RVUEXI parameters according to the specific needs of the site.

This section covers the following topics:

RVUEX1 User-Specified Parameter

Parameter Possible Values Default
UIDT-CELLS 100-10000 1000

The user ID table is managed using a hashing algorithm. This value is numeric and specifies the number of eight-byte cells that should be allocated to the user ID table manager.

RVUEX1 Timeout Parameters

Parameter Possible Values Default
UCMD-TIMEOUT 0-999 60

A small reentrant storage area is allocated for each active user of the Adabas Review online system (LIST, VIEW, START, PURGE reports functions). This area is deallocated when the user finishes each online request.

However, if the user's Natural session terminates abnormally during an Adabas Review operation, the Adabas Review nucleus may not have the opportunity to deallocate the reentrant area.

Specifying the UCMD-TIMEOUT parameter gives the Adabas Review nucleus a timeout value after which these inactive areas are deallocated. The timeout value is numeric and is specified in minutes.

Parameter Possible Values Default
UIDT-TIMEOUT 1-999 60

To report on the field TPTRANCT, Adabas Review must maintain a work area for each user that accesses Adabas. This area is called the user ID table.

If this field is specified in a report, the facility is activated and an area is allocated when Review receives the first call from each user. The area is deallocated when Review receives an Adabas CLOSE (CL) command for that user.

However, if the user's application does not issue a CL during termination, Review is unaware that the session has terminated.

The UIDT-TIMEOUT parameter is used to expire inactive user ID table elements. If the field TPTRANCT is not specified in any active reports, Review will not maintain user ID table elements for each user. This value is numeric and specifies the timeout value in minutes.

Top of page

Command Logging Considerations

This section discusses administrative considerations when performing Adabas Review command logging.

Setting Up Command Logging

Adabas Review provides you with options for determining how command logging is processed for reports. However, the Adabas Review administrator must complete the following tasks to set up the Adabas Review environment so that command logging can take place:

  1. Allocate command log data sets. Command log data sets must be allocated for reports.

  2. Add job control statements to the Adabas Review hub startup JCL (hub mode) or to the Adabas nucleus startup JCL (local mode).

    Each report that performs command logging must have a command log file assigned to it. For each command log file, there must be a corresponding job control statement in the startup JCL.

    The name must be a five-character name followed by a sequential number (01, 02, etc.) corresponding to the number of command logs. For example, if the name is "CMLOG" and there are two data sets to be defined, two statements are required with names as follows: CMLOG01 and CMLOG02. The five-character name is referenced by the report in the File command logging report option. The total number of data sets is referenced by the report in the Num of Logs command logging report option. For more information about these logging options, read Logging Options.

    Refer to the section RVLOG01 and RVLOG02 Command Logging Files for more information.

Using the Command Logging User Exit

Adabas Review writes to command log files in sequential order. When a command log file is filled, Adabas Review closes the file, switches to the next sequential file, and continues logging. When all files have been filled, Adabas Review switches back to the oldest file to log data. If a command logging user exit is not specified, Adabas Review will write over the log data in the file containing the oldest data.

A command logging user exit can be specified so that the data contained in the command log file can be copied to a new file before the command log file is overwritten with new command log data. This user exit will be called each time a command log file is closed or opened, but it is only called if you reference it in the User Exit report logging option. For more information about this logging option, read Logging Options.

LOGUEXIT Sample User Exit

The source library member LOGUEXIT contains sample code for the user exit that processes command logs. You may modify this exit so that it conforms to your site requirements, and you can include the exit name in the User Exit logging option on the Report Options screen of your report definition.

REVCLCOP Sample Copy Job

When a command log file is closed, the user exit starts the command log copy job. The JCL library member REVCLCOP contains a sample command log copy job. This job copies the contents of a filled command log file to another device and appends the new data to existing data. This job also reinitializes the end-of-file marker in the command log file.

End-of-File Marker Position

When a command log file is opened, the user exit checks the position of the end-of-file marker to determine if there is any data in the command log file.

Top of page

Summary Logging Considerations

This section discusses administrative considerations when performing Adabas Review summary logging.

Setting Up Summary Logging

Adabas Review provides you with options for determining how summary logging is processed for reports. However, the Adabas Review administrator must complete the following tasks to set up the Adabas Review environment so that summary logging can take place:

  1. Allocate summary log data sets. Summary log data sets must be allocated for summary reports.

  2. Add job control statements to the Adabas Review hub startup JCL (hub mode) or to the Adabas nucleus startup JCL (local mode).

    Each report that performs summary logging must have a summary log file assigned to it. For each summary log file, there must be a corresponding job control statement in the startup JCL.

    The name must be a five-character name followed by a sequential number (01, 02, etc.) corresponding to the number of command logs. For example, if the name is "SMLOG" and there are two data sets to be defined, two statements are required with names as follows: SMLOG01 and SMLOG02. The five-character name is referenced by the report in the Summary File summary logging report option. The total number of data sets is referenced by the report in the Num of Logs summary logging report option. For more information about these logging options, read Logging Options.

    Refer to the section RVSUM01 and RVSUM02 Summary Logging Files for more information.

Using the Summary Logging User Exit

Adabas Review writes to summary log files in sequential order. When a summary log file is filled, Adabas Review closes the file, switches to the next sequential file, and continues logging. When all files have been filled, Adabas Review switches back to the oldest file to log data. If a summary logging user exit is not specified, Adabas Review will write over the log data in the file containing the oldest data.

A summary logging user exit can be specified so that the data contained in the summary log file can be copied to a new file before the summary log file is overwritten with new summary log data. This user exit will be called each time a summary log file is closed or opened, but it is only called if you reference it in the Log Full Exit report logging option. For more information about this logging option, read Logging Options.

LOGUEXIT Sample User Exit

The source library member LOGUEXIT contains sample code for the user exit that processes summary logs. You may modify this exit so that it conforms to your site requirements, and you can include the exit name in the Log Full Exit logging option on the Report Options screen of your report definition.

REVCLCOP Sample Copy Job

When a summary log file is closed, the user exit starts the summary log copy job. The JCL library member REVCLCOP contains a sample summary log copy job. This job copies the contents of a filled summary log file to another device and appends the new data to existing data. This job also reinitializes the end-of-file marker in the summary log file.

End-of-File Marker Position

When a summary log file is opened, the user exit checks the position of the end-of-file marker to determine if there is any data in the summary log file.

Top of page

Modifying Configuration Parameters

The Adabas Review administrator can modify configuration parameter values in the Natural text member CONFIGDB.

Start of instruction setTo access and modify these parameters:

  1. At the Natural NEXT prompt, type LOGON SYSREVDB and press ENTER.

  2. Type EDIT CONFIGDB and press ENTER.

  3. After modifying the parameters, type SAVE and press ENTER to save the changes.

  4. Type MENU at the prompt to return to Adabas Review.

CONFIGDB File Parameter Description

CONFIGDB, which contains the Adabas Review configuration parameters, is saved in the Natural library SYSREVDB.

Parameter Possible Values Default
CURSOR-POSITION BOT | TOP BOT

Specifies whether the cursor is placed on the command line (BOT) in list displays, or on the SEL field (TOP).

Parameter Possible Values Default
DECIMAL-CHAR NAT|char NAT

Specifies the decimal character to use when generating Review reports. The value specified overrides the value specified for the NATPARM DC parameter. If the value specified is NAT then the value specified in the NATPARM DC parameter is used. To determine the current setting of the NATPARM DC parameter, issue GLOBALS at the NEXT prompt.

Parameter Possible Values Default
PC-FILE 'text' 'DOWNLOAD-PC-FILE-5'

Specifies the value to be used in the DOWNLOAD statement in the Review-generated programs. The value specified must be delimited with single apostrophes. The field is alphanumeric, maximum 20 characters.

Parameter Possible Values Default
RVBX-MESSAGE YES | NO YES

Specifies whether to display error messages about the incorrect installation of the Adabas Review link routine exits during installation verification.

Parameter Possible Values Default
UBAR any valid character |

Specifies the character to be used in maps as the vertical border. Any character recognized by your system is valid; the default value is "|".

Parameter Possible Values Default
CLOSE-DBID YES | NO NO

Specifies whether to issue a close (CL) command to the old Adabas Review database when a new database is accessed with the HUB= (DBID=) command.

Parameter Possible Values Default
REVIEWDB-UEX name exit not enabled

Specifies the name of the site-dependent Natural routine to be called for validation of a user's access to an Adabas Review function.

Refer to Natural source member N-USEXIT for more information on the calling and processing conventions for this exit.

Parameter Possible Values Default
MAXIMUM-MAXK 0 | nnnn 0

Specifies the maximum value that can be specified for the report option, Max K. The Max K value determines the maximum amount of storage available for a specific report.

A value of 0 (the default) indicates that the Max K option is not restricted.

When specifying a value, MAXIMUM-MAXK must be 4 or greater for z/OS.

Parameter Possible Values Default
OPEN-DBID YES | NO NO

Specifies whether an open (OP) command is issued to the new Adabas Review database when a new database is accessed with the HUB= (DBID=) command.

Top of page

User Exit 5 (Adabas Review Hub Event Handler)

User exit 5 is called by the Adabas nucleus when an event occurs with the Adabas Review hub. User exit 5 must be specified in ADARUN parameter UEX5 in the Adabas nucleus startup job. An event is defined as:

The exit is invoked with AMODE=31 and should return control in the same state.

The exit is required to process logging errors. It determines how the failure is handled. The parts of the buffer that were not logged and the response code received from the Adabas Review hub logging request are provided to assist in making the determination.

Input Parameters

On entry, register 1 points to the following parameter list:

graphics/reg1_parmlist.png

Parameter Usage
0(R1) Exit call indication. The value of this byte can be:
  • "O" -- connection with Adabas Review hub opened;

  • "C" -- connection with Adabas Review hub closed; or

  • "L" -- sending logging error to Adabas Review hub.

1(R1) Action to handle a logging error (ignored for open and close). The exit must provide one of the following values for this field in the parameter list for a logging error:
  • "W" -- wait for a specified time and then retry;

  • "R" -- retry logging operation immediately; or

  • "I" -- ignore the logging failure and continue without consequence.

2(R1) Response code for logging errors. This response code is the same as the Adabas response code in the Adabas Messages and Codes documentation.
4(R1) Fullword where the exit must provide a wait time (in seconds) for the logging failures that are to be retried after waiting.
8(R1) Address of the command log record that the Adabas nucleus was attempting to send to the Adabas Review hub.

Other Register Values at Entry

Value Description
R13 Save area of calling Adabas nucleus routine.
R14 Return address in Adabas nucleus.
R15 Entry point address for exit.

Output Parameters

Top of page

Review Natural User Exits

Review has two Natural user exits. These exits are located in the Review system library in Natural, and may be modified by using the Natural editor. They are applicable to both the Adabas Review and Review DC systems.

P-UEXIT1

Use: You may place coding in this program to allow for site-specific needs.
Invoked: This program is invoked when the online portion of Review is entered.
Example 1: Setting colors on (SET CONTROL 'T3279')
Example 2: Turning the PC mode on or off.
Remark: This program must not alter the Natural stack, and it must end with a STOP command.

P-UEXIT2

Use: You may place coding in this program to alter the processing that occurs when terminating Review.
Invoked: This program is invoked when the online portion of Review is terminated.
Example 1: Returning to Natural rather than terminating your session.
Example 2: Logging onto another Natural application.
Remark: Returning to a previous Natural application (using SETUP/RETURN).

Top of page