MPE/iX Intrinsics Reference Manual > Chapter 7 Command Definitions (HP32208-HPLOACNMPROC)

HPFOPEN

	MPE documents
	Complete PDF
	Table of Contents
	Index

	Edition 7 E0701
	Edition 7 E0300 ♥
	Edition 6 E0195

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.

item

type varies by reference (optional)

Passes and/or returns the option indicated by the corresponding itemnum parameter.

NOTE: An itemnum takes precedence over any previously specified duplicate itemnum. Any duplicated itemnum is flagged as a warning.

Itemnum/ Mnemonic

Item Description

0

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.

2/CA

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.

3/I32

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

5/I32

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.

6/I32

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.

7/I32

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).

8/CA

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)

(ASC) Not used for asynchronous devices.

9/I32

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

10/I32

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
5: NM spoolfile
4: Circular (CIR) file
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.

11/I32

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.

12/I32

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.

13/I32

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.

14/I32

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.

15/I32

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.

16/I32

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).

17/I32

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.

Default: 0

18/I32

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.

19/I32

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).

20/CA

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.

%devname% (% is the delimiter, devname is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)

21/@64

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.

22/CA

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.

%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.

23/CA

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.

24/I32

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.

25/CA

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

%envname% (% is the delimiter, envname is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)

26/CA

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)

%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.

27/I32

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

28/CA

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

%message% (% is the delimiter, message is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)

29/I32

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

30/I32

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.

31/CA

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

%expdate% (% is the delimiter, expdate is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)

(ASC) Not used for asynchronous devices.

32/CA

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)

%position% (% is the delimiter, position is the designator)
fabcxyzf (f is the delimiter, abcxyz is the designator)

(ASC) Not used for asynchronous devices.

33/I32

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.

34/I32

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

35/I32

File size:

Passes the maximum file capacity:

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.

36/I32

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.

37/I32

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.

38/I32

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:

0: Privilege level zero (most privileged level)
1: Privilege level one
2: Privilege level two
3: Privilege level three (least privileged level)

Default: 3

39/I32

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.

40/I32

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.

41/I32

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.

42/CA

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.

%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.

43/record

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.

44/I32

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.

45/CA

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.

46/I32

Inhibit buffering:

Passes a value enabling/disabling automatic operataing system buffering. 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.

47/I32

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.

48/I32

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:

0: No reverse VT
1: Reverse VT

Default: 0

49

Reserved for the operating system

50/I32

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.

51/String

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 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.

52/String

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

%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.

53/I32

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.

54/REC

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.

55

Reserved for the operating system

56/I32

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.

57

Reserved for the operating system

58

Reserved for the operating system

59

Reserved for the operating system

60

Reserved for the operating system

61

Reserved for the operating system

64/BA

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.

65-76

Reserved for the operating system

77/I32

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.

79/I32

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.8

80/I32

Reserved for the operating system.

81/I32

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.

82-86

Reserved for MPE/iX

87/@64

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.

Related Information

Intrinsics: FOPEN
Manuals: Accessing Files Programmer's Guide
Using KSAM XL
KSAM/3000 Reference Manual

HPFMTCALENDAR

HPFPCONVERT

HPFOPEN

MPE documents

Syntax

Parameters

Operation Notes

Related Information