RACHECK (standard form)

The standard form of the RACHECK macro is written as follows:

Macro parameter Classification and notes
   name name: Symbol. Begin name in column 1.
   
One or more blanks must precede RACHECK.
   
RACHECK  
   
One or more blanks must follow RACHECK.
   
PROFILE=profile addr profile addr: A-type address or register (2) – (12)
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)  
   
,VOLSER=vol addr vol addr: A-type address or register (2) – (12)
Note: VOLSER is required only for CLASS=‘DATASET’ and DSTYPE not equal to M when a discrete profile name is used and only when ENTITY is also coded.
   
    ,CLASS=‘class name’ class name: 1–8 character class name
    ,CLASS=class name addr class name addr: A-type address or register (2) – (12)
   
    ,ATTR=READ reg: Register (2) – (12)
    ,ATTR=UPDATE Default: ATTR=READ
    ,ATTR=CONTROL  
    ,ATTR=ALTER  
    ,ATTR=reg  
   
    ,DDNAME=‘ddname’ ddname: 1–8 character name
    ,DDNAME=ddname addr ddname addr: A-type address or register (2) – (12)
Note: DDNAME is valid for OPEN/CLOSE routine only.
   
    ,DSTYPE=N Default: DSTYPE=N
    ,DSTYPE=V  
    ,DSTYPE=M  
    ,DSTYPE=T  
   
    ,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  
   
    ,OLDVOL=old vol addr old vol addr: A-type address or register (2) – (12)
   
    ,APPL=‘applname’ applname: 1–8 character name
    ,APPL=applname addr A-type address or register (2) – (12)
   
    ,ACEE=acee addr acee addr: A-type address or register (2) – (12)
   
    ,ACCLVL=(access value access value addr: A-type address or register (2) – (12)
    addr)  
    ,ACCLVL=(access value parm list addr: A-type address or register (2) – (12)
    addr,parm list addr)  
   
    ,RACFIND=YES  
    ,RACFIND=NO  
   
    ,GENERIC=YES Default: GENERIC=ASIS
    ,GENERIC=ASIS  
   
    ,FILESEQ=reg reg: Register (2) – (12)
    ,FILESEQ=number number: 1–65535
   
    ,TAPELBL=STD Default: TAPELBL=STD
    ,TAPELBL=BLP  
    ,TAPELBL=NL  
   
    ,STATUS=NONE Default: STATUS=NONE
    ,STATUS=ERASE  
   
    ,USERID=‘userid’ userid: 1–8 character user ID
    ,USERID=userid addr userid addr: A-type address or register (2) – (12)
   
    ,GROUPID=‘groupid’ groupname: 1–8 character group name
    ,GROUPID=groupname groupname addr: A-type address or register (2) – (12)
    ,addr  
The parameters are explained as follows:
,PROFILE=profile addr
,ENTITY=( resource name addr)
,ENTITY=( resource name addr, CSA)
,ENTITY=(resource name addr,PRIVATE)
,ENTITY=(resource name addr,NONE)
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 ENTITY=(xxx,CSA). A profile supplied by RACLIST 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.
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) 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 main storage. The storage acquired for the profile is obtained from the common storage area (CSA), and is fetch-protected, key 0 storage. The issuer of RACHECK must free this storage when the profile is no longer needed. (The profile subpool number and length are part of the profile data returned.) If CSA is specified and the return code produced by the RACHECK macro instruction is 00 or 08, the address of the profile is returned in register 1.

    Only programs that are APF-authorized, system key 0–7, or in supervisor state can use the CSA parameter.

    By establishing and maintaining a resource profile, the resource manager can reduce the I/O required to perform RACF authorization checks on frequently accessed resources.

  • ENTITY=(resource name addr,PRIVATE) PRIVATE specifies the same as CSA except that RACHECK returns the profile in the user's 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 RACHECK 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.)

    Only programs that are APF-authorized, system key 0–7, or in supervisor state can use the PRIVATE parameter.

  • ENTITY=(resource name addr,NONE) specifies the same as ENTITY=resource name address. However, no profile is returned.
,VOLSER=vol addr
specifies the volume serial number, as follows:
  • For MVS™/VSAM DASD data sets, this is the volume serial number of the catalog controlling the data set.
  • 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.

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) and if ENTITY is also coded.

,CLASS=‘class name’
,CLASS=class name addr
specifies that RACF authorization checking is to be performed for a resource of the specified class. If an address is specified, the address must point to a 1-byte field indicating the length of the class name, followed by the class name.
,ATTR=READ
,ATTR=UPDATE
,ATTR=CONTROL
,ATTR=ALTER
,ATTR=reg
specifies the access authority of the user or group permitted access to the resource for which RACF authorization checking is to be performed:
  • READ: RACF user or group can open the resource only to read.
  • UPDATE: RACF user or group can open the resource to write or read.
  • CONTROL: For VSAM data sets, RACF user or group has authority equivalent to the VSAM control password. For non-VSAM data sets and other resources, RACF user or group has UPDATE authority.
  • ALTER: RACF user or group has total control over the resource.
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
,DDNAME=‘ddname’
,DDNAME=ddname addr
specifies the ddname associated with the data set name that is specified as the ENTITY name.

This keyword is intended for use only by OPEN processing.

,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 RACHECK CLASS=‘TAPEVOL’.

DSTYPE should be specified only for CLASS=‘DATASET’.

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

The INSTLN parameter can be used by an application program acting as a resource manager that needs to pass information to the RACHECK 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.
  • NOFAIL: If the authorization check fails, the attempt is not recorded. If the authorization check succeeds, the attempt is recorded as in ASIS.
  • NONE: The attempt is not to be recorded.

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

  • NOSTAT: The attempt is not to be recorded. No logging is to occur, and no resource statistics are to be updated (including messages and SMF records).

Only programs that are APF-authorized, system key 0–7, or in supervisor state, can use the LOG parameter.

,OLDVOL=old vol addr
specifies a volume serial:
  • 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.

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

,APPL=‘applname
,APPL=applname addr
specifies the name of the application requesting authorization checking. The applname is not used for the authorization-checking process but is made available to the installation exit routine or routines called by the RACHECK 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.
,ACEE=acee addr
specifies the address of the ACEE to be used during RACHECK processing. If no ACEE is specified, RACF uses the TASK ACEE pointer (TCBSENV) in the extended TCB. 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.

Only programs that are APF-authorized, system key 0–7, or in supervisor state, can use the ACEE parameter.

,ACCLVL=(access value addr)
,ACCLVL=(access value addr,parm list addr)
specifies the tape-label access-level information for the MVS tape-label functions. The access value 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 RACHECK installation exit routines. The optional parameter list pointed to by the specified address contains additional information to be passed to the RACHECK installation exit routines. RACF does not inspect or modify this information.
,RACFIND=YES
,RACFIND=NO
indicates whether or not the resource is 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 it was not part of the same tape volume defined by ENTITY.
,GENERIC=YES
,GENERIC=ASIS
specifies whether the resource name is to be treated as a generic profile name. If GENERIC is specified with CLASS=DEFINE, NEWNAME, then GENERIC applies to both the old and new names. 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.
  • If GENERIC=YES is specified, the resource name is considered a generic profile name, even if it does not contain a generic character: an asterisk (*) or a percent sign (%). If you specify GENERIC=YES, the resource name in the macro will match only a generic resource name in the RACF database. It will not match a discrete name.
  • If GENERIC=ASIS is specified, the resource name is considered a generic only if it contains a generic character: an asterisk (*) or a percent sign (%).
Table 1. Types of profile checking performed by RACHECK
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.
,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 value 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.
,TAPELBL=STD|BLP|NL
specifies the type of tape-label processing to be done:
STD
IBM® or ANSI standard labels
BLP
Bypass label processing
NL
Unlabeled tapes

For TAPELBL=BLP, the user must have the requested authority to the profile ICHBLP in the general-resource class FACILITY. For TAPELBL=NL or BLP, the user is not allowed to protect volumes with volume serial numbers 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 only for CLASS=‘DATASET’ and DSTYPE=T, or CLASS=‘TAPEVOL’.

,STATUS=NONE|ERASE
specifies whether or not RACHECK is to return the erase status of the given data set. This parameter is valid only for CLASS=‘DATASET’ and a DSTYPE value other than T.
,USERID=‘userid
,USERID=user ID addr
specifies the user ID that RACF uses to perform third-party RACHECK. 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 RACHECK, RACF verifies that user's authority to the given entity; RACF disregards the user ID associated with the ACEE of the caller.

For third-party RACHECK, RACF performs the following steps:
  1. Checks to see whether the USERID keyword is *NONE* and GROUPID is not specified. If so, then RACF creates a default user (null) ACEE, which it uses to perform the RACHECK.
  2. If not, checks to see whether an additional (third-party) ACEE already exists, chained off the current caller's ACEE or the ACEE specified in the ACEE= keyword.
  3. If so, checks to see whether the user ID in that ACEE matches the one specified on the USERID keyword. If so, RACHECK uses the existing ACEE and avoids RACINIT processing.
  4. If USERID is specified and RACHECK does not find an additional (third-party) ACEE, or the user ID in the ACEE does not match the user ID specified on the USERID keyword, then RACHECK creates a third-party ACEE based on the USERID keyword.
  5. If the GROUPID keyword is specified in addition to the USERID keyword, and a third-party ACEE already exists, the group name of the existing third-party ACEE must also match the group name specified on the GROUPID keyword. If the GROUPID keywords do not match, RACHECK creates a third-party ACEE based on the USERID keyword.
Note: If the calling program does not specify the GROUPID keyword, the internal RACINIT function uses the default group associated with the specified user ID.
Only programs that are APF-authorized, system key 0–7, or in supervisor state, can use the USERID and GROUPID keywords.
Note: If the user ID is *NONE* and a GROUPID has not been specified, then a default user (null) ACEE is created and used to satisfy RACHECK processing.
,GROUPID=‘groupid
,GROUPID=groupid addr
specifies the group name that RACF uses to perform third-party RACHECK.
If the calling program wants a third-party RACHECK performed on the group name rather than the user ID, the USERID keyword must be specified as *NONE*. When the caller invokes third-party RACHECK, RACF verifies the authority of the group name to the requested resource; RACF disregards the group name associated with the ACEE of the caller. For third-party RACHECK, RACF performs the following steps:
  • Checks to see whether an additional (third-party) ACEE already exists, chained off the caller's ACEE, or the ACEE specified in the ACEE= keyword.
  • If so, checks to see whether the group name matches that specified on the GROUPID keyword. If so, RACHECK uses that ACEE and avoids RACINIT processing.
  • If GROUPID is specified and RACHECK does not find an additional (third-party) ACEE, or the group name in the ACEE does not match the group ID specified on the GROUPID keyword, RACHECK creates a third-party ACEE based on the GROUPID keyword.

Only programs that are APF-authorized, system key 0–7, or in supervisor state, can use the USERID and GROUPID keywords.