Version 4.6.2
 —  Adabas Review Reference  —

User Exit Reference

This document describes the user exits provided with Adabas Review.


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.

Top of page

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

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.

  2. Assemble REVUEX1. A sample assembly job for the user exit, AREVUEX1, is provided in the Adabas Review jobs (JOBS) library.

  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. Thirty-two (32) 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=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).

Top of page

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:

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

Top of page

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

Top of page

REVUXLOG: Command or Summary Logging User Exit

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.

Installation Steps

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.

REVCLCOP Sample Copy Job

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.

Top of page

REVUXSUM: Report Exit for Summary Reports

Adabas Review provides a summary report user exit that is called whenever:

A report is summarized when it is:

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.

Top of page