This document describes the user exits provided with Adabas Review.
Additional Adabas Review programs, the RVCALL programs, are provided for you to use to perform Adabas Review SYSREVDB (online) functions from your own Natural programs. For information about these programs, read Performing Adabas Review Online Functions from Natural Programs.
 |
Warning: Sample user exits and programs and are not supported under any maintenance contract agreement. |
Adabas Review has three Natural user exits. These exits are located in the Adabas Review system library in Natural, and may be modified using the Natural editor.
P-UEXIT1 is invoked when the online portion of Adabas Review (SYSREVDB) is entered. A possible use for this user exit might be the setting of customer-specific colors or switching the PC mode on or off.
Important:
The P-UEXIT1 user exit that is called when SYSREVDB
is entered must not alter the Natural stack; it must end with a
STOP command.
P-UEXIT2 is invoked when PF12 is clicked on the Main Menu or when a termination command (such as FIN, QUIT, or LOGON) is entered on the command line of the Main Menu of SYSREVDB. When PF12 is clicked or a termination command is entered, the Natural system variable *COM contains the string "PF12 FROM MAIN MENU". When delivered, P-UEXIT2 performs no function at all. A possible use case for this user exit is the automatic logon to another Natural application.
P-UEXIT3 is invoked when PF3 is clicked on the Main Menu or when the EXIT command is entered on the command line of the Main Menu of SYSREVDB. When PF3 is clicked or the EXIT command is entered, the Natural system variable *COM contains the string "PF3 FROM MAIN MENU".
The normal Adabas Review behavior for PF3 or the EXIT command from the Main Menu is to leave SYSREVDB and log the user into a private Natural environment set up for that user. You can use P-UEXIT3 to alter this behavior, possibly when your users have no private Natural environments established. When delivered, P-UEXIT3 performs no function at all.
Note:
If your P-UEXIT3 code returns the user to SYSREVDB after
the exit completes, the normal Adabas Review PF3 behavior will be invoked. If this is
not what you want to happen, make sure that the exit does not return to
SYSREVDB implicitly or with the ESCAPE MODULE.
REVUEX1 is called from the ADALNK REVEXIT. Using this user exit you can provide user-specific data to be passed to Adabas Review. To do this, move the desired data into a 100-byte area in the RUBX. An address to this area is provided in the parameters passed to the REVUEX1 exit. The RUBX area is the area where link-relevant information is passed to Adabas Review. Once the user exit is processed, this user-specific data can be viewed in Adabas Review reports using a user field that accesses the Adabas Review field RDBLKUSR.
The user fields do only support binary and alphanumeric input types. The REVUEX1 is responsible to provide the right format in the area which will be transferred and later used in the Review nucleus. In case a wrong format, for example a value in packed format, is provided this might result in a not expected output value.
Note:
For the definition of the user field, the RDBLKUSR field name
must be specified as source field.
Important:
If an ADALNK batch link routine has been linked or
modified by Software AG product modules or user exits, it cannot be used in any
application startups of Adabas utility jobs or Adabas, Entire System Server,
Adabas Review Hub, or Entire Net-Work nuclei.
The following installation steps must be completed to
activate the user field user exit:
Customize REVUEX1 as needed. Sample source for the exit can be found in the Adabas Review source (SRCE) library. For information about parameters passed to the exit, read Parameters Passed to the Exit.
Note:
The name REVUEX1 cannot be changed.
If you want to customize REVUEX1 under CICS, you may customize member REVUEX1C.
Assemble REVUEX1. A sample assembly job for the user exit, AREVUEX1, is provided in the Adabas Review jobs (JOBS) library. ASMUEX1C can be used to assemble REVUEX1C.
Link REVUEX1 with the Adabas Review ADALNK REVEXIT. A sample job, LREVUEX1, is provided in the Adabas Review jobs (JOBS) library.
Link the Review ADALNK REVEXIT with the Adabas link routines. Sample jobs with names in the form LREVLxxx can be found in the Adabas Review jobs (JOBS) library.
Input parameters for the exit are expected in the following registers:
| Register | Parameter |
|---|---|
| 1 | Address of the user parameter list (for example, ACB,RB,FB). |
| 2 | Address of the user field data that can be modified. One hundred (100) bytes are reserved for the user field data. |
| Register | Description |
|---|---|
| 13 | Save area of calling ADALNK routine |
| 14 | Return address to ADALNK routine |
| 15 | Entry point address for the user exit |
To view the user-specific data in a report, specify a user field with following definition:
NAME=YCHOOSE LEN=70 INTYPE=C OUTTYPE=C FIELD=RDBLKUSR DISPLEN=70 HEADER=YCHOOSE NAME=YCHOOSE1 LEN=30 INTYPE=C OUTTYPE=C FIELD=RDBLKUSR+70 DISPLEN=30 HEADER=YCHOOSE1
The RDBLKUSR user field name cannot be changed; it is reserved for use with REVUEX1 (user field exit).
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:
a connection made with the Adabas Review hub during Adabas session open;
a connection ended 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. When buffering is active, this return code is provided once for a whole buffer and it is possible that only parts of the buffer were not transferred correctly.
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.
On entry, register 1 points to the following parameter list:
| Parameter | Usage |
|---|---|
| 0(R1) | Exit call indication. The value of
this byte can be:
|
| 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:
|
| 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. |
| Value | Description |
|---|---|
| R13 | Save area of calling Adabas nucleus routine. |
| R14 | Return address in Adabas nucleus. |
| R15 | Entry point address for exit. |
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.
Adabas Review provides a detailed report user exit that is called when a command log record is selected for the report. Only records that pass the processing rules are provided to the user exit.
This exit may be used to create SMF records, accounting records, or for any other purpose.
To install the user exit:
Specify the name of the user exit when creating the report.
For an online report, enter the exit name in the Exit Name field in the Detail Exit area of the Report Options screen.
When defining batch parameters, specify TYPE=DETAIL and the REPORT-EXIT= keyword of the REPORT statement. Read REPORT Statement in Using Batch Facilities for more information.
Provide the detailed report user exit in an executable library accessible to Adabas Review.
The detailed report user exit receives control using standard linkage:
| R1 | Address of the parameter list |
| R13 | 18 fullword savearea address |
| R14 | Return address |
| R15 | Entry-point address of the user exit |
The parameter list contains two entries:
| 0(R1) | Reserved for future use |
| 4(R1) | Address of the command log record |
Adabas Review writes to command, summary, and raw log files in sequential order. When a log file is filled, Adabas Review closes the file, switches to the next sequential file, and continues logging. The following messages are issued: REV20151 and REV20152. No check is actually performed to determine whether the log file is empty, and REV20152 is displayed in all cases.
When all files have been filled, Adabas Review switches back to the oldest file to log data. Adabas Review will write over the log data in the file containing the oldest data. Therefore, it is the responsibility of the customer to copy the data before this overwrite can occur.
A command, summary, or raw logging user exit can be specified so that the data contained in the log files can be copied to a new file before the log file is overwritten with new log data. This user exit is called each time a log file is opened or closed, but it is only called if you reference the user exit name in the User Exit (command logs), Log Full Exit (summary logs), or Switch Exit (raw logs) report logging option. So the user exit can be called before any data has been written to the log files at all. For more information about these logging options, read Logging Options.
The source library member REVUXLOG contains sample code for the user exit that processes log files. Copy and modify your copy of the sample to create your own user exit, with its own unique name. Then include the exit name in the User Exit (command logs), Log Full Exit (summary logs), or Switch Exit (raw logs) logging option on the Report Options screen of your report definition.
When the sample user exit is called, it starts the log copy job. The JCL library member REVCLCOP contains a sample log copy job. This job copies the contents of a filled log file to another device. This job also reinitializes the end-of-file marker in the log file
Copy and modify your copy of the sample job provided to create your own copy job, with its own unique name.
Adabas Review provides a summary report user exit that is called whenever:
A specified Adabas command is selected for the report
A report is summarized.
A report is summarized when it is:
Closed or purged from the LS screen;
Closed by an interval event;
Deactivated because the MAXSTORE limit was exceeded; or
Running when Adabas Review is terminated.
You may control the conditions that trigger the exit.
A report calling a summary exit is limited to one account (Order) field. If a summary report exit is specified and the report has multiple account fields, syntax error message REV00408 is issued.
To install the user exit:
Specify the name of the user exit when creating the report.
For an online report, enter the exit name in the Exit Name field in the Summary Exit area of the Report Options screen.
To control the conditions that drive the exit, the Report Options screen allows you to enter an Adabas command (Cmd field) and specify whether to call the exit at summarization time (Sum field). If the Adabas command field is left blank, the exit is only called when the report is summarized. If SUM is set to "N" and the Adabas command field is blank, the exit is never called.
When defining batch parameters, specify TYPE=SUMMARY and the SUMMARY-EXIT= keyword of the REPORT statement. Read about the REPORT Statement in Using Batch Facilities for more information.
Provide the summary report user exit in an executable library accessible to Adabas Review.
The summary report user exit receives control using standard linkage:
| R1 | Address of the parameter list |
| R13 | 18 fullword savearea address |
| R14 | Return address |
| R15 | Entry-point address of the user exit / Return code upon return |
The parameter list contains the following entries:
| Offset | Address of . . . | |||||
|---|---|---|---|---|---|---|
| 0(R1) | the reason for being called. This is a one-byte binary bit map. | |||||
|
||||||
| 4(R1) | the Adabas command. This is a two-byte character field. If the exit was called with X'80', the field indicates the Adabas command that is used as a trigger. | |||||
| 8(R1) | the report name. This is a 32-byte character field. | |||||
| 12(R1) | the summary record. | |||||
| 20(R1) | the command log record. |
The summary record is a variable length record that contains the field names and values for the report. It has a fixed portion and a variable portion.
Note:
The layout of the summary exit record is different from the
layout of the summary record written to the summary log file.
Here is the summary exit record layout:
************************************************************
* FIXED PORTION OF SUMMARY RECORD *
************************************************************
RECLEN DS H TOTAL RECORD LENGTH (INCLUSIVE)
DS H UNUSED
SUMCOUNT DS H NUMBER OF SUMMARY ENTRIES
SOFFSET DS H OFFSET OF SUMMARY PORTION
ACCLEN DS H LENGTH OF ACCOUNT DATA
ACCTNAME DS CL8 NAME OF ACCOUNT FIELD
*
************************************************************
* VARIABLE PORTION OF SUMMARY RECORD *
************************************************************
ACCTDATA DS 0CL1 START OF ACCOUNT DATA
ACCTPAD DS 0CL1 PADS OUT TO DOUBLEWORD
SUMFLD DS 0CL8 NAME OF SUMMARY FIELD
SUMVAL DS 0XL8 VALUE OF SUMMARY FIELD
The exit is called for each account entry (Order Field) in the report.
The last two fields above repeat for each summary field in the report.
All fields names are 8-byte character fields.
All summary data values are 8-byte binary fields.
The ACCTDATA field above always starts at the same offset, but its length is variable.
Upon returning from the exit, the user is responsible for setting a return code in R15:
| R15 = 0 | A zero return code indicates a normal return. |
| R15 # 0 | A nonzero return codes indicates that the user requested the system to zero all summary data for this account entry. |