HP 3000 Manuals HP 3000 Manuals
FOPEN
INTRINSIC NUMBER 1
Opens a file.
I BA LV LV IV BA BA
filenum:=FOPEN(formaldesignator,foptions,aoptions,recsize,device,ksamparam,
IV IV IV DV IV
userlabels,blockfactor,numbuffers,filesize,numextents,
IV IV O-V
initialloc,filecode);
The FOPEN intrinsic makes it possible to access a KSAM file. In the
FOPEN intrinsic call, a particular file may be referenced by its formal
file designator. When the FOPEN intrinsic is executed, it returns to the
user's process a file number by which the system uniquely identifies the
file. This file number, rather than the file designator, then is used by
subsequent intrinsics in referencing the file.
FUNCTIONAL RETURN
This intrinsic returns an integer file number used to identify the opened
file in other intrinsic calls.
PARAMETERS
formal- byte array (required)
designator
Contains a string of ASCII characters interpreted as a
formal file designator. This string must begin with a
letter, contain alphanumeric characters, slashes, or
periods, and terminate with any nonnumeric character
except a slash or a period. If the string names a
userpredefined file, it can begin with an asterisk (*).
Note: The DEL, SAVE, or TEMP parameters should not be
used to predefine a KSAM file in a :FILE command; they
will cause deletion or duplication of the file.
foptions logical by value (optional)
The foptions parameter allows you to specify different
file characteristics, by setting corresponding bit
groupings in a 16-bit word. If the file is new, bit 4
must be set to 1 to indicate that this is a KSAM file.
Refer to Table 4-6 for the foption bit settings.
Default: All bits are set to zero.
aoptions logical by value (optional)
The aoptions parameter permits you to specify the
various access options established by bit groupings in a
16-bit word. These access options are defined in Table
4-7.
Default: All bits are set to zero.
recsize integer by value (optional)
An integer indicating the size of the logical records in
the data file. If a positive number, this represents
words; bytes are represented by a negative number. If
the file is a newly-created file, this value is recorded
permanently in the file label. If the records in the
file are of variable length, this value indicates the
maximum logical record length allowed.
Binary files are word oriented. A record size
specifying an odd byte count for a binary file is
rounded up by FOPEN to the next highest even number.
ASCII files may be created with logical records which
are an odd number of bytes in length. Within each
block, however, records begin on word boundaries.
For either ASCII or binary files with fixed-length
records, the record size is rounded up to the nearest
word boundary. For example, a recsize specified as -106
for an ASCII file is 106 characters (53 words) in
length. A recsize of -113 for a binary file is 114
characters (57 words) in length. The rounded sizes
should be used in computations for blockfactor or block
size.
Default: The default value is the configured physical
record width of the associated device.
device byte array (optional)
Contains a string of ASCII characters terminated by any
nonalphanumeric character (except a slash or period)
that designates the device on which the file is to
reside. It may be a device class name of up to eight
alphanumeric characters beginning with a letter; or a
logical device number consisting of a three-byte numeric
string; or a remote device identifier consisting of the
device class name or logical device number followed by a
pound sign (#) and a remote device class name or logical
device number.
Device class names and logical device numbers are
assigned to devices during system configuration.
For KSAM files, the device must be a random access
device such as the disc. If the file is a newly-created
disc file specified as a device class name, then all
extents to the file must be members of the same class.
Similarly, if the device is identified by logical device
number, then all extents must have the same logical
device number.
Default: Disc.
ksamparam byte array (optional)
Contains information describing the key file of a KSAM
file. It includes the key file name, size and device
plus an entry for the primary key and up to 15 alternate
keys. If the file is new (is being created by FOPEN)
then this array must be included. If the file is an old
file, it can be omitted. Note that if the parameter is
included and the file is not a KSAM file, an error can
result. Refer to Table 4-8 for a full description of
ksamparam.
Default: key file description is omitted.
userlabels integer by ualue (optional)
Specifies the number of user-label records to be written
for the data file. If there are no user labels, this
parameter can be omitted.
Default: The default number of user-label records is
zero.
blockfactor integer by value (optional)
Establishes the size of each block in the data file by
specifying the number of logical records per block. It
also establishes the size of the data file buffer in
KSAM's extra data segment . For fixed-length records,
blockfactor is the actual number of records in a block;
for variablelength records, blockfactor is a multiplier
used to compute block size from record size; ( (maximum
recsize +1) * blockfactor) +1 = blocksize. The value of
blockfactor should be an integer that results in a block
size less than 4K words. The blockfactor is from 1
through 255. If you specify a negative value or zero,
the default value is used. Values greater than 255 are
defaulted to the specified blockfactor modulo 256.
Default: 1
numbuffers integer by value (optional)
An integer between 1 and 20 that specifies the number of
key block buffers in the extra data segment used by KSAM
files for buffering data and key blocks. The number of
buffers is specified in bits 4-10; the rest of the word
must be set to zeros:
Click here to view figure.
This number should only be specified if the default
number assigned by KSAM affects performance. Refer to
appendix B, under KSAM Extra Data Segments for a
discussion of how the key block buffers are used.
Default: Between 1 and 20 bUffers depending on access
type, number of keys, and number of levels per hey.
(Refer to appendix B.)
filesize double by value (optional)
A double-word integer specifying the maximum data file
size as the number of logical records in the file. A
zero or negative value results in the default filesize
setting. The maximum file capacity is over two million
(221 ) sectors; a sector contains 128 words.
Default: 1024 logical records
numextents integer by value (optional)
An integer specifying the number of extents (integral
number of contiguously-located disc sectors) that can be
dynamically allocated to the file as logical records are
written to it. The number of extents applies equally to
the data and key files on the assumption that there is a
proportional expansion in each. The size of each extent
is determined by the filesize parameter value divided by
the numextents parameter value. If specified,
numextents must be an integer from 1 to 32. A zero or
negative value results in the default setting.
Default: 8 extents.
_______________________________________________________
NOTE Extents are allocated on any disc in the device
class specified in the device parameter when the
file was created. If it is necessary to insure
that all extents of a file are on a particular
disc, a single disc device class or a logical
device number must be used in the device
parameter.
_______________________________________________________
initialloc integer by value (optional)
An integer specifying the number of extents to be
allocated to the data file when it is opened. (For a
key file, this parameter is forced equal to the value of
numextents.) This must be an integer from 1 to 32. If
an attempt to allocate the requested disc space fails,
the FOPEN intrinsic returns an error condition code to
the calling program.
Default: 1 extent.
filecode integer by value (optional)
An integer recorded in the file label and made available
for general use to anyone accessing the file through the
FGETINFO intrinsic. This parameter is used for new data
files only. The filecode applies to data files only;
the key file code is always 1080 and need not be
specified. For this parameter, any user can specify a
non-negative integer.
Default: 0
CONDITION CODES
CCE Request granted. The file is open.
CCG Not returned by this intrinsic.
CCL Request denied. This may be because another process
already has exclusive or semi-exclusive access for this
file, or an initial allocation of disc space cannot be
made due to lack of disc space. The file number value
returned by FOPEN if the file is not opened successfully
is zero. The FCHECK intrinsic should be called for more
details.
USING FOPEN
FOPTIONS PARAMETER.
Table 4-6. FOPEN foptions Parameter Format
Click here to view figure.
AOPTIONS PARAMETER.
Table 4-7. FOPEN aoptions Parameter Format
Click here to view figure.
Table 4-7. FOPEN aoptions Parameter Format (continued)
Click here to view figure.
KEY FILE DEFINITION. The ksamparam array defines the key file for a new
KSAM file. If the file has already been created, this parameter can be
set to all zeros or omitted. Otherwise, it must be assigned values to
define the key file as shown in Table 4-8.
When a new KSAM file is created, the MPE end-of-file for the key file is
set to the file limit. The file limit is based on the key file size (see
words 4-5 of ksamparam). The location of the key file end-of-file can be
determined by executing the VERIFY command of KSAMUTIL and looking at the
heading KEY FILE EOF. A call to FGETKEYINFO returns the key file size as
the number of sectors used by the file.
Table 4-8. FOPEN ksamparam Parameter Format
Click here to view figure.
This array defines the key file portion of a new KSAM file being created
by the FOPEN call. The values are:
Key File Name 8-byte file name that must be present if this is a new
file. Only the name is specified; the account, group,
and security are taken from the data file formal file
designator.
Key File Size Double-word specifying the maximum number of primary
keys expected from which the key file size is derived.
If zero, the data file size is used.
(Note that a call to FGETKEYINFO returns the key file
size as the number of sectors in the file.)
Key Device 8-byte array that specifies the device on which the key
file resides. Specified as a device class name of 1-8
alphanumeric characters beginning with a letter and
terminated by a non-alphanumeric character such as a
blank; or it is specified as a logical device number
(3-byte numeric string) identifying a particular device.
If the data file is assigned to a remote device the key
file is automatically allocated to the same machine.
Default is DISC.
Language The number of the language to use in determining the key
Identification- sequence. Bit 11 in the flagword must be set to 1 to
Number use any language other than NATIVE-3000.If bit 11 is set
to 0, NATIVE-3000 (the default) is used and the language
identification number in word 10 is ignored. If the
language is not configured, FOPEN returns condition code
CCL. For detailed information on using Native Language
Support (NLS) with KSAM files, refer to Appendix F.
Flagword 1-word that specifies file characteristics as shown
below:
-------------------------------------------
| 0 1 2 3 4 5 6 7 8 9 10 11 12|13|14|15 |
-------------------------------------------
| reserved |DL|NL| |SW|RN|JT |
-------------------------------------------
JT bit 15:1 = 1 if file is job temporary
file
= 0 if file is a permanent file
(default)
RN 14:1 = 1 if record numbering starts
with 1.
0 if record numbering starts with 0.
(default)
SW 13:1 = 1 if only sequential writing by
primary key value is allowed.
= 0 if random writing by primary key
value is allowed. (default)
0:9 = 0 all reserved bits must be set
to 0.
NL bit 11:1 = 1 if a configured language
is specified.
= 0 if the default language
(NATIVE-3000) is to be used.
DL bit 10:1 = 1 Duplicate file locks from
different open paths of the same PIN
are not allowed.
= 0 Duplicate file locks from the same
PIN are always allowed.
Number of Keys 1 byte providing the total number of keys for the file,
specified as a numeric digit between 1 and 16, (left
byte of word must be zero).
Key Definitions Each key in the file requires a 4-word definition. The
first definition is always of the primary key.
Subsequent definitions describe any alternate keys. Up
to 15 alternate keys are allowed in any one key file.
The key definitions each contain the following
information:
bits 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
------------------------------------------------------
| Key Type | Key Length |
|----------------------------------------------------|
| Key Location |
|----------------------------------------------------|
| D | Minimum (Maximum) Number of Keys per Block |
|----------------------------------------------------|
| (reserved) | R | (reserved) |
------------------------------------------------------
The information for each key has the form shown above
starting in word 17 of ksamparam. It is defined as
follows:
Key Type 4 bits specifying the type of the key by the following
code:
bits 0:4 = 0001 (1) = Byte key (1 to 255 bytes)
0010 (2) = Integer key (2 bytes)
0011 (3) = Double Integer key (4 bytes)
0100 (4) = Real key (4 bytes)
0101 (5) = Long key (8 bytes)
0110 (6) = Numeric Display key (1 to 28
bytes)
0111 (7) = Packed Decimal key, odd
number of digits (1 to 14 bytes)
1000 (8) = Packed Decimal key, even
number of digits (2 to 14 bytes)
Refer to Table 2-2 in section II for a full description
of key type.
Key Length 12 bits specifying length of the key in bytes. Length
is a function of key type (see key type) but must never
exceed 255 bytes.
Key Location 1 word specifying the location of the first byte of the
key in the record. Bytes in a record are numbered
starting with 1. (Note that it is good practice to
leave the first two bytes of a record empty of keys
since these bytes are used by FREMOVE for the record
delete code.)
D(Duplicate 1 bit that determines if duplicate values are allowed
Flag) for this key: = 0 if duplicate key values are not
allowed (default) = 1 if duplicate key values are
allowed.
Minimum 15 bits that specify the minimum number of keys allowed
(Maximum)- per key block. The value must be an even -numbered
Number of Keys integer greater than or equal to 4. The resulting key
per- Block block size must be less than 2048 words. If the
resulting key block size is greater than 2048 words, the
system will print the error message "INVALID KEY
BLOCKING FACTOR VALUE (FSERR 190)" and will not open the
file. In order to make optimum use of disc space, KSAM
may increase the value specified here. If KSAM
increases the number of keys per block, this new value
is the maximum size of the key block. (Refer to
appendix B for particulars on the calculation of block
size and the adjustment of the blocking factor). The
default generates a block size of 1K (1024) words.
R(Random Insert 1 bit (8:1) that determines whether duplicate key is to
Flag) be inserted randomly in duplicate key chain or is to be
added to the end of the chain; the duplicate flag (D
bit) must be set to 1 in order to use this flag.
= 0 if duplicate key values are to be inserted at the
end of the chain (default)
= 1 if duplicate key values are to be inserted
randomly. If inserted randomly, the chronological
order of duplicate keys is no longer maintained, but
the addition of keys is faster.
OPENING A NEW FILE
When FOPEN is used to open a new KSAM file, you must provide all the
information needed to create the two files that make up a KSAM file: the
key file and the data file. To inform the system that this is a KSAM
file, the KSAM bit must be set in the foptions parameter; and the
ksamparam parameter must be included to define the key file.
Figure 4-5 is a short SPL program that builds a KSAM file. The file has
two keys; the primary key starting in column 1 is 20 characters long, and
the alternate key starting in column 21 is 8 characters long. The
primary key will contain a name, the alternate a phone number.
The first step is to declare all arrays and variables needed by the
program followed by the intrinsic declaration for FOPEN. The shaded
declarations in Figure 4-5 show these required to open the file; others
are used in parts of the program not shown in this figure.
The next step is to move the necessary values to ksamparam in order to
define the key file.
The last step is to call the FOPEN intrinsic, passing any previously
defined variables or arrays by reference and passing all others by value.
DECLARATIONS FOR FOPEN. The array ksamparam is defined three different
ways: as a numeric array containing 25 words (KSAMPARAMA), as a byte
array equivalenced to the numeric array (KSAMPARAM), and as a double
array also equivalenced to the numeric array (KSAMPARAMD). These three
definitions allow the array to be addressed by word, by byte, or by
double word as required.
The variable to which the file number is returned is declared to be an
integer.
The two arrays that will contain the formal designator and device
parameter values are declared and assigned these values. In this case,
the formal designator is assigned the value JEXAMFIL. This name
identifies both the KSAM file in its entirety and the data file if
referenced separately. The device class name assigned to the device
parameter is DISC.
Finally, the intrinsic itself is declared in an INTRINSIC statement.
DEFINING KSAMPARAM. The ksamparam parameter is assigned a variety of
values that, for the sake of clarity, are assigned in separate
statements. The values assigned to ksamparam define the key file. The
statements that move values to ksamparam (refer to Figure 4-5) tell the
system everything it needs to know in order to build the key file.
The first item moved to ksamparam is the key file name, up to 8
characters enclosed in quotes. In this case, the key file name is
JKEYFILE.
Next, the size of the key file is defined in terms of the maximum number
of primary keys expected. The size is specified as a double word integer
and is assigned to the third double word in the array, specified by an
index of 2 counting from double word 0. The maximum number of primary
keys should be the same as the maximum number of records specified in the
filesize parameter of FOPEN. KSAM assigns a key file size based on this
value. If there are alternate keys, the key file size is made
proportionately larger. If the key file size is specified as zero, KSAM
uses the value of the FOPEN filesize parameter as the key file size.
The device class name is assigned in the 8 bytes starting in byte 12 that
are allocated to device description. In this case, the device class name
is DISC, the same as the device class name specified in the device
parameter of FOPEN for the data file.
____________________________________________________________________________
| |
| $CONTROL MAIN-JEXAMPL1 |
| <<*********************************************************>> |
| <<* *>> |
| <<* EXAMPLE l *>> |
| <<* BUILD A KSAM FILE *>> |
| <<* *>> |
| <<*********************************************************>> |
| ARRAY KSAMPARAMA(0:25); |
| BYTE ARRAY KSAMPARAM (*)=KSAMPARAMA; |
| DOUBLE ARRAY KSAMPARAMD(*)=KSAMPARAMA; |
| INTEGER FILNUM; |
| INTEGER ERRORCODE; |
| INTEGER LENGTH; |
| BYTE ARRAY FILENAME(0:9):="JEXAMFIL "; |
| BYTE ARRAY DEVICE(0:9):="DISC "; |
| ARRAY MESSAGE(0:35); |
| ARRAY INPUT(0:39); |
| ARRAY OUTPUT(*)=INPUT; |
| INTRINSIC FOPEN,FCLOSE,PWRITE,READ,PRINT,TERMINATE; |
| INTRINSIC FCHECK,FERRMSG; |
| <<*******************************>> |
| <<* SETUP KSAMPARAM FOR FOPEN *>> |
| <<*******************************>> |
| MOVE KSAMPARAM;="JKEYFILE"; <<THE KEY FILE NAME>> |
| KSAMPARAMD(2):=100D; <<THE MAX. # OF PRIMARY KEYS>> |
| MOVE KSAMPARAM(12):="DISC"; <<THE KEY FILE DEVICE TYPE>> |
| KSAMPARAMA(15):=&%(2)000000000000010; <<THE FLAG WORD>> |
| KSAMPARAMA(16):=2; <<PRIMARY KEY & ONE ALTERNATE>> |
| MOVE KSAMPARAMA(17):=([4/1,12/20], <<TYPE=ASCII; LENGTH=20 BYTES>> |
| 1, <<KEY LOCATION START FROM COL 1>> |
| [1/0,15/4], <<DUP NOT ALLOW; 4 KEY/BLOCK>> |
| 0); <<RESERVED>> |
| MOVE KSAMPARAMA(21):=([4/1,12/8], <<TYPE=ASCII; LENGTH=20 BYTES>> |
| 21, <<KEY LOCATION START FROM COL 21>>|
| [1/0,15/4], <<DUP NOT ALLOW; 4 KEY/BLOCK>> |
| 0); <<RESERVED>> |
| <<************************>> |
| <<* OPEN THE KSAM FILE *>> |
| <<************************>> |
| FILNJM:=FOPEN(FILENAME, <<THE DATA FILE NAME>> |
| &2)0000100000000100, <<KSAM,ASCII,NEW FILE>> |
| &%(2)0000000001000001,<<KSAM ACCESS,EXCLUSIVE,WRITE>> |
| -72, <<RECORD 72 BYTES LONG>> |
| DEVICE, <<DEVICE=DISC>> |
| KSAMPARAM, <<THIS DESCRIBES THE KEYS>> |
____________________________________________________________________________
Figure 4-5. FOPEN Example--Building a KSAM file
___________________________________________________________________________
| |
| , <<NO USERLABELS>> |
| 10, <<BLOCK 10 RECORDS>> |
| , <<NUMBUFFERS NOT USED>> |
| 100D); <<THIS FILE CAN HOLD 100 RECORD>> |
| IF FILNUM=0 |
| THEN BEGIN <<CANNOT OPEN KSAM FILE>> |
| MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; |
| PRINT(MESSAGE,-21,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>>|
| FERRMSG(ERRORCODE,MESSAGE,LENGTH); <<GET MESSAGE STRING>> |
| PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
___________________________________________________________________________
Figure 4-5. FOPEN Example--Building a KSAM file (continued)
Word 15, the flag word, is set next, It uses bits 13,14, and 15 to define
three conditions of the key file. In this example, bit 14 is the only
bit set. This means that record numbers in the file start with 1 rather
than 0 (bit 14=1), that the file is a permanent file saved in the system
directory (bit 15=0), and that records may be written to the file in
random order rather than being restricted to ascending sequence by
primary key (bit 13=0).In Figure 4-5 the flag word is specified as a
binary value for clarity; it could have been specified as octal 2 (2 or
%2) for brevity.
The right byte of the 16th word (byte 33) is set to 2 to specify that two
keys are to be used: the primary key and one alternate.
This completes the general description of the file. Its name, size,
device type, special conditions, and number of keys are now specified.
The remainder of ksamparam defines each key in 4-word entries. The first
entry always describes the primary key. Subsequent entries define up to
15 alternate keys. In this case, one primary and one alternate are
defined.
Starting in word 17, the primary key is defined as type ASCII, 20 bytes
long, its location starting in the first character of each record, and
duplicate values are not allowed. It is blocked with four keys per
block.
Starting in word 21, the altemate key is defined as type ASCII, 8 bytes
long, located starting in character 21 of the record, duplicate values
not allowed, and blocked four keys per block.
Refer to Table 4-8 for an illustration of the bit patterns used to define
the ksamparam entries.
CALLING FOPEN. When all the variables and arrays that pass values by
reference have been defined, the intrinsic FOPEN can be called. In
Figure 4-5, each parameter is shown on a separate line and documented for
clarity, but the call could also be specified as:
FILNUM:=FOPEN(FILNAME,%4004,%101,--72,DEVICE,KSAMPARAM,,10,0,100D);
This call is identical to the call in Figure 4-5 except that octal values
are used for foption and aoption.
foptions
The value of foptions is set to octal 4004, for which the bit pattern is:
Click here to view figure.
This specification defines the following file options:
New KSAM file (bit 4=1)
Allow: FILE (bit 5=0)
Fixed-Length Records (bits 8,9=00)
ASCII code (bit 13=1)
New file (bits 14,15=00)
aoptions
The value of aoptions is set to octal 101, for which the bit pattern is:
Click here to view figure.
This specification defines the following access options:
KSAM access expected (bit 3=0)
Exclusive access (bits 8,9=01)
Dynamic locking not allowed (bit 10=0)
Access type is write only (bits 12-15=0001)
OPENING AN EXISTING FILE
Once the file has been created, opening it again after it has been closed
is a simple process. The record size, device, blocking, buffersize, and
file size are all defined for the data file. Therefore, these parameters
need not be repeated. The key file has already been defined so that
ksamparam need not be specified. This leaves the first three parameters
to specify. Of these, only the formal-designator and the domain and
KSAM options of the foptions parameter are always required. The
formal-designator provides the file name in order to identify the file.
The domain option specifies where to locate the file; if domain is set to
zeros, the system expects a new file. Set the foptions KSAM option (bit
4:1) to 0 to indicate that the file is not new If the file is to be read
only, the access mode parameter, aoptions, can be omitted. For any other
type of access, aoptions should be specified.
OPENING FILE FOR READ ACCESS. The example in Figure 4-6 illustrates
opening a file for readonly access.
________________________________________________________________________________
| |
| %CONTROL MAIN=JEXAMPL2 |
| <<*********************************************************************>>|
| <<* *>>|
| <<* *>>|
| <<*********************************************************************>>|
| INTEGER FILNUM; |
| INTEGER ERRORCODE,LENGTH; |
| BYTE ARRAY FILNAME(0:9):="JEXAMFIL "; |
| ARRAY MESSAGE(0:35); |
| ARRAY INPUT(0:39); |
| ARRAY OUTPUT(*)=INPUT; |
| BYTE ARRAY KEYVALUE(0:7):="000-0000"; |
| INTEGER KEYLENGTH:=8; |
| INTEGER KEYLOCATION:=21; |
| INTEGER RELOP:=2; |
| INTRINSIC FOPEN,FCLOSE,FREAD,FFINDBYKEY,READ,PRINT, |
| FCHECK,FERRMSG,PRINT'FILE'INFO,TERMINATE; |
| <<************************>> |
| <<* OPEN THE KSAM FILE *>> |
| <<************************>> |
| FFILNUM:=OPEN(FILNAME,3); <<OPEN THE KSAM FILE>> |
| IF FILNUM=0 |
| THEN BEGIN <<CANNOT OPEN KSAM FILE>> |
| MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; |
| PRINT(MESSAGE,-21,0); |
| FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> |
| FERRMSG(ERRORCODE,MESSAGE,LENGTH); <<GET MESSAGE STRING>> |
| PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> |
| TERMINATE; |
| END; |
________________________________________________________________________________
Figure 4-6. FOPEN Example--Opening an Existing File
The file name is specified in the FILNAME array declaration as JEXAMFIL.
This is the file that was created and opened for write-only access in
Figure 4-5. It is opened for read-only access with the call:
FILNUM:=FOPEN(FILNAME,3);
The value of foptions is set to the value 3, for which the bit pattern
is:
Click here to view figure.
This specification defines the following file options:
Not a new KSAM file (bit 4=0)
Old user file (bits 14-15=11)
Because this is an existing (old) user file, other foptions settings
defined when the file was created need not be respecified. For example,
at creation the file was defined as containing ASCII code (bit 13=1). In
subsequent FOPEN calls this bit can be 0 without changing the code to
binary.
When an old user file is opened, the job file domain is searched first
and then the system file domain is searched for the file specified in the
formal designator.
The access parameter, aoptions, is not specified, but by default it
specifies the following access mode:
KSAM access expected
Share access (default for read-only)
Read-only access
OPENING FILE FOR WRITE ACCESS. To open an existing file for write
access, you use the same foptions values as you do to open the file for
read-only access. The different access mode is specified in the aoptions
parameter.
For example, assuming FILNUM and FILNAME have been declared:
FILNUM:=FOPEN(FILNAME,3,1)
The foptions specification is the same as described above. The aoptions
specification is:
Click here to view figure.
This bit pattern defines the following access options:
KSAM access expected (bit 3=0)
Exclusive access (default for all access modes except read-only) (bits
8-9=00)
Disallow dynamic locking (bit 10=0)
Write only access (bits 12-15=0001)
This opens the file for write-only access in which all previous data is
deleted. It is the access mode to use when writing to a file for the
first time. If you want to write to the end of an existing file then
bits 12-15 should equal 0010 and aoptions could be specified as 2 if
other aoptions values are defaulted. To open the file for both reading
and writing, bits 12-15 should be set to 0100, or the value 4. For
update, these bits are set to 0101, or the value 5.
OPENING KSAM FILE AS MPE FILE. You may want to open either the key file
or the data file as a standard MPE file. To do this, name the file you
want to open in the formaldesignator parameter, set foptions bit 4:1 to
1, and then set aoptions bit 3:1 to 1. These settings indicate that the
file is a KSAM file, but is to be treated as an MPE file. The remaining
parameter settings depend on what you want to do with the open file. For
example, if you want to read the key file, JKEYFILE, as an MPE file, you
call FOPEN as follows:
INTEGER FILNUM;
BYTE ARRAY FILNAME(0:9):="JKEYFILE ";
:
INTRINSIC FOPEN,...;
:
FILNUM:=FOPEN(FILNAME,%4003,%10000);
The value of foptions defines the following file options:
Specified as KSAM file (bit 4=1)
Old user file (bits 14-15=11)
The value of aoptions indicates the following:
Non-KSAM access expected (bit 3=1)
Share access (default for read only bits 8-9=00)
Read-only access (default bits 12-15=0000)
Normally, the only time you need to set bit 4 of foptions to 1 is when
you are originally creating a KSAM file. However, when you are opening
an existing KSAM file for non-KSAM access, you must set this bit to 1 so
that the system can distinguish the KSAM data or key file from an MPE
file.
OPENING FILE FOR SHARED ACCESS. When a file is opened for shared access
(aoptions bits 8,9=11), and you plan to modify the file in any way, you
must enable dynamic locking (aoptions bit 10=1). This is necessary since
you cannot call FWRITE, FUPDATE, or FREMOVE to modify a shared file
without first calling FLOCK to lock the file.
Even if you are not planning to modify the file, but only plan to read it
sequentially, you should allow dynamic locking when you open the
file. This is because FREAD (as well as FUPDATE and FREMOVE) is a
pointer-dependent procedure. Any time you call a pointer-dependent
procedure (refer to Table 4-2), you must precede it with a call to a
pointer-independent procedure that positions the pointer. It is
important to call FLOCK to lock the file before setting the pointer with
the pointer-independent procedure and leave it locked until you have
completed the sequential read or update. This insures that no other user
changes the position of the pointer between the call that positions the
pointer and the call that depends on the pointer.