| Note: | You can use this parameter on the CPYF command only. |
You can specify record keys to copy only from a keyed database file. You can copy records:
If the command reaches the end of the file before it reaches the specified ending key value or number of records, the copy completes normally.
If no record in the from-file member has a key that is a match with the FROMKEY value, but there is at least one record with a key greater than the specified value, the first record copied is the first record with a key greater than the FROMKEY value. If the specified key value is greater than any record in the member, the command sends an error message and does not copy the member.
You can specify *BLDKEY on the FROMKEY and TOKEY parameters to use a list of character and numeric values in their natural display form for the fields in a key. The command converts each element to the corresponding key field data type. The command then provides the composite key value (a key that is comprised of more than one field) to the database.
If you specify fewer values than the complete database key contains, the command builds a partial key and passes it to the database. If you specify more values than the database key contains, an ending error occurs. The command always applies values to the consecutive fields that are in the extreme left of the key so that it is impossible to skip key fields.
The command pads character fields on the right with blanks. The command adjusts numeric fields to the implied decimal point in the key field with the correct zero padding.
All regular rules for specifying numeric fields in an external character format apply. The command does not allow a floating-point value of *NAN (Not a Number).
See Example: build-key function and Example: using FROMKEY and TOKEY for specific coding examples.
It is also important to understand Key string comparisons made by the copy operation in order to interpret various warning messages.
| Note: | If you use record keys to select records, you cannot use relative record numbers (FROMRCD/TORCD parameters) to select records on the same CPYF command. |
You should not specify COMPRESS(*NO) when selecting records by record key from a keyed physical file. Because the keyed access path of a file does not contain deleted records, the copy command never copies them, so the compression is automatic.
Because deleted records are canceled in a copy by this method, it is also possible that the relative record numbers have changed in the new file, even if you have specified MBROPT(*REPLACE).
See the following topics for more information about specifying data for:
The check made by the copy operation (when the TOKEY value is specified) is a logical character comparison between the key string for each record retrieved and the key string that is:
A warning message is sent (but the copy operation continues) if this comparison gives different results than the ordering in which the database identifies the records in the keyed access path. The order may be different if:
If there are both ascending and descending fields in the file key, the first (the far left) key field determines whether the copy operation uses an ascending or descending key test to look for the last record to copy.
Using *BLDKEY is the easiest way to specify (and ensure correct padding) values for packed, binary, and floating-point fields.
An example of the build-key function is:
| Key Field Number | Type | Length | Decimal Precision | Value |
|---|---|---|---|---|
| 1 | CHAR | 6 |
| KEN |
| 2 | ZONED | 6 | 2 | 54.25 |
| 3 | BINARY | 4 | 1 | 10.1 |
You could specify the FROMKEY (or TOKEY) parameter as follows:
FROMKEY( 2 x'D2C5D5404040F0F0F5F4F2F50065')
Or, you could use the *BLDKEY value and specify the FROMKEY as follows:
FROMKEY(*BLDKEY (KEN 54.25 10.1))
Another example using key fields 1 and 2 is:
FROMKEY(2 'KEN 005425')
Or, you can specify the *BLDKEY value:
FROMKEY(*BLDKEY (KEN 54.25))
In this example, the copy command copies records in the file EMP1 to the file EMP1T. EMP1T is a file in a test library. Because you only need a subset of the records, you specify a from-key value and a to-key value. Both are full key values. Note that a 1 specified in the FROMKEY and TOKEY parameters indicates the number of key fields to be used in searching the record keys, starting with the first key field.
CPYF FROMFILE(PERSONNEL/EMP1) + TOFILE(TESTLIB1/EMP1T) MBROPT(*REPLACE) + FROMKEY(1 438872) TOKEY(1 810199)
All positions in a key value should be specified. If the value is shorter than the key field length, it will be padded on the right with zeros. Thus, a 5-position key field specified as FROMKEY(1 8) causes a search for a key equal to hex F800000000. If the key value contains blanks or special characters, you must enclose them in apostrophes.
When the number of key fields and a value are used to specify the FROMKEY or TOKEY parameter, the string should include the 2-byte length field for each variable-length key field. You must pad the variable-length key field with blanks so that keys following the variable-length key field are in the correct position. You can specify the data in hexadecimal format.
When you specify *BLDKEY on the FROMKEY or TOKEY parameter for variable-length key fields, specify the character string without the 2-byte length field. Only the amount of data that is entered for the key value is used for key comparisons. You can specify a zero-length string for variable-length key fields.
When the number of key fields and a value are used to specify the FROMKEY or TOKEY parameter, no conversion of data occurs if the corresponding key field in the from-file is a date, time, or timestamp field. The user input string that you specify (including the separators) must be in the same format as the date, time, or timestamp field. If it is not, a file open error may occur, or the records copied may not be the desired result.
If *BLDKEY is specified for the FROMKEY or TOKEY parameter and the corresponding key field in the from-file is a date, time, or timestamp field, the system attempts to convert the user-input key field value to the format (and separators) of the from-file field. The following rules apply to the conversion:
When you use the number of key fields and a value to specify the FROMKEY or TOKEY parameter, the copy command ignores the null values. The command uses only the buffer default values for values that are actually null for the comparison.
When you specify *BLDKEY on the FROMKEY or TOKEY parameter, none of the *BLDKEY values can refer to a null-capable field. If they do, the system sends an error message.
When you use the number of key fields and a value to specify the FROMKEY or TOKEY parameter, the copy command does not make any CCSID conversions to the input string.
When *BLDKEY is specified on the FROMKEY or TOKEY for character, DBCS-open, DBCS-either, or DBCS-only fields, the value specified is assumed to be in the CCSID of the process in which the copy command is running. The copy command converts each of these key values from the job CCSID to the CCSID of the from-file key field. If no conversion table is defined or an error occurs while converting the input key value, a message is sent and the copy operation ends. If the value can be correctly converted, the converted value is used to build the key value that determines the first and last record to be copied.
When the number of key fields and a value are used to specify the FROMKEY or TOKEY parameter, no conversions are done on the input string. The input string is used as is.
When you specify *BLDKEY on the FROMKEY or TOKEY for DBCS-graphic fields, you should enclose the DBCS data in shift-out and shift-in characters. The copy command assumes that the DBCS data is in the associated DBCS CCSID of the job CCSID. The shift-out and shift-in characters are removed before building the key. A message is sent and the copy operation ends: