Usage notes

  1. You must link edit the IRRSEQ00 callable service stub into your application code to resolve the entry point address at run time.
  2. For the Out_message_subpool parameter, select a subpool carefully. z/OS makes certain assumptions about subpool usage and characteristics. Using subpool 0 or 250 or any subpool documented in z/OS MVS Programming: Authorized Assembler Services Guide as having a storage key of USER (for example, 227-231 and 241) may give unpredictable results.
  3. All requests are processed synchronously. Control is not returned to the caller until RACF® has processed the administration request and output, if any has been returned to the caller.
  4. For the ADMN_RUN_COMD function code, the following RACF commands are not supported through this interface:
    • BLKUPD
    • RACLINK
    • RVARY
    • RACF operator commands (DISPLAY, RESTART, SET, SIGNOFF, STOP, and TARGET)

    RACF TSO administrative commands may not be directed to other RACF remote sharing facility (RRSF) nodes. The command image passed by the caller cannot contain the keywords AT or ONLYAT. These keywords cause the command to fail with SAF return code 8, RACF return code 16, RACF reason code 8.

    These messages are returned as command output:

    IRRV013I subsystem-name SUBSYSTEM racf-command COMMAND FROM THE IRRSEQ00 CALLABLE SERVICE WAS NOT PROCESSED.

    IRRV014I subsystem-name SUBSYSTEM AT() OR ONLYAT() KEYWORDS MAY NOT BE SPECIFIED WITH COMMANDS FROM THE IRRSEQ00 CALLABLE SERVICE.

    Any update to the RACF database caused by this service is subject to automatic direction and password synchronization as implemented by the installation.

  5. The parameter list passed to this service is a variable-length (VL) parameter list. The high-order bit of the last field (address of Out_message_strings) must be set to mark the end of the parameter list.
  6. All field data must be supplied in character format. For information about the contents of the field data, refer to z/OS Security Server RACF Command Language Reference for the appropriate command keyword as indicated in the following tables. For example, looking at Table 17 to find details on the content of the HLDCLASS field, see the ADDUSER/ALTUSER documentation for the HOLDCLASS keyword of the TSO segment.

    Additionally, RACF has a restriction of no more than 255 operands affecting a single nonbase segment (such as the TSO segment in a user profile, or the TME segment in a general resource profile) on a single command. Since the R_admin callable service generates a RACF command, this restriction applies to the number of field operands affecting nonbase segments. For the CSDATA segment in a user or group profile, this RACF restriction is further limited to no more than 85 operands on a single command. See the "RACF command restriction for nonbase segments in RACF profiles" topic in z/OS Security Server RACF Command Language Reference for specifics on this restriction.

  7. The following errors result in an "input parameter list error" being returned to the caller:
    • VL bit not set
    • An incorrectly specified ADMN_USRADM_USER_LEN, ADMN_GRPADM_LEN, or ADMN_RESADM_CLAS_LEN (must be from 1-8, inclusively)
    • An incorrectly specified length for the RACF user ID parameter (must be from 0 to 8, inclusively)
    • Invalid profile name length specified in input parameter list for profile extract functions (must be greater than 0 and less than or equal to 8 for USER or GROUP, less than or equal to 17 for CONNECT, and less than or equal to 246 for a general resource class). Note that the actual maximum profile length is determined by the Class Descriptor Table entry for a given resource class, and the length can be less than 246 characters. If a request specifies a profile name which is longer than the allowed maximum for the specified class, a "profile not found" (4/4/4) return code combination will result.
    • Setting ADMN_USRADM_SEG_NUM=0 on any of the list functions
    • Omitting the PROFILE field on any of the general resource, data set (except list), permit, or profile extract function codes
    • Specifying a subpool outside the range of 1 to 127 when the caller is in problem state
    • For ADMN_XTR_NEXT_RESOURCE, specifying a resource name containing generic characters without turning on the ADMN_PROF_GENERIC flag.
  8. When a return code combination of 4/4/20 is returned on an extract-next request, this means that RACF has encountered a profile name which appears to be generic, but is in fact discrete. This is almost always an error condition in the RACF database, and continuing to extract profiles will have unexpected results. The offending profile name is returned in the output buffer, but no profile data is returned.
    The normal cause of this problem is that the profile was defined prior to activating generics in the class. To fix the problem, delete the profile and define the profile again. For example: 
    RDELETE class profile-name
RDEFINE class profile-name operands ...
    Issue PERMIT commands as appropriate to recreate the access list.

    Some profiles are not used to protect resources, but instead contain data (such as profiles in the DIGTCERT class, which contain digital certificates). It may be valid for such profiles to contain asterisks or other generic characters, without generics being active for the class. These profiles will cause problems when R_admin is used to extract all profiles from the class. In the case of digital certifcates, R_admin does not return any actual information related to the certificate. To obtain certificate information, R_datalib (IRRSDL00) or Database Unload are the appropriate services.

    Note that the IRRICE member of SYS1.SAMPLIB contains a sample query (named BGGR) which searches Database Unload output for discrete profiles containing generic characters.

  9. Inconsistencies can occur when extracting profiles in RACLISTed classes if the in-storage profiles are different from those in the RACF database. In other words, when you are extracting a profile which has been changed since the last time the class was refreshed, the authorization information could be inconsistent between the in-storage copy, which was used to determine your authorization, and the database copy which is actually returned. This could result in certain profiles being unexpectedly returned or not.
  10. The ADMN_XTR_RRSF function extracts a snapshot of information from an active, running RRSF configuration. It is possible that some of the data returned, especially information concerning the status of the workspace datasets, may change between the time it is retrieved and the time it is used by the application which requested it.
  11. Use of ADMN_XTRSF_RRSF requires the caller to have READ access to OPERCMDS 'SET LIST' and 'TARGET LIST'. If the caller is not authorized to either of these, partial data is returned. A bit in the returned data buffer indicates to which data the caller was unauthorized.
Parent topic: R_admin (IRRSEQ00): RACF administration API