At each of the invocation points, the exit receives the address of the KGUP exit parameter block (KGXP) in register 1. The exit does not receive a parameter list. Entry and return specifications gives a complete list of the registers on entry to the KGUP exit.
The KGUP exit can alter some of the fields in KGXP. Some fields only provide information to the exit and cannot be changed, and some fields do not apply to particular calls to the exit.
Table 1 describes the KGXP control block.
Offset (Dec) | Number of Bytes | Description |
---|---|---|
0 | 4 | Block Identifier. 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. |
4 | 2 | Block Version Number. 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. |
6 | 2 | Block Length. 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. |
8 | 4 | Return Code. 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.
KGUP pre- or postprocessing.
|
12 | 1 | Call Point. 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.
|
13 | 1 | Options. 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.
|
14 | 1 | Verb Type. 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.
|
15 | 1 | KGUP Flags. 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.
|
16 | 72 | Action Key. 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 exit cannot modify the key label, key old label, or key type. |
88 | 72 | Rename Key. 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 exit cannot modify the key new label or the key type. |
160 | 72 | Transkey key-label1. 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 exit cannot modify the key-label1 or the key type. |
232 | 72 | Transkey key-label2. 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 exit cannot modify the key-label2 or the key type. |
304 | 8 | The OUTTYPE value, if specified. If no OUTTYPE is specified, this field set to binary zeros. |
312 | 4 | Key length in bytes. 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. |
316 | 16 | Key key-value 1. 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. |
332 | 16 | Key key-value 2. 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. |
348 | 16 | Key key-value 3. 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. |
364 | 16 | Key key-value 4. 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. |
380 | 4 | CSFKEYS record for transkey, key-label1.
The address of the CSFKEYS data set record that is output for transkey key-label1 on the KGUP control statement. This field only contains a value 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. |
384 | 4 | CSFKEYS record for transkey, key-label2. The address of the CSFKEYS data set record that is output for transkey key-label2 on the KGUP control statement. This field only contains a value when TRANSKEY key-label2 is specified for generated keys. 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. |
388 | 4 | CSFCKDS header record. 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. |
392 | 4 | CSFCKDS record. 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. |
396 | 4 | RENAME CSFCKDS record. 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. |
400 | 4 | Installation data. 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. |
404 | 4 | Installation exit area. 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. |