MPE/iX Commands Reference Manual > Chapter 6 Command List IV

Commands FCOPY thru GETRIN

	MPE documents
	Complete PDF
	Table of Contents
	Index

FCOPY
FILE
FINDDIR (UDC)
FINDFILE (UDC)
FORMSALIGN
FORTGO
FORTPREP
FORTRAN
FREERIN
FTN
FTNGO
FTNPREP
FTNXL
FTNXLGO
FTNXLLK
GETLOG
GETRIN

FCOPY

Invokes the FCOPY subsystem.

Syntax


  FCOPY [fcopycommand]

Parameters

fcopycommand: An FCOPY subsystem command. The FCOPY subsystem enables you to copy files or selected portions of files from any supported input device to any supported output device. There are many commands; only the most common examples are found in the "Examples" section of this command. Refer to the FCOPY Reference Manual (32212-90003) for more information.

Operation Notes

This command runs the FCOPY subsystem from MPE/iX. If the command is entered with no parameters, FCOPY prompts (>) the user for subsystem commands until an EXIT command is entered. If the fcopycommand parameter is used, FCOPY executes the FCOPY subsystem command and then returns control to MPE/iX.

Use

This command may be issued from a session, job, or in BREAK. To use this command from a program, the user or the program must have process handling (PH) capability. Pressing Break suspends the execution of this command. Entering the RESUME command continues the execution.

Examples

To access FCOPY to execute multiple commands, enter:


  FCOPY
  HP32212A.03.24
  FILE COPIER (C) HEWLETT-PACKARD CO. 1984
  
  >

To access FCOPY to execute a single command and return control to MPE/iX, enter the command as follows:


  FCOPY FROM=UDC.TECHPUBS;TO=TEMP;NEW
  
  HP32212A.03.24 FILE COPIER (C) HEWLETT-PACKARD CO. 1984
  
  EOF FOUND IN FROMFILE AFTER RECORD 23
  
  END OF SUBSYSTEM
  :

Related Information

Commands: COPY
Manuals: FCOPY Reference Manual

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 be used to access a remote file or device in a subsequent command or intrinsic. NS3000/XL AdvanceNet is not part of the HP 3000 Series 900 Computer System Fundamental Operating System and must be purchased separately.

Syntax


  FILE formaldisgnator = [ *formaldisgnator | $NULL | $NEWPASS |
      $OLDPASS | $STDIN | $STDINX | $STDLIST | filereference ]
    [ :nodespec ,filedomain ]
    [ :DEV=[ [ envname] #] [ device] [ ,[ outpri] [ ,numcopies]]]
    [ ;VTERM] [ ;ENV=envfile[ :nodespec]]
    [ ;option] [ ;access][ ; disposition]
    [ ;DEFBLK | ;OPTMBLK]

Parameters

formaldesignator

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

$NULL

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.

$NEWPASS

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.

$OLDPASS

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

$STDIN

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.

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

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.

$STDLIST

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.

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

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

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 not upshifted.
File names can be up to 255 characters in length for absolute pathnames and 253 characters for relative pathnames.
File names 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:

if filename = ..fn, look for file ..fn in the CWD (current working directory)
if filename = /fn, look for file fn in root directory (/)
if filename = ./fn, look for file fn in the CWD
if filename = ../fn, look for file fn in parent directory
if filename = .fn, look for file .fn in the CWD

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.

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.

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.

NOTE: The nodespec parameter and REMOTE command are not part of the HP 3000 Series 900 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 makes no difference in the performance of the FILE command.
However, specifying nodespec on a system that does not have NS3000/XL produces an error. The nodespec parameter is controlled by the NS3000/XL subsystem. Refer to the NS3000/XL User/Programmer Reference Manual.

filedomain

The domain of the file, which may be NEW, OLD, 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 in this chapter.
OLD: 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. Use this parameter when you are creating a file equation that back references a device link file.
OLDTEMP: 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 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.

NOTE: The envname parameter is not part of the HP 3000 Series 900 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 makes no difference in the performance of the FILE command.
However, specifying envname on a system that does not have NS3000/XL produces an error. The envname parameter is controlled by the NS3000/XL subsystem. Refer to the NS3000/XL User/Programmer Reference Manual.

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

device

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.

outpri

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

numcopies

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

VTERM

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

envfile

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.

option

Any valid option for the FILE command.

Syntax for Option


  [;REC=[recsize][,[blockfactor][,[F | U | V | B]
    [,[BINARY | ASCII] ]]]]
    
  [;DEN=[density]]
  
  [;DISC=[numrec][,[numextents][,[initialloc] ]]]
  
  [;CODE=filecode]
  
  [;[RIO | NORIO | STD | MSG | CIR | KSAMXL | SPOOL | KSAM64] ]
  
  [;ULABLE=numlabels]
  
  [;KEY={^filereference keyinfo}]
  
  [;FIRSTREC=recnum]
  
  [;REUSE | ;NOREUSE]

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

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

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

numrec

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.

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

numextents

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

initialloc

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.

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

RIO or NORIO

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 for a discussion of relative I/O.

STD, MSG, CIR, KSAMXL, or SPOOL

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:

variable length records of 1008 bytes each
a blocking factor of 1
ASCII format
permanent file
a record limit of 1023
undefined maximum number of extents, with 0 extents initially allocated

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

KSAM64 specifies a KSAM file that is capable of holding more than 4GB of data. KSAM64 files are compatible in every other way with KSAM XL files. All options that apply to KSAM XL files also apply to KSAM64 files.

numlabels

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.

^filereference or keyinfo

Information about KSAM XL and KSAM64key. 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:


  ;KEY= (keyspec;keyspec...)

Where:


  keyspec ::= keytype, keylocation, keysize [ ,DUP | ,RDUP ]

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.

keytype

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.

keylocation

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.

keysize

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

Table 6-1 KSAM key length

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)

DUP or RDUP

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.

recnum

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

REUSE or NOREUSE

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.

Syntax for Access


  [ ;NOCCTL  ;CCTL]
  [ ;NOMULTI  ;MULTI  ;GMULTI]
  [ ;NOMR  ;MR]
  [ ;WAIT  ;NOWAIT]
  [ ;ACC=[IN | OUT | UPDATE | OUTKEEP | APPEND | INOUT]]
  [ ;BUF=numbuffers] ;NOBUF][ ;LOCK  ;NOLOCK]
  [ ;COPY  ;NOCOPY][ ;FORMS=formsmsg] [ ;EXC  ;SHR  ;EAR  ;SEMI]
  [ ;NOLABEL  ;LABEL=[[volid][,[ IBM | ANS][,[expdate][,seq]]]]]
  [ ;FORMID=formid][ ;PRIVATE]

Parameters for Access

NOCCTL or CCTL

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.

NOMULTI, MULTI, or GMULTI

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.

NOMR or MR

Indicates if 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

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.

IN, OUT, UPDATE, OUTKEEP, APPEND, or INOUT

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.

BUF= numbuffers or NOBUF

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.

NOLOCK or LOCK

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.

COPY or NOCOPY

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.

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

EXC, SHR, EAR, SEMI

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

NOLABEL or LABEL

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

volid

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

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

formid

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.

PRIVATE

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.

Syntax for Disposition


  [ ;DEL   ;TEMP   ;SAVE   ;SPSAVE ]

Options for Disposition

DEL

The file is deleted when closed.

TEMP

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

SAVE

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

SPSAVE

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.

DEFBLK or OPTMBLK

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.

Operation Notes

This command allows you to change the specifications for files at run time, including the devices on which they reside, overriding specifications supplied through 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. The FILE command is the only way you can control or change the programmatic file specifications without changing the code which calls FOPEN or HPFOPEN.

Use

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

Examples

To run the program MYPROG, which references two files by the file names (formaldesignators) SOURCE and DEST, but 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

Enter the following command to send the output to a new file FILEX. The parameters entered on the command line define FILEX as having 64-word fixed-length records, blocked two records per block in ASCII code; it is limited to 800 records among 10 extents, two of which are to be immediately allocated. When MYPROG closes the file, it will be permaently saved.


  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 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 FORTRAN 77/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

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 FORTRAN compiler then backreferences itself:


  FTNXL *FTNTEXT
  FILE FTNTEXT=*FTNTEXT

The following is an example of using the *formaldesignator, in this case, specifying a file on magnetic tape used as a source file during 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.

The following example uses NMS file option SPOOL:


  FILE MYSPOOL;DISC=3000,1,1;SPOOL
  PRINT DOCFILE.MYGROUP.MYACCT,*MYSPOOL

Because the DEV= parameter of the FILE command is defaulted to disk, the result is an unlinked output spool file. To send this file to a printer, use the following command:


  SPOOLF MYSPOOL;PRINT;DEV=LP

This links MYSPOOL to the SPFDIR using the default PRI (8) and number of copies (1). Note that the DEV= parameter is required with the SPOOLF;PRINT command to link the spool file to a target device. Failure to specify DEV= (or specifying an inappropriate DEV such as disk) results in an error message.

HFS Examples


  FILE X=./my_file;SAVE
  PURGE *X

To reference the device link file TAPE7 in a file equation, enter:


  FILE T=TAPE7,OLD

Related Information

Commands: BUILD, LISTEQ, LISTFILE, RESET
Manuals: MPE/iX Intrinsics Reference Manual

FINDDIR (UDC)

The FINDDIR UDC executes the LISTFILE command to search for a directory.

NOTE: System-defined UDCs are not automatically available. Your System Manager must use the SETCATALOG command to make these UDCs available for your use. For example:


  SETCATALOG HPPXUDC.PUB.SYS;SYSTEM;APPEND

Syntax


  FINDDIR [[DIR=]dir_name] [ [START=]start_dir]

Parameters

Refer to the LISTFILE command for a complete explanation of the parameters used with the FINDDIR UDC. The following parameters are supported with the FINDDIR UDC.

dir_name: A simple directory name, including wildcards. The dir_name is case insensitive. It cannot be a pathname. For example, abc, @bc, and [A-M]_@ are valid dir_names; while /ABC/, ./Mydir, and ABC.GRP are not valid dir_names. The dir_name is optional and defaults to @.
start_dir: The name of the directory where the search is to begin. For example, /SYS/PUB. The default starting directory is the root directory (/).

Operation Notes

The FINDDIR UDC finds all directories matching dir_name, with the search beginning at start_dir.

The UDC executes the following form of the LISTFILE command:


  LISTFILE start_dir ,6 ;SELEQ=[OBJECT=DIR] ;NAME=dir_name ;TREE

Use

This UDC may be issued from a session, a job, a program, or in BREAK. Pressing Break aborts execution.

Examples

Refer to the LISTFILE command later in this chapter for examples.

Related Information

Commands: LISTFILE, FINDFILE (UDC), LISTDIR (UDC)
Manuals: None

FINDFILE (UDC)

The FINDFILE UDC executes the LISTFILE command to search for a file.

NOTE: System-defined UDCs are not automatically available. Your System Manager must use the SETCATALOG command to make these UDCs available for your use. For example:


  SETCATALOG HPPXUDC.PUB.SYS;SYSTEM;APPEND

Syntax


  FINDFILE [FILE=] filename [[START=]start_dir]

Parameters

Refer to the LISTFILE command for a complete explanation of the parameters used with the FINDFILE UDC. The following parameters are supported with the FINDFILE UDC.

filename: A simple file name, including wildcards. The filename is case insensitive. It cannot be a pathname. For example, abc, @bc, and [A-M]_@ are valid filenames; while /ABC/, ./Mydir, and ABC.GRP are not valid filenames. The filename is required.
start_dir: The name of the directory where the search is to begin; for example, /SYS/PUB. The default starting directory is the root directory (/).

Operation Notes

The FINDFILE UDC searches for all files matching filename, with the search beginning at start_dir.

The UDC runs the the following form of the LISTFILE command:


  LISTFILE start_dir ,6 ;SELEQ=[OBJECT=FILE] ;NAME=filename ;TREE

Use

This UDC may be issued from a session, a job, a program, or in BREAK. Pressing Break aborts execution.

Examples

Refer to the LISTFILE command later in this chapter for examples.

Related Information

Commands: LISTFILE, FINDDIR (UDC)
Manuals: None

FORMSALIGN

Configures one spooled printer or a group of spooled printers related by device class, to conditionally enter into a forms message dialog with its operator (s) when the current spoolfile includes a forms message.

Syntax


  FORMSALIGN [DEV=]{ldev | devclass | devname }
    [;[DIALOG=]{{EACHCHANGE | EACHFILE | EACHCOPY }
      [,{FORMIDOVERRIDE | NOFORMIDOVERRIDE}]}]
    [ ;SHOW]

Parameters

ldev

The logical device number of a printer. The printer must be configured as an MPE Type 32 device.

devclass

The device class name of a class of printers. Each printer in the class must be configured as an MPE Type 32 device. The device class must begin with a letter and consist of eight or fewer alphanumeric characters.

devname

The device name of a printer. The device name must begin with a letter and consist of eight or fewer alphanumeric characters. Users should note that it is not possible to have a device class name and a device name (which are the same). If you enter an alphanumeric character string, the command will search the device class list first, and then the device name list.

EACHCHANGE

The spooler process conducts the forms message dialog only when the (case-insensitive) forms message of the current spoolfile differs from that of the previous spoolfile printed by that process when an overriding formid specification is not in effect. Two different spoolfiles with the same forms message will print without the forms message dialog if they are printed consecutively.

EACHFILE

The spooler process conducts the forms message dialog whenever the spoolid of the current spoolfile differs from that of the previous spoolfile printed by that process, the current spoolfile contains a forms message and an overriding formid specification is not in effect. Two copies of the same spoolfile will print without the forms message dialog if they are printed consecutively.

EACHCOPY

The spooler process conducts the forms message dialog for every copy of every spoolfile which contains a forms message if an overriding formid specification is not in effect.

FORMIDOVERRIDE

This is a sub-parameter of the chosen EACHxxx keyvalue. With this feature selected, the Native Mode Spooler first checks its current and previous spoolfiles for the same non-blank, case-insensitive formid. If the formids match, both the DIALOG option for the spooler process and any forms message in the current spoolfile are ignored, and the forms message dialog is not activated. Identical formids override all other considerations.

Note that the DIALOG option is not changed. It is ignored as long as the two formids match.

If the two formids do not match, and the formid of the current spoolfile is not empty, then the spooler conducts the forms message dialog using the forms message of the current spoolfile.

If the current spoolfile has no forms message (even though it has a forms identification), the spooler:

Conducts no dialog if standard forms are already mounted.
Displays the STANDARD FORMS message if special forms are mounted.

If the two formids do not match because the current spoolfile has no formid and the previous spoolfile did, the spooler will always conduct a forms message dialog, again ignoring any setting of DIALOG. If the current spoolfile has a non-empty forms message, the spooler conducts a normal forms message dialog with the device operator. If the forms message is empty, and the device has special forms mounted, the spooler prompts the device operator to mount standard forms.

Once both the previous spoolfile and the current spoolfile have no formids, the spooler operates in accordance with the selected DIALOG option once more.

NOFORMIDOVERRIDE

This is a sub-parameter of the chosen EACHxxx keyvalue. With this feature selected, the Native Mode Spooler ignores any and all formids associated with the current spoolfile or the previous spoolfile. The setting of the DIALOG option always determines the conditions under which the spooler process conducts the forms message dialog. The formid is then useful only as an item in a selection equation.

NOTE: The setting of (NO)FORMIDOVERRIDE only affects the spooler's function during the forms message dialog. It has no effect on the use of the FORMID keyword in a selection equation of either the SPOOLF or LISTSPF command. It is still possible to select a subset of all spoolfiles to alter, delete, or display on FORMID=, regardless of the setting (NO)FORMIDOVERRIDE for a given device. They are totally independent of each other.
If the current spoolfile has no forms message but special forms are mounted on the device, the spooler always conducts the STANDARD FORMS dialog.

SHOW

Specifying this option causes the configuration for the specified devices to be displayed. If no other parameters are used, the current configuration is displayed. If other parameters are used, the configuration is first updated and then displayed. If a device class is specified, the configuration for each device in the class is displayed.

If this option is omitted, there is no display.

Operation Notes

The FORMSALIGN command can be used on a spooled or an unspooled printer, or on a device class containing any mixture of spooled and unspooled printers. When used on a spooled printer, the specified options become effective on the next copy selected for printing on that device. The choices are retained until changed by another FORMSALIGN command, even if the printer should become unspooled and a new spooler process started for it.

When used on an unspooled printer, it presently has no effect but will be retained (unless changed by another FORMSALIGN command) and will become effective immediately upon spooling the printer. Files which include a forms message, and which are directed to an unspooled printer, always trigger a forms message dialog with the printer's operator. Any formid accompanying the file is irrelevant when the file is directed to an unspooled printer.

NOTE: This command effects more than one device (if applied to all devices in a class). You may get warning messages for some devices and not others. A warning message on one or more devices affects only that device. The command will continue to execute until all selected devices have been configured or shown, or an error is detected. An error terminates the command.

The options specified in the FORMSALIGN command are stored in the appropriate device files. For example, options for LDEV 6 are stored in file 00000006.DEVICES.3000devs. This is why the options are retained even when no spooler process exists for LDEV 6.

However, these device files are reconstructed at each system startup. The FORMSALIGN options set at that time are EACHCHANGE, FORMIDOVERRIDE. Your SYSSTART file should include one FORMSALIGN command per device or class for which you want to set options other than the default.

Use

This command may be issued from a session, job, program, or in BREAK. Any user may execute this command with only the ;SHOW option to display current configuration. When changing configuration, this command may be executed only from the console or by any user who has been allowed the FORMSALIGN command with the ALLOW command. You can also execute this command by assigning a user the ASSOCIATE command and specifying the device.

Examples

To display the current configuration, enter:


  FORMSALIGN LP;SHOW

A sample of the output might look like the following:


                  FORMID
  LDEV   DEVNAME  DIALOG    OVERRIDE

    6    LDEV6    EACHCHANGE    YES
   14    LDEV14   EACHCOPY       NO
   15    LDEV15   EACHFILE      YES
   19    LDEV19   EACHCHANGE     NO

To conduct a forms message dialog for each copy of each file printed, enter:


  FORMSALIGN 6;DIALOG=EACHCOPY,NOFORMIDOVERRIDE

You may also specify the system startup options, for example:


  FORMSALIGN 6;DIALOG=EACHCHANGE,FORMIDOVERRIDE

Related Information

Commands: SPOOLER, ALLOW, ASSOCIATE
Manuals: Performing System Operation Tasks

FORTGO

Compiles, prepares, and executes a compatibility mode FORTRAN 66/V program. FORTRAN 66/V is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately.

Syntax


  FORTGO [textfile] [,[listfile] [,[masterfile] [,[newfile]]]]
    [;INFO=quotedstring]

Parameters

textfile

Actual file designator of the input file from which the source program is read. This can be any ASCII input file. The formal file designator is FTNTEXT. Default is $STDIN.

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. The formal file designator is FTNLIST. Default is $STDLIST.

masterfile

Actual file designator of the master file with which textfile is merged to produce a composite source. This can be any ASCII input file. The formal file designator is FTNMAST. Default is that the file is not read; input is read from textfile, or from $STDIN if textfile is not specified.

newfile

Actual file designator of the file resulting from merging textfile and masterfile. This can be any ASCII output file. The formal file designator is FTNNEW. Default is that the file is not written.

quotedstring

A sequence of characters between two single quotation marks (apostrophes) or between two double quotation marks. You may use the delimiter as part of the string so long as the delimiter appears twice. Any occurrence of two single or two double quotation marks in a row, is considered part of the string, and, therefore, not the terminating delimiter.

INFO=quotedstring is used to pass initial compiler options to a program.

NOTE: The formal file designators used in this command (FTNTEXT, FTNLIST, FTNMAST, and FTNNEW) cannot be backreferenced as actual file designators in the command parameter list. For further information, refer to the "Implicit FILE Commands for Subsystems" discussion of the FILE command.

Operation Notes

The FORTGO command compiles, prepares, and executes a compatibility mode FORTRAN 66/V program. If you do not specify a source file, MPE/iX expects input from your standard input device. If you do not specify listfile, MPE/iX writes the listing to your standard output device.

The USL file created during the compilation is a system-defined temporary file $OLDPASS, which is passed directly to the MPE segmenter, and cannot be accessed.

Use

This command may be issued from a session, job, or program. It may not be used in BREAK. Pressing Break suspends the execution of this command. Entering the RESUME command continues the execution.

Examples

To compile, prepare, and execute a FORTRAN 66/V program entered from the disk file SOURCE and transmit the resulting program listing to the disk file LISTFL, enter:


  FORTGO SOURCE,LISTFL

To enter your source input from a device other than your standard input device, and/or direct the listing to a device other than your standard list device, simply name the input and listing files as command parameters. In the example below, the source listing is read from magnetic tape, formally identified by the file name MTAPE. Output is sent to the printer, identified by the file name PRTR.


  FILE MTAPE;DEV=TAPE
  FILE PRTR;DEV=FASTLP

MTAPE and PRTR are then backreferenced in the FORTGO command, as shown here:


  FORTGO *MTAPE,*PRTR

Related Information

Commands: FORTPREP, FORTRAN, RUN, XEQ, PREP, SEGMENTER
Manuals: HP FORTRAN/3000 Reference Manual
MPE Segmenter Reference Manual

FORTPREP

Compiles and prepares a compatibility mode FORTRAN 66/V program. FORTRAN 66/V is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately.

Syntax


  FORTPREP [textfile] [,[progfile] [,[listfile] [,[masterfile]
      [,[newfile]]]]]
    [;INFO=quotedstring]

Parameters

textfile

Actual file designator of the input file from which the source program is read. This can be any ASCII input file. The formal file designator is FTNTEXT. Default is $STDIN.

progfile

Actual file designator of the program file to which the prepared program segments are written. When you omit progfile, the MPE segmenter creates the program file, which resides in the temporary file domain as $OLDPASS. To create your own program file, you must do so in one of two ways:

By using the MPE/iX BUILD command, and specifying a file code of 1029 or PROG, and a numextents value of 1. This file is then used by the PREP command.
By specifying a nonexistent file in the progfile parameter, resulting in the creation of job/session temporary file of the correct type.

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. The formal file designator is FTNLIST. Default is $STDLIST.

masterfile

Actual file designator of the master file with which textfile is merged to produce a composite source. This can be any ASCII input file. The formal file designator is FTNMAST. Default is that the master file is not read; input is read from textfile, or from $STDIN if textfile is not specified.

newfile

Actual file designator of the file resulting from the merger of textfile and masterfile. This can be any ASCII output file. The formal file designator is FTNNEW. Default is that the file is not written.

quotedstring

INFO=quotedstring

is used to pass initial compiler options to a program.

Operation Notes

This command compiles and prepares a compatibility mode FORTRAN 66/V program into a program file stored on disk. If you do not specify a source file, MPE/iX expects the input from your standard input device. If you do not specify listfile, MPE/iX sends the output to your standard list device.

The USL file created during compilation is a system-defined temporary file $OLDPASS, which is passed directly to the MPE segmenter. The segmenter also uses the file $OLDPASS. The prepared program segments are written to it, thus overwriting any existing temporary file of that name.

If you have no need to examine the USL file, use the default for progfile. This way, MPE/iX creates a program file for you, ensuring the best results. If, on the other hand, you want to store the USL file and the program file as separate entities, specify progfile.

Use

Examples

To compile and prepare a FORTRAN 66/V program entered from your standard input device, into the standard default file $OLDPASS, with the listing printed on your standard list device, enter:


  FORTPREP

To compile and prepare a FORTRAN 66/V source program from a text file named TEXTX into a program file named PROGX, with the listing sent to the list file LISTX, enter:


  FORTPREP TEXTX,PROGX,LISTX

The FORTPREP command combines the compilation and preparation steps. The compiled program segments, stored in the file $OLDPASS, are prepared and stored in the program file PROGX. Therefore, it is equivalent to:


  FORTRAN TEXTX, LISTX
  PREP $OLDPASS,PROGX

Related Information

Commands: FORTGO, FORTRAN, RUN, XEQ, PREP, SEGMENTER
Manuals: HP FORTRAN/3000 Reference Manual
MPE Segmenter Reference Manual

FORTRAN

Compiles a compatibility mode FORTRAN 66/V program. FORTRAN 66/V is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately.

Syntax


  FORTRAN [textfile] [,[uslfile] [,[listfile] [,[masterfile]
      [,[newfile]]]]]
    [;INFO=quotedstring]

Parameters

textfile

Actual file designator of the input file from which the source program is read. This can be any ASCII input file. The formal file designator is FTNTEXT. Default is $STDIN.

uslfile

Actual file designator of the user subprogram library (USL) file to which the object program is written, which can be any binary output file with file code of USL or 1024. The formal file designator is FTNUSL. If the uslfile parameter is omitted, the object code is saved to the temporary file $OLDPASS. If entered, this parameter indicates that the USL file was created in one of four ways:

By using the MPE/iX SAVE command to save default USL file $OLDPASS created during a previous compilation.
By building the USL with the MPE segmenter -BUILDUSL command. Refer to the MPE Segmenter Reference Manual (30000-90011).
By creating a new USL file with the MPE/iX BUILD command and specifying a file code of USL or 1024.
By specifying a nonexistent uslfile parameter, thereby creating a permanent file of the correct size and type.

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is FTNLIST. Default is $STDLIST.

masterfile

Actual file designator of the master file with which textfile is merged to produce a composite source. This can be any ASCII input file. Formal file designator is FTNMAST. Default is that the master file is not read; input is read from textfile, or from $STDIN if textfile is not specified.

newfile

Actual file designator of the merged textfile and masterfile. This can be any ASCII output file. Formal file designator is FTNNEW. Default is that no file is written.

quotedstring

INFO=quotedstring

is used to pass initial compiler options to a program.

NOTE: The formal file designators used in this command (FTNTEXT, FTNUSL, FTNLIST, FTNMAST, and FTNNEW) cannot be backreferenced as actual file designators in the command parameter list. For further information, refer to the "Implicit FILE Commands for Subsystems" discussion of the FILE command.

Operation Notes

This command compiles a compatibility mode FORTRAN 66/V program into a USL file on disk. If you do not specify textfile, MPE/iX expects input from your standard input device. If you do not specify listfile, MPE/iX sends the listing to your standard list device.

If you create the USL file (using the MPE/iX BUILD command) before compiling the program, you must assign it a file code of USL or 1024. If you omit this parameter, the compiled program segments are stored in the temporary file $OLDPASS.

Use

Examples

To compile a FORTRAN 66/V program entered from your standard input device into an object program in the USL file $OLDPASS, and write the listing to your standard list device, enter:


  FORTRAN

The following example compiles a program from the source file MYSOURCE and stores the object code into the USL file MYUSL. The program listing is stored in the disk file MYLIST:


  FORTRAN MYSOURCE,MYUSL,MYLIST;INFO= "$CONTROL BOUNDS"

To compile a FORTRAN 66/V program and store the object code into a USL file you create with the BUILD command, enter:


  BUILD OBJECT;CODE=USL
  FORTRAN SOURCE,OBJECT,LISTFL

To create a USL file with the BUILD command, the code must be specified.

Related Information

Commands: FORTGO, FORTPREP, RUN, XEQ, PREP, SEGMENTER
Manuals: HP FORTRAN/3000 Reference Manual
MPE Segmenter Reference Manual

FREERIN

Releases a global resource identification number (RIN).

Syntax


  FREERIN rin

Parameters

rin: The resource identification number (RIN) to be released. It must be a number from one to the configured maximum.

Operation Notes

A resource identification number is used to manage a resource shared by two or more jobs or sessions so that only one job or session at a time can access that resource.

The user acquires a RIN from the system by entering the GETRIN command. When all users are finished with the RIN, the user who acquired it returns it to the system by entering the FREERIN command. To free a RIN, you must be the original owner of that RIN, that is, the user who actually issued the GETRIN command that allocated the RIN and assigned it a password.

Use

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

Example

To release RIN 1, enter:


  FREERIN 1

Related Information

Commands: GETRIN
Manuals: MPE/iX Intrinsics Reference Manual
Resource Management Programmer's Guide

FTN

Compiles a compatibility mode FORTRAN 77/V program. FORTRAN 77/V is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. The native mode equivalent of this command is FTNXL.

Syntax


  FTN [textfile] [,[uslfile] [,[listfile]]]
    [;INFO=quotedstring]

Parameters

textfile

Actual file designator of the input file from which the source program is read. This can be any ASCII input file. Formal file designator is FTNTEXT. Default is $STDIN.

uslfile

Actual file designator of the USL file to which the object code is stored, which can be any binary output file with a file code of USL or 1024. Its formal file designator is FTNUSL. If the uslfile parameter is omitted, the object code is saved to the temporary file $OLDPASS. If entered, this parameter indicates that the USL file was created in one of four ways:

By using the MPE/iX SAVE command to save the default USL file $OLDPASS, created during a previous compilation.
By building the USL with the segmenter -BUILDUSL command. Refer to the MPE Segmenter Reference Manual (30000-90011).
By creating a new USL file with the MPE/iX BUILD command and specifying a file code of USL or 1024.
By specifying a nonexistent uslfile parameter, thereby creating a permanent file of the correct size and type.

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is FTNLIST. Default is $STDLIST.

quotedstring

A sequence of characters between two single quotation marks or between two double quotation marks that specify compiler options. You may use the delimiter as part of the string so long as the delimiter appears twice. Any occurrence of two single or two double quotation marks in a row, is considered part of the string, and, therefore, not the terminating delimiter.

Operation Notes

The FTN command compiles a compatibility mode HP FORTRAN 77/V program and stores the object code in a user subprogram library (USL) file on disk. If textfile is not specified, MPE/iX expects the source program to be entered from your standard input device. If you do not specify listfile, MPE/iX sends the program listing to your standard list device and identifies it by the formal file designator, FTNLIST.

If you create the USL prior to compilation, you must specify a file code of USL or 1024. If you omit the uslfile parameter, the object code is saved in the temporary file domain as $OLDPASS. To keep it as a permanent file, you must save $OLDPASS under another name.

You cannot backreference the formal file designators used in this command (FTNTEXT, FTNUSL, and FTNLIST) as actual file designators in the command parameter list. For further information, refer to the "Implicit FILE Commands for Subsystems" discussion of the FILE command.

Use

Examples

The following example compiles an HP FORTRAN 77/V program entered from your standard input device and stores the object program in the USL file $OLDPASS. The listing is then sent to your standard list device.

FTN

The next example compiles an HP FORTRAN 77 program contained in the disk file FORTSRC, and stores the object program in the USL file FORTOBJ. The program listing is stored in the disk file LISTFILE:


  BUILD FORTOBJ;CODE=USL
  FTN FORTSRC,FORTOBJ,LISTFILE

Related Information

Commands: FTNGO, FTNPREP
Manuals: HP FORTRAN 77/iX Reference
MPE Segmenter Reference Manual

FTNGO

Compiles, prepares, and executes a compatibility mode HP FORTRAN 77/V program. HP FORTRAN 77/V is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. The native mode equivalent of this command is the FTNXLGO command.

Syntax


  FTNGO [textfile] [,listfile] [;INFO=quotedstring]

Parameters

textfile: Actual file designator of the input file from which the source program is read. This can be any ASCII input file. Formal file designator is FTNTEXT. Default is $STDLIST.
listfile: Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is FTNLIST. Default is $STDLIST.

NOTE: The formal file designators used in this command (FTNTEXT and FTNLIST) cannot be backreferenced as actual file designators in the command parameter list. For further information, refer to the "Implicit FILE Commands for Subsystems" discussion of the FILE command.

quotedstring

INFO=quotedstring is used in the HP FORTRAN 77/V programming language to pass initial compiler options to a program.

Operation Notes

The FTNGO command compiles, prepares, and executes an HP FORTRAN 77/V program. If textfile is omitted, MPE/iX expects input from your standard input device. If you do not specify listfile, MPE/iX sends the program listing to the formal file designator FTNLIST (default is $STDLIST).

The USL file created during the compilation is the system-defined temporary file $OLDPASS, which is passed directly to the MPE segmenter. It cannot be accessed because the segmenter also uses $OLDPASS to store the prepared program segments, overwriting any existing temporary file of the same name.

Use

Examples

To compile, prepare, and execute an HP FORTRAN 77/V program entered from your standard input device, with the program listing sent to your standard list device, enter:


  FTNGO

To compile, prepare, and execute an HP FORTRAN 77/V program from the disk file FORTSRC and send the program listing to the file LISTFILE, enter:


  FTNGO FORTSRC,LISTFILE

Related Information

Commands: FTN, FTNPREP, RUN, XEQ, PREP, SEGMENTER
Manuals: HP FORTRAN 77/iX Reference
MPE Segmenter Reference Manual

FTNPREP

Compiles and prepares a compatibility mode HP FORTRAN 77/V program. HP FORTRAN 77/V is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. The native mode equivalent of this command is the FTNXLLK command.

Syntax


  FTNPREP [textfile] [,progfile] [,listfile] [;INFO=quotedstring]

Parameters

textfile

Actual file designator of the input file from which the source program is read. This can be any ASCII input file. Formal file designator is FTNTEXT. Default is $STDIN.

progfile

Actual file designator of the program file to which the prepared program segments are written. When you omit progfile, the MPE segmenter creates the program file, which is stored in the temporary file domain as $OLDPASS. If you do create your own program file, you must do so in one of two ways:

By using the MPE/iX BUILD command and specifying a file code of 1029, or PROG, and a numextents value of 1. This file is then used by the PREP command.
By specifying a nonexistent file in the progfile parameter, in which case a job/session temporary file of the correct size and type is created.

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is FTNLIST. Default is $STDLIST.

quotedstring

INFO=quotedstring is used in the HP FORTRAN 77/V programming language to pass initial compiler options to a program.

Operation Notes

The FTNPREP command compiles and prepares a compatibility mode HP FORTRAN 77/V program into a program file on disk. If you do not specify textfile, MPE/iX expects input from the current input device. If you do not specify listfile, MPE/iX sends the listing output to the formal file designator FTNLIST (default $STDLIST). The USL file $OLDPASS, created during compilation, is a temporary file passed directly to the MPE segmenter. You may access it only if you do not use the default for progfile. This is because the segmenter also uses $OLDPASS to store the prepared program segments, overwriting any existing temporary file of the same name.

Use

Examples

The following example compiles and prepares an HP FORTRAN 77/V program entered through your standard input device and stores the prepared program segments in the file $OLDPASS. The listing is printed on your standard list device.


  FTNPREP

To compile and prepare an HP FORTRAN 77/V source program from the source file FORTSRC, store it in FORTPROG, and send the listing to your standard list device, enter:


  FTNPREP FORTSRC,FORTPROG

Related Information

Commands: FTN, FTNGO, RUN, XEQ, PREP, SEGMENTER
Manuals: HP FORTRAN 77/iX Reference
MPE Segmenter Reference Manual

FTNXL

Compiles an HP FORTRAN 77/iX program. HP FORTRAN 77/iX is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. This command is recognized only if HP FORTRAN 77/iX is installed on your system. (Native Mode)

Syntax


  FTNXL [textfile] [,[objectfile] [,[listfile]]] [;INFO=quotedstring]

NOTE: This command follows the optional MPE/iX command line syntax. Refer to "Optional Format for MPE/iX Commands" at the beginning of this chapter.

Parameters

textfile

Actual file designator of the input file from which the source program is read. This can be any ASCII input file. Formal file designator is FTNTEXT. Default is $STDIN.

objectfile

Actual file designator of the object file, which is the output of the compiler. This file is stored in binary form and has a file code of either NMOBJ (1461) or NMRL (1033). Its formal file designator is FTNOBJ. If the objectfile parameter is omitted, the object code is saved to the temporary file $OLDPASS if it exists, or to $NEWPASS which then becomes $OLDPASS.

If you specify objectfile, the compiler stores the object file in a permanent file of the correct size, type, and name you specified.

If either a file of the same name or the default file $OLDPASS already exists, the new object code overwrites the old if the file code is NMOBJ or is appended to the old if the file code is NMRL. If the file code is NMRL, any existing version of the code module is first purged.

The compiler may issue an error message telling you that a new or existing object file is too small to contain the compiler's output or number of modules. In that case you must build a larger file or use the Link Editor to clean the NMRL. You may then recompile to the new file.

You may use the MPE/iX SAVE command to store $OLDPASS as a permanent file under another name.

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is FTNLIST. Default is $STDLIST.

quotedstring

A string of no more than 255 characters (including the single or double quotation marks that enclose it).

The info string used in the HP FORTRAN 77/iX programming language to pass initial compiler options to the HP FORTRAN 77/iX compiler. HP FORTRAN 77/iX places a single dollar sign ($) before the info string and places the string before the first line of source code in the text file.

NOTE: The formal file designators used in this command (FTNTEXT, FTNOBJ, and FTNLIST) cannot be backreferenced as actual file designators in the command parameter list. For further information, refer to the "Implicit FILE Commands for Subsystems" discussion of the FILE command.

Operation Notes

The FTNXL command compiles an HP FORTRAN 77/iX program and stores the object code in a source file on disk. If textfile is not specified, MPE/iX expects the source program to be entered from your standard input ($STDIN). If you do not specify listfile, MPE/iX sends the listing to your standard list device ($STDLIST) and identifies it by the formal file designator, FTNLIST. If you omit the objectfile parameter, the object code is saved in the file domain as $OLDPASS. To keep it as a permanent file, you save $OLDPASS under another name.

NOTE: This command is implemented as a command file. If you set the HPPATH variable to null (SETVAR HPPATH ""), the command file is not executed, and the command fails.

Use

Examples

The following example compiles an HP FORTRAN 77/iX program entered from your standard input device and stores the object program in the object file $OLDPASS. The listing is then sent to your standard list device.


  FTNXL

The next example compiles an HP FORTRAN 77/iX program contained in the disk file FORTSRC, and stores the object program in the object file FORTOBJ. The program listing is stored in the disk file LISTFILE.


  FTNXL FORTSRC,FORTOBJ,LISTFILE

NOTE: Program development in native mode uses the MPE/iX LINK command not the MPE V/E PREP command. This produces a significant change in the method of linking code.

If you have created a program called MAIN and a subprogram called SUB, each contained in a separate file, you might choose to handle it this way in MPE V/E:


  FTN MAIN, SOMEUSL
  FTN SUB, SOMEUSL
  :
  PREP SOMEUSL, SOMEPROG
  :
  RUN SOMEPROG

The second command appends the code from SUB to SOMEUSL.

However, LINK (in MPE/iX native mode) does not append SUB. On MPE/iX, you must compile the source files into separate object files and then use the Link Editor to link the two object files into the program file, as in this example:


  FTNXL MAIN, OBJMAIN
  FTNXL SUB, OBJSUB
  :
  LINK FROM=OBJMAIN,OBJSUB;TO=SOMEPROG
  :
  RUN SOMEPROG

On the other hand, if an NMRL is used instead of an NMOBJ, the above can be simplified to the following:


  BUILD RLFILE;DISC=10000;CODE=NMRL
  FTNXL MAIN, RLFILE
  FTNXL SUB, RLFILE
  LINK RLFILE,SOMEPROG
  RUN SOMEPROG

Related Information

Commands: FTNXLGO, FTNXLLK, RUN, XEQ, PREP, SEGMENTER
Manuals: HP FORTRAN 77/iX Reference
MPE Segmenter Reference Manual

FTNXLGO

Compiles, links, and executes an HP FORTRAN 77/iX program. HP FORTRAN 77/iX is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. This command is recognized only if HP FORTRAN 77/iX is installed on your system. (Native Mode)

Syntax


  FTNXLGO [textfile] [,[listfile]] [;INFO=quotedstring]

NOTE: This command follows the optional MPE/iX command line syntax. Refer to "Optional Format for MPE/iX Commands" at the beginning of this chapter.

Parameters

textfile: Actual file designator of the input file from which the source program is read. This can be any ASCII input file. Formal file designator is FTNTEXT. Default is $STDLIST.
listfile: Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is FTNLIST. Default is $STDLIST.
quotedstring: A run-time parameter for the compiler. It is a quoted string of no more than 255 characters (including the single or double quotation marks that enclose it). The info string is used in the HP FORTRAN 77/iX programming language to pass initial compiler options to the HP FORTRAN 77/iX compiler. HP FORTRAN 77/iX places a single dollar sign ($) before the info string and places the string before the first line of source code in the text file.

Operation Notes

The FTNXLGO command compiles, links, and executes an HP FORTRAN 77/iX program. If textfile is omitted, MPE/iX expects input from your standard input device. If you do not specify listfile, MPE/iX sends the program listing to the formal file designator FTNLIST (default is $STDLIST).

The object file created during compilation is a system-defined temporary file, $NEWPASS, which is passed directly to the Link Editor as $OLDPASS. The Link Editor purges the object file and writes the linked program to $OLDPASS, which is then executed and may be executed repeatedly.

NOTE: This command is implemented as a command file. If you set the HPPATH variable to null (SETVAR HPPATH ""), the command file is not executed, and the command fails.

Use

Example

To compile, link, and execute an HP FORTRAN 77/iX program entered from your standard input device, with the program listing sent to your standard list device, enter:


  FTNXLGO

To compile, link, and execute an HP FORTRAN 77/iX program from the disk file FORTSRC and send the program listing to the file LISTFILE, enter:


  FTNXLGO FORTSRC,LISTFILE

Related Information

Commands: FTNXL, FTNXLLK, LINK, RUN, XEQ, LINKEDIT Utility
Manuals: HP FORTRAN 77/iX Reference
MPE Segmenter Reference Manual

FTNXLLK

Compiles and links an HP FORTRAN 77/iX program. HP FORTRAN 77/iX is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. This command is recognized only if HP FORTRAN 77/iX is installed on your system. (Native Mode)

Syntax


  FTNXLLK [textfile] [,[progfile] [,[listfile]]] [;INFO=quotedstring]

NOTE: This command follows the optional MPE/iX command line syntax. Refer to "Optional Format for MPE/iX Commands" at the beginning of this chapter.

Parameters

textfile: Actual file designator of the input file from which the source program is read. This can be any ASCII input file. Formal file designator is FTNTEXT. Default is $STDIN.
progfile: Actual file designator of the program file to which the linked program is written. When you omit progfile, the MPE/iX Link Editor creates the program file, which is stored in the temporary file domain as $OLDPASS. If you do create your own program file, you do so by specifying a nonexistent file in the progfile parameter, in which case a job/session permanent file of the correct size and type is created.
listfile: Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is FTNLIST. Default is $STDLIST.
quotedstring: A run-time parameter for the compiler. It is a quoted string of no more than 255 characters (including the single or double quotation marks that enclose it). The info string is used in the HP FORTRAN 77/iX programming language to pass initial compiler options to the HP FORTRAN 77/iX compiler. HP FORTRAN 77/iX places a single dollar sign ($) before the info string and places the string before the first line of source code in the text file.

Operation Notes

The FTNXLLK command compiles and links an HP FORTRAN 77/iX program into a disk file. If you do not specify textfile, HP FORTRAN 77/iX expects your input from your standard input device. If you do not specify listfile, HP FORTRAN 77/iX sends the listing output to your current list device.

The object file created during compilation is a system-defined temporary file, $NEWPASS, which is passed directly to the Link Editor as $OLDPASS. The Link Editor overwrites progfile and writes the linked program to $OLDPASS, if progfile is omitted, which can then be executed.

NOTE: This command is implemented as a command file. If you set the HPPATH variable to null (SETVAR HPPATH ""), the command file is not executed, and the command fails.

Use

Examples

The following example compiles and links an HP FORTRAN 77/iX program entered through your standard input device and stores the linked program in the file $OLDPASS. The listing is printed on your standard list device.


  FTNXLLK

To compile and link an HP FORTRAN 77/iX source program from the source file FORTSRC, store it in FORTPROG, and send the listing to your standard list device, enter:


  FTNXLLK FORTSRC,FORTPROG

Related Information

Commands: FTNXL, FTNXLGO, LINK, RUN, XEQ, LINKEDIT Utility
Manuals: HP FORTRAN 77/iX Reference
MPE Segmenter Reference Manual

GETLOG

Establishes a logging identifier on the system.

Syntax


  GETLOG logid;LOG=logfile ,{ DISC | TAPE | SDISC | CTAPE }
    [;PASS=password] [{ ;AUTO | ;NOAUTO }]

Parameters

logid: The logging identifier to be established. This must contain from one to eight alphanumeric characters beginning with an alphabetic character.
logfile: The name of the file to receive data from the logging procedure. It must contain from one to eight alphanumeric characters, beginning with an alphabetic character. You must also specify the device class on which the log file resides, DISC, TAPE, SDISC (serial disk) or CTAPE (cartridge tape).
password: Logging identifier password, assigned by the creator for protection against illegal use of a particular identifier. The password must contain from one to eight alphanumeric characters, beginning with an alphabetic character. The password is optional. if ;PASS= is entered without a password none is assigned.
AUTO: Initiates an automatic CHANGELOG if the log file becomes full. This option is ignored if TAPE is specified.
NOAUTO: Prevents initiation of an automatic CHANGELOG. A CHANGELOG is not performed if the log file becomes full.

Operation Notes

The GETLOG command specifies a logging identifier to be used each time a particular logging process is used. Frequently the GETLOG command is used with databases, so that each test task that runs writes to a logging file. This makes data recovery easier because you know where the task failed.

The creator of the logging identifier must have user logging (LG) or system supervisor (OP) capability to execute this command. Other users can be allowed access to this logging identifier by notifying them of the identifier and password. If a password is specified, it is required whenever the logging process is accessed. Users accessing the logging system with this identifier must supply the identifier and password in the OPENLOG intrinsic.

To use the AUTO parameter, the log process for logid must be enabled for changing. You may do this by ending the log file name with the numeric characters 001 (for example fname001). This naming convention works in conjunction with the file set number to generate sequential file names automatically.

If a log file is restricted to a single volume or volume class when it is created with the BUILD command, then successive log files created by User Logging will have the same restriction.

If a new log file name is specified with the ALTLOG command, the links with any previous log file are broken.

There cannot be two logging identifiers with the same name on the system at the same time. The LISTLOG command can be used to determine what logging identifiers currently exist.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. User logging (LG) capability is required to use this command.

Example

To create the logging identifier FINANCE and associate it with the disk log file A, enter:


  GETLOG FINANCE;LOG=A,DISC

Related Information

Commands: ALTLOG, CHANGELOG, LISTLOG, OPENLOG, RELLOG, LOG, SHOWLOG, SHOWLOGSTATUS
Manuals: System Startup, Configuration, and Shutdown Reference Manual
User Logging Programmer's Guide

GETRIN

Acquires a global resource identification number (RIN) and assigns a password to it.

Syntax


  GETRIN rinpassword

Parameters

rinpassword: Password of the intrinsic that locks the RIN. The password must contain from one to eight alphanumeric characters, beginning with an alphabetic character.

Operation Notes

The GETRIN command acquires a global RIN from the MPE/iX RIN pool, typically during a session. You must assign an arbitrary password for the RIN, which aids in restricting its use to authorized users. You can then give this RIN and the associated password to cooperating users so that it can be locked and unlocked by them. For instructions on how to lock and unlock a RIN, and how to pass a RIN and its password as intrinsic parameters, refer to the MPE/iX Intrinsics Reference Manual (32650-90028).

Users who know the RIN and its password can use it in their programs (in jobs or sessions) until the user who acquired the RIN releases it with the FREERIN command. The RIN acquired is always a unique, positive integer. The total number of RINs MPE/iX can allocate is specified when the system is configured, but cannot exceed 1024. If all currently available RINs have been acquired by other users, MPE/iX rejects your request and issues the message:


  RIN TABLE FULL

In this case, you must wait until one of the RINs becomes available, or request that your system manager raise the maximum number of RINs that can be assigned.

Use

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

Example

To acquire a global RIN and assign to it the password MYRIN, enter:


  GETRIN MYRIN

MPE/iX responds with the RIN number assigned, for example:


  RIN: 1

Related Information

Commands: FREERIN
Manuals: Resource Management Programmer's Guide

Chapter 6 Command List IV

Chapter 7 Command List V