XKEYED Verb - Create XKEYED File
Syntax
XKEYED fileid,keysize,records,recsize{,ERR=lineref}
XKEYED fileid,keydef{,keydef...},records,recsize{,ERR=lineref}
Description
The XKEYED verb creates a keyed file that is similar to a DIRECT file but allows an unlimited number of keys composed of an unlimited number of key segments.
-
The first syntax example shows how to define an XKEYED file with only one key per record. This type of XKEYED file can be used in place of a DIRECT file without changes to application programs.
-
The second syntax example shows how to define an XKEYED file with more than one key per record. In this case, each key must be present within the data record. The bracketed expressions indicate the locations of keys within the record. Bracketed expressions separated by plus (+) signs indicate a composite key made up from several parts of the record.
-
Note: Record size depends on memory allocated to the JVM. File size depends on available disk space and the JVM.
-
See also MKEYED Verb - Create MKEYED File, VKEYED Verb - Create VKEYED File, BBjFileSystem::recoverFile
|
Parameter |
Description |
|
fileid |
Name of the new file. Must be unique. |
|
keysize |
Maximum length of a key in the file and must be an integer in the range of 1 to (2^31) -1. |
|
keydef |
Key definition. Each keydef has the following syntax: segment{+ segment...} Each segment has the following syntax: [{ field:} offset:len{ :flags}] |
|
records |
Maximum number of records for the file. Must be an integer. If records is 0, the number of records in the file is dynamically allocated. Total file size may increase as new keys are added, regardless of the number of keys previously written. |
|
recsize |
Size of each record in bytes. This value must be an integer in the range 0 to (2^31) -1. An XKEYED file with a record length of zero has no data, only keys. With this configuration, an XKEYED file can be used as a sort file. |
|
ERR=lineref |
Branch to be taken if an error occurs during execution. |
Sort Operation Flags
The following flags are available to control sorting operations. A flag may be used on any segment of a composite key.
|
Flag |
Description |
|
"B" |
Sorts a key segment numerically, provided the segment is exactly 8 bytes long and contains a business floating point quantity (string template data type "B"). |
|
"D" |
Sorts the key segment in descending order, and only the segment flagged is affected. To sort the entire key in descending order, each segment must be flagged. |
|
"I" |
In 12.0 and higher, creates a key segment which is case insensitive when using lookup operations such as READ RECORD specifying a KEY= option. This makes it possible to store records with mixed case values, but have the ability to lookup those records by key, irrespective of case. Only use this flag on pure character data as binary or numeric data will cause undefined results. See Example 5 below and Key/Index Case Sensitivity. |
|
"N" |
Sorts a key segment numerically, provided the segment is of type numeric as recognized by the template. NOTE: Reading records by specifying a KEY= option, require first encoding the numeric value in the correct format using a string template defined with a field of type "K" before passing it into the READ RECORD call. See Example 4 below. |
|
"U" |
Issues an !ERROR=11 when a duplicate key is detected on a WRITE. Determine the key chain and key that is duplicated. If this flag is not used, alternate keys can be duplicated, but the order is unspecified. Unlike the "D" flag, the "U" flag affects the entire key chain. |
The primary key will accept the "D" flag, but the "U" flag is there by default and cannot be reset.
XKEYED "MYFILE",[1:1:2],[2:1:10:"D"],0,80
When using flags on composite key segments, especially segments other than the first segment, set up a test file to verify that the order you desire is in fact the order you are getting.
MODE Options
Mode |
Description |
|
CRYPTPASS= |
In PRO/5 5.0 and higher, and BBj 4.0 and higher, creates an encrypted file with the specified password. BASIS recommends a password of at least 20 characters when using AES-128 and at least 40 characters when using AES-256. Note: Encrypted files tend to perform slower than non-encrypted files due to the overhead of encrypting and decrypting each time the file is accessed. |
Mode |
Value |
Description |
|
CRYPTALG= |
AES-128 AES-256 |
Uses AES-128 bit encryption, which is also the default. In BBj 6.0 and higher, and PRO/5 6.0 and higher, uses AES-256 bit encryption. |
To utilize AES-256 in BBj, the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files must be installed. These files are available for download at Oracle's Java SE Downloads page under "Additional Resources" near the bottom of the page.
Example 1
The following defines a simple XKEYED file with one key per record similar to a DIRECT file:
XKEYED "MYFILE",10,80,1000
Example 2
The following defines an XKEYED file with two keys of one segment each. The brackets indicate where in the record the key can be found.
XKEYED "MYFILE",[1:4:2],[2:1:10],80,1000
Example 3
The following defines an XKEYED file with three keys, one of which is composed of two segments. The "+" used between bracket expressions indicates a composite key.
XKEYED "MYFILE",[1:1:10]+[2:1:5],[1:25:2:"D"],[4:12:20],80,1000
Example 4
The following example shows how to encode a numeric value into the appropriate binary format to do a key lookup on a key defined with a sort flag of "N" (ordered numeric):
MKEYED "MYFILE",[1:6],[7:10:"N"],0,16
DIM rec$:"ID:C(6),NUM_COL:N(10)"
rec.ID$ = "000001"
rec.NUM_COL = 525.95
OPEN(1) "MYFILE"
WRITE RECORD(1) rec$
DIM key$:"NUM_COL:K(10)"
key.NUM_COL = 525.95
READ RECORD(1, KNUM=1, KEY=key$) rec$
Example 5
The following example shows creating a new XKEYED file with a case insensitive key. Note that line 30 shows the value is a mixed case value "AbCdEf" while line 60 reads that record successfully by using all lowercase characters "abcdef".
10
XKEYED "MYFILE",[1:6:"I"],0,6
20 DIM rec$:"ID:C(6)"
30 rec.ID$ = "AbCdEf"
40 OPEN(1) "MYFILE"
50 WRITE RECORD(1) rec$
60 READ RECORD(1, KNUM=0, KEY="abcdef") rec$