Using KSAM/XL and KSAM 64 (32650-90886)

Appendix B 261
BASIC/V Intrinsics
BKWRITE
BKWRITE
Writes data from a BASIC program to a KSAM file.
CALL BKWRITE (
filenum,status,parameterlist )
A call to procedure BKWRITE writes a record to a KSAM file from a BASIC program. This
call provides the only way to create a KSAM record from a BASIC program. The file must
have been opened with an access mode that allows writing. If access is shared, the file also
must be opened for dynamic locking (
lock = 1), and the file locked with BKLOCK before any
records are written.
Parameters
filenum A numeric variable containing the file number value that identifies the
file. This number was returned by the last call to BKOPEN. It should not be
altered unless the file is closed by a successful call to BKCLOSE.(
Required
parameter
)
status A four-character string variable to which is returned a code that indicates
whether or not the call to BKWRITE was successful and if not, why not. The
first character is set to zero when the call succeeds, to another value if not.
(
Required parameter )
parameterlist A list of variables or constants, separated by commas, that contain the
data to be written to the file as a record. The total length of the record
contents is derived from the total number, the type, and the length in
characters of the items in
parameterlist . The parameterlist must
contain a value for each location defined as a key location in the record.
(
Required parameter )
Operation Notes
After calling BKWRITE, you should always check the status parameter to ensure that the
write was successful. Upon successful completion of BKWRITE, one record containing the
values specified in
parameterlist is written to the opened KSAM file.
Two parameters that are set when the file is opened affect how BKWRITE operates. These
are the
access and sequence parameters.
In order to write to a file, the file must be opened with
access greater than 0. If the access
parameter is set to 1, all existing data in the file is cleared before the first record is written
to the file. If
access is set to 2 or greater, the first record written by BKWRITE immediately
follows any existing records; the file is not cleared.
The
sequence parameter determines whether records must be written in primary key
sequence, or not. If
sequence is 0, records can be written in any order; no check is made on
the sequence of the primary key field. If
sequence is set to 1, you must write each record
with a value in the primary key field that is greater than the primary key value in the
previous record. Primary key values may equal the previous primary key value only if the
file was created with duplicate key values permitted.