Data Files

This is the most common file format used in PxPlus. It contains at least one unique (primary key) field that identifies each record on the file. PxPlus supports internally and externally defined keys with record sizes up to 2GB. A wide variety of key segment options is available.

Keyed files support fixed length records (FLR), variable length records (VLR), and the PxPlus enhanced file format (EFF). Up to 16 keys and 96 segments are supported for FLR and VLR based files, and EFF is up to 255 keys and 255 segments per key.

For information on EFF files, see Enhanced File Format. For an explanation of EFF vs. VLR file formats, see EFF vs. VLR File Formats.

Three types of Keyed files can be created:

All PxPlus I/O directives work with keyed files. See Processing Data Files.

The READ directive without a KEY= option reads the record with the next higher key. When reading a file with an external key, it is normal to first retrieve the key of the next record.

Example:

k$=KEY(1,end=done)
READ (1,key=k$)

The WRITE directive without a KEY= option is invalid unless the record was previously extracted or has an imbedded key. See Multi-Keyed Files.

The REMOVE directive deletes the record whose key matches the key specified. When the record is deleted, its associated disk space is returned for reuse within the file.

Accessing or attempting to access a record whose key does not exist positions the file pointer to the next higher existing key. The only exception is when using the FIND directive. This directive is a variation of the READ verb that does not update the current file pointer if the key is not found.

Example:

This assumes that the file ACTNME has a key of name with a data field of account number.

0010 OPEN (2) "ACTNME" ! Assign ACTNME to file 2
0020 INPUT "Enter name:",NM$
0030 IF NM$="" THEN END
0040 K$=NM$
0050 READ (2,KEY=K$,DOM=0070) A_NUM$ ! Read record info
0060 PRINT A_NUM$, " ", K$
0070 K$=KEY(2,END=0020) ! Get next higher key
0080 IF K$<=NM$+$FF$ THEN GOTO 0050
0090 CLOSE (2)

Direct Files

A direct file is a keyed file with an external key. The key size must be specified along with the file name. The DIRECT directive is used to create a direct file:

DIRECT filename$, max_len [, max_recs [, rec_size ]]

Where:

Example:

DIRECT "CSTFLE",6

Sort Files

The sort file is a type of keyed file that consists of a key only with no data record portion. Key size must be specified, along with the file name. The SORT directive is used to create a sort file:

SORT filename$, max_keysize [, max_rec ]

Where:

Example:

SORT "CSTFLE",6

Multi-Keyed Files

The KEYED directive can create a file with one or more keys. The primary key may be external or internal. If the first field after the file name is a number, an external file key is created; if it contains a key definition (enclosed within [ ] ), then only internal key fields may be used.

The first key specified is considered the primary key. Every record must have a unique primary key. You can have duplicate secondary keys from record to record.

A multi-keyed file is a keyed file with one primary record key and up to 15/255 secondary keys. The primary key must be unique within the file, while the secondary keys may be duplicated between records; e.g. where two JONES may exist. Multi-keyed files are defined like any keyed file except that the key definition contains a series of comma-separated key declarations. The first key declaration is for the primary key; the remaining declarations are for secondary keys.

The KEYED directive is used to create a file with one or more keys:

KEYED filename$,[,extkey_len][,key_def$][,max_recs[,rec_size]][,fileopt]

Where:

Key Definitions

The key_definitions parameter contains one or more key declarations, each comma separated. The first key declaration is for the primary key; the remaining declarations are for the secondary keys. If an external key field is to be created, it must be a primary key and its length given as the first key declaration.

Keys that exist with the data portion of the record are defined by a key declaration in the following format:

[{"keyname":}field_no:offset:length{:"options"}]

Where:

If desired, multiple key descriptors can be specified for a single key. This will generate a composite key. The data fields will be concatenated together to form a complete key. When defining a composite key, the individual key descriptors are to be separated by a (+) plus sign.

Example:

Given customer file with an external key as follows:

The following KEYED directive would be used to create the above file with CUSTNO as the primary key, a secondary key of NAME and a composite secondary key of TYPE and CUSTNO:

KEYED "CUSTDB",5,[1:1:20],[3:1:1]+[KEY:1:5],,200

This directive would create the file "CUSTDB" with a five-character external key (CUSTNO), a 20-character secondary key of the first 20 characters of field 1 (NAME), and a six-character secondary key of the TYPE (1 ch), followed by the primary key. The record size would be 200 bytes each with no limit to the number of records.

Note:
If, when generating a key, the descriptor references data outside the data field (either by an offset outside of field specified or a length which exceeds the field length) and the descriptor is other than the last descriptor within a composite key, the key is padded with Hex $00$ in order to achieve the length specified.

There is a limit of 96 total data fields allowable in a file for use within keys (on FLR/VLR files). This means that the total number of data fields that can be used to define keys must be no more than 96 with the maximum number of keys being 1 primary and 15 secondary. If, for example, one key consists of 20 data fields, the maximum number of additional fields would now be limited to 76 for a total of 15 keys, 96 data fields.

If no external key is desired on the file, only key descriptors would be specified with the first key descriptor being considered the primary key.

Using the Secondary Keys

For the purposes of accessing multi-keyed data files, each key is assigned a key number. The primary key is assigned the key number of zero (0), the first secondary key is assigned one (1), and so on. When reading a multi-keyed file, the system performs the read based on the current key number being used. The key number is specified by the KNO= option in the WRITE, FIND, EXTRACT directives or any of the key functions; i.e. KEC( ), KEF( ), KEL( ), KEN( ), KEP( ), KEY( ). Once KNO= is specified, it remains the current key number until changed by a subsequent KNO= option. When a file is initially opened, the key number is set to zero (primary key).

All file input directives function basically the same on multi-keyed files as they do on normal single-keyed files. One exception is the READ (n,KEY=xxx) directive on secondary keys. This directive will read the first record that contains the desired key. Specifying a KEY= on an alternate key that contains duplicates will result in what appears to be an endless loop; i.e., the read will continue to re-position the key pointer to the first of the duplicates. Therefore, do not use the KEY= option in this case.

Updating Multi-Keyed Files

Adding or updating records on a multi-keyed file uses the same WRITE directive as does a single-keyed file. The record to be changed or added is determined by the primary key. If the file contains an external primary key, the KEY= option must be specified in the WRITE statement. If the file does not contain an external key, then the key will be determined by the data fields presented in the WRITE statement.

Note:
If a KEY= option is specified in a WRITE directive and no external key exists, or conversely, if no KEY= option is specified and an external key does exist, an Error #80: Invalid key definition, number or name is generated.

The REMOVE statement is used to delete a record from a multi-keyed file. The KEY= option is recommended on the REMOVE directive. The key specified must be the primary key of the record to be removed, regardless of whether the key is external or not. If the KEY= option is not specified, then the last record read or extracted will be removed.

Multi-Keyed Memory Files

Memory files (*memory*) can now have alternate keys specified. When opening a memory file, you can add a KEYDEF= option that defines the alternate key definition. Standard PxPlus alternate key definitions can be used.

Example:

The following will create a memory file with a six-character external key and two alternate keys based on fields 2 and 3 of the data:

OPEN (1) "*memory*;KEYDEF=6,[2:1:6:""U""],[3:1:30]"

If desired, the key definition for a memory file can include Key names.

Note:
Unlike standard *MEMORY* files, *MEMORY* files created with key definitions cannot have record inserted by record index. The key fields are always used.