HP 3000 Manuals HP 3000 Manuals
Chapter 4 USING KSAM FILES IN SPL PROGRAMS
KSAM FILE SYSTEM INTRINSICS
The Multi-Programming Executive Operating System (MPE) provides a set of
procedures, known as intrinsics. A subset of these intrinsics makes up
the file system, a set of procedures used to manipulate files. KSAM
files are processed using these same intrinsics with the following
exceptions: seven new intrinsics are added for KSAM files, and four of
the file system intrinsics do not apply to KSAM files. (Refer to Table
4-1 for a list of the KSAM file system intrinsics.)
Table 4-1. KSAM File System Intrinsics
---------------------------------------------------------------------------------------------------
| | | | | |
| INTRINSIC | KSAM | NOT USED | DIFFERENCES IN FORMAT | FUNCTION |
| NAME | ONLY | BY KSAM | | |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FOPEN | | | ksamparam replaces | Opens a KSAM file for |
| | | | formmsg as sixth | access and assign |
| | | | parameter. | file number to file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FCLOSE | | | none | Closes a KSAM file to |
| | | | | further access. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| [FRENAME] | | X | -- | If called for KSAM |
| | | | | file, returns CCL |
| | | | | error code. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FREAD | | | none | Reads next record in |
| | | | | sequential order by |
| | | | | key. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| *FREADC | X | | all new | Reads next record in |
| | | | | chronological |
| | | | | sequence. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| *FREADBYKEY | X | | all new | Reads record |
| | | | | identified by key |
| | | | | value. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FREADDIR | | | none | Reads record |
| | | | | identified by |
| | | | | chronological |
| | | | | position. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| [FREADSEEK] | | X | If called for KSAM file, | |
| | | | returns CCL error code. | |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FWRITE | | | control parameter | Writes record to KSAM |
| | | | included for | file. |
| | | | compatibility only. | |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| [FWRITEDIR] | | X | -- | If called for KSAM |
| | | | | file, returns CCL |
| | | | | error code. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| *FREMOVE | X | | all new | Deletes current |
| | | | | record from KSAM |
| | | | | file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FUPDATE | | | none | Updates last |
| | | | | referenced record. |
| | | | | |
---------------------------------------------------------------------------------------------------
Table 4-1. KSAM File System Intrinsics (continued)
---------------------------------------------------------------------------------------------------
| | | | | |
| INTRINSIC | KSAM | NOT USED | DIFFERENCES IN FORMAT | FUNCTION |
| NAME | ONLY | BY KSAM | | |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FSPACE | | | none | Spaces forward or |
| | | | | backward in file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| *FFINDBYKEY | X | | all new | Positions current |
| | | | | record pointer to |
| | | | | record located by key |
| | | | | value. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| *FFINDN | X | | all new | Positions current |
| | | | | record pointer to |
| | | | | relative record |
| | | | | number in key |
| | | | | sequence. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FPOINT | | | none | Positions current |
| | | | | record pointer to |
| | | | | relative record |
| | | | | number in |
| | | | | chronological |
| | | | | sequence. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FGETINFO | | | none | Requests file access |
| | | | | and status |
| | | | | information. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| *FGETKEYINFO | X | | all new | Requests access and |
| | | | | status information on |
| | | | | KSAM file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| [FRELATE] | | X | -- | If called for KSAM |
| | | | | file, returns CCE and |
| | | | | false condition. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FCHECK | | | none | Requests details of |
| | | | | file input/output |
| | | | | errors. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FERRMSG | | | none | Prints message |
| | | | | corresponding to |
| | | | | FCHECK error code. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FCONTROL | | | param parameter included | Ensures that |
| | | | for compatibility only | input/output is |
| | | | | complete or positions |
| | | | | to first sequential |
| | | | | record by key value; |
| | | | | other options not |
| | | | | available for KSAM |
| | | | | file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FSETMODE | | | none | Verifies critical |
| | | | | output as part of |
| | | | | write operation; |
| | | | | other options not |
| | | | | available for KSAM |
| | | | | file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FLOCK | | | none | Dynamically locks |
| | | | | file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FUNLOCK | | | none | Dynamically unlocks |
| | | | | file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FREADLABEL | | | none | Reads user's file |
| | | | | label. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FWRITELABEL | | | none | Writes user's file |
| | | | | label. |
| | | | | |
---------------------------------------------------------------------------------------------------
KSAM File System Intrinsics (continued)
---------------------------------------------------------------------------------------------------
| | | | | |
| INTRINSIC | KSAM | NOT USED | DIFFERENCES IN FORMAT | FUNCTION |
| NAME | ONLY | BY KSAM | | |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| *HP32208 | X | | all new | Identifies the KSAM |
| | | | | version. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FDELETE | | X | | Deactivates a RIO |
| | | | | record. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FDEVICE- CONTROL | | X | | Provides control |
| | | | | operations to a |
| | | | | printer, Workstation |
| | | | | Configurator, or a |
| | | | | spooled device. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FFILEINFO | | | none | Provides access to |
| | | | | file information. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FLABELINFO | | | The information returned | Returns information |
| | | | may not match what is | from the file label |
| | | | returned from FFILEINFO. | of a disc file. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FPARSE | | | none | Passes and validates |
| | | | | file designators. |
| | | | | |
---------------------------------------------------------------------------------------------------
| | | | | |
| FREAD- BACKWARD | | X | | Reads a logical |
| | | | | record backward from |
| | | | | the current record |
| | | | | pointer. Data is |
| | | | | presented to the user |
| | | | | as if read forward. |
| | | | | |
---------------------------------------------------------------------------------------------------
CALLING INTRINSICS FROM SPL
An intrinsic used in an SPL program must be declared at the beginning of
the program following all other declarations. There are two ways to
declare an intrinsic: one is to make an external procedure declaration,
and the other is to use the INTRINSIC declaration. Since declaring an
external procedure is a long process, you can save space and time by
using the INTRINSIC declaration as follows:
INTRINSIC intrinsicname, intrinsicname,..., intrinsicname;
You name all the intrinsics used in your program in the intrinsicname
list. When more than one intrinsic is named, the names must be separated
by commas.
You call an intrinsic by writing the intrinsic name followed by a list of
parameters enclosed in parentheses. These parameters must be in the
order established for each intrinsic as shown in the intrinsic formats
later in this section. Every parameter that is specified as a variable
or an array must be declared before the intrinsic is called. The formats
that describe intrinsics define the variable or array type of each
parameter; specify whether it can be passed by value or must be passed by
reference; and indicate whether any parameters are optional and if so
which ones.
In summary, to call an intrinsic from an SPL program:
1. Refer to the intrinsic format to determine the parameter type and
position.
2. Declare any variable or array names to be passed as parameters at
the beginning of the program.
3. Declare the intrinsic name in an INTRINSIC statement.
4. Issue the intrinsic call where appropriate in your program.
KSAM INTRINSIC SUMMARY
Table 4-1 is provided to give an overview of the intrinsics available for
accessing KSAM files. In this table, the intrinsics are organized into
functional groupings. In the body of this section, however, the
intrinsic descriptions are in alphabetic order so that they may be
referenced easily.
In Table 4-1, an asterisk (*) preceding an intrinsic name indicates that
this intrinsic applies only to KSAM files. A bracket around an intrinsic
name indicates that the intrinsic should not be used for KSAM files.
INTRINSIC FORMAT
Intrinsic format is illustrated below using FCHECK as an example.
IV I I D I O-V
FCHECK(filenum,errorcode,tlog,blknum,numrec);
Optional parameters are indicated by an underline under each option and
by the superscript O-V. The parameter type and whether it is passed by
value is shown by the superscript over each parameter. Possible
parameter types are:
BA Byte array
BP Byte pointer
D Double
DA Double array
DV Double by value
I Integer
IA Integer array
IV Integer by value
L Logical
LA Logical array
LV Logical by value
R Real
PASSING PARAMETERS. Integer,logical and double type parameters can be
passed by value. This means that the actual value can be specified in
the intrinsic call instead of a variable or array name. When a parameter
is passed by reference (default for all parameter types), the address in
the caller's data area of the named variable or array is made available
to the intrinsic. If the variable or array is modified by execution of
the intrinsic, the storage in the caller's data area is updated. When a
parameter is passed by value, the corresponding variable in the calling
routine is unchanged.
OPTIONAL PARAMETERS. If any parameters can be omitted, the superscripts
that describe individual parameters are followed by the superscript O-V,
option variable. O-V means that at least one parameter in the list is
optional. Since all parameters are recognized by their position in the
list, a parameter may be omitted but its preceding comma must be
included. If one or more parameters are omitted from the end of the
list, this is indicated by placing the terminating parenthesis after the
last specified parameter.
For example:
FCHECK(FILEX , , , , REC)
only the first and fifth parameters are included
FCHECK(2,ERR)
the last three parameters are omitted; note that filenum is passed
by value