Foptions and Aoptions
Terms Defined
Reserved for the operating systemDo not change these settings.
Record format extension
Byte stream record format is specified by setting the record format, foption (8:2), to variable-length records (01) and the record format extension, foption (1:1), to byte stream record format (1). Zero is the default value for this option. Using any record format value other than variable-length records with the record format extension results in an FSERR 49 (unimplemented function). Byte stream record format may only be specified for standard disk files. Specifying byte stream record format for any other type of file result in FSERR 49 error.
Record format extension
Files created using byte stream record format are assigned file attributes which override values specified by FOPEN parameters. The file attributes are as follows:
| Option | Description\Value |
|---|---|
| foption (13:1) | ASCII/binary\ASCII (1) |
| foption (7:1) | Carriage control\NOCCTL (0) |
| recsize | Logical record size\1 Byte (-1) |
| blockfactor | Blockfactor\1 Record/block |
File type option
Indicates internal record structure used to access records in a file. If the file is old, this option is ignored. Specifying a designator option (foption bits (10:3)) value other than zero overrides this option. This option is applicable only at file creation.
The following bit settings are valid:
| 000 | Standard (STD) file |
| 001 | KSAM/3000 file |
| 010 | Relative I/O (RIO) file |
| 011 | KSAM XL file |
| 100 | Circular (CIR) file |
| 101 | NM spoolfile |
| 110 | Message (MSG) file |
| 111 | KSAM64 file |
Default: 000
Disallow file equation option
Indicates whether or not to allow file equations. A leading * in a formal file designator can override the setting to disallow FILE.
The following bit settings are valid:
| 0 | Allow FILE equations to override programmatic or system-defined file specifications. |
| 1 | Disallow FILE equations from overriding programmatic or system-defined file specifications. |
Default: 0
Labeled tape
| 0 | No labeled tapes |
| 1 | Labeled tapes |
(ASC) Not valid for asynchronous device files, but may be set if file direction is anticipated.
Default: 0
Carriage control
Indicates whether or not a carriage control directive is supplied in the calling sequence of each FWRITE call that writes records onto the file. This option is applicable only at file creation.
The following bit settings are valid:
| 0 | No carriage-control directive is expected. |
| 1 | Carriage-control directives are expected. |
Default: 0
A carriage-control character passed through the controlcode parameter of FWRITE is acted upon for files that have carriage-control specified in HPFOPEN/FOPEN. Embedded control characters are treated as data for files specified no carriage-control, and do not invoke spacing. Spacing action can be specified on files specified with carriage-control either by embedding the control in the record or by sending the control code directly through the controlcode parameter of FWRITE.
Carriage control is supplied only for ASCII files. This option and the ASCII/binary option (foption bit (13:1)) are mutually exclusive, and attempts to open new files with both binary and carriage control directives result in an access violation.
If a carriage-control character is sent to a file where the control cannot be executed directly (for example, line-spacing characters sent to a disk or tape file), the control character is embedded as the first byte of the record. If a carriage-control character is sent to other types of files, the control is transmitted to the driver.
Control codes %400 through %403 are remapped to %100 through %103, so that they fit into one byte and thus can be embedded. Records written to the line printer with control codes %400 through %403 should contain only control information. A record written with control codes %400 through %403 and no data (count=0, or embedded control and count=1) does not cause physical I/O of any sort.
To compute record size, the file system assumes carriage-control information to be part of the data record. Therefore, specifying the carriage-control option adds one byte to the record size when the file is originally created. For example, a specification of REC=-132,1,F,ASCII;CCTL results in a recsize of 133 bytes.
In general, the entire record can be read (the size of which is returned in itemnum=67 of the FFILEINFO intrinsic). However, on writes to files where carriage-control characters are specified, the data transferred is limited to recsize-1 unless a control of 1 is passed, indicating that the data record is prefixed with embedded carriage-control characters.
Record format
Bit settings indicate internal record structure for a file. This option is applicable only at file creation.
The following bit settings are valid:
| 00 | Fixed-length records. The file contains logical records of uniform length. Fixed-length records are supported by disk and magnetic tape devices only. |
| 01 | Variable-length records. The file contains logical records of varying length. This format is restricted to records that are written in sequential order. The size of each record is recorded internally. The actual physical record size is determined by multiplying the record size (specified or default) plus one by the blocking factor, and adding one word for the end-of-block indicator. This format is the only valid combination with byte stream (1) record format extension. Variable-length records are supported by disk and magnetic tape devices only. |
| 10 | Undefined-length records. The file contains records of varying length that were not written as variable-length files. By default, all files not on disk or magnetic tape are treated as containing undefined-length records. The file system makes no assumption about the amount of data that is useful. You must determine how much data is required. For undefined-length records, only the data supplied is written, with no information about its length. Undefined-length records are supported by all devices. |
Default: 00
Designator
Passes a value indicating a special file opening. Any of the following special files can be specified with the formaldesig parameter. For example, a file name of $STDLIST opens standard list.
The following bit settings are valid:
| 000 | The actual file designator is the same as the formal file designator. |
| 001 | The actual file designator is $STDLIST. |
| 010 | The actual file designator is $NEWPASS. |
| 011 | The actual file designator is $OLDPASS. |
| 100 | The actual file designator is $STDIN. |
| 101 | The actual file designator is $STDINX. |
| 110 | The actual file designator is $NULL. |
Default: 000
For example, if you pass MYFILE in the formaldesig parameter, then using the designator option to equate it with $STDIN is equivalent to allowing the file equation FILE MYFILE=$STDIN.
The designator option is not equated with the formaldesig parameter if both of the following conditions are true: The disallow file equation option foption bit (5:1) allows file equations for this file opening. An explicit or implicit FILE command equating the formal file designator to a different actual file designator occurs in the job/session.
A leading * in a formal file designator passed by the formaldesig parameter overrides the disallow file equation option setting
ASCII/Binary
Indicates which code, ASCII or binary, a new file is in when written to a device that supports both codes. For disk files, this also affects padding (zeros for a binary file, blank characters for an ASCII file) that can occur when you issue a direct-write intrinsic call (FWRITEDIR) to a record that lies beyond the current logical end-of-file indicator. By default, magnetic tape and files are treated as ASCII files. This option is applicable only at file creation.
The following bit settings are valid:
| 0 | Binary file |
| 1 | ASCII file |
(ASC) Not valid for asynchronous device files.
Default: 0
File Domain
Indicates which file domain is searched to locate a file. A nameless disk file must always be a new file. A device file (such as a tape or terminal) always resides in the system file domain (permanent file directory). Always specify a device file as old or permanent.
The following bit settings are valid:
| 00 | The file is new. No search is necessary. |
| 01 | The file is a permanent file. The system file domain (permanent file directory) is searched. |
| 10 | The file is a temporary file. The job file domain (temporary file directory) is searched. |
| 11 | The file is an old (permanent or temporary) file. The job file domain (temporary file directory) is searched. If not found, the system file domain is searched. |
Default: 00
Copy mode option
Determines whether a file should be treated as a standard sequential file (copy by logical record) or physical block (copy to another file). Copy must be set to obtain EXCLUSIVE access. This causes the multiaccess bits to be set to 00.
The following values are valid:
| 0 | The file is accessed as its own file type. |
| 1 | The file is treated as a standard (STD) file, with variable-length records. For message files, this allows nondestructive reading of an old message file at either the logical record or physical-block-record level. Only block-level access is permitted if the file has message file format. This prevents incorrectly formatted data from being written to the message file while it is unprotected. |
In order to access a message file in copy mode, a process must be able to obtain EXCLUSIVE access to the file. If opening the message file for read only, the file system tries to grant exclusive access; for write only access to the message file, the EXCLUSIVE bits (8:2) in the aoptions must be set to 01.
Default: 0
Nowait I/O option
Enables/disables nowait I/O. Determines whether or not the accessor has control returned before the completion of an I/O request. The nowait I/O implies the inhibit buffering option (aoption bit (7:1)); if NOBUF is not specified, the file system does it for you and multirecord access is not available. This option is not available if the file is located on a remote computer. When opening nonmessage files, the process must be running in privileged mode to specify this option.
The following bit settings are valid:
| 0 | Nowait I/O not in effect |
| 1 | Nowait I/O in effect |
Default: 0
Nowait I/O cannot be specified for directories.
Multiaccess mode option
Indicates how the file's record pointer is to be shared. This option is useful for sharing standard input devices where there is some natural sequence of access to the file. This option permits processes located in different jobs or sessions to open the same file and share that file's record pointer.
The following bit settings are valid:
| 00 | No MULTI access. A unique record pointer is created for this access to the file. For message files, the default value of bits (5:2) is 10 for normal access, or is 00 for copy mode access. |
| 01 | Intrajob MULTI access only allowed. A record pointer is shared with all other opened files of the same name in the same job/session who opened the file with this option set to either 01 or 10. |
| 10 | Interjob MULTI access allowed. A record pointer is shared with all other opened files of the same name on the system. |
Default: 0
(ASC) Not valid for asynchronous device files.
Inhibit buffering option
Enables/disables automatic buffering by the operating system.
The following bit settings are valid:
| 0 | Allow normal buffering (BUF) |
| 1 | Inhibit buffering (NOBUF) |
Default: 0
NOBUF access is for physical block transfer; not logical record transfer.
NOBUF access assumes responsibility for blocking and deblocking of records in the file. To be consistent with files built using buffered I/O, records should begin on half word boundaries. When the information content of the record is less than the defined record length, pad the record with blanks if the file is ASCII, or with zeros if the file is binary.
The record size and block size for files with NOBUF specified follow the same rules as those files that are created using buffering. The default blocking factor for a file created under NOBUF is 1.
If a file is opened NOBUF without multirecord mode specified in multirecord option (aoption bit (11:1)), a maximum of only one block of data per read or write can be transferred.
The end-of-file (EOF) marker, next record pointer, and record transfer count are maintained in terms of logical records for all files. The number of logical records affected by each transfer is determined by the size of the transfer.
Transfers always begin on a block boundary. Those transfers that do not transfer whole blocks leave the next record pointer set to the first record in the next block. The EOF marker always points at the last record in the file.
For files opened NOBUF, the FREADDIR, FWRITEDIR, and FPOINT intrinsics treat the recnum parameter as a block number.
Indicate non-RIO access to an RIO file by specifying the file NOBUF. Use the physical block size from FFILEINFO to determine the maximum transfer length.
For message files, the file system normally resets the inhibit buffering option bit to zero. However, a message file can be opened with NOBUF if the copy mode option (aoption bit (3:1)) is set to 1; this determines whether access to the file is record-by-record or by block.
If you are reading a message file with the copy mode option enabled, the inhibit buffering option has the following meaning:
| 0 | Read by logical record |
| 1 | Read by physical block |
If writing to a message file, open it NOBUF; if the copy mode option is enabled, access the file block-by-block.
(ASC) Not valid for asynchronous device files.
Exclusive option
Indicates continuous exclusive access to this file, from open to close. Use this option when performing a critical operation (for example, updating the file). The following bit settings are valid:
| 00 | If access type option (aoption bits (12:4)) specifies read only access, then read-share access takes effect. Otherwise, exclusive access takes effect. Regardless of which access option was selected, FFILEINFO reports zero. |
| 01 | Exclusive access. After the file is opened, any additional HPFOPEN/FOPEN requests for this file are prohibited until this process issues the FCLOSE request or terminates. If any process is already accessing this file when an HPFOPEN/FOPEN call is issued with exclusive access specified, an error status is returned. If another HPFOPEN/FOPEN call is issued for this file while exclusive access is in effect, an error code is returned to the process that issued the call. Request exclusive access only if the lock access mode is allowed by the security provisions for the file.
For message files, specifying this value indicates that there can be only one writer and only one reader. Exclusive access cannot be specified for directories. |
| 10 | Read-share access (semi-exclusive access). After the file is opened, concurrent write access to this file through another HPFOPEN/FOPEN request is prohibited, whether issued by this process or another process, until this process issues the FCLOSE request or terminates. A subsequent request for the read/write or update access type option (aoption bits (12:4)) obtains read access. However, other types of read access are allowed. If a process already has write access to the file when this call is issued, an error code is returned to the calling process.
If another HPFOPEN/FOPEN call that violates the read only restriction is issued while read-share access is in effect, that call fails and an error code is returned to the calling process. Request read-share access only if the lock access mode is allowed by the security provisions for the file. For message files, this value specifies there can be multiple writers, but only one reader. |
| 11 | Share access. After the file is opened, concurrent access to this file by any process is permitted, in any access mode, subject to other security provisions in effect.
For message files, this value specifies that there can be multiple readers and multiple writers. |
Default: 00
Dynamic locking
Enables/disables file locking for the file. When this option is specified, the FLOCK and FUNLOCK intrinsics can be used to dynamically permit or restrict concurrent access to a disk file by other processes at specified times.
The following bit settings are valid:
| 0 | Disallow dynamic locking/unlocking |
| 1 | Allow dynamic locking/unlocking |
Default: 0
The process can continue this temporary locking/unlocking until it closes the file. If several accessors are sharing the file, they must all specify, or not specify, this option. For example, if a file is opened with the dynamic locking option enabled, and a subsequent accessor tries to open the file with dynamic locking disabled, the subsequent attempt to open fails.
Dynamic locking/unlocking is made possible through the equivalent of a global resource identification number (RIN) assigned to the file and temporarily acquired by FOPEN.
Cooperating accessors that have opened a file with the dynamic locking option enabled must access the file using either the FLOCK and FUNLOCK intrinsics to ensure exclusive use of the file. These accessors are allowed concurrent access even when not using FLOCK and FUNLOCK, but exclusiveness is not guaranteed.
Lock access is available to a process if it has lock, execute, append, or write access to the file. This option is ignored for files not residing on disk.
If this option is specified for a new file, the dynamic locking bit is NOT changed to 0 as it is on MPE V systems. When a file is new, there can be only one accessor so setting this bit really makes no sense. When opening a directory, dynamic locking must be set to 0 (disallowed).
(ASC) Not valid for asynchronous device files.
Multirecord
Indicates whether or not individual read or write requests are confined to record boundaries.
The following bit settings are valid:
| 0 | Nonmultirecord mode (NOMULTI) |
| 1 | Multirecord mode (MULTI) |
Default: 0
If the number of half words or bytes to be transferred (specified in the length parameter of the read or write request) exceeds the size of the physical record that is referenced, the remaining half words or bytes are taken from subsequent successive records until the number specified by length has been transferred. For message (MSG) files not accessed with the copy mode option (aoption bit (3:1)) enabled, the file system sets this option to zero. This option is available only if the inhibit buffering option (aoption bit (7:1)) is set to 1.
Access type
Indicates the type of access intended for the file. This option restricts/allows minimal use of file system intrinsics.
The following bit settings are valid:
| 0000 | Allows read access only, if the file's security provisions specify read access. FWRITE, FUPDATE, and FWRITEDIR intrinsic calls cannot reference this file. The end-of-file (EOF) is not changed; the record pointer starts at 0. |
| 0001 | Allows write access only, if the file's security provisions allow write access. (This only applies if the file is not open with shared access, otherwise you are given a "0010" access) Any data written in the file prior to the current FOPEN request is deleted. FREAD, FREADSEEK, FUPDATE, and FREADDIR intrinsic calls cannot reference this file. The EOF is set to 0; the record pointer starts at 0. On magnetic tape an EOF is written when the file is closed even if no data is written. |
| 0010 | Allows write-save access only, if the file's security provisions allow write access. Previous data in the file is not deleted. FREAD, FREADSEEK, FUPDATE, and FREADDIR intrinsic calls cannot reference this file. The EOF is not changed; the record pointer starts at 0. Therefore, data is overwritten if a call to FWRITE is made. The system changes this value to append for message files. |
| 0011 | Allows append access only if the file's security provisions allow either append or write access. FREAD, FREADDIR, FREADSEEK, FUPDATE, FSPACE, FPOINT, and FWRITEDIR intrinsic calls cannot reference this file. Data written by the FWRITE intrinsic is appended to the EOF, thereby extending the EOF. When a file is opened for append access, it is impossible to overwrite data in the file. For disk files, the EOF is updated after each FWRITE call. Therefore, data cannot be overwritten. |
| 0100 | Allows read/write (I/O) access only if the file's security provisions allows both read and write access. If both read and write access are not allowed, the access type specified in the security provisions ( read or write) is allowed. Any file intrinsic except FUPDATE can be called for this file. The EOF is not changed; the record pointer starts at 0. This option is not valid for message files. |
| 0101 | Allows update access only if the file's security provisions allows both read and write access. If both read and write access are not allowed, the access type specified in the security provisions (read or write) is allowed. All file intrinsics, including FUPDATE, can be called for this file. The EOF is not changed; the record pointer starts at 0. This option is not valid for message files. |
| 0110 | Allows execute access only if the file's security provisions allow execute access. This access allows read/write access to any loaded file. The program must be running in PM to specify execute access. This option is not valid for message files. |
| 1000 | Reserved for the operating system. |
| 1001 | Allows directory read access. This access allows you to open a directory and read its contents. Attempt to open a file with this type of access will return an error. |
Domain Disposition
Passes the disposition of the file, significant only for files on disk and magnetic tape; ignored for spooled and hot printers. (ASC) This parameter is not meaningful for asynchronous devices. This disposition can be overridden by a corresponding parameter in a FILE command entered prior to program execution.
The following bit settings are valid:
| 000 | 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 and a labeled tape is rewound and unloaded. |
| 001 | Close as a permanent file. If the file is a disk file, it is saved in the system file domain. A new or old temporary file on disk has an entry created for it in the system file directory. If a file of the same name already exists in the directory, an error code is returned 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. |
| 010 | Close as a 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 file name is checked. If a file of the same name already exists in the temporary file domain, an error code is returned and the file remains open. If a file resides on unlabeled magnetic tape, the tape is rewound. If the file resides on labeled magnetic tape, the tape is backspaced to the beginning of the opened file. |
| 011 | Close as a temporary job file (not rewound). This option has the same effect as domain disposition 010, except that tape files are not rewound. In the case of unlabeled magnetic tape, if this 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. |
| 100 | Release the file. The file is deleted from the system. |
| 101 | Makes a permanent standard disk file temporary (valid only for standard disk files with either fixed-length, variable-length, or unde ned-length record formats). The file is removed from the permanent file directory and inserted into the temporary file directory. (PM capability is required for this option.) |
Disk Space Disposition
Disk space disposition (valid only for standard disk files with either fixed-length, undefined-length, or variable-length record formats).
The following bit settings are valid:
| 00 | Does not return any disk space allocated beyond the end-of-file marker. |
| 01 | Returns any disk space allocated beyond the end-of-file (EOF) marker to the system. The EOF becomes the file limit; records cannot be added to the file beyond the EOF. |
| 10 | Returns any disk space allocated beyond the end-of-file (EOF) marker to the system. The file limit remains the same; records can be added to the file beyond EOF, up to the file limit. The disk space disposition takes effect on each FCLOSE. |
The source of these definitions is the Hewlett Packard MPE/iX Intrinsics Reference Manual; Edition 7; Part Number:32650-90875