HPFOPEN

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 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 of create directory entry (CD) access, status.info will return a value of -179.

If formaldesig is an escaped pathname:

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:

The following are examples of invalid formal file designators:

(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:

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:

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:

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:

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:

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:

(ASC) Not used for asynchronous devices.

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:

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:

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:

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:

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:

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:

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:

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:

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:

Default: 0

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.

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:

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:

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 2-gigabytes 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:

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:

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:

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,

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,

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:

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:

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:

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,

(ASC) Not used for asynchronous devices.

Labeled tape sequence:

Passes one of the following character arrays indicating the position of the file in relation to other files on the tape:

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,

(ASC) Not used for asynchronous devices.

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

File size:

Passes the maximum file capacity:

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:

Default: 3

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:

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:

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:

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:

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:

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:

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:

Default: 0

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:

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 Volumes 1 and 2 (32650-90003 and 32650-90364).) 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:

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:

Default: 0

(ASC) Not used for asynchronous devices.

KSAM parm:

Passes a record that defines the keys for a new KSAM file.

(KSAM XL) For KSAM XL files, refer to the parm parameter discussion in the Using KSAM XL (32650-90168).

(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 (30000-90079).

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,

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.

Header/Trailer:

Enable/disable standard headers/trailers:

Provides a standard way for the spooler to control the printing banners.

Valid only for the initial HPFOPEN call to the printer and prevents the header from being printed. On the last FCLOSE, the trailer is not printed.

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:

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:

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:

Specifying any value other than those above will result in error.