HP 3000 Manuals HP 3000 Manuals
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. (Refer to the Status Parameter discussion
earlier in this section.) (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)
USING BKWRITE
After calling BKWRITE, you should always check the status parameter to
insure 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 zero, 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. To illustrate, assume that the record illustrated by the
following example was the first record written to the file. It has the
value 1 as its primary key. If the file was opened with sequence = 1,
the next record written must have a value of 2 or more in the primary key
field. It may have the same value only if duplicates are allowed for
that key field, and must not have a value less than the previous primary
key.
The values written to the record depend on the type of the items in
parameterlist. To illustrate, consider the following statements:
10 DIM D$(20),E$(10),S$(4)
20 INTEGER I,J
30 D$="MITCHELL"<------------------ logical length = 8 characters
40 E$="JAMES" <------------------------- logical length = 5 characters
50 I=0<------------|
each integer requires 2 characters
60 J=1<------------|
70 CALL BKWRITE (F,S$,I,J,D$,E$)
/ | \-------/
/ | |
filnum | parameterlist
status
This set of statements writes one record to the KSAM file. The record
has the form:
![[]](../../pic3k/M010088/F0610A3c50.gif)
Assuming a file created with one key starting in the third character, two
characters long, the value 1 is the key value. Each integer requires 2
characters, the two strings use a total of 13 characters, resulting in
values that take up 17 characters of the record. The remainder of the
record is undefined. Record size is specified at file creation.
When writing from numeric arrays, the dimensioned length is used; when
writing from strings the logical length is used. The logical length of a
string variable or string array element, is the number of characters
actually stored in the variable or element. It determines the length of
the item written to the record. A numeric array, on the other hand, uses
the dimensioned length as the length of the item written to the record.
For example, suppose a numeric array A is added to the parameterlist in
the previous example:
5 INTEGER A(10) <------------------------- dimensioned length of A is 10 words
10 DIM D$(20),E$(10),S$(4)
20 INTEGER I,J,F
30 D$="MARSHALL"
40 D$="MILLY"
50 FOR I=1 TO 5 \
60 A(I)=1 |--------------------- Move 5 words to array A
70 NEXT I &/
80 I=0
90 J=3
100 CALL BKWRITE(F,S$,I,J,A(*),D$,E$)
This set of statements results in a record with the following values:
![[]](../../pic3k/M010088/F0610B3c50.gif)
NOTE Items written to a KSAM file from a BASIC program are concatenated;
rounding to word boundaries does not occur.
Figure 6-11 is an example of writing one string and one integer array to
each record of the KSAM file opened in Figure 6-4. The three records
written contain the following data:
![[]](../../pic3k/M010088/F0610C3c50.gif)
_____________________________________________________________________________
| |
| 10 DIM S$[4] |
| 20 DIM N$[26] |
| 30 DIM M$[72] |
| 40 INTEGER A[10] |
| 50 DIM B$[12] |
| 55 INTEGER J |
| 60 DIM B1$[1] |
| 65 DIM B2$[2] |
| 70 INTEGER A2[2],A3[3],A5[5] |
| 80 REM |
| 90 REM THE KSAM/3000 FILE WAS BUILT WITH: |
| 100 REM REC=-80,16,F,ASCII |
| 110 PEM KEY=B,2,2,DUP |
| 120 REM SO,RECORD LENGTH IS 2 BYTES, FIXED, TYPE ASCII, 16 REC/BLOCK.|
| 130 THE KEY IS 2 CHARACTERS LONG,STARTING IN CHARACTER 2 OF RECORD |
| 135 REM |
| : |
| 430 REM ******************************************************** |
| 440 REM * WRITE TO A KSAM FILE * |
| 450 REM ******************************************************** |
| 460 REM |
| 470 PEM ASSIGN VALUES TO OUTPUT VARIABLES |
| 480 REM |
| 490 FOR I=1 TO 5 |
| 500 A[I]=I |
| 510 NEXT I |
| 520 RS="123" |
| 530 REM |
| 540 REM F IS THE FILE NUMBER OF A KSAM FILE |
| 550 REM OPENED BY A CALL TO BKOPEN |
| 560 REM |
| |
| 570 REM NOTE THAT ONLY THREE BYTES "123" ARE WRITTEN FROM B$ |
| 580 REM WHEREAS TEN WORDS ARE WRITTEN FROM NUMERIC ARRAY A. |
| 620 REM |
| 630 REM THREE IDENTICAL RECORDS ARE BEING OUTPUT SO THAT |
| 640 REM SUBSEQUENT EXAMPLES OF THIS PROGRAM WILL EXECUTE |
| 650 REM . |
| 660 FOR I=1 TO 3 |
| 670 CALL BKWRITE(F,S$,BS,A[*]) |
| 680 REM |
| 690 REM NOW DETERMINE WHETHER THIS CALL SUCCEEDED |
_____________________________________________________________________________
Figure 6-11. Writing to a KSAM File with BKWRITE
____________________________________________________________________________
| |
| 700 REM |
| 710 IF S$[1;1]<>"0" THEN DO |
| 720 REM N$ CONTAINS THE NAME OF THE KSAM FILE |
| 730 REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CODE |
| 740 PRINT "UNABLE TO WRITE TO ";N$;"ERROR "[S$]; DETAIL ";S$[ 2]|
| 750 CALL BKERROR(S&,Ms) |
| 760 PRINT M$ |
| 770 GOTO 3620 |
| 780 DOEND |
| 790 NEXT I |
| 800 REM |
| 810 REM THE PROGRAM CONTINUES |
____________________________________________________________________________
Figure 6-11. Writing to a KSAM File with BKWRITE (continued)