IEFUAV — User Account Validation Exit

Topics for This Exit Appear as Follows:

Defining the Exit in SMFPRMxx
Controlling the Exit Routine Through the Dynamic Exits Facility
Exit Routine Environment
Exit Recovery
Exit Routine Processing
Programming Considerations
- Macro Instructions and Restrictions
Entry Specifications
- Registers at Entry
- Parameter Descriptions
Return Specifications
- Registers at Exit
Coded Example of the Exit Routine

You can use the IEFUAV installation exit routine to validate the accounting information of users of APPC/MVS transaction programs (TPs).

IEFUAV is invoked:

When the IBM-supplied APPC/MVS transaction scheduler (ASCH) selects a TP for execution and
At the points in TP processing where APPC/MVS could have tailored the accounting information for the TP user. For example, IEFUAV is invoked when APPC/MVS tailors the account number to which resources are charged for that instance of the TP.
The Workload Manager (WLM) component of the base control program is used to create forked/spawned address spaces. In addition to APPC/MVS TPs, the IEFUAV exit now receives control for forked/spawned address spaces.

When the IEFUAV exit receives control for a forked/spawned address space, the TP flag value indicator is set to 1. The jobname in the ASCB is BPXAS, which is the name of the procedure used to start the MVS™ initiator associated with forked/spawned address spaces.

Based on whether the TP user's accounting information is valid, IEFUAV sets a return code to indicate that either:

Processing should continue for the unit of work or
The unit of work is to be cancelled.

IEFUAV also allows you to place a message into a user's APPC/MVS job log. With the message you can provide information to supplement the return code.

For APPC/MVS TPs, IEFUAV is the only exit that allows you to validate accounting information for specific users at execution time. Therefore, it is recommended that you use IEFUAV, instead of IEFUJV (or another exit, such as IEFUJI or IEFUSI), to validate the accounting information of APPC/MVS TPs. Even though IEFUJV is invoked (as part of C/I text processing) during the reading of a TP profile, the user of the TP is not known at that time.

Defining the Exit in SMFPRMxx

To allow the system to invoke IEFUAV, define the exit in the SMF parmlib member (SMFPRMxx). Specify IEFUAV on the EXITS option of the SUBSYS parameter for the ASCH subsystem. If your installation chooses not to define a SUBSYS parameter for ASCH, you can specify IEFUAV on the EXITS option of the SYS parameter.

For more information about coding the EXITS option, see the description of SMFPRMxx in z/OS MVS Initialization and Tuning Reference.

Controlling the Exit Routine Through the Dynamic Exits Facility

IBM® has defined the IEFUAV installation exit to the dynamic exits facility. You can refer to the exit by the name SYS.IEFUAV or SYSyyy.IEFUAV. See the description of the SMFPRMxx parmlib member in z/OS MVS Initialization and Tuning Reference for an explanation of the naming conventions for SMF exit routines. You can use the EXIT statement of the PROGxx parmlib member, the SETPROG EXIT operator command, or the CSVDYNEX macro to control this exit and its exit routines.

To define IEFUAV to the dynamic exits facility, you must specify the exit in both PROGxx and SMFPRMxx. The system does not call the exit if it is defined in PROGxx only. If you do not plan to use the dynamic exits facility for IEFUAV, you need only define this exit in SMFPRMxx.

If you do not associate any exit routines with exit IEFUAV in PROGxx, the system defaults to using the exit routine name that matches the exit name (IEFUAV).

If you associate exit routines with IEFUAV in PROGxx, the system does not use the default exit routine. If you need this exit routine, you should explicitly add it to PROGxx.

You can use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX REQUEST=ADD macro or the ABENDNUM parameter of the SETPROG EXIT operator command to limit the number of times the exit routine abnormally ends before it becomes inactive. An abend is counted when both of the following conditions exist:

The exit routine does not provide recovery, or the exit routine does provide recovery but percolates the error
The system allows a retry; that is, the recovery routine is entered with bit SDWACLUP off.

By default, the system does not disable the exit routine.

Exit Routine Environment

IEFUAV receives control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 1.
In AMODE 31 and runs RMODE ANY.
In the address space of the unit of work being started
With no locks or ENQs held.

Exit Recovery

IBM strongly recommends that you set up an ESTAEX recovery routine to handle errors that might occur during the execution of IEFUAV.

If you do not provide recovery for IEFUAV, or if the exit routine's error percolates beyond its recovery routine, a system recovery routine will get control.

Whether or not the exit routine continues to be invoked depends on the abend processing of the dynamic exits facility.

Exit Routine Processing

The system invokes the IEFUAV exit routine during the processing of an APPC/MVS TP at the points in which the accounting information might have been altered. At these points, an installation can validate the user's accounting information before processing the transaction further. For example, IEFUAV is invoked when a TP issues Get_Transaction because this service allows APPC to tailor the accounting information for the unit of work, such as the account number to which a resource is charged.

When IEFUAV Is Invoked: IEFUAV will get control only for APPC/MVS TPs whose profiles specify TAILOR_ACCOUNT(YES). IEFUAV is invoked once for standard TPs and multiple times for multi-trans TPs, as follows:

For both standard and multi-trans TPs, IEFUAV is invoked when the APPC/MVS transaction scheduler (ASCH) selects a TP for execution. In this case, IEFUAV receives the generic accounting information that is specified in the TP user's RACF® profile.
For multi-trans TPs only, IEFUAV is invoked when the TPs issue calls to the following services:
- Get_Transaction, to obtain the next transaction. IEFUAV receives accounting information derived from the TP user's RACF profile.
- Return_Transaction, to restore the generic "shell" environment that was established when the TP was initialized. IEFUAV receives generic accounting information from the TP user's RACF profile.

For information on creating a TP profile, see z/OS MVS Planning: APPC/MVS Management.

The circumstances under which IEFUAV receives control might impose restrictions on exit routine processing; see macros and restrictions in Programming Considerations for more details.

Using IEFUAV to Validate Account Numbers

Code your IEFUAV routine to check the user's account number against a list of valid installation account numbers.

Using the Exit Function Code: IEFUAV determines why it was invoked by checking the exit function code in Word 3 of the parameter list (pointed to by Register 1). An installation would probably want IEFUAV to perform validation when Word 3 is set to a value of either 1 (generic account number) or 2 (possible account number alteration).

For exit function code 3, IEFUAV can simply return to the caller, as this code indicates the generic account number that IEFUAV already validated during TP initialization (exit function code 1).

See parameter descriptions in Entry Specifications for more information on the exit function codes.

Validating the User's Account Number: IEFUAV receives, as parameters, the accounting information specified on the JOB statement in the TP user's RACF profile. The accounting information appears in a formatted list, and follows the order in which the accounting parameters were specified on the JOB statement. Table 2 shows the format of the accounting information.

After locating the account number field, IEFUAV would typically do these checks:

Is the account number present? A value of 0 in the first byte of the account number field indicates the account number was omitted.
Does the account number have the correct length? A nonzero value in the first byte indicates the length of the account number.
Is the account number valid? IEFUAV can determine this by comparing the account number to a list of valid account numbers.

At the end of its processing, IEFUAV sets a return code that indicates whether processing for this user should continue or be cancelled.

Placing a Message into a User's APPC/MVS Job Log: IEFUAV allows you to place a message into a user's APPC/MVS job log. Through the message, you can provide information to supplement the return code from IEFUAV. On entry, word 5 of the input parameter list points to a two-word area representing a message area. Place the length of the message in the first word. If the length exceeds zero, then the system issues the message that the second word points to regardless of the value returned in register 15. The maximum allowed length is 80.

The second word is the address of an 80-byte buffer; in that buffer, place the message to be issued to the APPC/MVS job log.

Programming Considerations

SMF provides a replaceable module for an unused exit.

If an installation includes an IEFUAV exit routine, the following programming standards must be observed:

IEFUAV must follow standard linkage conventions.
IEFUAV must be reentrant.
IEFUAV cannot access ISAM data sets.

Macro Instructions and Restrictions are as follows.

If you want to issue a WTOR macro from IEFUAV, also issue the WAIT macro with LONG=YES.
You can issue any macros from IEFUAV, including the OPEN and DYNALLOC macros. The circumstances under which IEFUAV receives control, however, determine the results of OPEN and DYNALLOC processing:
- When IEFUAV gets control because the APPC initiator started a standard or multi-trans TP, IEFUAV can open only those data sets specified in the APPC initiator's procedure. If IEFUAV needs access to other data sets, it may dynamically allocate them, which adds those data sets to the APPC initiator's environment. Those data sets will remain available to the APPC initiator unless IEFUAV unallocates them before completing its processing.
- When IEFUAV gets control because a multi-trans TP issued either Get_Transaction or Return_Transaction, IEFUAV can open only those data sets that are specified in the TP's profile. If IEFUAV needs access to other data sets, it may dynamically allocate them, which adds those data sets to the TP's environment. Those data sets will remain available to the TP unless IEFUAV unallocates them before completing its processing.

Entry Specifications

IEFUAV is passed a list of parameter addresses (pointed to in register 1).

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Address of parameter list
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point of IEFUAV

Parameter Descriptions: Register 1 points to a list of addresses. The list is specified in VL format (that is, the last address has its leftmost bit set to 1). The following describes the list of parameters:

Word 1

Address of the common exit parameter area. For details, see Common Exit Parameter Area.

Word 2

Address of a 20-byte area containing the programmer's name (in EBCDIC). This area is aligned left and padded with blanks if necessary.

Word 3

Address of a 1-byte area that contains a value (binary). The value indicates one of the following conditions:

Exit Function Code: Condition
0: This code is reserved, and no action is taken.
1: For both standard and multi-trans TPs, this code indicates that IEFUAV has received control during the initialization of a TP. The exit receives generic, installation-supplied accounting information from the TP user's RACF profile (in the area pointed to by Word 4).
2: For multi-trans TPs, this code indicates that accounting information might have been altered. The exit receives accounting information from the TP user's RACF profile (in the area pointed to by Word 4).
3: For multi-trans TPs, this code indicates a return to processing on behalf of the multi-trans "shell". The exit receives generic, installation-supplied accounting information from the TP user's RACF profile (in the area pointed to by Word 4).
4-255: These codes are reserved, and no action is taken.

Word 4

Address of an area containing accounting information. (See Accounting Information.)

Word 5

Address of a two-word area representing a message area. The first word contains a message length of zero on entry. The second word contains the address of an 80-byte message buffer. In that buffer, the exit routine can place a message to be issued to the APPC/MVS job log.

Note: The high-order bit is set in the address of the last parameter to indicate the end of the parameter list.

Figure 1. IEFUAV Input Parameter Structure

Return Specifications

A return code from IEFUAV indicates whether processing is to continue.

If you associate multiple exit routines with IEFUAV, you can specify how the return information is to be handled using the ATTRIB KEEPRC function of the SETPROG EXIT command, the EXIT statement of PROGxx, or CSVDYNEX services. If multiple exit routines match the ATTRIB KEEPRC criteria, the system returns information from the exit routine that finished first.

If you do not specify the ATTRIB KEEPRC function, the system returns the information from the exit routine whose return value was the greatest. If multiple exit routines return with the same highest value, the return information from the exit routine that finished first will be returned.

If you associate multiple exit routines with exit IEFUAV, and any of those exit routines return with a value of 8, the system will cancel the unit of work.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register

Contents

0

Not applicable

1

Address of input parameter list

Words 1-4: Not applicable
Word 5: Points to a two-word area representing a message to be written to the APPC/MVS job log. The first word contains the length of the message. The second word is the address of an 80-byte buffer; the buffer contains the text of the message.

2-14

Not applicable

15

One of the following return codes:

Return Code: Explanation
0: Processing is to continue.
8: This unit of work should be cancelled.

Coded Example of the Exit Routine

IBM provides a sample IEFUAV exit routine in SYS1.SAMPLIB (member SMFEXITS). The sample routine validates the account number of the current user.

If this routine meets the needs of your installation, use it instead of coding your own routine (you will need to make minor modifications to the sample). If you plan to code your own routine, you might want to refer to this routine as an example.