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 locking and unlocking.	Use of procedures BKLOCK and BKUNLOCK prohibited. (Default value.)
1	Allow dynamic locking and unlocking.	Procedures BKLOCK and BKUNLOCK may be used to permit or restrict concurrent access to the file.

: (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 parameter.	If access = 0 (read only), then users share access to this 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 checking.	When records are written to the file, primary key values can be in any order; their sequence is not checked. (Default value.)
1	Sequencechecking.	As each recordis written to the file, KSAM checks to insure 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 “Procedures Allowed by BKOPEN access Parameter” 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

BKOPEN access Parameter

Read-only

(access=0)

Write-only

with Clear

(access=1)

Write-only

with Save

(access=2)

Read/Write

(access=3)

Update

(access=4)

Procedures

Allowed

BKREAD

BKREADBYKEY

BKSTART

BKWRITE

BKWRITE

BKREAD

BKREADBYKEY

BKSTART

BKWRITE

BKREAD

BKREADBYKEY

BKSTART

BKWRITE

BKREWRITE

BKDELETE

BKCLOSE

BKERROR

BKCLOSE

BKERROR

BKCLOSE

BKERROR

BKCLOSE

BKERROR

BKCLOSE

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 “Relation of exclusive Parameter to access Parameter” for a summary of the relation between theexclusive parameter and the access parameter.)

Table 6-5 Relation of exclusive Parameter to access Parameter

exclusive = 0

exclusive = 1

exclusive = 2

(default)

exclusive = 3

access = 0

(read only)

shared

exclusive

semi-exclusive

shared

access ≠ 0

(write only,

read/write,

or update)

exclusive

semi-exclusive

shared

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 “Positioning the Logical Record Pointer” 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 “Opening KSAM File with BKOPEN” 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).

Figure 6-4 Opening KSAM File with BKOPEN

 

 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

BKOPEN

Technical documentation

» Table of Contents

PARAMETERS

USING BKOPEN

Access Modes

Shared Access

Dynamic Locking

Sequence Checking