 |
» |
|
|
|
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:
| 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.
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: (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. 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. - 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. 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 | | 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. 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.
- 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.
| | 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. | | 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. | | 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.
- 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 | | 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. 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. | | 5:2 | Multiaccess mode option | | | Indicates how the file's record pointer is to be shared. This option is useful for
sharing standard input devices where there is some natural sequence of access to
the file. This option permits processes located in different jobs or sessions to
open the same file and share that file's record pointer. The following bit settings are valid: - 00
No MULTI access. A unique record pointer is created for this
access to the file. For message files, the default value of bits (5:2) is 10 for normal access, or is
00 for copy mode access.
- 01
Intrajob MULTI access only allowed. A record pointer is
shared with all other opened files of the same name in the same
job/session who opened the file with this option set to either 01 or 10.
- 10
Interjob MULTI access allowed. A record pointer is shared
with all other opened files of the same name on the system.
Default: 0 (ASC) Not valid for asynchronous device files. | | 4:1 | Nowait I/O option | | | Enables/disables nowait I/O. Determines whether or not
the accessor has control returned before the completion of an
I/O request. The nowait I/O implies the inhibit buffering option
(aoption bit (7:1)); if NOBUF is not specified, the file
system does it for you and multirecord access is not available.
This option is not available if the file is located on a remote computer.
When opening nonmessage files, the process must be running in
privileged mode to specify this option. The following bit settings are valid: - 0
Nowait I/O not in effect - 1
Nowait I/O in effect
Default: 0 Nowait I/O cannot be specified for directories. | | 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). Copy must be set to obtain
EXCLUSIVE access. This causes the multiaccess bits to be set to 00. The
following values are valid: - 0
The file is accessed as its own file type. - 1
The file is treated as a standard (STD) file, with variable-length records. For
message files, this allows nondestructive reading of an old message file at either
the logical record or physical-block-record level. Only block-level access is permitted
if the file has message file format. This prevents incorrectly formatted data from
being written to the message file while it is unprotected. In order to access a message file in copy mode, a process must be able to obtain
EXCLUSIVE access to the file. If opening the message file for read only, the file
system tries to grant exclusive access; for write only access to the message file,
the EXCLUSIVE bits (8:2) in the aoptions must be set to 01.
Default: 0 | | 0:3 | Reserved for the operating system. |
- recsize
16-bit signed integer by value (optional) Passes the size, in half words or bytes, of the logical records in the file.
If recsize=0, the system uses the default record size, 256 bytes.
Positive values are half words; 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..32,767 bytes. For variable-length ASCII files and fixed-length, variable-length, and
undefined-length binary files, the range is 1..32,766 bytes (1..16,383
half words). All odd values specified are rounded up to the next
even value (the next half word boundary).
Default: Device dependent; refer to the Accessing Files Programmer's Guide (32650-90017) for default record
sizes.
- device
character array (optional) Passes a string of ASCII characters terminating with any nonalphanumeric
excluding a slash (/) or period (.), designating
the device where the file is to reside. This parameter
optionally specifies density for tape files (;DEN= parameter)
and/or environment files for certain Hewlett-Packard laser printers
(;ENV= parameter), a
remote environment (node#), and whether the device is to be
allocated on a remote machine (;VTERM). Remote environments (device=node#) cannot be specified for
directories, byte streams, or when the formal file designator specifies
an escaped pathname. Syntax of the options available through the device parameter are: device= [node#] [ * **vol *volclass devname devclass ] - node#
remote environment option Passes a remote node name to be accessed through remote file access
(RFA). The node name string must be followed by a pound
character (#) to delimit the string. The internal format of the
name must match that defined by the NS 3000/XL subsystem. Refer to
the NS 3000/XL User/Programmer Reference Manual (36920-90001). Default: Local file access
- *
volume set option Passing only an asterisk character (*) indicates to FOPEN that
the disk file can span all volumes in the volume set bound to the
group where the file resides. No set name is actually passed.
This option is applicable only at file creation.
- **vol
volume name option Passing a name, preceded by two asterisks (**), indicates
that the disk file is restricted to the volume whose
name is specified in vol. The specified volume must reside
within the volume set bound to the group where the file resides.
This option is applicable only at file creation.
- *volclass
volume class option Passing a name, preceded by one asterisk (*), indicates
that the disk file is restricted to the volume class whose
name is specified in volclass. The specified volume class must
reside within the volume set bound to the group where the file resides.
This option is applicable only at file creation. - devname
device name option Passes the logical device number, in ASCII format, of a specific device.
The file is assumed to be permanent. If the logical device number of
a nonshareable device is specified, the nonshareable device must
be ready prior to the FOPEN call. If the device name option is used to open a file residing on a disk,
specify the logical device number of the disk drive where a volume which
resides within the volume set bound to the group where the file resides
is mounted (applicable only at file creation).
Thereafter, the disk file is associated with that volume, not
with the originally specified logical device number.
- devclass
device class option Passes a device class name or volume class name of up to eight
alphanumeric characters beginning with an alpha character.
For example, TAPE or DISC. If devclass is specified,
the file is allocated to any available device in that class. If the device class option is used to open a file residing on a disk,
specify a device class name that corresponds to a valid and
mounted volume class name; otherwise, it is assumed that the attempt is to
open a device file not a disk file. Applicable
only at file creation. The specified volume class must reside within
the volume set bound to the group where the file resides. The file
is free to span any of the volumes that fall within the specified
volume class.
- ;DEN= density
tape density option Passes the tape density to be used while writing to a tape file.
This option is applicable only when writing to a tape on a drive
that supports more than one density. When reading from a
tape, the density of the tape overrides the density value specified. To specify density when writing to the tape file, use the
keyword ;DEN=. Default: The highest density available on the device opened
- ;ENV= printenv
printer environment option Passes the name of a file that contains a printer environment.
Valid only for specified printers. If
opening an Hewlett-Packard 268x page printer file, an optional
printing environment can be specified for the job. The printing
environment is
defined as all of the characteristics of the printed page that are
not part of the data itself, including the page size, the margin width,
the character set, the orientation (horizontal or vertical), and the
name of the forms to use. If an environment file is not specified,
the file system selects a default printer environment. To specify a printer environment, assign the
keyword ;ENV=, followed by the name of the environment file, to
the device parameter in the form ;ENV=printenv.
Any environment selected remains active until replaced by a new
environment or a call FCLOSE to close the printer. Default: No printer environment file specified - ;VTERM
reverse VT option Indicates that the specified device name is allocated on a
remote machine. Specify the remote location of a device with
the device parameter as VTERM. Specify the remote
environment in the same open request, using either
the formaldesig parameter or the remote
environment option (see node# above) of the device parameter.
Reverse VT is almost the same as a terminal opened up through
remote file access, except that no session is required on the remote
machine. Default: No reverse VT
- formmsg
character array (optional) Passes a forms message that can be used for sending messages (for
example, telling the
system operator what type of paper to use in the line printer)
The message is a
string of ASCII characters terminated by a period. The maximum
number of characters allowed is 49, including the
terminating period; more than 49 characters are truncated. Used for tape label information if bit (6:1) of
the foption parameter is set. The tape label information is
formatted as follows:
.[volid[,type[,exp[,seq]]]];
|
The period is required so that the tape label information is not
mistaken for a forms message. - volid
Volume identifier, consisting of <=6 printable characters.
In a multivolume set, specify only the first volid.
- type
Label type, identified by three alphabetic characters: ANS - ANSI standard labels (default) IBM - IBM standard labels
- exp
Month/day/year of the file expiration date or
the date when the file information is no longer valid.
The file can be overwritten after this date.
If the default is 00/00/00, the file can be overwritten
immediately. In a volume set, file expiration dates must
be equal to or earlier than the date on the previous file. - seq
Use one of the following methods to specify the position
of the file in relation to other files on the tape: A zero, which causes a search of all volumes until the file is found. An unsigned integer (1-9999), which specifies the position of the file
relative to the current file on the tape. ADDF which causes the tape to be positioned to add a new file on
the end of the volume (or last volume in a multivolume set). NEXT which positions the tape at the next file on the tape.
If this is
not the first FOPEN for the file and a rewind occurred on the last
close, then the position remains at the beginning of the previous file.
Default: NEXT (KSAM) Contains a description of 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 flagword field to see if the default
values are acceptable; if not acceptable, specify this field explicitly.
For KSAM XL files, refer to the Using KSAM XL (32650-90168) for a
complete description of this parameter. For KSAM/3000 files, refer to the KSAM/3000 Reference Manual (30000-90079) for a
complete description of this parameter. - userlabels
16-bit signed integer by value (optional) Passes the number, in the range 0..254, of user-label records to
be created for the file. Applicable to new disk files only. Default: 0 (ASC) Not valid for asynchronous device files.
- blockfactor
16-bit signed integer by value (optional) Passes the number of logical records in one physical
record (block). This value is used to calculate the physical record
size for disk and magnetic tape files. The valid range for this option
is 1..255. If a value greater than 255 is specified, FOPEN resets
the value to 255. If a value less than 1 is specified, FOPEN resets
the value to the default blockfactor setting. For fixed-length records, blockfactor specifies the actual number
of records in a block. For variable-length records, blockfactor is
interpreted as a multiplier used to compute the block size
(recsize*blockfactor). For undefined-length
records, blockfactor is always one logical record per block. Default: For files opened BUF, the default is calculated by dividing
the specified recsize into the physical record size (block size)
configured for the device. For files opened NOBUF, the default is 1. (ASC) Not valid for asynchronous device files. - numbuffer
16-bit signed integer by value (optional) Passes the number of buffers, number of copies, and output priority
indicated by setting the following bits:
| Bits | Value/Meaning |
|---|
| 11:5 | Numbuffers | | | Indicates the number of buffers to allocate to the file. The valid range
is dependent on file type: For standard files, the valid range is 1..31. For circular and RIO files, the valid range is 1..16. For message files, the valid range is 2..16 (if a 1 is specified,
the file system sets this option to 2 and no error is returned). For KSAM/3000 files, the valid range is 1..20. Not used for KSAM XL files.
This option is ignored for standard
disk files, useful only for slow devices (such as tapes) used in a
buffered mode, and is not applicable for files representing interactive
terminals. This option must not specify a number of buffers whose combined size
exceeds the physical capacity of the file. Default: 00010 (decimal 2) | | 4:7 | Spooler copies | | | Indicates the number of copies of the file to be produced by the
spooling facility. The valid range is 0...127. This option is
applicable to spooled devices only. Specify this option for a file
already opened (for example, $STDLIST), this is the highest value
supplied before the last FCLOSE takes effect. The copies do not appear
continuously if the system operator intervenes or if a file of higher
output priority is ready before the last copy is complete. Default: 0000001 (decimal 1) | | 0:4 | Output priority | | | Indicate the output priority to be attached to the file
for spooled output. Applicable only to spooled devices.
The valid range for this option is the binary equivalent of 1..13.
The output priority must be a number between 1 (lowest priority) and 13
(highest priority), inclusive. If a value less than the
current outfence set by the system operator is specified, file printing
is deferred until the operator raises the output priority of the file or
lowers the outfence. Specify this option for a file already opened
(for example, $STDLIST), the highest value supplied
before the last FCLOSE takes effect. Default: 1000 (decimal 8) |
- filesize
32-bit signed integer by value (optional) Passes the maximum file capacity. For variable-length records, the
capacity is expressed in blocks (block = recordsize * blockfactor).
For fixed-length and undefined-length records, the capacity is expressed in
logical records: The maximum file size for standard and KSAM XL files is
4,294,901,759 bytes (4 gigabytes less 64K bytes). The maximum file size for RIO, circular, and message
files is dependent upon both the record size and number of extents
defined for the file: For circular and RIO files, a maximum file size of 500 megabytes is
possible if recsize=256 bytes and numextent=32. For message files, a maximum file size of 500 megabytes is possible
if recsize=128 bytes and numextent=32.
Applicable only at file creation. Default: 1023 records (ASC) Not valid for asynchronous device files. - numextent
16-bit signed integer by value (optional) Passes a value in the range 1..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) is allocated on a need basis.
Applicable only at file creation. Default: >8 extents (ASC) Not valid for asynchronous device files.
- initialloc
16-bit signed integer by value (optional) Passes an integer value in the range 1..32 that determines the number of extents to be allocated to the file initially. Applicable only at file creation. Default: 1 (ASC) Not valid for asynchronous device files. - 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..32,767 to indicate the file type
being created; programs running in user mode can access files with
non-negative file codes. If the program is running in privileged mode,
specify a file code in the range -32,768..32,767; programs
running in privileged mode can access files with a file code in the
range -32,768..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. Negative file codes are only allowed for file in MPE groups. Default: 0 (ASC) Not valid for asynchronous device files.
Table 4-9 FOPEN/HPFOPEN Parameter Equivalents | FOPEN Parameter | HPFOPEN Itemnum,Item |
|---|
| filenum (functional return) | filenum (parameter)
| | formaldesig | 2,formaldesig | foption:
Bits (14:2) Domain
Bit (13:1) ASCII/binary
Bits (10:3) File designator
Bits (8:2) Record format
Bit (7:1) Carriage-control
Bit (6:1) Labeled tape
Bit (5:1) Disallow file equation
Bits (2:3) File type
|
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:
Bits (12:4) Access type
Bit (11:1) Multirecord
Bit (10:1) Dynamic locking
Bits (8:2) Exclusive
Bit (7:1) Inhibit buffering
Bits (5:2) Multiaccess mode
Bit (4:1) Nowait I/O
Bit (3:1) File copy
|
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 (11:5) 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 |
Condition Codes | |
- CCE (2)
Request granted. The file is open. - CCG (0)
Not returned. - CCL (1)
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.
Related Information | |
- Intrinsics
HPFOPEN - Commands
None - Manuals
Accessing Files Programmer's Guide (32650-90017), Using KSAM XL (32650-90168), and KSAM/3000 Reference Manual (30000-90079)
|
