Using KSAM XL and KSAM 64 > Appendix B BASIC/V Intrinsics

BKOPEN

	MPE documents
	Complete PDF
	Table of Contents
	Index

	E0300 Edition 4 ♥
	E0394 Edition 3

A call to procedure BKOPEN initiates KSAM 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.

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/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. (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. Overwrites previously written data. Use of the procedures BKREAD, BKREADBYKEY, BKREWRITE, BKDELETE, and BKSTART are prohibited.

2: Write only. Saves previously written data and adds data. Use of the procedures BKREAD, BKREADBYKEY, BKREWRITE, BKDELETE, and BKSTART are prohibited.

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 equals 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 equals 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: Sequence checking. As each record is written to the file, KSAM checks to ensure 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.

Operation Notes

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.

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 ensure 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 B-2 "Procedures Allowed by BKOPEN Access Parameter" summarizes the procedures you may call depending on the access parameter value you specify in BKOPEN.

Table B-2 Procedures Allowed by BKOPEN Access Parameter

Procedure	Read-only (`access`=0)	Write-only with Clear (`access`=1)	Write-only with Save (`access`=2)	Read/Write (`access`=3)	Update (`access`=4)
`BKREAD`	X			X	X
`BKREADBYKEY`	X			X	X
`BKSTART`	X			X	X
`BKWRITE`		X	X	X	X
`BKREWRITE`					X
`BKDELETE`					X
`BKCLOSE`	X	X	X	X	X
`BKERROR`	X	X	X	X	X

By default in a multi-user environment, 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 B-3 "Relationship of Exclusive Parameter to Access Parameter" for a summary of the relation between the exclusive parameter and the access parameter.)

Table B-3 Relationship of Exclusive Parameter to Access Parameter

`exclusive`	=0	=1	=2 (default)	=3
`access`=0 (read only)	shared	exclusive	semi-exclusive	shared
`access`≠0 (write only, read/write, or update)	exclusive	exclusive	semi-exclusive	shared

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 B-2 "Procedures Allowed by BKOPEN Access Parameter" for a list of the pointer-dependent procedures.)

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. As a result of sequence checking, the physical 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 physical 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 physical order.

The example in Figure B-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 B-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 80 BYTES, FIXED, TYPE ASCII,
  121 REM   16 REC/BLOCK.
  130 REM THE KEY IS 2 CHARACTERS LONG,STARTING IN CHARACTER 2
  131 REM   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

BKLOCK

BKREAD

BKOPEN

MPE documents

Parameters

Operation Notes