DB2 Server for VM: System Administration

Supplying Account Numbers for Users

There is no rigid format for entering account or project numbers into accounting records, because their definition and use vary at each installation. (Some installations do not use account numbers at all.) Thus, you must devise your own scheme.

To do this, you replace a module named ARIUXIT with your own version of that module.
Note:The ARIUXIT accounting exit is not called in a DRDA protocol environment.

The resource adapter calls ARIUXIT when a user tries to connect to a DB2 Server for VM application server either implicitly or explicitly. The database manager branches to ARIUXIT even before attempting to verify the user.

The database manager allows ARIUXIT to access a control block. In this control block, ARIUXIT can provide up to 16 bytes of data.

Before calling ARIUXIT, the database manager initializes the 16-byte area. For batch/ICCF applications, the database manager initializes the area to character blanks.

The ARIUXIT module does not use the control block (except for the return code area); it only sets a no-operation return code and branches back to the database manager, as shown in the following figure.

Figure 109. The Database Manager Branching to ARIUXIT


REQTEXT

Because of this, the database manager places blanks in the installation-dependent field of the user's accounting records. Whatever data is in the 16-byte area is placed on the accounting records of the user who was trying to connect at the time that ARIUXIT was called.

Your version of ARIUXIT should determine the user's accounting information for your installation, verify it, and pass it to database manager which puts it in the user's accounting records. You can supply department names as well as account or project numbers. You can, in fact, supply whatever you like so long as it fits in 16 bytes and meets your own installation's requirements. The database manager does no error-checking on the data.

The database manager always branches to ARIUXIT in a non-DRDA protocol environment, regardless of whether the connect attempt is from a program, the DBS utility, the preprocessors, or ISQL. You cannot disable branching. If you want to be able to bypass your accounting routine, you have to code the routine so that you can turn it on and off.

How the ARIUXIT Module Works

The resource adapter is the component of the database manager that calls ARIUXIT. In multiple user mode, the resource adapter is in the user machine; in single user mode, it is in the database machine. The ARIUXIT module is called in both modes.

The resource adapter calls ARIUXIT in AMODE(31).

When the resource adapter detects any attempt to connect to an application server, it builds a parameter list for ARIUXIT, sets registers for a proper linkage, and calls ARIUXIT. It always calls ARIUXIT, even if the accounting facility is not enabled. The registers are set as follows:

Register 1
The address of the start of the parameter list for ARIUXIT. The parameter list itself is named ARIUEXI. The pointer to the parameter list points to the beginning of ARIUEXI, which is described below. The first field in ARIUEXI is an eye-catcher value.

Register 13
Points to a standard register save area.

Register 14
Contains the return address.

Register 15
Contains the entry point of the installation exit routine.

You must code ARIUXIT to save the DB2 Server for VM registers in the area pointed to by Register 13. If ARIUXIT does not save and restore the registers, the results will be unpredictable.

The resource adapter also builds the parameter list named ARIUEXI. Table 25 shows what is in ARIUEXI.

Table 25. ARIUEXI Parameter List
Length Description

2 words
1 word
Eye-catcher: 'ARIUEXI '
Length of ARIUEXI parameter list


1 word
1 word
Pointer to Exit Number
Pointer to length of Exit Number


1 word
1 word
Pointer to Exit Global Area
Pointer to length of Exit Global Area


1 word
1 word
Pointer to Exit Local User Area
Pointer to length of Exit Local User Area


1 word
1 word
Pointer to Exit Unique Area
Pointer to length of Exit Unique Area

2 words Reserved

1 word
1 word
Pointer to Environment Dependent Area
Pointer to length of Environment Dependent Area


1 word
1 word
Pointer to Exit Return Code Area
Pointer to length of Exit Return Code Area

Each area that ARIUEXI points to is described below.

Eye-catcher and Length of List
The resource adapter sets the eye-catcher field to 'ARIUEXI ' and the following full word to the length of the entire list. (This length includes the length of the eye-catcher field.)

Exit Number
The exit number is always a full word. The exit number for the accounting exit is 1. The resource adapter sets the pointer to the exit number with an address to a full word area containing a binary 1. The resource adapter sets the pointer to the length of the exit number with the address of a full word area containing a binary 4.

Exit Global Area
This area does not apply to the accounting exit. The resource adapter sets both the pointer to the global area and the pointer to the length of the global area to binary zeros.

Exit Local User Area
The local user area is 16 bytes long. It is a read/write area that lasts for the life of the user program. For CMS applications, the area exists until the end of the CMS command.

For each user, the resource adapter obtains the 16-byte storage area and sets it to binary zeros. The pointer to the local user area is unique for each user. On subsequent calls by the user, the resource adapter returns the same pointer; it never resets the area.

The pointer to the length of the local user area always points to a full word that contains a binary 16.

Exit Unique Area
In this area, you provide the installation-dependent accounting information. This area is also 16 bytes long. The resource adapter initializes the field to character blanks. In the VM/ESA operating system, the first four bytes of this area contain the CMS work unit ID. The accounting exit

writes over these first four bytes unless you modify it.

The pointer to the length of the area points to a full word that contains binary 16.

Reserved Area
This area is 8 bytes long and reserved. The resource adapter initializes it to binary zeros.

Environment-Dependent Area
This area is 40 bytes long. It contains information about the environment where the user is running.
Note:Some fields apply only to VSE uses of the database manager. For VM, those fields are set to binary zeros or character blanks.

The resource adapter initializes the environment-dependent area as follows:

Byte 1
Character S for single user mode, or M for multiple user mode.

Byte 2
Character V for VM.

Byte 3
Character blank for VM.

Byte 4
Character I for implicit connect, or E for explicit connect.

Bytes 5--8
Binary zeros.

Bytes 9--12
Binary zeros.

Bytes 13--20
Database name.

Bytes 21--28
CONNECT user ID for all explicit connections. Blanks for implicit connections.

Bytes 29--36
Character blanks.

Bytes 37--40
Binary zeros (reserved).

For implicit connections, you can use the CP DIAGNOSE instruction X'00' to obtain the VM user ID. (The VM user ID is used as the DB2 Server for VM user ID for implicit connections.)

Exit Return Code Area
The resource adapter initializes this full word area (and the pointer to it), and sets it to -1. A return code of -1 means that you do not want this exit. The length field for this area is a full word containing a binary 4. The resource adapter also ORs a X'80' to the high order byte of the pointer to the length field of the return code area. The X'80' indicates the end of the parameter list.

When you code your version of ARIUXIT, you can specify these return codes before branching back to the database manager:

-1
Means that you do not want this exit (the default). This indicates to the database manager that the exit is a no-op.

0
The function that the exit called to do a task completed successfully.

Other
Any return code other than 0 or -1 causes an -815 SQLCODE to be returned to the user. (SQLERRD1 contains the return code from the exit.) You can reject a user's attempt to connect because the user has incorrect accounting information.

Figure 110 summarizes the ARIUEXI parameter list and the areas pointed to by the list.

Figure 110. Summary of ARIUEXI Parameter List and Associated Areas

REQTEXT

Coding Your Own Accounting Exit

Exit routines must always be coded in Assembler language. Your version of ARIUXIT (and any of the modules it calls) must not use any DB2 Server for VM function.

Figure 111 shows the ARIUXIT module that is included with the database manager. This sample exit routine is on the service disk. Its file name and file type are ARIUXIT MACRO. Note that the Exit Return Code Area is set to -1, which means that you are not interested.

Figure 111. IBM-Supplied Version of ARIUXIT

 
          TITLE 'ARIUXIT'
***********************************************************************
* ARIUXIT USER EXIT ROUTER ROUTINE                                    *
*     REGISTER ASSUMPTIONS:                                           *
*         R1  -> PARMLIST                                             *
*         R13 -> SAVE AREA                                            *
*         R14 -> RETURN ADDRESS                                       *
*         R15 -> ENTRY POINT                                          *
*                                                                     *
* ALTHOUGH PROVIDED IN A GENERAL INTERFACE LIBRARY, ARIUXIT IS NOT TO *
* BE USED AS A GENERAL PROGRAMMING INTERFACE.  REFER TO PRODUCT       *
* DOCUMENTATION TO DETERMINE INTENDED USAGE.                          *
*                                                                     *
***********************************************************************
         SPACE 5
ARIUXIT  CSECT ,
ARIUXIT  AMODE ANY
ARIUXIT  RMODE 24
         DS    0H
         USING *,R15               GET ADDRESSABILITY
         B     PROLOG
         DC    CL8'ARIUXIT '       EYECATCHER
*
PROLOG   EQU   *
         STM   R14,R12,12(R13)     SAVE CALLER'S REGISTERS
         DROP  R15
         BALR  R12,0               R12 IS BASE REGISTER
*
PSTART   EQU   *
         USING PSTART,R12          GET ADDRESSABILITY FOR ROUTINE
         ST    R13,UXSAVE+4        STORE BACKWARD POINTER
         LA    R9,UXSAVE           ADDRESS OF SAVE AREA
         ST    R9,UXSAVE+8         STORE FORWARD POINTER
         LR    R13,R9              R13 POINTS TO NEW SAVE AREA
         L     R1,0(,R1)           GET POINTER TO PLIST
         USING PLIST,R1            GET ADDRESSABILITY TO PLIST DSECT
*
*  Insert your own code here
*  (and change the return code as appropriate).
*

 
         L     R2,PLRETCD          GET PTR TO EXIT RETURN CODE AREA
         L     R3,NEG1RC           LOAD NOOP RET CODE (NEGATIVE ONE)
*
         ST    R3,0(,R2)           STORE RET CODE INTO EXIT RC AREA
*
         L     R13,UXSAVE+4        GET BACKWARD POINTER
         LM    R14,R12,12(R13)     RESTORE CALLER'S REGISTERS
         BR    R14                 RETURN TO CALLER
*
END      EQU   *
         EJECT
***********************************************************************
*
*        DECLARES FOR ARIUXIT ROUTER
*
***********************************************************************
         SPACE 5
UXSAVE   DC    18F'0'         SAVE AREA FOR CALLER'S REGISTERS
NEG1RC   DC    F'-1'          NEGATIVE ONE RETURN CODE (NO-OP)
         SPACE 2
R0       EQU   0              REGISTERS EQUATES
R1       EQU   1
R2       EQU   2
R3       EQU   3
R4       EQU   4
R5       EQU   5
R6       EQU   6
R7       EQU   7
R8       EQU   8
R9       EQU   9
R10      EQU   10
R11      EQU   11
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15
         EJECT

 
***********************************************************************
*
*        DSECT FOR ARIUEXI PARAMETER LIST INTERFACE TO ARIUXIT ROUTER
*
***********************************************************************
         SPACE 5
         DS    0D
PLIST    DSECT
PLICTCH  DS    CL8            EYECATCHER
PLILENG  DS    F              LENGTH OF PLIST (INCLUDING EYECATCHER)
PLEXNUM  DS    F              PTR TO EXIT NUMBER
PLLXNUM  DS    F              PTR TO LENGTH OF EXIT NUMBER
PLGLOBA  DS    F              PTR TO EXIT GLOBAL AREA
PLLGLOB  DS    F              PTR TO LENGTH OF EXIT GLOBAL AREA
PLUSERF  DS    F              PTR TO EXIT LOCAL USER AREA
PLLUSER  DS    F              PTR TO LENGTH OF EXIT LOCAL USER AREA
PLEUNIQ  DS    F              PTR TO EXIT UNIQUE AREA
PLLUNIQ  DS    F              PTR TO LENGTH OF EXIT UNIQUE AREA
         DS    CL8            RESERVED
PLEDEPA  DS    F              PTR TO ENVIRONMENT DEPENDENT AREA
PLLDEPA  DS    F              PTR TO LENGTH OF ENVIRONMENT DEP AREA
PLRETCD  DS    F              PTR TO EXIT RETURN CODE AREA
PLLRETC  DS    F              PTR TO LENGTH OF EXIT RETURN CODE AREA
*
         END


Figure 112 shows a simple example of a user version of ARIUXIT. In this example, the string HERE IS USERDATA is moved into the exit unique area, and the exit return code area is set to 0.

Figure 112. Sample User Version of ARIUXIT

 
          TITLE 'ARIUXIT'
***********************************************************************
* ARIUXIT USER EXIT ROUTER ROUTINE                                    *
*     REGISTER ASSUMPTIONS:                                           *
*         R1  -> PARMLIST                                             *
*         R13 -> SAVE AREA                                            *
*         R14 -> RETURN ADDRESS                                       *
*         R15 -> ENTRY POINT                                          *
*                                                                     *
* ALTHOUGH PROVIDED IN A GENERAL INTERFACE LIBRARY, ARIUXIT IS NOT TO *
* BE USED AS A GENERAL PROGRAMMING INTERFACE.  REFER TO PRODUCT       *
* DOCUMENTATION TO DETERMINE INTENDED USAGE.                          *
*                                                                     *
***********************************************************************
         SPACE 5
ARIUXIT  CSECT ,
ARIUXIT  AMODE ANY
ARIUXIT  RMODE 24
         DS    0H
         USING *,R15               GET ADDRESSABILITY
         B     PROLOG
         DC    CL8'ARIUXIT '       EYECATCHER
*
PROLOG   EQU   *
         STM   R14,R12,12(R13)     SAVE CALLER'S REGISTERS
         DROP  R15
         BALR  R12,0               R12 IS BASE REGISTER
*
PSTART   EQU   *
         USING PSTART,R12          GET ADDRESSABILITY FOR ROUTINE
         ST    R13,UXSAVE+4        STORE BACKWARD POINTER
         LA    R9,UXSAVE           ADDRESS OF SAVE AREA
         ST    R9,UXSAVE+8         STORE FORWARD POINTER
         LR    R13,R9              R13 POINTS TO NEW SAVE AREA
         L     R1,0(,R1)           GET POINTER TO PLIST
         USING PLIST,R1            GET ADDRESSABILITY TO PLIST DSECT

 
*
* Here you would place code that gets and verifies your
* user-dependent data.  The following code shows moving the data
* into the Exit Unique Area.
*
* Make sure you check the Exit Number word.  If the Exit Number value
* is not a binary 1, you should set the Exit Return Code word to binary
* -1 (NEG1RC) and return to the database manager.
*
         L     R2,PLEUNIQ          GET PTR TO EXIT UNIQUE AREA
         MVC   0(16,R2),USERDATA   MOVE 16 BYTES OF USER DATA
         L     R2,PLRETCD          GET PTR TO EXIT RETURN CODE AREA
         L     R3,ZEROS            SET ZERO RETURN CODE
         ST    R3,0(,R2)           STORE RET CODE INTO EXIT RC AREA
*
EXIT     EQU   *                   RETURN TO THE DATABASE MANAGER
         L     R13,UXSAVE+4        GET BACKWARD POINTER
         LM    R14,R12,12(R13)     RESTORE CALLER'S REGISTERS
         BR    R14                 RETURN TO CALLER
*
END      EQU   *
         EJECT
 
***********************************************************************
*
*        DECLARES FOR ARIUXIT
*
***********************************************************************
         SPACE 5
UXSAVE   DC    18F'0'         SAVE AREA FOR CALLER'S REGISTERS
ZEROS    DC    F'0'           ZERO RETURN CODE
NEG1RC   DC    F'-1'          NEGATIVE RETURN CODE (NO-OP)
USERDATA DC    CL16'HERE IS USERDATA'
         SPACE 2
R0       EQU   0              REGISTERS EQUATES
R1       EQU   1
R2       EQU   2
R3       EQU   3
R4       EQU   4
R5       EQU   5
R6       EQU   6
R7       EQU   7
R8       EQU   8
R9       EQU   9
R10      EQU   10
R11      EQU   11
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15
         EJECT

 
***********************************************************************
*
*        DSECT FOR ARIUEXI PARAMETER LIST INTERFACE TO ARIUXIT
*
***********************************************************************
         SPACE 5
         DS    0D
PLIST    DSECT
PLICTCH  DS    CL8            EYE-CATCHER
PLILENG  DS    F              LENGTH OF PLIST (INCLUDING EYE-CATCHER)
PLEXNUM  DS    F              PTR TO EXIT NUMBER
PLLXNUM  DS    F              PTR TO LENGTH OF EXIT NUMBER
PLGLOBA  DS    F              PTR TO EXIT GLOBAL AREA
PLLGLOB  DS    F              PTR TO LENGTH OF EXIT GLOBAL AREA
PLUSERF  DS    F              PTR TO EXIT LOCAL USER AREA
PLLUSER  DS    F              PTR TO LENGTH OF EXIT LOCAL USER AREA
PLEUNIQ  DS    F              PTR TO EXIT UNIQUE AREA
PLLUNIQ  DS    F              PTR TO LENGTH OF EXIT UNIQUE AREA
         DS    CL8            RESERVED
PLEDEPA  DS    F              PTR TO ENVIRONMENT DEPENDENT AREA
PLLDEPA  DS    F              PTR TO LENGTH OF ENVIRONMENT DEP AREA
PLRETCD  DS    F              PTR TO EXIT RETURN CODE AREA
PLLRETC  DS    F              PTR TO LENGTH OF EXIT RETURN CODE AREA
*
         END

After the program is coded, assemble it as you would any other program.

Installing Your Version of ARIUXIT

During customization of DB2 Server for VM, you may have to modify TEXT files that are serviced as full part replacement (for example, for user exits, such as ARIUXIT). The source is shipped as a MACRO file.

Use the following steps to create and build the affected objects with the new parts. These steps use the VMSES/E local modification procedure.

Step 1. Stop the Application Server

Stop the application server using your normal operating procedures.

Step 2. Log on to the Installation or Service User ID

Log on to the installation or service user ID, 5697F42S.

Step 3. Establish the Minidisk or SFS Directory Order

Establish the access order. 

vmfsetup 5697F42S {DB2VM|DB2VMSFS}

Use DB2VM for installing on minidisks or DB2VMSFS for installing in Shared File System directories.

If you have your own PPF override, then substitute that name for the 5697F42S name shown in this command and any following commands.

Step 4. Copy the MACRO Source Code (First Time Only)

Copy the MACRO source code to the local modification disk as ASSEMBLE. This only needs to be done the first time you apply local modifications to this part; otherwise, you will delete your version of the ASSEMBLE file. 

vmfrepl ariuxit macro 5697F42S {DB2VM|DB2VMSFS}
  (filetype assemble outmode localsam

Use DB2VM for installing on minidisks or DB2VMSFS for installing in Shared File System directories.

Step 5. Edit the ASSEMBLE File

Edit ARIUXIT ASSEMBLE file on the local modification disk (2C2) and make your changes.

Step 6. Update the Local Version Vector Table

Update the local version vector table for the assembled TEXT file. 

vmfrepl ariuxit text 5697F42S {DB2VM|DB2VMSFS}
  (logmod modid nocopy

Use DB2VM for installing on minidisks or DB2VMSFS for installing in Shared File System directories.

modid is the new local modification identifier for the part (for example, L0001).

Step 7. Assemble the File

Use the VMFHLASM command to assemble ARIUXIT. 

vmfhlasm ariuxit 5697F42S {DB2VM|DB2VMSFS}
  (nockgen $select outmode localsam

Use DB2VM for installing on minidisks or DB2VMSFS for installing in Shared File System directories.

Notes:

  1. Other options are available for the assemble commands. Consult the VM/ESA: VMSES/E Introduction and Reference for additional information.

  2. We recommend that you use the VMFHLASM command supplied by VMSES/E. Also available are the VMFHASM and VMFASM commands.

  3. If the assemble function is successful, the ARIUXIT TXTLnnnn file is placed on the LOCALSAM 2C2(E) disk.

Step 8. Build your New Local Modification

Build your new local modification on the test build disks. 

vmfbld ppf 5697F42S {DB2VM|DB2VMSFS} (status
vmfbld ppf 5697F42S {DB2VM|DB2VMSFS} (serviced

Use DB2VM for installing on minidisks or DB2VMSFS for installing in Shared File System directories.

After you issue the VMFBLD command with the STATUS option, use the VMFVIEW BUILD command to view the $VMFBLD $MSGLOG file to see which objects will be built.

Step 9. Place the New Local Modification into Production

Use ARISINST to place the new local modification into production. 

arisinst c 5697F42S {DB2VM|DB2VMSFS}

Use DB2VM for installing on minidisks or DB2VMSFS for installing in Shared File System directories.

The C function of ARISINST copies the test service and production build disks to the SQLMACH production service and production build disks.

Step 10. Restart the Application Server

Restart the applicaton server in multiple user mode with the required PROTOCOL parameter.

Service Considerations for ARIUXIT

The dummy version of ARIUXIT is not serviceable; other portions of the DSC component, however, are serviceable. If service is applied to any portion of DSC, it is link-edited again. If you have coded your own version of ARIUXIT and completed the previous steps, your version of ARIUXIT will be included in the DSC component.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]