HOW TO USE THIS MANUAL

There are some differences in the way in which KSAM files can be accessed depending on the language in which you are programming. You should read the paragraphs below appropriate to your programming language and then turn to the last paragraph of this section, For All Programmers.

RPG PROGRAMMER

This manual does not describe the code required to access a KSAM file using RPG. For this information, you must refer to:

   RPG/3000 Compiler Applications & Reference Manual

COBOL II PROGRAMMER

If you are programming in COBOL II, you can access KSAM files through COBOL II's Indexed I/O Module. To do so you declare a file's organization to be INDEXED. Refer to the COBOL II Reference Manual (32233-90001) for documentation of this procedure.

You can optionally access KSAM files using MPE Intrinsics (Section IV) and COBOL procedures (Section III).It is recommended that you use COBOL procedures only when compatibility with COBOL is required.

COBOL PROGRAMMER

If you are programming in COBOL, you should read section II in order to learn how to:

Create, purge, rename, clear the contents, display the status of, or save a KSAM file. These functions are provided by the KSAMUTIL program.
Copy a KSAM file to another KSAM file in any key order.
Display the contents of a KSAM file in any key order on the standard list device. These functions are provided by the FCOPY program.

You should read section III in order to learn how to:

Open and close the KSAM file.
Open the file for shared access and dynamic locking.
Write the records to the file in sequential key order or in random order.
Read records from the file in sequential order by key value or at random by key value.
Change the key in preparation for a sequential read.
Rewrite or delete an existing record.
Dynamically lock or unlock the file.

Note the following limitations for COBOL:

You cannot programmatically create a KSAM file. You must use the >BUILD command of the KSAMUTIL utility program in order to create the file.
You cannot read a KSAM file in chronological sequence. You can, however, use FCOPY to copy the file to a non-KSAM file and then read it in chronological sequence.
For ANSII standard COBOL, only alternate keys, not primary keys, can be duplicated.

SPL PROGRAMMER

If you are programming in SPL, you should read section II in order to learn how to:

Create, purge, rename, clear the contents, display the status of, or save a KSAM file. These functions are provided by KSAMUTIL.
Copy a KSAM file to another KSAM file in any key order.
Display the contents of a KSAM file in any key order on the standard list device. These functions are provided by FCOPY.

You may skip sections III, V, and VI, which apply to programming in COBOL, FORTRAN, and BASIC respectively. You should read section IV to learn how to:

Create, open, and close a KSAM file.
Write records to the file in sequential primary key order or in random order.
Read records from the file in primary or altenate key order or in chronological order.
Read records at random by key value.
Read records directly according to a record number relative to the first chronological record.
Position record pointer forward or backward a specified number of records in any specified key sequence.
Position to a record defined by key value.
Position to a relative record number in key sequence or in chronological sequence.
Update or delete an existing record.
Request access and status information on the KSAM file.
Verify that input/output is completed, and verify that critical output is complete.
Dynamically lock or unlock the file.
Write or read user labels.

In general, SPL programmers can use all the file system intrinsics provided for HP 3000 standard files with the following exceptions:

A KSAM file cannot be renamed with the FRENAME intrinsic.
A KSAM file cannot be positioned to a relative record number with FREADSEEK. (Similar functions are performed by the KSAM intrinsics FFINDBYKEY and FFINDN).
A record cannot be written to a KSAM file according to relative record number with FWRITEDIR.
The relation between two files (interactive or duplicative) cannot be determined with FRELATE.

FORTRAN PROGRAMMER

If you are programming in FORTRAN, you should read section II in order to learn how to:

Create, purge, rename, clear the contents, display the status of, or save a KSAM file using KSAMUTIL.
Copy a KSAM file to another KSAM file in any key order with FCOPY.
Display the contents of a KSAM file in any key order on the standard list device using FCOPY.

As a FORTRAN programmer can call either the COBOL procedures described in section III (and summarized above) or the intrinsics described in section IV (also summarized above). You should, therefore, read both these sections. Depending on your program requirements, you can then choose to use either the COBOL procedures or the file system intrinsics. Since these methods differ significantly in how the file is created and accessed, you should not attempt to combine calls to COBOL procedures with calls to the file system intrinsics. In general, the intrinsics provide more capabilities than the COBOL procedures.

You should also read section V, which illustrates, by means of annotated examples, how to access a KSAM file through FORTRAN calls to the file system intrinsics. The examples illustrate:

Programmatically creating a KSAM file.
Writing records to a new KSAM file.
Reading the records in sequential order by primary key value and then by alternate key value.
Reading the records in chronological order.

BASIC PROGRAMMER

As a BASIC programmer you should read section II in order to learn how to:

Create, purge, rename, clear the contents, display the status of, or save a KSAM file using KSAMUTIL.
Copy a KSAM file to another KSAM file in any key order with FCOPY.
Display the contents of a KSAM file in any key order on the standard list device using FCOPY.

Since a BASIC programmer, like the COBOL programmer, cannot create a KSAM file programmatically, it is especially important to note how files are created with the BUILD command of program KSAMUTIL. Note also that BASIC programs cannot read a KSAM file in chronological sequence. You can, however, use FCOPY to copy the data file to a non-KSAM file and then read it in chronological sequence.

You can skip sections III, IV, and V, which apply to COBOL, SPL, and FORTRAN programming respectively, and read section VI, which describes the BASIC procedures to access KSAM files. These procedures enable you to:

Open and close a KSAM file.
Write records to a KSAM file in primary key or in random order.
Read records from the file in sequential order by key value, or at random by key value.
Change the key in preparation for a sequential read.
Rewrite or delete an existing record.
Dynamically lock and then unlock the file during shared access.

ALL PROGRAMMERS

Programmers using any of the languages that access KSAM files will probably need to refer to appendix A. This appendix contains an explanation of the error messages, condition codes, and status returns that can result from file access.

Appendix B describes the internal structure of KSAM files. It illustrates how key entries are stored in a special B-Tree structure, and how KSAM file size is determined. It also explains how files are accessed through the extra data segments allocated to each open file. This appendix provides information for the sophisticated programmer who wants to know how KSAM files operate in order to improve performance. For the average user, the information in appendix B is not needed in order to create and use KSAM files.

Appendix C provides the ASCII collating sequence used by KSAM /3000 to determine character key sequence; (numeric key sequence is in algebraic order). Note that the KSAM key sequence is in ascending order only, the order in which the ASCII characters are shown in appendix C.

Appendix D provides instructions that will help you convert your files to KSAM /3000 files. It tells you how to convert any serially accessible file to a KSAM file. If you are already using INDEX files, it describes use of the conversion program RTOKSAM for converting from INDEX to KSAM. Note that INDEX files were previously called RSAM files.

Appendix E describes the recovery procedures to be used if the system fails when KSAM files are open. It explains what happens when a file is closed normally as opposed to what happens when a system failure prevents normal closing, and then tells the user exactly what to do when a system failure affects open KSAM files.