MKEYED Verb - Create MKEYED File

Syntax

MKEYED fileid,keysize,records,recsize{,MODE=string}{,ERR=lineref}
MKEYED fileid,keydef{,keydef...},records,recsize{,MODE=string}{,ERR=lineref}

Description

See also XKEYED Verb - Create XKEYED File.

The MKEYED verb creates an MKEYED file that is similar to a DIRECT file but allows up to 16 keys composed of up to 48 key segments per record.

  • The first syntax example shows how to define an MKEYED file with only one key per record. This type of MKEYED file can be used in place of a DIRECT file without changes to application programs.

  • The second syntax example shows how to define an MKEYED 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. See the MKEYED Files section in the User's Reference Guide for additional information.

The total file size cannot exceed (2^31)-1 bytes.

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 120.

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 32767. An MKEYED file with a record length of zero has no data, only keys. With this configuration, an MKEYED file can be used as a sort file.

ERR=lineref

Branch to be taken if an error occurs during execution.

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.

Note:

PRO/5 supports the creation of encrypted MKEYED files, but does not support encryption of other file types.

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"

Not supported for MKEYED files. In BBj 12.0 and higher, creates a case insensitive key segment for XKEYED and VKEYED files. See XKEYED Verb - Create XKEYED File and Key/Index Case Sensitivity.

"N"

Only Available in BBj. 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 6 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.

MKEYED "MYFILE",[1:1:2],[2:1:10:"D"],0,80

NOTE: 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.

Four Gigabyte MKEYED Files

By default, the MKEYED verb only creates 2GB files. PRO/5 2.x has the capability to use 4GB MKEYED files on operating and file systems that can support 4GB files. See the PRO/5 readme.txt file to see if your system supports this feature. PRO/5 3.x and higher, on supported platforms, supports true 64-bit files that can grow past the 4GB limit of the previous versions and is limited only by physical disk space.

Four-gigabyte file types have a buffer zone to prevent file corruption that results from too much data being written to a file.

Creating a New 4GB MKEYED File (PRO/5 Rev. 2.x only)

Creating an MKEYED file with the SETOPTS Byte 7, Bit $80$ set automatically creates a 4GB file, provided that the operating system can support, and is configured to support, 4GB files.

Converting an MKEYED file from 2GB to 4GB (PRO/5 Rev. 2.x only)

The following issues pertain to converting a 2GB file to a 4GB file:

  • To prompt PRO/5 to convert an MKEYED file from 2GB to 4GB, include "MODE=4GB" in the OPEN statement. Performing this more than once slows down the OPEN process.

  • Using "MODE=4GB" in the OPEN statement on a file that is already 4GB-enabled will not cause PRO/5 to return an error, but will take much longer to open the file.

  • Attempting to OPEN a 4GB file on systems that do not support 4GB files will cause the OPEN and conversion process to fail. No changes will be made to the state of the MKEYED file.

Converting an MKEYED file from 4GB to 2GB (PRO/5 Rev. 2.x only)

A 4GB file that has exceeded 2GB in size cannot be converted to a 2GB file. To change the file back, OPEN the file and specify "MODE=2GB". If the file size is over 2GB, opening the file will result in a failure of the OPEN and no conversion will take place.

If a 4GB file ever exceeds 2GB, it cannot be converted back to 2GB using the "MODE=2GB" option. Deleting records to bring it under 2GB will not shrink the file. It is, however, possible to create a new 2GB file, then copy the existing data into it.

64-Bit MKEYED Files

In BBj and PRO/5 Rev. 3.x and higher, 64-bit MKEYED files can be created using SETOPTS 7 $80$. The mrebuild utility can be used to convert multi-keyed files from one format to another.

Currently, the only Windows operating systems to support 64-bit files are those based on NT (Windows 2000, XP, etc.). 64-bit MKEYED files are not supported on operating systems that are not NT-based, such as Windows 95, 98, or Me. Attempting to open or erase a 64-bit MKEYED file on operating systems that are not NT-based will cause an !ERROR=153 (file system does not support large files). However, access to these 64-bit files through the PRO/5 Data Server is fully supported.

Corruption Recovery Format MKEYED Files

MKEYED files can be created in or converted to a format that allows them to be easily recovered if they become corrupted. The mkconvert utility is a stand-alone executable that converts existing files. New files created with SETOPTS 7 $20$ automatically have this format.

The mrebuild utility is available in Revision 2.2 and later, and supercedes the mkconvert utility. The capabilities of mrebuild are tied to the capabilities of the revision of the PRO/5 or Visual PRO/5 client. For example, while the mrebuild utility that comes with PRO/5 or Visual PRO/5 Revision 2.x clients does not have the capability to create 64-bit files, the mrebuild utility that comes with PRO/5 or Visual PRO/5 Revision 3.x client does have this capability.

For each stored record in a corruption recovery format file, the new format adds a four-byte tag, key data for a single-keyed MKEYED file, and a four-byte checksum of the key and record data used to detect the actual data corruption of the record. This information enables the efficient recovery of record and key data, even if the data search tree is corrupt or missing.

The tag, key data, and checksum information cause the new format file to be larger than the original file. The size increase, however, is proportional to the number of records in the file.

Examples

Example 1

The following defines a simple MKEYED file with one key per record similar to a DIRECT file:

MKEYED "MYFILE",10,80,1000

Example 2

The following defines an MKEYED file with two keys of one segment each. The brackets indicate where in the record the key can be found.

MKEYED "MYFILE",[1:4:2],[2:1:10],80,1000

Example 3

The following defines an MKEYED file with three keys, one of which is composed of two segments. The "+" used between bracket expressions indicates a composite key. The program sets the SETOPTS byte 7, bits $80$ and $20$ in order to force the file to be created as a 64-bit highly recoverable file.

1000 LET A$=OPTS
1010 LET A$(7,1)=IOR(A$(7,1),$A0$)
1020 SETOPTS A$
1030 MKEYED "MYFILE",[1:1:10]+[2:1:5],[1:25:2:"D"],[4:12:20],80,1000
1040 LET CHAN=UNT
1050 OPEN(CHAN) "MYFILE"
1060 A$=FID(CHAN)
1070 IF A$(1,1) = $66$ THEN PRINT "File is a 64-bit Highly Recoverable MKEYED File"

Example 4

The following creates an encrypted MKEYED file with one 10-bytekey per 500-byte record.

MKEYED "myfile",10,0,500,MODE="CRYPTPASS=test"

Example5

The following creates anAES-256 bitencrypted MKEYED file with one 10-bytekey per 500-byte record.

MKEYED "myfile",10,0,500,MODE="CRYPTALG=AES-256,CRYPTPASS=use at least 40 characters"

Example6 - Only Supported in BBj

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$

See Also

Data Server Syntax

Verbs - Alphabetical Listing

MKEYED Files