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 “KSAM File System Intrinsics” for a list of the KSAM file system intrinsics.)

Table 4-1 KSAM File System Intrinsics

INTRINSIC NAME	KSAM ONLY	NOT USED BY KSAM	DIFFERENCES IN FORMAT	FUNCTION
FOPEN			ksamparam replaces formmsg as sixth parameter.	Opens a KSAM file for access and assign 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 included for compatibility only.	Writes record to KSAM file.
[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.
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 for compatibility only	Ensures that 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.
*HP32208	X		all new	Identifies the KSAM version.
FDELETE		X		Deactivates a RIO record.
FDEVICECONTROL		X		Provides control operations to a printer, Workstation Configurator, or a spooled device.
FFILEINFO			none	Provides access to file information.
FLABELINFO			The information returned may not match what is returned from FFILEINFO.	Returns information from the file label of a disc file.
FPARSE			none	Passes and validates file designators.
FREADBACKWARD		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:

Refer to the intrinsic format to determine the parameter type and position.
Declare any variable or array names to be passed as parameters at the beginning of the program.
Declare the intrinsic name in an INTRINSIC statement.
Issue the intrinsic call where appropriate in your program.

KSAM INTRINSIC SUMMARY

Table 4-1 “KSAM File System Intrinsics” 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 “KSAM File System Intrinsics”, 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