HP 3000 Manuals HP 3000 Manuals
FOPEN
NM and CM callable.
Establishes access to a file and defines the physical characteristics of
the file prior to access.
Syntax
_________________________________________________________________
| |
| I16 CA U16V U16V I16V CA |
| filenum:=FOPEN(formaldesig,foption,aoption,recsize,device,|
| CA I16V I16V I16V |
| formmsg,userlabels,blockfactor,numbuffer |
| 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 interpreted
according to MPE-escaped semantics. The file name
must be terminated by a nonalphanumeric character
other than a period (.), a slash (/), a hyphen (-),
and an underscore (_).
The file referred to by formaldesig can be either
an MPE file (i.e., one that uses MPE syntax) or it
can follow HFS syntax. If formaldesig follows MPE
syntax, the file name can include password, group,
and account specifications. The file name can
backreference a file equation and optionally be
preceded by an asterisk. If formaldesig follows
HFS syntax, the file name must start with either a
dot (.) or a slash (/).
The file referred to by formaldesig may reside
either in an MPE group or in an HFS directory. For
files located in HFS directories, traverse
directory entries (TD) access is required to all
directories specified in formaldesig. If there is
no TD access, FOPEN fails and a call to FCHECK with
filenum set to 0 will return a system error code
(398) in the fserrorcode parameter.
If formaldesig is an escaped pathname:
* you cannot reference remote files
* it cannot express a name equivalent to
filename:envid
* you cannot use the device parameter
(device=node#) to specify the remote
location of a device
If formaldesig is the name of a user-defined file,
it can begin with an asterisk (*). If formaldesig
is the name of a system-defined file, it can begin
with a dollar sign ($). When creating a KSAM file,
formaldesig must be a unique file name, that is,
one not currently existing in the permanent file
directory.
The formal file designator can contain command
interpreter variables and expressions that are
evaluated before formaldesig is parsed and
validated.
As the default, FOPEN creates a nameless file 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.)
(ASC) This parameter is recommended for use with
asynchronous device files because of the
flexibility it provides.
foption 16-bit unsigned integer by value (optional)
Specifies up to eight different file
characteristics by setting corresponding bit
groupings:
NOTE For old 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
Table 4-8. (cont.)
Bits Value/Meaning
13:1 ASCII/binary
Indicates which code, ASCII or binary, a new file is
in when written to a device that supports both codes.
For disk files, this also affects padding (zeros for a
binary file, blank characters for an ASCII file) that
can occur when you issue a direct-write intrinsic call
(FWRITEDIR) to a record that lies beyond the current
logical end-of-file indicator. By default, magnetic
tape and files are treated as ASCII files. This
option is applicable only at file creation.
The following bit settings are valid:
0 Binary file
1 ASCII file
(ASC) Not valid for asynchronous device files.
Default: 0
10:3 Designator
Passes a value indicating a special file opening. Any
of the following special files can be specified with
the formaldesig parameter. For example, a file name
of $STDLIST opens standard list.
The following bit settings are valid:
000 The actual file designator is the same as the
formal file designator.
001 The actual file designator is $STDLIST.
010 The actual file designator is $NEWPASS.
011 The actual file designator is $OLDPASS.
100 The actual file designator is $STDIN.
101 The actual file designator is $STDINX.
110 The actual file designator is $NULL.
Default: 000
For example, if you pass MYFILE in the formaldesig
parameter, then using the designator option to equate
it with $STDIN is equivalent to allowing the file
equation FILE MYFILE=$STDIN.
Table 4-8. (cont.)
Bits Value/Meaning
The designator option is not equated with the
formaldesig parameter if both of the following
conditions are true:
* The disallow file equation option foption bit
(5:1) allows file equations for this file
opening.
* An explicit or implicit FILE command equating
the formal file designator to a different
actual file designator occurs in the
job/session.
A leading * in a formal file designator passed by the
formaldesig parameter overrides the disallow file
equation option setting.
8:2 Record format
Bit settings indicate internal record structure for a
file. This option is applicable only at file
creation.
The following bit settings are valid:
00 Fixed-length records. The file contains logical
records of uniform length.
Fixed-length records are supported by disk and
magnetic tape devices only.
01 Variable-length records. The file contains
logical records of varying length. This format
is restricted to records that are written in
sequential order. The size of each record is
recorded internally. The actual physical record
size is determined by multiplying the record size
(specified or default) plus one by the blocking
factor, and adding one word for the end-of-block
indicator.
This format is the only valid combination with
byte stream (1) record format extension.
For new files, this option is not allowed when
NOBUF is specified. If NOBUF is specified, then
reads/writes are performed on the entire block,
not just the record.
Variable-length records are supported by disk and
magnetic tape devices only.
Table 4-8. (cont.)
Bits Value/Meaning
10 Undefined-length records. The file contains
records of varying length that were not written
as variable-length files. By default, all files
not on disk or magnetic tape are treated as
containing undefined-length records. The file
system makes no assumption about the amount of
data that is useful. You must determine how much
data is required. For undefined-length records,
only the data supplied is written, with no
information about its length.
Undefined-length records are supported by all
devices.
Default: 00
7:1 Carriage control
Indicates whether or not a carriage control directive
is supplied in the calling sequence of each FWRITE
call that writes records onto the file. This option
is applicable only at file creation.
The following bit settings are valid:
0 No carriage-control directive is expected.
1 Carriage-control directives are expected.
Default: 0
Carriage control is supplied only for ASCII files.
This option and the ASCII/binary option (foption bit
(13:1)) are mutually exclusive, and attempts to open
new files with both binary and carriage control
directives result in an access violation.
A carriage-control character passed through the
controlcode parameter of FWRITE is acted upon for
files that have carriage-control specified in
HPFOPEN/FOPEN. Embedded control characters are treated
as data for files specified no carriage-control, and
do not invoke spacing. Spacing action can be
specified on files specified with carriage-control
either by embedding the control in the record or by
sending the control code directly through the
controlcode parameter of FWRITE.
Table 4-8. (cont.)
Bits Value/Meaning
If a carriage-control character is sent to a file
where the control cannot be executed directly (for
example, line-spacing characters sent to a disk or
tape file), the control character is embedded as the
first byte of the record. If a carriage-control
character is sent to other types of files, the control
is transmitted to the driver.
Control codes %400 through %403 are remapped to %100
through %103, so that they fit into one byte and thus
can be embedded. Records written to the line printer
with control codes %400 through %403 should contain
only control information. A record written with
control codes %400 through %403 and no data (count=0,
or embedded control and count=1) does not cause
physical I/O of any sort.
To compute record size, the file system assumes
carriage-control information to be part of the data
record. Therefore, specifying the carriage-control
option adds one byte to the record size when the file
is originally created. For example, a specification
of REC=-132,1,F,ASCII;CCTL results in a recsize of 133
bytes.
In general, the entire record can be read (the size of
which is returned in itemnum=67 of the FFILEINFO
intrinsic). However, on writes to files where
carriage-control characters are specified, the data
transferred is limited to recsize-1 unless a control
of 1 is passed, indicating that the data record is
prefixed with embedded carriage-control characters.
6:1 Labeled tape
0 No labeled tapes
1 Labeled tapes
(ASC) Not valid for asynchronous device files, but may
be set if file direction is anticipated.
Default: 0
Table 4-8. (cont.)
Bits Value/Meaning
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. If the file is old, this option is
ignored. Specifying a designator option (foption bits
(10:3)) value other than zero overrides this option.
This option is applicable only at file creation.
The following bit settings are valid:
000 Standard (STD) file
001 KSAM/3000 file
010 Relative I/O (RIO) file
011 KSAM XL file
100 Circular (CIR) file
101 NM spoolfile
110 Message (MSG) file
Default: 000
1:1 Record format extension
Byte stream record format is specified by setting the
record format, foption (8:2), to variable-length
records (01) and the record format extension, foption
(1:1), to byte stream record format (1). Zero is the
default value for this option. Using any record
format value other than variable-length records with
the record format extension results in an FSERR 49
(unimplemented function). Byte stream record format
may only be specified for standard disk files.
Specifying byte stream record format for any other
type of file result in FSERR 49 error.
Table 4-8. (cont.)
Bits Value/Meaning
1:1 cont'd Record format extension
Files created using byte stream record format are
assigned file attributes which override values
specified by FOPEN parameters. The file attributes
are as follows:
Option Description\Value
foption (13:1) ASCII/binary\ASCII (1)
foption (7:1) Carriage control\NOCCTL (0)
recsize Logical record size\1 Byte (-1)
blockfactor Blockfactor\1 Record/block
0:1 Reserved for the operating system
aoption 16-bit unsigned integer by value (optional)
Specifies up to eight different file access options
by setting corresponding bit groupings:
Bits Value/Meaning
12:4 Access type
Indicates the type of access intended for the file.
This option restricts/allows minimal use of file
system intrinsics.
The following bit settings are valid:
0000 Allows read access only, if the file's security
provisions specify read access. FWRITE, FUPDATE,
and FWRITEDIR intrinsic calls cannot reference
this file. The end-of-file (EOF) is not changed;
the record pointer starts at 0.
0001 Allows write access only, if the file's security
provisions allow write access. Any data written
in the file prior to the current FOPEN request is
deleted. FREAD, FREADSEEK, FUPDATE, and FREADDIR
intrinsic calls cannot reference this file. The
EOF is set to 0; the record pointer starts at 0.
On magnetic tape an EOF is written when the file
is closed even if no data is written.
0010 Allows write-save access only, if the file's
security provisions allow write access. Previous
data in the file is not deleted. FREAD,
FREADSEEK, FUPDATE, and FREADDIR intrinsic calls
cannot reference this file. The EOF is not
changed; the record pointer starts at 0.
Therefore, data is overwritten if a call to
FWRITE is made. The system changes this value to
append for message files.
Table 4-8. (cont.)
Bits Value/Meaning
0011 Allows append access only if the file's
security provisions allow either append or write
access. FREAD, FREADDIR, FREADSEEK, FUPDATE,
FSPACE, FPOINT, and FWRITEDIR intrinsic calls
cannot reference this file. Data written by the
FWRITE intrinsic is appended to the EOF, thereby
extending the EOF. When a file is opened for
append access, it is impossible to overwrite data
in the 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 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. Any file intrinsic except FUPDATE can
be called for this file. The EOF is not changed;
the record pointer starts at 0. 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, including FUPDATE, can be called for
this file. The EOF is not changed; the record
pointer starts at 0. 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.
1000 Reserved for the operating system.
1001 Allows directory read access. This access allows
you to open a directory and read its contents.
Attempt to open a file with this type of access
will return an error.
Table 4-8. (cont.)
Bits Value/Meaning
11:1 Multirecord
Indicates whether or not individual read or write
requests are confined to record boundaries.
The following bit settings are valid:
0 Nonmultirecord mode (NOMULTI)
1 Multirecord mode (MULTI)
Default: 0
If the number of half words or bytes to be transferred
(specified in the length parameter of the read or
write request) exceeds the size of the physical record
that is referenced, the remaining half words or bytes
are taken from subsequent successive records until the
number specified by length has been transferred. For
message (MSG) files not accessed with the copy mode
option (aoption bit (3:1)) enabled, the file system
sets this option to zero. This option is available
only if the inhibit buffering option (aoption bit
(7:1)) is set to 1.
Table 4-8. (cont.)
Bits Value/Meaning
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
The process can continue this temporary
locking/unlocking until it closes the file. 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.
Dynamic locking/unlocking is made possible through the
equivalent of a global resource identification number
(RIN) assigned to the file and temporarily acquired by
FOPEN.
Cooperating accessors that have opened a file with the
dynamic locking option enabled must access the file
using either the FLOCK and FUNLOCK intrinsics to
ensure exclusive use of the file. These accessors are
allowed concurrent access even when not using FLOCK
and FUNLOCK, but exclusiveness is not guaranteed.
Lock access is available to a process if it has lock,
execute, append, or write access to the file. This
option is ignored for files not residing on disk.
If this option is specified for a new file, the
dynamic locking bit is NOT changed to 0 as it is on
MPE V systems. When a file is new, there can be only
one accessor so setting this bit really makes no
sense. When opening a directory, dynamic locking must
be set to 0 (disallowed).
(ASC) Not valid for asynchronous device files.
Table 4-8. (cont.)
Bits Value/Meaning
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 bits (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.
For message files, specifying this value
indicates that there can be only one writer and
only one reader.
Exclusive access cannot be specified for
directories.
Table 4-8. (cont.)
Bits Value/Meaning
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 bits (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.
For message files, this value specifies there can
be multiple writers, but only one reader.
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.
For message files, this value specifies that
there can be multiple readers and multiple
writers.
Default: 00
Table 4-8. (cont.)
Bits Value/Meaning
7:1 Inhibit buffering option
Enables/disables automatic buffering by the operating
system. If NOBUF is specified, I/O is allowed
directly between the data area and the applicable
hardware device.
The following bit settings are valid:
0 Allow normal buffering (BUF)
1 Inhibit buffering (NOBUF)
Default: 0
NOBUF access is for physical block transfer; not
logical record transfer. If NOBUF is specified with
this option as well as a variable-length record
structure in record format option (foption bits (8:2))
and the file does not have a variable-length record
format, then the format is changed internally to an
undefined-length record format. Therefore, you are
responsible for buffer management. When performing an
FWRITE, the variable structure must be set up.
NOBUF access assumes responsibility for blocking and
deblocking of records in the file. To be consistent
with files built using buffered I/O, records should
begin on half word boundaries. When the information
content of the record is less than the defined record
length, pad the record with blanks if the file is
ASCII, or with zeros if the file is binary.
The record size and block size for files with NOBUF
specified follow the same rules as those files that
are created using buffering. The default blocking
factor for a file created under NOBUF is 1.
If a file is opened NOBUF without multirecord mode
specified in multirecord option (aoption bit (11:1)),
a maximum of only one block of data per read or write
can be transferred.
Table 4-8. (cont.)
Bits Value/Meaning
The end-of-file (EOF) marker, next record pointer, and
record transfer count are maintained in terms of
logical records for all files. The number of logical
records affected by each transfer is determined by the
size of the transfer.
Transfers always begin on a block boundary. Those
transfers that do not transfer whole blocks leave the
next record pointer set to the first record in the
next block. The EOF marker always points at the last
record in the file.
For files opened NOBUF, the FREADDIR, FWRITEDIR, and
FPOINT intrinsics treat the recnum parameter as a
block number.
Indicate non-RIO access to an RIO file by specifying
the file NOBUF. Use the physical block size from
FFILEINFO to determine the maximum transfer length.
For message files, the file system normally resets the
inhibit buffering option bit to zero. However, a
message file can be opened with NOBUF if the copy mode
option (aoption bit (3:1)) is set to 1; this
determines whether access to the file is
record-by-record or by block.
If you are reading a message file with the copy mode
option enabled, the inhibit buffering option has the
following meaning:
0 Read by logical record
1 Read by physical block
If writing to a message file, open it NOBUF; if the
copy mode option is enabled, access the file
block-by-block.
(ASC) Not valid for asynchronous device files.