FOPEN

16-bit signed integer (assigned functional return)

Returns the file number that will be used to identify the opened file in subsequent intrinsic calls.

character array (optional)

Passes a string to be associated with the file as its formal file designator. The string can contain alphanumeric characters, slashes or periods, and terminates with any nonalphanumeric character except a slash (/), a colon (:), or a period (.). If the string is the name of a system defined file it will begin with a dollar sign ($). If the string is the name of a user predefined file, it can begin with an asterisk (*). You can specify the remote location of a device as filename:envid.

If you use one of the system defined files, the file can be used for either input, ($STDIN, $STDINX) or output, ($STDLIST), but not for both.

Though not required, the use of a formal file designator is recommended in programs written for asynchronous devices because of the flexibility it provides. If no formaldesignator is specified, a temporary nameless file is assigned that you can read from or write to, but not save. Note that all character arrays must start on a halfword boundary.

16-bit unsigned integer by value (optional)

You can specify various file characteristics by setting corresponding bit groupings in foptions. The correspondence is from right to left, beginning with bit 15. These characteristics are as follows, proceeding from the rightmost bit groups to the leftmost bit groups in the word. Not all of the characteristics specified in foptions have meaning for asynchronous devices, as noted in the descriptions of the individual bit settings.

Specifying foptions as zero is equivalent to not specifying foptions.

Bits (14:2)—Domain foptions.

Used to specify the file domain. If you anticipate redirection of the file to some other device, you should select a domain of 11 (Old Permanent or Temporary).

Bit (13:1)—ASCII/binary foptions.

Ignored for asynchronous devices. All files not on disk are treated as ASCII files. Use FCONTROL(27)to enable transfer of binary data. Set to 1.

Bit (10:3)—Default file designator foptions.

You should select $STDIN (100), $STDINX (101) or $STDLIST (001) for terminals, $STDLIST (001)for printers.

Bits (8:2)—Record format foption.

The format in which the records in the file are recorded. This field is ignored when a file is opened on a terminal, since records of files on terminals are always of undefined length. However, if you anticipate the need to redirect the file to tape or disk, you may want to set these bits to 00, which specifies "fixed-length".

Bit (7:1)—Carriage control foption.

Specifies whether or not you will supply a carriage control directive in the calling sequence of each FWRITE call that writes records to the file.

A carriage control character passed through the controlcode parameter of FWRITE is recognized as such and acted upon only for files that have carriage control specified in FOPEN.

A carriage control character sent to a file on which the control cannot be executed directly (for example, line spacing characters sent to a file spooled to disk), causes the control character to be embedded as the first byte of the record. Thus, the first byte of each record in such a spooled file contains control information. Carriage control characters sent to other types of files are sent to the driver and acted upon directly.

If CCTL is not specified, only single spacing will be available to this file.

Bit (6:1)—MPE/iX tape label foption.

Meaningless for asynchronous devices, but may be set if file redirection is anticipated.

Bits (5:1)—Disallow :FILE equation foption.

If this bit is set to 1, any :FILE equation intended to override the specifications set through the FOPEN call will be ignored. Note that a leading * in a formal file designator effectively overrides the disallow file equation foption.

Bits (2:3)—File type foption.

Set to 000 (standard file) for asynchronous devicefiles.

Bits (0:2)—Reserved for MPE/iX. These should be set to 0.

16-bit unsigned integer by reference (optional)

You can specify up to seven different file access options by setting corresponding bit groupings in aoptions. The correspondence is from right to left, beginning with bit 15. These access options are described below, proceeding from the rightmost bit groups to the leftmost bit groups in the word.

If aoptions are not specified, the value of all bits is assumed to be 0.

Bits (12:4)—Access type aoptions.

The type of access allowed users of the file. Table 8-10 “Access Types” summarizes how these settings apply to terminals and printers.

Bit (11:1)—Multirecord aoption.

Specifies whether or not a block of data (size specified in the tcount parameter of the read or write request) that exceeds the file's physical record size may be transmitted as several records. This option is only available for terminals. Data written to printers is not broken up on record boundaries. Instead it is written as a single long record.

Bit (10:1)—Dynamic locking aoption.

Meaningless for asynchronous devices. If specified for files not residing on disk, this option will be ignored.

Bit (8:2)—Exclusive access aoption.

Specifies whether you have continuous exclusive access to this file. This option does not apply to printers. Exclusive access is available during the first FOPEN issued against a terminal. If a session is already running on a terminal, it is not possible to issue another FOPEN with "exclusive" specified. (See the MPE/iX Intrinsics Reference Manual for more information on what each of the bit settings implies.)

Bit (7:1) —Inhibit buffering aoption.

Not meaningful for asynchronous devices. Buffering is inhibited by default. (Inhibited buffering means that your process is assigned no system buffers.) Terminals always are treated with buffering inhibited.

Bit (5:2)—Multiaccess mode aoption.

Not meaningful for asynchronous devices.

Bit (4:1)—NOWAIT I/O aoption.

Determines whether or not NOWAIT I/O is specified for the file. NOWAIT I/O allows the accessor to initiate an I/O request and to have control returned before the completion of the request. Terminal operation with NOWAIT I/O has the standard NOWAIT ramifications; that is, Privileged Mode is required, no buffering is allowed, and IOWAIT or IODONTWAIT must be called after each I/O request.

Bits (3:1)—File copy access aoption.

Specifies whether or not a file may be treated as a standard sequential file rather than as a file of its own type.

Bits (0:3)—Reserved for MPE/iX. You should set each of these bits to 0.

16-bit signed integer by value (optional)

Specifies the size of the logical records in the file. A positive number is used to represent halfwords, a negative number to represent bytes. This value indicates the maximum logical record length allowed if the records in the file are of variable length.

For terminal and printer files, no rounding up occurs if you specify a record size consisting of an odd number of bytes. The record size may be different from that configured for the port. The default value of recsize is the configured record size (normally 40 halfwords for terminals, 66 halfwords for printers).

character array (optional)

A byte array in which you can specify a particular device class or logical device number. On a terminal, you must use this parameter if you intend to read and write through a single file. (That is, if you intend to FOPEN the device once, with read and write access, you must use this parameter.) Note that all character arrays must start on a halfword boundary.

This parameter optionally specifies environment files for certain Hewlett-Packard laser printers (;ENV=printenv).

character array (optional)

Passes a forms message that you can use for such purposes as telling the System Operator what type of paper to use in the line printer. This message will be displayed on the console when the file is ready to print, and processing will be delayed until the System Operator verifies that the correct forms are in the printer and responds accordingly. The message can also be used for terminal files.

The message itself is a string of ASCII characters terminated by a period. The maximum number of characters allowed in the array is 49, including the terminating period. Arrays with more than 49 characters are truncated. Note that all character arrays must start on a halfword boundary.

This array also has significance when used for magnetic tape files. See the MPE/iX Intrinsics Reference Manual for more information on this usage.

16-bit signed integer by value (optional)

Not meaningful for asynchronous devices. Applies to disk files only.

16-bit signed integer by value (optional)

Not meaningful for asynchronous devices. Blocking factor is always 1.

16-bit signed integer by value (optional)

The number of buffers, number of copies, and output priority to be applied to the file, indicated by three bit groupings.

Bits (11:5)—Number of buffers.

Not meaningful for asynchronous devices. Data transfers to and from terminals and printers are always unbuffered.

Bits (4:7)—Number of copies.For spooled output devices only, specifies the number of copies of the entire file to be produced by the spooling facility. You can specify number of copies for a file already opened (for example, $STDLIST), in which case the highest value supplied before the last FCLOSE takes effect. The copies do not appear contiguously if the System Operator intervenes or if a file of higher output priority becomes READY before the last copy is complete. These bits are ignored for nonspooled output devices. The default value is 1.

Bits (0:4)—Output priority.

For spooled output devices only, specifies the output priority to be attached to the file. This priority is used to determine the order in which files are output when several are waiting for the same device. Accepted values are between 1 (lowest priority) and 13 (highest priority) inclusive. If this value is less than the current OUTFENCE set by the System Operator, file output is deferred until the operator raises the output priority of the file or lowers the OUTFENCE. You can specify priority for a file already opened (for example, $STDLIST), in which case the highest value supplied before the last FCLOSE takes effect. These bits are ignored for nonspooled output devices. The default priority is 8.

32-bit signed integer by value (optional)

Not meaningful for asynchronous devices.

16-bit signed integer by value (optional)

Not meaningful for asynchronous devices.

16-bit signed integer by value (optional)

Not meaningful for asynchronous devices.

16-bit signed integer by value (optional)

Not meaningful for asynchronous devices.