HP 3000 Manuals HP 3000 Manuals
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.*
* At random by chronological record number.*
*The starred access methods are not available to a COBOL or BASIC
programmer.
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.**
* To a record determined by its record number relative to the first
record written to the file (chronological sequence).**
**Not available in COBOL or BASIC program.
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 iii 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, and the
section on using FCOPY to add data to an existing file for further
information.