RACROUTE

Syntax:

RACROUTE('AUTH',entity[,class][,attr][,dstype][,volser]
          [,oldvol][,appl][,owner][,acclvl][,racfind]
          [,generic][,reqstor][,subsys][,msgsuppress])

Arguments:

'AUTH'

indicates that authorization checking is to be performed. This argument is not optional and must always be coded with this value.

entity

the name of the resource that RACF is to perform authorization checking for. If the class argument value is either 'TAPEVOL' or 'DASDVOL', the value of entity must be a 6 character volume serial number (blank padded on the right, if necessary). The lengths of other resource names can be found in the system class descriptor tables.

Note: When specifying a data set name, make sure it is fully qualified and do not include quotes in the string.

class

a 1 to 8 character value naming the resource class which contains the entity for which authorization checking is to be performed. If you specify less than 8 characters the value is blank padded on the right.

The default value is 'DATASET'.

attr

specifies the type of access authority you are trying to acquire:

'READ'

you require read access only.

'UPDATE'

you require both read and write access.

'CONTROL'

For non-VSAM, this is the same as 'UPDATE'. For VSAM this is the same as the level of authority for the control password.

'ALTER'

you require complete control over the resource.

The default value is 'READ'.

dstype

gives the type of data set (if any) for this request. The valid values are:

'N'

non-VSAM

'V'

VSAM

'M'

model profile

The default value is 'N'.

volser

the 1 to 6 character volume serial number. For a VSAM data set this is the serial number of the volume that controls the VSAM data set. For non- VSAM data sets, it is the volume that actually holds the data set. If you specify less than 6 characters the argument is padded on the right with blanks.

This argument is required when the value for class is 'DATASET', except when the value for dstype is 'M'. In all other cases, volser is not used.

Note: For SMS managed data sets, the volser argument is ignored, but must still be coded. A dummy value such as 'XXXXXX' can be used in this case.

oldvol

specifies, when class is 'TAPEVOL', a volume within the same tape volume that contains the volume given in the entity argument. When class is 'DATASET', oldvol gives the serial number of a volume in the same multi-volume data set as volser. The argument is padded on the right with blanks if you specify less than 6 characters.

appl

a 1 to 8 character application name. It gives the name of the application that wants the authorization checking.

Note: This string is not checked by RACF. It is handed to the local exit routine.

owner

a 1 to 8 byte field that gives the name of the profile owner. The owner is permitted 'ALTER' access.

acclvl

a 1 to 8 byte field that gives, for tape label processing, access level information. RACF does nothing with this field. It is passed to installation exits.

racfind

specifies that the resource is or is not protected by a discrete (as opposed to generic) profile. The possible values are:

'YES'

the resource is protected by a discrete profile.

'NO'

the resources is not protected by a discrete profile.

generic

specifies that the resource name is either a generic profile name or not. The possible values are:

'YES'

the resource name is a generic profile even if generic characters (asterisk or percent) are not present.

'ASIS'

the resource name is a generic profile only if generic characters (asterisk or percent) are present. This is the default.

reqstor

specifies a 1 to 8 byte control point name used by RACF router table processing. The default is blanks.

subsys

the 1 to 8 character name of the subsystem requesting access. This name, like reqstor is used to match with the RACF router table. The default is blanks.

msgsuppress

specify one of the following:

'Y'

suppress messages.

'N'

do not suppress messages (the default).

Module Name:

Service Description:

Returned Information:

0

authorization is granted.

4

the resource or class is unknown to your security package or the MVS router is not active.

8

authorization is denied.

Other

the abend code in decimal (use D2X to convert to hex). If an abend code is returned, the REASON variable will be set to contain the abend reason code.

Two other special variables are created by RACROUTE. These are:

SAFPRRET

which contains the RACF or installation exit return code.

SAFPRREA

which contains the RACF or installation exit reason code.

Examples:

1. Call the RACROUTE function to check 'ALTER' access to entity 'ACCOUNTS' in class 'FINANCE':

   call racroute 'auth','accounts','finance','alter'
   if rc = 0 then
     /* allow the access */
   else
     /* don't allow the access */