 |
» |
|
|
|
Opens a file. Syntax | |
I16 CA U16V U16V I16V CA
filenum:=FOPEN(formaldesig,foption,aoption,recsize,device,
CA I16V
formmsg,userlabels
I32V I16V I16V I16V
filesize,numextent,initialloc,filecode); |
Functional Return | |
- filenum
16-bit signed integer (assigned functional
return) Returns a unique file number identifying the opened
file.
Parameters | |
- formaldesig
character array (optional) Passes a formal file designator, following file naming
conventions. The file name must begin with a letter and contain
alphanumeric characters, slashes, or periods. Terminate the string
by placing a delimiter in the array element following the last valid
character. The delimiter can be any nonalphanumeric character except
a slash (/), period (.), colon (:), or exclamation point (!). If the file name is the name of a user-defined file, it can
begin with an asterisk (*). If the file name is the name of a system-defined
file, it can begin with a dollar sign ($). The remote location of a device can be specified as filename:envid. The file, lockword, group, and account names are each
limited to eight characters in length. The formal file designator can contain command interpreter
variables and expressions that are evaluated before the formal file
designator is parsed and validated. Default: A nameless file is assigned that can be read or written
to, but not saved. (The domain option of a nameless file must specify
a new file unless it is a device file.) - foption
16-bit unsigned integer by value (optional) Specifies up to eight different file characteristics,
as noted below, by setting corresponding bit groupings: | | | |  | NOTE: For existing files, default conditions are specified
in the file label. Device characteristics may override some foptions. | | | | |
- Bits
Value/Meaning - 14:2
Domain Indicates which file domain is searched to locate a
file. A nameless disk file must always be a new file. A device file (such
as a tape or terminal) always resides in the system file domain
(permanent file directory). Always specify a device file as old
or permanent. The following bit settings are valid: - 00
The file is new. No search is necessary. - 01
The file is a permanent file. The system file domain (permanent
file directory) is searched. - 10
The file is a temporary file. The job file domain
(temporary file directory) is searched. - 11
The file is an old (permanent or temporary) file.
The job file domain (temporary file directory) is searched. If not found,
the system file domain is searched.
Default: 00 - 13:1
ASCII/binary Indicates which code, ASCII or binary, a new file is
in when written to a device that supports both codes. This option
is applicable only at file creation. type The following bit settings are valid: Default: 0 - 10:3
Designator The actual file designator is the same as the formal
file designator (000). This is the default and only setting allowed
for KSAM files. - 8:2
Record format Bit settings indicate internal record structure for
a file. This option is applicable only at file creation. KSAM XL/64 support fixed-length records only (00). The file
contains logical records of uniform length. - 7:1
Carriage control No carriage-control directive is expected for KSAM
files. - 5:1
Disallow file equation option Indicates whether or not to allow file equations. A
leading * in a formal file designator can override the setting
to disallow FILE. The following bit settings are valid: - 0
Allow FILE equations to override programmatic or system-defined
file specifications. - 1
Disallow FILE equations from overriding programmatic or system-defined
file specifications.
Default: 0 - 2:3
File type option Indicates internal record structure used to access
records in a file. KSAM XL files are identified by a setting of
011. KSAM64 files are identified by a setting of 111. - 0:2
Reserved for MPE/iX
- aoption
16-bit unsigned integer by value (optional) Specifies up to eight different file access options,
as noted below, by setting corresponding bit groupings: - Bits
Value/Meaning - 12:4
Access type Indicates the type of access intended for the file.
This option restricts usage of file system intrinsics. The following bit settings are valid: - 0000
Allows read access only, provided that the file's
security provisions specify read access. FWRITE, FUPDATE, and FREMOVE intrinsic calls cannot reference this file. The end-of-file
(EOF) is not changed. - 0001
Allows write access only, provided that the file's
security provisions allow write access. Any data written in the
file prior to the current FOPEN request is deleted. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. The
EOF is set to 0. - 0010
Allows write-save access only, if the file's security provisions
allow write access. Previous data in the file is not deleted.
FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. The
EOF is not changed. Therefore, data is overwritten if a call to
FWRITE is made. The system changes this value to append for
message files. - 0011
Allows append access only, if the file's security
provisions allow either append or write access. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. For
disk files, the EOF is updated after each FWRITE call. Therefore, data cannot be overwritten. - 0100
Allows read/write (I/O) access only, provided that
the file's security provisions allows both read and write access.
If both read and write access are not allowed, the access type specified
in the security provisions (either read or write) is allowed. Any
file intrinsic except FUPDATE and FREMOVE can be called for this file. The EOF is not changed.
This option is not valid for message files. - 0101
Allows update access only, if the file's security
provisions allows both read and write access. If both read and write access
are not allowed, the access type specified in the security provisions
(either read or write) is allowed. All file intrinsics can be called
for this file. The EOF is not changed. This option is not valid
for message files. - 0110
Allows execute access only, if the file's security
provisions allow execute access. This access allows read/write access to
any loaded file. The program must be running in PM to specify execute
access. This option is not valid for message files. - 0111
Allows execute/read access only, if the file's security provisions
allow execute access. This access allows only read access to any
loaded file. The program must be running in PM to specify execute/read
access. This access is changed to execute (only) access for KSAM,
CIR, and RIO files. This option is not valid for message files.
Default: 0000 - 10:1
Dynamic locking Enables/disables file locking for the file. When this
option is specified, the FLOCK and FUNLOCK intrinsics can be used to dynamically permit or
restrict concurrent access to a disk file by other processes at
specified times. The following bit settings are valid: - 0
Disallow dynamic locking/unlocking. - 1
Allow dynamic locking/unlocking.
Default: 0 If several accessors are sharing the file, they must all specify,
or not specify, this option. For example, if a file is opened with
the dynamic locking option enabled, and a subsequent accessor tries
to open the file with dynamic locking disabled, the subsequent attempt
to open fails. | | | | | NOTE: The file system does not guarantee exclusive access,
even when FLOCK and FUNLOCK are used, unless all programs that access the
file cooperate by using locking. A program that opens the file with
dynamic locking enabled will still be allowd to modify the file,
even if it never calls FLOCK. | | | | |
- 8:2
Exclusive option Indicates continuous exclusive access to this file,
from open to close. Use this option when performing a critical operation
(for example, updating the file). The following bit settings are valid: - 00
If access type option (aoption bit (12:4)) specifies read only access, then read-share
access takes effect. Otherwise, exclusive access takes effect. Regardless
of which access option was selected, FFILEINFO reports zero. - 01
Exclusive access. After the file is opened, any
additional HPFOPEN/FOPEN requests for this file are prohibited until this
process issues the FCLOSE request or terminates. If any process is already
accessing this file when an HPFOPEN/FOPEN call is issued with exclusive access specified,
an error status is returned. If another HPFOPEN/FOPEN call is issued for this file while exclusive access
is in effect, an error code is returned to the process that issued
the call. Request exclusive access only if the lock access mode
is allowed by the security provisions for the file. - 10
Read-share access (semi-exclusive access). After
the file is opened, concurrent write access to this file through another
HPFOPEN/FOPEN request is prohibited, whether issued by this
process or another process, until this process issues the
FCLOSE request or terminates. A subsequent request for
the read/write or update access type option (aoption bit (12:4)) obtains read access. However, other types
of read access are allowed. If a process already has write access
to the file when this call is issued, an error code is returned
to the calling process. If another HPFOPEN/FOPEN call that violates the read only restriction is
issued while read-share access is in effect, that call fails and
an error code is returned to the calling process. Request read-share
access only if the lock access mode is allowed by the security provisions
for the file. - 11
Share access. After the file is opened, concurrent
access to this file by any process is permitted, in any access mode, subject
to other security provisions in effect.
Default: 00 - 5:2
Multiaccess mode option. KSAM XL/64 support no multiaccess
(00). Default: 00 - 4:1
NOWAIT I/O option. KSAM XL/64 does not support NOWAIT I/O (0). Default: 0 - 3:1
Copy mode option Determines whether a file should
be treated as a standard sequential file (copy by logical record)
or physical block (copy to another file). KSAM XL/64 do not allow the copy mode option (0). Default: 0 - 0:3
Reserved for MPE/iX.
- recsize
16-bit signed integer by value (optional) Passes the size, in halfwords or bytes, of the logical
records in the file. Positive values are halfwords, negative values
are bytes. The valid range is dependent on storage and record formats: For fixed-length and undefined-length
ASCII files, the valid range is 1 to 32,767 bytes. For variable-length ASCII files and fixed-length,
variable-length, and undefined-length binary files, the range is
1 to 32,766 bytes (1 to 16,383 halfwords). All odd values specified
are rounded up to the next even value (the next halfword boundary).
Default: Device dependent. - device
character array (optional) Passes a string of ASCII characters terminating with
any nonalphanumeric character except a slash (/) or period (.), designating the device where the file is to reside. For a KSAM file, the
device must be a random access device such as a disk. Default: DISC - ksamparam
character array (optional) Contains a description of the KSAM parameters including
the primary key and up to 15 alternate keys. If a new file is being
created, this parameter must be specified. If this is an existing
file, check flag word field to see if the default values are acceptable.
In the flag word field you can set bit 13 to sequential write. For
COBOL, set flag 9. If this is not an existing file, specify this
field explicitly. (Refer to Figure 9-6 “FOPEN KSAM Parameter Format” for parameter
format.) Language ID Number This three-digit code identifies the native language to be
used for the file. To display a list of native languages that are
available on your system, enter RUN NLUTIL.PUB.SYS. If the file already exists, this field is ignored. Flag word The flag word contains a halfword defining the file characteristics. - Bits
Value/Meaning - 15:1
Reserved, do not use. Always set to 0. - 14:1
Enter 1 if record numbering is to start with 1.
Enter 0 if record numbering is to start with 0. - 13:1
Enter 1 if only sequential writing by primary key
is allowed. Enter 0 if random writing by primary key is allowed. - 12:1
Enter 1 if deleted record space can be reused. Enter
0 if deleted record space cannot be used. - 11:1
Enter 1 if a language type is specified. Enter 0
if a language type is not specified. - 10:1
Enter 1 if the primary key cannot be changed with
the FUPDATE intrinsic for files that are opened for sequential processing.
Enter 0 if the primary key can be changed with the FUPDATE intrinsic for files that are opened for sequential
processing. This enables KSAM processing of COBOL information according
to COBOL standards. - 9:1
Enter 1 if the file is programmatically accessed
by the COBOL programming language. Enter 0 if the file is not programmatically
accessed by the COBOL programming language. This enables KSAM to
process COBOL information according to COBOL standards. - 8:1
Enter 1 if selecting optimal block size. - 0:9
Enter 0. These bits are reserved and must contain
zeros.
Number of Keys In bits 8:8, enter a number between 1 and 16 specifying the
number of keys to be defined for this file. Key Definitions Each key in the file requires a 4-halfword word definition.
The first definition is always the primary key. Up to 15 alternate
keys are allowed for any KSAM file. The key definitions contain
the key type, key length, key location, duplicate key flag, and
random insert flag: Key Type Bits 0:4 specify the type of key: - Value
Meaning - 0001
Byte key (1 to 255 bytes) - 0010
Short integer key (255 bytes) - 0011
Integer key (255 bytes) - 0100
Real number key (255 bytes) - 0101
Long real number key (255 bytes) - 0110
Numeric display key (1 to 28 bytes) - 0111
Packed decimal key (1 to 14 bytes) - 1000
Signed packed decimal key (2 to 14 bytes) - 1001
IEEE floating-point decimal key (4, 8, or 16 bytes)
Key Length Bits 4:12 specify the key length. Enter the length of the
key in bytes. A maximum of 255 bytes is allowed, but the length
is dependent on the type of key data specified. Key Location Enter the relative location in bytes of the key field in the
record. Note that the first byte of the record is considered 1. Duplicate Key Flag Bits 0:1 specify the duplicate key flag. Enter 1 if duplicate
key values are allowed for this key. Enter 0 if duplicate key values
are not allowed for this key. Random Insert Flag Bits 8:1 specify the random insert flag. This field specifies
the method of inserting duplicate key values. To use this feature,
the previous duplicate key flag must be set to 1. Bits 0:8 and 9:7
are reserved and always set to 0. Enter 1 if duplicate key values are to be inserted randomly
in the duplicate key chain. Enter 0 if duplicate key values are to be inserted at the
end of the duplicate key chain. - userlabels
16-bit signed integer by value (optional) Passes the number, in the range 0 to 254, of user-label
records to be created for the file. Applicable to new disk files
only. Default: 0 - filesize
32-bit signed integer by value (optional) Passes the maximum file capacity. KSAM XL/64 require extra space for their index area. The actual
space needed is computed by the KSAM XL type manager, based on the
file size specified by the user. If the space required to build
a KSAM XL file of the user-specified size exceeds 4 gigabytes, FOPEN returns an error. For a KSAM64 file, FOPEN returns an error if the space required exceeds
128 gigabytes - numextent
16-bit signed integer by value (optional) Passes a value in the range 1 to 32 that determines
the number of extents for the file. If a value of 1 and an initialloc value of 1 is specified, the file is created as one
contiguous extent of disk space. If a value >1 is specified, a
variable number of extents (with varying extent sizes) are allocated
on a need basis. Applicable only at file creation. Default: >=1 extents - initialloc
16-bit signed integer by value (optional) Passes an integer value in the range 1 to 32 that determines
the number of extents to be allocated to the file initially. Applicable
only at file creation. Default: 0 - filecode
16-bit signed integer by value (optional) Passes a value that can be used as a file code to identify
the type of file. This code is recorded in the file label and is
accessible through the FFILEINFO intrinsic. Applicable only at file creation (except
when opening an old file that has a negative file code). If the program is running in user mode, specify a file code
in the range 0 to 32,767 to indicate the file type being created;
programs running in user mode can access files with nonnegative
file codes. If the program is running in privileged mode, specify
a file code in the range -32,768 to 32,767; programs running in
privileged mode can access files with a file code in the range -32,768
to 32,767. If an old file with a negative file code is opened, the
file code specified must match the file code in the file label. Default: 0
Table 9-6 FOPEN/HPFOPEN Parameter Equivalents | FOPEN Parameter | HPFOPEN Itemnum,Item |
|---|
| filenum (functional return) | filenum (parameter) | | formaldesig | 2,formaldesig | foption: Bits (10:3) File designator Bit (7:1) Carriage-control Bit (5:1) Disallow file equation
|
3, domain
53, ASCII/binary
5, file designator
6, record format
7, carriage-control
8, labeled tape
9, disallow file equation
10, file type
| aoption: Bit (10:1) Dynamic locking Bit (7:1) Inhibit buffering Bits (5:2) Multiaccess mode
|
11, access type
15, multirecord
12, dynamic locking
13, exclusive
46, inhibit buffering
14, multiaccess mode
16, nowait I/O
17, file copy
| | recsize | 19, record size | | device | 20, device name
22, volume class
23, volume name
24, density
25, printer environment
26, remote environment
42, device class
48, reverse VT | | formmsg | 8, labeled tape label
28, spooled message
30, labeled tape type
31, labeled tape expiration
32, labeled tape sequence
54, KSAM parms | | userlabels | 33, user labels | | blockfactor | 40, block factor | numbuffers: Bits (4:7) Spooler copies Bits (0:4) Output priority
|
44, numbuffers
34, spooler copies
27, output priority
| | filesize | 35, filesize | | numextent | 47, numextent | | initialloc | 36, initial allocation | | filecode | 37, filecode |
Operation Notes | |
Figure 9-6 “FOPEN KSAM Parameter Format” shows the format of the KSAM parameter. A file can be referenced by its formal file designator. When
executed, a unique file number is returned to the process. This
file number, rather than the formal file designator, is used in
subsequent calls to this file. Condition Codes | |
- CCE
Request granted. The file is open. - CCG
Not returned. - CCL
Request denied. For example, another process already
has exclusive or semi-exclusive access for this file, the privilege
level of this file is not user (3), or an initial allocation of
disk space cannot be made due to lack of disk space. If the file
is not opened successfully, the file number value returned by
FOPEN is 0. Call the FCHECK intrinsic for more details.
Refer to this intrinsic in the MPE/iX Intrinsics
Reference Manual for other codes pertaining to KSAM
files. |
Printable version
