User Exit Reference

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.

P-UEXIT1, P-UEXIT2 and P-UEXIT3: Review Natural User Exits

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: User Field User Exit

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.

Installation Steps

Start of instruction setThe following installation steps must be completed to activate the user field user exit:

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

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

  3. Link REVUEX1 with the Adabas Review ADALNK REVEXIT. A sample job, LREVUEX1, is provided in the Adabas Review jobs (JOBS) library.

  4. 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 Passed to the Exit

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.

Other Register Values at Entry to the Exit

Register Description
13 Save area of calling ADALNK routine
14 Return address to ADALNK routine
15 Entry point address for the user exit

Viewing the User-Specific Data in a Report

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

REVUEX5: Adabas Review Hub Event Handler (Adabas Exit 5)

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.

Input Parameters

On entry, register 1 points to the following parameter list:

graphics/reg1_parmlist.png

Parameter Usage
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 for 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 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

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

REVUXDET: Report Exit for Detailed Reports

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.

Installation Steps

Start of instruction setTo install the user exit:

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

  2. Provide the detailed report user exit in an executable library accessible to Adabas Review.

Input Parameters Passed to the Exit

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

REVUXLOG: Command, Summary, or Raw Logging User Exit

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.

Installation Steps

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.

REVCLCOP Sample Copy Job

When the sample user exit is called, it starts the 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 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.

REVUXSUM: Report Exit for Summary Reports

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.

Installation Steps

Start of instruction setTo install the user exit:

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

  2. Provide the summary report user exit in an executable library accessible to Adabas Review.

Input Parameters Passed to the Exit

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.
X'80' The exit was called because the specified command was selected.
X'40' The exit was called during summary processing.
X'01' If this bit is on in addition to one of the above, it indicates that this is the last account entry for the report.
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.

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

Return Codes

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.