DB2 Server for VSE: 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.

The resource adapter calls ARIUXIT when a user tries to connect to a DB2 Server for VSE 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 105. The Database Manager Branching to ARIUXIT

Because of this, the database manager places blanks (for batch/ICCF) or CICS information (for online applications) in the installation-dependent field of the user's accounting records. If you choose, you can change (write over) this area. 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 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 partition; in single user mode, it is in database partition. The ARIUXIT module is called in both modes.

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 VSE 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 23 shows what is in ARIUEXI.

Table 23. 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 CICS transactions, the area exists for each transaction until the transaction ends
• For batch or VSE/ICCF applications, the area exists until the end of the job step.

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. It is obtained and initialized by the resource adapter. How it is initialized depends on the environment:

• For batch/ICCF applications, it is initialized to character blanks.
• For online CICS transactions, it is initialized as follows:

  Bytes 1--4

  contain the CICS transaction ID.

  Bytes 5--12

  contain the CICS sigon ID, if available.

  Bytes 13--16

  contain the CICS terminal ID, if available. If the transaction does not have a CICS terminal ID and the user coded the ARIRCAN cancel support, the first 4 characters of the RMARUDAT data from the RMAR control block is placed into bytes 13-16. Otherwise, these bytes are blank.

  Note:

  If the user coded the ARIRCAN cancel support, the RMARUDAT data from the RMAR control block is placed into bytes 29-36 of the Environment Dependent area.

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:

This area identifies environment-dependent information. Some fields apply only to VM uses of the database manager. For VSE, those fields are set to 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 D for VSE.

Byte 3

Character B for batch or VSE/ICCF, or O for VSE online.

Byte 4

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

Bytes 5--8

Pointer to CICS transaction control area (TCA) for VSE online. For batch or VSE/ICCF, binary zeros.

Bytes 9--12

Pointer to CICS save area (CSA) for VSE online. For batch or VSE/ICCF, this field is set to binary zeros.

Bytes 13--20

Character blanks.

Bytes 21--28

CONNECT user ID for all explicit connections and all online implicit connections. Blanks for implicit connections.

Bytes 29--36

If the ARIRCAN cancel support is coded, this field is set to RMARUDAT from the RMAR control block. (For more information about the contents of this field, see the description of the Exit Unique Area on page ***.) Otherwise, this field is character blanks.

Bytes 37--40

Binary zeros (reserved).

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 106 summarizes the ARIUEXI parameter list and the areas pointed to by the list.

Figure 106. Summary of ARIUEXI Parameter List and Associated Areas

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 VSE function. In an online environment, imbedded CICS commands (EXEC CICS) are not allowed.

You can link-edit your accounting exit to run in AMODE 24 or 31 by using the AMODE parameter in the PARM field of the EXEC LNKEDT statement. Your accounting exit will be loaded below 16 megabytes and given control according to its AMODE. If the AMODEs of the accounting exit and the database manager differ, the database manager switches AMODEs before transferring control to the accounting exit. For CICS/VSE applications, you MUST link-edit your accounting exit to run in AMODE 31.

Figure 107 shows the ARIUXIT module that is included with the database manager. This sample exit is supplied as an A-type source member named ARIUXIT. Note that the Exit Return Code Area is set to -1, which means that you are not interested.

Figure 107. 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 108 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 108. 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

After assembling your program, you must catalog the ARIUXIT OBJ file into your private sublibrary. (Your assembled version of ARIUXIT must be named ARIUXIT OBJ.) Then link-edit the DB2 Server for VSE component DSC; then stop the application server in order for the change to take effect.

The DSC component, which is described in the DB2 Server for VSE & VM Diagnosis Guide and Reference manual manual, contains the IBM-supplied version of ARIUXIT. The link book name for DSC is ARISLKMD. When doing the link-edit, specify your private sublibrary ahead of the DB2 Server for VSE sublibrary on the LIBDEF statement defining the search order. The link-edit will then replace the IBM-supplied version with your version.

An example of job control to install a user version of ARIUXIT is shown in Figure 109. Here, the ARIUXIT OBJ would be installed in a sublibrary called LIB.SQL, and the DSC component would be replaced in PRD2.DB2710.

Figure 109. Example Job Control to Install ARIUXIT in the Production Library

// JOB INSTALL USER EXIT // LIBDEF *,SEARCH=(LIB.SQL,PRD2.DB2710),CATALOG=PRD2.DB2710 * **************************************************************** * INSTALL ARIUXIT USER EXIT ROUTINE * * **************************************************************** // OPTION CATAL INCLUDE ARISLKMD // EXEC LNKEDT,PARM='MSHP,AMODE=xxx,RMODE=24' /* /&

AMODE (addressing mode) is the attribute of the entry point of the loaded phase, and must be one of the following:

24

The exit is invoked in AMODE 24

31

The exit is invoked in AMODE 31

ANY

The exit is invoked in the caller's addressing mode

Note:

The accounting exit must always be loaded below 16 megabytes (RMODE 24). If you are running DRDA online CICS transactions, the accounting exit cannot be linkedited with AMODE 24.

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.