
	Version 4.3.2	SEARCH INDEX CONTENTS \| PDF PAGE PDF BOOKS \| HOME UP PREV NEXT

— Installation and Operations for BS2000 —

Operations

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:

SYSOUT and a Subtask List Files
Files Used by Adabas Review
Editing the RVUEXI Parameter File
Command Logging Considerations
Modifying Configuration Parameters
User Exit 5 (Adabas Review Hub Event Handler)
Review Natural User Exits

SYSOUT and a Subtask List Files

Adabas Review spawns the following subtask jobs:

In local mode, the Review database and in hub mode, the Review hub spawns a job where the Review subtask REVIEWB runs.
When an autogenerated report is started, a job running REVAUTO is started.
When a history report is started, a job running RAOSHIST is started.

Each of these jobs generates a SYSLST file with the following file name structure:

L.<L/O>.<task_number>,<subtask>,<timestamp>

where

is for SYSLST

is for SYSOUT

task_number

is the task number of the Review database or Review hub

subtask

is one of the following:

REVIEWB#	for the Review subtask
RAOSAUTO	for the autogenerated report subtask
RAOSHIST	for the history report subtask

timestamp

is the STCK value (in hexadecimal) when the subtask was started

The files provide important diagnostic information when errors occur within the system. They may, however, accumulate in number over time so that it becomes necessary to delete them.

To delete all accumulated Review subtask listings

Use the commands

/DELETE-FILE L.*REVIEWB#*
/DELETE-FILE L.*RAOSAUTO*
/DELETE-FILE L.*RAOSHIST*

Files Used by Adabas Review

RVLOG01 and RVLOG02 Command Logging Files

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.

Adabas Review command logging under BS2000 is an optional feature. BS2000 uses its own command logging files.

Refer to the section Command Logging Considerations for more information.

RVUALT History File

RVUALT is an alternate sequential file used to save history data.

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.

The Adabas Review hub start-up JCL contains a RVUALT job control statement. This statement identifies an alternate file to which historical data may be written.

In situations where the Adabas Review repository is unavailable, Adabas Review receives a response code 148.

In this case, Adabas Review writes the data to the file specified by the RVUALT job control statement, if it has been assigned in the job stream. The next time the Adabas Review hub is started, another subtask is started to copy the historical data to the Adabas Review repository.

Note:
A separate RVUALT dataset must be allocated for each Adabas Review hub.

For BS2000 systems, allocate this file using P.GENERATE.

RVUAUT1 and RVUAUT2 Report Definition Datasets

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.

For BS2000 systems, generate these files using P.GENERATE.

RVUCARD Dataset for GENCARD Command

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

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

RVUEXI 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 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 Dataset

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.

RVUPARM Dummy Dataset

Software AG recommends that you 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.

For BS2000 systems, use the dataset *DUMMY.

Notes:

When RVUPARM is "dummied", the following message displays: REV20164 - OPEN FAILED FOR RVUPARM. When RVUPARM has been dummied, this message is normal and should be ignored.
The above error message can be avoided by creating a RVUPARM dataset that contains only an asterisk.

RVUPRTnn Logical Printer Files

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

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 Review hub start-up job control (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.

Editing the RVUEXI Parameter File

RVUEXI is a parameter file that contains parameters which 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.

RVUEXI 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 8-byte cells that should be allocated to the user ID table manager.

RVUEXI 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.

Command Logging Considerations

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

Setting Up Command Logging

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 job control statements to the Adabas Review hub start-up JCL

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 Adabas Review hub start-up 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 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.

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 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.

LOGUEXIT

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.

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.

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.

Modifying Configuration Parameters

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.
Type SAVE and press ENTER to save the changes.
Type MENU at the prompt to return to Adabas Review.

CONFIGDB File Parameter Description

CONFIGDB contains parameters that affect Adabas Review.

CONFIGDB 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 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 8 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 HUB= (DBID=) command.

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.

An event is defined as

a connection made with the Adabas Review hub during Adabas session open;
a connection broken with the Adabas Review hub during Adabas session close; or
a non-zero return code received from the send operation for a command log record.

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 record that was 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, the register 1 points to the following parameter list:

Input Parameters

Parameter

Header

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 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 found 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

R13	save area of calling Adabas nucleus routine
R14	return address in Adabas nucleus
R15	entry point address for exit

Output Parameters

For logging errors, the exit is required to set a value in the 'operation' field. If the wait value (W) is chosen, the exit is also required to provide a non-zero time value.
Register 15 should be set to zero. All other registers should be returned intact.

Review Natural User Exits

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.

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 on to another Natural application.
Example 3:	Returning to a previous Natural application (using SETUP/RETURN).

SEARCH INDEX CONTENTS | PDF PAGE PDF BOOKS | HOME UP PREV NEXT