This document describes the user exits provided with Adabas Review.
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 32-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.
Note:
It is possible to use any user field, but the RDBLKUSR user field
name cannot be changed; it is reserved for use with REVUEX1. In addition, you
might find it necessary to modify the Adabas Review DDM if you want to view this field
on line. For more information, read Defining Adabas Review User
Fields.
Important:
If an ADALNK batch link routine has been modified to
accommodate the needs of an Adabas product extension (such as Adabas Review),
it should not be used for the Adabas nucleus or Adabas utility jobs.
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.
Assemble REVUEX1. A sample assembly job for the user exit, AREVUEX1, is provided in the Adabas Review jobs (JOBS) library.
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. Thirty-two (32) 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=USERFLD1 LEN=32 INTYPE=C OUTTYPE=C FIELD=RDBLKUSR DISPLEN=32 HEADER=RDBLKUSR
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 and summary 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 data set 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 or summary logging user exit can be specified so that the data contained in the command or summary log files can be copied to a new file before the log file is overwritten with new log data. This user exit will be called each time a command or summary log file is closed, but it is only called if you reference it in the User Exit (command logs) or Log Full Exit (summary logs) report logging option. For more information about these logging options, read Logging Options.
The source library member REVUXLOG contains sample code for the user exit that processes command or summary 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 (command logs) or Log Full Exit (summary logs) logging option on the Report Options screen of your report definition.
When a command or summary log file is closed, the user exit starts the command or summary log copy job. The z/OS JCL or z/VSE JCS library member REVCLCOP or REVCLCOP.X contain a sample log copy job. This job copies the contents of a filled command or 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 command or summary log file.
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. |