This document describes operational procedures and processes for Adabas Review after it has been installed and initialized.
The Adabas Review main task in both local and hub modes is protected by an ESTAE. In local mode, the ESTAE protects the Adabas nucleus; in hub mode, it protects the Adabas Review clients (also Adabas nuclei).
In local mode, if Adabas Review processing terminates abnormally (abends) in the Adabas main task, the Adabas Review ESTAE routine is given control.
The ESTAE routine traps the abend and 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.
Adabas is protected from termination if Adabas Review abends. Adabas processing continues 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 receive the following message:
Review not installed on database
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
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.
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(RVUAUT1) //RVUAUT2 DD DISP=SHR,DSN=REVvrs.SRCE(RVUAUT2) //RVUCARD DD DISP=SHR,DSN=REVvrs.SRCE(RVUCARD) //RVUFLD DD DISP=SHR,DSN=REVvrs.SRCE(RVUFLD) //RVUPARM DD DUMMY //RVUPRT00 DD SYSOUT=X,LRECL=80,RECFM=FBA //RVUPRT01 DD SYSOUT=X,LRECL=160,RECFM=FBA //RVUPRT02 DD SYSOUT=X,LRECL=160,RECFM=FBA //RVUPRT03 DD SYSOUT=X,LRECL=160,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.
This section describes the files used by Adabas Review:
Note:
The RVUPRT00 data set is mandatory for the Adabas Review processor.
Omitting this data set prohibits the start of the subtask and affects the
subsequent use of SYSREVDB for Adabas Review administration. For example, the TECH
command within SYSREVDB can yield unpredictable results when Adabas Review is started
without the RVUPRT00 data set. Other files described in this section can be
omitted if not needed.
The following are the default names for sequential logging files:
RVLOG for sequential command logging files.
RVSUM for sequential summary logging files.
RAWSM or RAWDT for Raw logging files.
Each report performing command logging or Raw logging must reference a unique file name prefix and a number of command log files associated with that file name prefix.
Only summary reports performing summary logging can use an existing file name prefix from a different report. The parameter definitions of the report which is started first will be used for all reports which are started afterwards.
Note:
All log data sets for a particular report must be the same
size.
Adabas Review allows each report to have up to 99 log files and writes to these files in sequential order. A DD statement must be added to the JCL for each log file. The names of these log files are made up of the file name prefix and a sequential number. The data sets for these 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, BLKSIZE=27998,LRECL=27994) to
make better use of disk storage.
Refer to the section Logging Considerations 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 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.
In hub mode, the Adabas Review hub startup JCL contains a RVUALT statement.
In local mode, the Adabas startup JCL must be modified to include a RVUALT statement during the Adabas Review installation procedure.
RVUALT data sets must be allocated:
In hub mode, a separate RVUALT data set must be allocated for each Adabas Review hub.
In local mode, if Adabas Review is installed on multiple databases, an RVUALT data set must be allocated for each database.
Note:
Ensure that the RVUALT data set is large enough to store all
the data Adabas Review writes to it. Monitor the RVUALT data set and take appropriate
action if the data set becomes full.
The RVUALT history file is allocated using the following DCB attributes:
RECFM=VB,BLKSIZE=10000,LRECL=9996,DSORG=PS
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:
unavailable (in hub mode).
on the same database that is being monitored (in local mode). The response code is returned when the database is brought down and Adabas Review tries to write the historical data.
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 are data sets that contain the report definition control statements for autostarted reports and also some system relevant session parameters such as buffer sizes (for more information, read INPUT Statement. Adabas Review generates the statements and writes them to these files whenever online the target definition parameters are changed (read Displaying SVC Lists and Target Objects) or an autostarted report is created or changed.
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 partitioned data set (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 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.
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 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 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.
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.
The following logical printer files are used by Adabas Review:
RVUPRT00 is the Adabas Review logical printer for statistics about Adabas Review operations, such as number of reports, number of records processed, etc.
Note:
The RVUPRT00 data set is mandatory for the Adabas Review processor.
Omitting this data set prohibits the start of the subtask and affects the
subsequent use of SYSREVDB for Adabas Review administration. For example, the TECH
command within SYSREVDB can yield unpredictable results when Adabas Review is started
without the RVUPRT00 data set. Other files described in this section can be
omitted if not needed.
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:
Review statistics are written to RVUPRT00.
Summary reports are written to RVUPRT01.
The first detail report is written to RVUPRT02
Additional detail reports begin at RVUPRT03 and increment the printer number for each additional report. When a detail report is purged, the corresponding printer number is freed. The next detail report started will reuse the lowest available printer number.
RVUSEQ specifies a sequential input file that contains Adabas command log records. This file is either created by Adabas or by Adabas Review. 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 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:
| 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.
| 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.
This section discusses administrative considerations when performing Adabas Review command logging, summary logging or Raw logging.
Adabas Review provides you with options for determining how logging is processed for reports. However, the Adabas Review administrator must complete the following tasks to set up the Adabas Review environment so that logging can take place:
Allocate log data sets. Log data sets must be allocated for reports.
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 logging must have a log file assigned to it. For each log file, there must be a corresponding job control statement in the startup JCL.
Only summary log files can be shared amongst more than one report. For command log data sets or Raw log data sets, they have to be defined uniquely. If this is not the case an appropriate error message will be printed and the report will be started without logging.
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 Logging Files for more information.
Adabas Review writes to log files in sequential order. When a log file is filled, Adabas Review closes the file, switches to the next sequential file, and continues writing. When all files have been filled, Adabas Review switches back to the oldest file to write data. If a 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 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.
For complete information about the command logging user exit, read REVUXLOG: Command or Summary Logging User Exit
The Adabas Review administrator can modify configuration parameter values in the Natural text member CONFIGDB.
To access and modify these parameters:
At the Natural NEXT prompt, type LOGON SYSREVDB and press ENTER.
After modifying the parameters, type SAVE and press ENTER to save the changes.
Type MENU at the prompt to return to Adabas Review.
The rest of this section describes the CONFIGDB file parameters.
The CONFIGDB file contains parameters that affect Adabas Review. It is saved in the Natural library SYSREVDB.
Adabas Review has two Natural user exits. These exits are located in the Adabas Review system library in Natural, and may be modified by using the Natural editor.
For more information about these exits, read P-UEXIT1 and P-UEXIT2: Review Natural User Exits.