RACROUTE REQUEST=AUTH (standard form)

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.

• 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.

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.

N

for non-VSAM

V

for VSAM

M

for model profile

T

for tape

DSTYPE should be specified only for CLASS=DATASET.

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.

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.

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.

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.

To use this keyword, you must also specify RELEASE=1.9 or a later release 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.

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.

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

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.

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.

The default is SYSTEM=NO.

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.

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.

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

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.

• 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.