This topic describes these parameters, which are used by most of the callable services:

• Return_code
• Reason_code
• Exit_data_length
• Exit_data
• Key_identifier

Return and Reason Codes

Return_code and reason_code parameters return integer values upon completion of the call.

Return_code

The return code parameter contains the general results of processing as an integer.

Table 2 shows the standard return code values that the callable services return. A complete list of return codes is shown in Appendix A. ICSF and TSS Return and Reason Codes.

Table 2. Standard Return Code Values From ICSF Callable Services

Value Hex (Decimal)	Meaning
00 (00)	Successful. Normal return.
04 (04)	A warning. Execution was completed with a minor, unusual event encountered.
08 (08)	An application error occurred. The callable service was stopped due to an error in the parameters. Or, another condition was encountered that needs to be investigated.
0C (12)	Error. ICSF is not active or an environment error was detected.
10 (16)	System error. The callable service was stopped due to a processing error within the software or hardware.

Generally, PCF macros will receive identical error return codes if they execute on PCF or on ICSF. A single exception has been noted: if a key is installed on the ICSF CKDS with the correct label but with the wrong key type, PCF issues a return code of 8, indicating that the key type was incorrect. ICSF issues a return code of 12, indicating that the key could not be found.

Reason_code

The reason code parameter contains the results of processing as an integer. You can specify which set of reason codes (ICSF or TSS) are returned from callable services. The default value is ICSF. For more information about the REASONCODES installation option, see z/OS Cryptographic Services ICSF System Programmer’s Guide. Different results are assigned to unique reason code values under a return code.

A list of reason codes is shown in Appendix A. ICSF and TSS Return and Reason Codes.

Exit Data Length and Exit Data

The exit_data_length and exit_data parameters are described here. The parameters are input to all callable services. Although all services require these parameters, several services ignore them.

Exit_data_length

The integer that has the string length of the data passed to the exit. The data is identified in the exit_data parameter.

Exit_data

The installation exit data string that is passed to the callable service’s preprocessing exit. The installation exit can use the data for its own processing.

For more information about the exits, see z/OS Cryptographic Services ICSF System Programmer’s Guide.

Key Identifier for Key Token

A key identifier for a key token is an area that contains one of these:

• Key label identifies keys that are in the CKDS or PKDS. Ask your ICSF administrator for the key labels that you can use.
• Key token can be either an internal key token, an external key token, or a null key token. Key tokens are generated by an application (for example, using the key generate callable service), or received from another system that can produce external key tokens.

  An internal key token can be used only on ICSF because the master key encrypts the key value. Internal key tokens contain keys in operational form only.

  An external key token can be exchanged with other systems because a transport key that is shared with the other system encrypts the key value. External key tokens contain keys in either exportable or importable form.

  A null key token can be used to import a key from a system that cannot produce external key tokens. A null key token contains a key encrypted under an importer key-encrypting key but does not contain the other information present in an external key token.

The term key identifier is used to indicate that different inputs are possible for a parameter. One or more of the previously described items may be accepted by the callable service.

Key Label

If the first byte of the key identifier is greater than X'40', the field is considered to be holding a key label. The contents of a key label are interpreted as a pointer to a CKDS or PKDS key entry. The key label is an indirect reference to an internal key token.

A key label is specified on callable services with the key_identifier parameter as a 64-byte character string, left-justified, and padded on the right with blanks. In most cases, the callable service does not check the syntax of the key label beyond the first byte. One exception is the CKDS key record create callable service which enforces the KGUP rules for key labels unless syntax checking is bypassed by a preprocessing exit.

A key label has this form:

There are some general rules for creating labels for CKDS key records.

• Each label can consist of up to 64 characters. The first character must be alphabetic or a national character (#, $, @). The remaining characters can be alphanumeric, a national character (#, $, @), or a period (.).
• All alphabetic characters must be upper case (A-Z). All labels in the key data sets are created with upper case characters.
• Labels must be unique for DATA, DATAXLAT, MAC, MACVER, DATAM, and DATAMV keys.
• For compatibility with Version 1 Release 1 function, transport and PIN keys can have duplicate labels for different key types. Keys that use the dynamic CKDS update services to create or update, however, must have unique key labels.
• Labels must be unique for any key record, including transport and PIN keys, created or updated using the dynamic CKDS update services.