HP 3000 Manuals HP 3000 Manuals
CALLING A KSAM PROCEDURE
The KSAM interface procedures are called from a BASIC program with a CALL
statement of the following general form:
statement label CALL procedure name (filenumber, status [,parameterlist])
Where
statement label is the number of the statement in the program.
procedure name identifies the KSAM access procedure to which control is
transferred. (Refer to Table 6-1 for a complete list of
the procedure names.)
filenumber is a numeric variable whose value identifies an open
KSAM file. This parameter must be present. Its value
is assigned by KSAM/3000 when the file is opened and
must not be changed until the file is closed.
status is a 4-character string variable to which a code is
returned that indicates whether the current operation
was successful or not, and if not, the reason for
failure.
parameterlist is a set of one or more parameters that, if present,
further define input-output operations on this file.
The first two parameters, filenumber and status are included in every
KSAM procedure call, except BKERROR and BKVERSION. The parameters in
parameterlist depend on the procedure in which they are used. Some
parameterlist parameters are optional and, if omitted, default values are
assigned by KSAM. Such parameters are indicated by brackets in the
procedure call format. The required parameters filenumber and status are
both variables, the first numeric, the second string. Other parameters
are either variables or expressions. Expressions being either variables,
constants, or a combination of both. The data type of the parameter
depends on its definition in the procedure. The procedure call formats
specify the data type of each parameter.
Depending on the procedure, certain variables can be assigned values as a
result of executing the procedure. The procedure itself is never
assigned a value (unlike a function, which may be assigned a value).
Refer to Table 6-1 for a complete list of the KSAM interface procedures
that can be called from a BASIC program.
OPTIONAL PARAMETERS
When parameters in parameterlist are optional, those parameters are
surrounded by brackets, In a series of optional parameters, the enclosing
brackets are nested. For example:
CALL name (filenum,status[,param1[,param2[,param3]]])
This notation tells you that parameters can be omitted only from the end
of the optional list; parameters cannot be omitted from the middle or
beginning of the list. For example, if you want to specify param3, you
must also specify the preceding parameters, param1 and param2; if you
specify param2, you can omit the following parameter param3, but not the
preceding param1.
Table 6-1. KSAM Procedures for BASIC Interface
--------------------------------------------------------------------------------------------------
| | | | |
| PROCEDURE | PARAMETERS | FUNCTION | PAGE |
| NAME | | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKCLOSE | filenum, | Terminates processing of KSAM file | 6-8 |
| | | identified by filenum. | |
| | status | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKDELETE | filenum, | Logically removes record from KSAM file; | 6-10 |
| | | the record to be deleted is the record at | |
| | status | which the logical record pointer is | |
| | | currently positioned. | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKERROR | status, | Converts numeric value returned in status | 6-12 |
| | | parameter to character string message. | |
| | message | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKLOCK | filenum, | Dynamically locks KSAM file during shared | 6-14 |
| | | access, conditionally depending on | |
| | status | condition. | |
| | [,condtion] | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKOPEN | filenum, | Initiates processing of file identified by | 6-16 |
| | | filenum, named by filename. Type of | |
| | status, | access, whether dynamic locking is allowed, | |
| | | whether access is exclusive, and whether | |
| | filename | primary key sequence is checked are options | |
| | [,access | of BKOPEN. | |
| | [,dynamic lock | | |
| | [,exclusive | | |
| | [,sequence ]]]] | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKREAD | filenum, | Reads data from current sequential record | 6-22 |
| | | of file identified by filenum into | |
| | status | variables named in parameterlist. | |
| | [,parameter- list]| | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKREADBYKEY | filenum, | Reads data from a record identified by | 6-26 |
| | | keyvalue in the key specified by | |
| | status, | keylocation of the file identified by | |
| | | filenum into variables named in | |
| | keyvalue, | parameterlist. | |
| | | | |
| | keylocation, | | |
| | | | |
| | parameterlist | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKREWRITE | filenum, | Writes data from parameterlist to record at | 6-29 |
| | | which pointer is positioned in file | |
| | status, | identified by filenum. | |
| | | | |
| | parameterlist | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKSTART | filenum, | Positions file identified by filenum in | 6-32 |
| | | preparation for a sequential read to the | |
| | status | first record with a key in keylocation | |
| | [,keyvalue | whose value bears the specified relation to | |
| | [,keylocation | keyvalue. | |
| | [,relation ]]] | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKUNLOCK | filenum, | Unlocks file identified by filenum that has | 6-36 |
| | | been previously locked by BKLOCK. | |
| | status | | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKVERSION | status, | Identifies version of KSAM/3000 currently | 6-38 |
| | | being used returns version number in | |
| | message | message. | |
| | | | |
--------------------------------------------------------------------------------------------------
| | | | |
| BKWRITE | filenum, | Writes data from parameterlist to record in | 6-39 |
| | | file identified by filenum. | |
| | status, | | |
| | | | |
| | parameterlist | | |
| | | | |
--------------------------------------------------------------------------------------------------