RACROUTE REQUEST=VERIFYX (standard form)

The standard form of the RACROUTE REQUEST=VERIFYX macro is written as follows. For a description of 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: 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.



`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede RACROUTE.

RACROUTE

␢	One or more blanks must follow RACROUTE.


REQUEST=VERIFYX

,TOKNOUT=`utoken addr`	`utoken addr`: A-type address or register (2) – (12)

,ACTINFO=`account addr`	`account 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)

,ENCRYPT=YES	Default: ENCRYPT=YES
,ENCRYPT=NO

,ERROROPT=ABEND	Default: ERROROPT=ABEND
,ERROROPT=NOABEND

,EXENODE=`execution`	`execution node addr`: A-type address or register (2) – (12)
`node addr`

,GROUP=`group addr`	`group addr`: A-type address or register (2) – (12)

,INSTLN=`parm list addr`	`parm list addr`: A-type address or register (2) – (12)

,JOBNAME=`jobname`	`jobname addr`: A-type address or register (2) – (12)
`addr`

,LOG=ALL
,LOG=ASIS	Default: LOG=ASIS
,LOG=NONE

,LOGSTR=`logstr addr`	`logstr addr`: A-type address or register (2) – (12)

,NEWPASS=`new`	`new password addr`: A-type address or register (2) – (12)
`password addr`

,NEWPHRASE=`new`	`new password phrase addr`: A-type address or register (2) – (12)
`password phrase addr`

,OIDCARD=`oid addr`	`oid addr`: A-type address or register (2) – (12)

,PASSCHK=YES	Default: PASSCHK=YES
,PASSCHK=NO

,PASSWRD=`password`	`password addr`: A-type address or register (2) – (12)
`addr`

,PGMNAME=`programmer`	`programmer name addr`: A-type address or register (2) – (12)
`name addr`

,PHRASE=`password phrase`	`password phrase addr`: A-type address or register (2) – (12)
`addr`

,POE=`port of entry addr`	`port of entry addr`: A-type address or register (2) – (12)
,POENET=`network name` `addr`	`network name addr`: A-type address or register (2) – (12)

,REMOTE=YES
,REMOTE=NO	Default: REMOTE=NO

,SECLABL=`seclabel addr`	`seclabel addr`: A-type address or register (2) – (12)

,SERVAUTH=`servauth` `addr`	`servauth addr`: A-type address or register (2) – (12)

,SESSION=`type`	`type`: Any valid session type
	Default: SESSION=TSO

,SGROUP=`submitting`	`submitting group addr`: A-type address or register (2) – (12)
`group addr`

,SNODE=`submitting`	`submitting node addr`: A-type address or register (2) – (12)
`node addr`

,SMC=YES	Default: SMC=YES
,SMC=NO

,START=`procname addr`	`procname addr`: A-type address or register (2) – (12)

,STAT=ASIS	Default: STAT=ASIS
,STAT=NO

,STOKEN=`stoken addr`	`stoken addr`: A-type address or register (2) – (12)

,SUSERID=`submitting`	`submitting userid addr`: A-type address or register (2) – (12)
`userid addr`

,TERMID=`terminal addr`	`terminal addr`: A-type address or register (2) – (12)

,TOKNIN=`utoken addr`	`utoken addr`: A-type address or register (2) – (12)


,TRUSTED=YES
,TRUSTED=NO	Default: TRUSTED=NO

,USERID=`userid addr`	`userid addr`: A-type address or register (2) - (12)

,MF=S

The parameters are explained as follows:

,ACTINFO=account addr

specifies the address of a field containing accounting information. This 144-byte area is passed to the RACINIT installation exit routine; it is not used by the RACROUTE REQUEST=VERIFY routine. The accounting field, if supplied, should have the following format:

The first byte of the field contains the number (binary) of accounting fields.
The following bytes contain accounting fields, where each entry for an accounting field contains a 1-byte length field, followed by the field.

,APPL=‘applname’

,APPL=applname addr

specifies the name of the application issuing the RACROUTE REQUEST=VERIFYX. If an address is specified, the address must point to an 8-byte application name, left justified and padded with blanks if necessary.

,ENCRYPT=YES

,ENCRYPT=NO

specifies whether RACROUTE REQUEST=VERIFYX encodes the old password, the new password, and the OIDCARD data passed to it.

The default is YES.

YES: Data specified by the PASSWRD, NEWPASS, and OIDCARD keywords are not pre-encoded. RACROUTE REQUEST=VERIFYX encodes the data before storing it in the user profile or using it to compare against stored data.
NO: Data specified by the PASSWRD, NEWPASS, and OIDCARD keywords is already encoded. RACROUTE REQUEST=VERIFYX bypasses the encoding of this data before storing it in, or comparing it against, the user profile.
Note: If the password was shipped from another system, the encryption method must be the same on all systems utilizing the password. For example, the RACF password authentication exit, ICHDEX01, must be identical on all systems.
ENCRYPT=NO does not apply to PHRASE and NEWPHRASE and will be ignored if specified.

,ERROROPT=ABEND

,ERROROPT=NOABEND

specifies whether RACROUTE REQUEST=VERIFYX will abend or not when an error occurs while it is accessing the RACF database.

The default is ABEND.

ABEND

When RACROUTE REQUEST=VERIFYX encounters an error accessing the RACF database, issue a 483 abend.

NOABEND

When RACROUTE REQUEST=VERIFYX encounters an error accessing the RACF database, 483 abends are suppressed. Instead, the request receives a SAF RC 8, RACF RC X'5C' and a RACF reason code of X'0483yyyy' where 'yyyy' is the RACF manager return code associated with the abend that would have been issued. If you are specifying the ERROROPT keyword with a specific release value, RELEASE=value, the Table 1 shows how the RELEASE= values affect the operation of the ERROROPT keyword:

Table 1. Relationship between the ERROROPT keyword and RELEASE= values
Release	Action
All earlier releases	ERROROPT keyword is flagged as an unknown keyword.
7703 and 7705	ERROROPT keyword is syntax checked only and an informational MNOTE indicating that the ERROROPT keyword is being ignored is returned. No abend suppression is performed. However, the SAF parameter list is built with the ERROROPT bit set. This allows programs which are assembled with RELEASE=7703 and RELEASE=7705 to take advantage of ERROROPT=NOABEND once the applications are executed in a z/OS Version 1 Release 3 (HBB7706) or later environment.
7706 and later	483 abends are replaced with a SAF return code of 8, a RACF return code of X'5C', and a RACF reason code of X'0483yyyy'. "yyyy" is the RACF manager return code associated with the abend that would have been issued.

,EXENODE=execution node addr

specifies the address of an area that contains a 1-byte length field followed by the name of the node on which the unit of work is to be executed. The node name cannot exceed eight bytes.

,GROUP=group addr

specifies the group of the user who has entered the system. The address points to a 1-byte length field, followed by the group name, which can be up to eight characters long.

Applications should fold the group name to uppercase.

,INSTLN=parm list addr

specifies the address of an area containing parameter information meaningful to the RACINIT installation exit routine. This area is passed to the installation exit when the exit routine is given control from the RACROUTE REQUEST=VERIFY routine.

The INSTLN parameter can be used by an installation having a user verification or job initiation application, and wanting to pass information from one installation module to the installation exit routine.

,JOBNAME=jobname addr

specifies the address of the job name of a background job. The address points to an 8-byte area containing the job name (left-justified and padded with blanks if necessary). If JOBNAME= is specified with the START= parameter, and the STARTED class is active, RACF uses the jobname during its processing to help determine the user ID and group name that are assigned for the started task.

Note: The JOBNAME parameter is used by RACF during RACROUTE REQUEST=VERIFYX authorization checking to verify the user's authority to submit the job. It is also passed to the installation RACINIT exit routine.

,LOG=ALL

,LOG=ASIS

,LOG=NONE

specifies when log records are to be generated.

The default is LOG=ASIS.

ALL: Any request to create an ACEE, regardless of whether it succeeds or fails, generates a RACF log record.
ASIS: Only those attempts to create an ACEE that fail generate RACF log records.
NONE: A request to create an ACEE, regardless of whether it succeeds or fails, does not generate a RACF log record.
LOG=NONE suppresses both messages and SMF records regardless of MSGSUPP=NO.

Note: SMF records are written for password changes when SETROPTS AUDIT(USER) is in effect regardless of the LOG setting specified.

,LOGSTR=logstr addr

specifies the address of a 1-byte length field followed by character data that is written to the SMF data set, together with RACF audit information.

,NEWPASS=new password addr

specifies the password that is to replace the user's currently defined password. The address points to a 1-byte length field, followed by the password, which can be up to eight characters.

The NEWPASS= keyword has no effect unless PASSCHK=YES is either defaulted to or explicitly specified and PASSWRD= is also specified. If the NEWPASS= keyword is specified with PASSCHK=NO, no error message is issued but the password is not changed. A new password phrase cannot be set using a password for authentication, nor can a new password be set using a password phrase for authentication.

,NEWPHRASE=new password phrase addr

specifies the password phrase to replace the user's currently defined password phrase. The address points to a 1-byte length field, followed by the password phrase, which can be 14-100 characters (or 9-100 characters if the new password phrase exit, ICHPWX11, is installed and accepts the new value). Specifying a length field of zero is equivalent to not specifying NEWPHRASE.

RACF checks the following set of basic rules for the value specified by NEWPHRASE:

The user ID is not part of the password phrase.
At least two alphabetics are specified (A - Z, a - z).
At least two non-alphabetics are specified (numerics, punctuation, special characters, blanks).
No more than two consecutive characters are identical.

If NEWPHRASE is specified without PHRASE, it is not used unless the user already has a password phrase, and PASSWRD is specified with a PassTicket instead of a password. If PASSWRD is specified with a PassTicket, and both NEWPASS and NEWPHRASE are specified, NEWPHRASE is used. A new password phrase cannot be set using a password for authentication, nor can a new password be set using a password phrase for authentication.

If NEWPHRASE is specified with PASSCHK=NO, no error message will be issued but the password phrase will not be changed.

When specifying NEWPHRASE=, you must also specify RELEASE=7730 or later.

,OIDCARD=oid addr

specifies the address of the currently defined operator-identification card of the user who has entered the system. The address points to a 1-byte length field, followed by the operator ID card.

,PASSCHK=YES

,PASSCHK=NO

specifies whether or not the user's password, password phrase or OIDCARD is to be verified.

YES: RACROUTE REQUEST=VERIFYX verifies the user's password, password phrase, or OIDCARD.
There are some circumstances where verification checking does not occur even though PASSCHK=YES is specified. Some examples are surrogate processing (see z/OS Security Server RACF Security Administrator's Guide) or when the START or the ENVRIN keywords are specified.
NO: The user's password or OIDCARD is not verified.

,PASSWRD=password addr

specifies the currently defined password of the user who has entered the system. The address points to either:

a 1-byte length field, followed by the password, which can be up to eight characters, or
a 1-byte length field, followed by a PassTicket, which is always eight bytes.

Note: The currently defined password is maintained in the case entered, except when the following occurs: if the PASSASIS bit is off in the user's profile and the password does not match the current password in the user's profile, the password is folded to uppercase and again compared to the current password provided MIXEDCASE PASSWORD support is enabled in SETROPTS.

,PGMNAME=programmer name addr

specifies the address of the name of the user who has entered the system. This 20-byte area is passed to the RACINIT installation exit routine; it is not used by RACF.

,PHRASE=password phrase addr

specifies the address of the currently defined password phrase of the user who has entered the system. The address points to a 1-byte length field followed by the password phrase, which can be 9-100 characters. Specifying a length field of zero is equivalent to not specifying PHRASE.

The PASSWRD and OIDCARD parameters are not used if the PHRASE parameter is specified.

Password phrases are not checked in cases where a password is not checked (PASSCHK=NO, START= or ENVRIN= specified, SURROGAT processing).

When specifying PHRASE=, you must also specify RELEASE=7730 or later.

,POE=port of entry addr

specifies the address of the port of entry into the system. The address points to the name of the input device through which the user or job entered the system. For example, this could be the name of the input device through which the job was submitted or of the terminal logged onto. The port of entry is an 8-character field that is left-justified and padded with blanks.

The port of entry becomes a part of the user's security token (UTOKEN). A flag in the UTOKEN uniquely identifies the RACF general-resource class to which the data in the POE field belongs: APPCPORT, TERMINAL, CONSOLE, or JESINPUT. The SERVAUTH class can also be a port of entry but it must be specified using the SERVAUTH keyword.

The RACF class JESINPUT provides the conditional access support for jobs entered into the system through a JES input device. The CONSOLE class performs the same task for commands that originate from a console. In addition, the APPCPORT class provides conditional access support for users entering the system from a given LU (APPC port of entry).

If the JESINPUT class is active and the JESINPUT profile protecting this port of entry has a security label other than SYSMULTI, it will override the user's default security label if the SECLABEL keyword is not specified and the RACF option SECLBYSYSTEM is active on the system.

The TERMINAL class covers the terminal used to log onto TSO.

When both the POE and TERMID keywords, or both the POE and SERVAUTH keywords, are specified the POE keyword takes precedence. Information specified by POE= on an ENVIR=CREATE can be attached to the created ACEE and used in subsequent RACF processing. RACF does not make its own copy of this area when attaching this information to the created ACEE. This area must not be explicitly freed prior to the deletion of the ACEE. For the same reason, the area must reside in a non-task-related storage subpool so that implicit freeing of the area does not occur.

Restriction: The POE keyword does not allow the length needed for a SERVAUTH resource representing an IP address.

,POENET=network name address

specifies the address of a structure that consists of a 1-byte length field followed by up to an 8-byte field containing the network name of the partner LU. When specified with the POE parameter, the value specified for POENET is combined with the value specified for POE to create a network qualified name in the form netid.luname. The network qualified LU name is then used as the POE value during further processing. POENET is only valid with SESSION=APPCTP, and should not be specified with any other type of session. To specify the POENET parameter, you must specify RELEASE=2.6.

,REMOTE=YES

,REMOTE=NO

specifies whether or not the job came through the network. The default is REMOTE=NO.

,SECLABL=seclabel addr

specifies the address of an 8-byte, left-justified character field containing the security label, padded to the right with blanks.

If you do not specify the SECLABEL parameter while the SECLABEL class is active, a security label may be derived from other parameters in the following order:

TOKNIN=
SERVAUTH=
TERMID=
JESINPUT (if SECLBYSYSTEM is active and the security label is other than SYSMULTI)
Default security label from user profile

If a security label was not found in any of these places, the user is assigned a security label of SYSLOW only when both of the following conditions are true:

MLACTIVE is in effect.
The user is authorized to the SYSLOW SECLABEL profile.

An installation can use security labels to establish an association between a specific RACF security level (SECLEVEL) and a set of (zero or more) RACF security categories (CATEGORY). If it is necessary to use security labels to prevent the unauthorized movement of data from one level to another when multiple levels of data are in use on the system at the same time, see z/OS Security Server RACF Security Administrator's Guide for further information.

,SERVAUTH=servauth addr

specifies the address of the identifier for the server through which the user is accessing the system. The address points to a 1-byte length field followed by up to a 64-byte area containing the name of a resource in the SERVAUTH class. This resource is the network access security zone name that contains the IP address of the user. If the SERVAUTH class is active and the SERVAUTH profile protecting this resource has a security label other than SYSMULTI, it will override the user's default security label if the SECLABEL keyword is not specified. After verifying that the user has access to this resource, a copy of the information specified by SERVAUTH= on an ENVIR=CREATE is attached to the created ACEE and used in subsequent RACF processing. If the POE keyword is specified, the SERVAUTH keyword is ignored. When the SERVAUTH keyword is specified, POE information in the STOKEN or TOKNIN and the TERMID keyword are ignored. When specifying SERVAUTH=, you must also specify RELEASE=7708 or later.

Rule: When both the POE and SERVAUTH parameters are specified, SERVAUTH is ignored.

,SESSION=type

specifies the session type to be associated with the request. Session types are literals. When the SESSION keyword is used in combination with the POE keyword, SESSION determines the class with which the POE keyword is connected.

When the session type is APPCTP, RACF requires APPL= and POE= also to be specified. The APPL= value should be the address of the local LU name, and the POE= value should be the address of the remote LU name.

If SERVAUTH is specified, the default session type is IP. If SERVAUTH is not specified and TERMID= or POE= is specified, the default session type is TSO. Otherwise, session type is not set.

Restrictions for the IP session type:

If a session type of IP is specified with the POE keyword, a parameter list abend will occur.
As with the OMVSSRV session type, the last access date and time messages are not issued.

The allowable session types and their associated POE classes are:

Session type	Description	POE class
APPCTP	An APPC transaction program	APPCPORT
COMMAND	A command	CONSOLE
CONSOPER	A console operator	CONSOLE
EXTBATCH	A job from external reader (EXT)	JESINPUT
EXTXBM	An execution batch monitor job	JESINPUT
INTBATCH	A batch job from internal reader (INT)	JESINPUT
INTXBM	An execution batch monitor job from INT	JESINPUT
IP	A TCP/IP address	None
MOUNT	A mount	None
NJEBATCH	A job from network job entry (NJE)	JESINPUT
NJEOPER	A network job-entry operator	JESINPUT
NJEXBM	An network execution batch monitor job	JESINPUT
NJSYSOUT	A network SYSOUT	JESINPUT
OMVSSRV	An OMVS server application When OMVSSRV is specified, user profile statistics are updated daily at most. Audit records are only created when one of the following conditions are met: An incorrect password or password phrase is specified. The user ID has been revoked. A new password or password phrase was provided. A security label error occurred.	None
RJEBATCH	A batch job from remote job entry (RJE)	JESINPUT
RJEOPER	A remote job-entry operator	JESINPUT
RJEXBM	A remote execution batch monitor job	JESINPUT
STARTED	A started procedure of started task	None
SYSAS	A system address space	None
TKNUNKWN	An unknown user from NJE	JESINPUT
TSO	A TSO or other interactive session logon	TERMINAL

Note: When no POE class is associated with the session type, the POE ID and session are preserved.

,SGROUP=submitting group addr

specifies the address of an area that contains a 1-byte length field followed by the group name of the user who submitted the unit of work. The group name cannot exceed eight bytes.

,SMC=YES

,SMC=NO

specifies the use of the step-must-complete function of RACROUTE REQUEST=VERIFYX processing.

YES: RACROUTE REQUEST=VERIFYX processing makes other tasks for the step non-dispatchable.
NO: The step-must-complete function is not used.

Note: SMC=NO should not be used if DADSM ALLOCATE/SCRATCH functions execute simultaneously in the same address space as the RACROUTE REQUEST=VERIFYX function.

,SNODE=submitting node addr

specifies the address of an area that contains a 1-byte length field, followed by the name of the node from which the unit of work was submitted. The node name cannot exceed eight bytes.

,START=procname addr

specifies the procedure name of a started task for which the RACROUTE REQUEST=VERIFYX is being performed. The address points to an 8-byte area containing the procedure name (left-justified and padded with blanks if necessary). If START= is specified, REQUEST=VERIFYX processing searches the started-procedures table for the user ID and group to use for this REQUEST=VERIFYX request. If the USERID and GROUP keywords are specified, REQUEST=VERIFYX uses those values if it cannot find a STARTED class profile or an entry in the started procedure table that matches the specified procedure name (and jobname from JOBNAME= if the STARTED class is used.)

If START is specified, PASSWRD and OIDCARD should not be specified.

,STAT=ASIS

,STAT=NO

specifies that no statistics are updated for this execution of RACROUTE REQUEST=VERIFYX, and that if logon is successful, no message is issued.

When STAT=NO is specified, the request does not result in the user being revoked even if the user's statistics have not been updated within k days (where k is the inactive period defined using SETROPTS INACTIVE(k)).

Note:

The default (STAT=ASIS) is processed the same as STAT=NO.
Messages are always issued if the RACROUTE REQUEST=VERIFYX processing is unsuccessful.

,STOKEN=stoken addr

specifies the address of the submitter's security token (UTOKEN). The first byte contains the length of the UTOKEN, and the second byte contains the format version number. See ICHRUTKN mapping, See "RUTKN: Resource/User Security Token" in z/OS Security Server RACF Data Areas.

If you specify STOKEN, the user ID in STOKEN becomes the submitter's ID in TOKNOUT, unless you specified the submitter's ID (SUSER) keyword. If you did, that keyword becomes the submitter's ID in TOKNOUT. Likewise, if you specified GROUP in the STOKEN, that becomes the submitter's group in TOKNOUT, unless you specified the submitter's group (SGROUP) keyword. The SESSION, port-of-entry (POE), and port-of-entry class (POEX) fields are also used from the STOKEN. The execution node becomes the resulting submit node and execution node unless you specify the submit node (SNODE) or execution node (EXENODE) keywords. In all cases, the specified keywords on the request override the fields of the STOKEN, if one is specified.

Also, STOKEN is used unless different submitter-checking information, such as surrogate checking, security-label dominance, or JESJOBS checking is specified.

,SUSERID=submitting userid addr

specifies the address of an area that contains a 1-byte length field followed by the user ID of the user who submitted the unit of work. The user ID cannot exceed eight bytes.

Applications should fold the submitting user ID to uppercase.

,TERMID=terminal addr

specifies the address of the identifier for the terminal through which the user is accessing the system. The address points to an 8-byte area containing the terminal identifier. The area must reside in a storage subpool not related to any task.

If POE= is specified, the TERMID= area is not referred to in subsequent processing and can be freed at the user's discretion. If the TERMINAL class is active and the TERMINAL profile protecting this resource has a security label other than SYSMULTI, it will override the user's default security label if the SECLABEL keyword is not specified.

Rule: When both the TERMID and SERVAUTH keywords are specified, the SERVAUTH keyword takes precedence.

,TOKNIN=utoken addr

specifies an address that points to a caller-provided area that contains an input UTOKEN. The mapping of the area is a 1-byte length field, followed by a 1-byte version code, followed by the UTOKEN itself, which can be 78 bytes long. The TOKNIN should have been previously obtained by RACROUTE REQUEST=VERIFY, VERIFYX, TOKENXTR or TOKENBLD.

,TOKNOUT=output token addr

specifies the address of the caller-provided area in which the UTOKEN is built. The first byte of storage at the address specified is the token length field. The second byte must contain the format version of the token. It is followed by a 78-byte area in which to build the UTOKEN. The mapping of the area is a 1-byte length field, followed by a 1-byte version code, followed by the rest of the token information.

For a description of the fields TOKNOUT uses from STOKEN, see the STOKEN description.

,TRUSTED=YES

,TRUSTED=NO

specifies whether or not the unit of work is a member of the trusted computer base. Subsequent RACROUTE REQUEST=AUTH requests using a token with this attribute have the following effects:

Authorization checking is bypassed (this includes bypassing the checks for security classification on users and data).
No statistics are updated.
No audit records are generated, except those requested using the SETROPTS LOGOPTIONS command or the UAUDIT operand on the ALTUSER command.
No exits are called.

Subsequent RACROUTE REQUEST=FASTAUTH requests using a token with this attribute have the following effects:

Authorization checking is bypassed (this includes bypassing the checks for security classification on users and data).
No statistics are updated.
No audit records are generated, except those requested using the UAUDIT operand on the ALTUSER command.

This is similar to having the started-procedures-table trusted bit on.

Note: The TRUSTED=YES keyword only has meaning when SESSION=STARTED is also specified.

,USERID=userid addr

specifies the user identification of the user who has entered the system. The address points to a 1-byte length field, followed by the user ID, which can be up to eight characters.

If the USERID= keyword is omitted, (*) is the default.

To prevent a protected user ID from being used to logon, RACROUTE REQUEST=VERIFYX processing checks for the protected user ID being specified, and fails for requests that have a password specified or expected. For additional information on RACROUTEs handling of protected user IDs, see the USERID parameter of RACROUTE REQUEST=VERIFY.

Application considerations: When verifying a user ID and password from a user, be sure to validate that the user ID and password contain only alphanumeric characters and are 1–8 characters in length. Additionally, you must change the user ID, password, and new password to uppercase unless SETROPTS MIXEDCASE is in effect. If SETROPTS MIXEDCASE is in effect, you must change only the user ID to uppercase.

Certificate user IDs:

Certificate authority certificates are associated with the user ID irrcerta, MULTIID certificate name filters are associated with the user ID irrmulti, and site certificates are associated with the user ID irrsitec. These user IDs cannot be used for any purpose other than anchoring certificate authority certificates, site certificates, or certificate name filters.

The irrcerta, irrmulti, and irrsitec user IDs are defined to RACF during IPL in a manner similar to the method used to define the user ID IBMUSER. These user IDs are added in revoked status and are not connected to any groups, insuring that they cannot be used as valid user IDs. RACROUTE REQUEST=VERIFYs performed for these user IDs fail due to the lack of connected groups.

,MF=S

specifies the standard form of the RACROUTE REQUEST=VERIFYX macro instruction.

Return codes and reason codes

When you execute the macro, space for the RACF return code and reason code is reserved in the first two words of the RACROUTE parameter list. You can access them using the ICHSAFP mapping macro, by loading the ICHSAFP pointer with the label that you specified on the list form of the macro. When control is returned, register 15 contains the SAF return code.

Note: All return and reason codes are shown in hexadecimal. Also, note that SAF return code is presented as SAF RC and RACF return code is presented as RACF RC in the following topic.

SAF RC

Meaning

00

RACROUTE REQUEST=VERIFYX has completed successfully.

RACF RC

Meaning

3C

Request completed successfully, but a VERIFYX condition occurred in SAF.

Reason Code: Meaning
20: TOKNOUT area specified was too large; on return, the length field contains the length used.
24: STOKEN area specified was too large.
30: TOKNIN area specified was too large.

04

The requested function could not be performed.

RACF RC

Meaning

00

No security decision could be made.

Reason Code

Meaning

00

RACF was not called to process the request because one of the following occurred:

RACF is not installed.
The combination of class, REQSTOR, and SUBSYS was found in the RACF router table, and ACTION=NONE was specified.
The RACROUTE issuer specified DECOUPL=YES and a RELEASE= keyword with a higher release than is supported by this level of z/OS®.

20

RACF is not active.

3C

RACF is not installed.

58

RJE or NJE operator FACILITY class profile not found.

08

The requested function failed.

RACF RC

Meaning

00

Default ACEE or token-building error.

Reason Code: Meaning
00: SAF failed to set up a recovery environment.

04

The user profile is not defined to RACF.

08

The password or password phrase is not authorized.

0C

The password or password phrase has expired.

10

At least one of the following conditions has occurred:

The new password or password phrase is not valid.
A new password phrase was specified with a current password, or a new password was specified with a current password phrase.
A new password phrase was specified with a PassTicket as the current password, but the user does not currently have a password phrase.
A password or password phrase change is disallowed at this time because the minimum password-change interval has not passed.

14

The user is not defined to the group.

18

RACROUTE REQUEST=VERIFYX was failed by the installation exit routine.

1C

The user's access has been revoked.

24

The user's access to the specified group has been revoked.

28

OIDCARD parameter is required but not supplied.

2C

OIDCARD parameter is not valid for specified user.

30

The user is not authorized to the port of entry.

34

The user is not authorized to use the application.

38

SECLABEL checking failed.

Reason Code: Meaning
04: MLACTIVE requires a security label; none was specified.
08: Indicates the user is not authorized to the security label.
0C: The system was in multilevel secure status, and the dominance check failed.
10: Neither the user's nor the submitter's security label dominates. They are disjoint.
14: The client's security label is not equivalent to the server's security label.

3C

A VERIFYX error occurred in SAF.

Reason Code: Meaning
04: Old password required. Message IRR009I issued.
08: User ID required. Message IRR008I issued.
0C: Propagation checking could not complete. Failed to set up a recovery environment.

44

A default token is used as input token.

48

Indicates that an unprivileged user issued a RACROUTE REQUEST=VERIFYX in a tranquil state (MLQUIET).

4C

NODES checking failed.

Reason Code: Meaning
00: Submitter's node is not allowed access to execution node.
04: NJE failure: UACC of NONE for USERID type of NODES profile.
08: NJE failure: UACC of NONE for GROUP type of NODES profile.
0C: NJE failure: UACC of NONE for SECLABEL type of NODES profile.
10: NJE failure: No local submit node specified.
14: NJE failure: Reverification of translated values failed.

50

Indicates that a surrogate submit attempt failed.

Reason Code: Meaning
04: Indicates the SURROGAT class was inactive.
08: Indicates the submitter is not permitted by the user's SURROGAT class profile.
0C: Indicates that the submitter is not authorized to the security label under which the job is to run.

54

Indicates that a JESJOBS check failed.

5C

Indicates that an error occurred while retrieving data from the RACF database.

Reason Code: Meaning
0483yyyy: An error occurred while RACROUTE REQUEST=VERIFY was accessing the RACF data base. "yyyy" is the RACF manager return code associated with the abend that would have been issued.

64

Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=VERIFYX macro; however, the list form of the macro does not have the same release parameter. Macro processing terminates.

Example 1

The following example shows a RACROUTE REQUEST=VERIFYX coded for handling verification checking for a batch job that has been submitted with a USERID, GROUPID, SECLABEL, and PASSWORD. The UTOKEN area is filled with the verified job information.

   RACROUTE REQUEST=VERIFYX,SESSION=INTBATCH,          X
            PASSWRD=PASSWORD,TOKNOUT=TOKOUT,           X
            EXENODE=EXNOD,USERID=USER,                 X
            GROUP=GROUPID,SECLABL=SLBL,                X
            STOKEN=STOK,TRUSTED=NO,WORKA=RACWK,        X
            RELEASE=1.9
  ⋮
PASSWORD  DS  0CL9
PASSWL    DS  FL1'5'
PASSWT    DS  CL8'PWD01'

TOKOUT    DS  0CL80
TKOLEN    DS  XL1'50'   /* LENGTH - 80 DEC */
TKOVRS    DS  XL1'01'   /* VERSION 1       */
TKODATA   DS  CL78

EXNOD     DS  0CL9
EXNODL    DS  FL1'2'
EXNODT    DS  CL8'N1'

USER      DS  0CL9
USERL     DS  FL1'6'
USERT     DS  CL8'USER01'

GROUPID   DS  0CL9
GROUPIDL  DS  FL1'4'
GROUPIDT  DS  CL8'SYS1'

SLBL      DS  CL8'SYSLOW'

STOK      DS  CL80          /* OBTAINED BY PREVIOUS RACROUTE CALL */
RACWK     DS  CL512

Note: Additional keywords required by RACF to complete the request, such as WORKA, are specified on RACROUTE itself.