RACROUTE REQUEST=SIGNON (standard form)

The standard form of the RACROUTE REQUEST=SIGNON macro instruction 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=SIGNON

,APPL=`‘applname’`	`applname`: 1–8 character application name
,APPL=`applname addr`	`applname addr:` A-type address or register (2) – (12).

,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)
,TYPE=LISTCRT ,TYPE=LISTDEL ,TYPE=SIGNIN ,TYPE=SIGNOFF ,TYPE=QSIGNON

,LSTTYPE=ONFROM	Default: LSTTYPE=ONFROM

,MF=S

,VERBEXIT=`address of`	`exit addr`: A-type address or register (2) – (12)
`fullword`

If TYPE=SIGNIN is specified:

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

,ENVRIN=`envr data addr`	`envr data addr`: A-type address or register (2) – (12)

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

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

,VERBEXIT=`address of`	`address of fullword`: A-type address or register (2) – (12)
`fullword`

If TYPE=SIGNOFF is specified:

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

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

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

,VERBEXIT=`address of`	`address of fullword`: A-type address or register (2) – (12)
`fullword`	Note: This keyword is required on or before TYPE=SIGNOFF. Refer to VERBEXIT keyword description for more information.

If TYPE=QSIGNON is specified:

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

,ACEE=`address of`	`address of fullword`: A-type address or register (2) – (12)
`fullword`

,ENVROUT=`envr data`	`envr data addr`: A-type address or register (2) – (12)
`addr`

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

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

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

The parameters are explained as follows:

,ACEE=address of fullword

specifies the address of a fullword where a QSIGNON request is to store an ACEE pointer for a signed-on user. If the keyword is omitted (or zero), an ACEE is not returned. The caller is responsible for doing a RACROUTE REQUEST=VERIFY, ENVIR=DELETE to delete a returned ACEE when no longer needed.

,APPL=‘applname’

,APPL=applname addr

specifies the local LU name. The local LU name is an 8-character field which is left-justified and padded with blanks.

The APPL name is part of the key that uniquely identifies which signed-on list entries are being processed.

Note that an asterisk (*) should not be specified for the APPL name. It is not treated as a generic character, and will not match the application name when used in the key.

The maximum number of APPL names that RACF supports in the signed-on lists is 39.

,ENVRIN=envr data addr

specifies the data structure that contains the information required to re-create a security environment. The address points to a data structure defined in Table 1. See also the mapping for "SGNPL: RACROUTE REQUEST=SIGNON Parameter List (Request Section)" in z/OS Security Server RACF Data Areas. The data structure describes the storage location for the ENVR object. While the format of the data structure pointed to by ENVRIN is known to the RACROUTE invoker, the content of the object itself is defined by the external security product.

The ENVRIN keyword is provided to pass in a relocatable security environment or to manipulate a user security environment. You can specify ENVRIN on a RACROUTE REQUEST=SIGNON, TYPE=SIGNIN to mark a security environment so that future RACROUTE REQUEST=VERIFY, ENVIR=DELETE requests of that user security environment do not get audited.

To use ENVRIN on a RACROUTE REQUEST=SIGNON, TYPE=SIGNIN you must have previously obtained a relocatable user security environment by specifying ENVROUT on a prior service such as RACROUTE REQUEST=VERIFY, ENVIR=CREATE, or RACROUTE REQUEST=EXTRACT,TYPE=ENVRXTR.

,ENVROUT=envr data addr

specifies the data structure that is to hold the information used to describe a security environment.

This information can be used later on a service with the ENVRIN keyword such as RACROUTE REQUEST=VERIFY to recreate the security environment without causing I/O to the RACF Database. The address points to a data structure defined in Table 1. The data structure describes the storage location for the ENVR object. The key of the ENVR data structure is a single byte value that represents the associated ENVR object storage area. The low-order nibble of this value is the storage key. A key value of X'07' returns an ENVR object in key 07 storage.

While the format of the data structure pointed to by ENVROUT is known to the RACROUTE invokers, the content of the object itself is defined by the external security product.

Figure 1 and Table 1 represent the ENVR data structure for use with the ENVRIN and ENVROUT keywords. The data structure must start on a fullword boundary.

Figure 1. ENVR data structure

Table 1. Description of ENVR data structure
Description	Length (bytes)	ENVROUT usage	ENVRIN Usage
ENVR object length	4	Output	Input
ENVR object storage area length	4	Input/Output	Input
ENVR object storage area address	4	Input/Output	Input
ENVR object storage area subpool	1	Input	N/A
ENVR object storage area key	1	Input	N/A

The ENVR object storage area can be supplied by the caller or obtained by RACF. If supplied by the caller, it must be on a doubleword boundary and be associated with the job step task. If RACF obtains the storage area, it is on a doubleword boundary and is associated with the Job Step task. The storage will be allocated based on the mode of the caller (LOC=ANY for 31-bit callers and LOC=BELOW for 24-bit callers). The following table shows how the field values affect ENVROUT processing.

Table 2. ENVROUT Storage Area Processing
ENVR object storage area length	ENVR object storage area address	Result
Zero	Any value	RACF obtains minimum storage size needed to contain the ENVR Object. Storage size is returned in the ENVR Object storage area length. Storage address is returned in the ENVR Object storage area address.
Nonzero	Zero	RACF obtains storage size specified or the minimum storage size needed to contain the ENVR Object. Storage size is returned in the ENVR Object storage area length. Storage address is returned in the ENVR Object storage area address.
Nonzero	Nonzero	RACF attempts to use the storage area provided. If the area is too small to contain the ENVR object, RACF frees the storage area provided and obtains the minimum storage size needed to contain the ENVR object. Storage size is returned in the ENVR object storage area length. Storage address is returned in the ENVR object storage area address.

Storage is obtained and freed in the subpool and key specified in the ENVR data structure.

Since the ENVR object length is returned to the caller, the ENVR object can be moved from one storage area to another. This value is supplied as an output to the caller. RACF does not attempt to use this value in either ENVROUT or ENVRIN processing.

The caller is responsible for freeing the ENVR object storage area when it is no longer needed. The length, address, subpool, and key to be used when doing the FREEMAIN are contained in the ENVR data structure.

The ENVR object returned by ENVROUT= is a relocatable object that can be copied from one storage location to another. The returned ENVR object, or a copy of the returned ENVR object, can be specified as input to the RACROUTE interface using the ENVRIN keyword, or to the initACEE callable service using the ENVR_in parameter.

The ENVR object can be passed to other systems, but this should be done with great care. The ENVR object should not be saved for a long period of time before being used as ENVRIN, and it should not be passed to systems that have different security information. The other systems should share the RACF database and have compatible RACF installation exits and class descriptor tables.

,GROUP=address

specifies the group provided by 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.

The GROUP name is part of the key which uniquely identifies which signed-on list entries are being processed.

Note:

For TYPE=SIGNIN, if GROUP is not specified, the signed-on list entry contains blanks in the GROUP field.
For TYPE=SIGNOFF, if GROUP is not specified, the value used to match entries in the signed-on-from list is defaulted to blanks.
For TYPE=SIGNOFF, the GROUP name can be specified as * to indicate a “don't care” condition that allows a match with any GROUP name in the list. All entries matching USERID are removed from the signed-on list regardless of GROUP.

,LSTTYPE=ONFROM

specifies that you are requesting the operation for the signed-on-from list.

Although LSTTYPE has a default of ONFROM, you should specify this keyword since omitting it causes an MNOTE and an assembler return code of 4.

,POE=port-of-entry address

specifies the address of the port of entry into the system. The address points to the partner LU name. The port of entry is an 8-character field which is left-justified and padded with blanks.

The POE name is part of the key which uniquely identifies which signed-on list entries are being processed.

Note: For LISTDEL and SIGNOFF, the POE name can be specified as *; this indicates a “don't care” condition that allows a match with any POE name in the list.

,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. Note that an asterisk (*) should not be specified for POENET as it is not treated as a generic character and results in an incorrect network qualified LU name. To specify the POENET parameter, you must specify RELEASE=2.6.

,SECLABL=address

specifies the address of an 8-byte field which contains the user's security label. The field is left-justified and padded to the right with blanks.

Note: If SECLABL is not specified, the signed-on list entry contains blanks in the SECLABL field.

,TOKNOUT=address

specifies the address of a user-provided area in which an output UTOKEN is to be built. The UTOKEN along with the APPL parameter can be used on a subsequent RACROUTE REQUEST=VERIFY, ENVIR=CREATE to re-create the security environment. However, using ENVROUT to obtain a copy of the security environment and then using ENVRIN to provide this security environment on a subsequent RACROUTE REQUEST=VERIFY provides better performance if the requirements for using ENVRIN are met.

,TYPE=LISTCRT

,TYPE=LISTDEL

,TYPE=SIGNIN

,TYPE=SIGNOFF

,TYPE=QSIGNON

specifies the action to be performed for the specified APPL and POE.

LISTCRT

Create and initialize a signed-on-from list to represent users signed on from a specified POE to a specified APPL; use of LISTCRT is optional, as SIGNIN can perform this function automatically.

LISTDEL

Delete a signed-on-from list. TYPE=LISTDEL can be called while running in SRB mode.

QSIGNON

Determine if the specified user is in the signed-on-from list and optionally return data using the ACEE, ENVROUT, and TOKNOUT keywords.

SIGNIN

Add a user to the signed-on-from list; additionally, if no signed-on-from list exists for the specified APPL and POE, SIGNIN creates and initializes one.

This allows signed-on-from lists to be created implicitly (on the first TYPE=SIGNIN request), or explicitly (using TYPE=LSTCRT).

SIGNOFF

Remove users from signed-on-from lists associated with the specified APPL.

The following table indicates the various combinations you can specify to remove entries from the signed-on-from list(s). On the TYPE=SIGNOFF request, for the POE, USERID, and GROUP keywords you can do one of the following:

Specify the keyword with an exact value.
Specify the keyword as * (“don't care.”).

In the following table, M indicates the keyword was specified with an exact value (which would be blanks for the GROUP keyword if it is not specified); * indicates that all values for that keyword are considered a match.

Table 3. Delete Actions Based on Supplied Input
POE or POENET.POE	USERID	GROUP	DELETES…
*	*	*	ALL entries
*	*	M	Entries matching GROUP
*	M	*	Entries matching USERID
*	M	M	Entries matching USERID and GROUP
M	*	*	Entries matching POE
M	*	M	Entries matching POE and GROUP
M	M	*	Entries matching POE and USERID
M	M	M	Entries matching POE, USERID and GROUP

,USERID=address

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.

The value of USERID is part of the key which is used to uniquely identify which signed-on list entries are being processed.

Note: For TYPE=SIGNOFF, USERID can be specified as * to indicate a “don't care” condition that allows a match with any USERID in the list. All entries matching GROUP are removed from the signed-on list regardless of USERID.

,VERBEXIT=address of fullword

specifies the address of an address of a user exit routine which receives control from RACF during SIGNOFF processing. The user exit is responsible for issuing the ALLOCATE of the SIGNOFF TP for the partner LU. When the user exit receives control from RACF, register 1 points to a parameter list mapped by ICHSGX1P, the mapping macro for the TYPE=SIGNOFF VERBEXIT. See "SGX1P: RACROUTE REQUEST=SIGNON Parameter List Mapping" in z/OS Security Server RACF Data Areas.

RACROUTE REQUEST=SIGNON, TYPE=SIGNOFF processing expects to pass control to a VERBEXIT. You can supply the VERBEXIT when the signed-on list is initially created or on a TYPE=SIGNOFF request; if specified on both, the VERBEXIT specified with TYPE=SIGNOFF is used.

If no exit address (or an address of zero) is passed, the signoff routine for the partner LU can not be invoked. The RACROUTE return code (08,10,30) indicates a failure. However, the entries are deleted from the list.

,MF=S

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

Return codes and reason codes

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

If the “don't care” character is specified in one or more keywords on a SIGNOFF and you encounter an internal error reason code, it might be possible that all user entries matching your keyword specification were not deleted. This can be verified using RACF's DISPLAY SIGNON operator command. If you find you still have user entries to delete, you might want to rerun the request, try RACF's SIGNOFF operator command, or try the request multiple times for specific user entries. If these still do not remove your user entries, you first need to work with the IBM® support center to resolve the underlying problem.

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=SIGNON has completed successfully

RACF RC

Meaning

00

The RACROUTE REQUEST=SIGNON function was performed.

Reason Code: Meaning
00: Indicates a normal completion.
04: TYPE=SIGNOFF requested, user not found for specified port of entry.
08: TYPE=LISTDEL requested, list not found.
0C: TYPE=LISTCRT requested, list already exists.
10: TYPE=SIGNIN requested, user already signed on.
14: TYPE=LISTDEL requested, error physically deleting list(s). Data space storage could not be freed but RACF considers the list to be deleted.

04

Requested function could not be completed. No RACF decision.

RACF RC

Meaning

00

RACF could not process RACROUTE REQUEST=SIGNON request.

Reason Code

Meaning

00

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

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®.
Environment is not MVS/ESA 4.2.2 or later.
A version of RACF earlier than 1.9.2 is installed.
RACF is not installed.
RACF is not active.

04

RACF could not complete processing of SIGNON request. If the reason code indicates an internal error, contact your support center.

Reason Code

Meaning

04

Unable to establish recovery or an abend occurred.

08

RACF subsystem initialization problem. One of the following has occurred.

RACF subsystem not started at IPL,
RACF subsystem failed to initialize correctly, or
RACF subsystem was abnormally stopped.

0C

Internal error: Null ID found.

10

STORAGE PROBLEM—The underlying data space storage management request failed.

14

STORAGE UNAVAILABLE—No more data space storage available for expanding the PV list.

18

Internal error: INVALID LENGTH Exception

1C

Internal error: INCONSISTENCY Exception 1.

24

Internal error: INCONSISTENCY Exception 2.

28

Internal error: OPERATION REJECTED Exception.

2C

Internal error: INVALID CONTROL DATA Exception.

34

Local lock was held by invoker.

38

Lock prematurely released, (i.e. not by obtainer).

3C

Internal error: Unexpected Exception.

40

Internal error: INVALID OFFSET Exception.

44

Internal error: INVALID KEY DEFINITION Exception.

48

Exceeded maximum number of APPL names for the signed-on lists.

08

Requested function has failed.

RACF RC

Meaning

08

User information not returned on a TYPE=QSIGNON request.

Reason Code: Meaning
04: User not found in signed-on list.

0C

The VERBEXIT returned a nonzero return code. RACF has propagated the return code (xx) back to the caller as a reason code.

Reason Code: Meaning
xx: Defined and documented by APPC/MVS VERBEXIT or other VERBEXIT being used. For possible values of xx, refer to documentation of VERBEXIT being used.

Note: List processing occurs before VERBEXIT processing. The user is deleted from the list prior to this failure.

10

Parameter list error

Reason Code: Meaning
04: No APPL LU name specified.
08: No POE LU name specified.
0C: Blank or null APPL LU name specified.
10: Blank or null POE LU name specified.
14: No TYPE was specified, or type was specified to the macro incorrectly.
18: USERID was not specified on a SIGNIN, SIGNOFF, or QSIGNON request.
1C: Blank or null USERID was specified on a SIGNIN, SIGNOFF, or QSIGNON request.
20: USERID length specified is not valid. The 1-byte length field specified was less than or equal to zero, or was greater than eight.
24: GROUP length specified is not valid. The 1-byte length field specified was less than or equal to zero, or was greater than eight.
28: The ENVR Object storage area address specified with the ENVRIN keyword is 0 (TYPE=SIGNIN), or the ENVR Object storage area address specified is not on a doubleword boundary (TYPE=SIGNIN or TYPE=QSIGNON).
2C: The length specified for the ENVR Object is greater than the length of the storage containing the ENVR Object for the ENVRIN keyword on a SIGNIN.
30: No VERBEXIT address found. The VERBEXIT must have been provided by the time the SIGNOFF is performed. Must be specified either when the list is initially created (by LISTCRT or SIGNIN), or on the SIGNOFF request.
Note: List processing occurs before VERBEXIT processing. The user is deleted from the list prior to this failure.
34: Either the POE, USERID, or GROUP keyword was incorrectly specified as * on a LISTCRT or a SIGNIN request. A “don't care” character can only be specified on a SIGNOFF or LISTDEL request.

14

RACROUTE REQUEST=VERIFY error encountered during QSIGNON.

Reason Code: Meaning
XXXXYYYY: For the explanation of this reason code, refer to RACROUTE REQUEST=VERIFY Return codes and reason codes. Under SAF return code of X'08', see RACF return code YYYY and RACF reason code XXXX

Example 1

Sign a user into the signed-on-from list (standard form of the macro).

         RACROUTE REQUEST=SIGNON,                                      X
               RELEASE=1.9.2,                                          X
               WORKA=RACRWRKA,                                         X
               TYPE=SIGNIN,                                            X
               LSTTYPE=ONFROM,                                         X
               APPL=MYAPPL,                                            X
               POE=MYPOE,                                              X
               USERID=MYUSERID,                                        X
               GROUP=MYGROUP,                                          X
               ENVRIN=ENVRDATA,                                        X
               MF=S

Example 2

List form of a RACROUTE REQUEST=SIGNON.

LISTBEG  RACROUTE REQUEST=SIGNON,                                      X
               RELEASE=1.9.2,                                          X
               WORKA=RACRWRKA,                                         X
               TYPE=SIGNIN,                                            X
               LSTTYPE=ONFROM,                                         X
               APPL=MYAPPL,                                            X
               POE=MYPOE,                                              X
               USERID=MYUSERID,                                        X
               GROUP=MYGROUP,                                          X
               ENVRIN=ENVRDATA,                                        X
               MF=L

Example 3

Use QSIGNON to determine if a user is signed in, and if so, obtain an ENVROUT object (execute form of the macro).

         RACROUTE REQUEST=SIGNON,                                      X
               RELEASE=1.9.2,                                          X
               WORKA=RACRWRKA,                                         X
               TYPE=QSIGNON,                                           X
               LSTTYPE=ONFROM,                                         X
               ENVROUT=ENVRDATA,                                       X
               MF=(E,LISTBEG)

                  DATA DECLARATIONS

            DS    0D
RACRWRKA    DC    128F'0'          512 BYTE RACROUTE WORK AREA
MYUSERID    DC    AL1(7)           LENGTH OF USERID
            DC    CL7'DANHERE'     THE ACTUAL USERID
MYGROUP     DC    AL1(6)           LENGTH OF GROUP NAME
            DC    CL6'DEPT52'      THE ACTUAL GROUP NAME
MYSECLABL   DC    CL8'SECRET'      SECURITY LABEL
MYTOKNOUT   DS    10D              80 BYTES FOR RETURNED TOKEN
MYVERBEXIT  DC    A(0)             ADDRESS OF VERBEXIT
MYPOE       DC    CL8'DANIWS'      PARTNER LU NAME
MYAPPL      DC    CL8'MVSHOST1'    LOCAL LU NAME
MYACEE      DC    A(0)             ADDRESS OF RETURNED ACEE
ENVRDATA    DS    0F
            DC    F'0'             ENVR LENGTH
            DC    F'4096'          DESIRED ENVR STORAGE AREA SIZE
            DC    A(0)             LET RACF OBTAIN IT
            DC    AL1(1)           IN SUBPOOL 1
            DC    AL1(1)           IN KEY 1