The name of the control block. The field must contain the character string KGXP. The exit must not change the value and KGUP does not use the field upon return from the exit.

The version of the control block. The field must contain the character string 03. The exit cannot change this field and KGUP does not use this field on return from the exit.

The length of the control block. The decimal value of the field is 408. The exit cannot change the field and KGUP does not use this field on return from the exit.

The return code the exit supplies upon completion. Upon entry, KGUP initializes this field to zeros. The valid decimal return codes for each of the invocation points are:

Record Pre- or postprocessing.

0

Normal, continue processing.

4

Reject control statement, but do not end KGUP.

8

End KGUP immediately.

KGUP pre- or postprocessing.

0

Normal, continue processing.

> 0

End KGUP immediately.

Indicates the invocation point of the exit. The exit cannot change this field and KGUP does not use this field on return from the exit. You can determine the invocation point by the bit that is set on.

Bit

Meaning When Set On

0

KGUP preprocessing invocation.

1

KGUP postprocessing invocation.

2

Record preprocessing invocation.

3

Record postprocessing invocation.

4-7

Reserved.

Indicates the keywords specified on the KGUP control statement. The exit cannot change this field and KGUP does not use the field upon return from the exit. The field is used only during the record preprocessing and postprocessing invocations. You can determine the keywords on the control statement by the bits that are set on.

Bit

Meaning When Set On

0

LABEL with multiple values specified.

1

RANGE specified.

2

KEY specified.

3

CLEAR specified.

4

SINGLE specified.

5

NOCV specified.

6

OUTTYPE specified.

7

Reserved.

Indicates the verb used on the KGUP control statement. The exit cannot change this field and KGUP does not use this field on return from the exit. The field is used only for the record preprocessing and record postprocessing invocations. You can determine the verb on the control statement by the bit that is set on.

Bit

Meaning When Set On

0

ADD

1

UPDATE

2

DELETE

3

RENAME

4

SET

5

OPKYLOAD

6-7

Reserved.

Indicates the processing conditions encountered by KGUP at the record postprocessing invocation. The exit cannot change this field and KGUP does not use the field upon return from the exit. The field is not used for the KGUP pre- or postprocessing invocations or the record preprocessing invocation. The processing conditions can be determined by examining whether bit 0 is set on.

Bit

Meaning When Set On

0

Non-odd parity key was imported.

1

Algorithm is AES

2

Algorithm is DES

3-7

Reserved.

Contains the key index accessed by the KGUP control statement. The key index consists of the key label and type fields of a CKDS record entry (Debugging Aids describes the CKDS record format in greater detail). The key index is the first 72 bytes of a CKDS record, and the information in the key index is used to differentiate one key from another.

The exit can modify the field at the record preprocessing invocation. The field is not used for the KGUP pre- or postprocessing invocation or the record postprocessing invocation.

If the exit modifies the field, KGUP uses the modified field to access the CKDS upon return from the exit.

Before the record preprocessing invocation, KGUP places this in this field:

• The key label or key old label from the LABEL or key label from the RANGE keyword of the control statement
• The key type from the TYPE keyword of the control statement

The exit cannot modify the key label, key old label, or key type.

Contains the key index used to rename a key when RENAME is the verb on the control statement. The key index consists of the key label and type fields of a CKDS record entry.

The exit can modify the field at the record preprocessing invocation. The field is not used for the KGUP pre- or postprocessing or record postprocessing invocations.

If the exit modifies the field, KGUP uses the modified field to access the CKDS upon return from the exit.

Before the record preprocessing invocation, KGUP places this information in this field:

• The key new label from the LABEL keyword of the control statement.
• The key type from the TYPE keyword of the control statement.

The exit cannot modify the key new label or the key type.

The key index of the TRANSKEY key-label1 on the KGUP control statement. The key index is the key label and type of the CKDS record entry.

The exit can modify the field at the record preprocessing invocation. The field is not used for the KGUP pre- or postprocessing and record postprocessing invocations.

If the exit modifies the field, KGUP uses the modified field to access the CKDS upon return from the exit.

Before the record preprocessing invocation, KGUP places this information in this field:

• The key-label1 from the TRANSKEY keyword of the control statement.
• The key type. The type is IMPORTER, if keys are supplied; the type is EXPORTER, if keys are not supplied.

The exit cannot modify the key-label1 or the key type.

The key index of the TRANSKEY key-label2 on the KGUP control statement. The key index is the key label and type of the CKDS record entry.

The exit can modify the field at the record preprocessing invocation. The field is not used for the KGUP pre- or postprocessing and record postprocessing invocations.

If the exit modifies the field, KGUP uses the modified field to access the CKDS upon return from the exit.

Before the record preprocessing invocation, KGUP places this information in this field:

• The key-label2 from the TRANSKEY keyword of the control statement.
• The key type. The key type is IMPORTER, if keys are supplied; the type is EXPORTER, if keys are not supplied.

The exit cannot modify the key-label2 or the key type.

The value supplied by the LENGTH keyword or the byte length of the key value if the KEY option was selected.

This value is for ease of processing the key values. The exit may not modify this value.

The value of the key supplied on the KGUP control statement. The 16 bytes are hexadecimal characters representing the 8-byte hexadecimal key value. The field contains a value only if the KEY option was specified and a key value was supplied on the control statement. You can determine whether the KEY option was used by examining bit 2 at offset +13 in KGXP.

If TRANSKEY was specified on the control statement, KGUP decrypts key-value1 under the transport key specified with the TRANSKEY keyword. If CLEAR was specified on the control statement, KGUP does not decrypt key-value1.

The exit can modify the field at the record preprocessing invocation. This field is not used for the KGUP pre- or postprocessing invocations or the record postprocessing invocation. The field does not contain a value when generating keys.

The exit is permitted to put values in this field only if a key was supplied on the control statement. The exit-supplied value must be edited for hexadecimal values and it then replaces the values entered on the input control statement.

The value of the second key supplied on the KGUP control statement. The 16 bytes are hexadecimal characters representing the 8-byte hexadecimal key value. The field contains a value only if the KEY option was specified and a key value was supplied on the control statement. You can determine whether the KEY option was used by examining bit 2 at offset +13 in KGXP.

If TRANSKEY was specified on the control statement, KGUP decrypts the key-value 2 under the transport key specified with the TRANSKEY keyword. If SINGLE was specified on the control statement, the key-value 2 will be equal to the key-value. If CLEAR was specified on the control statement, KGUP does not decrypt the key-value 2.

The exit can modify the field at the record preprocessing invocation. This field is not used at the KGUP pre- or postprocessing invocation or the record postprocessing invocation.

The field does not contain a value when generating keys.

The exit can put values in this field only if a key was supplied on the control statement. The exit-supplied value must be edited for hexadecimal values; it then replaces the values entered on the input control statement.

The value of the third key supplied on the KGUP control statement. The 16 bytes are hexadecimal characters representing the 8-byte hexadecimal key value. The field contains a value only if the KEY option was specified and a key value was supplied on the control statement. You can determine whether the KEY option was used by examining bit 2 at offset +13 in KGXP.

If TRANSKEY was specified on the control statement, KGUP decrypts the key-value 3 under the transport key specified with the TRANSKEY keyword. If CLEAR was specified on the control statement, KGUP does not decrypt the key-value 3.

The exit can modify the field at the record preprocessing invocation. This field is not used at the KGUP pre- or postprocessing invocation or the record postprocessing invocation.

The field does not contain a value when generating keys.

The exit can put values in this field only if a key was supplied on the control statement. The exit-supplied value must be edited for hexadecimal values; it then replaces the values entered on the input control statement.

The value of the fourth key supplied on the KGUP control statement. The 16 bytes are hexadecimal characters representing the 8-byte hexadecimal key value. The field contains a value only if the KEY option was specified and a key value was supplied on the control statement. You can determine whether the KEY option was used by examining bit 2 at offset +13 in KGXP.

The exit can modify the field at the record preprocessing invocation. This field is not used at the KGUP pre- or post-processing invocation or the record post-processing invocation. The field does not contain a value when generating keys.

The exit can put values in this field only if a key was supplied on the control statement. The exit-supplied value must be edited for hexadecimal values; it then replaces the values entered on the input control statement.

The address of the CSFKEYS data set record that is output for transkey key-label1 on the KGUP control statement. The field ONLY contains a value when generating keys. This field is filled in when CLEAR keys are generated.

The exit can modify the field at the record postprocessing invocation. KGUP sets the address to zero for the KGUP pre- or postprocessing and record preprocessing invocations.

KGUP does not check the field upon return from the exit. Normal CSFKEYS processing applies. KGUP uses key values on control statement creation.

For the format of the CSFKEYS record, refer to z/OS Cryptographic Services ICSF Administrator’s Guide.

The address of the CSFCKDS data set header record.

The exit can check the field at the KGUP pre- or postprocessing invocations. However, the exit can modify the field only at the KGUP postprocessing invocation. KGUP sets the value of the field to zero for the record pre- or postprocessing invocations.

The exit can modify the installation data field of the CKDS header record (see Debugging Aids for a description of the CKDS header record. Offset +196 of the CKDS header record is the installation data field). The installation data field supplied by the exit is placed in the CKDS header record after the KGUP postprocessing invocation returns control to KGUP.

The address of the CSFCKDS data set record processed by the KGUP control statement. KGUP sets the address to zero if the TRANSKEY keyword has two labels of transport keys.

The exit can check the field only at the record postprocessing invocation. KGUP sets the address to zero for the record preprocessing and KGUP pre- or postprocessing invocations.

The exit can modify the record area if the TRANSKEY keyword does not have two labels.

The address of the CSFCKDS data set record processed when the RENAME verb is used in a control statement. You can determine whether the RENAME verb was used by examining bit 3 at offset +14 in KGXP.

The exit can modify the field at the record postprocessing invocation. KGUP sets the address to zero for the record preprocessing and KGUP pre- or postprocessing invocations.

The exit can modify the record area. KGUP does not check this field upon return from the invocation. Normal CSFCKDS processing applies.

The address of the data specified on the INSTDATA keyword of the KGUP control statement. The address of the area is zero if a SET control statement has not been processed. The SET statement describes how to use the field in greater detail.

The address of an area set by the installation that is preserved across all invocations of the exit. The first byte of the area contains the length of the area (including the length byte). After KGUP completes, the first 64 bytes of the area are written to the SMF data set. The exit has exclusive control of modifying this area. The area is only used as input to SMF processing upon completion of KGUP.