HP 3000 Manuals

Getting Started as an MPE/iX Programmer Programmer's Guide

KSAM/V 

KSAM is an acronym for Keyed Sequential Access Method.  KSAM/V provides a
disc file structure for organizing and accessing records in a file
according to the contents of key fields.  It is Hewlett-Packard's
implementation of indexed sequential processing.  KSAM/V allows you to
access records in two ways:

   *   Sequentially, according to a sequence defined by key values.

   *   Randomly, by finding the record that has a field matching a
       specific key value.

A KSAM file consists of two associated MPE/iX files:

   *   A data file containing all of the file's data records

   *   A key file, containing one or more balanced trees that maintain
       primary and alternate logical sequences for the data records.

The data file contains the actual data.  It can consist of fixed-length
or variable-length records.  Each record in the data file contains one
primary key field and may have a maximum of 15 alternate key fields.
Data records are stored in a KSAM file in chronological order (this is
the order in which they were written to the file), without regard to key
sequence.  In KSAM mode, you can specify standard access if you wish.  In
addition to KSAM mode, you can specify standard (NOKSAM) mode.

The associated key file must be used to access the data records.

KSAM procedures add, delete, read, and update KSAM records and are
callable from user applications.

KSAMUTIL allows you to manipulate, verify, and analyze KSAM files.
Because KSAM file structure is different from MPE/iX file structure, you
cannot create a KSAM file with the MPE/iX command :BUILD. You can rename
it with the MPE/iX command :RENAME, but it is inadvisable because it
destroys the cross reference between the data file and the associated key
file.  Therefore, it is extremely useful to have KSAMUTIL commands that
are designed to operate specifically on KSAM files and preserve the
proper cross referencing.

Figure 7-1  shows an example of building a KSAM file.


          Figure 7-1.  Building a KSAM File 

The KSAMUTIL command BUILD requires the following parameters:

   *   Data file name.

   *   Key file name.

   *   One or more key types, with corresponding key location, and key
       size.

The first key specified becomes the primary key.  Each subsequent key
specified becomes an alternate key.  Notice in the example that the first
alternate key allows records to have duplicate values in that field.  The
fourth subparameter of the KEY field is the key blocking factor.  Default
blocking is one record per block, which usually results in wasted disc
space.  You can find the blocking factor by dividing the sector size
(256) by the record length and then rounding down.

FCOPY (KSAM Options) 

You can use FCOPY with KSAM options that make it perform correctly for a
KSAM file instead of an MPE/iX file.  FCOPY provides many file
manipulation services.  For example, you can use it to:

   *   Load a KSAM file by copying data from an MPE/iX or a KSAM file
       into a KSAM file.

   *   Reorganize a KSAM file by building another KSAM file with keys
       specified in a different order and copying the old KSAM file into
       the newly built one.

   *   Convert an ISAM (Indexed Sequential Access Method) file to a KSAM
       file by building a KSAM file and copying the magnetic tape
       containing the ISAM file data to the newly built KSAM file.

   *   Copy only active KSAM records (data records that are not logically
       deleted by having a flag in the first word).  This feature allows
       you to physically delete KSAM records from a file and compact the
       file size.  FCOPY defaults to copying only active records unless
       you specify otherwise.

   *   Recover logically deleted records by using the :NOKSAM option.

   *   Write logically deleted records to a separate file by using the
       :NOKSAM option and specifying ;SUBSET=#%377,%377#,1.

   *   Write any KSAM file to $STDLIST or a line printer.  Thus, during a
       session, you can either display the file on the terminal or list
       it out on a line printer.  During a job, you can list it on a line
       printer.

   *   Copy data in a KSAM file to an MPE/iX file in chronological,
       primary, or alternate key sequence.

   *   Recover corrupt key files or files with missing key files.

   *   Recover anomalies resulting from system interrupts by specifying
       ;KEY=0.

The FCOPY utility has three KSAM options:

   *   ;KEY=nn

              - if omitted, copies in primary key sequence, retaining old
              key trees.

              - if nn=0, copies in chronological sequence and rebuilds
              key trees.

              - if nn>0, copies in sequence by key number nn, where the
              key numbers are assigned in order of occurrence.

   *   ;NOKSAM

              - copies all records in chronological sequence, including
              deleted records.

              - if omitted, only active records are copied.

   *   FCOPY default, which copies active records in the primary key
       sequence

When using the KSAM options of FCOPY, consider the following information:

   *   KEY and NOKSAM are mutually exclusive options; use them only when
       the FROM file is a KSAM file.

   *   NOKSAM processes the FROM file as an MPE/iX file.  Use it to copy
       all data in a KSAM data file, including the logically deleted
       records.

   *   Do not use the NOKSAM option to copy a KSAM file with
       variable-length records.

   *   If you use the NOKSAM option to reload a file due to keyfile
       corruption, you must also specify NOUSERLABELS. Using the SUBSET
       option ensures that only valid (non-deleted) records are copied.

   *   When copying an existing KSAM file, you can let FCOPY create a TO
       file for you by using the syntax:

              >FROM=KSAMDATA;TO=(NDATA,NKEY)

              where NDATA and NKEY are previously non-existent KSAM data
              and key fields.

Figure 7-2  shows an example of loading a KSAM file.  The diagram
shows how the key file is built on KSAM file information specified in the
KSAMUTIL command BUILD.


          Figure 7-2.  Loading a KSAM File 

The steps required to reorganize a KSAM file are:

   1.  Use KSAMUTIL to build a new KSAM file with new key fields.

   2.  Use FCOPY to copy the old KSAM file to the new one, specifying
       whichever key in the old file is the primary key in the new file.

   3.  Use KSAMUTIL to purge the old file and rename the new copy to the
       old file name.

Figure 7-3  shows an example of reorganizing a KSAM file.


          Figure 7-3.  Reorganizing a KSAM File 

KSAM procedures 

KSAM procedures allow you to programmatically add, delete, read, and
update KSAM files.  The procedures vary depending on the language in
which the program is written.  You can access KSAM files through KSAM
procedures in the native languages that run on the 900 Series HP 3000:

   *   HP C/iX

   *   COBOL II/XL

   *   HP FORTRAN 77/iX, through calls to intrinsics (for example,
       HPFOPEN and FOPEN).

   *   HP Pascal/iX, through calls to intrinsics (for example, HPFOPEN
       and FOPEN).

For detailed information on using KSAM procedures in HP C/iX, HP
Pascal/iX, HP COBOL II/XL, and HP FORTRAN 77/iX, refer to KSAM/V 
Reference Manual (30000-90079).

MPE/iX 5.0 Documentation