RACROUTE: Router interface

The RACROUTE macro is the interface to RACF® (or another external security manager) for MVS™ resource managers. The macro descriptions in this information define this interface. This does not imply that the MVS operating system supports all the functions allowed by the interface. Rather, it defines the macros and keywords that are available for MVS resource managers to implement security for data and other resources.

The RACROUTE macro invokes the system authorization facility (SAF) router. If RACF is present, the SAF router directs control to the RACF router. If RACF is active, the RACF router then invokes RACF.
Note: High Level Assembler or Assembler H is required to assemble the RACROUTE macros.

In coding the RACROUTE macro to perform a particular request, you must also use the necessary parameters for that request type on the RACROUTE macro instruction. For example, if you code RACROUTE to access REQUEST=AUTH, you must code REQUEST=AUTH and any other required parameters as well as any optional ones you need from the RACROUTE REQUEST=AUTH macro. RACROUTE ensures that only the parameters applicable to the RACROUTE REQUEST=AUTH request type have been coded.

Note: When the function verifies the parameter list, if a keyword other than SEGDATA, STOKEN, TOKNIN, or TOKNOUT has an associated length and this length is zero, the function assumes that the keyword is not specified. For the SEGDATA keyword on the RACROUTE REQUEST=EXTRACT, TYPE=REPLACE, a length of zero is valid. For STOKEN, TOKNIN, and TOKNOUT, the keyword is considered not specified if both the associated length and version fields are zero in the token area.

Table 1 is a quick reference that identifies the system macro-request types that are replacements for the independent RACF system macros documented in Independent RACF system macros.

Table 1. Cross-reference for RACROUTE REQUEST=type and the independent RACF system macros
RACROUTE request type Equivalent independent RACF system macro
REQUEST=AUTH RACHECK
REQUEST=DEFINE RACDEF
REQUEST=EXTRACT RACXTRT
REQUEST=FASTAUTH FRACHECK
REQUEST=LIST RACLIST
REQUEST=STAT RACSTAT
REQUEST=VERIFY RACINIT

Keyword and parameter cross-reference for RACROUTE

Table 2 lists the parameters available through the RACROUTE macro interface and cross-references them to each REQUEST=type in the entire RACROUTE macro. The allowable parameters for each REQUEST=type are marked with the symbol X. See the specific RACROUTE REQUEST=type macro descriptions for information about the use of the parameters for each type of request.

Table 2. RACROUTE REQUEST= Operand cross-reference
RACROUTE
parameters
A
U
D
I
T
A
U
T
H
D
E
F
I
N
E
D
I
R
A
U
T
H
E
X
T
R
A
C
T
F
A
S
T
A
U
T
H
L
I
S
T
S
I
G
N
O
N
S
T
A
T
T
O
K
E
N
B
L
D
T
O
K
E
N
M
A
P
T
O
K
E
N
X
T
R
V
E
R
I
F
Y
V
E
R
I
F
Y
X
ACCLVL=   X X                      
ACEE= X X X X X X X X       X X  
ACEEALET=       X   X                
ACCESS=       X                    
ACTINFO=                         X X
APPL=   X       X X X         X X
ATTR=   X       X                
AUDIT=     X                      
AUTHCHKS=           X                
BRANCH=         X                  
CHKAUTH=     X                      
CLASS= X X X X X X X   X          
COPY=                 X          
COPYLEN=                 X          
CRITERIA=           X                
DATA=     X                      
DATEFMT=         X                  
DECOUPL= X X X X X X X X X X X X X X
DERIVE=         X                  
DSTYPE=   X X                      
ENCRYPT=         X               X X
ENTITY=   X X   X X                
ENTITYX= X X X   X X                
ENTRY=                 X          
ENVIR=     X       X           X  
ENVRIN=           X   X         X  
ENVROUT=         X     X         X  
ERASE=     X                      
ERROROPT=                         X X
EVENT= X                          
EVQUAL= X                          
EXENODE=                   X     X X
EXPDT=     X                      
EXPDTX=     X                      
FIELDS=         X                  
FILESEQ=   X X                      
FILTER=             X              
FLDACC=         X                  
FORMOUT=                     X      
GENERIC=   X X   X                  
GLOBAL=             X              
GROUP=               X   X     X X
GROUPID=   X                        
ICRX=                         X  
ICTX=                         X  
IDID=                         X  
INSTLN=   X X     X X           X X
JOBNAME=                         X X
LEVEL=     X                      
LIST=             X              
LOC=             X           X  
LOG=   X   X   X             X X
LOGSTR= X X   X   X             X X
LOGSTRX=           X                
LSTTYPE=               X            
MATCHGN=         X                  
MCLASS=     X                      
MENTITY=     X                      
MENTX=     X                      
MF= X X X X X X X X X X X X X X
MGENER=     X                      
MGMTCLA=     X                      
MSGRTRN=   X X                   X X
MSGSP=   X X                   X X
MSGSUPP=   X X X   X             X X
MVOLSER=     X                      
NESTED=                         X  
NEWNAME=     X                      
NEWNAMX=     X                      
NEWPASS=                         X X
NEWPHRASE=                         X X
NEXT=                 X          
NOTIFY=     X                      
OIDCARD=                         X X
OLDVOL=   X                        
OWNER=     X       X              
PASSCHK=                         X X
PASSWRD=                         X X
PGMNAME=                         X X
PHRASE=                         X X
POE=               X   X     X X
POENET=               X   X     X X
PROFILE=   X                        
RACFIND=   X X                      
RECVR=   X                        
RELATED= X X X X X X X X X X X X X X
RELEASE= X X X X X X X X X X X X X X
REMOTE=                   X     X X
REQSTOR= X X X X X X X X X X X X X X
RESCSECLABEL=       X                    
RESOWN=     X                      
RESULT= X                          
RETPD=     X                      
RTOKEN=   X   X                    
SECLABL=     X         X   X     X X
SECLVL=     X                      
SEGDATA=         X                  
SEGMENT=         X                  
SERVAUTH=                         X X
SESSION=                   X     X X
SGROUP=                   X     X X
SMC=                         X X
SNODE=                   X     X X
START=                         X X
STAT=                         X X
STATUS=   X                        
STOKEN=                   X     X X
STORCLA=     X                      
SYSTEM=   X                     X  
SUBPOOL=         X   X           X  
SUBSYS= X X X X X X X X X X X X X X
SUSERID=                   X     X  
TAPELBL=   X X                      
TERMID=                   X     X X
TOKNIN=                   X X   X X
TOKNOUT=               X   X X X X X
TRUSTED=                   X     X X
TYPE=     X X X     X            
UACC=     X                      
UNIT=     X                      
USERID=   X           X   X     X X
USERSECLABEL=       X                    
UTOKEN=   X                        
VERBEXIT=               X            
VOLSER=   X X   X                  
WARNING=     X                      
WKAREA=           X                
WORKA= X X X X X X X X X X X X X X
XMREQ=                     X X    
X500NAME=                         X  

Addressing considerations

If a caller is executing in 24-bit addressing mode, all parameters and parameter lists are assumed to reside below 16MB. If a caller, however, is executing in 31-bit addressing mode, all parameters and parameter lists might reside above 16MB (that is, all parameter addresses are 31-bit addresses).

All parameter lists generated by the RACROUTE macro are in a format that allows assembled code to be moved above 16MB without being reassembled.

Cross memory considerations

Except where specifically noted, RACROUTE can only be issued in non-cross-memory mode (for example, where HASN=PASN=SASN). For the services that can be invoked in cross-memory mode (where it is not the case that HASN=PASN=SASN), RACROUTE must be issued in primary ASC mode.