RACROUTE REQUEST=EXTRACT (standard form)

The standard form of the RACROUTE REQUEST=EXTRACT macro is written as follows.

Note: For a description of additional parameters that are required and additional keywords that you can code on the RACROUTE request, but that are not specific to this request type, see RACROUTE (standard form).
Note:

RACROUTE REQUEST=EXTRACT requires an ACEE. For most applications, the system creates an ACEE to represent the active user. However, for special cases where no ACEE exists, the invoker must create one before invoking RACROUTE REQUEST=EXTRACT.

The most common way to create an ACEE is to issue a RACROUTE REQUEST=VERIFY, specifying ENVIR=CREATE. After all RACROUTE invocations are complete, the invoker should issue RACROUTE REQUEST=VERIFY with ENVIR=DELETE specified to delete the ACEE previously created.

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 ensure proper processing in recovery situations.

Macro parameter Classification and notes
   name name: Symbol. Begin name in column 1.
   
One or more blanks must precede RACROUTE.
   
RACROUTE  
   
One or more blanks must follow RACROUTE.
   
REQUEST=EXTRACT  
   
,TYPE=EXTRACT  
,TYPE=EXTRACTN  
,TYPE=REPLACE  
,TYPE=ENCRYPT  
,TYPE=ENVRXTR  
   
    ,ACEE=acee addr acee addr: A-type address or register (2) – (12)
   
    ,ENTITY=profile profile name addr: A-type address or register (2) – (12)
    name addr  
    ,ENTITYX=extended extended profile name addr: A-type address or register (2) – (12)
    profile name addr  
   
    ,FLDACC=YES  
    ,FLDACC=NO Default: FLDACC=NO
   
    ,GENERIC=ASIS Default: GENERIC=ASIS
    ,GENERIC=YES  
   
    ,VOLSER=vol addr vol addr: A-type address or register (2) – (12)
   
    ,MF=S  
   
If TYPE=EXTRACT or EXTRACTN is specified
   
    ,BRANCH=YES  
    ,BRANCH=NO Default: BRANCH=NO
   
    ,CLASS=‘class name’ class name: 1–8 character name
    ,CLASS=class name addr class name addr: A-type address or register (2) – (12)
  Default: CLASS=‘USER’
   
    ,DATEFMT=YYYYDDDF  
    ,DATEFMT=YYDDDF Default: DATEFMT=YYDDDF
   
    ,DERIVE=YES See explanation of keyword.
  Default: Normal processing
   
    ,FIELDS=field addr field addr: A-type address or register (2) – (12)
   
    ,MATCHGN=YES  
    ,MATCHGN=NO Default: MATCHGN=NO
   
    ,SEGMENT=‘segment segment name: 1–8 character name
    name’  
    ,SEGMENT=segment segment name addr: A-type address or register (2) – (12)
    name addr  
   
    ,SUBPOOL=subpool subpool number: Decimal digit 0–255
    number Default: See the explanation for SUBPOOL keyword.
   
If TYPE=REPLACE is specified:
   
    ,CLASS=‘class name’ class name: 1–8 character name
    ,CLASS=class name addr class name addr: A-type address or register (2) – (12)
  Default: CLASS=‘USER’
   
    ,DATEFMT=YYYYDDDF  
    ,DATEFMT=YYDDDF Default: DATEFMT=YYDDDF
   
    ,FIELDS=field addr field addr: A-type address or register (2) – (12)
   
    ,SEGDATA=segment segment data addr: A-type address or register (2) – (12)
    data addr  
   
    ,SEGMENT=‘segment segment name: 1–8 character name
    name’  
    ,SEGMENT=segment segment name addr: A-type address or register (2) – (12)
    name addr  
   
If TYPE=ENCRYPT is specified:
   
    ,BRANCH=YES  
    ,BRANCH=NO Default: BRANCH=NO
   
    ,ENCRYPT=(data data addr: A-type address or register (2) – (12)
    addr,DES)  
    ,ENCRYPT=(data  
    addr,HASH)  
    ,ENCRYPT=(data  
    addr,INST)  
    ,ENCRYPT=(data  
    addr,STDDES)  
Note: If TYPE=ENCRYPT is specified, the only other allowable parameters are ENTITY, ENTITYX, RELEASE, ENCRYPT, and BRANCH, with ENCRYPT being required.
   
If TYPE=ENVRXTR is specified:
   
    ,ENVROUT=envr data envr data addr: A-type address or register (2) – (12)
    addr  
Note: When TYPE=ENVRXTR is specified, only the keywords ACEE and ENVROUT are recognized, with ENVROUT being required.
The parameters are explained as follows:
,ACEE=acee addr
Specifies an alternate ACEE for RACF to use rather than the current ACEE. For example, for the USER class or for CLASS= not specified, if the ENTITY or ENTITYX parameter has not been specified, or ENTITYX has been specified with zero for the buffer length and zero for the actual entity name length, RACF refers to the ACEE during extract processing of user data.

If you want to use the ACEE parameter, you must specify RELEASE=1.8 or later.

For TYPE=ENVRXTR, if the caller is in cross-memory mode, the specified ACEE must reside in the HOME address space.

For TYPE=EXTRACT,BRANCH=YES, if the caller is in cross-memory mode, the specified ACEE must reside in the PRIMARY address space.

,BRANCH=YES
,BRANCH=NO
Specifies whether you want RACF to use a branch entry.

The following applies to TYPE=EXTRACT with BRANCH=YES:

The RACROUTE REQUEST=EXTRACT macro supports an SRB-compatible branch entry when you specify BRANCH=YES and TYPE=ENCRYPT or BRANCH=YES and TYPE=EXTRACT with no change in function.

Cross memory mode is supported to obtain general resource profiles.

  • General resource profiles that can be brought into storage are candidates for branch entry EXTRACT.
    • You can use the SETROPTS RACLIST command or RACROUTE REQUEST=LIST, GLOBAL=YES command to create a global listing of profiles in a data space. You can use this list only in the address space it was issued from.
    • You can also use RACROUTE REQUEST=LIST, GLOBAL=NO to create a listing of profiles in the user's address space, but this does not create a global listing of profiles.
  • User data that is defaulted from the ACEE is a candidate for branch entry EXTRACT. This occurs when the USER class is specified or CLASS= is not specified, no ENTITY or ENTITYX is specified or ENTITYX is specified with zero for buffer length and zero for the actual entity name length, and no SEGMENT or FIELDS information is specified. The user's ID and default connect group are extracted from the current ACEE.

    If the user's primary and secondary languages are available, they are also extracted from the current ACEE, along with a code (U) indicating that the reported languages are defined in the user's profile. If the user's primary and secondary languages are not available in the user's profile, the installation default primary and secondary languages that are set by SETROPTS are returned, along with a code (S) indicating that the reported languages are the installation default.

    Additionally, if the user's work attributes (WORKATTR) information is available, it is also extracted from the ACEE. For the format of the WORKATTR information that is returned from the ACEE, see RXTW: RACROUTE REQUEST=EXTRACT Result Area Mapping in z/OS Security Server RACF Data Areas.

    Note: Start of change To obtain user-related custom fields that are available in the user's ACEE, applications must use the R_GetInfo callable service (IRRSGI00), which supports both supervisor and problem state callers. For more information, see R_GetInfo (IRRSGI00): Get security server fields in z/OS Security Server RACF Callable Services.End of change
  • RACF can extract the following fields of the general-resource profile:
    NOT Programming Interface Information

    CATEGORY, IPLOOK, MEMCNT, MEMLST, and NUMCTGY. Exception: The MEMCNT and MEMLST fields of the SECLABEL profile are programming interfaces.

    End NOT Programming Interface Information

    ACL2, ACL2ACC, ACL2CNT, ACL2NAME, ACL2RSVD, ACL2UID, ACLCNT, APPLDATA, AUDIT, CONVSEC, CSFAUSE, CSFSCPR, CSFSCPW, CSFSEXP, CSFSCLBS, CSFSCLCT, CSFSKLBS, CSFSKLCT, DIDCT, DIDLIST1, GAUDIT, INSTDATA, KEYDATE, KEYINTVL, LEVEL, LOGDAYS, LOGTIME, LOGZONE, NOTIFY, OWNER, SECLABEL, SECLEVEL, SESSKEY, SLSFLAGS, UACC, USERACS, USERID, and WARNING.

  • RACF searches RACLISTed profiles in the following order:
    • Those off the ACEE (if ACEE is specified),
    • Those off the TCB ACEE in the PRIMARY address space,
    • Those off the ASXB ACEE in the PRIMARY address space.
    If the profile is not found off any ACEE, RACF searches globally RACLISTed profiles.

To specify the BRANCH keyword, you must specify Release=1.9 or later.

,CLASS=‘class name’
,CLASS=class name addr
Specifies the class that contains the entity. The class name can be USER, GROUP, CONNECT, DATASET, or any general-resource class defined in the class descriptor table.

If you specify CLASS, you must specify RELEASE=1.8 or later.

,DATEFMT=YYYYDDDF
,DATEFMT=YYDDDF
Specifies the format of the date that you want to extract or replace. If you specify DATEFMT=YYYYDDDF and TYPE=EXTRACT or EXTRACTN, RACF retrieves date fields in the format ccyydddF where cc=19 or cc=20, unless the date being retrieved is in a uninitialized state in the RACF database, in which caseX'0000000F' or X'FFFFFFFF' is returned. If TYPE=REPLACE is specified, RACF accepts dates in the format ccyydddF where cc=19 or cc=20. When accepting a date as input to put into the database, RACF validates that cc=19 or cc=20, and that for
cc=19, 70 <  yy <= 99
and for
cc=20, 00 <= yy <= 70.

If you specify DATEFMT=YYDDDF, RACF retrieves and accepts dates in the normal three-byte format.

To specify the DATEFMT keyword, you must specify Release=1.9.2 or a later release number.

,DERIVE=YES
Specifies that the desired field is to be obtained from the DFP segment of the appropriate profile. To specify DERIVE, you must also specify RELEASE=1.8.1 or later.
DERIVE requests are limited to the DFP segment of the DATASET and USER profiles. The following explains the DERIVE processing for both a DATASET and a USER request:
  • DATASET

    Specifying the DERIVE=YES keyword with CLASS=DATASET and FIELDS=RESOWNER causes RACF to perform additional processing other than simply extracting the data set resource owner from the data set profile.

    DFP uses this retrieved information for authority checking when allocating a new data set.

    To process the request, RACF first attempts to extract the RESOWNER field from the DATASET profile that is specified by the ENTITY or ENTITYX keyword. If the profile exists and the RESOWNER field contains data, RACF checks to see whether that data is the user ID of a user or group that is defined to RACF. If so, RACF returns that user ID along with a reason code that indicates whether the user ID is that of a user or a group.

    If RACF does not find a profile that matches the DATASET name that is specified by the ENTITY or ENTITYX keyword, RACF attempts to locate the generic DATASET profile that protects that DATASET name.

    If it finds the generic profile, and the RESOWNER field contains data, RACF checks to see whether that data is the user ID of a user or a group that is currently defined to RACF. If so, RACF returns that user ID along with a reason code that indicates whether the user ID is that of a user or a group.

    If RACF does not find a generic profile, or the retrieved data is not a user or group, RACF returns the high-level qualifier from the name that is specified on the ENTITY ENTITYX keyword along with a reason code that indicates whether that high-level qualifier matches a defined user or group, or neither.

    You specify a DERIVE request for RESOWNER as follows:
     RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT,                            X
     ENTITY=DSNAME,                                                    X
     VOLSER=MYDASD,                                                    X
     CLASS='DATASET',                                                  X
     FIELDS=RESFLDS,                                                   X
     SEGMENT='DFP',                                                    X
     DERIVE=YES,                                                       X
     WORKA=RACWK,                                                      X
     RELEASE=1.8.1
     ⋮
     DSNAME   DC CL44'USER1.DATASET'
     MYDASD   DC CL6'DASD1'
     RESFLDS  DC A(1)
              DC CL8'RESOWNER'
     RACWK    DC CL512
    Note: You must specify all the keywords in the example for the DERIVE request to work.
  • USER

    The purpose of specifying the DERIVE=YES keyword with CLASS=USER is to obtain the desired DFP field information (STORCLAS, MGMTCLAS, DATACLAS or DATAAPPL) from the profile of the user. If the user's profile does not contain the desired DFP fields, RACF goes to the user's default group and attempts to obtain the information for the remaining fields from the GROUP profile (the remaining fields being those that do not contain information in the USER profile).

    You specify a DERIVE request for information from a USER profile as follows:
     RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT,                             X
     ENTITY=USER01,                                                     X
     CLASS='USER',                                                      X
     FIELDS=STRFLDS,                                                    X
     SEGMENT='DFP',                                                     X
     DERIVE=YES,                                                        X
     WORKA=RACWK,                                                       X
     RELEASE=1.8.1
     ⋮
     USER01   DC CL8'USER01'
     STRFLDS  DC A(1)
              DC CL8'STORCLAS'
     RACWK    DC CL512

RACF processes the DERIVE keyword if it is specified with the DATASET or USER class. In addition, for DERIVE processing to occur, SEGMENT=DFP and RELEASE=1.8.1 or later must also be specified.

,ENCRYPT=(data addr,DES)
,ENCRYPT=(data addr,HASH)
,ENCRYPT=(data addr,INST)
,ENCRYPT=(data addr,STDDES)
Specifies the user-authentication key and authentication method.
Note:
  • If the password was shipped from another system, the encryption method must be the same on all systems using the password. For example, the RACF password authentication exits, ICHDEX01 and ICHDEX11, must be identical on all systems.
  • If SETROPTS PASSWORD(ALGORITHM(KDFAES)) is active and a password is being encrypted for subsequent input to RACROUTE REQUEST=VERIFY or RACROUTE REQUEST=VERIFYX with ENCRYPT=NO, then the password must be encoded using the DES method to be evaluated successfully. If a password is being encrypted for comparison with a password extracted using RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT, the comparison fails if the extracted password is encrypted using the KDFAES algorithm, even if the clear text is correct.
Specifying zero for the 1-byte length that is associated with the user-authentication key has the same effect as not specifying the keyword. Upon return to the caller, the first subparameter contains the address of an area that contains a 1-byte length followed by the product of the authentication process. Neither the address itself nor the length is changed. Also, data is one-way transposed; that is, no facility is provided to recover the data in readable form.
  • ,ENCRYPT=(data addr,DES)

    Specifies the user-authentication key and the National Bureau of Standards Data Encryption Standard (DES) encryption method. The address points to a 1-byte length followed by from 1 to 255 bytes of text to be used as the key for encryption. The second subparameter specifies the RACF DES algorithm (the RACF variation of DES). When the DES algorithm is used, RACF uses the variable-length user-authentication key to encrypt eight bytes of clear-text data pointed to by the ENTITY or ENTITYX parameter, or by the user ID from the current ACEE (if no ENTITY or ENTITYX is specified or if ENTITYX is specified with zero for the buffer length and zero for the actual entity-name length).

    RACF uses the first eight bytes of clear-text data pointed to by the ENTITY or ENTITYX parameter, or the user ID specified in the ACEE. All other text is ignored.

  • ,ENCRYPT=(data addr,HASH)

    Specifies the user-authentication key and the RACF hashing algorithm. The address points to a 1-byte length followed by from 1 to 255 bytes of text to be used as the user-authentication key. The second subparameter specifies the RACF hashing algorithm. When this hashing algorithm is used, the user-authentication key is masked instead of encrypted.

  • ,ENCRYPT=(data addr,INST)

    Specifies the user-authentication key and the INST authentication method. The address points to a 1-byte length followed by from 1 to 255 bytes of text to be used as the key for authentication. The second subparameter specifies whatever scheme that the installation is using (INST value). When the INST algorithm is used, RACF passes to the installation-defined algorithm the variable-length user-authentication key and the eight bytes of clear-text data pointed to by the ENTITY or ENTITYX parameter, or by the user ID from the current ACEE (if no ENTITY or ENTITYX is specified or if ENTITYX is specified with zero for the buffer length and zero for the actual entity-name length).

    If there is no installation-defined authentication method present, RACF uses the DES encryption method. RACF uses the first eight bytes of clear-text data pointed to by the ENTITY or ENTITYX parameter, or the user ID specified in the ACEE. All other text is ignored.

  • ,ENCRYPT=(data addr,STDDES)

    Specifies the user-authentication key and the STDDES authentication method. The address points to a 1-byte length followed by eight bytes of text to be used as the key for authentication. The second subparameter specifies the NBS DES algorithm. When the STDDES algorithm is used, RACF uses the 8-byte user authentication key to encrypt eight bytes of clear-text data pointed to by the ENTITY or ENTITYX parameter, or the user ID from the current ACEE if no ENTITY or ENTITYX is specified or if ENTITYX is specified with zero for the buffer length and zero for the actual entity-name length.

    The authentication key must be eight bytes. Any other length for the key results in a parameter-list error. RACF uses the first eight bytes of clear-text data pointed to by the ENTITY or ENTITYX parameter, or the user ID specified in the ACEE. All other text is ignored.

,ENTITY=profile name addr
,ENTITYX=extended profile name addr
Specifies the address:
  • ,ENTITY=profile name addr

    For Release 1.7 or earlier (limited to USER), specifies the address of an area eight bytes long that contains the resource name (user ID for CLASS=USER) for which profile data is to be extracted, or the user ID to be used when encoding. The name must be left-justified in the field and padded with blanks. If this parameter is not specified for TYPE=EXTRACT, a default value of zero indicates that RACF should use the user ID provided in the ACEE operand. For TYPE=REPLACE, the parameter must be specified. If CLASS=USER is coded, information from the ACEE control block is returned in the result area.

    For Release 1.8 and later, specifies the address of a resource name for which profile data is to be extracted or replaced for TYPE=EXTRACT, or REPLACE, or the clear-text data to be processed for TYPE=ENCRYPT. The area is 8 bytes long for USER and GROUP, 17 bytes long for CLASS=CONNECT, and 44 bytes long for DATASET. The lengths of all other profile names are determined by the class descriptor table. The name must be left-justified in the field and padded with blanks. If this parameter is not specified for TYPE=EXTRACT, a default value of zero indicates that RACF should use the user ID provided in the ACEE operand. For TYPE=REPLACE, the parameter must be specified. If CLASS=USER is coded, information from the ACEE control block is returned in the result area.

    Note: When you specify MATCHGN=YES, if your RACF installation is not using the restructured-database format and the length of an entity name for a general-resource class is longer than 39 characters, RACF uses generic profiles to match the name.
  • ,ENTITYX=extended profile name addr specifies the address of a structure that consists of two 2-byte length fields, followed by the entity name.
    • The first 2-byte field specifies a buffer length that can be from 0 to 255 bytes. This length field refers to the length of the buffer that contains the entity name; it does not include the length of either length field.
    • The second 2-byte field specifies the actual length of the entity name. This length field includes the length of the actual name without any trailing blanks; it does not include the length of either length field.
    These two length fields can be used in several different ways:
    • If you know the length of the entity name, you can specify 0 in the first field and the length of the entity name in the second field. When you specify the second field, note that each byte counts. This means that the entity name that you specify must match exactly the entity name on the RACF database.
    • If you choose to place the entity name in a buffer area, specify the length of the buffer in the first field. For the second field, do one of the following:
      • If you know the length of the entity name, specify the length in the second field. The length of the first field can be from 0–255 bytes, but must be equal to or greater than the length of the second field.
      • If you do not know the length of the entity name, specify 0 in the second field, and have RACF determine the number of characters in the entity name.
    If this parameter is not specified or is specified in one of the following formats, a default value of zero indicates that RACF should use the user ID from the current ACEE. These are the only two situations in which specifying zero for the buffer length and zero for the actual entity-name length does not result in a parameter-list error.
    • Zero is specified for the buffer length and zero is specified for the actual entity-name length for TYPE=ENCRYPT.
    • Zero is specified for the buffer length and zero is specified for the actual entity-name length for TYPE=EXTRACT with USER being specified for the class or CLASS= being unspecified.
    Note:
    1. When you specify MATCHGN=YES, if your RACF installation is not using the restructured-database format and the length of an entity name for a general-resource class is longer than 39 characters, RACF uses generic profiles to match the name.
    2. Programs using RACROUTE REQUEST=EXTRACT and ENTITY=, and either TYPE=EXTRACTN or TYPE=EXTRACT (with MATCHGN=YES) with an ENTITY buffer shorter than the class's MAXLENX value, might experience unpredictable results if the programs retrieve a profile name longer than the class's MAXLNTH value that does not fit within the buffer. Errors might include immediate 0C4 abends due to overlays of program storage. (MAXLNTH and MAXLENX are operands on the ICHERCDE macro. See z/OS Security Server RACF Macros and Interfaces for further information about the ICHERCDE macro.)

Guideline: Use ENTITYX rather than ENTITY. With ENTITY, the entity name you pass to RACF must be in a buffer, the size of which is determined by the length in the class descriptor table. If the maximum length of a class descriptor entity increases in the future, you must modify your program to use a larger buffer. By using ENTITYX with the maximum buffer size, you avoid this possible problem because you removed the class descriptor table dependency from your program.

Requirement: Use ENTITYX with the maximum buffer size rather than ENTITY to avoid a buffer overlay when using the functions described above in Note 2.

Restriction: When using BRANCH=YES with TYPE=EXTRACTN, the entity value should contain blanks, or a name returned by a previous extract. Passing an entity name that does not exist in the RACLISTed profiles will result in an error rather than finding the next profile name alphabetically after the specified entity name.

,ENVROUT=envr data addr
Specifies the data structure that is to hold the information that is 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 re-create 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.

The ENVR object that is extracted from the ACEE includes the X500 name, USP, ICTX, and IDID if they exist. Although the format of the data structure that ENVROUT points to is known to the RACROUTE callers, the content of the object itself is defined by the external security product.

This keyword is only recognized when TYPE=ENVRXTR is specified. To use this keyword, RELEASE=2.6 or later must also be specified.

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

Figure 1. ENVR Data Structure
ENVR Data Structure
Table 1. Description of ENVR data structure
Description Length (bytes) ENVROUT usage
ENVR object length 4 Output
ENVR object storage area length 4 Input/output
ENVR object storage area address 4 Input/output
ENVR object storage area subpool 1 Input
ENVR object storage area key 1 Input

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 is 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 the minimum storage size that is needed to contain the ENVR Object. Storage size is returned in the ENVR Object storage area length. The storage address is returned in the ENVR Object storage area address.
Nonzero Zero RACF obtains the specified storage size or the minimum storage size needed to contain the ENVR Object. Storage size is returned in the ENVR Object storage area length. The 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. The 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.

,FIELDS=field addr
Specifies the address of a variable-length list. The first field is a 4-byte field that contains the number of profile field names in the list that follows.

Specifying zero for this 4-byte field has the same effect as not specifying the keyword.

Each profile field name is eight bytes long, left-justified, and padded to the right with blanks. The allowable field names for each type of profile are in the template listings in RACF database templates. For an illustration of how to specify the FIELDS keyword, see the TYPE=REPLACE example ("Example 1").

For Release=1.8 or later, the following options exist:
  • The count field can contain numbers 1–255.
  • The field names can be any of the field names in the template listings, unless BRANCH=YES is specified. For more information, see the explanation of the BRANCH parameter.

If you specify TYPE=EXTRACT or EXTRACTN, RACF retrieves the contents of the named fields from the RACF profile indicated by the CLASS= and ENTITY= or ENTITYX= parameters, and returns the contents in the result area. (See the EXTRACT keyword for an explanation of the result area.)

Beginning with Release 1.8, you can specify TYPE=REPLACE. RACF replaces or creates the indicated fields in the profile specified on the CLASS and ENTITY or ENTITYX keywords with the data pointed to by the SEGDATA keyword.

Note:
  1. Do not replace a repeat group-count field. Doing so causes unpredictable results.
  2. You cannot replace an entire repeat group, a single occurrence of a repeat group, or a single existing field in a repeat group. If you attempt to do so, RACF adds the data to the existing repeat group or groups.

    As an alternative, consider retrieving all occurrences of the specified fields within a repeat group, or adding a new occurrence of a repeat group.

  3. If you add occurrences of a repeat group, RACF places those additions at the beginning of the repeat group.
Example 1: This example of TYPE=REPLACE replaces fields in the BASE segment. It shows one way to code the macro and the declarations necessary to make the macro work.
       RACROUTE REQUEST=EXTRACT,TYPE=REPLACE,                         X
                CLASS='USER',                                         X
                ENTITY=USERID,                                        X
                FIELDS=FLDLIST,                                       X
                SEGDATA=SEGDLIST,                                     X
                SEGMENT=BASE,                                         X
                WORKA=RACWK
        ⋮
        USERID   DC  CL8,'BILL'
        FLDLIST  DC  A(3)
                 DC  CL8'AUTHOR'
                 DC  CL8'DFLTGRP'
                 DC  CL8'NAME'
        SEGDLIST DC  AL4(6),CL6'DJONES'
                 DC  AL4(8),CL8'SECURITY'
                 DC  AL4(11),CL11'BILL THOMAS'
        BASE     DC  CL8'BASE'
        RACWK    DC  CL512
When the replacement action takes place, the following occurs:
  • “DJONES” is placed in the AUTHOR field in the profile.
  • “SECURITY” is placed in the DFLTGRP field in the profile.
  • “BILL THOMAS” is placed in the ‘NAME’ field in the profile.
Example 2: In this example, RACROUTE REQUEST=EXTRACT retrieves the UACC from a fully qualified, generic data set profile. RACROUTE places the information in a work area in subpool 1.
 RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT,                               X
          VOLSER=VOLID,                                               X
          CLASS='DATASET',                                            X
          ENTITY=DSN,                                                 X
          FIELDS=FLDS,                                                X
          GENERIC=YES,                                                X
          SUBPOOL=1,                                                  X
          RELEASE=1.8,                                                X
          SEGMENT='TSO',                                              X
          WORKA=RACWK
 ⋮
 DSN   DC CL44'SYS1.LINKLIB'
 FLDS  DC A(1)
       DC CL8 'UACC'
 RACWK DC CL512
,FLDACC=NO
,FLDACC=YES
Specifies whether field-level access checking should be performed.
If you specify FLDACC=YES, the RACF database manager checks to see that the user running your program has the authority to extract or modify the fields specified in the RACROUTE REQUEST=EXTRACT macro.
Note:
  1. FLDACC=YES is ignored if BRANCH=YES is specified.
  2. For field-level access checking to occur, you must specify RELEASE =1.8 or later when you code the macro. In addition, before the program runs, the security administrator must activate and RACLIST the FIELD class using the SETROPTS command. If you code FLDACC=YES and the FIELD class is not active and RACLISTed, the request is failed with a return code 8, reason code 4.
  3. In addition, the security administrator must issue the RDEFINE and PERMIT commands to designate those users who have the authority to access the fields designated in the RACROUTE REQUEST=EXTRACT macro.
  4. If you specify FLDACC=NO or omit the parameter, the manager ignores field-level access checking.
  5. If you specify FLDACC=YES for TYPE=REPLACE with segment name CSDATA and field name CSCDATA, the data associated with the CSKEY field is used instead of the template name for field level access checking. This allows field level access checking to work in a consistent manner with the authorization that occurs for the RACF commands (for example, a field can be protected with a FIELD profile like USER.CSDATA.custom-field-name or GROUP.CSDATA.custom-field-name.
,GENERIC=ASIS
,GENERIC=YES
Specifies whether RACF is to treat the entity name as a generic profile name.
YES
RACF considers the entity name a generic profile name, even if it does not contain any of the generic characters. If you specify GENERIC=YES, the resource name in the macro matches only a generic resource name in the RACF database. It does not match a discrete name.
Characters considered generic are:
  • For data set class:
    • Asterisk (*)
    • Percent (%)
  • For general resource class:
    • Asterisk (*)
    • Percent (%)
    • Ampersand (&)
ASIS
RACF considers the entity name a generic profile name if it contains:
  • For data set class:
    • Asterisk (*)
    • Percent (%)
  • For general resource class:
    • Asterisk (*)
    • Percent (%),
    • Ampersand (&).
Note: A profile in the RACFVARS class is not considered to be a generic profile even though it contains an ampersand sign.

If you specify GENERIC, you must specify RELEASE=1.8 or later.

Note: If generics have not been enabled for the class, EXTRACT and EXTRACTN do not find generic profiles.
,MATCHGN=YES
,MATCHGN=NO
Specifies that you want to extract data from a profile that matches or covers the resource name specified on the ENTITY or ENTITYX keyword.
YES

RACF extracts data from the discrete profile, if one exists; if a discrete profile does not exist, RACF extracts data from the best-matching generic profile. If a best-matching generic profile is found, that profile name is returned to the caller in the ENTITY or ENTITYX location.

If ENTITYX is specified, the length of the best-matching profile name is also returned in the 2-byte, actual entity-name-length location. If the buffer length is less than the length of the best-matching profile, you get a return and reason code indicating that the profile was not found because the buffer length specified is too small.

NO
RACF extracts data from a profile (discrete or generic) that exactly matches the name specified on the ENTITY or ENTITYX keyword.
Note:
  1. To specify the MATCHGN keyword, you must specify Release=1.9 or a later release number.
  2. For MATCHGN=YES, the class must be active.
,SEGDATA=segment data addr
Specifies the address of a list of data items to be placed in the respective fields named by the FIELDS= parameter. You use the SEGDATA parameter when you specify TYPE=REPLACE. If you specify SEGDATA, you must also specify CLASS, FIELDS, and RELEASE=1.8 or a later release number. The stored data is paired in the following format:
  • A 4-byte length field that contains the length of the data field that follows
  • A data field of variable length.
Specifying zero for the length field causes the field being replaced to be removed from the segment. Each length field is followed immediately by a data field, until the end of the replacement data is reached. The count field, which is pointed to by the first field in the FIELDS parameter, contains the total number of length-data pairs.
,SEGMENT=‘segment name’
,SEGMENT=segment name addr
Specifies the RACF profile segment that RACF is to update or from which it is to extract data. If you allow the SEGMENT parameter to default, RACF assumes that you want to extract information from the base segment.

Each segment name is eight bytes long, left justified, and padded to the right with blanks. SEGMENT is not preceded by a 4-byte length field.

If you specify SEGMENT, you must also specify the CLASS and FIELDS keywords, and RELEASE=1.8 or a later release number.

Note: Start of change When extracting CSDATA information, the returned information is a standard repeat group as defined in the RACF database templates, where the CSTYPE field contains the type of the field, CSKEY contains the name of the field, and CSVALUE contains the value of the field.End of change
Start of changeAs alternatives to RACROUTE REQUEST=EXTRACT, consider using the following services for extracting CSDATA fields:
  • The R_Admin callable service (IRRSEQ00) returns CSDATA fields consistently with the way other profile segments and fields are returned.
  • The R_GetInfo callable service returns CSDATA fields that are defined with the ACEE(YES) keyword directly from an ACEE without incurring IO.
End of change

Start of changeBoth callable services can be invoked from problem state programs.End of change

Start of changeFor more information, see R_admin (IRRSEQ00): RACF administration API and R_GetInfo (IRRSGI00): Get security server fields in z/OS Security Server RACF Macros and Interfaces.End of change

,SUBPOOL=subpool number
Specifies the storage subpool from which the extract-function routine obtains an area that is needed for the extraction.
Note:
  1. If this parameter is not specified, it defaults to 229.

    Take some care in selecting a subpool, as MVS™ makes certain assumptions about subpool usage and characteristics. In particular, using subpool 0 or 250, or any subpool that is documented in z/OS MVS Programming: Assembler Services Guide as having a storage key of USER (for example, 227–231 and 241) might give unpredictable results.

  2. If a common-area subpool (for example 226–228, 231, 239, 241, 245, 247, or 248) is used and not freed before the job terminates, then the job might show up in the exception reports of RMF (or other monitoring tools that support the tracking of common-area storage utilization) as owning common storage. Before your job terminates, it should issue a FREEMAIN to free this common storage.
,TYPE=ENCRYPT
,TYPE=ENVRXTR
,TYPE=EXTRACT
,TYPE=EXTRACTN
,TYPE=REPLACE
Specifies the type of function to be performed by the extract-function routine.
ENCRYPT
Allows RACF to provide an authentication token to be used in verifying a user's identity. The ENCRYPT keyword specifies the user-authentication key to be used for authentication, and the authentication method. The first eight bytes of the area pointed to by the ENTITY or ENTITYX operand are used as the clear-text data to be processed by the INST, DES, and STDDES authentication routines. The HASH method uses the user-authentication key as clear-text data and masks the data instead of encrypting it. If ENTITY or ENTITYX is not specified, or ENTITYX is specified with zero for the buffer length and zero for the actual entity-name length, the user ID from the current ACEE is used as the clear-text data. If TYPE=ENCRYPT is specified, no work area is returned.
ENVRXTR
Extracts an ENVR object from the specified ACEE. The ENVR object is returned using the ENVROUT keyword. TYPE=ENVRXTR can be invoked in cross-memory mode to extract an ENVR object in the primary address space from an ACEE in the HOME address space.

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.

Note:
  1. When TYPE=ENVRXTR is specified, only the keywords ACEE and ENVROUT are recognized, with ENVROUT being required.
  2. RELEASE=2.6 or later must be also specified.
  3. This service is always invoked as a branch entered service, and the BRANCH= keyword is ignored.
  4. The issuer must be APF authorized, system key (0–7), or in supervisor state unless in cross memory mode. In cross memory mode, the caller must be system key (0–7) and in supervisor state.
  5. This service is always invoked with DECOUPL=YES. The setting of the DECOUPL= parameter is ignored.
EXTRACT
Extract information from any field in any profile, unless BRANCH=YES is specified.

The profile templates in RACF database templates define the type and name of each field in each profile. If you specify EXTRACT, RACF extracts information from the profile that is determined by the ENTITY or ENTITYX and CLASS keywords.

Specifically, RACF extracts (from the RACF database) the fields specified in the FIELDS keyword from the segment specified by the SEGMENT keyword.

Otherwise, you can obtain the default user-class information from the current user's profile (the specified or default ACEE) if you do the following:
  • Specify the USER class or do not specify the CLASS= keyword.
  • Do not specify the SEGMENT and FIELDS keywords.
  • Do not specify the ENTITY or ENTITYX keyword, or specify ENTITYX with zero for the buffer length and zero for the actual entity-name length.

An installation that is processing selected or all users in the USER class by coding RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN (where the starting profile is a value less than X'C1') might find that this code returns one of the irrcerta, irrmulti, and irrsitec user IDs, which are the user IDs associated with digital certificates. These user IDs are not valid user IDs and do not represent real users. Because they do not contain a default group, they cannot be used for RACROUTE REQUEST=VERIFY processing, nor can they be used on a third-party RACROUTE REQUEST=AUTH. As a result, an installation might want to ignore these user IDs in its code.

When the default information is taken from the current user's profile (the specified or default ACEE), there is no I/O to the RACF database, and the user's ID and default connect group are extracted from the current ACEE. This also results in returning the language information as follows:
  • If the user's primary and secondary languages are available, they are extracted from the current ACEE, along with a code indicating that the reported languages are defined in the user's profile.
  • If the user's primary and secondary languages are not available in the user's profile, the installation default primary and secondary languages set by SETROPTS are returned, along with a code indicating that the reported languages are the installation default.

Additionally, if the user's work attributes (WORKATTR) information is available, it is also extracted from the ACEE. For the format of the WORKATTR information returned from the ACEE, see RXTW: RACROUTE REQUEST=EXTRACT Result Area Mapping in z/OS Security Server RACF Data Areas in the z/OS Internet library.

To use TYPE=EXTRACT to extract field information from a profile, you must specify RELEASE=1.8 or a later release number.
Note: If you specify TYPE=EXTRACT, do not specify ENCRYPT.

Upon return, register 1 contains the address of a result area that begins with a fullword containing the length and subpool number of the area. EXTWOFF is used as the offset from EXTWKEA to locate the start of the optional returned fields. See RXTW: RACROUTE REQUEST=EXTRACT Result Area Mapping in z/OS Security Server RACF Data Areas in the z/OS Internet library for the mapping of this area. It is your responsibility to issue a FREEMAIN to release the area after you are through using it. See the description of the SUBPOOL keyword.

There are certain conditions under which register 1 can contain a nonzero value that is not a pointer to a result area.
R15 value SAFPRRET SAFPRREA
4 0 anything
4 4 0
X'64' anything anything

Otherwise, when register 1 contains a nonzero value, it contains the address of the result area.

You need to initialize the parameter lists such that SAFPRRET and SAFPRREA start out as 0 in order to distinguish these cases.

In general, RACF returns field data in the order it was specified, with a 4-byte length field preceding each profile field. The following lists show what is returned for different types of extractions:
  • For a single field, you get:
    • A 4-byte length field that contains the length of the field that follows, or
    • If the requested field is a variable-length field, there is no additional length byte.
    What is returned for a single field
  • For a combination field (representing one or more fields), you receive:
    • A 4-byte length field that contains the combined length of all the fields that follow, or
    • A combination field made up of 4-byte length fields followed by their respective individual data fields.
    What is returned for a combination field
  • For a single field within a repeat group, you receive:
    • A 4-byte length field that contains the combined length of all the fields that follow, or
    • A 4-byte length field that indicates the length of the specified field in the first occurrence of the repeat group. This is followed by a 4-byte length field that indicates the length of the specified field in the second occurrence of the repeat group. This order repeats until all the occurrences of the repeat group are accounted for.
    What is returned for a single field within a repeat group
  • For a combination field (representing one or more fields) within a repeat group, you receive:
    • A 4-byte length field that contains the combined length of all the fields that follow, or
    • A combination field consisting of a 4-byte length field indicating the length of the individual data field that follows it, followed by the next 4-byte length field indicating the length of the next individual data field. This order repeats until all the individual fields that make up the combination field are accounted for. The order begins again for the next occurrence of the repeat group.
    What is returned for a combination field within a repeat group
  • When you specify the name of a repeat-group count field, you retrieve the 4-byte length followed by the 4-byte repeat group count.
    When a field to be extracted is empty, the following results:
    • For fixed-length fields, RACF returns the default as specified by the template definitions. The default for flag fields is X'00'. The default for fixed-length fields in the BASE segment of the profile is binary 1(s). The default for fixed-length fields in other segments is binary zeros.
    • For variable-length fields, RACF returns a length of zero and no data.
EXTRACTN
Specifies that upon return, register 1 contains the address of a result area that begins with a fullword containing the area's subpool number and length. To see the format of the result area, see the explanation of TYPE=EXTRACT, above and RXTW: RACROUTE REQUEST=EXTRACT Result Area Mapping in z/OS Security Server RACF Data Areas in the z/OS Internet library. At offset 6 in the result area, there is a flag. If the flag has a X'80', the name returned is generic.

If you specify EXTRACTN, the macro extracts information from the profile that follows the profile determined by the ENTITY or ENTITYX and CLASS keywords. From that next profile, RACF extracts the fields specified in the FIELDS keyword from the segment that is specified by the SEGMENT keyword. In addition, RACF returns the name of the profile from which it extracted the data.

Note:
  1. If you specify TYPE=EXTRACTN, do not specify ENCRYPT=.
  2. To retrieve all profiles within a class, the database must be processed twice, once to extract all discrete profiles and once again to extract all generic profiles (see Example 3). In exception, the DATASET class needs to be processed only once to extract all discrete and generic profiles. (See Example 4.)
REPLACE
Use of the REPLACE option to update a profile requires a thorough knowledge of the interrelationships of fields within a profile, and of the potential relationships between profiles. For instance, if you use RACROUTE REQUEST=EXTRACT to update a password, you should also update the password change date. However, since you cannot update the password history, subsequent password changes (by PASSWORD or TSO LOGON, for example) might allow the old password to be used again.

If you specify TYPE=REPLACE, RACF takes the information in the fields specified in the FIELDS parameter and pointed to by SEGDATA, and places that information in the designated segment. (The segment is within the profile that is determined by the ENTITY or ENTITYX and CLASS keywords.) If you specify TYPE=REPLACE, you must specify FIELDS, SEGDATA=, and RELEASE=1.8 or later. If you want to replace a segment other than the base segment, you must specify the SEGMENT keyword with the segment you want. If you do not specify SEGMENT, the segment defaults to the base segment.

With Release 1.8 and later, if you want to create a TSO segment, you can do so by specifying the RACROUTE REQUEST=EXTRACT macro in the following way:
   TYPE=REPLACE  SEGMENT=TSO
Note: If you specify TYPE=REPLACE, do not specify ENCRYPT=.
,VOLSER=volser addr
Specifies the volume serial number as follows:
  • For non-VSAM DASD data sets and for tape data sets, this specifies the volume serial number of the volume on which the data set resides.
  • For VSAM DASD data sets and tape data sets, this specifies the volume serial number of the catalog controlling the data set.

The field pointed to by the VOLSER address contains the volume serial number. If necessary, you must pad it to the right with blanks so it contains six characters.

If you specify VOLSER, you must specify RELEASE=1.8 or later.

VOLSER is valid with CLASS=DATASET.

,MF=S
Specifies the standard form of the RACROUTE REQUEST=EXTRACT 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=EXTRACT has completed successfully.
RACF RC
Meaning
00
The extraction, replacement, or encoding completed successfully.
Reason Code
Meaning

For DERIVE requests:

00
Some of the values are derived from the USER profile, and some might be derived from the GROUP profile.
04
High-level qualifier returned as RESOWNER, which matched a valid USER.
08
DFP data returned from an EXTRACT request from USER profile was actually from the user's default connect group.
0C
High-level qualifier returned as RESOWNER, which matched a valid GROUP.
24
RESOWNER field matched a valid USER.
28
RESOWNER field matched a valid GROUP.
2C
At least one, but not all, of the fields requested failed to be retrieved because of field-level access checking.
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®.
04
An ESTAE environment could not be established, or if Register 0 contains a reason code of 1, neither EXTRACT, EXTRACTN, REPLACE, nor ENCRYPT was specified for TYPE=.
08
For TYPE=EXTRACT, TYPE=EXTRACTN, or TYPE=REPLACE, the profile could not be found, or one of the other errors shown by the reason code has occurred.
Reason Code
Meaning
00
No profile found.
04
Field-level access checking failed. The FIELD class might not be active and RACLISTed.
08
Segment not found.
0C
Class not RACLISTed (branch EXTRACT).
10
Class not active (branch EXTRACT).
14
For EXTRACT:

Neither the RESOWNER field nor the high-level qualifier matched a valid USER or GROUP.

For branch-entered EXTRACT only:

Field specified is not valid. Note that the field can be valid for a profile in the RACF database, but not for a RACLISTed profile.

18
For EXTRACT:

For MATCHGN=YES with ENTITYX= specified, the buffer length specified was too small to return the matching generic profile.

For branch-entered EXTRACT only:

For TYPE=EXTRACTN with ENTITYX= specified, the buffer length specified was too small to return the next profile name.

With ENTITYX specified, the discrete entity name was passed in but a generic profile was returned which does not fit into the buffer specified for the entity passed in by the caller.

1C
The class was RACLISTed by RACROUTE REQUEST=LIST, GLOBAL=YES, but the data space has been deleted (branch EXTRACT).
0C
RACF is inactive.
10
The extract operation failed. SAFPRREA contains the RACF-manager return code that caused the operation to stop. The value in the SAFPRREA should be interpreted as follows:
Reason Code
Meaning
xxxxyyyy
xxxx is the RACF manager reason code and yyyy is the RACF manager return code. This return code is not used for the encrypt function.
For branch EXTRACT, the return and reason codes in SAFPRREA are internal RACF codes indicating an error in RACF, except for the following:
Reason Code
Meaning
00080018
The RACLIST data space cannot be accessed due to an ALESERV failure.
Note: For an explanation of the RACF manager return codes, refer to the part of z/OS Security Server RACF Macros and Interfaces that discusses the ICHEINTY macro or the topic of z/OS Security Server RACF Messages and Codes that describes RACF manager return codes.
14
For TYPE=ENCRYPT or TYPE=EXTRACT of USER class data, ENTITY or ENTITYX was not specified and no ACEE exists or the ACEE was not for a defined user.
Reason Code
Meaning
00
No ACEE exists.
04
ACEERACF bit is off.
08
The requested function failed.
RACF RC
Meaning
18
A parameter-list error was encountered.
Reason Code
Meaning
04
For a TYPE=REPLACE request, FIELDS= was not specified.
08
Type specified is not valid.
0C
Number of fields is not valid.
10
Class name specified is not valid.
14
Version in parameter list is not valid.
18
Subpool specified is not valid.
1C
Parameter length not valid.
20
For TYPE=REPLACE request, SEGDATA= was not specified.
24
Entity name specified is not valid.
2C
For TYPE=ENCRYPT request, no user-authentication key was specified.
30
Encoding method is not valid.
34
ENTITY= or ENTITYX= was not specified with TYPE=REPLACE, TYPE=EXTRACTN, or TYPE=EXTRACT with class other than USER.
38
Multiple profiles and no volume specified.
3C
Profile found, but the wrong volume serial number was specified.
40
For a TYPE=EXTRACT request of USER class data, FIELDS= is not permitted with BRANCH=YES because the USER class cannot be RACLISTed (branch EXTRACT).
44
For the ENTITYX format, both the entity-name length and the buffer length are zero.
48
Entity-name length with the ENTITY or ENTITYX keyword is not valid:
  • The specified length is less than zero.
  • The specified length is one of the following:
    • Greater than 44 if CLASS=DATASET,
    • Greater than 8 if CLASS=USER or GROUP,
    • Greater than 17 if CLASS=CONNECT, or
    • Greater than the maximum for the specified class as defined in the class descriptor table.
  • For a TYPE=ENCRYPT request, the specified length is not zero or eight.
4C
Buffer length specified with ENTITYX keyword not valid:
  • Less than zero
  • Greater than 255
  • Not zero but less than the entity name length
50
The entity name contains a blank.
  • If the ENTITYX keyword is specified and the entity-name length is given, the name has a blank in the beginning, in the middle, or at the end.
54
For a TYPE=ENCRYPT request for the STDDES authentication method, the specified data length is not 8.
58
For a TYPE=EXTRACT request of user-class data, the user specified with ENTITY= or ENTITYX= is not the same as the user specified in the ACEE (branch EXTRACT).
5C
For a TYPE=EXTRACT request of user-class data that is defaulted from the ACEE, FIELDS= and SEGMENT= are not permitted because the user ID in the ACEE is not that of a RACF-defined user.
60
For TYPE=ENVRXTR, the ENVROUT keyword was not specified.
64
For TYPE=ENVRXTR, the ENVR object storage area address specified was not on a doubleword boundary.
68
For TYPE=ENVRXTR, the ENVR object could not be built because the ACEE was not valid.
6C
GENERIC=YES was specified with TYPE=EXTRACTN and BRANCH=YES.
70
MATCHGN=YES was specified with TYPE=EXTRACTN and BRANCH=YES.
64
Indicates that the CHECK subparameter of the RELEASE keyword was specified on the execute form of the RACROUTE REQUEST=EXTRACT macro; however, the list form of the macro does not have the same RELEASE parameter. It also indicates that the TYPE parameters specified on the list and execute forms might not be the same TYPE. Macro processing terminates.

Example 1

The following is an example of a RACROUTE REQUEST=EXTRACT that looks for an APPCLU profile that has been RACLISTed off an ACEE, the one called VTAMACEE, to match the entity named in LULUPAIR. Specifying BRANCH=YES means that the function does not invoke an SVC. It is therefore SRB-compatible. If the function finds a profile to match the entity name, it returns fields specified in FLDLIST.

Because MATCHGN=YES is specified, if a discrete profile that matches the entity name is not found, the function looks for a best-matching generic profile. If a best-matching generic profile is found, the fields specified in FLDLST are returned from that profile. The best-matching generic profile is returned in the entity location.
 RACROUTE REQUEST=EXTRACT,TYPE=EXTRACT,                               X
          BRANCH=YES,                                                 X
          CLASS='APPCLU',                                             X
          ENTITY=LULUPAIR,                                            X
          ACEE=VTAMACEE,                                              X
          SEGMENT='SESSION',                                          X
          FIELDS=FLDLST,                                              X
          MATCHGN=YES,                                                X
          RELEASE=1.9,                                                X
          WORKA=RACWK
 ⋮
 LULUPAIR DC CL(35)'NETA.LU1.LU2'
 FLDLST   DC A(3)
          DC CL8'SESSKEY'
          DC CL8'KEYDATE'
          DC CL8'KEYINTVL'
 RACWK    DC CL512

Example 2

The following is an example of a RACROUTE REQUEST=EXTRACT that uses the STDDES authentication method to process the data in RANDATA, using the data in SESSNKEY as the authentication key. The function overlays the data in SESSNKEY with the product of the authentication process. Specifying BRANCH=YES means that the function is compatible with SRB mode and does not issue any SVCs.
 RACROUTE REQUEST=EXTRACT,TYPE=ENCRYPT,                               X
          BRANCH=YES,                                                 X
          ENTITY=RANDATA,                                             X
          ENCRYPT=(SESSNKEY,STDDES),                                  X
          RELEASE=1.9,                                                X
          WORKA=RACWK
 ⋮
 RANDATA  DC CL8'RANDATA1'
 SESSNKEY DC AL1(8),CL8'SESSNKEY'
 RACWK    DC CL512

Example 3

The following is an example of a RACROUTE REQUEST=EXTRACT with EXTRACTN. It retrieves all profiles within any class (except the DATASET class). The database must be processed twice, once to extract all discrete profiles and once to extract all generic profiles.
EXTRTNGR CSECT
*
*        Entry Linkage
*
         STM   14,12,12(13)              Push caller registers
         BALR  12,0                      Establish …
         USING *,12                      … addressability
         GETMAIN R,LV=DYNLEN             Get dynamic storage
         LR    11,1                      Move getmained address to R11
         USING DYNAREA,11                Addressability to DSECT
         ST    13,SAVEAREA+4             Save caller save area address
         LA    15,SAVEAREA               Get address of own save area
         ST    15,8(13)                  Store in caller save area
         LR    13,15                     Get address of own save area
*
*        Initialize variables in dynamic storage area
*
*
         MVC   ENTXBLEN,H6               Set buffer length to 6
         MVC   ENTXNLEN,H0               Set entity length to 0
         MVC   ENTXNAME,BLNKNAME         Set entity name to blanks
*
*        Copy static RACROUTE to dynamic GETMAINed areas
*
         MVC   DYNRACR(RACRLEN),STATRACR
*
*        Loop to retrieve the OWNER field from all discrete
*        profiles in the TAPEVOL class.
*
DISLOOP  EQU   *                         Start of discrete loop
         RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,ENTITYX=ENTXBUFF,      *
              FIELDS=FIELDS,WORKA=WORKAREA,RELEASE=1.9,MF=(E,DYNRACR)
         LTR   15,15                     Check return code
         BNZ   TRYGEN                    Exit on nonzero return code
*                                        to search for generic profiles
*               .
*               .
*        Do discrete TAPEVOL profile processing here.
*               .
*               .
*                                        Free storage for this profile
         XR    3,3                       Zero out register 3
         XR    2,2                       Zero out register 2
         USING EXTWKEA,1                 Base the result area on
*                                        register 1
         ICM   3,1,EXTWSP                Move the result area subpool
*                                        into register 3
         ICM   2,7,EXTWLN                Move the result area length
*                                        into register 2
         DROP  1                         Drop basing on register 1
         FREEMAIN R,LV=(2),A=(1),SP=(3)  Free storage before processing
*                                        next profile
*
         B     DISLOOP                   Process next discrete profile
*
*
TRYGEN   EQU   *                         Search for generic profiles
*
         MVC   ENTXBLEN,H6               Set buffer length to 6
         MVC   ENTXNLEN,H0               Set entity length to 0
         MVC   ENTXNAME,BLNKNAME         Set entity name to blanks
         SLR   15,15                     Clear return code
*
*        Modify request to set GENERIC to YES
*
         RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,GENERIC=YES,           *
               RELEASE=1.9,MF=(M,DYNRACR)
*
*        Loop to retrieve the OWNER field from all generic
*        profiles in the TAPEVOL class.
*
GENLOOP  EQU   *                         Start of generic loop
*
         RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,ENTITYX=ENTXBUFF,      *
              FIELDS=FIELDS,WORKA=WORKAREA,RELEASE=1.9,MF=(E,DYNRACR)
         LTR   15,15                     Check return code
         BNZ   DONE                      Exit on nonzero return code
*               .
*               .
*        Do generic TAPEVOL profile processing here.
*               .
*               .
*                                        Free storage for this profile
         XR    3,3                       Zero out register 3
         XR    2,2                       Zero out register 2
         USING EXTWKEA,1                 Base the result area on
*                                        register 1
         ICM   3,1,EXTWSP                Move the result area subpool
*                                        into register 3
         ICM   2,7,EXTWLN                Move the result area length
*                                        into register 2
         DROP  1                         Drop basing on register 1
         FREEMAIN R,LV=(2),A=(1),SP=(3)  Free storage before processing
*                                        next profile
*
         B     GENLOOP                   Process next generic profile
*
*        Return to caller
*
DONE     EQU   *                         Return to caller
         L     13,SAVEAREA+4             Caller's save area address
         FREEMAIN R,LV=DYNLEN,A=(11)     Get dynamic storage
         LM    14,12,12(13)              Pop registers
         SLR   15,15                     Clear return code
         BR    14                        Return to caller
*
*        Static RACROUTE area
*
STATRACR RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,ENTITYX=*-*,           *
               FIELDS=*-*,SEGMENT='BASE',CLASS='TAPEVOL',              *
               GENERIC=ASIS,WORKA=*-*,RELEASE=1.9,MF=L
RACRLEN  EQU   *-STATRACR               Length of RACROUTE
*
*        Constants
*
H0       DC    H'0'
H6       DC    H'6'
BLNKNAME DC    CL6' '
*
FIELDS   DC A(1)
         DC CL8'OWNER'
*
*        Result area mapping
*
         IRRPRXTW
*
*        Dynamic area
*
DYNAREA  DSECT
*
DYNRACR  RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,ENTITYX=*-*,           *
               FIELDS=*-*,SEGMENT='BASE',CLASS='TAPEVOL',              *
               GENERIC=ASIS,WORKA=*-*,RELEASE=1.9,MF=L
*
*        ENTITYX structure
*
ENTXBUFF DS    0CL10                     ENTITYX structure
ENTXBLEN DS    H                         Entity name buffer length
ENTXNLEN DS    H                         Entity name actual length
ENTXNAME DS    CL6                       Entity name
*
*        Work and save areas
*
WORKAREA DS    128F                      Work area
SAVEAREA DC    18F'0'                    Save area
*
DYNLEN   EQU   *-DYNAREA                 Dynamic area length
*
         END

Example 4

The following is an example of a RACROUTE REQUEST=EXTRACT with EXTRACTN. It retrieves all profiles within the DATASET class. The database needs to be processed only once to extract all discrete and generic profiles in the DATASET class.
EXTRTNDS CSECT
*
*        Entry Linkage
*
         STM   14,12,12(13)              Push caller registers
         BALR  12,0                      Establish …
         USING *,12                      … addressability
         GETMAIN R,LV=DYNLEN             Get dynamic storage
         LR    11,1                      Move getmained address to R11
         USING DYNAREA,11                Addressability to DSECT
         ST    13,SAVEAREA+4             Save caller save area address
         LA    15,SAVEAREA               Get address of own save area
         ST    15,8(13)                  Store in caller save area
         LR    13,15                     Get address of own save area
*
*        Initialize variables in dynamic storage area
*
*
         MVC   ENTXBLEN,H44              Set buffer length to 44
         MVC   ENTXNLEN,H0               Set entity length to 0
         MVC   ENTXNAME,BLNKNAME         Set entity name to blanks
*
*        Copy static RACROUTE to dynamic GETMAINed areas
*
         MVC   DYNRACR(RACRLEN),STATRACR
*
*        Loop to retrieve the OWNER field from all DATASET
*        profiles for each high level qualifier.  Generic
*        profiles are retrieved first.
*
LOOP     EQU   *                         Start of loop
         RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,ENTITYX=ENTXBUFF,      *
              FIELDS=FIELDS,WORKA=WORKAREA,RELEASE=1.9,MF=(E,DYNRACR)
         LTR   15,15                     Check return code
         BNZ   DONE                      Exit on nonzero return code
*               .
*               .
*        Do DATASET profile processing here.
*               .
*               .
*                                        Free storage for this profile
         USING EXTWKEA,1                 Base the result area on
*                                        register 1
         MVC   DYNGENRC,EXTFLAG          Make a local copy of generic
*                                        flag
         XR    3,3                       Zero out register 3
         ICM   3,1,EXTWSP                Move the result area subpool
*                                        into register 3
         XR    2,2                       Zero out register 2
         ICM   2,7,EXTWLN                Move the result area length
*                                        into register 2
         DROP  1                         Drop basing on register 1
         FREEMAIN R,LV=(2),A=(1),SP=(3)  Free storage before processing
*                                        next profile
*
         TM    DYNGENRC,X'80'            Check generic bit
         BO    GENERIC                   Branch if generic bit is on
*                                        Otherwise, profile is not
*                                        generic, so set GENERIC to
*                                        ASIS
         RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,GENERIC=ASIS,          *
               RELEASE=1.9,MF=(M,DYNRACR)
         B     LOOP                      Process next profile
*
GENERIC  EQU   *                         Profile name is generic,
*                                        so set GENERIC to YES
         RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,GENERIC=YES,           *
               RELEASE=1.9,MF=(M,DYNRACR)
*
         B     LOOP                      Process next profile
*
*        Return to caller
*
DONE     EQU   *                         Return to caller
         L     13,SAVEAREA+4             Caller's save area address
         FREEMAIN R,LV=DYNLEN,A=(11)     Get dynamic storage
         LM    14,12,12(13)              Pop registers
         SLR   15,15                     Clear return code
         BR    14                        Return to caller
*
*        Static RACROUTE area
*
STATRACR RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,ENTITYX=*-*,           *
               FIELDS=*-*,SEGMENT='BASE',CLASS='DATASET',              *
               GENERIC=ASIS,WORKA=*-*,RELEASE=1.9,MF=L
RACRLEN  EQU   *-STATRACR               Length of RACROUTE
*
*        Constants
*
H0       DC    H'0'
H44      DC    H'44'
BLNKNAME DC    CL44' '
*
FIELDS   DC A(1)
         DC CL8'OWNER'
*
*        Result area mapping
*
         IRRPRXTW
*
*        Dynamic area
*
DYNAREA  DSECT
*
DYNRACR  RACROUTE REQUEST=EXTRACT,TYPE=EXTRACTN,ENTITYX=*-*,           *
               FIELDS=*-*,SEGMENT='BASE',CLASS='DATASET',              *
               GENERIC=ASIS,WORKA=*-*,RELEASE=1.9,MF=L
*
*        ENTITYX structure
*
ENTXBUFF DS    0CL48                     ENTITYX structure
ENTXBLEN DS    H                         Entity name buffer length
ENTXNLEN DS    H                         Entity name actual length
ENTXNAME DS    CL44                      Entity name
*
*        Work and save areas
*
WORKAREA DS    128F                      Work area
SAVEAREA DC    18F'0'                    Save area
DYNGENRC DS    CL1                       Local copy of generic flag
*
DYNLEN   EQU   *-DYNAREA                 Dynamic area length
*
         END