This section of the documentation describes operational procedures and processes for Adabas Review after it has been installed and initialized.
This document covers the following topics:
If Adabas Review processing terminates abnormally (ABENDs), the Adabas Review routine ESTAE 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.
Contact your Software AG technical support representative with the printed information for assistance in resolving the ABEND.
Adabas is protected from termination if Adabas Review ABENDs. Adabas processing will continue without interruption.
Note:
Although Adabas will be temporarily unavailable during dump
processing, it will continue processing as usual once the dump has
completed.
Users attempting to access Adabas Review following a trapped ABEND will receive the following message:
Review not installed on database
The progress of the error handling routine is reported by messages written to the console. The following is an example sequence of console messages sent during ABEND processing:
REVESTAE - REVIEW ESTAE EXIT DRIVEN REVESTAE - REVIEW NOW DISABLED REVESTAE - ABEND 000C1000 PSW 078D2000 80129E98 REVESTAE - R0 00000002 - R1 0D652DD0 - R2 000FD240 - R3 000FBCC0 REVESTAE - R4 00129C48 - R5 0D50AFA8 - R6 0D6E8000 - R7 001331F8 REVESTAE - R8 0D50B0E8 - R9 800E93E0 - R10 00042000 - R11 0D5007E0 REVESTAE - R12 80128C48 - R13 00128D68 - R14 001294BA - R15 8000DD10 REVESTAE - DUMP HAS BEEN TAKEN REV20126 - REVIEW SUB-TASK DETACHED REV20129 - HISTORY SUB-TASK DETACHED
Statements must be added to the Adabas start-up 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 start-up statements may be edited, or additional statements may be needed, depending upon the needs of your site. However, deleting any of these statements will affect the functioning of Adabas Review and is, therefore, not recommended.
The following is a listing of the statements added to the Adabas start-up job for z/VM during Adabas Review installation.
The following file definitions are added to the Adabas start-up EXEC:
'FILEDEF RVUPRT00 DISK REV43 REVPRT00 A (LRECL 133' 'FILEDEF RVUPRT01 DISK REV43 REVPRT01 A (LRECL 133' 'FILEDEF RVUPRT02 DISK REV43 REVPRT02 A (LRECL 133' 'FILEDEF RVUPRT03 DISK REV43 REVPRT03 A (LRECL 133' 'FILEDEF RVUAUT1 DISK REV43 RVUAUT1 * (LRECL 80' 'FILEDEF RVUAUT2 DISK REV43 RVUAUT2 * (LRECL 80' 'FILEDEF RVUALT DISK REV43 RVUALT A (LRECL 9996 RECFM V' 'FILEDEF RVLOG01 DISK REV43 RVLOG01 A (LRECL 9996 RECFM V' 'FILEDEF RVLOG02 DISK REV43 RVLOG02 A (LRECL 9996 RECFM V' 'FILEDEF RVUEXP DISK REV43 RVUEXP A (LRECL 80' 'FILEDEF RVUEXI DISK REV43 RVUEXI * (LRECL 80' 'FILEDEF RVUFLD DISK REV43 RVFLD * (LRECL 80' 'FILEDEF RVUPARM DUMMY
The Adabas start-up statements listed above identify files that are used by Adabas Review. Each of these files is described in the following section Files Created by Adabas Start-up Statements.
RVLOG01 and RVLOG02 are sequential command logging files. Each report performing command logging must reference a unique file name prefix and the number of command log files associated with that file name prefix.
Note:
All command log datasets for a particular report must be the same
size.
Under z/VM, Adabas Review allows each report to have up to 99 command log files, and writes to these files in sequential order. A FILEDEF statement must be added to the RMTNUC EXEC 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 files have the following DCB attributes:
RECFM=VB,BLKSIZE=10000,LRECL=9996,DSORG=PS
Refer to the section Setting Up Command Logging for more information.
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 file is an alternate sequential file to which historical data is written when it cannot be written to the Adabas Review repository.
Under z/VM, the RVUALT file is allocated automatically by Adabas Review. If Adabas Review is installed on multiple databases, a RVUALT dataset is allocated for each database.
Adabas Review receives a response code 148 (Adabas not active) and writes the data to the RVUALT file in situations where the Adabas Review repository is on the same database that is being monitored. The response code is returned when the database is brought down and Adabas Review tries to write the historical data.
The next time Adabas is started, another subtask is started to copy the historical data from the RVUALT file to the Adabas Review repository.
RVUAUT1 and RVUAUT2 are datasets 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.
Under z/VM, the RVUAUT1 and RVUAUT2 datasets are provided on the Adabas Review installation tape.
RVUCARD is a dataset used by the GENCARD command. The GENCARD command creates batch parameter statements from report definitions created online.
Under z/VM, RVUCARD is not used.
RVUEXI is a parameter file that contains parameters which control the Adabas Review operating environment. The 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 is a companion file to RVUEXI and if specified, any parameter processing errors encountered in RVUEXI will be written to the RVUEXP output file.
The RVUFLD dataset contains parameter control statements for creating user-defined fields. Parameters in this dataset define the length, type, and location of reporting fields to be determined by the user.
The recommended procedure is to set RVUPARM as a dummy dataset. 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 dataset if desired, and Adabas Review will access this dataset prior to accessing datasets specified by RVUAUT1 and RVUAUT2.
Under z/VM, a FILEDEF of "dummy" can be used.
Note:
When RVUPARM has been "dummied", the message
REV20164 - Open failed for RVUPARM is displayed.
In this case, the message is normal and should be ignored. The message does not
occur if instead you create a RVUPARM dataset that
contains only an asterisk.
RVUPRT00 is the Adabas Review logical printer for statistics about Adabas Review operations, such as number of reports, number of records processed, etc.
RVUPRT01, 02, ... nn
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 start-up JCL.
Assignment of logical printers to reports depends on the order in which the reports are started:
If the first report started is a summary report, RVUPRT01 is used for all summary reports.
If the first report is a detailed report, RVUPRT01 is assigned to the detailed report, and another logical printer is used for summary reports. When a detail report is purged, the corresponding printer number is freed. The next detail report started will reuse the lowest available printer number.
The RVUEXI file contains parameters to control the Adabas Review operating environment. The Adabas Review administrator may edit the following RVUEXI parameters according to the specific needs of the site.
Note:
Default values are underlined in the following tables.
| 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 8-byte cells that should be allocated to the user ID table manager.
| 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.
| Parameter | Possible Values | Default |
|---|---|---|
| CMS-FULLSYNCH | YES | NO | NO |
Specifies whether REVIEWB should be called for every command log record instead of when the REVIEW-BUFFER is full.
This section discusses administrative considerations when performing Adabas Review command logging.
Command log information is passed from Adabas to Adabas Review. Under some conditions, information is returned to Adabas. Information flows between Adabas Review and Adabas as follows:
Adabas passes command logs to Adabas Review.
All Adabas command logging information is passed to Adabas Review.
User determines what information is reported.
Adabas Review users are given the option to suppress any unnecessary information on a report-by-report basis. This option is available from the Edit Report (ER) function. The user selects from parameters that mirror the ADARUN parameters.
The user has 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:
Allocate command log datasets.
Command log datasets must be allocated for reports.
Add control statements to the REV43 FILEDEFS member.
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 entry in the REV43 FILEDEFS member.
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 datasets to be defined, two statements are required with names as follows:
CMLOG01 CMLOG02
The five-character name is referenced by the report in the command logging report option FILE. The total number of datasets is referenced by the report in the command logging report option NUM OF LOGS.
Refer to the section RVLOG01 and RVLOG02 Command Logging Files for more information.
Adabas Review writes to command log files in sequential order. When a command log file is filled, Adabas Review closes the file and switches to the next sequential file. If all files have been filled, Adabas Review switches back to the oldest file and begins again.
If a command logging user exit is not specified, Adabas Review simply closes a filled command log file and opens the next file. When all files are filled, Adabas Review writes over the file containing the oldest data.
A user exit is provided so that the data contained in the command log file may be copied to a new file before the command log file is overwritten with new command log data. This user exit is called each time a command log file is closed or opened.
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 users may include the exit name on the Report Options screen of their report definition.
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.
If the position indicates that there is no data in the file, Adabas Review writes command log data to the file.
If the position indicates that there is data in the file, Adabas Review sends a message to the operator asking whether Review should wait until the copying of the command log is completed, or begin writing to the command log file and overwrite the existing data.
The Adabas Review administrator can modify configuration parameter values in the Natural text member CONFIGDB.
To access and modify the CONFIGDB parameters
At the Natural NEXT prompt, type LOGON SYSREVDB and press ENTER.
Type the command EDIT CONFIGDB and press ENTER. Modify the parameters as required.
Type SAVE and press ENTER to save the changes.
Type MENU at the prompt to return to Review.
CONFIGDB, which contains parameters that affect Adabas Review, 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 | NAPARM DC=value | . |
Specifies the decimal character to use when generating Review
reports. The value specified should match the value specified for the NATPARM
DC parameter. To determine the current setting of the NATPARM DC parameter,
issue GLOBALS at the NEXT prompt. The Review default
value for DECIMAL-CHAR is a period ('.').
| 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 |
|---|---|---|
| RVXB-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 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.
| 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 DBID= command.
Review has two Natural user exits. These exits are found 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 Data Communication systems.
| 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. |
| 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 on to another Natural application. |
| Example 3: | Returning to a previous Natural application (using SETUP/RETURN). |
