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

The first two parameters, filenumber and statusare 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 “KSAM Procedures for BASIC Interface” 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 NAME	PARAMETERS	FUNCTION	PAGE
BKCLOSE	filenum, status	Terminates processing of KSAM file identified by filenum.	6-8
BKDELETE	filenum, status	Logically removes record from KSAM file; the record to be deleted is the record at which the logical record pointer is currently positioned.	6-10
BKERROR	status, message	Converts numeric value returned in status parameter to character string message.	6-12
BKLOCK	filenum, status [,condtion]	Dynamically locks KSAM file during shared access, conditionally depending on condition.	6-14
BKOPEN	filenum, status, filename [,access [,dynamic lock [,exclusive [,sequence]]]]	Initiates processing of file identified by filenum, named by filename. Type of access, whether dynamic locking is allowed, whether access is exclusive, and whether primary key sequence is checked are options of BKOPEN.	6-16
BKREAD	filenum, status [,parameter- list]	Reads data from current sequential record of file identified by filenum into variables named in parameterlist.	6-22
BKREADBYKEY	filenum, status, keyvalue, keylocation, parameterlist	Reads data from a record identified by keyvalue in the key specified by keylocation of the file identified by filenum into variables named in parameterlist.	6-26
BKREWRITE	filenum, status, parameterlist	Writes data from parameterlist to record at which pointer is positioned in file identified by filenum.	6-29
BKSTART	filenum, status [,keyvalue [,keylocation [,relation]]]	Positions file identified by filenum in preparation for a sequential read to the first record with a key in keylocation whose value bears the specified relation to keyvalue.	6-32
BKUNLOCK	filenum, status	Unlocks file identified by filenum that has been previously locked by BKLOCK.	6-36
BKVERSION	status, message	Identifies version of KSAM/3000 currently being used returns version number in message.	6-38
BKWRITE	filenum, status, parameterlist	Writes data from parameterlist to record in file identified by filenum.	6-39