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