RACROUTE REQUEST=STAT (standard form)

The standard form of the RACROUTE REQUEST=STAT macro is written as follows. For a description of additional keywords that you can code and additional parameters that are required on the RACROUTE request, but that are not specific to this request type, see RACROUTE (standard form).



`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede RACROUTE.

RACROUTE

␢	One or more blanks must follow RACROUTE.


REQUEST=STAT
,CLASS=`‘class name’`	`class name`: 1–8 character class name
,CLASS=`class name addr`	`class name addr`: A-type address or register (2) – (12)

,COPY=`copy addr`	`copy addr`: A-type address or register (2) – (12)
,COPYLEN=`copy length`	`copy length`: length or register (2) – (12)

,ENTRY=`entry addr`	`entry addr`: A-type address or register (2) – (12)

,NEXT=`next class addr`	`next class addr`: A-type address or register (2) – (12)

,MF=S

The parameters are explained as follows:

,CLASS=‘class name’

,CLASS=class name addr

specifies the class name to be located. The name can be explicitly defined on the macro by enclosing the name in quotes. If specified, the address must point to an 8-byte field containing the class name, left-justified and padded with blanks if necessary.

The class name specified must be a general resource defined to RACF® in the class descriptor table (CDT). (For a list of the classes supplied by IBM®, see Supplied class descriptor table entries.)

Note:

The classes DATASET, USER, and GROUP are not in the class descriptor table.
If you specify both the CLASS and NEXT parameters, the NEXT parameter will be ignored.
If CLASS= and NEXT= are omitted, the status of RACF is returned.

,COPY=

specifies the address, or register containing the address, of storage obtained by the caller. It is the responsibility of the caller to obtain this storage before the RACROUTE REQUEST=STAT call and to free it when it is no longer needed.

On return from the macro request, the storage area contains a copy of the class entry from the class descriptor table mapped by ICHPCNST.

,COPYLEN=

specifies the length, or a register containing the length, of the COPY area requested.

For applications requesting a complete class entry, the length of the COPY area provided by the caller needs to change whenever the CNST or CNSX lengths change. When that occurs, callers are not required to recompile their programs if they use field RCVTCDTL which contains the length needed to hold both a CNST and a CNSX entry.

If the value for COPYLEN is smaller than field RCVTCDTL, then the CNST and CNSX data returned is truncated to the length specified on the COPYLEN operand.

If the value for COPYLEN is larger than field RCVTCDTL, the CNST and CNSX class entries are returned. The rest of the COPY area is unaltered.

If the value of COPYLEN is 0, no data is returned and the COPY area is unaltered.

Note: The COPY and COPYLEN operands allow AMODE 24 callers to access the fields located above the 16 megabyte line contained in the CNSX.

Restrictions:

The COPY and COPYLEN operands are ignored when the CLASS= and NEXT= operands are omitted.
The COPY and COPYLEN operands require that RELEASE=2.2 or later be specified on the RACROUTE REQUEST=STAT macro.
You must specify both the COPY= and COPYLEN= operands. If only one of the operands is specified, the one that is specified is ignored.

Guideline:

Use the COPY and COPYLEN operands rather than the ENTRY operand. Classes in the dynamic class descriptor table cannot be processed using the ENTRY operand. By using the COPY and COPYLEN operands rather than the ENTRY operand, your application will work more reliably on systems that use the dynamic class descriptor table.

However, if the application is running on levels of RACF prior to RACF 2.2, use the COPY, COPYLEN, and ENTRY operands. On levels of RACF prior to RACF 2.2, the COPY and COPYLEN operands are ignored. Therefore, your application needs to be sensitive to the release of RACF it is running on.

When running RACF 2.2, OS/390® Security Server (RACF) V1R1, or later, the area returned by the COPY operand should be used; when running on RACF 2.1 or prior releases, the area pointed to by the ENTRY operand should be used.

You can implement this guideline as follows; see Example 3.

Prior to invoking RACROUTE REQUEST=STAT, clear the area specified by the COPY operand.
On return from the RACROUTE REQUEST=STAT request and after checking the return codes, use field CNSTLGT to determine where the class information was returned.
If CNSTLGT is not equal to 0 (running RACF 2.2, OS/390 Security Server (RACF) V1R1, or later), then the application should use class information returned in the area specified by the COPY operand and mapped by ICHPCNST.

If CNSTLGT is equal to 0 (running RACF 2.1 or prior release), the application should use the class information pointed to by the ENTRY operand.

,ENTRY=entry addr

specifies the address of a 4-byte area that is set to the address of the specified class in the static class descriptor table. If the class specified in the CLASS= operand is found in the dynamic class descriptor table, zero will be returned for entry addr.

Rules:

AMODE 24 callers should use the COPY and COPYLEN operands instead of the ENTRY operand.
Use the COPY= and COPYLEN= operands for classes in the dynamic class descriptor table.
If you specify ENTRY=, it will be ignored when the CLASS= operand is omitted.
If you specify both ENTRY= and NEXT=, the ENTRY= operand is ignored.

,NEXT=next class addr

specifies that RACF is to retrieve the class descriptor entry for the class following (in alphabetical order) the class specified. The address must point to an 8-byte field containing the class name, left-justified and padded with blanks, if necessary. If completed successfully, the NEXT operation updates the area pointed to by the NEXT operand with the name of the class just processed. The NEXT= function will consider the dynamic class descriptor table, if it exists, as a logical extension to the static class descriptor table. Entries in both tables will be considered while locating the next alphabetical entry. Alphabetical order is determined by the EBCDIC ordering of the characters in the class name, as illustrated in Table 1.

Table 1. Alphabetic sort order for NEXT= processing
Sorting order of characters allowed in a class name	EBCDIC equivalent
`$`	X'5B'
`#`	X'7B'
`@`	X'7C'
uppercase letters `A–Z`	X'C1'–X'E9'
numbers `0–9`	X'F0'–X'F9'

When you specify NEXT=, RACF will locate the class that alphabetically follows the specified class in the class descriptor table. RACF will return the class descriptor entry of that 'next' class in the areas specified on the COPY= and COPYLEN= operands. If you do not specify COPY= and COPYLEN=, the return and reason codes will still reflect the status of RACF and the class returned in the NEXT= operand.

To retrieve the first class in the class descriptor table, the NEXT field must be initialized to either eight blanks (X'40') or eight null characters (X'00'). If a class name is specified, it will be used as a search string for comparison to existing class names. Regardless of whether RACF does or does not find the specified class name in the table, RACF will return the next name alphabetically greater than the specified name, if one exists in the table.

Note: The classes DATASET, USER, and GROUP are not in the class descriptor table, so they will not be returned by the NEXT= function.

Rules:

If you specify NEXT=, do not specify CLASS= nor ENTRY=.
1. NEXT= will be ignored if it is specified with CLASS=.
2. ENTRY= will be ignored if it is specified with NEXT=.
When specifying NEXT=, you must also specify RELEASE=7709 or later.

,MF=S

specifies the standard form of the RACROUTE REQUEST=STAT macro instruction.

Return codes and reason codes

When you execute the macro, space for the RACF return code and reason code is reserved in the first two words of the RACROUTE parameter list. You can access them using the ICHSAFP mapping macro, by loading the ICHSAFP pointer with the label that you specified on the list form of the macro. When control is returned, register 15 contains the SAF return code.

Note: All return and reason codes are shown in hexadecimal. Also, note that SAF return code is presented as SAF RC and RACF return code is presented as RACF RC in the following topic.

SAF RC

Meaning

00

RACROUTE REQUEST=STAT has completed successfully.

RACF RC: Meaning
00: RACF is active and the class (specified in CLASS= or returned in NEXT=) is active.

04

RACROUTE REQUEST=STAT did not complete successfully.

RACF RC

Meaning

00

No security decision could be made.

Reason Code

Meaning

00

RACF was not called to process the request because one of the following occurred:

RACF is not installed.
The combination of class, REQSTOR, and SUBSYS was found in the RACF router table, and ACTION=NONE was specified.
The RACROUTE issuer specified DECOUPL=YES and a RELEASE= keyword with a higher release than is supported by this level of z/OS®.

04

RACF is active; the class (specified in CLASS= or returned in NEXT=) is inactive.

08

RACF is active. If CLASS= was specified, the class is not defined to RACF. If NEXT= was specified, no class was found to satisfy the request; the end of the class descriptor table was found.

0C

RACF is inactive; the class (specified in CLASS= or returned in NEXT=) was active prior to RACF being deactivated.

10

RACF is inactive; the class (specified in CLASS= or returned in NEXT=) is inactive.

14

RACF is inactive. If CLASS= was specified, the class is not defined to RACF. If NEXT= was specified, no class was found to satisfy the request; the end of the class descriptor table was found.

18

RACF is not installed, or an insufficient level of RACF is installed.

1C

Incorrect parameter-list length is detected for the request-specific portion of the RACROUTE REQUEST=STAT parameter list.

64

Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=STAT macro; however, the list form of the macro does not have the same RELEASE parameter. Macro processing terminates.

Note: For RACF return codes X'00', X'04', X'0C', and X'10', the class-descriptor entry for the specified class is returned to the caller in the COPY area provided or in the area pointed to by the ENTRY address.

Example 1

Determine whether the DASDVOL class is active, and retrieve the address of its class descriptor. A fullword, CDADDR, contains the class-descriptor address.

RACROUTE REQUEST=STAT,CLASS='DASDVOL',ENTRY=CDADDR,      X
         WORKA=RACWK
     ⋮
RACWK    DS   CL512

Example 2

Retrieve a copy of the CNST and CNSX area and reference fields in the CNSX.

USING CVTMAP,4              * Establish addressability to CVT
L     4,16(0)
USING RCVT,5                * Establish addressability to RCVT
L     5,CVTRAC
L     2,RCVTCDTL            * Load length to GETMAIN in reg 2.
GETMAIN RU,LV=(2)           * Get storage.
LR    3,1                   * Save address of new area in reg 3.
RACROUTE REQUEST=STAT,WORKA=SAFWORK,                          X
      CLASS='TCICSTRN',                                       X
      COPY=(3),                                               X
      COPYLEN=(2),                                            X
      RELEASE=2.2,MF=S
USING CNST,3                * Reg 3 was set up to point to COPY area
USING CNSX,4                * Establish addressability to CNSX
L     4,CNSTCNSX
IC    8,CNSTDFRC            * Load value of CNSTDFRC
     ⋮
ICHPCNST                    * Generates CNST and CNSX DSECTs

Example 3

Use the COPY and ENTRY operands together in a program that runs on RACF Version 2 Release 2 (FMID HRF2220) and on releases prior to RACF Version 2 Release 2.

         LA    0,COPYAREA            * Get address of COPY area
         LA    1,AREALEN             * Get length of COPY area
         SLR   15,15                 * Clear length/padding register
         MVCL  0,14                  * Zero out COPY area
RACROUTE REQUEST=STAT,WORKA=SAFWORK, CLASS='JESSPOOL',   X
         ENTRY=EPTR,
         COPY=COPYAREA, COPYLEN=AREALEN,                 X
         RELEASE=2.2, MF=S
***
*** Check if class data was returned in COPYAREA.
*** -- If so, use COPYAREA data mapped by ICHPCNST macro.
*** -- Otherwise, use class entry returned in EPTR because
***    this system is running an earlier release of RACF that
***    does not support COPY function.
***
         LA    3,COPYAREA            * Get address of COPY area
         USING CNST,3
         CLC   CNSTLGT,ZEROH         * Was class data returned in
                                     * COPYAREA?
         BNE   USECOPY               * -- Yes,
                                     * Use class entry in COPYAREA
         USING OLDCNST,3             * -- No,
                                     * Use class entry pointer EPTR
         L     3,EPTR                * and pre-2.2 CNST mapping
     ⋮
USECOPY  EQU   *                     * Use class entry in COPYAREA
         USING CNST,3
         USING CNSX,4                * Establish addressability to CNSX
         L     4,CNSTCNSX            * if program needs to access CNSX
                                     * fields
     ⋮
COPYAREA DS CL400           * Large enough to hold a 2.2 class entry
AREALEN  EQU 400            * Size of area provided (COPYAREA)
EPTR     DS  A              * Address of class ENTRY returned
ZEROH    DC  H'0'
OLDCNST  DSECT              * Pre-2.2 CNST declared locally

Example 4

Use the NEXT operand to process all entries, both static and dynamic, in the class descriptor table.

*                                                                       
         MVC   CLASSNM,BLANKS      Set classname to blanks              
         LA    4,COPYAREA                                               
         USING CNST,4              Addressability to CNST fields        
         LA    5,COPYCNSX                                               
         USING CNSX,5              Addressability to CNSX fields        
*                                                                       
         LA    0,COPYAREA                                               
         LA    1,COPYLEN                                                
         SLR   15,15                                                    
         MVCL  0,14                Clear the return area for CDT entry  
*                                                                       
LOOP     EQU   *                                                        
*                                                                       
* Issue RACROUTE REQUEST=STAT to get next class.                        
*                                                                       
CLSSTAT  RACROUTE REQUEST=STAT,COPY=COPYAREA,COPYLEN=COPYLEN,          X
               NEXT=CLASSNM,WORKA=RRWA,                                X
               RELEASE=7709,MF=S                                        
*                                                                       
         L     6,CNSTLGT          See if we have reached the end        
         LTR   6,6                                                      
         BZ    ALLDONE                                                  
*                                                                       
* Process each class here.  A copy of the CDT entry is in COPYAREA,     
* and the class name is also in CLASSNM.                                
*                                                                       
         B     LOOP                                                     
ALLDONE  EQU   *                  End of CDT entries                    
⋮                                                                
CLASSNM  DS    CL8                Name of class from REQUEST=STAT       
BLANKS   DC    CL8'        '                                            
COPYAREA DS    CL(CNSTCBLN)       Area for CNST portion                 
COPYCNSX DS    CL(CNSXCBLN)       Area for CNSX portion                 
COPYLEN  EQU   *-COPYAREA         Length of CDT entry                   
RRWA     DS    CL512              RACROUTE work area                    
         ICHPCNST                 Generates CNST and CNSX DSECT