HPFOPEN

Opens a file, defines its physical characteristics, and sets up access to the file.

Syntax

I32 I32 I32V *

HPFOPEN(filenum,status[,itemnum,item

[,itemnum,item

.

[,itemnum,item]...]]]);

Use

The HPFOPEN intrinsic sets up access to a file and defines its characteristics and the manner in which it may be accessed. HPFOPEN provides a superset of the options provided by the FOPEN intrinsic. That is, all of the file options available through an FOPEN call are provided, along with some additional options and enhanced features. When these additions or enhancements apply to asynchronous device control, they will be noted in the parameter descriptions that follow. For a complete summary of all the additional options and features provided by HPFOPEN you should see the MPE/iX Intrinsics Reference Manual.




	NOTE: Because HPFOPEN is designed to be more flexible and extensible than the FOPEN intrinsic, HPFOPEN is the recommended intrinsic for file access.

The HPFOPEN intrinsic uses itemnum/item pairs to specify file options. The itemnum indicates the option being set, and the item specifies the desired setting. The itemnum/item optional parameters must always appear in pairs, except for Item # = 0, which can be used to end the option list. You can specify up to 41 option pairs in the same call, following the rules of precedence listed below:

An itemnum takes precedence over any previously specified duplicate itemnum. Any duplicated itemnum is flagged as a warning.
Some pairs are mutually exclusive. When applicable, these are noted in the itemnum/item summary that follows.
Each optional parameter specified in the file equation string option (Item# = 52) is treated as if it were the equivalent itemnum/item pair when determining precedence.

Parameters

filenum

32-bit signed integer by reference (required)

Returns a file number used to identify the opened file in subsequent intrinsic calls.

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. The status parameter is used in place of error checking routines that call FCHECK. Such routines are not useful with HPFOPEN.

Bits (0:16) comprise status.info. A negative value indicates an error condition, and a positive value indicates a warning condition. See the MPE/iX Intrinsics Reference Manual for a list of possible values.

Bits (16:16) comprise status.subsys. The value represented by these bits defines the subsystem that set the status information. The File System identification number is 143.




	CAUTION: Since HPFOPEN can return information on the success of its execution in the `status` parameter, it is good programming practice to specify this parameter and check its value after the intrinsic call. If an error or warning condition is encountered and you did not specify the `status` parameter, HPFOPEN causes the calling process to abort.

filenum

32-bit signed integer by value (optional)

The item number of an HPFOPEN option, as defined in the itemnum/item summary that follows.

item

type varies by reference (optional)

Passes and/or returns the HPFOPEN option indicated by the corresponding itemnum parameter, as described in the itemnum/item summary that follows.




	NOTE: All `item` parameters of type character array (CA), except for the `fill character option` (Item# = 45), must be delimited by a single character which appears only as the first and last element of the specified character array. For example: %filename% (% is the delimiter, filename is the designator) fabcxyzf (f is the delimiter, abcxyz is the designator)

Item Number, Item Summary

The following discussion lists the optional itemnum/item pairs. A short descriptive name is provided for each pair, along with a mnemonic indicating the parameter type of each item. All item parameters are passed by reference.

Item# = 0

Indicates end of the option list. This is the only itemnum that does not have a corresponding item. The absence of an itemnum after the last itemnum/item pair is equivalent to specifying this option.

Item# = 2

formaldesignator option (CA)

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

Item# = 3

domain option (I32)

Passes a value indicating the file domain. HPFOPEN assumes that all devicefiles are PERMANENT files. However, to maintain compatibility with MPE V/E, devicefiles can be opened with the domain option set to NEW, but a warning message is returned in the status parameter.

0: The file is a NEW TEMPORARY file.
1: The file is a PERMANENT file.
2: The file is a TEMPORARY file.
3: The file is an OLD PERMANENT or TEMPORARY file.
4: The file is a NEW PERMANENT file.

Item# = 5

designator option (I32)

Passes a value indicating a special file opening. Note that special files can also be specified through the formaldesignator option (Item# = 2). You should select $STDIN (4), $STDINX (5) or $STDLIST (1) for terminals, $STDLIST (1) for printers.

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.

Item# = 6

record format option (I32)

Passes a value indicating 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 this value to 0, which specifies "fixed-length".

0: Fixed-length records.
1: Variable-length records.
2: Undefined-length records (no implied record structure).

Item# = 7

Carriage Control Option (I32)

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

0: No carriage control directive is expected (NOCCTL).
1: Carriage control directives are expected (CCTL).

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.

Item# = 8

labeled tape label option (CA)

Not meaningful for asynchronous devices.

Item# = 9

Disallow file equation option (I32)

Passes a value indicating whether or not you wish to allow MPE/iX file equations. Note that a leading * in a formal file designator effectively overrides the disallow option.

0: Allow :FILE equations to override programmatic or system defined file specifications.
1: Disallow :FILE equations from overriding programmatic or system defined file specifications.

Item# = 10

file type option (I32)

Set to 0 (standard file) for asynchronous devicefiles.

0: Standard file (STD).
1: Keyed Sequential Access Method file (KSAM).
2: Relative I/O file (RIO).
4: Circular file (CIR).
6: Message file (MSG).

Item# = 11

access type option (I32)

Passes a value that specifies access restrictions for the file. See Table 8-10 “Access Types” for a summary of how the access type settings apply to terminals and printers.

0: Read access only.
1: Write access only.
2: Write access only, but previous data in file not deleted
3: Append access only.
4: Input/output access.
5: Update access.
6: Execute access.
7: Execute-Read access. (Not included in Table 8-10 “Access Types”. Returns File System Error 40 if applied to an asynchronous devicefile.)
8: Reserved for MPE/iX. No access; opens the file without any access checking. A process must be executing in system code to use this access type.

Item# = 12

dynamic locking option I32)

Not meaningful for asynchronous devices. If specified it will be ignored.

Item# = 13

exclusive option (I32)

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

0: Default.
1: Exclusive access.
2: Semi-exclusive access.
3: Shared access.

Item# = 14

multiaccess option (I32)

Not meaningful for asynchronous devices.

Item# = 15

multirecord option (I32)

Passes a value indicating whether or not a block of data 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.

0: Non-multirecord mode (NOMULTI).
1: Multirecord mode (MULTI).

Item# = 16

nowait i/o option (I32)

Passes a value that 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.

0: NOWAIT I/O not in effect.
1: NOWAIT I/O in effect.

Item# = 17

copy mode option (I32)

Passes a value that specifies whether or not a file may be treated as a standard sequential file rather than as a file of its own type.

0: File must be accessed as its own type.
1: File may be accessed as standard sequential file.

Item# = 18

short mapped option (@32)

Not meaningful for asynchronous devices.

Item# = 19

record size option (I32)

Passes the size, in bytes, of the logical records in the file. 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 is the configured record size (normally 40 words for terminals, 66 words for printers).

Item# = 20

device name option (CA)

Passes the logical device number, in ASCII form, of a specific device. The device specified should be ready prior to the HPFOPEN call or an error will result. You can obtain the logical device number through the FFILEINFO intrinsic. Note that all character arrays must start on a halfword boundary.

Only one of the following options can be in effect when a file is opened: device name option (Item# = 20), volume class option (Item# = 22), volume name option (Item# = 23), device class option (Item# = 42). The last itemnum specified takes precedence over all previously specified itemnums from this group. Any duplication is flagged as a warning.

Item# = 21

long mapped option (@64)

Not meaningful for asynchronous devices.

Item# = 22

volume class option (CA)

Not meaningful for asynchronous devices.

Item# = 23

volume name option (CA)

Not meaningful for asynchronous devices.

Item# = 24

density option (I32)

Not meaningful for asynchronous devices.

Item# = 25

printer environment option (CA)

Passes the name of a file that contains a printer environment. This option is valid only for certain printer devices. Note that all character arrays must start on a halfword boundary.

Item# = 26

remote environment option (CA)

Passes the node name of the remote computer where the file is located. This option is used when you are referencing a file located on a remote computer. Note that all character arrays must start on a halfword boundary.

Item# = 27

output priority option (I32)

Passes the output priority to be attached to the file for spooled output. 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. This parameter is ignored for nonspooled devices. The default priority is 8.

Item# = 28

spooled message option (CA)

Passes a spooler message that is associated with a spool file. For example, you can pass a 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 must be displayed to the System Operator and verified before the file can be printed on a line printer. The maximum number of characters allowed is 48. An array of more than 48 elements is truncated by MPE/iX. Note that all character arrays must start on a halfword boundary.

Item# = 29

privileged access option (I32)

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 you close the file associated with the restricted file number. You cannot specify a value less than the execution level of the calling process.

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

Item# = 30

labeled tape type option (I32)

Not meaningful for asynchronous devices.

Item# = 31

labeled tape expiration option (CA)

Not meaningful for asynchronous devices.

Item# = 32

labeled tape sequence option (CA)

Not meaningful for asynchronous devices.

Item# = 33

user labels option (I32)

Not meaningful for asynchronous devices.

Item# = 34

spooler copies option (I32)

Passes a non-negative value indicating the number of copies of the entire file to be produced by the spooling facility. This option is applicable to spooled devices only. You can specify this option 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. This option is ignored for nonspooled output devices. The default is to print 1 copy.

Item# = 35

filesize option (I32)

Not meaningful for asynchronous devices.

Item# = 36

initial allocation option (I32)

Not meaningful for asynchronous devices.

Item# = 37

filecode option (I32)

Not meaningful for asynchronous devices.

Item# = 38

file privilege option (I32)

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. You cannot specify a value less than the execution level of the calling process. This option is applicable only at file creation.

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

Item# = 39

will access option (I32)

Not meaningful for asynchronous devices.

Item# = 40

block factor option (I32)

Not meaningful for asynchronous devices.

Item# = 42

device class option (CA)

Passes a device class name which is used by the file system to select a nonsharable device from a configured list of available devices within that device class. The name can have a length of up to eight alphanumeric characters, beginning with a letter. If you specify a device class, the file is allocated to any available device in that class. Note that all character arrays must start on a halfword boundary.

Only one of the following options can be in effect when a file is opened: device name option (Item# = 20), volume class option (Item# = 22), volume name option (Item# = 23), device class option (Item# = 42). The last itemnum specified takes precedence over all previously specified itemnums from this group. Any duplication is flagged as a warning.

Item# = 43

UFID option (record)

Not meaningful for asynchronous devices.

Item# = 44

numbuffers option (I32)

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

Item# = 45

fill character option (CA)

Passes two ASCII characters that determine what padding character you wish to use at the end of blocks or unused pages. You must not use delimiter characters for this option. The fill character must be a two-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. The default is the ASCII null character. Note that all character arrays must start on a halfword boundary.

Item# = 46

inhibit buffering option (I32)

Not meaningful for asynchronous devices.

Item# = 47

numextents option (I32)

Not meaningful for asynchronous devices.

Item# = 48

reverse VT option (I32)

Passes a value that indicates whether or not the given device name is to be allocated on a remote machine. You must specify the remote environment in the same open request, using either the formaldesignator 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.

0: No reverse VT.
1: Reverse VT.

Item# = 49

Reserved for MPE/iX.

Item# = 50

final disposition option (I32)

Not meaningful for asynchronous devices.

Item# = 51

Pascal/iX string option (Pascal/iX STRING type)

Passes a formal file designator, following MPE/iX file naming conventions, but using the Pascal/iX STRING type format. This option is identical to formaldesignator option (Item# = 2) except for the type of the item. No delimiters are needed.

Item# = 52

file equation string option (CA)

Passes a character string that matches the MPE/iX file equation specification syntax exactly. This enables you to specify the options available in the :FILE command. Note that all character arrays must start on a halfword boundary.

Item# = 53

ASCII/binary option (I32)

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

0: Binary file.
1: ASCII file.

Item# = 54

KSAM parm option (REC)

Not meaningful for asynchronous devices.

Item# = 55

Reserved for MPE/iX.

Item# = 56

object class option (I32)

Passes a user object class number, in the range 0..10, that is associated with the file.

Item# = 57

Reserved for MPE/iX.

Item# = 58

Reserved for MPE/iX.

Item# = 59

Reserved for MPE/iX.

Item# = 60

Reserved for MPE/iX.

Item# = 61

Reserved for MPE/iX.

Condition Codes

The HPFOPEN intrinsic does not return meaningful condition code values. Status information is returned in the optional status parameter described above.

Additional Discussion

See the discussions of creating files and opening files in Accessing Files. See also the MPE/iX Intrinsics Reference Manual and the MPE/iX Commands Reference Manual.

HPFOPEN

Technical documentation

» Table of Contents

» Glossary

» Index

Syntax

Use

Parameters

Item Number, Item Summary

Condition Codes

Additional Discussion