The ADABAS Interface User Exit Routine

The ADABAS Interface › The ADABAS Interface User Exit Routine

The ADABAS Interface User Exit Routine

In order to accommodate installation-dependent requirements not supported by the standard ADABAS Interface, provision has been made for you to supply an exit routine, written in Assembler, to augment or modify actions normally taken. A sample routine upon which you can base your version of the exit is provided in the CAJRSAMP.

The name of the exit routine load module must be ADAEXIT. It must reside in one of the following libraries:

SYS1.LINKLIB
The library in which the ADABAS Interface resides, as indicated by the STEPLIB DD statement
A library concatenated to the library corresponding to STEPLIB

If ADAEXIT is not available, the ADABAS Interface processes the command log file as described earlier in this chapter.

The ADABAS Interface gives control to ADAEXIT after each sorted ADABAS command log record has been read and the following actions have been performed:

The record's start and stop dates and times have been converted to an internally meaningful representation.
The concatenated string of user-specified keys has been built for the record.
The estimated CPU time and number of instructions, based on the record's command code and Software AG's SAGTIP009, has been computed.

ADAEXIT is invoked according to standard linkage conventions with the following registers set:

Register	Description
13	Address of calling program's register save area
14	Return address of calling program
15	ADAEXIT's entry point address
1	Address of the parameter list passed to ADAEXIT

The parameter list passed to ADAEXIT has the following format:

Word	Description
1	Address of the command log record currently being processed by the ADABAS Interface
2	Address of a eight-character area in which your version of the terminal/user ID may be placed (the high-order byte of this word is set to x'80' to denote the end of the parameter list)

Upon entry to ADAEXIT, the contents of the field pointed to by word 2 of the parameter list contains one of the following:

blanks for Version 4 format records if there was no match between the job name (LOGJNAME) in the command log record and any of TPNAMES specified by you in the QENVR macro. For Version 5 format records, the contents of LOGUSER will always be present.
a printable numeric terminal/user ID, if there was a match, and Version 4 format records are printed. This is derived by considering the low-order two bytes of LOGPHUID in the command log record as a binary number, converting it to decimal, unpacking it, and ORing the rightmost byte with x'F0'. If processing Version 5 format records, it will contain an eight-byte userid field from the ADABAS log record field, LOGUSER.

In either case, you are free to examine and/or modify any of the original fields in the ADABAS command log record which is accessible via word 1 of the parameter list. You may also supply your own version of the eight-character terminal/user ID in the field pointed to by word 2. Upon return to the ADABAS Interface, your version of the terminal/user ID is initially moved to an internal summary record and eventually to the CA JARS history record, provided the return code in Register 15 is zero.

A zero in Register 15 upon return to the ADABAS Interface indicates that certain fields in the current ADABAS command log record are to be added to corresponding fields in what will eventually be the summarized history record. These include the following:

ADABAS Log Entry	Description

LOGDUR	Duration
LOGNECBS	Number of posted ECBs
LOGNUPDS	Number of descriptors updated
LOGASSOI	Number of associator I/Os
LOGDATAI	Number of data I/Os
LOGWORKI	Number of work I/Os
Total I/O count = LOGASSOI + LOGDATAI + LOGWORKI

Minimum start and maximum end dates and times are adjusted, if necessary, and various alphanumeric fields (such as job name, terminal/user ID, command code, and file number) are placed in their respective slots in a temporary summary record. The counter denoting the number of ADABAS command log records accumulated in the current history record is increased by one, another sorted ADABAS command log record is read, and the process above is repeated. The factors contributing to the elapsed and estimated CPU times are accumulated internally and are calculated just before the history record is written.

If the user exit has determined that the current command log record is to be excluded from further processing by the ADABAS Interface (that is, current record's values are not to be accumulated), a nonzero value must be placed in Register 15 before returning. This being the case, the internal counter denoting the number of user-rejected records is increased by one, the next sorted ADABAS command log record is read, and the above process is repeated.

A sample user exit is provided on the following pages, and as member ADAEXIT in CAJRSAMP.

ADAEXIT  CSECT
         USING *,15              USE R15 AS BASE REGISTER TEMPORARILY
         B     ENTRY             BRANCH AROUND EYE-CATCHER
*
         DC    C'ADAEXIT-1.0-
&SYSDATE-.&SYSTIME'.            EYE-CATCHER
*
*   ENTRY LOGIC
*
ENTRY    DS    0H
         STM   14,12,12(13)      SAVE CALLER'S REGISTERS
*                                SET UP BASE REGISTER
         DROP  15                  RELEASE TEMPORARY BASE REGISTER
         LR    11,15               LOAD WITH ENTRY ADDRESS
         USING ADAEXIT,11          USE IT AS ADAEXIT'S BASE REGISTER
*                                CHAIN SAVE AREAS (STANDARD LINKAGE)
         ST    13,SAVEAREA+4       BACKWARD LINK IN ADAEXIT'S SAVEAREA
         LR    10,13               R10 = A(CALLER'S SAVEAREA)
         LA    13,SAVEAREA         R13 = A(ADAEXIT'S SAVEAREA)
         ST    13,8(,10)           FORWARD LINK IN CALLER'S SAVEAREA
*                                GET ADDRESSABILITY TO PASSED PARMS
         USING ADALOG,9            R 9 = A(ADABAS LOG RECORD)
         LM    9,10,0(1)           R10 = A(USERID FIELD)
         LA    10,0(,10)           CLEAR R10'S HIGH BYTE
*
*   NOTE: A NON-ZERO VALUE IN R15 UPON RETURN WILL CAUSE THE CURRENT
*         ADABAS LOG RECORD TO BE EXCLUDED (REJECTED) FROM FURTHER
*         PROCESSING BY THE ADABAS INTERFACE.
*
*                                ASSUME CURRENT RECORD WILL BE ACCEPTED
         SLR   15,15               ZERO RETURN CODE
*
*   PROCESSING LOGIC
*                                CHECK FOR RECORD ACCEPTANCE
         CLC   LOG...,CONSTANT     DO WE WANT TO ACCEPT THIS RECORD ?
         BE    ACCEPT              YES..ON TO FURTHER EXIT PROCESSING
         LA    15,4                NO...SET NON-ZERO RETURN CODE
         B     RESTORE             AND LEAVE
*
ACCEPT   DS    0H                COME HERE IF RECORD WAS ACCEPTED
              .
              .                  USER EXIT PROCESSING
              .
         MVC   0(8,10),USERID      SUPPLY OWN VERSION OF USERID
              .
*
*   RETURN LOGIC
*
RESTORE  DS    0H
         L     13,SAVEAREA+4       RESTORE CALLER'S R13
         L     14,12(,13)          RESTORE CALLER'S R14
         LM    0,12,20(13)         RESTORE CALLER'S R0-R12
         BR    14                  RETURN TO CALLER
*
         DROP  9,11                RELEASE LOG RECORD & BASE REGISTER
         EJECT
*

  *   CONSTANTS AND WORK AREAS
  *
  CONSTANT DC    ...                 RECORD ACCEPTANCE TEST CONSTANT

  USERID   DC    CL8'.....'          USER'S VERSION OF USERID (THIS FIELD
  *                                  MUST BE NO LONGER THAN 8 BYTES)
  SAVEAREA DC    18F'0'              ADAEXIT'S SAVE AREA
           EJECT
  ***********************************************************************
  *                                                                     *
  *        ADABAS LOG RECORD                                            *
  *                                                                     *
  ***********************************************************************
  ADALOG   DSECT                     ADABAS LOG RECORD DSECT
  LOGRTYPE DS    H                          RECORD TYPE
  LORVERS  DS    XL2                        VERSION C'52'
  TLOFTIMI DS    XL8                        STCK
  TLOXRTYP DS    XL1                        BUFFER TYPES
  LOGPRTY  DS    X                          DISPATCHING PRIORITY
  LOGCTYPE DS    X                          COMMAND TYPE
  LOGNECBS DS    X                          # POSTED ECB'S
  LOGTHDNR DS    X                          THREAD NUMBER
  LOGBUF   DS    X                          USER BUFFER FLAG
  LOGNUPDS DS    H                          # DESCRIPTORS UPDATED
  LOGJNAME DS    CL8                        JOB NAME
  LORCOMID DS    0CL28                      COMMUNICATION ID
  LORCPUID DS    XL8                        CPUID
  LORVMID  DS    XL8                        VMID
  LOROSID  DS    XL4                        OS ID
  TLOXUSID DS    CL8                        USER ID
  LOGDUR   DS    F                          DURATION           (16MS FMT)
  LORSEQNR DS    F                          UNIQUE COMMAND SEQUENCE
  LORDBID  DS    H                          DATABASE ID
  LORNIOS  DS    0H
  LOGASSIO DS    H                          # ASSOCIATOR IO'S
  LOGDATAI DS    H                          # DATA IO'S
  LOGWORKI DS    H                          # WORK IO'S
  LOGSIBAI DS    H                          # SIBA IO'S
  LORARCH  DS    XL1                        ARCH TYPE
  LORESV1  DS    XL3                        RESERVED FIELD
  LORREV   DS    F                          REVIEW
  LORNUCID DS    H                          SMP / ADAPLEX ID
  LORRESV2 DS    H                          RESERVED
  LORACB   DS    0XL80                      ADABASE CONTROL BLOCK
  LORESV3  DS    CL2                        RESERVED
  LOGCMD   DS    CL2                        COMMAND CODE
  LOGCID   DS    CL4                        COMMAND ID
  LOGFNR   DS    XL2                        FILE NUMBER
  LOGRSP   DS    XL2                        RESPONSE CODE
  TLOFISN  DS    XL4                        ISN
  LOGISL   DS    XL4                        ISN LOWER LIMIT
  LOGISQ   DS    XL4                        ISN QUANTITY
  LOGFBL   DS    XL2                        FORMAT BUFFER LENGTH
  LOGRBL   DS    XL2                        RECORD BUFFER LENGTH
  LOGSBL   DS    XL2                        SEARCH BUFFER LENGTH
  LOGVBL   DS    XL2                        VALUE BUFFER LENGTH
  LOGIBL   DS    XL2                        ISN BUFFER LENGTH
  LOGOP1C  DS    CL1                        COMMAND OPTIONS 1

LOGOP2C  DS    CL1                        COMMAND OPTIONS 2
LOGAD1   DS    CL8                        ADDITIONS 1 FIELD
LOGAD2C  DS    CL4                        ADDITIONS 2 FIELD
LOGAD3   DS    CL8                        ADDITIONS 3 FIELD
LOGAD4   DS    CL8                        ADDITIONS 4 FIELD
LOGAD5   DS    CL8                        ADDITIONS 5 FIELD
LORCTIM  DS    XL4                        COMMAND TIME
TLOCUSA  DS    XL4                        USER FIELD
LOGQBRL  EQU   *-ADALOG         BASIC RECORD LENTH
*                               CONTROL BLOCK PORTION (RTYP=X'01')
         END