RACROUTE REQUEST=TOKENXTR (standard form)

The standard form of the RACROUTE REQUEST=TOKENXTR 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).



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

␢	One or more blanks must precede RACROUTE.

RACROUTE

␢	One or more blanks must follow RACROUTE.


REQUEST=TOKENXTR

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

,ACEE=`acee addr`	`acee addr`: A-type address or register (2) - (12)

,XMREQ=YES	Default: XMREQ=NO
,XMREQ=NO

,MF=S

The parameters are explained as follows:

,ACEE=acee addr

specifies the address of the ACEE from which information is to be extracted. If you do not specify the ACEE keyword, TOKENXTR extracts the information it needs from the TCBSENV field of the task control block if it is nonzero; if it is zero, TOKENXTR extracts information it needs from the ASXBSENV field.

Note: If no ACEE is specified or found, a token is returned with the following information:

The user ID is ‘*’.
A default TOKEN flag is on.
An undefined user flag is on.
A flag indicating this token is created for a pre-RACF 1.9 system.

If there is a down-level ACEE, a token is returned with indication of a pre-RACF 1.9 system; certain fields might be blank or zero, such as SECLABEL, submitting user ID, and other information not available for a down-level ACEE.

Restriction: For a nested ACEE, token information is extracted only from the primary identity, not from the embedded daemon identity.

,TOKNOUT=return token addr

specifies the address where the requester wants TOKENXTR to return the UTOKEN that was extracted from the ACEE. The first byte of storage at the address specified must contain the number of bytes of available storage. The second byte must contain the format version of the token.

,XMREQ=NO

,XMREQ=YES

indicates whether or not the caller is in cross-memory mode.

NO: Indicates that the caller is not in cross-memory mode. (NO is the default.)
YES: Signifies that the caller might (but need not) be running in cross-memory mode.

The caller must be in primary ASC mode when RACROUTE is issued.

,MF=S

specifies the standard form of the RACROUTE REQUEST=TOKENXTR 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=TOKENXTR has completed successfully.

RACF RC

Meaning

00

Reason described by the following hex reason codes:

Reason Code: Meaning
00: The request was successful.
04: ACEE supplied is not valid (down level). Information is defaulted if it could not be extracted.
08: No ACEE available. Information is defaulted if it could not be extracted.
0C: TOKNOUT area length was too large.

04

RACROUTE REQUEST=TOKENXTR did not complete successfully.

RACF RC

Meaning

00

Reason described by the following hex reason codes:

Reason Code: Meaning
00: XMREQ=YES was specified in a non-MVS/ESA environment.

Example

This example shows how to extract information from the ACEE to determine which type of label to put on printed output data. See the example topic for TOKENMAP for an example of converting the token returned by TOKENXTR into readable form.

RACROUTE  REQUEST=TOKENXTR,TOKNOUT=TOKOUT,                            X
          WORKA=RACWK,                                                X
          RELEASE=1.9
  ⋮
RACWK     DS  CL512
TOKOUT    DS  0CL80
          DC  XL2'5001' /*FIRST 2 BYTES SPECIFY THE TOKEN VERSION */
          DC  XL78'0'