RACROUTE REQUEST=AUTH (standard form)

The standard form of the RACROUTE REQUEST=AUTH macro is written as follows. For a description of additional parameters that are required and 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).

Note:

RACROUTE REQUEST=AUTH requires an ACEE. For most applications, the system will have created an ACEE to represent the active user. However, for special cases where no ACEE exists, the invoker must create one before invoking RACROUTE REQUEST=AUTH. If there is no ACEE, the result is ABEND 582 with reason code 00.

The most common way to create an ACEE is to issue a RACROUTE REQUEST=VERIFY, specifying ENVIR=CREATE. After all RACROUTE invocations are complete, the invoker should issue RACROUTE REQUEST=VERIFY with ENVIR=DELETE specified, to delete the ACEE previously created.

Application programs must be structured so that a task requesting RACF® services does not do so while other I/O initiated by the task is outstanding. If such I/O is required, the task should either wait for the other I/O to complete before requesting RACF services, or the other I/O should be initiated under a separate task. This is necessary to assure proper processing in recovery situations.

Macro parameter Classification and notes
   name name: Symbol. Begin name in column 1.
   
One or more blanks must precede RACROUTE.
   
RACROUTE  
   
One or more blanks must follow RACROUTE.
   
REQUEST=AUTH  
   
,CLASS=‘class name’ class name: 1–8 character name
,CLASS=class name addr class name addr: A-type address or register (2) – (12)
   
,ENTITY=resource name addr resource name addr: A-type address only
,ENTITY=(resource name addr) resource name addr: A-type address or register (2) – (12)
,ENTITY=(resource name addr,CSA)  
,ENTITY=(resource name addr,PRIVATE)  
,ENTITY=(resource name addr,NONE)  
   
,ENTITYX=extended resource name addr extended resource name addr: A-type address only
,ENTITYX=(extended resource name addr) extended resource name addr: A-type address or register (2) – (12)
,ENTITYX=(extended resource name addr,CSA)  
,ENTITYX=(extended resource name addr,PRIVATE)  
,ENTITYX=(extended resource name addr,NONE)  
   
,PROFILE=profile addr profile addr: A-type address or register (2) – (12)
   
,VOLSER=vol addr vol addr: A-type address or register (2) – (12)
Note: VOLSER is required for CLASS=DATASET and DSTYPE not equal to M when a discrete profile name is used and when ENTITY is also coded.
   
    ,ACCLVL=access level access level addr: A-type address or register (2) – (12)
    addr  
    ,ACCLVL=(access level parm list addr: A-type address or register (2) – (12)
    addr,parm list addr)  
   
    ,ACEE=acee addr acee addr: A-type address or register (2) – (12)
   
    ,APPL=‘applname’ applname: 1–8 character name
    ,APPL=applname addr applname addr: A-type address or register (2) – (12)
   
    ,ATTR=READ Default: ATTR=READ
    ,ATTR=UPDATE  
    ,ATTR=CONTROL  
    ,ATTR=ALTER  
    ,ATTR=reg reg: register (2) – (12)
   
    ,DSTYPE=N Default: DSTYPE=N
    ,DSTYPE=V  
    ,DSTYPE=M  
    ,DSTYPE=T  
   
    ,FILESEQ=number number: 1–65535
    ,FILESEQ=reg reg: register (2) – (12)
   
    ,GENERIC=YES  
    ,GENERIC=ASIS Default: GENERIC=ASIS
   
    ,GROUPID=‘groupid’ groupid: 1–8 character group ID
    ,GROUPID=groupname groupname addr: A-type address or register (2) – (12)
    addr  
   
    ,INSTLN=parm list addr parm list addr: A-type address or register (2) – (12)
   
    ,LOG=ASIS Default: LOG=ASIS
    ,LOG=NOFAIL  
    ,LOG=NONE  
    ,LOG=NOSTAT  
   
    ,LOGSTR=logstr addr logstr addr: A-type address or register (2) – (12)
   
   
    ,OLDVOL=old vol addr old vol addr: A-type address or register (2) – (12)
   
    ,RACFIND=YES  
    ,RACFIND=NO  
   
    ,RECVR=recvr addr recvr addr: A-type address or register (2) – (12)
   
    ,RTOKEN=rtoken addr rtoken addr: A-type address or register (2) – (12)
   
    ,STATUS=NONE Default: STATUS=NONE
    ,STATUS=ERASE  
    ,STATUS=EVERDOM  
    ,STATUS=WRITEONLY  
    ,STATUS=ACCESS  
   
    ,SYSTEM=NO Default: SYSTEM=NO
    ,SYSTEM=YES
Note: To use the SYSTEM= keyword you must specify RELEASE=1.9.2 or later.
   
    ,TAPELBL=STD Default: TAPELBL=STD
    ,TAPELBL=BLP  
    ,TAPELBL=NL  
   
    ,USERID=‘userid’ userid: 1–8 character user ID
    ,USERID=userid addr userid addr: A-type address or register (2) – (12)
   
    ,UTOKEN=token addr token addr: A-type address or register (2) – (12)
   
    ,MF=S  
   
When SYSTEM=YES is specified, only the following keywords are valid:
   
,CLASS=‘class name’ class name: 1–8 character name
,CLASS=class name addr class name addr: A-type address or register (2) – (12)
   
,ENTITY=resource name addr resource name addr: A-type address only
,ENTITY=(resource name addr) resource name addr: A-type address or register (2) – (12)
   
    ,ATTR=READ Default: ATTR=READ
    ,ATTR=UPDATE  
    ,ATTR=CONTROL  
    ,ATTR=ALTER  
    ,ATTR=reg reg: register (2) – (12)
   
    ,APPL=‘applname’ applname: 1–8 character name
    ,APPL=applname addr applname addr: A-type address or register (2) – (12)
   
    ,INSTLN=parm list addr parm list addr: A-type address or register (2) – (12)
   
    ,LOG=ASIS Default: LOG=ASIS
    ,LOG=NOFAIL  
    ,LOG=NONE  
    ,LOG=NOSTAT  
The parameters are explained as follows:
,ACCLVL=access level addr
,ACCLVL=(access level addr,parm list addr)
specifies the tape-label access-level information for the MVS™ tape-label functions. The access level pointed to by the specified address is a 1-byte length field, containing the value (0–8) of the length of the following data, followed by an 8-character string that is passed to the RACROUTE REQUEST=AUTH installation-exit routines. The optional parameter list pointed to by the specified address contains additional information to be passed to the RACROUTE REQUEST=AUTH installation exit routines. RACF does not inspect or modify this information.
,ACEE=acee addr
specifies the address of the ACEE to be used during RACF authorization-check processing.

Programs must be APF-authorized, system key 0–7, or in supervisor state to use the ACEE parameter.

If no ACEE is specified, RACF uses the TASK ACEE pointer (TCBSENV) in the extended task control block (TCB). Otherwise, or if the TASK ACEE pointer is zero, RACF uses the main ACEE for the address space. The main ACEE is pointed to by the ASXBSENV field of the address-space extension block.

,APPL=‘applname’
,APPL=applname addr
specifies the name of the application requesting authorization checking. The application name is not used for the authorization checking process but is made available to the installation exit routine or routines called by the RACROUTE REQUEST=AUTH routine. If the address is specified, the address must point to an 8-byte field containing the application name, left-justified and padded with blanks.
,ATTR=READ
,ATTR=UPDATE
,ATTR=CONTROL
,ATTR=ALTER
,ATTR=reg
specifies the level of authority requested. RACF checks the resource profile protecting the resource identified by the ENTITY and CLASS keywords. The values have the following hierarchical order:
  • READ
  • UPDATE
  • CONTROL
  • ALTER

That is, if a user has update authority and ATTR=READ is specified, RACF returns a return code of 0. If ATTR=CONTROL, RACF returns a return code of 8.

For multilevel secure environments:
  1. When ATTR=READ or ALTER, it will be treated as though it was a read-only request for purposes of mandatory access control (MAC) checking.
  2. When ATTR=UPDATE or CONTROL, it will be treated as though it was a read-write request for purposes of mandatory access control (MAC) checking.
If a register is specified, the register must contain one of the following codes in the low-order byte of the register:
X'02'
READ
X'04'
UPDATE
X'08'
CONTROL
X'80'
ALTER
The default is ATTR=READ.
,CLASS=‘class name’
,CLASS=class name addr
specifies that RACF authorization checking is to be performed for a resource of the specified class. The address must point to a 1-byte field indicating the length of the class name, followed by the class name.

The specified class must be defined in the class descriptor table, and must be active for this request to be processed. In addition, if the class descriptor table specifies that RACLIST is required, the SETROPTS RACLIST option must be active for the class.

,DSTYPE=N
,DSTYPE=V
,DSTYPE=M
,DSTYPE=T
specifies the type of data set associated with the request:
N
for non-VSAM
V
for VSAM
M
for model profile
T
for tape
DSTYPE=T should not be specified unless the SETROPTS TAPEDSN option is active (RCVTTDSN bit is on); otherwise, the processing is the same as for RACROUTE REQUEST=AUTH, CLASS=‘TAPEVOL’.

DSTYPE should be specified only for CLASS=DATASET.

,ENTITY=resource name addr
,ENTITY=(resource name addr)
,ENTITY=(resource name addr,CSA)
,ENTITY=(resource name addr,PRIVATE)
,ENTITY=(resource name addr,NONE)
,ENTITYX=extended resource name addr
,ENTITYX=(extended resource name addr)
,ENTITYX=(extended resource name addr,CSA)
,ENTITYX=(extended resource name addr,PRIVATE)
,ENTITYX=(extended resource name addr,NONE)
,PROFILE=profile addr
specifies the resource address.

Guideline: Use ENTITYX rather than ENTITY. With ENTITY, the entity name you pass to RACF must be in a buffer, the size of which is determined by the length in the class descriptor table. If the maximum length of a class descriptor entity increases in the future, you must modify your program to use a larger buffer. By using ENTITYX with the maximum buffer size, you avoid this possible problem because you remove the class descriptor table dependency from your program.

For the ENTITY keyword, the resource name is a 44-byte DASD data set name for CLASS=DATASET, or a 6-byte volume serial number for CLASS=DASDVOL or CLASS=TAPEVOL. The length of all other resource names is determined from the class descriptor table.

  • ENTITY=resource name addr or ENTITY=(resource name addr) specifies that RACF authorization checking is to be performed for the resource whose name is pointed to by the specified address. The name must be left-justified in the field and padded with blanks.
  • ENTITY=(resource name addr,CSA) specifies that RACF authorization checking is to be performed for the indicated resource and that a copy of the profile is to be maintained in central storage. The storage acquired for the profile is obtained from the common storage area (CSA), and is fetch-protected, key 0 storage.

    For ENTITY, CSA returns the address of the in-storage profile, with the name field replaced by the entity name specified.

    If CSA is specified and the return code from the RACROUTE REQUEST=AUTH macro instruction is 00 or 08 (that is, a profile exists), the address of the profile mapped by ICHRRPF is returned in register 1, as long as the return code is not a CDT default return code for a resource profile. If a default return code is returned, register 1 does not contain the address of the profile. Note that, like CSA, when PRIVATE is specified, the profile is not returned along with a default return code. See note 3 for the effect of a default return code on a reason code.

    Programs must be APF-authorized, system key 0–7, or in supervisor state to specify CSA with the ENTITY keyword.

    Note:
    1. If a common-area subpool (for example 226–228, 231, 239, 241, 245, 247, or 248) is used and not freed before the job terminates, then the job might show up in the exception reports of RMF (or other monitoring tools that support the tracking of common-area storage utilization) as owning common storage. Before your job terminates, it should issue a FREEMAIN to free this common storage.
    2. If a VOLSER is specified on the RACROUTE REQUEST=AUTH macro for the DATASET class, it is built into the profile.
    3. When a default return code of other than 4 is specified for a class in the class descriptor table, in addition to returning that specified return code, the reason code is incremented by X'200' (decimal 512).
  • ENTITY=(resource name addr,PRIVATE) PRIVATE specifies the same as CSA except that RACROUTE returns the profile in the user private area rather than in common storage, and the name field contains the name of the returned profile instead of the name of the resource that was specified on the ENTITY keyword. The issuer of RACROUTE REQUEST=AUTH must free this storage when the profile is no longer needed. (The profile subpool number and length are returned as well as the profile data.) For default reason codes, no profile is returned as for CSA.

    If the reason codes default, refer to Class descriptor table (CDT) default return codes and reason codes to identify them. If CSA or PRIVATE was specified on ENTITY or ENTITYX, register 1 does not point to a profile.

    Programs must be APF-authorized, system key 0–7, or in supervisor state to specify PRIVATE with the ENTITY keyword.
    Note: If a VOLSER is specified on the RACROUTE REQUEST=AUTH macro for the DATASET class, it is built into the profile.
  • ENTITY=(resource name addr,NONE) specifies the same as ENTITY=resource-name address. However, no profile is returned.
  • ENTITYX=extended resource address or ENTITYX=(extended resource address) specifies the address of a structure that consists of two 2-byte length fields, followed by the entity name. The entity name is the name of the resource for which RACF authorization checking is to be performed.
    • The first 2-byte field specifies a buffer length, which can be from 0 to 255 bytes. This length field refers to the length of the buffer that contains the entity name; it does not include the length of either length field.
    • The second 2-byte field specifies the actual length of the entity name. This length field includes the length of the actual name without any trailing blanks; it does not include the length of either length field.
    These two length fields can be used in several different ways:
    • If you know the length of the entity name, you can specify 0 in the first field and the length of the entity name in the second field.
    • If you choose to place the entity name in a buffer area, specify the length of the buffer in the first field. For the second field, do one of the following:
      • If you know the length of the entity name, specify the length in the second field. The length of the first field can be from 0 to 255, but must be equal to or greater than the length of the second field.
      • If you do not know the length of the entity name, specify 0 in the second field, and RACF counts the number of characters in the entity name.

    To use this keyword, you must also specify RELEASE=1.9 or later.

  • ENTITYX=(extended resource name addr,CSA) specifies that RACF authorization checking is to be performed for the indicated resource, and that a copy of the profile is to be maintained in main storage. The storage acquired for the profile is obtained from the common storage area (CSA), and is fetch-protected, key 0 storage.

    For ENTITYX, CSA returns the address of the in-storage profile, with the name field replaced by the entity name specified.

    If CSA is specified and the return code produced by the RACROUTE REQUEST=AUTH macro instruction is 00 or 08, the address of the profile mapped by ICHRRPF is returned in register 1, as long as the return code is not a CDT default return code for a resource profile. If a default return code is returned, register 1 does not contain the address of the profile. Note that, like CSA, when PRIVATE is specified, the profile is not returned along with a default return code. See note 2 for the effect of a default return code on a reason code.

    Programs must be APF-authorized, system key 0–7, or in supervisor state to specify CSA with the ENTITYX keyword.

    Note:
    1. When a common-area subpool (for example 226–228, 231, 239, 241, 245, 247, or 248) is used and not freed before the job terminates, then the job might show up in the exception reports of RMF (or other monitoring tools that support the tracking of common-area storage utilization) as owning common storage. Before your job terminates, it should issue a FREEMAIN to free this common storage.
    2. When a default return code of other than 4 is specified for a class in the class descriptor table, in addition to returning that specified return code, the reason code is incremented by X'200' (decimal 512).

    To use this keyword, you must also specify RELEASE=1.9 or a later release number.

  • ENTITYX=(extended resource name addr,PRIVATE) PRIVATE specifies the same as CSA, except that RACROUTE returns the profile in the user private area rather than in common storage, and the name field contains the name of the returned profile instead of the name of the resource that was specified on the ENTITY keyword. For default reason codes, no profile is returned as for CSA.

    If the reason codes default, refer to Class descriptor table (CDT) default return codes and reason codes to identify them. If CSA or PRIVATE was specified on ENTITY or ENTITYX, then register 1 does not point to a profile.

    The issuer of RACROUTE REQUEST=AUTH must free this storage when the profile is no longer needed. (The profile subpool number and length are part of the profile data returned.)

    To use this keyword, you must also specify RELEASE=1.9 or a later release number.

    Programs must be APF-authorized, system key 0–7, or in supervisor state to specify PRIVATE with the ENTITYX keyword.

  • ENTITYX=(extended resource name addr,NONE) specifies the same as ENTITYX=resource name address. However, no profile is returned.

    To use this keyword, you must also specify RELEASE=1.9 or a later release number.

  • PROFILE=profile addr specifies that RACF authorization checking is to be performed for the resource whose profile is pointed to by the specified address. This profile must be supplied by a previously executed RACROUTE REQUEST=AUTH with CSA or PRIVATE specified. A profile supplied by RACROUTE REQUEST=LIST is not acceptable.

    To specify PROFILE, programs must be APF-authorized and in supervisor state. The programs must also be in system key 0 or in the same key as the storage of the profile.

Note:
  1. If ENTITY=(...,CSA) or ENTITY=(...,PRIVATE) is coded on the RACROUTE macro instruction, RACF ignores the privileged and trusted attributes and performs normal authorization processing.
  2. It is generally not advisable to use generic characters in an entity(x) name as the results you expect usually will not occur. Using a generic character in the entity(x) name indicates that the application is (for some reason) asking about a profile, not a resource, and therefore during processing of the AUTH request RACF will use only a generic profile name that is exactly the same in the RACF data base. For example: An entity name of A.B.C*.D will ONLY match on a generic profile of that exact name in that resource class. Less specific (such as A.B.**) generic profiles will NOT be used.
,FILESEQ=number
,FILESEQ=reg
specifies the file-sequence number of a tape data set on a tape volume or within a tape-volume set. The number must be in the range 1–65535. If a register is specified, it must contain the file-sequence number in the low-order halfword. If CLASS=DATASET and DSTYPE=T are not specified, FILESEQ is ignored.
,GENERIC=YES
,GENERIC=ASIS
specifies whether the resource name is to be treated as a generic profile name. GENERIC is ignored if the GENCMD option on the RACF SETROPTS command is not specified for the class (see z/OS Security Server RACF Command Language Reference).
This keyword is designed primarily for use by RACF commands.
YES
The resource name is considered a generic profile name, even if it does not contain a generic character: an asterisk (*), a percent sign (%), or, for general-resource classes, an ampersand sign (&). If you specify GENERIC=YES, the entity(x) name in the macro will match only a generic profile name that is exactly the same in the RACF data base. It will not match a discrete name.
ASIS
The resource name is considered generic if it contains a generic character: an asterisk (*), a percent sign (%), or, for general-resource classes, an ampersand sign (&).
,GROUPID=‘groupid’
,GROUPID=groupid address
specifies the group name that RACF uses to perform third-party authorization checking. This is an 8-character field, left-justified, and padded to the right with blanks.

If the calling program wants a third-party authorization check performed on the group name rather than the user ID, the USERID keyword must be specified as *NONE*. That is, when the caller invokes third-party authorization checking, RACF verifies the authority of the group name to the requested resource; RACF disregards the group name associated with the ACEE of the caller.

Programs must be APF-authorized, system key 0–7, or in supervisor state to use the GROUPID keyword.

,INSTLN=parm list addr
specifies the address of an area that is to contain parameter information meaningful to the RACROUTE REQUEST=AUTH installation exit routine. This information is passed to the installation exit routine when it is given control by RACROUTE REQUEST=AUTH.

The INSTLN parameter can be used by an application program acting as a resource manager that needs to pass information to the RACROUTE REQUEST=AUTH installation exit routine.

,LOG=ASIS
,LOG=NOFAIL
,LOG=NONE
,LOG=NOSTAT
specifies the types of access attempts to be recorded on the SMF data set.
ASIS
RACF records the event in the manner specified in the profile that protects the resource, or by other methods such as a SETROPTS option.
NOFAIL
If the authorization check fails, the attempt is not recorded. If the authorization check succeeds, the attempt is recorded as in ASIS.
Note: When SETROPTS PROTECTALL(WARNING) is in effect, the attempt is recorded as for ASIS.
NONE
The attempt is not recorded.

LOG=NONE suppresses both messages and SMF records regardless of MSGSUPP=NO and MSGRTRN.

NOSTAT
Like LOG=NONE, the attempt is not recorded and it suppresses both messages and SMF records regardless of the MSGSUPP and MSGRTRN keyword values. It differs in that, even if resource statistic gathering had been requested, it would not occur.

Programs must be APF-authorized, system key 0–7, or in supervisor state to use the NOFAIL, NONE, and NOSTAT keywords.

,LOGSTR=logstr addr
specifies a variable-length data string consisting of a 1-byte, binary length field followed by character data that is to be included in the RACF SMF process records. The character data can be 0–255 bytes long. The RACF report writer includes LOGSTR data on the process reports.

To use this keyword, you must also specify RELEASE=1.9 or a later release number.

,OLDVOL=old vol addr
specifies a volume serial number:
  • For CLASS=DATASET, within the same multivolume data set specified by VOLSER=
  • For CLASS=TAPEVOL, within the same tape volume specified by ENTITY=.

RACF authorization checking verifies that the OLDVOL specified is part of the same multivolume data set or tape-volume set. RACF authorization checking does not look at global access table entries when the OLDVOL parameter is specified.

The specified address points to the field that contains the volume serial number padded to the right with blanks, if necessary, to make 6 characters.

,RACFIND=YES
,RACFIND=NO
indicates whether the resource is meant to be protected by a discrete profile. The RACF processing and the possible return codes are given in Table 1.
Note: In all cases, a return code of X'0C' is also possible if the OLDVOL specified was not part of the multivolume data set defined by VOLSER, or if it was not part of the same tape volume defined by ENTITY.
Table 1. Types of profile checking performed by RACROUTE REQUEST=AUTH
Operand Generic profile checking inactive Generic profile checking active
RACFIND=YES Look for discrete profile; if found, exit with return code 00 or 08. If no discrete profile is found, exit with return code 08. Look for discrete profile; if found, exit with return code 00 or 08. Look for generic profile; if found, exit with return code 00 or 08. Exit with return code 08 if neither a discrete nor a generic profile is found.
RACFIND=NO No checking. Exit with return code 04. (See note). Look for generic profile; if found, exit with return code 00 or 08. If not found, exit with return code 04. (See note).
RACFIND not specified Look for discrete profile; if found, exit with return code 00 or 08. If no discrete profile is found, exit with return code 04. (See note). Look for discrete profile; if found, exit with return code 00 or 08. Look for generic profile; if found, exit with return code 00 or 08. Exit with return code 04 if neither a discrete nor a generic profile is found. (See note).
Note: If PROTECTALL is active, no profile is found, and the user ID whose authority was checked does not have the SPECIAL attribute, RACF returns a return code X'08' instead of a return code X'04' and denies access.
,RECVR=recvr addr
specifies the address of the user ID that has the authority to access the resource regardless of whether there is a resource profile to protect it. The field is 8 bytes, left-justified and padded to the right with blanks.

The RTOKEN= keyword is required when the RECVR= keyword is specified.

To use this keyword, you must also specify RELEASE=1.9 or a later release number.

,RTOKEN=rtoken addr
specifies the address of the RTOKEN of a unit of work. See the explanation of UTOKEN for format.

To use this keyword, you must also specify RELEASE=1.9 or later.

,STATUS=NONE
,STATUS=ERASE
,STATUS=EVERDOM
,STATUS=WRITEONLY
,STATUS=ACCESS
specifies the type of status required.
NONE
No STATUS= functions have been requested.
ERASE
RACROUTE REQUEST=AUTH is to return the ERASE status of the data set specified on the ENTITY or ENTITYX keyword. The ERASE status is returned as the RACF reason code. A reason code of 4 indicates the data set will be erased when scratched, and a reason code of 0 indicates it will not. The user of this operand should be aware that the SETROPTS ERASE setting, in conjunction with the ERASE setting in the profile protecting the data set, determines the ERASE status. This parameter is valid for CLASS=DATASET and a DSTYPE value other than T.
EVERDOM
Security-label authorization checking includes a check to see whether the user has a security label, other than that of this job or logon session, that could ever dominate that of the current object. This is done primarily so that message security can determine what to do with the messages that cannot currently be shown to the user. For example, if the user does not have a security label that can ever dominate that of the message, the message can be deleted. Be aware that choosing this option increases processing time. The default is that security-label authorization checking occurs with the security label of the current job or logon session.
STATUS=EVERDOM is intended for use only with ATTR=READ and is supported for classes using the following authorization checking only:
  1. EQUALMAC
  2. MAC
  3. RVRSMAC
WRITEONLY
The request is for output only in a class that also allows read or write functions. No reading is to be done.
STATUS=WRITEONLY is intended for use by a trusted process that only allows its users to write data, not to read it, and is supported for classes using the following authorization checking only:
  1. EQUALMAC
  2. MAC
ACCESS
The request is simply to return the user's highest current access to the resource specified. Upon successful completion, the user's access is returned in the RACF reason code. No auditing is done for this request.
Note:
  1. If the ATTR= keyword is specified along with STATUS=ACCESS, the ATTR= keyword is ignored.
  2. To use the STATUS=ACCESS keyword, you must specify RELEASE=1.9 or later.
,SYSTEM=NO
,SYSTEM=YES
specifies whether the caller is in system key 0–7 or supervisor state, or both.
NO
indicates that the caller cannot guarantee to be in supervisor state or system key 0–7. When SYSTEM=NO is specified, normal REQUEST=AUTH processing occurs.
 
 
YES
indicates that the caller is in system key 0–7 or supervisor state, or both. If the caller is not in system key 0–7 or supervisor state, an abend might occur. Specifying SYSTEM=YES when the caller is in system key 0–7 or supervisor state might allow more efficient processing of this request. Currently, SYSTEM=YES has no effect on RACF's processing of RACROUTE REQUEST=AUTH.
Note: To use the SYSTEM= keyword you must specify RELEASE=1.9.2 or later.

The default is SYSTEM=NO.

,TAPELBL=STD
,TAPELBL=BLP
,TAPELBL=NL
specifies the type of tape-label processing to be done:
STD
IBM® or ANSI standard labels
BLP
Bypass label processing
NL
Non-labeled tapes

For TAPELBL=BLP, the user must have the requested authority to the profile ICHBLP in the general-resource class FACILITY. For more information about using the ICHBLP profile, see z/OS Security Server RACF Security Administrator's Guide.

For TAPELBL=NL or BLP, data management routines do not allow the user to protect volumes with volume serial number in the format “Lnnnnn.”

This parameter is primarily intended for use by data-management routines to indicate the label type from the LABEL keyword on the JCL statement.

This parameter is valid for CLASS=DATASET and DSTYPE=T, or CLASS=TAPEVOL.

,USERID=‘userid’
,USERID=userid address
specifies the user ID that RACF uses to perform third-party authorization checking. This is an 8-character field that is left-justified and padded to the right with blanks.

If USERID is specified when the caller invokes RACROUTE REQUEST=AUTH, RACF verifies that user's authority to the given entity; RACF disregards the user ID associated with the ACEE of the caller.

Note:
  1. If the calling program does not specify the GROUPID keyword, the internal RACROUTE REQUEST=VERIFY function uses the default group associated with the specified user ID.
  2. Specifying USERID=BLANKS (where BLANKS is eight characters of X'40' characters), with GROUPID not specified or specified as GROUPID=BLANKS, causes RACF to build an ACEE with an asterisk (*) specified as the user ID or group name. This is the same as an ACEE built by RACROUTE REQUEST=VERIFY without specifying USERID, GROUPID, or PASSWORD.
  3. An ACEE with a user ID of asterisk (*) is built by RACF only for the case listed in Note 2, and it cannot be specified. For example, consider USERID=VAR1, where variable VAR1 is the asterisk character (*) followed by 7 blanks. This results in a 282-48 abend that regards the asterisk (*) as in invalid RACF user ID.

Programs must be APF-authorized, system key 0–7, or in supervisor state to use the USERID keyword.

,UTOKEN=token addr
specifies the address of the UTOKEN of the user for whom RACF performs third-party authorization checking. The first byte contains the length of the UTOKEN, and the second byte contains the version number.

If UTOKEN is specified when the caller invokes RACROUTE REQUEST=AUTH, RACF verifies that user's authority to the given entity; RACF disregards the user ID associated with the ACEE of the caller. Furthermore, if this parameter is specified, it takes precedence over the USERID and GROUPID parameters (if specified).

To use this keyword, you must also specify RELEASE=1.9 or a later release number.

The ACEE= does not perform a third-party check. Only UTOKEN, USERID, and GROUPID do this.

Programs must be APF-authorized, system key 0–7, or in supervisor state to use the UTOKEN parameter.

,VOLSER=vol addr
specifies the volume serial number, as follows:
  • For non-VSAM DASD data sets and tape data sets, this is the volume serial number of the volume on which the data set resides.
  • For VSAM DASD data sets, this is the volume serial number of the catalog controlling the data set.

The volume serial number is optional if DSTYPE=M is specified; it is ignored if the profile name is generic.

The field pointed to by the specified address contains the volume serial number, padded to the right with blanks if necessary to make six characters. VOLSER= is only valid (and must be supplied) with CLASS=DATASET, (unless DSTYPE=M is specified) when ENTITY or ENTITYX is also coded.

,MF=S
specifies the standard form of the RACROUTE REQUEST=AUTH macro instruction.