HOW TO USE KSAM FILES

Although a KSAM file consists physically of two separate files, a data and a key file, it is treated as one file for most purposes. For example, reading from a KSAM file in primary key sequence is equivalent to reading sequentially from a non-KSAM file. Similarly, creating the data file portion of a KSAM file is equivalent to creating a non-KSAM file.

CREATING A KSAM FILE

A KSAM file can be created in two ways: interactively with the > BUILD command of the utility program KSAMUTIL, or programmatically with a call to the MPE file system intrinsic FOPEN. (A COBOL or BASIC programmer can create a KSAM file only through the > BUILD command, not FOPEN.) Whether > BUILD or FOPEN is used, file creation consists of creating a data file in very much the same way you would create any HP 3000 file. The name assigned to the data file is the name by which the KSAM file is known. Then, as part of the file creation procedure, a key file is created and each of its keys defined by type, location in the data record, and size. If duplicate key values are to be allowed, this is specified as part of the key definition.

WRITING RECORDS TO A KSAM FILE

You can write records to a KSAM file in either of two ways. In one, records are written in any order regardless of primary key values. In the other, records are written in order according to the value of the primary key in each record. In the first case, the chronological sequence in which records are written differs from the logical record sequence determined by primary key. In the second, the chronological and logical record sequence is the same. When you specify that records are to be written in primary key sequence, KSAM checks to make sure that this sequence is followed and issues an error message if not.

You can specify that the file be cleared of any existing records before writing new records to the file, or you can write records following any previously written records. The choice is made when you open the file.

In any case, when records are written to the data file, the key file structure is modified automatically in order to place all keys in the new record into their proper sequence.

Records cannot be written directly to a KSAM file according to a relative record number.

RETRIEVING RECORDS FROM A KSAM FILE

Records can be retrieved in a variety of ways:

Sequentially in the order determined by key value; either the primary or an alternate key can be selected to determine the order.
At random according to the value of a specified key; either the primary or an alternate key can be selected for the matching process.
Chronologically in the order the data records were written.^[1]
At random by chronological record number.^[1]

^[1]

Whenever duplicate keys are used and retrieval is by key value, the first key encountered determines the record read. When generic keys are used, the smallest key value is selected first. Again, if there are duplicates in generic key values, the first key encountered is selected.

UPDATING RECORDS IN A KSAM FILE

You can change the contents of an existing record by program calls that read the record into storage where you update it and then write it back to the file. The updated record overwrites the existing record in its current location if the new record and the old record are the same length. Otherwise, the new record is written to the end of the file and the old record is marked for deletion.

POSITIONING IN A KSAM FILE

Record pointers can be positioned:

To a record determined by key value using either the primary or an alternate key.
To a record determined by its record number relative to the first record in key sequence, where the key is either primary or an alternate.^[2]
To a record determined by its record number relative to the first record written to the file (chronological sequence).^[2]

^[2]

DELETING RECORDS FROM A KSAM FILE

Records are not physically deleted from the data file. In order to delete a record, you call a procedure that marks the record for deletion by writing a delete code (octal 177777) in the first word of the record. Any subsequent access to the file skips such records, treating them as if they were not there. In addition, the key file is automatically reorganized so that keys in the deleted record are no longer in the path that defines the key sequence. The space in the key file created by the deleted entries is reused. However, to maintain the file's chronological order, the space occupied by deleted entries in the data file is not reused.

Because data records are not physically deleted, you can reconstruct deleted records by copying the data file using FCOPY with the NOKSAM and SUBSET options. In this way, you can restore files in which you deleted, records by mistake.

To prevent records from being deleted by mistake, do not place binary or numeric data that could result in octal 177777 (the deletion code) in the first word of a data record. The best practice is to always keep the first word of each data record blank. Doing so helps you identify deleted records and prevents KSAM from writing delete codes over recoverable data.

REORGANIZING A KSAM FILE

If many records have been deleted, thereby using a great deal of physical space in the file, you can compact the file by using FCOPY/3000 to copy only the active records, those not tagged for deletion, to a new KSAM file. You can also use FCOPY to delete, add, or change alternate keys by copying the file to a new KSANI file with a different key definition. When the key definition is different, you must first create the new file with the >BUILD command of KSAMUTIL.

SHARED ACCESS TO KSAM FILES

Several programs can access the same KSAM file simultaneously. Shared access is assumed when the file is only being read, exclusive access is assumed when the file is being written to or updated. Thus, you can choose to make all your access shared or all exclusive. Note that shared access uses more memory than exclusive access since each open KSAM file requires a separate extra data segment.

When access to the file is shared, it is each user's responsibility to dynamically lock the file before changing it in any way. The file must be locked before any records in the file are written, updated, or deleted, and then unlocked immediately after such action. By requiring this action, the system makes sure that the most recent values are brought into each user's buffer at each access. Any call to read or position to a record for sake of subsequent access should be within the locked portion of code that includes the actual update call.

(Refer to appendix E for a full discussion of shared access.)

RECOVERY AND ANALYSIS OF KSAM FILES

The utility program KSAMUTIL provides several commands that can be used to analyze KSAM files. These commands allow you to check any key sequence to obtain a formatted dump of the key file, and in the event of a system failure, to check key file structural damage, determine whether key values are missing, and recover key values and data records by resetting end-of-file pointers. The command, KEYINFO, that performs these recovery functions must be run in case of a system failure while a KSAM file is open. (A full discussion of these commands is found in section II; also refer to appendix E for a discussion of KSAM file recovery in the event of system failure.)

USING FILE EQUATIONS WITH KSAM FILES

KSAM opens the key and data file allowing file equations for both. KSAM accesses the files in a very specific way. Since file equations will override any aoptions that KSAM uses, it is possible to specify access parameters on the file equation which will cause unpredictable results. The following should not be used on a file equation which references a KSAM file:

 

   BUF=numbers of buffers 

   NOMR 

   WAIT

Refer to "Dynamic Locking" and "Exclusive Access" in Table 4-7 “FOPEN aoptions Parameter Format”, and the section on using FCOPY to add data to an existing file for further information.

^[1]*The starred access methods are not available to a COBOL or BASIC programmer.

^[2]**Not available in COBOL or BASIC program.