# 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:

SWXRROUT

## Service Description:

The RACROUTE function is used to check whether a user is authorized to use a security package-protected resource. The information which you supply as arguments to this routine, along with system-maintained information, is used to determine whether access to a resource should, or should not be permitted. Note however, that the actual act of allowing the requested action to take place (or not) is the responsibility of your program.

## Returned Information:

The RACROUTE function returns the RACROUTE macro return code. If you CALL the RACROUTE function, the returned value is contained in the RESULT special variable. In addition, the RC special variable is set to contain the return code. The possible values for return code are:

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 */

© Copyright 1998 by Open Software Technologies, Inc.