HP 3000 Manuals HP 3000 Manuals
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.