How to use the RACF system macros

• Standard form (MF=S):

  Use the standard form of the macro when writing your own user programs (such as a non-system module), programs that you store in your own loadlib. By design, the standard form of the macro generates an inline parameter list and then modifies it. Do not use the standard form of the macro to write reentrant code, because reentrant code cannot be modified. With few exceptions, if you use the standard form of the macro in writing reentrant code, the execution of the code results in an abend.

  The standard form of the macro does three things: It obtains storage, fills in the parameters you have specified on the parameter list, and generates a call to the service routine.

• List, execute, and modify forms:
  Use the list, execute, and modify forms of the macro in combination when you write a reentrant program or plan to have numerous invocations of the macro. The forms of the macro work together in the following way:

  • List form (MF=L):

    The list form is used in two ways: 1) to allocate storage in your program's dynamic area (DSECT), and 2) to provide a template in the control section (CSECT) from which the dynamic storage parameter list can be initialized. This implies that two list forms are generally used in one program. One is used to allocate storage, and the other is used to initialize that storage. For example, the parameter list length is copied from the control section parameter list to the dynamic storage parameter list. To ensure that a valid dynamic storage parameter list has been built, the entire parameter list residing in the control section should then be copied to the parameter list residing in the dynamic storage.

    Since parameter list lengths can change from one release of RACF to the next, it is important to specify the same release on all invocations of the macro whether they be list, modify, or execute forms. If you were to code RELEASE=7705 on the control section parameter list and RELEASE=2.4 on the dynamic storage parameter list, the copy could result in an abend, or the call to the service would yield unpredictable results, since the complete parameter list was not copied.

    Note: The expansion of the list form does not contain any executable instructions; therefore, you cannot use registers in the list form.
  • Execute form (MF=E):

    When you specify the execute form of the macro, you can change the initial parameters you specified on the list form of the macro. You can also specify additional allowable parameters you might not have specified on the list form. When you issue the execute form of the macro, you generate a call to the service routine. You can change the parameters on the macro with each subsequent invocation of the execute form of the macro.

  • Modify form (MF=M):

    When you specify the modify form of the macro, you, in effect modify the parameter list of the list form of the macro. When you set the parameters that you want using the modify form of the macro, you can then use the execute form. The advantage of using the modify form is that it allows you to set only those parameters that you need. Thus, you can code a series of modify forms, followed by one execute form instead of many execute forms. This results in reducing the number of macro invocations that you need to code.

  Note: You must use the list form of the macro in conjunction with the execute or modify forms. The list form initializes certain fields that the execute and modify forms do not modify. Also, you must be sure to specify the same values for RELEASE= and REQUEST= on the execute, list, and modify forms.

*************************************************************************
*
* Example of list and execute in a reentrant module.
*
*************************************************************************
*
RACROUT  START
*        .
*        .
         BALR 12,0                     Refer to linkage conventions
         USING *,12                     in z/OS MVS Programming: 
                                            Assembler Services Guide 
         USING DYNDAT,13           
*
*************************************************************************

*************************************************************************
*
* Copy the static RACROUTE parameter list to the dynamic storage
* parameter list.
*
*************************************************************************
*
         LA  8,RACROUD                 Load the address of the
*                                      dynamic storage parameter list.
*
         LA 10,RACROUS                 Load the address of the static
*                                      parameter list.
*
         L   9,RACROUL                 Load the length of the
*                                      parameter list.
*
         LR 11,9                       Copy the length into register 11
*                                      for the MVCL.
*
         MVCL 8,10                     Copy the static parameter list
*                                      into the dynamically allocated
*                                      storage.
*
*************************************************************************
*
* Establish addressability to RACROUTE parameters.
*
*************************************************************************
*
         LA 3,TOKNOUT
         USING TOKEN,3
         MVI TOKLEN,TOKCURLN           Initialize the TOKNOUT area
*                                      with the length.
*
         MVI TOKVERS,TOKVER01          Initialize the TOKNOUT area
                                       with the version.
*
         LA 4,USERLN                   Load register 4 with the
*                                      user ID information address.
*
         LA 5,SAFWK                    Load register 5 with the SAF
*                                      work area address.
*
RACRTE   RACROUTE REQUEST=VERIFYX,TOKNOUT=(3),SESSION=RJEBATCH,       X
               USERID=(4),PASSWRD=PASSLN,                             X
               WORKA=(5),MF=(E,RACROUD),RELEASE=1.9
*
*************************************************************************

*************************************************************************
*
* Constants for RACROUTE
*
*************************************************************************
*
USERLN   DC    X'07'                  Length of user ID
USERID   DC    CL8'IBMUSER '          User ID value
PASSLN   DC    X'03'                  Password length
PASSWD   DC    CL8'IBM'               Password value
         DS OF
RACROUS  RACROUTE REQUEST=VERIFYX,MF=L,RELEASE=1.9
RACROUL  DC A(*-RACROUS)
*
         ICHSAFP                      SAF parameter list
*
&TOKCNST SETB 1                       Allow additional constants
         ICHRUTKN                     Security TOKEN
*
*************************************************************************
*
* Module acquired dynamic storage.
*
*************************************************************************
*
DYNDAT   DSECT
*        .
*        .
*        .
RACROUD  RACROUTE REQUEST=VERIFYX,MF=L,RELEASE=1.9
                                      Acquire storage for the parameter
                                      list in the module dynamic storage
                                      area.
SAFWK    DS    128F'0'                SAF work area
TOKNOUT  DS    2OF'0'                 Storage for TOKEN to be returned
*
         END   RACROUT
*
*************************************************************************