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'.

X'0001'-Start a new cache.

The cache is created and the caller is now ready to start adding records. No one but the caller has access to the cache. The cache is not made available to other callers at this time.

X'0002'-Add a record to the new cache.

The caller must provide a name for this record and the data associated with the record. The caller calls this function multiple times, once per record to complete the cache. Only the caller of function code X'0001' may call function code X'0002'. A caller of function code X'0002' who is not the same task as the one who called function code X'0001', will not be allowed to add a record to the cache.

X'0003'-End cache creation.

Only the caller of function code X'0001' is allowed to end the creation of the cache. A caller of function code X'0003' who is not the same task as the one who called function code X'0001', will not be allowed to end cache creation. This function is further defined by the Option parameter.

If the Option parameter is X'0001':

• The cache is made available, with system-wide name/token service, to callers of function x'0004' so they can retrieve records from the cache. Any previous cache of the same Cache-name is deleted.
• The cache is hardened to the RACF® database if the CACHECLS class is active and if a profile exists in that class with a profile name identical to the Cache_name provided as input to R_cacheserv.

If the Option parameter is X'0002', discard the new cache and leave the existing cache intact. This is used if the calling application determines that something is wrong with the new cache or encounters an error while creating it.

X'0004'-Fetch information from cache.

Retrieve information from the cache. This function is further defined by the Option parameter.

If the Option parameter is X'0001' and the cache already exists, the requested (by name) record is retrieved for the caller (or is not found). If the cache does not exist yet (for example, right after IPL), a new cache can be automatically restored and populated with records that were hardened to the RACF database the last time someone called function code x'0003'. The cache is restored if the CACHECLS class is active and the cachename_ddd_nnnnn profiles containing the cache contents exist. Data and Data_Length are updated.

If the Option parameter is X'0002', then retrieve the version number of the existing in-storage cache. If no in-storage cache exists, retrieve the version from the database-hardened copy of the cache. Do not restore the cache from the database in this case. Version and Version_Length are updated.

X'0005'-Delete the cache.

This function is further defined by the Option parameter.

If the Option parameter is X'0001', then delete the in-storage cache only.

If the Option parameter is X'0002', then delete the hardened database copy of the cache only.

If the Option parameter is X'0003', then delete both the hardened database copy and in-storage cache.

X'0006'-Manage a read/write cache.

The function code X'0001-X'0005' cache is essentially a read-only cache. All of the data is added to the cache before the cache is made available for retrieval and if data needs to be changed a new cache must be created. This function, X'0006', provides support for a read/write cache. Multiple callers can store and retrieve cache data at the same time.

The read/write cache is not hardened to the RACF database.

This function is further defined by the Option parameter.

If the Option parameter is X'0001', then Store data in the read/write cache and return a reference to the data.

• The caller can store the following records:
  • A source record (Source_ptr parameter). The caller is responsible for building the source record. It will be stored as binary data.
  • An application data record (Data_ptr parameter). Like the source record, the caller is responsible for building the application data record and it will be stored as binary data. The caller must also specify the name of the record (Record_name_ptr parameter), so that the application data record can be found on a Locate request. The caller can also store a null application data record, by specifying a record name and a Data_length of zero.

  If the caller is in supervisor state or system key and 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. The ACEE parameter is ignored unless specified by a caller in supervisor state or system key.

  If no ACEE, source record, application data record name, and application data record are specified on a Store request (Source_length, Record_name_length, and Data_length are all zeros), 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.

  See the descriptions of the Record_name_ptr and Data_ptr parameters for more information about the structure of the application data record name and application data record built by RACF.

• When the Store is successful, a cache reference is returned. A cache reference consists of both a reference value (Reference parameter) and an associated reference user ID (Reference_userID parameter). The cache reference can be used to retrieve the source record and the application data record (Retrieve option), retrieve just the application data record (RetrieveAppl option), or to remove the source record (Remove option).

  A cache reference can only be used to retrieve or remove data one time. When it has been specified, the cache reference is no longer valid.

  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 caller can use the Reference_timeout parameter to control the lifespan of the cache reference, by specifying the time interval in which it can be used. When this interval has expired, the reference can only be used to Remove the source record. A retrieve request (Retrieve, RetrieveAppl) will fail when an expired cache reference is specified. The RemoveExpired option also uses the reference timeout interval to determine when source records can be removed from the cache. If not specified, a default timeout value will be assumed.
• The caller can use the Data_timeout parameter to control the lifespan of the application data record, by specifying the time interval in which it can be used. When this interval has expired, the record will not be found on a Locate request. The RemoveExpired option also uses the data timeout interval to determine when application data records can be removed from the cache. If not specified, a default timeout value will be assumed.
• If the cache does not exist yet, the first Store request will cause it to be created.

If the Option parameter is X'0002', then Locate an application data record in the read/write cache, store the specified source record, and return a reference to the data.

• The caller must specify the application data record name that was specified when the application data record was stored (Record_name_ptr parameter).
• Locate uses the timeout interval that was specified when the application data record was stored (Data_timeout parameter). When this interval has expired, the record will not be found.
• The caller must specify a source record (Source_ptr parameter) and, optionally, a reference timeout interval (Reference_timeout parameter). If not specified, a default timeout value will be assumed.
• When the Locate is successful, the source record is stored in the cache and a cache reference is returned. A cache reference consists of both a reference value (Reference parameter) and an associated reference user ID (Reference_userID parameter). The cache reference can be used to retrieve the source record and the application data record(Retrieve option), retrieve just the application data record (RetrieveAppl option), or to remove the source record (Remove option).

  A cache reference can only be used to retrieve or remove data one time. When it has been specified, the cache reference is no longer valid.

  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.

If the Option parameter is X'0003', then Retrieve data from the read/write cache.

• The caller must specify a cache reference. A cache reference consists of both a reference value (Reference parameter) and an associated reference user ID (Reference_userID parameter).

  A cache reference can only be used to retrieve data one time. When it has been specified, the cache reference is no longer valid.

• Retrieve uses the reference timeout interval that was specified on a Store or Locate request (Reference_timeout parameter). When this interval has expired, Retrieve will fail.
• When a Retrieve is successful, the following data can be returned:
  • A source record (Source_ptr parameter). The Source_length parameter contains the length of the record and the Source_ptr parameter contains the name of a fullword containing the address of the source record. Storage for the record is obtained in the subpool specified by the caller (Subpool parameter) and the caller is responsible for freeing it. A length of zero indicates that no source record was returned.
  • An application data record name (Record_name_ptr parameter). The Record_name_length parameter contains the name of a fullword containing the address of the application data record name. Storage for the application data record name is obtained in the subpool specified by the caller (Subpool parameter) and the caller is responsible for freeing it. A length of zero indicates that no application data record name was returned.
  • An application data record (Data_ptr parameter). The Data_length parameter contains the length of the record and the Data_ptr parameter contains the name of a fullword containing the address of the application data record. If the caller specifies an area and length that is large enough to contain the application data record, RACF will return the record in that area. If the caller specifies an area and length that is too small to contain the record, RACF will obtain storage in the specified subpool (Subpool parameter) and will return the address of the application data record along with SAF return code 0, RACF return code 0, and RACF reason code 16. The caller can also just specify a length of zero to ask that RACF obtain storage without returning the 0/0/16 return code. Data_length will be set to the actual length of the application data record retrieved. The caller is responsible for freeing all application data record output areas, either provided by the caller or obtained by RACF. A length of zero indicates that no application data record was returned.

If the Option parameter is X'0004', then retrieve application data (RetrieveAppl) from the read/write cache.

• The caller must specify a cache reference. A cache reference consists of both a reference value (Reference parameter) and an associated reference user ID (Reference_userID parameter).

  A cache reference can only be used to retrieve data one time. When it has been specified, the cache reference is no longer valid.

• RetrieveAppl uses the reference timeout interval that was specified when the application data record was stored (Reference_timeout parameter). When this interval has expired, no data will be found.
• When a RetrieveAppl is successful, the following data can be returned:
  • An application data record name (Record_name_ptr parameter). The Record_name_length parameter contains the name of a fullword containing the address of the application data record name. Storage for the application data record name is obtained in the subpool specified by the caller (Subpool parameter) and the caller is responsible for freeing it. A length of zero indicates that no application data record name was returned.
  • An application data record (Data_ptr parameter). The Data_length parameter contains the length of the record and the Data_ptr parameter contains the name of a fullword containing the address of the application data record. If the caller specifies an area and length that is large enough to contain the application data record, RACF will return the record in that area. If the caller specifies an area and length that is too small to contain the record, RACF will obtain storage in the specified subpool (Subpool parameter) and will return the address of the application data record, along with SAF return code 0, RACF return code 0, and RACF reason code 16. The caller can also just specify a length of zero to ask that RACF obtain storage without returning the 0/0/16 return code. Data_length will be set to the actual length of the application data record retrieved. The caller is responsible for freeing all application data record output areas, either provided by the caller or obtained by RACF. A length of zero indicates that no application data record was returned.

If the Option parameter is X'0005', then Remove a source record from the read/write cache.

• The caller must specify a cache reference. A cache reference consists of both a reference value (Reference parameter) and an associated reference user ID (Reference_userID parameter).
• When a source record is retrieved (option X'0003'), RACF marks it as expired and eligible for explicit or internal RemoveExpired processing, so caller invocation of Remove processing is optional.

If the Option parameter is X'0006', then remove all expired records from the read/write cache (RemoveExpired).

• RemoveExpired uses the timeout values specified when the data was stored to determine which records are expired, so they are no longer valid. Source records are removed based on the reference timeout interval (Reference_timeout parameter) and application data records are removed based on the data timeout interval (Data_timeout parameter).
• RACF does cache cleanup on a regular basis by doing an internal RemoveExpired, so caller invocation of RemoveExpired processing is optional.

If the Option parameter is X'0007', then Destroy the read/write cache.

• The read/write cache is destroyed. All references to data in the cache are no longer valid.

  Under normal circumstances, the caller should have no reason to destroy the read/write cache. This option is provided only as a means for a customer, working with IBM® support, to recover from a catastrophic cache error.

• A subsequent request to Store data will cause a new cache to be created.

  The value of the Option parameter also determines how other parameters will be used for Function_code X'0006'. For example, on a Store (Option X'0001') request, Data_ptr is an input parameter and on a Retrieve (Option X'0003') request, it is an output parameter. See the description of Function_code X'0006' for more information.

X'0007'-Manage an extended read/write cache.

The cache for function codes X'0001-X'0005' is essentially a read-only cache. All of the data is added to the cache before the cache is made available for retrieval, and if data needs to be changed a new cache must be created. Function code X'0006' provides support for a read/write cache of distributed user information. Function code X’0007’ provides support for an extended read/write cache containing both RACF and distributed user information. Multiple callers can store and retrieve cache data at the same time. The read/write cache is not hardened to the RACF database.

This function is further defined by the Option parameter.

If the Option parameter is X'0001', then locate the record if present. If the record is not present, Store data in the read/write cache, and return an extended context reference to the data.

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 (the ICRXREFR portion of the ICRX). 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.

• If the caller is in supervisor state or system key and specifies a valid ACEE on a Store request (option X'0001'), RACF will use the specified ACEE to locate, or to build and store, an application data record name and an application data record. The Source_length, Record_name_length, Data_length parameters, and their associated data parameters will be ignored. See the description of the ACEE parameter for more information. The ACEE parameter is ignored unless specified by a caller in supervisor state or system key.
• If no ACEE is specified on a Store request, or it is ignored because of the caller’s state, 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.
• If the locate or the store is successful, an extended cache reference will be returned in the ICRX_area parameter, and the length of the ICRX in the ICRX_length parameter. The ICRX will contain a cache reference consisting of a reference value and an associated reference user ID, as well as the RACF user ID and IDID value. The ICRX can be used to retrieve the application data (RetreiveAppl option) or to remove the reference (Remove option). The structure of the ICRX data area is detailed in z/OS Security Server RACF Data Areas.
• A cache reference can only be used to retrieve or remove data one time. When it has been specified, the cache reference is no longer valid.
• The Reference_timeout and Data_timeout parameters are ignored for function code X’0007’ since these values are set internally by RACF.

If the Option parameter is X'0002', then retrieve application data (RetrieveAppl) from the read/write cache. The caller must specify an extended cache reference (ICRX_area parameter) containing a cache reference.

• When a RetrieveAppl is successful, an application data record (Data_ptr parameter) is returned. The Data_length parameter contains the length of the record and the Data_ptr parameter contains the name of a fullword containing the address of the application data record. If the caller specifies an area and length that is large enough to contain the application data record, RACF will return the record in that area (ALET-qualified through the ParmALET parameter). If the caller specifies an area and length that is too small to contain the record, RACF will obtain storage in the specified subpool (Subpool parameter) and will return the address of the application data record, along with SAF return code 0, RACF return code 0, and RACF reason code 16. The caller can also just specify a length of zero to ask that RACF obtain storage without returning the 0/0/16 return code. If RACF obtains storage for the return of the data record, the storage will be obtained in the primary address space. Data_length will be set to the actual length of the application data record retrieved. The caller is responsible for freeing all application data record output areas, either provided by the caller or obtained by RACF. A length of zero indicates that no application data record was returned.

If the Option parameter is X'0003', then Remove a context reference record from the read/write cache.

• The caller must specify an extended cache reference (ICRX_area parameter) containing a cache reference.
• Remove processing is optional since records will be marked expired after a period of time and will become eligible for internal removal processing.
• Option parameter X’0003’ can also be used to remove an application data record from the read/write cache by marking it no longer valid. The caller must specify an ICRX_area parameter containing the IDID information needed to identify the record, without a cache reference. Once marked not valid, attempts to retrieve the record using outstanding context references will no longer find the record, and it will not be used for subsequent store requests.

If the Option parameter is X'0004' (store and return reusable ICRX), then processing proceeds as with Option X'0001', but the returned ICRX will be marked as being reusable. This ICRX will be valid for multiple Option X'0002' RetrieveAppl calls until it times out after an hour of inactivity.

If the Option parameter is X'0005' (validate the input ICRX), we will validate the input ICRX and the IDID included in it. This function is intended to validate the user-built ICRX that is provided by the application to a subsystem like CICS®, not the completed ICRX that is returned by RACF to the caller of R_cacheserv as is done with Option X'0001', which contains the RACF user-id in ICRXUSER and the ICR. The caller must be in supervisor state or system key.

The following fields will be validated:

• ICRX fields:
  • ICRXID – The value must be the literal 'ICRX'
  • ICRXVERS – The value must be greater than or equal to ICRXVR01 and less than or equal to the current version – ICRXCURV (currently set to 2)
  • ICRXOFFN – The number of offsets must be 3 (for versions 1 and 2 of the ICRX)
  • ICRXFLGS – The value of this flag-byte must be 0
  • ICRXLEN – The value must be greater than or equal to the length of the ICRX header – ICRXHLN, and less than or equal to the length of the ICRX provided in the R_cacheserv parameter list
  • ICRXICRO – Must be 0
  • ICRXDIDO – Must be equal to the length of the ICRX header – ICRXHLN
  • ICRXUSRO – Must be 0
• IDID fields:
  • IDIDID – The value must be the literal 'IDID'
  • IDIDVERS – The value must be greater than or equal to IDIDVR01 and less than or equal to the current version – IDIDCURV (currently set to 1)
  • IDIDOFFN – The number of offsets must be 5 (for version 1 of the IDID)
  • IDIDHSHN – The three high order bits of this bit string must be off (0), and for any IDID section not specified (offset is 0), the corresponding bit must be off (0)
  • IDIDSP – The value must be the same as the value in ICRXSP
  • IDIDLEN – The value must be greater than the length of the IDID header – IDIDHLN, and the sum ICRXDIDO + IDIDLEN must be less than or equal to the length of the ICRX – ICRXLEN
  • IDIDOFF1 – Must be equal to the length of the IDID header – IDIDHLN
  • IDIDOFF2 – Must be 0
  • IDIDOFF3, IDIDOFF4, and IDIDOFF5 – Must be either 0, or (if non-zero) must be contained within the IDID and be in sequential order.
• IDID Section1 fields:
  • IDID1OF1 – Must be equal to the length of the IDID Section1 header
  • IDID1UDL – Must be greater than or equal to 1 and less than or equal to the value indicated by RCVTDNL
  • IDID1OF2 – Must be equal to the sum of the length of the IDID Section1 header, the length of IDID1UDL, and the value specified in IDID1UDL
  • IDID1RL – Must be greater than equal to 1 and less than or equal to the value indicated by RCVTRL

See Parameter Usage for the function codes to which the Option parameter applies. Valid option values and their effect on the specified function code are described above under the Function_code parameter.

When hardening to the RACF database, the cache version identifier is compared with the version already hardened. If the versions are the same, the new cache will not be hardened.

The cache name is used internally to isolate multiple caches from each other. It is also used to generate names of the dataspace(s) that will form the cache, and also the profile names used to harden the contents of the cache to the RACF database as profiles in the CACHECLS class.

Function code X'0006' (Manage a read/write cache) with Options X’0001’ (Store), X’0002’ (Locate), X'0003' (Retrieve), and X’0004’ (RetrieveAppl) only: Name of the address of the application data record name to be stored (option X'0001') or located (option X'0002'), or name of a fullword where the address of the application data record name is to be placed during retrieval (options X'0003' and X'0004').

When an application data record is specified on a Store (option X'0001') request, the caller must also specify the application data record name. The caller is responsible for obtaining and freeing storage for the application data record name. The length is specified in Record_name_length. When an application data record is not specified on a Store request (Data_length is zero), specification of an application data record name is optional.

If the caller is in supervisor state or system key and 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.

When an application data record name is built from an ACEE, ICTXLEN is set to the value that will be used for Record_name_length.

When Locate (option X'0002') is specified, the caller must provide an application data record name and is responsible for obtaining and freeing storage for the application data record name. The length is specified in Record_name_length.

When Retrieve (option X'0003') or RetrieveAppl (option X'0004') is specified, RACF obtains storage for the application data record name in the subpool provided by the Subpool parameter. Storage will be obtained in the primary address space. The caller is responsible for freeing this storage. Record_name_length will be set to the actual length of the record name retrieved.

This parameter is ignored for function code X'0007'.

Function code X’0006’ (Manage a read/write cache) with Options X’0001’ (Store), X’0002’ (Locate), X’0003’ (Retrieve), and X'0004' (RetrieveAppl) only: Name of a fullword containing the length of the application data record name to be stored (option X'0001') or located (option X'0002'), or the length of the application data record name retrieved (options X'0003' and X'0004').

When Store (option X'0001') is specified, a zero length indicates that the application data record name has not been specified. Otherwise, valid values are 1 to 8192.

When Retrieve (option X'0003') or RetrieveAppl (option X'0004') is specified, Record_name_length will be set to the actual length of the record name retrieved.

This parameter is ignored for function code X'0007'.

Function code X'0006' (Manage a read/write cache) with Options X'0001' (Store), X'0003' (Retrieve), and X'0004' (RetrieveAppl) only: Name of the address of the application data record to be stored (option X'0001'), or name of a fullword where the address of the application data record is to be placed during retrieval (options X'0003' and X'0004').

• When an application data record is specified on a Store (option X'0001') request, the length is specified in Data_length.
• If the caller is in supervisor state or system key and 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.

  An application data record built by RACF has the following structure:

  Table 1. Structure of an application data record built by RACF

  OFFSET (DECIMAL)	OFFSET (HEX)	TYPE	LENGTH	NAME	DESCRIPTION
  0	0	STRUCTURE	12	ApplData	Application data record.
  0	0	UNSIGNED	4	ApplVersion	Format version. For this release, this field is set to X’00000001’.
  4	4	UNSIGNED	4	ApplUserIDLen	Length of a security manager (RACF) user ID, or zero if the user ID is omitted. The user ID has a maximum length of 8 bytes.
  8	8	UNSIGNED	4	ApplUserIDOff	Offset of user ID.
  12	C	CHARACTER	*		Data related to the length and offset pairs begins here.

  The length of the application data record is equal to the length of the ApplData structure plus the sum of the lengths of the data related to the length and offset pairs. When an application data record is built from an ACEE, RACF will set ApplUserIDLen and the value pointed to by ApplUserIDOff from the ACEE user ID values (ACEEUSRL and ACEEUSRI).

• When Retrieve (option X’0003’) or RetrieveAppl (option X’0004’) is specified, the caller can either specify the address where the output application data record is to be placed, or RACF will obtain an area and return the address of that area. If the caller specifies an area and length that is large enough to contain the application data record, RACF will return the record in that area, ALET qualified using the ParmALET. If the caller specifies an area and length that is too small to contain the record, RACF will obtain storage in the specified subpool (Subpool parameter) and will return the address of the application data record along with SAF return code 0, RACF return code 0 and RACF reason code 16. The caller can also just specify a length of zero to ask that RACF obtain storage without returning the 0/0/16 return code. If RACF obtains storage for the return of the data record, the storage will be obtained in the primary address space. Data_length will be set to the actual length of the application data record retrieved. The caller is responsible for freeing all application data record output areas, either provided by the caller or obtained by RACF. A length of zero indicates that no application data record was returned.

When Function_code X'0004' (Fetch) and Option X'0001' are specified, Data_length will be set to the actual length of the data requested. If return and reason codes indicate that an insufficient length value was specified, resulting in a return of partial data, use the updated Data_length value to obtain a larger results area and resubmit the request.

This parameter applies only to function code X'0006' (Manage a read/write cache)

When Store (option X'0001') or Locate (option X'0002') is specified, the caller is responsible for obtaining and freeing storage for the source record. The length is specified in Source_length.

When Retrieve (option X'0003') is specified, R_cacheserv obtains storage for the source record in the subpool provided by the Subpool parameter. Storage will be obtained in the primary address space. The caller is responsible for freeing this storage. The length is returned in Source_length.

This parameter applies only to function code X'0006' (Manage a read/write cache)

When Store (option X'0001') is specified, a zero length indicates that the source record has not been specified. Otherwise, valid values are 1 to 8192.

When Retrieve (option X'0003') is specified, Source_length will be set to the actual length of the record retrieved.

This parameter applies only to function code X'0006' (Manage a read/write cache)

This parameter applies only to function code X'0006' (Manage a read/write cache)

A successful Store (option X'0001') or Locate (option X'0002') request will return a cache reference, consisting of both a Reference_userID value and a Reference value. The Reference_userID and Reference value pair can be used on a subsequent Retrieve (option X'0003'), RetrieveAppl (option X'0004'), or Remove (X'0005') request. Only a Reference_userID and Reference value pair from a successful Store or Locate request will produce expected results on a Retrieve, RetrieveAppl, or Remove request.

An output reference user ID will be prefixed by the characters “**” X(’5C5C’). The remaining 6 characters are reserved for use by the security manager (RACF).

This parameter applies only to function code X'0006' (Manage a read/write cache)

A successful Store (option X'0001') or Locate (option X'0002') request will return a cache reference, consisting of both a Reference_userID value and a Reference value. The Reference_userID and Reference value pair can be used on a subsequent Retrieve (option X'0003'), RetrieveAppl (option X'0004'), or Remove (X'0005') request. Only a Reference_userID and Reference value pair from a successful Store or Locate request will produce expected results on a Retrieve, RetrieveAppl, or Remove request.

An output reference value will be a printable EBCDIC string, consisting of the characters “0-9”, “A-Z”, “$” (X’5B’), “#” (X’7B), or “@” (X’7C’).

This parameter applies only to function code X'0006' (Manage a read/write cache)

The ACEE must begin with the eyecatcher "ACEE". Otherwise, the area must contain binary zeros in the first 4 bytes. When the area contains binary zeros, RACF uses the task-level ACEE if found, or the address space ACEE.

For more information on extended identity context references and distributed identity data (IDID), refer to z/OS Security Server RACF Data Areas.