Usage notes

An ALET must be specified for the SAF_return_code, RACF_return_code, and RACF_reason_code parameters, and a single ALET specified for all of the remaining parameters, not including the ACEE_ALET and ACEE parameters. The ALET for the ACEE parameter must be specified separately, using the ACEE_ALET parameter.
The parameter list for this callable service is intended to be variable length to allow for future expansion. Therefore, a parameter containing a count of parameters is used: NumParms. This parameter tells how many parameters appear in the list following and including the NumParms parameter. NumParms must be set to 19 for function code X'0006' or 21 for function code X'0007'. However, for compatibility with prior releases, invokers who only use function codes X'0001' through X'0005' can continue to specify a NumParms value of 10.
Use of the Add function code first requires an invocation of R_cacheserv with the Start function code. After all records have been added, R_cacheserv must be invoked one additional time with the End function code to indicate that the cache has been filled and should be made available for use. Only the issuer of Start (same task) can Add and End.
To allow the R_cacheserv callable service to harden/restore the cache to/from the RACF® database as profiles in the CACHECLS class, two steps must be taken:
1. the class must be made active by the RACF SETROPTS CLASSACT command, that is, SETROPTS CLASSACT(CACHECLS)
2. a base profile for this cache must be defined in the CACHECLS class using the RACF RDEFINE command, that is, RDEFINE CACHECLS cachename, where cachename is the Cache_name given as input to the R_cacheserv callable service.
Unless both of these steps are taken, the harden and restore phases of the End and Fetch functions, respectively, will not be performed for the cache identified by Cache_name.
When the cache is hardened to the RACF database, the cache contents are written to the database as profiles containing 50K pieces of the cache with the last profile's size being less than or equal to 50K. The names of the profiles are constructed from the input Cache_name parameter by adding the values _ddd, where ddd is the sequential dataspace number (in decimal), starting with 001 and _nnnnn, where nnnnn is the number of the profile containing cache information for that dataspace, also in decimal. The first 50K of the cache is written as cachename_001_00001, the second as cachename_001_00002, and so on. The profiles will be created with the same owner as that of the base profile.
If a request is made to Start a cache, followed by any number of Add requests, then Start is requested again for the same cache name without an intervening End request, this will result in the Start of a new empty cache, causing all records that were previously added to be discarded.
If a Start, Add, or End (Option X'0001') results in a SAF return code of 8, the state of the cache is undefined and it is highly recommended that R_cacheserv be invoked again, specifying End with Option X'0002' to discard the new cache, leaving the existing cache intact. Note that if the SAF return code 8 was caused by an ABEND during Start or Add, End with Option X'0002' will result in SAF return code 8 with RACF return code 8 and RACF reason code 36, indicating that the new cache was already discarded during ABEND recovery processing.
If more than one record is added to the cache with the same name (specified using the Record_name_ptr parameter), Fetch results are unpredictable.
The dataspaces that form the cache are associated with the master address space and are persistent so that records in the cache can be fetched from any address space. Function code X'0005' can be used to delete the cache when its contents no longer need to be accessed.
Function codes X'0001' through X'0005', function code X'0006', and function code X'0007' are not compatible. In other words, function code X'0006' option X'0003' cannot be used to retrieve a record that was added to a cache using function code X'0002' and function code X'0004' cannot be used to fetch a record that was stored using function code X'0006' option X'0001'.
For function code X'0006', Manage a read/write cache, and function code X'0007', Manage an extended read/write cache, when a parameter list error is detected, R_cacheserv returns SAF return code 8, RACF return code 12, and RACF reason code nn, where nn indicates the position in the parameter list of the parameter in error. For example, the NumParms parameter is the 9th parameter in the parameter list, so if an invalid value is supplied, R_cacheserv will return SAF return code 8, RACF return code 12, and RACF reason code 9.
If a supervisor state or system key caller specifies a valid ACEE on a Store request (option X’0001’), RACF will use the specified ACEE to build and store an application data record name and an application data record. The Record_name_ptr, Record_name_length, Data_ptr, and Data_length parameters will be ignored. See the description of the ACEE parameter for more information.
If no ACEE (see the parameter description for more information), source record, application data record name, and application data record are specified (Source_length, Record_name_length, and Data_length are all zeros) on a Store request, RACF will build and store the application data record name and the application data record using the task-level ACEE if found, or the address space ACEE.
.
R_cacheserv does not use the parmALET value when it obtains storage for the application data record name, the application data record, the ICRX, or the source record. Storage will always be obtained in the primary address space.
When RACF is enabled for sysplex communication and it determines that an R_cacheserv retrieve or remove request (function code X’0006’, options X'0003', X'0004', or X'0005' and function code X'0007', options X'0002' and X'0003') is for data that is cached on another member of the sysplex, RACF will attempt to retrieve or remove the data from the other member. See z/OS Security Server RACF System Programmer's Guide for more information about how to enable RACF for sysplex communication.
RACF recommends that customers put the Integrated Cryptographic Service Facility (ICSF) CSNBRNG module in the link pack area (LPA) or the modified link pack area (MLPA) so that it can be used for generating reference values (Reference parameter). If RACF cannot find CSNBRNG in LPA or MLPA, it will default to using a less efficient software pseudo random number generator (PRNG) for generating reference values.
The RACF read/write cache, function code X'0006', has a capacity limit of 2 GB. Assuming that application data records are less than 500 bytes, the cache can contain a maximum of approximately 4 million records at any point in time. When data records are in the 501-1000 byte range, the maximum number of cached records will be approximately 2 million. However, RACF does cache cleanup regularly by doing an internal RemoveExpired, so it is unlikely that cache limits will be reached.
Function code X'0007', option X'0001' stores an ENVR object in the extended read/write cache. This ENVR object does not include any installation data pointed to by ACEEIEP.