FILE

A formal file designator in the format:

filename[.groupname[.accountname]][:nodespec]

The filename, groupname, and accountname are the identifiers that form a fully qualified file name. Each identifier may contain from one to eight alphanumeric characters, beginning with an alphabetic character. This file name may be used to identify the file in subsequent commands or intrinsic calls.

The nodespec extension of the formal file designator, explained below, is a parameter shared with the NS3000/XL AdvanceNet subsystem. It is not part of the fundamental operating system. MPE/iX accepts this extended formal file designator, with a node specification following a colon (:), in the FILE and RESET commands and in the FOPEN and HPFOPEN intrinsics.

If formaldesignator is not equated to another file designation, the parameter specifies the name of an actual file. Placing an asterisk ahead of the parameter (*formaldesignator) establishes a backreference to a formal file designator defined in a FILE command.

The backreferenced form, *formaldesignator, is valid only if it appears on the right side of the equal sign (=).

Actual file designator of a system-wide file that is always treated as an empty file. When $NULL is accessed by a program for input, that program receives only an end-of-file indication. When it is accessed by a program for output, the associated write request is accepted by MPE/iX, but no physical output is actually performed.

Do not specify parameters or options for $NULL files; if you do, you will receive an error.

The system-wide name of the temporary job file. When $NEWPASS is closed, it is referenced by the name $OLDPASS. Opening $NEWPASS destroys any previous $OLDPASS temporary file.

The system-wide name of the last temporary file that was closed as $NEWPASS.

The system-wide name of the standard job input device. A colon (:) as the first character read on this file indicates end-of-file. You will receive an error if you specify the DEV= option, VTERM parameter, or any of the option parameters or options with $STDIN; there are restrictions on the disposition parameters and options as well.

The same as $STDIN except that a colon can be read as the first character and received as data. An EOD produces an end-of-file on $STDINX.

You will receive an error if you specify the VTERM parameter or any of the option parameters or options with $STDINX; there are restrictions on the disposition parameters and options as well.

The system-wide name for the standard job or session list device. You will receive an error if you specify the VTERM parameter or any of the option parameters or options with $STDLIST; there are restrictions on the disposition parameters and options as well.

The actual file designator of the file. If the name does not begin with a dot (.) or slash (/), the name is considered to follow standard MPE file naming syntax rules. File names will be in the following format:

 filename[/lockword][.groupname[.accountname]]

Each identifier may contain from one to eight alphanumeric characters, beginning with an alphabetic character. The file name resolution is as follows:

In a batch job, the file fails to open if the file has a lockword that is not specified in filereference. In a session, MPE/iX prompts you for a lockword if one exists.

If the name begins with a dot (.) or a slash (/), the name is considered to follow the HFS file naming syntax rules:

File names are of the form

   path/filename

where the path/filename combination may have a maximum of 255 characters. The expected behavior of the path/filename resolution is as follows:

If a file has a lockword, attempts to open the file with the HFS naming syntax fail unless the file also has an ACD which defeats the lockword. It is recommended that all lockwords be removed in favor of ACDs.

An extension of the formal file reference. It may be an environment identification (specified in a previous DSLINE or REMOTE command), or it may be $BACK. It may appear in the formal file designator of the file or as an extension of an actual file reference.

The nodespec parameter does not function when used with HFS naming syntax.

If an environment identification appears in a file designation and in the DEV= option, an attempt to open the file (with the FOPEN or HPFOPEN intrinsic, for example) produces an error.

$BACK instructs MPE/iX to "hop backward" one node toward your local system to find the specified file. This works only if the FILE command is issued in a remote session. If the systems involved are connected in a local area network (LAN), one "hop backward" always means returning to your local system. The $BACK specification is the same as DEV=# without an environment name.

The domain of the file, which may be NEW, OLD, or OLDTEMP:

This may be a nodespec, logical device number, or an X.25 node name. The parameter envname may consist of as many as eight alphanumeric characters, beginning with an alphabetic character.

If you choose the DEV= option, it must be followed by at least one parameter (the parameter can be simply #). The DEV= parameter does not accept device names, volume classes, or volume names. The default device class is DISC. A previously defined environment identifier is permitted in the DEV= option, but the domain and organization qualifiers are not permitted.

The logical device class name or logical device number of a device, such as a disk, tape, printer, or a terminal. The default is DISC.

If you are opening a file that is to reside on a movable volume set, you must specify a device class that includes the drives upon which the home volume set is mounted. The file is then allocated to any of the volume set's volumes that fall within that device class.

The output priority requested for an output spool file. This may have a value of 1 (the lowest priority) to 13 (the highest).

The number of copies requested for an output spool file. The maximum number is 127.

Instructs MPE/iX to use reverse virtual terminal service instead of remote file access. Use VTERM only if the designated device is a remote terminal. Using VTERM allows a local application program to perform I/O to remote terminals located on systems that support reverse virtual terminal. Refer to Communicator 3000, Volume 2, Issue 6 (version G.02.00 of MPE V/E U-MIT).

The name of a file containing printer environment information, which controls the print output formats on the printer. Not all printers support this feature/capability to accept environment information.

This name may be an actual file designator, or it may be a formal file designator preceded by an asterisk (*).

The information in this file may contain specifications for page size, character fonts, forms, and other printer requirements to be used with the HP laser printing system. The file must be in a form suitable for downloading to the printer.

For example, to specify the environment file ACCTENV.HPENV.SYS to be used when printing, enter:

 FILE ACCTLIST;DEV=ACCTPP;ENV=ACCTENV.HPENV.SYS

For information on creating an environment file for your specific printer, refer to the documentation that came with your printer.

The ENV= parameter in a FILE command overrides the environment specified in the FOPEN or HPFOPEN intrinsic.

If the ENV= parameter is used and the *formaldesignator or filereference is omitted the parameter is ignored. Only a fully specified environment option overrides the environment option supplied by programmatic open. Any environment file specification for a subsequent FOPEN or HPFOPEN of the device file is ignored.

Any valid option for the FILE command.

Record size. A positive number indicates words; a negative number indicates bytes for new files only. For fixed-length files, this is the logical record size. For undefined length files, this is the maximum record size. For variable-length files, this is the maximum logical record size if blockfactor is 1. If not, this is used to calculate the maximum logical record size and physical record size.

For byte-stream files, recsize is assigned a length of 1 byte.

Records always begin on word boundaries. Therefore, the record size is rounded up to the nearest word boundary for block size calculations. For a binary file or a variable-length ASCII file, odd byte lengths are rounded up and the extra byte is available for data.

However, if an odd-byte-length record size is specified for a fixed or undefined length record file, the extra byte is not available for data. Default is the configured physical record width of the associated device. If you do not use the DEV= parameter, the default is DISC with 1023 records.

For example, a fixed-length ASCII file with a record size specified as 11 bytes has only 11 bytes available for data in each logical record. However, to determine actual block size, 12 bytes are used for the record size (block size = 12 bytes multiplied by the blockfactor). If the file is specified as a binary file, the 11 bytes are rounded up to 12 bytes (6 words), all of which are available for each logical record.

This is the only option parameter that applies to $STDIN, $STDINX, or $STDLIST; if you specify other option parameters for these files, FILE returns an error.

Number of logical records per physical block, for new files only. Default is calculated by dividing the specified recsize into the configured block size; this value is rounded downward to an integer that is never less than 1. For variable-length record files, blockfactor is set to 1 after using the original value along with recsize to calculate maximum logical record size and physical record size. (This does not apply to message files.) The blockfactor is ignored for undefined-length records. Maximum size is 255.

For byte-stream files, blockfactor is set to 1.

Defines the format of the records of the file. A file may contain fixed-length records (F), undefined-length records (U), variable-length records (V), or byte-stream format (B). Default is F for disk files.

Indicates the type of records. BINARY indicates binary-coded records and is the default. ASCII indicates ASCII-coded records.

Byte stream files are ASCII coded.

Corresponds to tape densities in BPI (bytes-per-inch) for new files only. This parameter is only applicable when writing to a tape mounted on the HP 7976A, HP 7978A, or HP 7980 variable-density tape drive.

The density value from a file equation takes precedence over the density specified in FOPEN or HPFOPEN. The supported densities are 800, 1600, and 6250. For details on the operation of density selection, refer to the FOPEN and HPFOPEN intrinsics in the MPE/iX Intrinsics Reference Manual (32650-90028).

Maximum number of logical records, for new files only. For fixed-length and undefined-length files, the maximum value allowed for this field is 2,147,483,647. Default is 1023.

Maximum number of disk extents. This is a value from 1 to 32.

Number of extents to be initially allocated to the file at the time it is opened. This is a value from 1 to 32. Default is 0.

Code indicating a specially formatted file. This code is recorded in the file label and is available to processes accessing the file through the FGETINFO or FLABELINFO intrinsic. For this parameter, any user can specify a positive integer ranging from 0 to 32,767 or a mnemonic name. Certain integers and mnemonics have been reserved for particular Hewlett-Packard defined meanings. Default is the unreserved file code of 0.

Creates a relative or nonrelative I/O file. RIO creates a relative I/O file. The record length parameter is implicitly changed to fixed-length record. RIO is a special file access method primarily intended for use by COBOLII programs; however, you can access these files by programs written in any language. NORIO creates a nonrelative I/O file. Default is NORIO.

RIO and NORIO specifications affect only the physical characteristics of the file. If NOBUF is specified in the FILE command, the file is accessed in non-RIO mode; otherwise, RIO access is used with RIO files. NOBUF access is provided for special operations on RIO files such as replicating a RIO file. NOBUF is not normally used by the RIO user. Refer to the MPE/iX Intrinsics Reference Manual(32650-90028) for a discussion of relative I/O.

Defines the type of file. The default is STD (standard MPE/iX disk file).

MSG (message file) allows communication between any set of processes. MSG acts like a FIFO (first in, first out) queue, where records are read from the start of the file and logically deleted and/or are appended to the end of file.

CIR (circular file) acts as normal sequential file until full. When full, the first physical block is deleted when the next record is written, and remaining blocks are logically shifted to front of file. CIR cannot be simultaneously accessed by readers and writers.

KSAMXL specifies a native mode KSAM file (KSAM XL file).

SPOOL specifies an output spool file. No spooling attributes are initialized. PRI is set to 8 and number of copies to 1. No output device is set.

This spool file will not be linked to the spool file directory (SPFDIR) and, therefore, will not be printed unless it is subsequently linked to the SPFDIR with the SPOOLF;PRINT command. At that time, the target output device must be set according to the rules of that command. Use of the SPOOL option forces the SAVE disposition, overriding any user-specified disposition.

The characteristics of a file created with the ;SPOOL keyword are:

These characteristics override any other characteristics, such as binary format, which may be specified.

The number of user label records to be created for the new file. You can specify as many as 255 labels. This parameter applies to any type of file.

Information about KSAM XL key. keyinfo is the information, ^filereference is a file containing keyinfo; the caret (^) means the contents of the file will be used.

Use the following format for keyinfo:

You must specify one keyspec for each key in the KSAM file. First, describe the primary key, followed by as many as 15 subsequent keyspecs, each describing an alternate key.

KSAM key type, specified as BYTE, INTEGER, REAL, IEEEREAL, NUMERIC PACKED, OR *PACKED. Specify with the whole word, or initial: B, I, R, E, N, P, or *. If more than one is specified, spell the word out correctly. See keysize parameter.

Location of the first byte of the KSAM key within the data record counting from the first byte in the record. The first byte in the data record is always numbered 1. Only one key can start at each location. This parameter applies only to KSAM files.

Length of the KSAM key, in bytes. This parameter is required for all key types. Different keytypes have different lengths, as described below:

These two options apply only to KSAM files. Specify the DUP option if you want duplicate key values to be permitted. If you don't specify DUP, records with duplicate key values are rejected and an error message issued when such records are written to the file. When the DUP option is used, each new duplicate key is inserted at the end of the duplicate key chain. This maintains the chronological order of duplicate.

If you specify RDUP, duplicate keys are allowed; they are inserted randomly in the duplicate key chain. This method makes insertion of such keys faster, but does not maintain the chronological order of the duplicate key chain.

The default is that duplicate keys are not allowed.

If you specify 1, record numbers in the new KSAM data file are numbered starting with 1. Otherwise, by default, record numbers start with 0. (Only 1 and 0 are acceptable.)

This option is used only for new KSAM files.

If you specify the REUSE option, KSAM files are compacted by reusing deleted record space. If you also specify the DUP option for a key, duplicate records are placed chronologically at the tail of the file, and all nonduplicate records are assigned to the first available space.

Deleted record space will not be reused with the NOREUSE option, which is the default.

Indicates whether or not carriage-control characters are specified. NOCCTL indicates that carriage-control characters are not being specified in writes to the file. CCTL indicates that carriage-control characters are being supplied in writes to the file. Default is NOCCTL.

Indicates if the sharing of files in jobs and sessions is allowed. NOMULTI prohibits sharing files in MULTI mode and is the default. MULTI allows concurrent accesses of the file and may regard the file as if no buffering is taking place. Access control information can be shared by the processes of the same CI process tree (that is parent-to-child processes) with MULTI. GMULTI is the same as MULTI except it allows accesses to be in different jobs/sessions.

Indicates if multirecord access is permitted. NOMR specifies that no multirecord access is permitted. MR allows multirecord access to the file. Default is NOMR.

Indicates if I/O requests are to be completed or queued before control returns to the program. WAIT completes I/O requests to the file before control is returned to the program. NOWAIT returns control to the program as soon as I/O requests are queued by MPE/iX; only privileged mode programs are allowed. In this way, the program does not have to wait for the physical I/O to be complete before resuming execution, and it also implies NOBUF.

Only MSG files may be opened in NOWAIT mode without privileged mode.

Defines the type of file access. IN only permits READ access to the file and is the default for all input devices. OUT only permits WRITE access to the file and is the default for output devices. UPDATE permits any type of access to the file. OUTKEEP only permits WRITE access to the file, except previous data is not deleted. APPEND only permits APPEND access to any file. INOUT only permits INPUT/OUTPUT access; any file intrinsic except FUPDATE can be issued against the file.

Specifies whether buffers are to be allocated to the file. The numbuffers parameter is the number of buffers (1 to 16) to be allocated for the file. The numbuffers parameter is ignored for terminals. The default is BUF=2 buffers. NOBUF specifies that no buffers are allocated for the file. This parameter has no meaning for NM files.

Indicates if dynamic locking and unlocking is to be permitted. NOLOCK prohibits dynamic locking/unlocking of file through the FLOCK and FUNLOCK intrinsics. LOCK allows dynamic locking and unlocking through FLOCK and FUNLOCK intrinsics. Default is NOLOCK.

Indicates if files can be copied. COPY allows MSG, KSAM, CIR, and SPOOL files to be either copied (logical data record read) or replicated (block read and write completely duplicating file) to another file. NOCOPY accesses the file in its natural mode, that is, as a MSG file. Default is NOCOPY.

A message to the operator requesting that certain forms be mounted. The message must be displayed and verified before the output data can be printed on a line printer. The message is a string of no more than 49 ASCII characters terminated by a period. Control characters for bells and inverse video may be sent to the system console using this parameter. Attempts to send other control characters, however, results in a display of blanks and the associated control character letter when the forms message appears on the system console. Default is that no forms message is sent.

Indicates if shared or exclusive file access is allowed. EXC is exclusive access; after the file is opened, no other accesses are permitted. For message files, EXC means one writer and one reader. For circular files EXC means one reader or one writer. SHR is share access; after the file is opened other accesses are permitted. EAR is exclusive access for one writer; it allows multiple readers. SEMI is intended for use with message files; it allows one exclusive reader, multiple writers; if the file is not a message file, SEMI acts like EAR (one exclusive writer, multiple readers). Default is EXC except with read only file access (IN).

Indicates if this tape is labeled or unlabeled. NOLABEL specifies an unlabeled tape. LABEL specifies a labeled tape. Default is NOLABEL.

Up to six alphanumeric characters identifying a labeled magnetic tape volume. If a special character, such as # is specified, volid must be surrounded by quotation marks (for example, FILE LT;DEV=TAPE; LABEL="#12345",ANS).

Type of standard label. ANS is ANSI-standard label. IBM is IBM-standard label. Default is ANS.

Month, day, year, written in the format mm/dd/yy. This specifies the expiration date of the file, or the date after which information contained in the file is no longer useful. The file can be overwritten without operator reconfirmation after this date. Default is 00/00/00; the file can be overwritten immediately.

Either an absolute file number between 1 and 9999 (inclusive), or one of the following, which specifies the position of the file relative to other files on the tape:

Applies only to output spoolfiles. A string of up to eight alphanumeric characters, beginning with a letter, which uniquely identifies a special form that is to be mounted. A message displaying this formid is printed on the system console or $STDLIST of the associated user of the spooled device. The spooler process then awaits verification that the special forms have been mounted before printing the file for which the formid was specified. The default is that no formid or message is displayed.

The PRIVATE option generates a spool file that may be accessed in privileged mode only. This means that the file is not accessible to normal users on the system. Private spoolfiles may not be saved or copied. They may only be purged, printed, or (within limits) altered by using the SPOOLF command instead of using the PURGE or COPY commands.

The file is deleted when closed.

The file is saved in the job/session temporary domain when closed.

The file is saved in the permanent file domain when closed.

If this parameter is used, the resulting spool file is created with SPSAVE disposition. This means the spool file is not to be purged after the last copy of it has been printed, but is instead retained in the OUT.HPSPOOL group.

This option is only valid for output spoolfiles. Private spoolfiles cannot be saved with the SPSAVE parameter.

If none of these parameters are supplied, the disposition of the file is as it was when opened, or as specified by the FCLOSE intrinsic call issued by the user program.

These two options apply only to KSAM files. DEFBLK specifies that the data block size will be the default data block size of 4096 bytes. OPTMBLK specifies that KSAMXL will select the optional data block size based on the record size. The default is DEFBLK.

BUILD, LISTEQ, LISTFILE, RESET

MPE/iX Intrinsics Reference Manual