HP 3000 Manuals HP 3000 Manuals
BKOPEN
A call to procedure BKOPEN initiates file processing.
CALL BKOPEN (filenum,status,name [;access[,lock[,exclusive[,sequence]]]])
In order to process a KSAM file, it must be opened with a call to the
BKOPEN procedure. BKOPEN initiates processing, and optionally specifies
how the file is to be processed. BKOPEN does not create the file; it
must have been created previously. You can create a KSAM file through
the BUILD command of the KSAMUTIL program (refer to section II).
To open a file means to make it available for processing. You can also
specify how the file is to be accessed (whether for input, output, input
and output, or for update), whether dynamic locking is allowed, whether
access to the file can be shared, and whether records written to the file
are to be checked for primary key sequence. Default values are assigned
for the optional parameters. If you want to change the current
processing or access method, you must close the file and then open it
again with the parameters set to new values.
PARAMETERS
filenum A numeric variable whose value identifies the file
opened by the call to BKOPEN. Since the value of filenum
identifies the file in other CALL statements, it must
not be changed while the file is open. (Required
parameter)
status A four-character string variable to which is returned a
code to indicate whether or not the file was
successfully opened and if not, why not. The first
character is "0" if the open is successful, to another
value if not. (Refer to Status Parameter discussion
earlier in this section.) (Required parameter)
name A string expression containing the name of the KSAM file
to be processed. This name is the actual designator
assigned to the file when it was created, or else it is
a back reference to a formal designator specified in a
:FILE command, in which case, name has the form *formal
designator. (Required parameter)
access A numeric expression whose value indicates one of the
permissible access types:
0 Read only. Use of procedures BKWRITE, BKREWRITE, and BKDELETE are
prohibited.
1 Write only. Deletes previously written data. Use of the procedures
BKREAD, BKREADBYKEY, BKREWRITE, BKDELETE, and BKSTART are
prohibited.
2 Write only. Saves previously written data. Use of the procedures
prohibited by the access=1, above, are also prohibited by
access=2.
3 Read and write. Use of procedures BKREWRITE and BKDELETE prohibited.
(Default value.)
4 Update access. Allows all procedures described in this section.
(Optional parameter) Default: If omitted, or out of
range, access is 3, read and write access.
lock A numeric expression whose value indicates whether
dynamic locking can take place. Acceptable values are:
0 Disallow dynamic Use of procedures BKLOCK and BKUNLOCK prohibited. (Default
locking and value.)
unlocking.
1 Allow dynamic Procedures BKLOCK and BKUNLOCK may be used to permit or
locking and restrict concurrent access to the file.
unlocking.
(Optional parameter) Default: If omitted, or out of
range, lock = 0 to disallow dynamic locking
exclusive A numeric expression whose value indicates the kind of
exclusive access desired for this file. If this
parameter is omitted or is not one of the following
acceptable values, the default is assumed:
0 Depends on access If access = 0 (read only), then users share access to this
parameter. file as if exclusive were set to 3. If access is not = 0,
then access to this file is exclusive as if exclusive were
set to 1.
1 Exclusive. Prohibits other access to this file until either the file
has been closed or the process terminated. Only the user
who opened the file can access it while it is currently
open.
2 Semi-exclusive. Other users can access this file, but only for read access.
The file cannot be accessed to write, rewrite, or delete
records until it is closed or the process is terminated.
(Default value.)
3 Shared. Once the file is opened, it can be accessed concurrently by
any user in any access mode, subject only to the MPE
security provisions in effect.
(Optional parameter) Default: If omitted, or out of
range, exclusive = 2, semi-exclusive access.
sequence A numeric expression whose value indicates whether
records written to the file will be checked for primary
key sequence or not. Acceptable values are:
0 No sequence When records are written to the file, primary key values can
checking. be in any order; their sequence is not checked. (Default
value.)
1 Sequence As each record is written to the file, KSAM checks to insure
checking. that its primary key value is greater than the primary key
value of any previously written records; if duplicates are
allowed for this key, then the primary key can be equal to
that of the previously written record.
(Optional parameter) Default: If omitted, or out of
range, sequence = 0, no sequence checking
USING BKOPEN
After calling BKOPEN, you should always check the status parameter to
determine whether the open was successful. Upon successful execution of
BKOPEN, the file named in name is available for processing; an
identification number is assigned to this file and returned to filenum
where it is available to identify the open file in other calls. Until
the file is successfully opened with BKOPEN, no operation can be executed
that references the file either explicitly or implicitly.
If only the first three parameters are specified, and the file is opened
successfully, the file has the following default characteristics:
* Read and Write access; you can read from and write to but not update
the file.
* Semi-exclusive access; other users can read from but not write to or
update the file.
* Dynamic locking not allowed; you cannot lock or unlock a file.
* No sequence checking; records can be written in any order without
checking sequence of primary key values.
Access Modes. There are two types of write only access: one clears any
existing records before writing the specified records to the file (access
= 1); the other saves existing records and writes the new records after
those already written (access = 2). Both these access modes do not
permit any read or update access to the file.
Read-only access (access = 0) can be specified if you want to insure that
the file is not changed. This mode prohibits the writing of new records,
and rewriting or deleting of existing records. In read-only mode, you
can position the file, and read records in either sequential or random
order.
The default access mode (access = 3) allows you both to read records from
and write records to a file, but not to change or delete existing
records. If you plan to read and write records during the same process,
but do not want to alter existing records, use this access mode.
If you want to rewrite or delete existing records in a KSAM file, you
must open with access = 4. This mode allows you to use the BKREWRITE and
BKDELETE procedures, as well as all the other procedures described in
this section.
Table 6-4 summarizes the procedures you may call depending on the access
parameter value you specify in BKOPEN.
Table 6-4. Procedures Allowed by BKOPEN access Parameter
------------------------------------------------------------------------------------------------------
| | | | | | |
| | Read-only | Write-only | Write-only | Read/Write | Update |
| | (access=0) | with Clear | with Save | (access=3) | (access=4) |
| | | (access=1) | (access=2) | | |
| | | | | | |
------------------------------------------------------------------------------------------------------
| | | | | | |
| Pro- | BKREAD | BKWRITE | BKWRITE | BKREAD | BKREAD |
| cedures | BKREADBYKEY | | | BKREADBYKEY | BKREADBYKEY |
| Allowed | BKSTART | | | BKSTART | BKSTART |
| | | | | BKWRITE | BKWRITE |
| | | | | | BKREWRITE |
| | | | | | BKDELETE |
| | | | | | |
| | BKCLOSE | BKCLOSE | BKCLOSE | BKCLOSE | BKCLOSE |
| | BKERROR | BKERROR | BKERROR | BKERROR | BKERROR |
| | | | | | |
------------------------------------------------------------------------------------------------------
Shared Access. By default in a multi-user envornment, all users whose
MPE security restrictions allow them to access your file can read the
file, but they cannot change the file or add new records to it. This is
the default specification of the exclusive parameter in BKOPEN
(exclusive=2). It is independent of the value of the access parameter.
If you want to prevent other users from reading the file as well as
writing to it, you must specify this by setting exclusive=1. This
setting allows only you to read from, write to, or alter the file.
Another alternative is to set exclusive=0, thereby allowing other users
access to the file only when it is opened for read only (access=0). This
setting of the exclusive parameter prevents any access by other users
when the file is opened for any form of write or update (accesss != 0) .
This means that you and other users share read access to the file, but
only you can write to or change the file.
You can choose to completely share access to the file, reading and/or
writing and updating, by setting the exclusive parameter to 3.
(Refer to Table 6-5 for a summary of the relation between the exclusive
parameter and the access parameter.)
Table 6-5. Relation of exclusive Parameter to access Parameter
-----------------------------------------------------------------------------------------------------
| | | | | |
| | exclusive=0 | exclusive=1 | exclusive=2 | exclusive=3 |
| | | | (default) | |
| | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | |
| access=0 | shared | exclusive | semi-exclusive | shared |
| (read only) | | | | |
| | | | | |
-----------------------------------------------------------------------------------------------------
| | | | | |
| access!=0 | exclusive | exclusive | semi-exclusive | shared |
| (write only, | | | | |
| read/write, | | | | |
| or update) | | | | |
| | | | | |
-----------------------------------------------------------------------------------------------------
Dynamic Locking. When access is shared, it is good practice to allow
dynamic locking so that individual users can dynamically lock the file
while performing any updates to the file. The file can be unlocked as
soon as the update is complete. An update to a file is when you write a
new record, delete a record, or rewrite an existing record. When access
is exclusive or semi-exclusive, there is no need for dynamic locking
since only the user who has opened the file can update the file.
Dynamic locking should also be allowed if access is shared and you plan
to read the file sequentially. This is because the sequential read
procedure (BKREAD) is dependent on the position of the logical record
pointer and, in a shared environment, this pointer can be changed by
other users unless the file is locked (Refer to Table 6-3 for a list of
the pointer-dependent procedures.)
Sequence Checking. When sequence checking is specified, you must write
records to the file in primary key sequence. An attempt to write a
record out of sequence causes the write to fail and the value "21" is
returned to status following a call to BKWRITE. (Refer to the description
of Status earlier in this section.) As a result of sequence checking,
the chronological and the primary key sequence of records in your file is
the same. Since the BASIC KSAM procedures have no provision to read the
file in chronological sequence, you may want to specify sequence checking
for any file that you will want to read in that order. With sequence
checking, a file read in logical order by primary key (the default for
BKREAD) is also read in chronological order.
The example in Figure 6-4 shows how to use BKOPEN to open a KSAM file for
input and output (default access), with dynamic locking (lock=1), for
shared access (exclusive=3), and without sequence checking (default
sequence).
_____________________________________________________________________________
| |
| 10 DIM S$[4] <-------- status \ |
| 20 DIM N$[26] <------------- filename |- variable dimensions |
| 30 DIM M$[72] <-------- message / |
| 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 REM KEY=B,2,2,,DUP |
| 120 REM SO,RECORD LENGTH IS 2 BYTES, FIXED, TYPE ASCII, 16 REC/BLOCK. |
| 130 REM THE KEY IS 2 CHARACTERS LONG,STARTING IN CHARACTER 2 OF RECORD|
| 135 REM |
| 140 REM ******************************************************** |
| 145 REM * OPEN A KSAM FILE * |
| 150 REM ******************************************************** |
| 160 REM |
| 170 REM THE FILE NAME IS IN N$ |
| 175 REM THE STATUS OF THE CALL IS RETURNED IN S$ |
| 180 REM WHEN SUCCESSFUL, BKOPEN RETURNS A FILE NUMBER IN F |
| 190 REM INPUT-OUTPUT ACCESS IS SPECIFIED IN J |
| 200 REM DYNAMIC LOCKING IS ALLOWED IN D |
| 210 REM SEMI-EXCLUSIVE ACCESS IS INDICATED IN E |
| 220 REM |
| 240 N$="KNAME,ACCOUNT,GROUP" <---------- file name |
| 250 J=3 <-------- access is read/write |
| 260 D=1 <------------------------------- dynamic locking allowed |
| 270 E=3 <-------- access shared |
| 280 CALL BKOPEN(F,S$,N$,J,D,E) |
| 290 REM |
| 300 REM NOW DETERMINE WHETHER THE CALL SUCCEEDED: |
| 310 REM |
| 320 IF S$[1;1]<>"0" THEN DO |
| 330 REM S$ IS THE STATUS CODE SET BY THE CALL TO BKOPEN |
| 340 REM N$ IS THE NAME OF THE FILE |
| 350 PRINT "UNABLE TO OPEN ";N$;" ERROR ";S$[1;1];"DETAIL "LS$[2] |
| 360 CALL BKERROR(S$,M$) |
| 370 PRINT M$ |
| 380 GOTO 3620 <-------- to close the file |
| 390 DOEND |
| 400 REM |
| 410 REM THE PROGRAM CONTINUES |
_____________________________________________________________________________
Figure 6-4. Opening KSAM File with BKOPEN