NM callable only.
Creates file objects and supports FIFO files.
Syntax
I32 I32 I32V *
HPFOPEN (filenum, status [,itemnum, item] [...]);
NOTE: Up to 41 itemnum/item pairs can be specified.
Parameters
filenum
32-bit signed integer by reference (required)
Returns a file descriptor for a FIFO file.
Can be used safely with all file system intrinsics that require a 16-bit
file number to be passed in the intrinsic call (for example,
FREAD, FWRITE, FCLOSE).
status
32-bit signed integer by reference (optional)
Returns the status of the HPFOPEN call. If no errors or warnings
are encountered, status returns 32-bits of zero. If
errors or warnings are encountered, status is interpreted
as two 16-bit fields:
Bits (0:16) comprise status.info. A negative value
indicates an error condition, and a positive value indicates a warning
condition. Refer to the MPE/iX Error Message Manual Volumes 1, 2 and
3 for a description of its value.
Bits (16:16) comprise.status.subsys. The value represents
the subsystem that set the status information. The subsystem identifier
for HPFOPEN is 143.
CAUTION: If an error or warning is encountered and the
status parameter was not specified, HPFOPEN causes the
calling process to abort.
itemnum
32-bit signed integer by value (optional)
Passes the item number.
NOTE: An itemnum takes precedence over any previously
specified duplicate itemnum. Any duplicated
itemnum is flagged as a warning.
item
type varies by reference (optional)
Passes and/or returns the option indicated by the corresponding
itemnum parameter.
End of option list:
There is no corresponding item. The absence of an
itemnum after the last itemnum, item pair
is equivalent to specifying this option.
Formal designator:
Passes a formal file designator that is interpreted according to
MPE-escaped semantics (unless another syntax has been chosen via item 41).
The first charater is interpreted as a delimiter, and all subsequent
characters, up to the next occurrence of the delimiter, comprise the formal
designator. The file name must be terminated by a nonalphanumeric character
other than a period (.), a slash (/), a hyphen (-), and an underscore (_).
Use of matched starting and ending name delimiters (a quoted name)
alleviates the need for a terminating character other than the quote
characters.
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,
HPFOPEN fails and a value of -180 is returned in the
status.info parameter. If you are using HPFOPEN to
create a file or hierarchical directory and you lack create directory entry
(CD) access, status.info will return a value of
-179.
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, HPFOPEN 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.)
The following are examples of valid formal file designators:
&file/lock.group.account:node.dest.level&
&filename&
&!myfile&
&!afile/![FINFO("!afile",33)]&
The following are examples of invalid formal file designators:
"filename.group (missing delimiter ("))
file.group" ('f' is used as delimiter, missing
at end)
(ASC) It is recommended that this itemnum, item pair be
used for asynchronous devices.
When you use HPFOPEN to open a file, you may use either
itemnum=2 or itemnum=51; you cannot use
both.
Domain:
Passes a value indicating which file domain the system searches to locate
the file. A nameless disk file must always be a new file.
A device file (such as a tape drive, terminal, spooled printer or
hot printer) always resides in the system file domain
(permanent file directory). Always specify a device file as old or
permanent.
The following values are valid:
0
The file is a new temporary file. It is not placed in a
directory.
1
The file is a permanent file, found in the system file
domain.
2
The file is a temporary file, found in the job file
domain.
3
The file is an old (permanent or temporary) file. The
job file domain is searched first. If the file is not found, the
system file domain is searched.
4
The file is created, placed in the permanent file
directory, and becomes a permanent file.
Hierarchical directories must be created in the permanent file domain by
specifying the create file domain (4).
Default: 0
Designator:
Passes a value indicating a special file opening. Any of the following
special files can be specified with the itemnum=2. For
example, a file name of $STDLIST opens the standard list device.
The following values are valid:
0
Allows all other options to specify the file.
1
The actual file designator is $STDLIST.
2
The actual file designator is $NEWPASS.
3
The actual file designator is $OLDPASS.
4
The actual file designator is $STDIN.
5
The actual file designator is $STDINX.
6
The actual file designator is $NULL.
Default: 0
For example, if MYFILE is passed in itemnum=2,
then using itemnum=5 and item=4 to equate
it with $STDIN is equivalent to the file equation FILE
MYFILE=$STDIN.
This option is not equated with itemnum=2 if both of the
following conditions are true:
The itemnum=9 option allows file equations for the
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
itemnum=2 overrides an itemnum=9
option.
Record format:
Passes a value indicating the internal record structure desired for the
file. This option is applicable only at file creation.
The following values are valid for records:
0
Fixed-length
1
Variable-length
2
Undefined-length (no implied structure)
9
Byte stream
10
Hierarchical directory
Default: 0
Byte stream record format may be specified only for standard disk files
(itemnum 10 equal to 0). Hierarchical directory record
format is the the default record format when creatinng a directory
(itemnum 10 equal to 9). Itemnum 10 equal
to 9 is the only record format which may be specified when creating a
directory. Hierarchical record format is only specified for the directory
file type. Record formats not implemented for the specified file type are
ignored. Byte stream and hierarchical directory record formats are
supported only on disk devices.
(ASC) This itemnum,item pair is ignored for files opened on
a terminal; records of files on terminals are of undefined length. If the
file is to be redirected to tape or disk, set the value to 0 (fixed-length).
FIFO file must be created with the byte streams (9) record format.
Carriage-control:
Passes a value indicating 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 values are valid:
0
No carriage-control directive expected
1
Carriage-control directive expected
Default: 0
Carriage-control is defined only for ASCII files. This option and
itemnum=53 are 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 control
parameter of FWRITE is recognized for files with carriage-control
specified in HPFOPEN/FOPEN. Embedded control characters are
treated as data on files where no carriage-control is specified, and
spacing is not invoked for the file. Specify spacing action on files where
carriage-control has been specified by either embedding the control in the
record, indicated with a control parameter in the call to
FWRITE, or by sending the control code directly through the
control 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. Therefore, the first byte of each record in a disk file having
carriage-control characters enabled contains control information. If
carriage-control characters are 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 can be embedded. Records written to the line
printer with control codes %400 through %403 should contain only control
information.
Records written with control codes %400 through %403 and no data (count=0,
or embedded control and count=1) does not cause physical I/O.
For computing record size, the file system considers carriage-control
information as 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.
Generally, the entire record can be read. Refer to the table listing the
item values returned by 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 one
is passed, indicating the data record is prefixed with embedded
carriage-control characters.
The value of this itemnum is ignored when a byte stream or
hierarchical directory is created. Byte stream files and hierarchical
directories are created without carriage control (NOCCTL).
Enable tape label:
Passes the tape label name of a labeled tape. The name must follow the ANSI
standards for tape label names. The name consists of <=6 printable
characters that identify the volume. In a multivolume set, only the first
tape label can be specified.
Default: a null tape label
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example:
%volid% (% is the delimiter, volid
is the designator)
fabcxyzf (f is the delimiter,
abcxyz is the designator)
Disallow file equation:
Passes a value indicating whether or not file equations are allowed. A
leading * in a formal file designator overrides the setting to
disallow file equations.
The following values 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.
File equations can be enabled for escaped pathnames expressed using
MPE-escaped name semantics or names expressed using POSIX name semantics,
but a matching file equation is not found since the file designator on the
left side of a file equation can only be expressed using MPE-only syntax.
Default: 0
File type:
Passes a value indicating the internal record structure used to access
records in the file. If the file is old, this option is ignored. Specifying
an itemnum=5 value other than zero overrides this option.
This option is applicable only at file creation.
The following values are valid:
0
Standard (STD) file
1
KSAM/3000 file
2
Relative I/O (RIO) file
3
KSAM XL file
4
Circular (CIR) file
5
NM spoolfile
6
Message (MSG) file
7
KSAM 64 file
9
Directory
Default: 0
Hierarchical directories must be created in the permanent file domain.
KSAM/3000 (1), RIO (2) and CIR (4) file types may only be created using
names belonging to the MPE name space.
(ASC) Set the value to 0 for asynchronous devices.
Access type:
Passes a value indicating the type of access intended for the file. This
option restricts/allows usage of the file system intrinsics.
The following values are valid:
0
Read access only, if the file's security provisions allow
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 zero. (Default)
1
Write access only, if the file's security provisions
allow write access. (This only applies if the file is not open with
shared access, otherwise you are given a "2" access) Any data written
in the file prior to the current HPFOPEN request is deleted.
FREAD, FREADSEEK, FUPDATE, and FREADDIR intrinsic
calls cannot reference this file. The EOF is set to zero; the record
pointer starts at zero. On magnetic tape an EOF is written to the tape
when the file is closed even if no data is written.
2
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 zero. Therefore, data is overwritten if
FWRITE is called. The system changes this value to append for
message files.
3
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. The record pointer is set to EOF prior to
each FWRITE. For disk files, the EOF is updated after each
FWRITE call. Therefore, data cannot be overwritten.
4
Read/Write (I/O) access only, if the file's security
provisions allow both read and write access. If both read and write
access are not allowed, the access type is limited to that specified in
the security provisions (either read or write). Any file intrinsic can
be issued except FUPDATE for this file. The EOF is not changed;
the record pointer starts at zero. This option is not valid for message
files.
5
Update access only, if the file's security provisions
allow both read and write access. If both read and write access are not
allowed, the access type is limited to that specified in the security
provisions (either read or write). All file intrinsics can be issued,
including FUPDATE, for this file. The EOF is not changed; the
record pointer starts at zero. This option is not valid for message
files.
6
Execute access only, if the file's security provisions
allow execute access. This allows read/write access to any loaded file.
The program must be running in privileged mode to specify execute
access. This option is not valid for message files.
7
Execute-Read access only, if the file's security
provisions allow execute access. This allows only read access to a
loaded file. The program must be running in PM to specify execute-read
access. This is changed to execute access for KSAM, CIR, and RIO files.
Not valid for message files.
8
Reserved for MPE/iX. No access, opens the file or
directory without any access checking. A process must be executing in
system code to use this access type.
9
Directory read access, opens a directory for directory
read access. Directories can only be opened for no access or directory
read access. Files cannot be opened for directory read access.
FIFO files should be opened for Read Access Only (0) or Write Access Only
(1). Other access types can cause unexpected results to occur.
Dynamic locking:
Passes a value enabling/disabling file locking for the file. When specified,
the FLOCK and FUNLOCK intrinsics can be used to
dynamically permit/restrict concurrent access to a disk file by other
processes at specified times.
The following values 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, that subsequent attempt to open fails.
Dynamic locking/unlocking is possible through the equivalent of a global
resource identification number (RIN) assigned to the file and temporarily
acquired by HPFOPEN.
Accessors that have opened a file with the dynamic locking option enabled
must access the file through the FLOCK and FUNLOCK
intrinsics to gain exclusive access to the file. Since the use of these
intrinsics is discretionary, however, all accessors must agree to use
FLOCK and FUNLOCK when writing to a file to guarantee
exclusive access. File locking is advised, but is not mandated by MPE/iX.
Lock access must be at the account, group, and file levels for
HPFOPEN to grant this option. (Lock access is available if lock,
execute, append, or write access is set at these levels.) This option is
ignored for files not residing on disk.
This itemnum may only be specified with the disallow
dynamic locking value (0) when used with directories.
(ASC) Not used for asynchronous devices.
Exclusive:
Passes a value indicating continuous exclusive access to the file, from
open to close. Use this option when performing a critical operation (for
example, updating the file).
The following values are valid:
0
If itemnum=11 specifies read only access,
read-share access takes effect. Otherwise, exclusive access takes
effect. Regardless of which access option was selected,
FFILEINFO reports zero. A zero (default) value for the
itemnum specifies that if the access type is read,
directory read, or no access (itemnum 11 equal to 0, 8,
or 9) then shared access takes effect; otherwise exclusive access takes
effect.
1
Exclusive access. After the file is opened, any
additional HPFOPEN/FOPEN requests for this file, whether
issued by this process or another process, 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 to the process. 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 that HPFOPEN/FOPEN 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 means that there can be only one reader and one writer.
Exclusive access cannot be used with directories.
2
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 itemnum=11 obtains read access.
However, other types of read access are allowed. If a process already
has write access to the file when this HPFOPEN 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. You can request
read-share access only if you are allowed the lock access mode by the
security provisions for the file. For message files, specifying this
value means that there can be multiple readers, but only one
writer.
3
Share access. After the file is opened, this permits
concurrent access to this file by any process, in any access mode,
subject to other basic security provisions in effect. For message files,
specifying this value means that there can be multiple writers and one
reader.
Default: 0
(ASC) This option is ignored for devices.
FIFO files should be opened for Share Access (3). Other exclusive accesses
to file will cause unexpected results to occur.
Multiaccess:
Passes a value indicating 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 values are valid:
0
No multiple process access allowed. A unique record
pointer is created for this access to the file. For message files, the
file system sets the multiaccess option to 2 when a zero is specified
for this option.
1
Intrajob multiprocess access 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 itemnum=14 is set
to either 1 or 2.
2
Interjob multiprocess access allowed. A record pointer is
shared with all other opened files of the same name on the system. This
is the same as specifying the GMULTI option in a FILE
command.
Default: 0
Native byte stream access (see item 77) is opened regardless of the value
of this itemnum. This itemnum is also
ignored for directories since it is not applicable.
(ASC) Not used for asynchronous devices.
Multirecord:
Passes a value indicating that individual read or write requests are not
confined to record boundaries.
The following values 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, a block) 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 itemnum=17
enabled, the file system sets this option to zero. This option is available
only if itemnum=46 is set to 1.
(ASC) This option is not used for printers.
Nowait I/O:
Allows the accessor to initiate an I/O request and to have control returned
before the completion of the I/O. This option implies the inhibit buffering
option; if NOBUF is not specified, the file system does it.
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 PM (execution level 2) to specify this option.
Set itemnum=29 to 3 if the file is to be accessed while in
user mode (execution level 3).
The following values are valid:
0
Nowait I/O not in effect
1
Nowait I/O in effect
Default: 0
Directories may not be opened using Nowait I/O (1).
Copy mode:
Passes a value that determines if any file should be treated as a standard
sequential file so it can be copied by logical record or physical block to
another file.
Byte stream files and directories are accessed using normal access (0)
regardless of the value specified for this itemnum.
The following values are valid:
0
The file is accessed as its own file type (for example, a
message file is treated as a message file).
1
The file is to be 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 is
opened with write access. This prevents incorrectly formatted data from
being written to the message file while it is unprotected. To access a
message file in copy mode, a process must have exclusive access to the
file.
(KSAM) Not allowed for KSAM XL or KSAM64 files.
Short-mapped:
Returns a short pointer to the beginning of the data area of the file. This
option maps the file into short pointer space. A short-mapped file can be 4
megabytes in length. The calling process can have up to 6 megabytes of
short-mapped files open at a time. Use the pointer as a large array of any
type to efficiently access the file.
NOTE: SHORT MAPPED files are limited to 4 MB in size per file with a
6MB/process limit. The system space that holds all SHORT MAPPED files is
limited to 1GB with some space already used by the operating system. If a large
number of files or large amount of space is needed, consider opening the files
LONG-MAPPED (item number 21) or LARGE-MAPPED (item number 87)
A file previously opened normally (not mapped) or with the long-mapped
option is not accessible with the short-mapped option. If this option is
specified with the file already opened into long pointer space, an error
results.
A loaded program file or a loaded library file is not accessible with the
short-mapped option. A file cannot be loaded that is currently opened with
the short-mapped option.
Sharing of short pointer files is provided through normal file system
sharing mechanisms, for example, use of the exclusive option. With the
short-mapped file, all file system intrinsics, applicable to the file, can
be used. FREAD and FWRITE calls can be mixed with the
short-mapped access.
Standard (STD) type disk files of fixed or undefined record length can be
accessed short-mapped with the access type option set to any value.
Standard type disk files of variable record length can be accessed
short-mapped only if the access type option is set to read-only access.
KSAM files can be accessed short-mapped only if the access type option is
set to read-only access and the copy mode option is set to 1.
Directories may not be opened using short-mapped access.
Default: No short pointer returned.
(ASC) Not used for asynchronous devices.
Record size:
Passes the size, in bytes, of the logical records in the file. Valid range
is dependent upon both storage format (ASCII or binary) and record format.
For fixed-length and undefined-length ASCII files, a record size can be
specified in the range 1..32,767. For variable-length ASCII files, and for
fixed-length, variable-length, and undefined-length binary files, a record
size can be specified in the range 1..32,766.
HPFOPEN rounds up odd values to the next highest even number
(equivalent to the nearest half word boundary) if the file is ASCII with
variable-length record format, binary with fixed-length, variable-length,
or undefined-length record format.
For example, if a record size of 105 is specified for a fixed-length binary
file, HPFOPEN sets the record size to 106; if a record size of 233
is specified for a fixed-length ASCII file, the record size remains the
same as it was when specified.
The value specified for this itemnum is ignored when a byte
stream file or hierarchical directory is created. Byte stream files are
created with a logical record size of one byte (1). Hierarchical
directories are created with a logical record size of 32 bytes (32).
Default: 256
(ASC) For terminal and printer files, no rounding up occurs if a record
size consisting of an odd number of bytes is specified. The record size can
be different from the port configuration. The default is the configured
record size (normally 40 words for terminals, 66 words for
printers).
Device name:
Passes the logical device number, in ASCII form, of a specific device. The
file is assumed to be permanent. If the device name option is specified,
the nonshareable device should be ready prior to the HPFOPEN call
(otherwise, an error results).
Only one of the following options can be in effect when a file is opened:
itemnum=20
itemnum=22
itemnum=23
itemnum=42
Default: Disk file located on the volume class DISC associated
with the group in which file resides.
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example:
%devname% (% is the delimiter,
devname is the designator)
fabcxyzf (f is the delimiter,
abcxyz is the designator)
Long-mapped:
Returns a long-pointer to the beginning of data of the file. This option
maps the file into long pointer space. A long-mapped file can be up to 4GB
-64KB or (4,294,901,760 bytes) in size. There is no limit to the number of
long-mapped files a process can have open at one time. The pointer can be
used as a large array of any type to access the file.
A loaded program file or a loaded library file is not accessible, and a
file cannot be loaded with this option.
Sharing long-pointer files is provided through normal file system file
sharing mechanisms. All file system intrinsics applicable to the file can
be used. FREAD and FWRITE calls can be mixed with this
option.
Standard (STD) disk files of fixed or undefined record length can be
accessed with this option. Standard disk files of variable record length
can be accessed only if itemnum=11 (read-only access).
Standard disk files of variable record length and KSAM files can be
accessed only if itemnum=11 (read-only access) and
itemnum=17 (set to 1).
Directories may not be opened using long-mapped access.
Default: Not returned
(ASC) Not used for asynchronous devices.
Volume class:
Passes a character array representing a volume class name where the file
space is to be restricted. This option is applicable only at file creation.
A volume class is a subset of volumes within a volume set. The volume class
name must be a valid volume class name residing on the volume set bound to
the volume (the volume set is an attribute of the group in which the file
resides).
Only one of the following options can be in effect when a file is opened
with this option:
itemnum=20
itemnum=22
itemnum=23
itemnum=42
Default: A disk file located on the volume class DISC associated
with the group in which file resides.
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example:
%volclass% (% is the delimiter,
volclass is the designator)
fabcxyzf (f is the
delimiter, abcxyz is the designator)
This itemnum may not be specified when creating
hierarchical directories.
(ASC) Not used for asynchronous devices.
Volume name:
Passes a character array representing a volume name that restricts the file
specified to a specific volume. The volume must reside within the volume
set of the group where the file resides. This option is applicable only at
file creation.
Only one of the following options can be in effect when a file is opened
with this option:
itemnum=20
itemnum=22
itemnum=23
itemnum=42
Default: A disk file located on the volume class DISC associated
with the group in which the file resides.
This itemnum may not be specified when creating
hierarchical directories.
(ASC) Not used for asynchronous devices.
Density:
Passes the tape density required when 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 this option.
Default: The highest density available on the device opened.
(ASC) Not used for asynchronous devices.
Printer environment:
Passes the name of a file that contains a printer environment. This option
is valid only for specified printer devices.
If opening an Hewlett-Packard 268x page printer file, specify an optional
printing environment 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 forms to use. If
an environment file is not specified, the file system selects a default
printer environment.
Any environment selected remains active until replaced by a new environment,
or until a call to FCLOSE (close the printer).
Default: No printer environment file specified.
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example,
%envname% (% is the delimiter,
envname is the designator)
fabcxyzf (f is the
delimiter, abcxyz is the designator)
Remote environment:
Passes the node name of the remote computer where the file is located. This
option is used when referencing a file located on a remote computer.
Default: No node name passed (local file access).
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example,
%envname% (% is the delimiter,
envname is the designator)
fabcxyzf (f is the
delimiter, abcxyz is the designator)
A remote environment cannot be specified when creating or opening files in
the HFS name space or in byte stream files.
Output priority:
Passes the output priority to be attached to the file for spooled output.
This option is applicable only to spooled devices. The output priority must
be a number between 1 (lowest priority) and 13 (highest priority),
inclusive. If the value specified is less than the current outfence set by
the system operator, file printing is deferred until the operator raises
the output priority of the file or lowers the outfence. This option can be
specified for a file already opened (for example, $STDLIST), where
the highest value supplied before the last FCLOSE takes effect.
This option is ignored for nonspooled devices.
Default: 8
Spooled message:
Passes a spooler message associated with a spoolfile. For example, a
message is passed that can be used for telling the system operator what
type of paper to use in the line printer. This message must be displayed to
the system operator and verified before the file can be printed on a line
printer. The number of characters allowed <=48; any quantity > 48
characters is truncated.
Default: No spooled message specified
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example:
%message% (% is the delimiter,
message is the designator)
fabcxyzf (f is the
delimiter, abcxyz is the designator)
Privileged access:
Passes a value that temporarily restricts access to the file number
returned from HPFOPEN to a calling process whose execution level
is equal to or less than the value specified in this option. This
restriction lasts until the file associated with the restricted file number
is closed. Do not specify a value less than the execution level of the
calling process.
The following values are valid:
0
Privilege level zero (most privileged level)
1
Privilege level one
2
Privilege level two
3
Privilege level three (least privileged level)
Default: The execution level of the calling process
Labeled tape type:
Passes a value that indicates tape label type information. This option is
valid only for labeled tapes. The following values are valid:
0
ANSI standard labels
1
IBM standard labels
Default: 0
(ASC) Not used for asynchronous devices.
Labeled tape expiration:
Passes the date of the expiration of the file or the date after which the
information in the file is no longer useful, in the format
MM/DD/YY. The file can be overwritten after this date. If the
default is specified, the file can be overwritten immediately. In a volume
set, file expiration dates must always be equal to or earlier than the date
on the previous file.
Default: No expiration date specified
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example,
%expdate% (% is the delimiter,
expdate is the designator)
fabcxyzf (f is the
delimiter, abcxyz is the designator)
Labeled tape sequence:
Passes one of the following character arrays indicating the position of the
file in relation to other files on the tape:
0
Causes a search of all volumes until the file is found.
1.. 9999
Specifies the position of the file relative to the
current file on the tape.
ADDF
Causes the tape to be positioned so as to add a new
file at the end of the volume or last volume in a multivolume set.
NEXT
Positions the tape at the next file on the tape. If
this is not the first HPFOPEN/FOPEN for the file and a rewind
occurred on the last close, then the position remains at the beginning
of the previous file.
Default: No array passed (no sequence indicated)
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example,
%position% (% is the delimiter,
position is the designator)
fabcxyzf (f is the
delimiter, abcxyz is the designator)
User labels:
Passes the number, in the range 0..254, of user-label records to be created
for the file. Applicable for new disk files only.
Default: 0
This itemnum may not be specified when creating
hierarchical directories.
(ASC) Not used for asynchronous devices.
Spooler copies:
Passes a value in the range 1..127 indicating the number of copies of the
entire file to be produced by the spooling facility. This option is
applicable to spooled devices only. This option can be specified for a file
already opened (for example, $STDLIST), where 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 becomes READY before the last copy is
complete. This option is ignored for nonspooled output devices.
Default: 1
For variable-length records, the capacity is expressed in blocks
(blockitem#=recordsize * blockfactor).
For fixed-length and undefined-length records, the capacity is
expressed in logical records.
The maximum file size for a standard byte stream file is 2
gigabytes (2,147,483,648 bytes)
The maximum file size for standard, fixed length record files and
KSAM64 files is 128 gigabyte (137,438,953,472 bytes
The maximum file size for other standard and KSAM XL files is
4,294,901,759 bytes (4 gigabytes less 64K bytes).
The maximum file size for a CM KSAM data file is 2 gigabytes and
for a CM KSAM key file, 2 gigabytes.
The maximum file size of 500 megabytes, for RIO and circular is
dependent upon both the record size and the number of extents defined
for the file:
For circular and RIO files, recsize=256 bytes
and numextent=32.
This option is applicable only at file creation.
Default: 2 gigabytes
This itemnum may not be specified when creating
hierarchical directories.
(ASC) Not used for asynchronous devices.
Initial allocation:
Passes a positive integer value indicating the number of records to be
allocated to the file initially. This option is applicable only at file
creation.
Default: 0
This itemnum may not be specified when creating
hierarchical directories.
(ASC) Not used for asynchronous devices.
File code:
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. This option is 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 positive file codes only.
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 is opened
that has a negative file code in its file label, the file code specified
must match the file code in the file label (otherwise, an error results).
File codes cannot be specified for hierarchical directories. Negative file
codes may be used only for files in MPE groups. A
status.info of -315 is returned when negative file
codes are specified for files outside MPE groups.
Default: 0
(ASC) Not used for asynchronous devices.
File privilege:
Passes a value that determines a permanent privilege level to be associated
with a newly created file. This option permanently restricts file access to
a process whose execution level is less than or equal to the specified
value. A value cannot be specified for less than the execution level of the
calling process. This option is applicable only at file creation.
The following values are valid:
Access type:
Passes a value indicating how to use the file, either sequentially or
randomly. The file system uses this information to determine the most
efficient prefetching algorithm to improve the performance of the file
access.
The following values are valid:
0
Access the file sequentially
1
Access the file randomly
Default: 0
(ASC) Not used for asynchronous devices.
Block factor:
Passes the number of logical records to be contained in one physical record
(block). This value is used to calculate the physical record size (block
size) for disk and magnetic tape files. Valid ranges are 1..32,767. This
option is applicable only at file creation.
For fixed-length records, this option specifies the actual number of
records in a block. For variable-length records, this option is interpreted
as a multiplier used to compute the block size
(record size option * block factor option).
For undefined-length records, this option is always one logical record per
block.
This itemnum may not be specified when creating
hierarchical directories.
Default: 1 for files opened NOBUF; for files opened BUF,
it is calculated by dividing the specified records into the block size
configured for the device.
(ASC) Not used for asynchronous devices.
Name syntax:
Specifies which of three name semantics will be used to interpret the
filename passed to HPFOPEN:
0
MPE-escaped semantics
1
MPE-only sematics
2
POSIX semantics
MPE-escaped name semantics is the default value for this
itemnum. The selected name semantics do not apply to file
equations specified through itemnum 52 or system-defined
file references specified through itemnum 5.
Device class:
Passes a device class where the file resides. The file system uses the
device class name to select a nonshareable device from a configured list of
available devices. The name can have a length of up to eight alphanumeric
characters, beginning with a letter (for example, TAPE). If a
device class is specified, the file is allocated to any available device in
that class.
Only one of the following options can be in effect when a file is opened:
itemnum=20
itemnum=22
itemnum=23
itemnum=42
Default: A disk file located on the volume class DISC associated
with the group in which file resides.
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example:
%devclass% (% is the delimiter,
devclass is the designator)
fabcxyzf (f is the delimiter,
abcxyz is the designator)
This itemnum may not be specified when creating
hierarchical directories. Hierarchical directories created on the system
volume set is allocated on any volume within the set. Hierarchical
directories created on non-system volume sets is allocated on the master
volume.
UFID:
Passes a unique file identifier (UFID) to provide a fast opening of an old
disk file. A UFID is a record structure, 20 bytes in length, that uniquely
identifies a disk file. Using this option avoids a directory search. Obtain
the UFID of an opened file by calling FFILEINFO. The UFID can then
be passed to HPFOPEN. The file represented by the UFID must be
accessible to the process calling HPFOPEN. (All file system
security checks are made.) New files cannot be opened with this option. If
the file to be opened by the UFID contains a lockword, use
itemnum=2 to specify the file name with the lockword.
Only files in the MPE name space may be opened by UFID. An attempt to open
a file outside the MPE name space by UFID results in a
status.info of -321 being returned. Only system
code may open a file by UFID in the POSIX name space.
Default: No UFID passed (a directory search is performed)
(ASC) Not used for asynchronous devices.
Numbuffers:
Passes the number of buffers to allocate to the file. Ignored for standard
disk files. This option is useful only for slow devices (such as tapes)
used in a buffered mode. Not applicable for files representing interactive
terminals; a system-managed buffering method is always used.
The valid range for this option is dependent upon the file type:
For standard and KSAM 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.)
This option must not specify a number of buffers whose combined size
exceeds the physical capacity of the file.
This itemnum is ignored when creating hierarchical
directories.
Default: 2
(ASC) Not used for asynchronous devices.
Fill character:
Passes two ASCII characters that determine what padding character to use at
the end of blocks or unused pages, and the padding used by
itemnum=53. Do not use delimiter characters for this option.
The fill character must be a 2 byte array. The first character only is used
as the padding character. The second character is reserved for future use.
This option is applicable only at file creation.
Default: Null characters for a binary file and ASCII blanks for an ASCII
file.
The default fill character for byte stream files is the null character. The
fill character is null for hierarchical directories regardless of the value
specified for this itemnum.
Inhibit buffering:
Passes a value enabling/disabling automatic operataing systembuffering. If
NOBUF is specified, I/O is allowed to take place directly between
the data area and the applicable hardware device.
The following values are valid:
0
Allow normal buffering (BUF)
1
Inhibit buffering (NOBUF)
Default: 0
NOBUF access is oriented to physical block transfer rather than
logical record transfer. If NOBUF and a variable-length record
structure are specified in itemnum=6 and the file does not
have a variable-length record format, then the format is changed internally
to an undefined-length record format. When performing an FWRITE,
set up the variable structure.
With NOBUF access, responsibility for blocking and deblocking of
records in the file belongs to the program. 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, you must 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 manipulated 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 one.
If a file is opened NOBUF without multirecord mode specified in
itemnum=15, then transfer a maximum of only one block of
data per read or write.
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 you have 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
itemnum=46 to zero. However, a message file can be opened
with NOBUF if itemnum=17 is set to 1; this
determines access to the file record-by-record or by block.
If writing to a message file, open it NOBUF if
itemnum=17 to access the file block-by-block.
Native byte stream access opens NOBUF (1) regardless of the value
specified for this itemnum. This itemnum is
ignored for directories since a physical block transfer interface is not
provided for directories.
(ASC) Not used for asynchronous devices.
Numextents:
Passes a value in the range 1..32 that determines the number of extents for
the file. If a value of 1 is specified, the file is created as one
contiguous extent of disk space. If a value greater than 1 is specified, a
variable number of extents (with varying extent sizes) is allocated on a
need basis. This option is applicable only at file creation.
(ASC) Not used for asynchronous devices.
Default: 1
This itemnum may not be specified when creating
hierarchical directories.
Reverse VT:
Passes a value indicating whether or not the given device name is to be
allocated on a remote machine. Specify the remote environment in the same
open request, using either the formal designator option or the remote
environment option. Reverse VT behaves nearly the same as a terminal opened
through remote file access, except that no session is required on the
remote machine.
The following values are valid:
Final disposition:
Passes a value indicating the final disposition of the file at close time
(significant only for files on disk and magnetic tape). A corresponding
parameter in a FILE command can override this option, unless file
equations are disallowed with itemnum=9.
The following values are valid:
0
No change. The disposition remains as it was before the
file was opened. If the file is new, it is deleted by FCLOSE;
otherwise, the file is assigned to the domain it belonged to previously.
An unlabeled tape file is rewound. If the file resides on a labeled
tape, the tape is rewound and unloaded.
1
Permanent file. If the file is a disk file, it is saved
in the system file domain. A new or temporary file on disk has an entry
created for it in the system (permanent) file directory. If a file of
the same name already exists in the directory, an error code is
returned at close time and the file remains open. If the file is a
permanent file on disk, this domain disposition has no effect. If the
file is stored on magnetic tape, the tape is rewound and
unloaded.
2
Temporary job file (rewound). The file is retained in
your temporary (job/session) file domain and can be requested by any
process within your job/session. If the file is a disk file, the
uniqueness of the file name is checked. If a file of the same name
already exists in the temporary file domain, an error code is returned
at close time and the file remains open. When a file resides on
unlabeled magnetic tape, the tape is rewound. However, if the file
resides on labeled magnetic tape, the tape is backspaced to the
beginning of the presently opened file.
3
Temporary job file (not rewound). This value has the same
effect as specifying final disposition option itemnum=2,
except that tape files are not rewound. In the case of unlabeled
magnetic tape, if the FCLOSE is the last done on the device
(with no other FOPEN/HPFOPEN calls outstanding), the tape is
rewound and unloaded. If the file resides on a labeled magnetic tape,
the tape is positioned to the beginning of the next file on the
tape.
4
Released file. The file is deleted from the system.
5
Convert a permanent file to a temporary file. The file is
removed from the permanent file directory and placed in the temporary
file directory. (Privileged mode capability is required to use this
option.)
Default: 0
For more information on file disposition at close time, refer to the
description of the FCLOSE intrinsic.
(ASC) Not used for asynchronous devices.
Pascal XL string:
Passes a formal file designator that follows MPE/iX file naming conventions,
using the Pascal XL STRING type format. This option is identical to
itemnum=2 except for the type of item. No delimiters are
needed.
Default: No string passed
When you use HPFOPEN to open a file, you may use either
itemnum=2 or you may use itemnum=51; you
may not use both.
As the default, the formal file designator is interpreted according to
MPE-escaped semantics. To choose another syntax, use
itemnum 41.
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,
HPFOPEN fails and a value of -180 is returned in the
status.info parameter. If you are using HPFOPEN to
create a file or hierarchical directory and you lack of create directory
entry (CD) access, status.info will return a value of
-179.
File equation string:
Passes a character string that matches the file equation specification
syntax exactly. (Refer to the FILE command in the MPE/iX
Commands Reference Manual.) This option allows the specification of
options available in the FILE command.
The formaldesig parameter and filereference
parameter can contain embedded command interpreter variables and
expressions. However, there cannot be more than 8-characters in each of
these components (filename, lockword, groupname, accountname)
including the command interpreter variable and expression characters.
Default: No string passed
A character placed in the first element designates the delimiter used by
HPFOPEN to search for the end of the character array. The
delimiter can appear again only following the last valid character of the
character array, for example:
%fileequation% (% is the delimiter,
fileequation is the designator)
fabcxyzf (f is the delimiter,
abcxyz is the designator)
The formaldesignator in the file equation string must
belong to the MPE name space. The filerefence in the file
equation string is interpreted using MPE-escaped semantics. Both the
formaldesignator and the filereference in
the file equation string may also contain embedded command interpreter
variables or expressions.
ASCII/binary:
Passes a value indicating whether ASCII or binary code is to be used for a
new file when it is written to a device that supports both codes. For disk
files, this affects padding that can occur when issuing 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 values are valid:
0
Binary file
1
ASCII file
Default: 0
(ASC) Not used for asynchronous devices.
KSAM parm:
Passes a record that defines the keys for a new KSAM file.
(KSAM XL and KSAM64) For KSAM XL and KSAM64 files, refer to the
parm parameter discussion in the Using KSAM XL.
(KSAM/3000) The record must be at least 34 bytes in size. For details,
refer to the ksamparam parameter discussion in the
KSAM/3000 Reference Manual.
Default: No record passed
(ASC) Not used for asynchronous devices.
Object class:
Passes a user object class number, in the range 0..10, that is associated
with the file.
Default: Determined by the file code for system and subsystem files, and by
the file type and record type for normal user files.
Access Control Definition:
Passes a byte array defining the access control definition (ACD) to be
attached to a new file. The byte array has a length of 1 to 279 bytes.
Unlike other HPFOPEN options that expect a delimiter at both the
beginning and the end of the byte array, this option only expects a
trailing carriage return character as a delimiter, for example,
(X:@.@;R,W:MGR.SYS;RACD:JOHN.SMITH)<cr>
Where, the <cr> is the carriage return character (13, 0x0D).
The ACD assigned to a newly created file or directory may be different from
the ACD specified as the value of this itemnum. If a
process' file mode creation mask (cmask) is initialized, it
modifies the ACD.
Data format
Allows the caller to select a different format to view the data in the file.
The current valid values for this item are:
0
Use the standard record based view of accessing the file.
This is the default value for all opens. For conventional files, the
file is record based. For directories, the standard non-privileged
directory information is returned when the HPDIRREAD intrinsic
is called. When this value is specified with a byte stream file, access
to the file is emulated to appear like a buffered variable record file.
This is the default.
1
When this value is specified, calls to HPDIRREAD
returns privileged directory information including the UFID and link ID
of the entry. Note that this value is only applicable to directory
files. This value is ignored for all other file types. In order to
specify this value, the caller must be executing in system code.
2
When this value is specified, the system attempts to let
the caller access the file as a native byte stream file. Byte stream
emulation is supported for ordinary fixed and variable length record
files as well as for files with the byte stream record type. If this
value is requested against a file type that does not support byte
stream access, an error is returned.
Specifying any value other than the values described above will result in
an error.
POSIX Non-Block Mode
Specifying this itemnum allows the caller to open a file with the POSIX
Non-Block mode. This item is useful for a subset of files (including pipes
and FIFO's) and is ignored for all other files. The behavior of the HPFOPEN
call with this option is dependent on the type of file being opened.
The current valid values for this item are:
0
This value indicates that Non-Block mode is off. This is
the default value.
1
This value indicates that Non-Block mode is on.
Specifying any value other than those described above will result in
error.
Symbolic link option:
This itemnum allows the caller to specify different options
when traversing through or opening a symbolic link. The valid values for
this itemnum are described below:
0
Follow symbolic links. This is the default value for this
option. When a symbolic link is encountered it is traversed according
to the path specified in the symbolic link.
1
Does not follow symbolic links. If the final component of
a path is a symbolic link, then no traversal is done and the symbolic
link is opened. Symbolic links that occur prior to the last component
is traversed.
Specifying any value other than those above will result in error.
Large Mapped Access:
Returns a pointer to the beginning of file data. This option can be used on
any sized file, but is the only means by which to open files larger than
4 gb -64kb (4,294,901,760 bytes) for mapped access. Large mapped access
shares the same constraints on file types as the long mapped option
(option 21).
Operation Notes
Enables creation of a new file on a shareable device and defines the physical
characteristics of that file prior to access. Enables access to existing files.
Returns a file number to the calling process that uniquely identifies the file.
Use the file number to reference the file in calls to other intrinsics.
Complete PDF
