R_datalib might return one of several values as the SAF and RACF® return and reason codes. This topic defines
the return codes that can be returned by any of the functions. In
addition, each function of R_datalib has its own unique set of return
codes, which are also listed in this topic.
Table 1. R_datalib return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 0 |
0 |
0 |
The service was successful. |
| 4 |
0 |
0 |
RACF is
not installed. |
| 8 |
8 |
4 |
Parameter list error occurred. Attributes
were not specified as 0 or the last word in the parameter list did
not have the higher order bit on. |
| 8 |
8 |
8 |
Not RACF-authorized to use the requested service. |
| 8 |
8 |
12 |
Internal error caused recovery to
get control. |
| 8 |
8 |
16 |
Unable to establish a recovery environment. |
| 8 |
8 |
20 |
Requested Function_code not defined. |
| 8 |
8 |
24 |
Parm_list_version number not supported. |
| 8 |
8 |
28 |
Error in Ring_name or RACF_userid parameter (Note:
Ring_name value is case sensitive). |
| 8 |
8 |
72 |
Caller not in task mode. |
| 8 |
8 |
92 |
Other internal error. |
| 8 |
8 |
96 |
The linklib (steplib or joblib) concatenation
contains a non-APF authorized library. |
| 8 |
12 |
0x00xxyyyy |
An unexpected error is returned from ICSF. The
hexadecimal reason code value is formatted as follows:
- xx - ICSF return code
- yyyy - ICSF reason code
|
Function-specific return and reason codes for DataGetFirst and
DataGetNext:
Table 2. DataGetFirst and
DataGetNext return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 8 |
8 |
32 |
Length error in attribute_length,
Record_ID_length, label_length, or CERT_user_ID. |
| 8 |
8 |
36 |
dbToken error. The token may be zero,
in use by another task, or may have been created by another task. |
| 8 |
8 |
40 |
Internal error while validating dbToken. |
| 8 |
8 |
44 |
No certificate found with the specified status.  Possible causes are an empty keyring or there is
no certificate in the keyring that matches the specified criteria. This return and reason code is
also issued when a DataGetNext function is called and there are no more certificates in the
keyring. |
| 8 |
8 |
48 |
An output area is not long enough.
One or more of the following input length fields were too small: Certificate_length,
Private_key_length, or Subjects_DN_length. The length field(s) returned
contain the amount of storage needed for the service to successfully
return data. |
| 8 |
8 |
52 |
Internal error while obtaining record
private key data. |
| 8 |
8 |
56 |
Parameter error - Number_predicates, Attribute_ID or
Cert_status |
| 8 |
8 |
80 |
Internal error while obtaining the
key ring or z/OS® PKCS #11 token
certificate information or record trust information. |
| 8 |
8 |
84 |
The key ring profile for RACF_user_ID/Ring_name
or z/OS PKCS #11 token is not
found, or the virtual key ring user ID does not exist. |
Function-specific return and reason codes for DataAbortQuery:
Table 3. DataAbortQuery return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 8 |
8 |
36 |
dbToken error. The token might be
zero, in use by another task, or might have been created by another
task. |
| 8 |
8 |
40 |
Internal error while validating dbToken. |
Function-specific return and reason codes for CheckStatus:
Table 4. CheckStatus return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 0 |
0 |
0 |
Certificate is trusted or certificate
not registered with RACF. |
| 8 |
8 |
60 |
Internal error - Unable to decode
certificate. |
| 8 |
8 |
64 |
Certificate is registered with RACF as not trusted. |
| 8 |
8 |
68 |
Parameter error - zero value specified
for Certificate_length or Certificate_ptr. |
Function-specific return and reason codes for GetUpdateCode:
Table 5. GetUpdateCode return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 8 |
8 |
84 |
The key ring profile for RACF_user_ID/Ring_name
or z/OS PKCS #11 token is not
found, or the virtual key ring user ID does not exist. |
| 8 |
8 |
88 |
Internal error - Unable to obtain the key ring
or the z/OS PKCS #11 token
data. |
Function-specific return and reason codes for IncSerialNum:
Table 6. IncSerialNum return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 0 |
0 |
0 |
Success, serial number returned. |
| 8 |
8 |
76 |
Certificate is invalid. |
| 8 |
8 |
80 |
Certificate is not installed or is marked NOTRUST,
or does not have a private key. |
| 8 |
8 |
84 |
Parameter error. A zero value was specified
for one of the following parameters:
- a certificate length or certificate owned by another user.
- a minimum serial number.
|
Function-specific return and reason codes for NewRing:
Table 7. NewRing
return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 8 |
8 |
32 |
The profile for Ring_name is not found for REUSE. |
| 8 |
8 |
36 |
The profile for Ring_name already exists. REUSE
was not specified. |
| 8 |
8 |
40 |
The Ring_name is not valid. |
| 8 |
8 |
44 |
The RACF_user_ID is not valid or not found. |
Function-specific return and reason codes for DataPut:
Table 8. DataPut
return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 4 |
4 |
0 |
Success but the certificate’s status is
NOTRUST. |
| 4 |
4 |
4 |
Success but the DIGTCERT class needs to be refreshed
to reflect the update. |
| 4 |
4 |
8 |
Success but the Label information is ignored
because the certificate already exists in RACF. |
| 4 |
4 |
12 |
Success but the Label information is ignored
because the certificate already exists in RACF, and its status is NOTRUST. |
| 4 |
4 |
16 |
Success but the Label information is ignored
because the certificate already exists in RACF, and the DIGTCERT class needs to be refreshed
to reflect the update. |
| 8 |
8 |
32 |
Parameter error - incorrect value specified
for Certificate_length or Certificate_ptr, or the label area is too
small. |
| 8 |
8 |
36 |
Unable to decode the certificate. |
| 8 |
8 |
40 |
The private key is neither of a DER encoded
format nor of a key label format. |
| 8 |
8 |
44 |
Bad encoding of private key or unsupported algorithm
or incorrect key size. |
| 8 |
8 |
48 |
The specified private key does not match the
existing private key. |
| 8 |
8 |
52 |
Cannot find the key label. |
| 8 |
8 |
56 |
ICSF error when trying to find the key label. |
| 8 |
8 |
60 |
Not authorized to access ICSF key entry. |
| 8 |
8 |
64 |
The specified certificate label already exists
in RACF. |
| 8 |
8 |
68 |
The user ID specified by CERT_user_ID does not
exist in RACF. |
| 8 |
8 |
76 |
The certificate cannot be installed. |
| 8 |
8 |
80 |
The certificate exists under a different user. |
| 8 |
8 |
84 |
Cannot find the profile for Ring_name. |
Function-specific return and reason codes for DataRemove:
Table 9. DataRemove return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 4 |
4 |
0 |
Success to remove the certificate
from the ring but cannot delete the certificate from RACF because it is connected to
other rings. |
| 4 |
4 |
4 |
Success but cannot delete the certificate from RACF because of an unexpected error. |
| 4 |
4 |
8 |
Success but cannot delete the certificate from RACF because of insufficient authority. |
| 4 |
4 |
12 |
Success but the DIGTCERT class needs to be refreshed
to reflect the update. |
| 4 |
4 |
16 |
Success to remove the certificate from the ring but cannot delete the certificate from RACF because it is has been used to generate a request. |
| 8 |
8 |
32 |
Parameter error – incorrect value specified
for Label_length, Label_ptr or CERT_user_ID. |
| 8 |
8 |
36 |
Cannot find the certificate with the specified
label and owner ID. |
| 8 |
8 |
40 |
The profile for Ring_name is not found. |
| 8 |
8 |
44 |
Cannot delete the certificate from RACF because it is connected to other rings. |
| 8 |
8 |
48 |
Cannot delete the certificate from RACF because it is has been used to generate a request or its associated private key no longer exists in the PKDS or TKDS. |
Function-specific return and reason codes for DelRing:
Table 10. DelRing
return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 8 |
8 |
32 |
The profile for Ring_name is not found. |
Function-specific return and reason codes for DataRefresh:
Table 11. DataRefresh return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 4 |
4 |
0 |
The refresh is not needed. |
Function-specific return and reason codes for DataAlter:
Table 12. DataAlter return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 4 |
4 |
0 |
Success but the requested HIGHTRUST status is
changed to TRUST since the certificate does not belong to CERTAUTH |
| 4 |
4 |
4 |
Success but the DIGTCERT class needs to refresh
to reflect the update |
| 4 |
4 |
8 |
Success but the requested HIGHTRUST status is
changed to TRUST since the certificate does not belong to CERTAUTH,
and the DIGTCERT class needs to refresh to reflect the update |
| 8 |
8 |
32 |
Parameter error - invalid value specified for
Label_length, Label_ptr, New_Label_length or New_Label_ptr |
| 8 |
8 |
36 |
Certificate not found |
| 8 |
8 |
40 |
New certificate label specified already exists in RACF for this user |
| 8 |
8 |
44 |
User ID specified by CERT_user_ID does not exist in RACF |
Function-specific return and reason codes for GetRingInfo:
Table 13. GetRingInfo return and reason codes
| SAF return code |
RACF return
code |
RACF reason
code |
Explanation |
| 4 |
4 |
0 |
There are more rings to be returned. |
| 4 |
4 |
8 |
There are more rings that satisfy the searching
criteria, but can not be returned due to insufficient authority. |
| 8 |
8 |
32 |
No ring found. |
| 8 |
8 |
36 |
Parameter error - invalid value specified |
| 8 |
8 |
40 |
The output area is too small for 1 set of result.
The Ring_result_length returned contains the amount of storage needed. |
| 8 |
8 |
44 |
User ID specified by RACF_user_ID does not exist in RACF |
| 8 |
8 |
48 |
The ring specified as the search criteria for
other rings is not found |
Note: For search type 0 which is used for getting
ring information for a specific ring, if insufficient authority is
granted, 8 8 8 will be returned. For other search types which are
used for getting ring information for multiple rings, only the authorized
entries will be returned, with return/reason code 4 4 8.