FILE


FILE

     Declares the file attributes to be used when a file is
opened. This declaration, informally known as a file
equation, may be used to override programmatic or system
default file specifications. With the addition of shared
parameters from the NS3000/XL AdvanceNet subsystem, the
declaration may specify a formal file designator that may
used to access a remote file or device in a subsystem command
or intrinsic. NS3000/XL AdvanceNet is not part of the 900
Series HP 3000 Computer System Fundamental Operating System
and must be purchased separately. (CM)

SYNTAX


=*formaldesignator
=$NULL
=$NEWPASS
FILE formaldesignator =$OLDPASS
=$STDIN
=$STDINX
=$STDLIST
=filereference[:nodespec]
[,filedomain]

[;DEV=[[envname]#][device][,outpri][,numcopies]
[;VTERM]
[;ENV=envfile[:nodespec]]
[;option]
[;access]
[;disposition]
[{;DEFBLK}]
{;OPTMBLK}






NOTE The symbol ">" can no longer be used in a special
forms message after B.30.00.

PARAMETERS


formaldesignator A formal file designator that has the form

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

in which 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 FILE
and RESET and in the FOPEN and HPFOPEN intrinsic.
Refer to the RESET command and also
the MPE/iX Intrinsics Reference Manual (32650-
90028).

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 ( = ).

$NULL Actual file designator of a system-defined 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.

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

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

$STDIN The system-defined name of the standard job input
device. A colon () as the first character read on
this file indicates end-of-file.

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

$STDLIST The system-defined name for the standard job or
session list device.

filereference 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. Filenames will be in the
following the format:

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

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


o if filename = FN, look for file "FN" in CWD
(current working directory)

o if filename = FN.GP, look for file "FN" in group
"GP" of the logon account (regardless of the
current working directory)

o if filename = FN.GP.AC, look for file, "FN" in
group "GP" of account "AC:.

In a batch job, the file will

fail to open if the file has a lockword that is not
specified in filereference. In a session, MPE/iX
will prompt 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:

o filenames are not upshifted

o filenames can be up to 255 characters in length

o filenames can begin with, and contain, any of
the following characters:

* a-z, A-Z, 0-9, _, -, .

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:

o if filename = ./.fn, look for file ".fn" in CWD
(current working directory)

o if filename = ./..fn, look for file "..fn" in CWD

o if filename = /fn, look for file "fn" in root (/)

o if filename = ./fn, look for file "fn" in CWD

o if filename = ../fn, look for file "fn" in
parent directory

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

nodespec 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. 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.
The nodespec parameter will not function when used
with HFS naming syntax.

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

NOTE


The nodespec parameter and REMOTE command are not part of the 900
Series HP 3000 Computer System Fundamental Operating System. The
NS3000/XL AdvanceNet subsystem must be purchased separately. The
nodespec parameter is optional if you do not have NS3000/XL
AdvanceNet, omitting the nodespec parameter will make no difference in
the performance of the FILE command.

However, specifying nodespec on a system that does not have NS3000/XL
will produce an error. The nodespec parameter is controlled by the
NS3000/XL subsystem. Refer to the NS3000/XL User/Programmer Reference
Manual (36920-90001).

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

NEW Creates a new file, which is the
default. The NEW file may be
permanent or temporary, depending on
how the file was created. You must
use either the BUILD command or the
FOPEN or HPFOPEN intrinsic to create
the file. Refer to the BUILD command

OLD Specifies an existing permanent file
that was saved in the system or in a
movable volume set domain. The file
continues to exist after the current
job or session ends.

OLDTEMP Specifies a temporary file that
already exists in the temporary
session or job file domain. The file
is deleted at the end of the current
job or session.

envname This may be a NS3000 environment name as
specified by the NSFILE command. The parameter
envname may consist of as many as eight
alphanumeric characters, beginning
with an alphabetic character.

NOTE


The envname parameter is not part of the 900 Series HP 3000 Computer
System Fundamental Operating System. The NS3000/XL AdvanceNet subsystem
must be purchased separately. The envname parameter is optional if
you do not have NS3000/XL AdvanceNet, omitting the envname parameter
will make no difference in the performance of the FILE command.

However, specifying envname on a system that does not have NS3000/XL
will produce an error. The envname parameter is controlled and by the
NS3000/XL subsystem. Refer to the NS3000/XL User/Programmer Reference
Manual (36920-90001).

DEV= 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. The DEV= parameter will accept
either a volume class. An asterisk (*) must
precede a volume class name and ** must precede
a volume name.

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.

device The logical device name or logical device number of
a device, such as a disk, tape, printer, or a
terminal. The default is DISC. If the DEV= option
appears, it must be followed by at least one
parameter (the parameter can be simply #).

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

outpri The output priority requested for a spooled device.
This may have a value of 1 (the lowest priority) to
13 (the highest).

numcopies The number of copies requested for a spooled output
device file. The maximum number is 127.

VTERM Instructs MPE/iX to use the Reverse Virtual Terminal
service instead of the Remote File Access. You may
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 which support Reverse Virtual Terminal.
Refer to Communicator 3000, Volume 2, Issue 6
(Version G.02.00 of MPE V/E "U-MIT").

envfile The name of a file containing laser printer
environment information, which controls the printing
output formats on the laser printer. 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 contains such
specifications as page size, the character font,
forms, and other printer requirements to be used
with the HP Laser Printing System, entered with IDS
3000/XL and IFS 3000/XL. The file must be in a form
suitable for downloading to the HP2680A, 2688,
2563A, or 2608S.

To specify an environment file called
TRADMIN.HPENV.HP2680A for a form printed on the
HP2680A, enter

FILE LP;DEV=LASER;ENV=TRADMIN.HPENV.HP2680A

Refer to the IFS 3000/XL Reference Guide (36580-
90001) for discussions on creating environment
files.

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


The ENV= parameter will not use the system default
environment file (which is the one for a HP2680
system). Only a fully specified environment option
will override the environment option supplied by
a program in FOPEN or HPFOPEN.

option Any valid option for the FILE command.


SYNTAX FOR OPTION

                                    {F}
;REC=[recsize][,[blockfactor][,{U}[,{BINARY}]]]
{V} {ASCII }

;DEN=[density]
;DISC=[numrec][,numextents][,initialloc]
;CODE=[filecode]

[ {;RIO } ]
{;NORIO}
{;STD}
{;KSAMXL}
{;SPOOL}
{;KSAM64}

[ {;MSG} ]
{;CIR}

[;ULABEL=numlabels]

[;KEY={^filereference2}]
{keyinfo}

[;FIRSTREC=recnum]

[ {;REUSE} ]
{;NOREUSE}

[;LANG= { langid } ]
{ langname}


PARAMETERS FOR OPTION


recsize 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 will be DISC with 128
records.

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

blockfactor 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 always set to 1 after
using the original value along with recsize to
calculate maximum logical record size and physical
record size. The blockfactor is ignored for
undefined length records. Maximum size is 255.

F, U, V or B 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.

BINARY or ASCII 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.

density Corresponds to tape densities in BPI (bits-per-inch)
for new files only. This parameter is only
applicable when writing to a tape mounted on the HP
7976A or HP 7978A, 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 FOPEN and HPFOPEN in the MPE/iX
Intrinsics Reference Manual (32650-90028).

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

Default is 1023.

The file system uses these values to compute other
characteristics of the file as well. Therefore, the
values (or default values) specified in the FILE
command may be valid within their respective fields,
but may cause overflow errors in the computation of
internally needed file specifications.

The combination of record size, blocking factor,
maximum number of records, record and file type is
taken together to determine the maximum file size of
a file. The following table lists the maximum file
sizes for different types of files:

File Type Maximum Bytes

Byte stream record files ......... 2,147,483,647
Standard,fixed length record files. 137,438,953,472
KSAM64 files ....................... 137,438,953,472
All other files .................... 4,294,901,760

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

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

filecode 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 32767 or a mnemonic name. Certain integers and
mnemonics have been reserved for particular Hewlett-
Packard defined meanings.

NOTE

There are many file codes.  To examine them, type:

HELP FILE FILECODE

MPE/iX File Codes


File codes are recorded in the file label and are available to
processes accessing the file through the ``FFILEINFO'' or ``FGETINFO''
intrinsic. Although any user can specify a positive integer ranging
from 0 to 32767 or mnemonic name for this parameter, certain reserved
integers and mnemonics have particular system defined meanings,
beginning on the next page.

File Codes

Integer Mnemonic Meaning
------------------------------------------------------------------------
1024 USL User Subprogram Library
1025 BASD Basic Data
1026 BASP Basic Program
1027 BASFP Basic Fast Program
1028 RL Compatibility Mode Relocatable Library
1029 PROG Compatibility Mode Program File
1030 NMPRG Native Mode Program File
1031 SL Segmented Library
1032 NMXL Native Mode Executable Library
1033 NMRL Native Mode Relocatable Library
1035 VFORM VPLUS Forms File
1036 VFAST VPLUS Fast Forms File
1037 VREF VPLUS Reformat File
1040 XLSAV Cross Loader ASCII File (SAVE)
1041 XLBIN Cross Loader Relocated Binary File
1042 XLDSP Cross Loader ASCII File (DISPLAY)
1050 EDITQ Edit Quick File
1051 EDTCQ Edit KEEPQ File (COBOL)
1052 EDTCT Edit TEXT File (COBOL)
1054 TDPDT TDP Diary File
1055 TDPQM TDP Proof Marked QMARKED
1056 TDPP TDP Proof Marked non-COBOL File
1057 TDPCP TDP Proof Marked COBOL File
1058 TDPQ TDP Work File
1059 TDPXQ TDP Work File (COBOL)
1060 RJEPN RJE Punch File
1070 QPROC QUERY Procedure File
1080 KSAMK KSAM Key File
1083 GRAPH GRAPH Specification File
1084 SD Self-describing File
1090 LOG User Logging Log File
1091 FTAM1 Unformatted text FTAM File
1092 FTAM2 Sequential text/variable record FTAM File
1093 FTAM3 Unformatted binary FTAM File
1100 WDOC HPWORD Document
1101 WDICT HPWORD Hyphenation Dictionary
1102 WCONF HPWORD Configuration File
1103 W2601 HPWORD Attended Printer Environment
1110 PCELL IFS/3000 Character Cell File
1111 PFORM IFS/3000 Form File
1112 PENV IFS/3000 Environment File
1113 PCCMP IFS/3000 Compiled Character Cell File
1114 RASTR Graphics Image in RASTER Format
1130 OPTLF OPT/3000 Log File
1131 TEPES TEPE/3000 Script File
1132 TEPEL TEPE/3000 Log File
1133 SAMPL APS/3000 Log File
1139 MPEDL MPEDCP/DRP Log File
1140 TSR HPToolset Root File
1141 TSD HPToolset Data File
1145 DRAW Drawing File for HPDRAW
1146 FIG Figure File for HPDRAW
1147 FONT Reserved
1148 COLOR Reserved
1149 D48 Reserved
1152 SLATE Compressed SLATE File
1153 SLATW Expanded SLATE Work File
1156 DSTOR RAPID/3000 DICTDBU Utility Store File
1157 TCODE Code File for Transact/3000 Compiler
1158 RCODE Code File for Report/3000 Compiler
1159 ICODE Code File for Inform/3000 Compiler
1166 MDIST HPDESK Distribution list
1167 MTEXT HPDESK Text
1168 MARPA ARPA Messages File
1169 MARPD ARPA Distribution List
1170 MCMND HPDESK Abbreviated Commands File
1171 MFRTM HPDESK Diary Free Time List
1172 None Reserved
1173 MEFT HPDESK External File Transfer Messages File
1174 MCRPT HPDESK Encrypted Item
1175 MSERL HPDESK Serialized (Composite) Item
1176 VCSF Version Control System File
1177 TTYPE Terminal Type File
1178 TVFC Terminal Vertical Format Control File
1192 NCONF Network Configuration File
1193 NTRAC Network Trace File
1194 NLOG Network Log File
1195 MIDAS Reserved
1211 NDIR Reserved
1212 INODE Reserved
1213 INVRT Reserved
1214 EXCEP Reserved
1215 TAXON Reserved
1216 QUERF Reserved
1217 DOCDR Reserved
1226 VC VC File
1227 DIF DIF File
1228 LANGD Language Definition File
1229 CHARD Character Set Definition File
1230 MGCAT Formatted Application Message Catalog
1236 BMAP Base Map Specification File
1242 BDATA BASIC Data File
1243 BFORM BASIC Field Order File for VPLUS
1244 BSAVE BASIC Saved Program File
1245 BCNFG Configuration File for Default Option BASIC Program
1246 BKEY Function Key Definition File for Terminal
1247 BSVXL Business Basic/XL Program File
1248 BDTXL Business Basic/XL Data File
1249 BBNCM Business Basic/V Binary File
1258 PFSTA Pathflow Static File
1259 PFDYN Pathflow Dynamic File
1270 RFDCA Revisable Form DCA Data Stream
1271 FFDCA Final Form DCA Data Stream
1272 DIU Document Interchange Unit File
1273 PDOC HPWORD/150 Document
1275 DFI DISOSS Filing Information File
1276 SRI Search Restart Information File
1401 CWPTX Chinese Word Processor Text File
1421 MAP HPMAP/3000 Map Specification File
1422 GAL Reserved
1425 TTX Reserved
1428 RDIC HP Business Report Writer (BRW) Dictionary File CM
1429 RSPEC BRW Specification File
1430 RSPCF BRW Specification File
1431 REXEC BRW Execution File
1432 RJOB BRW Report Job File
1433 ROUTI BRW Intermediate Report File
1434 ROUTD BRW Dictionary OUTPUT
1435 PRINT BRW Print File
1436 RCONF BRW Configuration File
1437 RDICN BRW NM Dictionary File
1438 REXNM BRW NM Execution File
1441 PIF Reserved
1461 NMOBJ Native Mode Object File
1462 PASLB Pascal Source Library
1476 TIFF TAG Image File Format
1477 RDF Revisable Document Format
1478 SOF Serial Object File
1479 GPH Chart File for Charting Gallery Chart
1480 GPD Data File for Charting Gallery Chart
1483 VCGPM Virtuoso Code Generator Processed Micro File
1484 FRMAT Formatter
1485 DUMP Dump Files Created and used by IDAT and DPAN
1486 NWMD0 New Wave Mail Distribution List
1491 X4HDR X.400 Header for HPDesk Manager
1500 WP1 Reserved
1501 WP2 Reserved
1502 LO123 Lotus 123 Spread Sheet
1514 FTCF Form Tester Command Spec File
1515 INSP Spooler XL Input Spool File
1516 OUTSP Spooler XL Output Spool File
1517 CHKSP Spooler XL Checkpoint File
1521 DSKIT HPDesk Intrinsics Transaction File
1526 MSACK Mail Server Acknowledgement
1527 MSNDN Mail Server Non-Delivery Notification
1528 MSTRC Mail Server Trace File
2500 HPWR HP OpenDeskWriter backup File
2501 STORE Store-to-disk File
2502 STDIR On disk directory of files stored
3333 Reserved

See also the extended list von HP and 3rd party used filecodes at FILECODE.

NOTE

Default is the unreserved file code of 0.

Using ``1090 (LOG)'' as your designated file code may not yield the
number of records you specify in the ``;DISC'' parameter. Most files
use the number of records specified in the``;DISC'' parameter as the
maximum limit; user logging uses this specified number as a minimum.


RIO or NORIO Creates a relative or nonrelative I/O file. RIO
creates a relative I/O file. The record length
parameter will be implicitly changed to fixed record
length. 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 will be
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
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.

STD Defines the type of file. STD is a standard MPE/iX
disk file. Default is STD.

MSG  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 CIR acts as normal sequential file until
full. When full, the first physical block will be
deleted when the next record is written, and
remaining blocks will be logically shifted to front
of file. CIR cannot be simultaneously accessed by
readers and writers.

KSAMXL KSAMXL specifies a Native Mode KSAM file (KSAM/XL file).

KSAM64 KSAM64 specifies a KSAM file that is capable of
supporting file sizes beyond 4GB, but is in every
other way identical to a KSAMXL file. All FILE
command parameters that refer to KSAM or KSAMXL
files also apply to KSAM64 files.

SPOOL SPOOL specifies an output spoolfile. The default
outpri on the file is 8; the default number of
copies is 1; the default device is as configured in
SYSGEN.

numlabels The number of user label records to be created for
the new file. Up to 255 labels can be specified.
This parameter applies to any type of file.

^filereference or Filereference2 is a file containing keyinfo. This
parameter only applies to, and is required for new
KSAM files. The "^" means that the contents of the
file will be used.

Keyinfo has the following format:

;KEY=(keytype,keylocation,keysize [{,DUP }];
{,RDUP}
.
.
.
keytype,keylocation,keysize [{,DUP }])
{,RDUP}

One key specification (keytype, keylocation, keysize
[,DUP|,RDUP]) must be included for each key in the
KSAM file. The first occurrence of the key
specification describes the primary key; each
subsequent key specification describes an alternate
key. There may be up to 15 alternate key
specifications in addition to the primary key
description.

keytype KSAM key type specified as BYTE, INTEGER, REAL,
IEEEREAL, NUMERIC, PACKED, or *PACKED. The whole
word or only the first letter need be specified.
Valid abbreviations are B, I, R, E, N, P, and *,
respectively. If more than one letter is specified,
the word must be spelled correctly.

keylocation Location of the first byte of the key within the
data record counting from the first byte in the
record. The first byte in the date record is always
numbered 1. Only one key can start at the same location.

This parameter applies only to KSAM files.

keysize Length of the KSAM key in bytes. The length depends
on keytype as follows:

BYTE 1 to 255 bytes
INTEGER 1 to 255 bytes
REAL 1 to 255 bytes
IEEEREAL 4, 8, or 16 bytes
NUMERIC 1 to 28 bytes
PACKED 1 to 14 bytes (odd number of digits)
*PACKED 2 to 14 bytes (even number of digits)

This parameter is required for all key types.

DUP or RDUP These two options apply only to KSAM files. The DUP
option allows the user to specify that duplicate key
values are permitted. If DUP is not specified,
records with duplicate key values are rejected and
an error message is 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 keys.

The RDUP option specifies that duplicate keys are
allowed and are to be 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.

recnum Determines whether record numbers in the new KSAM
data file are to start with zero or one. If the
integer 1 is specified, then records are numbered
beginning with 1; otherwise, they will start with 0.
The only acceptable values for recnum are 1 and 0.

The default is record numbering that starts with zero.

;REUSE or ;NOREUSE The REUSE option forces KSAM files to be compacted
by reusing deleted record space. If the DUP option
is specified for akey, then duplicate records are
placed chronologically at the tail of the file, but
all nonduplicate records are assigned to the first
available space.

If the NOREUSE option is used, deleted record space
will not be reused. The default is NOREUSE. This
option can only be used for new KSAM files.

langid An integer number indicating the native language of
the file. The default is 0, or NATIVE-3000. The
language can only be selected at the time of file
creation. The language must be currently configured
on the system.

langname The name indicating the native language for the
file. The default language is NATIVE-3000. The
language can only be selected at the time of file
creation. The language must be currently configured
on the system.



SYNTAX FOR ACCESS


[{;NOCCTL}] {;NOMULTI}
{;CCTL } [{;MULTI }]
{;GMULTI }

{IN } [{;NOMR }]
{OUT } {;MR }
[;ACC=[{UPDATE }]]
{OUTKEEP} [{;WAIT }]
{APPEND } {;NOWAIT }
{INOUT }
[{;LOCK }]
[{;BUF=[numbuffers]}] {;NOLOCK }
{;NOBUF }
[{;COPY }]
{;EXC } {;NOCOPY }]
[{;SHR }]
{;EAR } [;FORMS=formsmsg]
{;SEMI}

[{;NOLABEL ]
{;LABEL=[volid ][,[{IBM}] [,[expdate][,seq]]]}
{ANS}
[;FORMID=]
[;PRIVATE]
[;SPSAVE]


PARAMETERS FOR ACCESS


NOCCTL or CCTL Indicates whether carriage control characters are or
are not 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.

IN Defines the type of file access.
OUT IN only permits READ access to the file and
UPDATE is the default for all input devices. OUT only
OUTKEEP permits WRITE access to the file and is the default
APPEND for output devices. UPDATE permits any type of
INOUT 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.

BUF=numbuffers or Specifies whether buffers are to be allocated
NOBUF 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.

EXC, SHR, EAR, SEMI Specifies shared or exclusive file access. EXC is
EXCLUSIVE access; after the file is opened no other
accessors are permitted. For message and circular
files, EXC means one writer and one reader. SHR is
SHARE access; after the file is opened other
accessors are permitted. EAR is exclusive for one
writer, allowing multiple readers. SEMI is intended
for use with message files; it allows 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).

NOLABEL or LABEL Specifies if this tape is labeled or unlabeled.
NOLABEL specifies that this is not a labeled tape.
LABEL specifies that this is a labeled tape.
Default is NOLABEL.

volid Up to six alphanumeric characters identifying a
labeled magnetic tape volume.

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

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

seq 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

0 Causes a search of all volumes until
the file is found.

ADDF ADDF positions the tape to add a new
file on the end of the volume (or last
volume in a multivolume set). Note
that ADDF should not be used to add to
a new labeled tape volume.

NEXT NEXT positions the tape at the next
file on the tape. If this is the
first FOPEN or HPFOPEN, then NEXT will
cause the tape to be positioned to the
first file on the tape. If the
previous FCLOSE specified REWIND, the
tape backspaces to the last file, and
the position is as it was, on the
previous file. This is the default.
Refer to FOPEN and HPFOPEN in the MPE
XL Intrinsics Reference Manual
(32650-90028) for more information.

NOMULTI, MULTI, or GMULTI Specifies the sharing of files in jobs
and sessions. NOMULTI prohibits
sharing files in MULTI mode and is the
default. MULTI allows concurrent
accessors 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 father-to-son
processes) with MULTI. GMULTI is the
same as MULTI except it allows
accessors to be in different jobs or
sessions.

NOMR or MR Specifies whether multirecord access is permitted.
NOMR specifies that no multirecord access is
permitted. MR allows multirecord access to the
file. Default is NOMR.

WAIT or NOWAIT Specifies whether 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 also implies NOBUF.

NOLOCK or LOCK Specifies whether dynamic locking/unlocking is
permitted. NOLOCK prohibits dynamic locking and
unlocking of file through the FLOCK and FUNLOCK
intrinsics. LOCK allows dynamic locking. The
default is NOLOCK.

COPY or NOCOPY Specifies whether files can be copied. COPY allows
MSG, KSAM, and CIR 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.

formsmsg 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,
will result in a display of blanks and the
associated control character letter when the forms
message appears on the system console. Default is no
forms message sent.

FORMID Applies only to output spoolfiles. A string of up
to 8 alphanumeric characters, beginning with a
letter, which uniquely identifies a special form
which 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.

This parameter has been added to support the Native
Mode Spooler.

PRIVATE The PRIVATE option generates a spoolfile which 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 PURGE or COPY commands.

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

PRIVATE spoolfiles cannot be saved using SPSAVE.


SYNTAX FOR DISPOSITION

      {;DEL   }
[{;TEMP }]
{;SAVE }
{;SPSAVE}


PARAMETERS FOR DISPOSITION

DEL                 The file is deleted when closed.

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

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

SPSAVE A spoolfile will be created with the SPSAVE
disposition. The spoolfile is not to be
purged after the last copy of it has been
printed. It will be saved in the OUT.HPSPOOL account.

PRIVATE spoolfiles cannot be saved with SPSAVE.

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.


PARAMETERS FOR DEFBLK and OPTMBLK

     DEFBLK specifies that the data block size will be the default
 data block size of 4096 bytes.

 OPTMBLK specifies that the OS will select the optimal data block
size based on the record size for KSAM XL and KSAM64 files.

The default is DEFBLK


OPERATION

     This command allows you to change the specifications for
files at run time, including the devices on which they
reside, overriding specifications supplied via the FOPEN or
HPFOPEN intrinsic. The FILE command remains in effect for
the entire job or session unless revoked by the RESET
command or superseded by another FILE command.

To use the FILE command for a file, you must have a valid,
formal file designator (the name by which your program
recognizes the file). The formal file designator provides a
way for commands and code outside your program to reference
the file.

With the addition of shared parameters from the NS3000/XL
AdvanceNet subsystem, the declaration may specify a formal
file designator that may be used to access a remote file or
device in a subsequent command or intrinsic. NS3000/XL
AdvanceNet is not part of the 900 Series HP 3000 Computer
System Fundamental Operating System and must be purchased
separately.

This command may be issued from a session, job, program, or
in BREAK. Pressing [Break] has no effect on this command.

NOTE

When you are programming in a language other than SPL, and you do not
write the FOPEN or HPFOPEN intrinsic calls for files used by your
program, the FILE command is the only way you can control or change the
programmatic file specifications.


EXAMPLE(S)

     A program, MYPROG, references two files by the file names
(formaldesignators) SOURCE and DEST, but you wish to use two
existing disk files INX and OUTX as the actual files for the
program. Enter

FILE SOURCE=INX
FILE DEST=OUTX
RUN MYPROG

Output is to be sent to a new file, FILEX, with 64-word
fixed length records, blocked two records per block in ASCII
code. FILEX is limited to 800 records among 10 extents, two
of which are to be immediately allocated. The file is to be
permanently saved when MYPROG closes it. Enter

FILE DEST=FILEX,NEW;REC=64,2,F,ASCII;DISC=800,10,2;SAVE
RUN MYPROG

Note that the file equation only modifies those items
specified. All other attributes used will come from the
parameters specified in the FOPEN or HPFOPEN call (or the
defaults where parameters are omitted) for the file DEST.


IMPLICIT FILE COMMANDS FOR SUBSYSTEMS

     When an actual file designator appears as a command
parameter, it is automatically equated to a formal file
designator. This is then used within the subsystem by an
implicit FILE command issued by the command executor. For
instance, within the FORTRAN77/XL compiler the formal file
designator for the text file input is FTNTEXT. Suppose you
specify a file named ALSFILE for text file input as shown below

FTNXL ALSFILE

MPE/iX implicitly issues the following FILE command,
invisible to you

FILE FTNTEXT=ALSFILE

NOTE

You cannot backreference any of the formal file designators associated
with the command as actual file designators. Therefore, do not, use the
formal file designators FTNTEXT, FTNUSL, or FTNLIST as actual file
names. The use of FTNTEXT as a file name, as in the following example,
is invalid because the implicit FILE command issued by the HP FORTRAN
compiler will then backreference itself

FTNXL;*FTNTEXT
FILE FTNTEXT=*FTNTEXT

The following is an example of a correct use of the
*formaldesignator, in this case, specifying, a file on
magnetic tape used as a source file during an HP FORTRAN
compilation

FILE SOURCE=TAPE1,OLD;DEV=TAPE;REC=-80
FTNXL;*SOURCE

Implicitly, the command executor issues the following FILE
command, backreferencing your previous FILE command

FILE FTNTEXT=*SOURCE

Implicit FILE commands, like explicit FILE commands, cancel
any previous FILE commands that reference the same formal
file designators. Formal file designators are described in
each compiler command description throughout this manual.


HFS EXAMPLE(S)

     FILE X=./my_file;SAVE
PURGE *X

ADDITIONAL INFORMATION

Commands:   None

Manuals : MPE/iX Intrinsics Reference Manual (32650-90028)