HPlogo MPE/iX Commands Reference Manual > Chapter 11 Command List IX

Commands RECALL/=RECALL thru RUN

MPE documents

Complete PDF
Table of Contents
Index

RECALL/=RECALL

Displays all pending console REPLY messages.

Syntax


  RECALL=RECALL

Parameters

None.

Operation Notes

A user, the system operator, a job or a program issues the RECALL command to determine if any pending resource requests are currently awaiting a response. Pending resource requests are responded to by using the REPLY command.

Use

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

Any user may execute the RECALL command. However, the CTRL-A =RECALL command may only be executed at the physical console, and cannot be executed from a job or a program.

Examples

To display all pending system console messages, which require a response, enter: 

  RECALL
  THE FOLLOWING REPLIES ARE PENDING:
  10:05/#J19/15/LDEV # FOR "L00576" ON TAPE1600 (NUM)?
If any replies are pending, the request(s) are displayed on the console as shown above. If no replies are pending, the following message appears on the console: 

  RECALL
  NO REPLIES PENDING (CIWARN 3020)
Use the =RECALL command if the RECALL command is ineffective, or when a job or subsystem is being executed from the console. 

  CTRL-A
  =RECALL
  NO REQUESTS PENDING (SYS 15)

Related Information

Commands

REPLY

Manuals

STORE and TurboSTORE/iX Manual
Performing System Operation Tasks

REDO

Allows the user to edit and reexecute any command still retained in the command line history stack. (Native Mode)

Syntax


  REDO [[CMD=]cmdid] [[;EDIT=]editstring]
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

cmdid

Specifies the command to execute. The command may be specified by its relative or absolute order in the command line history stack, or by name (as a string). The default is -1, the most recent command.

The following Table 11-1 "Re-execute Directives for the REDO Command" illustrates the result of using various forms of the cmdid parameter.

Table 11-1 Re-execute Directives for the REDO Command

cmdid Executes
(omitted) Previous command (same as REDO -1).
-n The nth command before the most recent one. The n represents a number in the command line stack relative to the most recent command, which is -1.
m Command number m in the command line stack. The number m is absolute (not relative).
string The most recent command beginning with string.

MPE/iX detects an error if you specify a cmdid that cannot be found in the history stack.

editstring

A string specifying the first (of one or more) edit(s) to be performed on cmdid before it is displayed on the standard listing device ($STDLIST).

When the (edited) command line is displayed, you may edit the line interactively. REDO displays the command line and accepts further edits repeatedly, until you signal completion by entering a Return only. At this point, the CI executes the edited version of the command.

If you omit editstring, then you are given the opportunity to edit the command line interactively, after which the command is reexecuted.

If you specify editstring, it must appear, character for character, and space for space, exactly as it would if you were using the REDO command in interactive mode.

The edit string must be surrounded by quotation marks (" ") if it contains any scanner/parser delimiters such as: , ; " ' [ ] or = or spaces.

Operation Notes

REDO executes the command specified as cmdid. The user may specify an optional editstring that edits the command before it is reexecuted. This command is a companion to the MPE/iX DO command. Unlike the DO command, the REDO command does permit interactive editing.

If editstring is specified, the edit is performed on cmdid before the command is presented for interactive editing. If editstring is omitted, then editing is interactive.

In either case, the (edited) line is echoed to $STDLIST before it is reexecuted. At this point, you may edit the line interactively. The interactive (editing) mode, remains available to you until you press only Return.

Both cmdid and editstring must be surrounded by either single or double quotation marks if they contain any delimiters such as , ; " " [, ], =, or a space.

The editing directives used in editstring are defined in Table 6-3.

Table 11-2 Editing Directives for the REDO Command

Directive Effect
iINSERT. If text follows the i, the text following i is inserted in the current line at the position after the i.
rREPLACE. If text follows the r, the text following r replaces the same number of characters in the current line, beginning at the position of r.
dDELETE. Deletes a character from the current line for each specified in the edit line. Note that "d d" does not specify a range but simply deletes one character from the position above each d. Multiple d's may be followed by an insert or replace operation.
dwDELETE WORD. Deletes a word starting at the letter d. A word is defined as all characters except a space, comma, or semicolon. If you place the d directly beneath a word delimiter, then the word and the delimiter characters are deleted. If no word exists on the command line, no delete occurs. You may follow this directive with other edits.
ddelimDELETE TO DELIMITER. Deletes all characters starting at the position of the d and ending at, but not including, the specified delimiter. If delim is not found, no delete occurs. You may follow this directive with other edits.
d>DELETE TO EOL. Deletes to the end of the current line from the position specified by d>. It may be followed by an INSERT or REPLACE operation.
^UPSHIFT. Upshifts the character positioned at the ^. You may specify multiple ^ characters to upshift a series of characters. Or, you may type multiple ^ characters, followed by spaces, then followed by more ^'s to upshift some characters while skipping others. You may follow this directive with other edits.
^wUPSHIFT WORD. Upshifts the word starting at the position specified by ^. A word is defined as all characters except a space, comma, or semicolon. If you place the ^ directly beneath a word delimiter, the delimiter is skipped and only the word is upshifted. If no word exists on the command line, no upshift occurs. You may follow this directive with other edits.
^delimUPSHIFT TO DELIMITER. Upshifts all characters starting at the position specified by the ^ and ending at, but not including, the specified delimiter. If delim is not found, no upshift occurs. You may follow this directive with other edits.
^>UPSHIFT TO EOL. Upshifts all characters starting from the position specified by the ^ to the end of the current line. You may follow this directive with other edits.
vDOWNSHIFT. Downshifts the character positioned at the v. You may specify multiple v's to downshift a series of characters. Or, you may type multiple v's, followed by spaces, then followed by more v's to downshift some characters while skipping others. You may follow this directive with other edits.
vwDOWNSHIFT WORD. Downshifts the word starting at the position specified by v. A word is defined as all characters except a space, comma, or semicolon. If you place the v directly beneath a word delimiter, the delimiter is skipped and only the word is downshifted. If no word exists on the command line, no downshift occurs. You may follow this directive with other edits.
vdelimDOWNSHIFT TO DELIMITER. Downshifts all characters starting at the position of the v and ending at, but not including, the specified delimiter. If delim is not found, no downshift occurs. You may follow this directive with other edits.
v>DOWNSHIFT TO EOL. Downshifts all characters starting from the position specified by the v to the end of the current line. You may follow this directive with other edits.
>textAPPEND. The > followed by text appends the text to the end of the current line. If > is positioned beyond the end of the current line, then a replacement is performed instead.
>dDELETE FROM EOL. Deletes from the end of the current line, right-to-left. Multiple d's may be specified after >, as well as INSERT and REPLACE strings.
>dwDELETE WORD FROM EOL. Deletes the last word in the command line. To find the last word, trailing word delimiters are skipped. If no word exists in the command line, then none is deleted. If you follow >dw with additional editing directives, each edit is performed recursively. That is, the first edit is performed (updating the current EOL), then the next edit is performed (again updating the current EOL), and so on.
>ddelimDELETE TO DELIMITER FROM EOL. Starting at the end of the current line, deletes all characters right-to-left up to, but not including, delim. If the delimiter is not found, no delete occurs. If you follow this directive with additional editing directives, each edit is performed recursively. That is, the first edit is performed (updating the current EOL), then the next edit is performed (again updating the current EOL), and so on.
>^UPSHIFT FROM EOL. Upshifts the character at the current EOL. You may specify multiple ^'s to upshift a series of characters (read right-to-left) from the EOL. Also, you may follow this directive with other edits.
>^wUPSHIFT WORD FROM EOL. Upshifts the last word in the command line. You may follow this directive with other edits.
>^delimUPSHIFT TO DELIMITER FROM EOL. Starting at the end of the current line, upshifts all characters right-to-left up to, but not including, delim. If the delimiter is not found, no upshift occurs. You may follow this directive with other edits.
>vDOWNSHIFT FROM EOL. Downshifts the character at the current EOL. You may specify multiple v's to downshift a series of characters (read right-to-left) from the EOL, and you may follow this directive with other edits.
>vwDOWNSHIFT WORD FROM EOL. Downshifts the last word in the command line. You may follow this directive with other edits.
>vdelimDOWNSHIFT TO DELIMITER FROM EOL. Starting at the end of the current line, downshifts all characters right-to-left up to, but not including, delim. If the delimiter is not found, no downshift occurs. You may follow this directive with other edits.
>rtextREPLACE. Replaces characters at the end of the command line. The replacement is done so that the last (rightmost) character of the replacement string is at the end of the line.
cCHANGE. Changes all occurrences of one string to another in the current line when the search string and replace string are properly delimited. A proper delimiter is a nonalphabetic character (such as ', ", / or ,). The substitution is specified as: c<delim>search-string<delim> [replace-string [<delim>]]. Omitting the replace-string causes occurrences of search-string to be deleted, with no substitution.
uUNDO. A single u in column one cancels the most recent edit of the current line. Using the UNDO command twice in a row cancels all edits for the current line and reestablishes the original, unedited line. If u is placed anywhere other than column one of the current line, then a simple replacement is performed. UNDO makes sense only if you have a line on which you have performed some editing that can be "undone."
otherSimple replacement. Any other character (not i, r, d, d>, >, >d, c, or u) causes that character to be replaced in the current line at the position indicated by the character. In fact, simple replacement also occurs for the editing characters i, r, c, or > if they are not followed by text; or if > appears at or beyond the current end of line.

Editing Samples

The Table 11-3 "REDO Editing Samples" shows examples of using the REDO command.

Table 11-3 REDO Editing Samples

Edit Action
uFirst occurrence undoes the previous edits. The u must be in column one.
uSecond occurrence undoes all edits on the current line. The u must be in column one.
rxyzReplaces the current text with xyz starting at the position of r.
xyzReplaces the current text with xyz starting at the position of x.
ixyzInserts xyz into the current line, starting at the position immediately before the i.
dddDeletes three characters, one above each d.
d xyzDeletes a single character above the d, skips one space, then replaces the current text with xyz starting at the position of x.
ddixyzDeletes two characters, then inserts xyz in the current line in the position before the i.
d dDeletes one character above the first d, skips two spaces, and deletes a second character above the second d. It does not delete a range of characters.
d d>xyzDeletes a single character above the first d, skips two spaces, and deletes to the end of the line beginning at the second d, and then appends xyz to the end of line.
>xyzAppends xyz to the end of the current line.
>ddxyzDeletes the last two characters from the end of the current line and then appends xyz to the end of the line.
>rxyzReplaces the last three characters in the current line with xyz.
>ixyzAppends xyz to the end of the line. In this case, the i command is superfluous, because > accomplishes the same result. Using >xyz would be sufficient.
c/ab/defChanges all occurrences of ab to def, starting at c.
c"ab"Deletes all occurrences of "ab" starting at c.
cxyzReplaces the current text with cxyz, starting at c. Because delimiters have been specified (as they were in the previous two examples), this is a simple replacement.
^wixUpshifts the word above the ^ and inserts an "x" at the end of the word it just upshifted.
v/abcStarting at the position of v, downshifts all characters up to, but not including, the "/", then replaces the "/" and the next two characters with "abc".
>dw^.dwDeletes the last word in the current line, recalculates the EOL, then upshifts all characters up to, but not including, the dot (.), then deletes the word to the left of the characters that were upshifted.

Use

This command is available in a session or in BREAK. It is not available in a job or from a program. Pressing Break aborts the execution of this command.

Examples

The following are examples of editing options for the REDO command:
REDO PAS

Edits the most recent command beginning with the string PAS.

REDO 10

Edits command number 10 (absolute) on the command history stack.

REDO -2

Edits the second-to-last command on the stack (one command before the most recent).

Related Information

Commands

DO, LISTREDO

Manuals

Using the HP 3000 Series 900: Advanced Skills

REFUSE

Disables jobs/sessions and/or data on a designated device.

Syntax


  REFUSE [JOBS,] [DATA,] ldev

Parameters

JOBS

Disables the JOB (or HELLO) command from the designated device.

DATA

Disables the DATA command from the designated device.

ldev

The logical device number of the device for which JOB (or HELLO) and DATA commands are refused.

Operation Notes

The REFUSE command prevents a device from automatically recognizing and accepting one or more of the three commands (JOB, HELLO, and DATA) users execute to introduce jobs or sessions. The JOBS parameter in the REFUSE command refers to both jobs and sessions. If neither the JOBS nor DATA parameter is supplied, both JOB (or HELLO) and DATA commands are refused. To undo the effect of the REFUSE command, use ACCEPT.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be executed only from the console unless distributed to users with the ALLOW or ASSOCIATE command.

Examples

To prevent logical device 35 from recognizing the DATA command, enter: 

  REFUSE DATA,35
To prevent both jobs and data recognition on logical device 35 enter: 

  REFUSE 35

Related Information

Commands

ACCEPT

Manuals

Performing System Operation Tasks (32650-90137)

RELEASE

Removes security provisions from a file. Security does not resume for a released file until you enter the SECURE command for the file.

Syntax


  RELEASE filereference

Parameters

filereference

Specifies the actual file designator of the file whose file access matrix access control you want to disable. The filereference can be either in MPE or HFS syntax.

MPE Syntax

If the filereference does not begin with a dot or a slash, it is parsed according to the MPE syntax and has the form: 


  filename[/lockword][.groupname[.acctname]]
If the file has a lockword, you must specify it; otherwise, the system prompts you for it. If you do not specify groupname.acctname, the system assumes the logon group and account.

HFS Syntax

If the filename begins with a dot (.) or a slash (/), it is parsed according to HFS syntax.

Operation Notes

  • Usage

    You can use this command only for permanent disk files you have created. Under default system security provisions, the file must be in your logon account and must belong to your logon or home group.

  • Checking the file status

    You can enter the LISTFILE command to determine if a file is currently released or secured. Refer to the LISTFILE command for more information.

  • Access control definition

    An access control definition (ACD) overrides file access controls whether or not you have released or secured the file.

    For more information about ACDs, refer to the ALTSEC command in this manual.

  • Unaffected access controls

    This command does not affect the following access controls:

    Privileged files

    You cannot release privileged files.

    Lockwords

    You cannot override lockwords.

    ACDs

    This command does not affect the security on files with access control definitions. However, if you remove the ACD, the file is released. Refer to the ALTSEC command in this book for more information about ACDs.

Use

You can enter this command from a session, a job, a program, or in BREAK. Pressing Break does not affect this command.

Example

  • To release all security provisions for a file named FILE1 in your logon group and account, enter: 

    
  :RELEASE FILE1
    If the system fails to locate the file, the following error message appears: 
    
  UNABLE TO ACCESS FILE1.GROUP1.ACCT1.  (CIERR 356)

Related Information

Commands

ALTSEC, LISTF, LISTFILE, SECURE, ALTLOG, CHANGELOG, GETLOG, LISTLOG, LOG, OPENLOG, RESUMELOG, SHOWLOGSTATUS, SWITCHLOG

Manuals

None

RELLOG

Removes a user logging identifier from the system.

Syntax


  RELLOG logid

Parameters

logid

The logging identifier to be removed from the system.

Operation Notes

The RELLOG command removes a user logging identifier from the system by deleting it from the directory of logging identifiers. This command may be issued only by the user who created the logging identifier. System supervisor (OP) or user logging (LG) capability is required to use this command.

After RELLOG is issued, programs containing the removed logging identifier are not allowed to access the logging system.

Use

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

Example

To remove the logging identifier DATALOG from the system, enter: 

  RELLOG DATALOG

Related Information

Commands

GETLOG

Manuals

User Logging Programmer's Guide

RENAME

Changes the file name, lockword, and/or group name of a disk file.

Syntax


  RENAME oldfilereference, newfilereference [;TEMP]

Parameters

oldfilereference

Current name of file, written in the format: 


  [*]filename[/lockword][.groupname[.acctname]]
To use HFS syntax, preceed the file name with a dot (.), or a slash (/).

newfilereference

New name of file, in the same format as oldfilereference. If you omit acctname and/or groupname, the logon account and/or group are assumed.

To use HFS syntax, preceed the file name with a dot (.), or a slash (/).

TEMP

Indicates that the old file was, and the new file will be, temporary files. If you do not specify TEMP, RENAME assumes that the files are permanent.

Operation Notes

The RENAME command changes the system file identification for a permanent or temporary disk file. You can use it to change the name of a file, to change the lockword of an MPE file, or to move any file to a different location.
MPE Files

To rename an MPE file, you must have DD access to the source MPE group and CD access to the target MPE group. If you specify groupname or acctname, you must have save access to the group or account. Users with System Manager (SM) capability can rename any file to any location on the system.

You can use RENAME to move native mode MPE files to HFS directories. You cannot move compatability mode MPE files to HFS directories. For example, you can use RENAME with KSAM/XL files, but you cannot use it to rename MPE V/E KSAM files.

To successfuly rename a file across group or account boundaries, you must move it within a single volume set and that volume set must be physically mounted.

When you use RENAME to move a file that does not have an ACD to a directory or to another account, an ACD is automatically created for the file to ensure that it is protected by the appropriate file access matrix of its new location.

HFS Files

To rename a file in an HFS directory, you must have delete directory entry access (DD) to the old directory and create directory entry access (CD) to the new directory.

Files in HFS directories can be renamed to files in the MPE account group structure, and they can be renamed to files in other HFS directories.

You cannot rename a directory. If either oldfilereference or newfilereference is actually a directory, you will get an error.

Spool Files

If you have access to spoolfiles, you can rename them. In this case, the name of the file changes, but the contents and links to the spooler remain the same.

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

Since temporary files exist only for the duration of your current job or session, their fully qualified file names correspond to your logon group and account. The following example shows the command entry to change the name of a temporary file from OLDFILE to NEWFILE, and reassign it to the group NEWG. 

  RENAME OLDFILE,NEWFILE.NEWG,TEMP
To change the lockword of the permanent file FILE2 from LOCKA to LOCKB, enter: 

  RENAME FILE2/LOCKA,FILE2/LOCKB
To transfer a file from one group to another within the same account, use the RENAME command, simply naming the new group in the second parameter. You must have SAVE access to GROUP2 and both groups must be in the system domain or reside on the same volume set. For example, to move the file MYFILE from GROUP1 to GROUP2, enter: 

  RENAME MYFILE.GROUP1,MYFILE.GROUP2
The following command renames the file dir2/doc/print.txt in the current working directory (CWD) to MYFILE in the group and account MYGROUP.MYACCT. 

  RENAME ./dir2/doc/print.txt, MYFILE.MYGROUP.MYACCT
The following command renames the file FILE1 in the PUB group to new_txt in the HFS directory dir1 under the root directory. 

  RENAME FILE1.PUB, /dir1/new_txt
The following command renames the KSAM XL file KSFILE in the PUB group to ksfile in the HFS directory dir1 under the root directory. 

  RENAME KSFILE.PUB, /dir1/ksfile

Related Information

Commands

BUILD, COPY, PURGE, PRINT

Manuals

None

REPLY/=REPLY

Replies to pending resource requests at the console.

Syntax


  REPLY pin, reply
  =REPLY pin, reply

Parameters

pin

The process identification number (PIN) of the message sender. As part of the message requesting the REPLY, the PIN always appears after the second slash mark (/). In the following example, the PIN is 43. 


  ?16:15/#S25/43/LDEV# FOR "T" ON TAPE (NUM)?

reply

The reply type specified in parentheses in the message, defined by one of the following:

(NUM)

Reply must be a logical device number.

(Y/N)

Reply must be either YES (or Y) or NO (or N).

(MAX CHARS.=nn)

Reply must be a string expression consisting of nn characters or less.

Operation Notes

User programs that have requested the use of a device and are waiting for you to reply remain suspended indefinitely and cannot be aborted until a REPLY or a Break/ABORT is issued. If for any reason you cannot reply as requested (for example, if the particular device is nonexistent or a special form is unavailable), then use REPLY/=REPLY with 0 if type NUM is requested, or with N if type Y/N is requested. This returns an error code to the program and the REPLY/=REPLY is aborted.

The reply usually takes the form (NUM) or (Y/N), since (MAX CHARS.=nn) is used only for labeled tapes and the PRINTOPREPLY intrinsic.

If your reply is not of the type specified, an error message is displayed.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be issued only from the logical console, unless distributed to specific users with the ALLOW or ASSOCIATE command.

The Ctrl-A =REPLY command can be used only from the physical console. It cannot be executed from a job or a program.

Examples

Use the REPLY command to respond to a message from the MPE/iX system, as follows: 

  10:05/#J19/15/LDEV# FOR "NAS" OF TAPE1600 (NUM)?
  REPLY 15,7
or 

   CTRL-A
   =REPLY 15,7
Use the REPLY command to respond to a FORMS message from the MPE/iX system, as follows: 

  15:46/#S93/22/FORMS: PLEASE MOUNT MAILING LABEL FORMS
  ?15:46/#S39/22/SP#12/LDEV# FOR #S93;OUTFILE ON LP (NUM)?
  REPLY 22,12
  15:46/#S39/22/LDEV#12 FORMS ALIGNED OK (Y/N)?
Answering NO causes the printing to be deferred to a much lower priority. After the forms have been aligned, use the ALTSPOOLFILE command to change the spooling priority, in order to send the spoolfile to the printer. 

  REPLY 22,NO
  15:48/#S93/22/LDEV#12 FORMS ALIGNED OK (Y/N)?
Answering YES causes the spoolfile to go to the printer in its assigned sequence.

When the next spoolfile becomes ACTIVE, you are requested to mount the appropriate special or standard forms.

To reply to a standard forms request, enter: 

  16:00/#S93/22/STANDARD FORMS
  ?16:00/#S93/22/LDEV # FOR #S95;L ON LP (NUM)?
  REPLY 22,12

Related Information

Commands

RECALL

Manuals

Performing System Operation Tasks
System Startup, Configuration, and Shutdown Reference Manual

REPORT

Displays accounting information for the logon account and group. Any user may obtain REPORT information about the user's logon group. (Compatibility Mode)

Syntax


  REPORT [groupset] [,listfile] [;ONVS=[volumesetname]]

Parameters

groupset

Specifies the accounts and groups for which information is to be listed. The permissible entries, some of which use wildcard characters, and their capability requirements such as account manager (AM) and/or system manager (SM) are listed below:

group

Reports on the specified group in the logon account. This is the default for standard users, who may specify only their logon group.

@

Reports on all groups in the logon account. This is the default for account managers, but may be executed by users with AM or SM capability.

group.acct

Reports on the specified group in the specified account. This requires SM capability.

@.acct

Reports on all groups in the specified account. This requires AM capability (if it is the logon account) or SM capability for any account.

@.@

Reports on all groups in all account totals. This is the default for system managers and requires SM capability.

ONVS= should always be used when @.@ is used as the groupset parameter.

group.@

Reports on specified group in any account. This requires SM capability.

You may use the wildcard characters, @, #, and ? to specify a set of names.

@

Specifies zero or more alphanumeric characters. Used by itself, it specifies all possible combinations of such characters. Used with other characters, it indicates all the possible names that include the specified characters (@ABC@ = all names that include ABC anywhere in the name).

#

Specifies one numeric character (A###@ = all names that begin with A followed by any three digits, followed by any combination of zero to three alphanumeric characters).

?

Specifies one alphanumeric character (A?# = all the three-character names that begin with A, followed by an alphanumeric, followed by a digit.)

The characters may be used as follows:

n@

Report on all groups starting with the character "n".

@n

Report on all groups ending with the character "n".

n@x

Report on all groups starting with the character "n" and ending with the character "x".

n##``...#

Report on all groups starting with the character "n".

?n@

Report on all groups whose second character is "n".

n?

Report on all two-character groups starting with the character "n".

?n

Report on all two-character groups ending with the character "n".

These characters, when placed appropriately in the groupset parameter, may also be used to report on accounts.

listfile

Actual file designator of the output file to which information is to be written. The default is $STDLIST, but output may be redirected with a FILE equation as follows: 


  FILE LIST1;DEV=LP
  REPORT, *LIST1

volume-setname

Instructs MPE/iX to report account information for the specified volume set. If this parameter is omitted, the default is the MPE/iX system volume set. Refer to "Operation Notes."

Operation Notes

The REPORT command displays the total resource usage logged against accounts and groups, and the limits on those resources. For standard users, data is displayed for their own group(s) only; account managers may specify all groups in their account; system managers may specify any or all groups in any or all accounts.

The information includes usage counts and limits for permanent file space (in sectors), CPU-time (in seconds), and session connect-time (in minutes). The file space usage count reflects the number of sectors used at the time the REPORT command is issued. However, CPU-time and connect-time usage appear as they were immediately before the beginning of the current session. CPU-time and connect-time contain non-zero values only when the MPE/iX system volume set is specified (either in the ONVS= parameter or by default when ONVS= is not used). CPU-time and connect-time are displayed as zero for non-system volume sets.

If you specify the ONVS= parameter, REPORT displays file space counts for the specified volume set(s) only. If you specify a non-system volume, all other volume names are also displayed, but their file space counts are displayed as zero even though they may not be zero. You should always specify ONVS= when @.@ is the groupset parameter.

If data for the MPE/iX system volume set is requested (either with or without the ONVS= parameter), file space counts are displayed for all volume sets (both system and non-system). However, the account total display reflects only file space in the MPE/iX system volume set.

If you specify volume-related commands or parameters for a volume set that is not currently mounted, or for an account that does not exist, MPE/iX returns an error message.

MPE/iX uses a naming convention for volume sets that differs from the MPE V/E naming convention for private volumes. As a convenience to established Hewlett-Packard users, MPE/iX does, however, accept the naming convention that was used for MPE V/E private volumes. Refer to the VSRESERVE or VSRELEASE commands in this chapter.

For information on migrating files from MPE V/E private volumes to MPE XL mountable volume sets, please refer to the chapter on DIRMIG in the Migration Process Guide.

NOTE: The REPORT does not produce the same output as DISCFREE because REPORT does not account for disk space taken up by objects such as directory files and label tables. To determine how much space is taken up by other objects, issue the FSCHECK TOTALEXTENTS command.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break aborts the execution of this command. Account manager (AM) capability is required to issue the command for an entire account, or system manager (SM) capability to issue the command for the entire system.

Example

To obtain the display of account information for the group, SOPRM, enter: 

  REPORT SOPRM
  ACCOUNT       FILESPACE-SECTORS     CPU-SECONDS    CONNECT-MINUTES
   /GROUP       COUNT    LIMIT    COUNT    LIMIT    COUNT    LIMIT
  SOPRM         13599       **    30144       **    17258       **
   /GLOSSARY     1068       **      542       **      656       **
   /PUB           182       **      123       **     1155       **
   /SECT1         180       **       85       **      429       **
   /SECT10      11779       **    25271       **     9716       **
   /SECT2         390       **     4123       **     5302       **

Related Information

Commands

VSCLOSE, VSOPEN, VSRELEASE, VSRESERVE, VSRESERVESYS, VSTORE, VSUSER, RESETACCT, DISKUSE, DISCFREE Utility, LISTFILE

Manuals

Volume Management Reference Manual

RESET

Cancels file equations.

Syntax


  RESET { formaldesignator | @ }

Parameters

formaldesignator

A formal file designator name in the form file[.group[.account]] [:nodespec], for which a FILE command has been issued. The nodespec portion may be an environment identifier indicating the location of the file, or it may be $BACK. Specifying $BACK means that the file resides one "hop" back toward your local system (which may be the local system itself).

@

Signifies all formal file designators specified in all FILE commands previously issued in this session or job.

Operation Notes

The RESET command resets a formal file designator to its original meaning, canceling any FILE command that has been issued for this formal file designator earlier in the current session or job.

NOTE: The nodespec 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 nodespec parameter is optional. If you do not have NS3000/XL AdvanceNet, omitting the nodespec parameter makes no difference in the performance of the RESET command, however, specifying it does produce an error message.

Use

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

Example

To cancel the effects of a previous FILE command that specified characteristics for a file programmatically referred to as ALPHA enter: 

  RESET ALPHA

Related Information

Commands

FILE, LISTEQ

Manuals

None

RESETACCT

Resets the running counts of CPU-time or connect-time accumulated by an account and by all groups within that account to zero.

Syntax


  RESETACCT [{ @ | acct } [,{ CPU | CONNECT }]]

Parameters

@

Specifies that the counters for all accounts, and all groups within the accounts, are to be reset. Default.

acct

Specifies the name of a particular account, and all groups within the account are to be reset.

CPU

Specifies that only the CPU usage counter is to be reset. Default is that both the CPU-time and connect-time counters are reset.

CONNECT

Specifies that only the connect-time usage counter is to be reset. Default is that both the CPU-time and connect-time counters are reset.

Operation Notes

This command resets the running counts of CPU-time or connect-time accumulated by an account and by all groups within that account to zero. If all parameters are omitted when you execute RESETACCT, all counters (except file space) for all groups in all accounts are reset.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. System manager (SM) capability is required to execute this command.

Example

To reset the CPU counter for all accounts in the system, enter: 

  RESETACCT @,CPU

Related Information

Commands

REPORT

Manuals

None

RESETDUMP

Disarms the debug facility call that is made during abnormal process termination. (Native Mode)

Syntax


  RESETDUMP

Parameters

None

Operation Notes

This command disarms the debug facility (armed by using the SETDUMP command) after a process abort. It affects all processes created later under the current session or job.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. Issuing this command in BREAK does not affect existing processes.

Example

To disarm the stackdump/debug facility enter: 

  RESETDUMP

Related Information

Commands

DEBUG, SETDUMP

Manuals

System Debug Reference Manual

RESTORE

Returns files that have been stored on backup media to the system.

Syntax


  RESTORE [restorefile] [;filesetlist] [;option [;...]]
    [;SHOW [=showparmlist]] [;ONERROR= { QUIT | SKIP | FULL }]
    [;{ LOCAL | GROUP=groupname [;...] | ACC[OUN]T=accountname }]
    [;CREATE [= { ACCT | GROUP | CREATOR | PATH }]]
    [;CREATOR [=username]] [;GID [=filegroupname]]
    [;{ KEEP | NOKEEP }] [;{ OLDDATE | NEWDATE }]
    [;DIRECT0RY] [;LISTDIR]
    [;PROGRESS [=minutes]]
    [;FCRANGE=filecode/filecode [,...]] [;FILES=maxfiles]
    [;DEV=device]
    [;VOL=volumename] [;VOLCLASS=volumeclassname]
    [;VOLSET=volumesetname]
    [;COPYACD] [;NOACD] [;TREE] [;STOREDIR[ECTORY] = directoryname]
    [;PARTI[IAL]DB] [;RESTORESET=(device [,...])]
The following parameters are available with TurboStore/iX and TurboSTORE/iX True-Online Backup products only: 

  [;RESTORESET=(device [,...]) [,(device [,...]) [,...]]]
  [;MOSET=(ldev [,...]) [,(ldev[,...]) [,...]]]
  [;NAME=backupname]

Parameters

restorefile

The name of the device that contains the files you want restored to the system. This file must be backreferenced, using an asterisk (*). A File equation for restorefile should be set up before invoking RESTORE. If you want to restore files from a file called SOURCE enter this file equation before running RESTORE: 


  FILE SOURCE;DEV=TAPE
The restorefile can now reference a remote device. For example, 

  FILE REMOTE;DEV=REMSYS#TAPE
  RESTORE *REMOTE;@;SHOW
NM RESTORE will restore all files from the specified remote device. Although the initial tape mount request will appear on the remote console, all of RESTORE's console messages will be displayed on the local console. Currently, labeled tapes and Magneto-optical devices cannot be used for remote backup.

A message is displayed on the system console requesting the operator to mount the tape identified by the restorefile parameter and to allocate the device.

If restorefile is not supplied and the RESTORESET option is not used, then RESTORE creates a default file name. The default file name is the user's logon username. No file equation is used.

Sequential and parallel devices are specified with the RESTORESET option. Similarly, magneto-optical devices are specified using the MOSET option. You should not specify restorefile when using RESTORESET or MOSET.

A disk file can also be specified with a file equation for restorefile. An example of such a file equation would be: 


  :FILE MYDISC=DISCBACK.DAILY.BACKUP;DEV=DISC
Note that DEV=DISC must be specified for RESTORE to recover files from disk backups. All other information in the file equation will be ignored by RESTORE.

NOTE: TurboSTORE/iX 7x24 True-Online Backup must be used to create disk backups.

filesetlist

Specifies the set of files to be restored. The default depends on the user's capability, as shown below:

Default

Capability

@

None

@.@

Account manager (AM)

@.@.@

and/or system supervisor (OP)

The filesetlist parameter has the form shown below: 

  filesetitem [,filesetitem [...]]
where filesetitem can be ^indirectfile or fileset.

indirectfile

A file name that backreferences a disk file. The syntax is

^indirectfile or !indirectfile

This file may consist of fileset(s) and option(s), but only options can appear after the first semicolon (:) on each line. An option specified on one line will operate on all files in the filesetlist.

^indirectfile is the preferred format. If you use !indirectfile, the CI will interpret this as a variable reference, so you will have to specify indirectfile instead.

fileset

Specifies a set of files to be restored, and optionally those files to be excluded from the RESTORE operation. The fileset parameter has the form: 


  filestorestore [-filestoexclude [...]]
The system restores any file that matches filestorestore unless the file also matches filestoexclude, which specifies files to be excluded from the RESTORE operation. You may specify an unlimited number of filestoexclude.

Since "-" is a valid character for HFS syntax file names, a blank character must separate it from HFS file sets to obtain the special negative file set meaning.

filestorestore
filestoexclude

Both filestorestore and filestoexclude may be entered in MPE or HFS syntax. Wildcards are permitted for both MPE and HFS syntax.

The MPE syntax is as follows: 


  filename[.groupname[.accountname]]
A lockword may be specified for files to be restored, in the form: 

  filename/lockword.group.account
The HFS syntax is as follows: 

  /dir_lev_1/dir_lev_2/.../dir_lev_i/.../filedesig
or 

  ./dir_lev_i/dir_lev_j/.../dir_lev_k/.../filedesig
If the name begins with a dot (.), then it is fully qualified by replacing the dot with the current working directory (CWD).

Each of the components dir_lev_i and filedesig can have a maximum of 255 characters with the full path name being restricted to 1023 characters. Each of the components dir_lev_i and filedesig can use the following characters:

  • Letters a to z

  • Letters A to Z

  • Digits 0 to 9

  • Special characters - _ .

For HFS syntax, the lowercase letters are treated distinctly from the uppercase letters (no upshifting). Names in MPE syntax are upshifted.

Both MPE and HFS name components can use the characters @, #, and ? as wildcard characters. These wildcard characters have the following meaning:

@

specifies zero or more alphanumeric characters.

#

specifies one numeric character.

?

specifies one alphanumeric character.

These wildcard characters can be used as follows

n@

Restore all files starting with the character n.

@n

Restore all files ending with the character n.

n##...#

Restore all files starting with character n followed by up to seven digits (useful for storing all EDIT/3000 temporary files).

n@x

Restore all files starting with the character n and ending with the character x.

?n@

Restore all files whose second character is n.

n?

store all two-character files starting with the character n.

?n

Restore all two-character files ending with the character n.

Also, character sets may be specified in the following syntax:

[ct]

specifies letter c or t.

[c-t]

specifies any letter from range c to t.

[e-g1]

specifies any letter range e to g or digit 1.

Examples of using character sets are:

[A-C]@

Restore all files that begin with the letters A, B, or C.

myset[e-g1]

Restore all files that begin with the name myset and end in e, f, or g, or 1.

myset
[d-e1-6]

Restore all files that begin with the name myset and end in d or e, or 1, 2, 3, 4, 5, or 6.

You may specify up to a maximum of sixteen characters for each character set and you may not nest brackets.

A character set specifies a range for only one (1) ASCII character. The range [a-d]@ gets all files that begin with the letter a through the letter d. The ranged [ad-de] may cause unpredictable results.

Since the hyphen (-) is a valid character for HFS syntax file names, it is allowed inside a character set, immediately following a left bracket ([) or preceding a right bracket (]). When specified between two characters, the hyphen implies a range of characters.

Specifying Database Files

When specifying TurboIMAGE and ALLBASE/SQL databases to be restored, only the root file or DBCon file needs to be specified. RESTORE will determine which other files belong to that database, and will restore all of them. If dataset file(s) are specified without specifying a root file, then a warning will be printed for each file, and they will not be restored. Individual database files can be restored without the root file by specifying the ;PARTIALDB option on the RESTORE command line.

Database corruption may result if not all database files are restored from a backup. Be sure that you only want to restore certain database files before overriding the default behavior with ;PARTIALDB.

MPE and HFS Naming Equivalences

When an MPE name component is a single @ wildcard, the @ will be "folded" to include all MPE and HFS named files at that level and below. To specifiy only MPE-named files, use ?@ instead.

MPE wildcards are not expanded in filestoexclude. This means that @.@.@-@.@.@ is NOT an empty fileset. It contains all of the HFS named files on the system.

A fileset may be entered in any of the following formats and may use wildcard characters. Equivalent MPE and HFS formats are grouped together as follows.

file.group.acct/ACCT/
GROUP/FILE

One particular file in one particular group in one particular account.

file.group/LOGON-
ACCT/GROUP/FILE

One particular file in one particular group in the logon account.

file
./FILE

One particular file in the logon group and account.

@.group.acct
/ACCT/GROUP/

All files (MPE and HFS) in one particular group in one particular account.

?@.group.acct

All MPE name files in one particular group in one particular account.

@.group/LOGON-
ACCT/GROUP/

All the files (MPE and HFS) in one particular group in the logon account.

?@.group

All MPE named files in one particular group in the logon account.

@.@.acct
/ACCT/

All the files (MPE and HFS) in all the groups in one particular account, plus all the files and directories under the specified account.

thisisit.@.account

Any MPE file named thisisit in all groups in one particular account.

?@.@.acct

All MPE named files in all the groups in one particular account.

@

All (MPE and HFS) files in the CWD. This is the default for everyone, regardless of permissions.

@.@

All (MPE and HFS) files in the logon account.

@.@.@

All the files and directories (MPE and HFS) on the system.

?@.@.@

All MPE named files on the system.

SHOW

Request to list names of restored files. Default is a listing of the total number of all files restored and not restored. For files not restored, the reason and the names are listed. This listing is sent to $STDLIST (formal designator SYSLIST) unless a FILE command is entered to send the listing to some other device. For instance, the following file equation entered before the RESTORE command would send the listing to a line printer: 


  FILE SYSLIST; DEV=LP

showparmlist

Tells RESTORE what information to display for the files that are restored. If you specify ;SHOW and omit showparmlist, then the default is SHORT if the recordsize of SYSLIST is less than 132 characters, or LONG if the recordsize is equal to or greater than 132 characters. The format for showparmlist is: 


  showparm [,showparm[,showparm[,...]]]
where showparm may be one of the options described below. If you do not specify SHORT or LONG, then the base information is SHORT if SYSLIST is less than 132 characters, or LONG if SYSLIST is 132 or more characters.

NOTE: If an HFS-named file is specified in the filesetlist, or the expansion of a wildcard includes a HFS-named file, then a HFS-style output listing will be used. This listing shows the same information as the MPE format, but puts the name of the file at the right end of the listing, to allow for longer HFS names. If a HFS name is too long to fit in the record size of the output file, it will be wrapped onto the next line. Wrapping is signified by a "*" as the last character on the line.

showparm

SHORT

Overrides the LONG display to show file, group, and account name or the fully qualified path name, volume restrictions, file size (in sectors), file code, and media number.

LONG

Overrides the SHORT display to show all the information that SHORT does plus the ending reel number, record size, blocking factor, number of extents, EOF, and file starting and ending media number. For spoolfiles, the old spoolfile name is also displayed.

NAMESONLY

Displays only the filename and the starting and ending media number. You cannot use NAMESONLY with SHORT or LONG.

DATES

Displays the creation date, the last date of access, and the last date of modification.

SECURITY

For MPE format listing, causes SHOW to display the creator and the file access matrix for all the files which do not have an active ACD. For files with active ACDs only, the phrase *ACD EXISTS* is displayed.

For HFS format listing, the phrase *ACD EXISTS* or *ACD ABSENT* is displayed, depending on whether the file has an ACD.

PATH

Forces all file listings to be in HFS format. Full HFS pathnames are displayed instead of MPE style names.

OFFLINE

Sends another copy of the SHOW output to the formal file designator OFFLINE, which defaults to device LP.

ONERROR

Tells RESTORE what to do if there is a tape read error. If you omit this parameter, then the default option is QUIT for labeled and unlabeled tapes. ONERR is a synonym for ONERROR.

QUIT

Tells RESTORE to abort after a tape read error.

SKIP

Tells RESTORE to perform a file-skip-forward past a tape error, resynchronize, and resume reading from the tape.

FULL

Tells RESTORE to restore a file even if a media error occured while reading the file's data. SM or OP capability is required to specify this option. A file can be partially restored, with "holes" where missing data would be. Warnings are issued on the RESTORE listings for all files that are partially restored. In the summary of files restored at the end of the listing, there is a total count of all partially restored files.

The use of this option could lead to corrupted copies of files. You should only use it as a last resort, when there is no other way to recover file data. It should NEVER be used as the default ONERROR option.

LOCAL

Specifies that files will be restored regardless of the system's directory structure. The files will be restored in the user's current working directory. The creator will be changed to the current user.

GROUP= groupname

Specifies that the files being restored will be restored to an existing group identified as groupname. If you specify LOCAL, you cannot specify groupname.

ACCOUNT= accountname

Specifies that the files being restored will be restored to an existing account identified as accountname. If you specify LOCAL, you cannot specify accountname.

CREATE

Allows you to restore files whose group, account, or creator does not yet exist in the system's directory. The account and groups will be created with default capabilities.

If no suboptions are specified, then CREATE defaults to ACCOUNT,GROUP,CREATOR,PATH for SM or OP, to GROUP,CREATOR,PATH for AM, and to PATH for everything else.

If CREATE is specified, the necessary directory structures are created, provided the user has the appropriate capabilities. System Manager (SM) or System Supervisor (OP) capability is needed for account, group, and user creation. Account Manager (AM) capability is needed for group and user creation.

GROUP

Instructs MPE/iX to examine the file label of the file being restored and create the group that it finds named in the file label. The user must have Account Manager (AM), System Manager (SM), or System Supervisor (OP) capability.

ACCOUNT

Instructs MPE/iX to examine the file label of the file being restored and create the account that it finds named in the file label. The user must have system manager (SM) or system supervisor (OP) capability .

CREATOR

Instructs MPE/iX to examine the file label of the file being restored and create the creator that it finds named in the file label. The user must have the appropriate capabilities: AM, SM, or OP if the user is in the logon account; SM or OP for users outside the logon account. If the CREATOR=username parameter is specified, that creator identification will be used, instead of the user in the file label.

If CREATE=CREATOR is not used, the default behavior is: If the creator of the file is not found in the system directory, the file will not be restored. You will get an error message telling you that the creator does not exist In order to restore this "orphan" file, you must use the CREATOR option or the CREATE option.

Refer to the "EXAMPLES" section for this command.

PATH

Instructs RESTORE to create the hierarchical portion of the path necessary to restore the files. The user must have the appropriate access capabilities. Read and traverse access is required over the path and insert entry access is required for the node where the next entry is being created. If the path information information exists on the media then the path is created using the information. Otherwise, a default ACD and the restoring process' uid/gid are used. Note that the suboptions ACCOUNT and GROUP are required to get the accounts and groups created, respectively.

CREATOR= username

All files will have their creator identifications changed to the specified user name. If username does not exist, then the file is not restored, unless CREATE is specified.

If CREATOR=username is not specified, the creator in is determined from the file label as it appears on the tape.

GID

Changes the file gid to the supplied file group name. If filegroupname is omitted, then the gid present on the media is preserved. This option overrides the account and local options with respect to the gid changes.

filegroupname

The file sharing group name which will be the new gid for all files being restored. If this parameter is not specified then the gid on the media is preserved.

KEEP

If a file on the RESTORE media has the same name as a file already residing on the disk, KEEP instructs the system to preserve the file on the disk and to skip over the file on the RESTORE media. The file on tape is not restored and the file on the disk remains as it was.

If you do not specify KEEP, then the file on the RESTORE media replaces the identically named file on the disk. The only exception is if the file on the disk is being accessed when RESTORE attempts to replace it. In that case, RESTORE preserves the file on the disk (as if you had specified KEEP) and skips over the file on the backup.

NOKEEP

Instructs the system to restore every file on the tape, even if it has the same name as a file already residing on the disk. This is the default.

NEWDATE or OLDDATE

STORE and RESTORE maintain four times and dates for each file: the creation date, modification date, last access date, and the state change date. NEWDATE changes all dates and times to the date and time that RESTORE was executed. OLDDATE retains all dates and times from the date of the store procedure. The default is NEWDATE.

DIRECTORY

Instructs RESTORE to restore all the volume set directories on the media. You must have system supervisor (OP) or system manager (SM) capability to use this parameter. All HFS directories on the media will also be restored. When RESTORESET option is used with DIRECTORY, please restore the directories first if they are not already on the system with "RESTORE ;;DIRECTORY" command before restoring the files with the RESTORESET option.

PROGRESS

Instructs RESTORE to report its progress at regular intervals by displaying the message RESTORE OPERATION IS nnn% COMPLETE. For interactive users, this message is displayed on $STDLIST. For jobs, this message is sent to the system console.

minutes

A positive number specifying the number of minutes between progress messages. The maximum is 60. The default is 1 (one) minute.

LISTDIR

This option may not be specified with any other option, other than DIRECTORY. It displays information from the tape directory and tape label, but does not restore any files. The type of tape created, the record size, and any files that match your filesetlist are displayed. If specified with DIRECTORY, the names of the all volume set directories and all HFS directories on the media are also displayed. The security restrictions that apply to filesetlist also apply here. The output goes to SYSLIST.

The LISTDIR option applies only to NMSTORE tapes. It cannot be used for MPEv format tapes.

FCRANGE

The set of file code ranges that are to be restored.

filecode/filecode

A file code range. A filecode is an integer between -32768 and 32767. FCRANGE=1000/1040 would restore only those files having file codes between 1000 and 1040. You may specify a maximum of eight file code ranges.

FILES= maxfiles

If you are restoring a large number of files from an MPE V/E (transport) tape, specify a number at least as large as the number of files to be restored. The default is 4000.

This parameter is ignored when you are restoring MPE XL format store tapes. No limit is imposed.

When a FILES= option is put in an indirect file, it is ignored.

DEV= device

Specifies the device on which the restored files are to reside. It takes one of two forms:

devclass

Specifies the type of device. The file is allocated to the home volume set (within the specified device class) of the group into which it is being restored.

ldn

Specifies a particular logical device number (ldn) corresponding to a particular device. The file will be allocated to that device only if one of the volumes in the home volume set (of the group into which a file is being restored) currently occupies the device.

By default, MPE/iX attempts to restore the file on a logical device compatible with the type and subtype specified in the file's file label and with the type and subtype of the mounted home volume set (of the group into which a file is being restored). If this fails, an attempt is made to restore the file on the same device class as specified in the file's file label and that of the mounted home volume set (of the group into which a file is being restored). If this fails, an attempt is made to restore the file on any member of the home volume set (of the group into which a file is being restored). If this fails, the file is not restored.

You cannot use DEV with the VOLSET, VOLCLASS, or VOL options.

VOL

The volume on which the restored files are to reside. If there is no room on this volume, the device restrictions will default to the volume's class; if this fails, it will default to the volume's set; if both fail, the files will not be restored.

volumename

A volume name. If no VOLCLASS or VOLSET options are specified, volumename must reside on the system volume set.

VOLCLASS

The volume class on which the files are to reside. If there is no room on this volume class, the device restrictions will default to the volume class's volume set; if this fails, the files will not be restored.

volumeclassname

A volume class name. If no VOLSET options are specified, volumeclassname must reside on the system volume set.

VOLSET

Specifies the volume set on which the files are to reside. If the specified directories do not exist on that volume set, the file(s) will be restored to the specified group and account.

volumesetname

A volume set name. If you specify the VOL or VOLCLASS options, the corresponding volume/volume class name must reside within this volume set.

Volume Set Notes

VOLSET, VOLCLASS and VOL may not be used with the DEV option.

You can inadvertently restore files to groups or accounts that you did not intend. This can happen if the accounting structure of the files you are restoring does not match the accounting structure of the target volume, volume class, or volume set. For instance, if you restore files to VOLSET=joes_vs (assume that joes_vs exists) but the accounting structure of those files does not exist on joes_vs, the files will be restored to the volume set where the group and account exist. This may not be where you intended them to go. The system does not prevent this, so you must use caution.

MPE/iX volume sets are not compatible with MPE V/E private volumes, and MPE XL introduces a new naming convention for volume sets. Refer to the VSRESERVE and VSRELEASE commands.

COPYACD

Directs RESTORE to copy the ACD associated with the files or directories from the media. This option is on by default.

NOACD

Directs RESTORE not to copy the ACD associated with the files or directories from the media. This option overrides the default COPYACD option.

TREE

Forces every HFS syntax file set to be scanned recursively, irrespective of the slash specified or not at the end of the file set.

NOTREE

Forces every HFS syntax file set not to be scanned recursively irrespective of the slash specified or not at the end of the file set. NOTREE yields a horizontal cut in the hierarchical directory.

STOREDIRECTORY

Specifies that RESTORE should use the supplied directoryname when looking for the disk store directory file. This option should be specified if the disk directory file for this backup resides in a directory other than the default path of /SYS/HPSTORE/store_dirs/. If a disk directory file exists in the default directory for this backup, the STOREDIRECTORY option does not need to be specified. The user needs to have access permissions to the STOREDIRECTORY path and the STORE directory file.

directoryname

The name of the disk directory file to be used by RESTORE. It can be in either MPE or HFS format. If it is not a fully qualified filename, it will be qualified by the CWD. This file should either be a disk directory file created by STORE or a symbolic link pointing to one.

PART[IAL]DB

Allows RESTORE to restore individual database dataset files without specifying the database's root or DBCon file.

Database corruption may result if not all database files are restored from a backup. Be sure that you only want to restore certain database files before overriding the default behavior with ;PARTIALDB.

THE FOLLOWING OPTIONS ARE AVAILABLE ONLY IF TURBOSTORE XL OR TURBOSTORE XL II IS INSTALLED ON YOUR SYSTEM. TURBOSTORE IS NOT PART OF THE FUNDAMENTAL OPERATING SYSTEM, BUT MAY BE PURCHASED SEPARATELY.

For additional information on TURBOSTORE XL, refer to the Store and Turbostore/iX Manual (30319-90001).
RESTORESET

Specifies parallel and sequential backup devices. This option cannot be use if the restorefile parameter is specified.

When DIRECTORY option is used with RESTORESET, please restore the directories first if they are not already on the system with "RESTORE ;;DIRECTORY" command before restoring the files with the RESTORESET option.

Consecutive tapes are specified in the following way: 


  ;RESTORESET = (*tape1,*tape2,*tape3,...)
This instructs MPE/iX to use only one drive at a time for the restore. When the first reel of tape is exhausted, RESTORE will shift to the next available drive, leaving the first free for rewinding and changing reels. Thus, at any given time, only one drive is restoring files and the effect is to accelerate the restore process.

In the following example, all three tapes will be used in parallel during the restore: 


  ;RESTORESET=(*tape1),(*tape2),(*tape3)...
In the following example, sets of tapes are used sequentially for the restore. Two tapes would be restoring at any particular moment, while the other two are rewinding so that the operator may switch reels. 

  ;RESTORESET=(*tape1,*tape2),(*tape3,*tape4)
This option cannot be used if the restorefile parameter is specified.

device

Specifies the device from which the file is to be restored. It must be a magnetic tape or DDS. This device should be specified in a file equation before you invoke the RESTORE command, ie: 


  FILE DEVICE;DEV=TAPE
This file equation can also specify a remote device or a disk file.

MOSET

Specifies parallel Magneto Optical (MO) backup devices. This option is not available if the storefile option is specified.

Parallel devices are specified by either of the two following commands: 


  ;MOSET = (12),(13),(15)
  ;MOSET = (MO),(MO),(MO)
All MO devices are used in parallel during the restore. The preferred format is specifying just "MO", since RESTORE will use the the NAME parameter to locate the correct media.

This option is not available if the restorefile option is specified.

NAME

This parameter must be specified with the MOSET option, and cannot be specified without it. If specifies the logical name to be used for the backup. For example: 


  RESTORE @.@.@;;MOSET=(12);NAME=DAILY.D23OCT90.BOZO
This name could indicate that the restore should be taken from the daily backup done on 23 Oct 1990 on the system called BOZO.

backupname

A three field name of a total maximum length of 26 characters. The format is fname.gname.aname. The name represents the "handle" to this particular backup and can is used to retrieve files from this backup. The fname, gname and aname can be up to 8 alphanumeric characters. For example DAILY.D24OCT90.SYSTEM.

Operation

This command restores data into the system (on disk), from a file or files previously stored by the STORE command. A message is shown on the system console requesting the system operator to mount the device(s) identified by the restorefile parameter or the RESTORESET option, and to allocate the device(s).

No message is displayed if AUTOREPLY is configured through SYSGEN.

  • Command process

    The output generated by RESTORE is sent to a file whose formal designator is SYSLIST. Any errors encountered during the restore will be reported to SYSLIST (and optionally OFFLINE). The ONERR option determines if RESTORE will continue after encountering an error restoring a file. Any file belonging to a group whose home volume set has not been mounted will not be restored.

    If you are restoring files that were stored on a large MPE V/E tape or disk, such as a SYSGEN tape, you must include the maxfiles parameter. Specify a number at least as large as the number of files to be restored. The default is 4000.

  • Required capabilities for restoring files

    Your capabilities determine which files you may restore. If you have system manager or system supervisor capability, you can restore any file from a store tape, assuming the account and group to which the file belongs, and the user who created the file, are defined in the system. If you have account manager capability, you can restore any file in your account. To restore files with negative file codes, you need Privileged Mode (PM), system supervisor (OP), or system Manager (SM) capability. If you have standard user capability, you can restore only those files in your logon account.

    With the ;CREATE option, you may build groups, accounts, and creators which do not currently exist in the directory. This way, you may restore files to your system without first defining the account, group and user with the NEWACCT, NEWGROUP, and NEWUSER commands. However, these structures will be created with default capabilities.

  • Lockword requirements

    The system manager and system supervisor may restore lockword-protected files without specifying the lockword only when RESTORE is executed during a session. Users without SM or OP capability must always supply the lockword. The exception is AM. If you have AM and you are working in your own account, you do not have to supply the lockword. If RESTORE is executed as a job, however, all users lacking SM, OP, or AM capability must supply file lockwords.

  • Disk space requirements

    RESTORE determines whether sufficient disk space remains to restore a file that already exists on the disk. If sufficient space remains, RESTORE writes a new copy of the file to the disk before purging the old copy of the file. The old copy of the file is purged only if the restore operation is successful.

  • Restoring True-Online Backups

    When restoring backups created with TurboSTORE/iX 7x24 True-Online Backup, when the sync point occurred at the end of the backup, RESTORE must read the complete store directory information before restoring any files. If a store disk directory file exists for this backup, or one is specified with the STOREDIRECTORY option, then RESTORE can read the directory information from this file before starting to restore files. However, if a disk directory file does not exist, or is not specified, then RESTORE may prompt the user to mount the last media from the backup. RESTORE will skip to the final media directory information, and then will prompt the user to mount the first needed media for the backup. If you know that you are restoring from a sync at end True-Online backup and do not have a disk directory file, then you can speed up the restore process by mounting the last piece of media first.

    Files that have after image data from a sync-at-end True-Online backup will be inaccessible between the time that the normal file data is restored, and the after image log data is read in from the end of the backup and restored. You will not be able to read or modify these files until the after image log data has been applied.

Use

This command may be issued from a session, job, or program. If you press [Break] during a restore, the operation continues while you interact with the Command Interpreter. Both ABORT and RESUME can be used within BREAK.

The user must have System Manager (SM), System Supervisor (OP), or Privileged Mode (PM) capability to use this command for privileged files.

Examples

To restore all files belonging to your logon group from the restorefile T, enter: 

  :FILE T;DEV=TAPE
  :RESTORE *T;@;KEEP;SHOW
In response, the system operator receives a request to mount the tape identified as T. If a file on T already exists in the system, it will not be restored because the KEEP parameter was specified.

To restore a file ABC without specifying a restorefile, no file equation need be used. For example: 

  :RESTORE ;ABC.PUB.SYS;SHOW
  
  TURBO-STORE/RESTORE     VERSION      A.50.11     HP36398A
    (C) 1986 HEWLETT-PACKARD CO.
  WED, NOV 23  1994  11:22 AM
  WILL RESTORE        1 FILES      ; NUMBER OF FILES ON MEDIA       1

  FILENAME GROUP ACCOUNT VOLUME RESTRICTIONS     SECTORS CODE   MEDIA
  ABC     .PUB  .SYS     DISC               :C         0            1

  FILES RESTORED :                               1 
  :
If you restore all files without specifying a fileset, a warning will appear, alerting you that all files, based on your capabilities, will be restored. 

  :RESTORE
  
  TURBO-STORE/RESTORE  VERSION  A.50.03  HP36398A
    (C) 1986 HEWLETT-PACKARD CO.
  THU, JAN  6, 1994,  8:10 PM
  WARNING: YOUR DEFAULT FILESET BECOMES '@' SINCE YOU HAVE NONE OF
    OP, AM, OR SM CAPABILITY  (S/R 1913)
To have the list of restored files printed on a line printer, enter: 

  :FILE T;DEV=TAPE
  :RESTORE *T;@;SHOW=OFFLINE
To restore the file FILEA.GROUPA.ACCOUNTA when the creator, USERA, does not exist on the system, you may use one of the methods shown here: 

  :RESTORE *TAPEFILE; FILEA.GROUPA.ACCOUNTA; CREATOR=USERB
This changes the creator of FILEA to USERB. USERB must exist on the system. 

  :RESTORE *TAPEFILE; FILEA.GROUPA.ACCOUNTA; CREATE=CREATOR
This creates USERA on the system. 

  :RESTORE *TAPEFILE; FILEA.GROUPA.ACCOUNTA; CREATE
Creates USERA on the system, and GROUPA and ACCOUNTA, if necessary, and if you have the require capabilities.

To restore only a subset of the fileset, enter 

  :RESTORE *T;@.@.@-@.PUB.SYS
This restores all files except those in PUB.SYS.

Related Information

Commands

STORE, VSTORE, REPLY, RECALL

Manuals

STORE and TURBOSTORE/iX Manual
Magneto-Optical Media Management User's Guide
Volume Management

RESUME

Resumes execution of a suspended operation. (Native Mode)

Syntax


  RESUME

Parameters

None.

Operation Notes

After a program or MPE/iX command operation is suspended by pressing Break or by using the CAUSEBREAK intrinsic, the RESUME command resumes execution of the operation at the point where the execution was suspended. Note that the RESUME command is legitimate only during a BREAK. Many MPE/iX commands are aborted rather than suspended by a BREAK, and thus cannot be resumed.

If, instead of RESUME, you enter another program command (such as EDITOR, FTNXL, or RUN) or one of the nonprogram commands (HELLO or BYE), the command interpreter prints the following message on your terminal: ABORT? (YES/NO). If you respond YES to the ABORT? message, the command interpreter aborts the current (suspended) program and executes the command.

If you respond NO to the ABORT? message, the command interpreter prints the message COMMAND NOT ALLOWED IN BREAK and prompts you for another command. If you now enter RESUME at the prompt, the suspended program continues at the point where it was interrupted. If you had logged on using the PARM= option of HELLO to create a process with PARM=1 (or 3), and then have the occasion to respond YES to an ABORT? message, MPE/iX aborts the command process and logs you off immediately.

Use

This command may be issued only while in BREAK. It may not be used from a session (other than while in BREAK mode), job, or program. Pressing Break has no effect on this command.

Example

To continue a suspended program at the point of interruption, enter: 

  RESUME
  READ PENDING
  Return

Related Information

Commands

ABORT

Manuals

None

RESUMEJOB

Resumes a suspended job. (Native Mode)

Syntax


  RESUMEJOB #Jnnn

Parameters

#Jnnn

A job number.

Operation Notes

The system operator uses the RESUMEJOB command to resume processing a job suspended with the BREAKJOB command. The job continues execution from the point at which it was suspended; no message is issued.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be executed only from the console unless distributed with the ALLOW command, or if the JOBSECURITY is set LOW.

Example

To resume the processing of job 68, enter: 

  RESUMEJOB #J68

Related Information

Commands

BREAKJOB

Manuals

Performing System Operation Tasks

RESUMELOG

Resumes system logging following suspension caused by an error. (Native Mode)

Syntax


  RESUMELOG

Parameters

None.

Operation Notes

When the operator resumes logging with the RESUMELOG command, a special log record is displayed that denotes the number of log events and corresponding records that were not recorded while logging was suspended, the total number of unrecorded job initiation records, and the total number of unrecorded job/session termination records.

Use

This command may be issued from a session, job, program, or in BREAK. It may be executed only from the console, or by a user with system supervisor (OP) capability.

Examples

Assume the system is online and running with logging enabled. If a recoverable error occurs, the following error message is sent to the system console: 

  ST/10:43/LOG FILE NUMBER 104 ERROR #46.
  LOGGING SUSPENDED.
After the error is corrected, enter RESUMELOG. A confirmation message then appears at the system console, as follows: 

  ST/10:45/LOG FILE NUMBER 104. LOGGING RESUMED.
  ST/10:45/LOG FILE NUMBER 104 ON.

Related Information

Commands

ALTLOG, CHANGELOG, GETLOG, LISTLOG, LOG, OPENLOG, RELLOG, SHOWLOGSTATUS, SWITCHLOG

Manuals

System Startup, Configuration, and Shutdown Reference Manual

RESUMESPOOL

Resumes suspended spooler output to a spooled device.

Syntax


  RESUMESPOOL ldev;BACK [ nnn { FILES | PAGES }]

  RESUMESPOOL ldev;FORWARD [ nnn { FILES | PAGES }]

  RESUMESPOOL ldev;BEGINNING

Parameters

ldev

The logical device number of a spooled device.

BACK

Instructs the spooler to back up nnn files or nnn pages and resume printing at that point. (Refer to "Operation Notes.")

FORWARD

Instructs the spooler to step forward nnn files or nnn pages and resume printing at that point. (Refer to "Operation Notes.")

BEGINNING

Instructs the spooler to resume printing at the beginning of the file which had been previously suspended.

nnn

The number of files or pages you wish the spooler to backspace or space forward when printing a RESUME. (Must be an integer between 1 and 256, inclusive.)

FILES or PAGES

Informs the spooler process which unit of measure to use when printing a RESUME. For the purposes of this command, FILE is defined as the text appearing between FOPEN intrinsic statements within the spoolfile. (Refer to "Operation Notes.") Using the FILES parameter is not allowed on the HP 2680A Page Printer or an HP 2608S CIPER-Protocol Printer. PAGE is the literal page (usually 60 lines or skip to channel 1), as output by the spooler to the printer.

Operation Notes

If you specify only the ldev parameter, the printer resumes printing at the beginning of the highest-priority spoolfile. Otherwise, the printer resumes printing the previously ACTIVE spoolfile.

Always overestimate the number of files or pages you need when using the BACK parameter, or underestimate the number when using the FORWARD parameter. This is the only way to ensure getting all the output you need, since partial pages and header pages affect the page count. However, if you instruct the spooler to go BACK further than the beginning of the file, an error message is displayed on the system console and printing resumes at the beginning of the file. Similarly, an error message is displayed if you instruct the spooler to advance FORWARD beyond the point where files exist. In this case, printing does not resume until a new command is issued.

By using the SPOOK utility with mode control ON, you can determine where each FOPEN intrinsic occurs within a spoolfile. This is useful, for example, when you are compiling, preparing, and running large programs, and printing the entire output is unnecessary.

Use

This command may be issued from a session, job, program, or in BREAK. Pressing Break has no effect on this command. It may be executed only at the console unless distributed to users with the ALLOW or ASSOCIATE command.

Examples

To resume output to logical device number 6 at the beginning of the file, enter: 

  RESUMESPOOL 6;BEGINNING
To resume output to logical device number 6 and reprint the last two pages, enter: 

  RESUMESPOOL 6;BACK 2 PAGES
To resume output to logical device number 6 and print the highest priority spoolfile, enter: 

  RESUMESPOOL 6

Related Information

Commands

SUSPENDSPOOL

Manuals

Performing System Operation Tasks

RETURN

Causes execution to return from the current user command (UDC or command file) to the calling environment. (Native Mode)

Syntax


  RETURN

Parameters

None

Operation Notes

This command terminates the execution of the currently executing user command. Control resumes in the calling environment at the command line following the user command in which RETURN was embedded. Invoking RETURN at the CI colon (:) prompt has no effect.

Use

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

Example

The following example uses the RETURN command to exit from a command file prematurely based on a parameter error condition. 

  PARM ERROR_NUM
  COMMENT DISPLAY CIERR MESSAGE ASSOCIATED WITH "ERROR_NUM".
  IF NOT NUMERIC (!ERROR_NUM) THEN
     ECHO EXPECTED A NUMBER.
     RETURN
  ENDIF
  SETVAR CIERROR ABS (!ERROR_NUM)
  ECHO !HPCIERRMSG
The last two lines above can be combined as: 

  ECHO ![SETVAR(CIERROR,ABS(!ERROR_NUM))] ![HPCIERRMSG]
This line causes a slightly different output because the error number precedes the message.

Related Information

Commands

ESCAPE

Manuals

None

RPG

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

Syntax


  RPG [textfile] [,[uslfile] [,[listfile] [,[masterfile]
    [,[newfile]] ]]]

Parameters

textfile

The 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 RPGTEXT. Default is $STDIN.

uslfile

The actual file designator of the user subprogram library (USL) file to which the object program is written. This can be any binary input file with a file code of USL or 1024. Its formal file designator is RPGUSL. If the uslfile parameter is omitted, the object code is saved to the temporary file $OLDPASS. If entered, this parameter refers to a file created in one of four ways:

  • By using the MPE/iX SAVE command to save the default USL file 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

The actual file designator of the file on which the program listing is written. This can be any ASCII output file. The formal file designator is RPGLIST. Default is $STDLIST.

masterfile

The actual file designator of the master file to be merged against textfile to produce a composite source. This can be any ASCII input file. The formal file designator is RPGMAST. Default is that the master file is not read, and input is read from textfile, or from $STDIN if textfile is not specified. If two files being merged have identical line numbers, the lines from textfile or from $STDIN overwrite those in masterfile.

newfile

The actual file designator of the file produced by merging textfile and masterfile. This can be any ASCII output file. The formal file designator is RPGNEW. Default is that no file is written.

NOTE: The formal file designators used in this command (RPGTEXT, RPGUSL, RPGLIST, RPGMAST, and RPGNEW) 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 an RPG program onto a user subprogram library (USL) file on disk. If you do not specify textfile, MPE/iX expects input from your standard input device. If you create the USL file before compiling the source code, you must assign it a file code of USL or 1024.

Use

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

Examples

The following example compiles an RPG program entered from your standard input device, stores the object code in the default USL file $OLDPASS, and sends the listing to the standard list device: 

  RPG
The next example compiles an RPG program contained in the disk file SOURCE. The object code is stored in the USL file OBJECT, which is a permanent disk file created with the BUILD command. The program listing is sent to the disk file LISTFL: 

  BUILD OBJECT;CODE=USL
  RPG SOURCE,OBJECT,LISTFL
To compile an RPG program and store the object code in the USL file OBJECT (created during the compilation process), enter: 

  RPG SOURCE,OBJECT,LISTFL

Related Information

Commands

RPGGO, RPGPREP, PREP, RUN

Manuals

MPE Segmenter Reference Manual
RPG/3000 Compiler Reference Manual

RPGGO

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

Syntax


  RPGGO [textfile] [,[listfile] [,[masterfile] [,newfile]]]

Parameters

textfile

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

listfile

The actual file designator of the file on which the program listing is written. This can be any ASCII output file. The formal file designator is RPGLIST. Default is $STDLIST.

masterfile

The actual file designator of a file which is merged against textfile to produce a composite source. This can be any ASCII input file. The formal file designator is RPGMAST. Default is that the master file is not read; input is read from textfile, or from $STDIN, if textfile is not specified. If two files being merged have identical line numbers, the lines from textfile or from $STDIN overwrite those in masterfile.

newfile

The actual file designator for the file produced by merging the textfile and the masterfile. This can be any ASCII output file. The formal file designator is RPGNEW. Default is that no file is written.

NOTE: The formal file designators used in this command (RPGTEXT, RPGLIST, RPGMAST, and RPGNEW) 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, prepares, and executes an RPG program. If you do not specify textfile, MPE/iX expects the source code to be entered from your standard input device.

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

Use

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

Examples

To compile, prepare, and execute an RPG program entered from your standard input device and send the program listing to your standard list device, enter: 

  RPGGO
To compile, prepare, and execute an RPG program read from the disk file SOURCE and send the program listing to the disk file LISTFL, enter: 

  RPGGO SOURCE,LISTFL

Related Information

Commands

RPG, RPGPREP, PREP, RUN

Manuals

MPE Segmenter Reference Manual
RPG/3000 Compiler Reference Manual

RPGPREP

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

Syntax


  RPGPREP [textfile] [,[progfile] [,[listfile] [,masterfile]
    [,[newfile]] ]]

Parameters

textfile

The 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 RPGTEXT. Default is $STDIN.

progfile

The actual file designator of the program 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. If you do create your own program file, however, 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 or session file of the correct size and type is created. Default is that $NEWPASS is assigned.

listfile

The actual file designator of the file on which the program listing is written. This can be any ASCII output file. The formal file designator is RPGLIST. Default is $STDLIST.

masterfile

The actual file designator of the master file that is merged against textfile to produce a composite sourcefile. This can be any ASCII input file. The formal file designator is RPGMAST. Default is that master file is not read; input is read from textfile, or from $STDIN if textfile is not specified. If two files being merged have identical line numbers, the lines from textfile or from $STDIN overwrite those in masterfile.

newfile

The actual file designator of the file produced by merging the textfile and the masterfile. This can be any ASCII output file. The formal file designator is RPGNEW. Default is that no file is written.

NOTE: The formal file designators used in the command (RPGTEXT, RPGLIST, RPGMAST, and RPGNEW) 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 and prepares an RPG program to a program file on disk. If you do not specify textfile, MPE/iX expects the source program to be entered from your standard input device. The USL file $OLDPASS, created during compilation, is a system-defined temporary file passed directly to the MPE segmenter. You can access it only if you do not use the $NEWPASS default for progfile. This is because the segmenter also uses $OLDPASS to store the prepared program segments, overwriting any existing temporary files of that name.

Use

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

Examples

To compile and prepare an RPG program entered from your standard input device, and send the listing to your standard list device, enter: 

  RPGPREP
The USL file created during compilation is a temporary file passed directly to the MPE segmenter. You can access it under the name $OLDPASS only if the prepared program segments are not also stored in $OLDPASS (which overwrites the USL file). Therefore, to save the compiled USL and the prepared program file, specify a nonexistent file for progfile in the RPGPREP command line and save the USL file $OLDPASS under another name. In the following example, the prepared program is saved as COMFL, and the USL file is renamed (and saved) to NUSL: 

  RPGPREP,COMFL
  SAVE $OLDPASS,NUSL
Unless you have specifically created a permanent file to store the prepared program, the program file COMFL is stored in the temporary file domain. To save it as a permanent file, use the SAVE command: 

  SAVE COMFL
Using the BUILD command, you can create your own program file in the permanent file domain. When you do so, be sure to specify a file code of PROG or 1029 and a numextents parameter value of 1. Such a file is created in the next example. It is then used by the PREP command. 

  BUILD PROGFL;CODE=PROG;DISC=,1
  RPGPREP,PROGFL
To send the program listing to a device other than the default standard list device, use the FILE command. In this example, the file equation assigns the file name LINEA to device class LP (your line printer). LINEA is then backreferenced in the RPGPREP command line: 

  FILE LINEA;DEV=LP
  RPGPREP,EDTDISC,COMFL,*LINEA

Related Information

Commands

RPG, RPGGO, PREP, RUN

Manuals

MPE Segmenter Reference Manual
RPG/3000 Compiler Reference Manual

RPGXL

Compiles an RPG/XL program. RPG/XL 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 RPG/XL is installed on your system. (Native Mode)

Syntax


  RPGXL [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 RPGTEXT. Default is $STDIN.

objectfile

Actual file designator of the object file to which the object code is stored. This file is stored in binary form and has a file code of 1461 or NMOBJ. Its formal file designator is RPGOBJ. If the objectfile parameter is omitted, the object code is saved to the temporary file $OLDPASS.

If you specify objectfile, the compiler stores the object file in a permanent file of the correct size and type, and with the name you specified. If a file of the same name already exists, the object code overwrites that file. If the compiler issues an error message telling you that a new or existing object file you are trying to compile to is too small, build the object file with a larger size and recompile to it. 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 RPGLIST. Default is $STDLIST.

quotedstring

A run-time parameter for the compiler. It is a quoted string that may contain either the word "VERSION" or "version" and is used to display the compiler and library VUF number.

NOTE: The formal file designators used in this command (RPGTEXT, RPGOBJ, and RPGLIST) 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 RPGXL command compiles an RPG/XL program and stores the object code in a file on disk. If textfile is not specified, RPG/XL expects the source program to be entered from your standard input ($STDIN). If you do not specify listfile, RPG/XL sends the listing to your standard list device ($STDLIST). If you omit the objectfile parameter, the object code is saved in the temporary 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

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

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

  RPGXL
The next example compiles an RPG/XL program contained in the disk file RPGSRC, and stores the object code in the object file MYRPGOBJ. The program listing is stored in the disk file LISTFILE. 

  RPGXL RPGSRC,MYRPGOBJ,LISTFILE
NOTE: Program development in native mode uses the MPE/iX LINK command not the MPE V/E PREP command. This produces a significant difference in the method of linking code.

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

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

  :RPGXL MAIN, OBJMAIN
  :FTNXL SUB, OBJSUB
  :
  :LINK FROM=OBJMAIN,OBJSUB;TO=SOMEPROG
  :
  :RUN SOMEPROG
However, if an NMRL is used instead of an NMOBJ, the above can be simplified to the following: 

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

Related Information

Commands

RPGXLGO, RPGXLLK

Manuals

HP RPG/XL Programmer's Guide
HP RPG/XL Reference Manual
HP RPG Utilities Reference Manual

RPGXLGO

Compiles, links, and executes an RPG/XL program. RPG/XL 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 RPG/XL is installed on your system. (Native Mode)

Syntax


  RPGXLGO [textfile] [,[listfile]]
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 RPGTEXT. 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 RPGLIST. Default is $STDLIST.

NOTE: The formal file designators used in this command (RPGTEXT and RPGLIST) 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 RPGXLGO command compiles, links, and executes an RPG/XL program. If textfile is omitted, RPG/XL expects input from your standard input device. If you do not specify listfile, RPG/XL sends the program listing to the formal file designator RPGLIST (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

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.

Example

To compile, link, and execute an RPG/XL program entered from your standard input device, with the program listing sent to your standard list device, enter: 

  RPGXLGO
To compile, link, and execute an RPG/XL program from the disk file RPGSRC and send the program listing to the file LISTFILE, enter: 

  RPGXLGO RPGSRC,LISTFILE

Related Information

Commands

RPGXL, RPGXLLK

Manuals

HP RPG/XL Programmer's Guide
HP RPG/XL Reference Manual
HP RPG Utilities Reference Manual

RPGXLLK

Compiles and links an RPG/XL program. RPG/XL 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 RPG/XL is installed on your system. (Native Mode)

Syntax


  RPGXLLK [textfile] [,[progfile] [,[listfile]]]
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 RPGTEXT. 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.

If you name an existing program file (file code = NMPROG), that file is purged before the new one of the same name 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 RPGLIST. Default is $STDLIST.

NOTE: The formal file designators used in this command (RPGTEXT and RPGLIST) 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 RPGXLLK command compiles and links an RPG/XL program into a disk file. If you do not specify textfile, RPG/XL expects your input from your standard input device. If you do not specify listfile, RPG/XL 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

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

The following example compiles and links an RPG/XL 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. 

  RPGXLLK
To compile and link an RPG/XL source program from the source file RPGSRC, store it in RPGPROG, and send the listing to your standard list device, enter: 

  RPGXLLK RPGSRC,RPGPROG

Related Information

Commands

RPGXL, RPGXLGO

Manuals

HP RPG/XL Programmer's Guide
HP RPG/XL Reference Manual
HP RPG Utilities Reference Manual

RUN

Executes a prepared or linked program. (Native Mode)

Syntax

The only required parameter is progfile. If you specify any other parameters, they will override the default parameters that the creator of the program established, but only for that particular execution of the program. If run is implied, see operation note below. 

  RUN progfile [,["]entrypoint ["]]
    [;NOPRIV] [;LMAP] [;DEBUG] [;MAXDATA=maxstack]
    [;PARM=parameternum]
    [;STACK=stacksize] [;DL=dlsize]
    [;NMSTACK=nmstacksize] [;NMHEAP=nmheapsize]
    [;LIB= { G | P | S }] [;XL="library [, ...]"] [;NOCB]
    [;INFO="quotedstring"] [;UNSAT=["]unsatproc ["]]
    [;STDIN= [{ *formaldesig | fileref | $NULL }]]
    [;STDLIST= [{ *formaldesig | fileref [,NEW] | [$NULL]}]]
    [;PRI= { BS | CS | DS | ES } {#}]

Parameters

progfile

The name of the program file to be executed. If the name is not fully qualified, it is given a full qualification consistent with the current job domain. The file may be redirected with a file equation.

entrypoint

Program entry point where execution is to begin. It contains a character string specifying the entry point (label) in the program where execution is to begin when the program is executed. This point may be the primary entry point of the program, or any secondary entry point in the program's outer block. Default is the primary entry point.

By default, MPE/iX shifts all alphabetic characters in entrypoint to uppercase; surrounding the parameter with quotation marks (" or ') prevents MPE/iX from performing the upshift and permits you to enter strings for case-sensitive applications.

NOPRIV

Specifies that the pages of the code space of the program are to be assigned execution level 3 (the least-privileged execution level), regardless of the declared execution level. The execution level of pages in a library are not affected by the NOPRIV parameter. The default is that code in the program executes at its declared execution level.

LMAP

Indicates that the user wants a listing of the process describing the spaces occupied by the process and by the links created to bind the external references of the process. The load map is written to the loader list device. The default is not to print a load map. Load maps for compatibility mode and native mode are significantly different from each other.

Native Mode

The load map for a native mode program or library is a listing that describes the spaces loaded for a process and the linkages used to connect the external references of the process. When the lmap option is selected at run time, the listing is produced for the program and for each library specified by the user.

The load map is organized into two major areas: the SOM's Description area, with one per loaded SOM, and the Process Data Dictionary area.

Each SOM Description Area has six sections:

  • The name section.

  • The locality name section.

  • The export code symbols section.

  • The import code symbols section.

  • The export data symbols section.

  • The import data symbols section.

The above description is true for the program file and all user-supplied library files, but not for the subsystem library XL.PUB.SYS. The SOMs loaded from the subsystem library are now displayed in the load map. However, only the name section is written except for subsystem SOMs that have Shared Globals, in which case the export and import data symbols sections are written to the load map.

SOM Description area 

  Name Section.
  NM Program File : REALP.CMARTCLE.CICSNM
  Module Name     : REALS
  FSN             :    0
  SOM             :    0
  
  LP              :      240.40100000
  DP              :      240.41635000
  
  Shared Data     :  YES
The first line of the load map from the name section displays the type of the file (program or library) and the full name of the file. The title is followed by the module name of the loaded SOM. The next grouping of items is the File Sequence Number (FSN) and the SOM number. The FSN is the number given the file according to its location in the ordered list of files presented to the loader. Starting with the number zero, which is assigned the program file, each user library is given the next number as it is encountered in the binding sequence. SOMs are numbered according to their position in the library file. This value is given by the Link Editor and read by the Loader.

The FSN and SOM number are useful when using the Process Data Dictionary area of the load map. They identify the file and SOM to which the data export belongs.

The next grouping is the LP and DP. The LP is the pointer to the Cross Reference Table (XRT), which contains the plabels for external procedure calls for this module. The DP is the pointer to the Static Global Data area for this module. The notation used for an address has the form: sid.offset.

The sid (space ID) is the 32-bit virtual space number that was assigned for that space when it was loaded. The offset is the byte offset within the space relative to its beginning.

The next grouping shows the condition of the shared global flag for this module. This information is only shown if the flag is set true.

Locality Name Section 

  Locality Name        Type       Address        Length  XL|R/W
  -------------        ----       ------------   ------  ------  
  $LIT$                Code       2C5.5000          348   3
  $UNWIND_START$       Code       2C5.5348           74   3
  $DXRT$               Data       240.41634000     1000   3/0
  $GLOBAL$             Data       240.41635000       E8   3/3
The name section is followed by the section that describes the spaces declared with the module.

The new subspace is the $DXRT$, which is the Data Cross Reference Table. Its address points to the bottom of the DXRT. Entry into the DXRT is negatively offset from the beginning of the Static Global area, which is the address of the $GLOBAL$ subspace.

The valid types for subspace are: Code, Data and Common. The length column is the number of bytes in hexadecimal format. The last column is read in two ways: for Code subspaces, it is the execution level; for Data subspace, it is R-read access, W-write access.

Export Code Symbols Section 

  Entry Name           Type   Proc Addr     Stub Addr     XL/EL
  ----------           ----   ---- ----     -----------   -----
  $START$              PProg                2C5.5014       3/3
  main                 Entry  2C5.50BC      2C5.5050       3/3
The valid types for export code symbols are:
Entry

Any code entry point. Includes both primary and secondary entry points that may be used as targets of r-space calls.

PProg

Primary program entry point.

SProg

Secondary Program entry point.

The procedure address (Proc Addr) column gives the starting address of the procedure. The stub address (Stub Addr) column gives the (inbound) external call stub. The last column is interpreted as follows: XL-execution level and/or EL-the call execution level.

Import Code Symbols Section 

  External Name         Type          XRT           Stub Addr
  -------------         ----          ---           ---------
  printf                Stub            4           2C5.506C
  proca                 Stub            3           2C5.509C
  .
  .
  
  exit                  Stub            A           2C5.5294
The valid types for import code symbols are:
Stub

This symbol marks an import (outbound). The Link Editor creates an import stub for the unsatisfied code symbols, and the Loader satisfies the reference by filling in the XRT entry allocated for this stub.

Plabl

This symbol defines an export stub for a procedure for which a procedure label has been generated. The Loader builds an XRT entry for the procedure at the offset allocated by the Link Editor.

The XRT column specifies the entry in the XRT through which the contents of a plabel can be located. Each entry is 32 bytes. The stub address (Stub Addr) column is the outbound stub address. This stub accesses the XRT for the targeted export.

Export Data Symbols Section 

  Symbol Name         Select Type Scope   Size     DP Addr       R/W
  -----------         ------ ---- -----   ----     ------------  ---
  a                      YES Stor  Univ      8     240.416350E0  3/3
  b                      YES Data  Univ    n/a     240.41635000  3/3
The Select column indicates whether this particular export was the one chosen by the Loader to place in the PDD.

The valid types for export data symbols are:
Data

Normal initialized data. Example (a C construct): double b = 3.3;

Stor

Storage. This symbol requests a data storage location of a certain size.

The scope column is always Univ-universal.

The Size column shows the number of bytes in decimal format required for the export symbol. Space is allocated for four (4) characters only. To accommodate numbers greater than 9999 bytes, the format changes to 10k up to 999k (999 kilobytes). The next range is 1.0m up to 9.9m (9.9 megabytes), followed by 10m to 999m (999 megabytes), and finally, 1.0g to 4.2g (4.2 gigabytes). Size information is only available for storage request types. There is no size information available for initialized data, that is, data universals.

The DP Addr column contains the actual virtual address of the symbol, provided the Select column is YES.

The last column gives the access rights for the symbol.

Import Data Symbols Section 

  IMPORTED DATA SYMBOLS .....
  Symbol Name             Type Scope   DXRT      DXRT Addr     R/W
  -----------             ---- -----   ----      ------------- ---
  c                       Data Unsat     -C      240.41634FE4  3/3
  d                       Data Unsat    -14      240.41634FEC  3/3
  ANSI_MODE               Data Unsat    -18      240.41634FE8  3/3
  a                       Data Unsat    -10      240.41634FF0  3/3
The valid type for import data symbols is:
Data

Requested import data item. Example (a C construct): extern double c

The scope column is always UnsatImport request has not been satisfied.

A DXRT entry is indexed negatively from the DP of the SOM. The DXRT column gives this offset, which is in bytes. The value is in hexadecimal format. The DXRT Addr column gives the indirect address for the import symbol.

The last column gives the access rights for the symbol.

Process Data Dictionary Area 

  |||||||||||||||||||||||||||||||||||||||||||||||||||||
  |||                                               |||
  |||            PROCESS DATA DICTIONARY            |||
  |||          SHARED GLOBALS DATA EXPORTS          |||
  |||                                               |||
  |||||||||||||||||||||||||||||||||||||||||||||||||||||
  
  Symbol Name   FSN  SOM Type Scope Size   DP Addr       R/W
  -----------   ---  --- ---- ----- -----  ------------- ---
  a               0    0 Stor  Univ    8   240.416350E0  3/3
  b               0    0 Data  Univ  n/a   240.41635000  3/3
  d               1    0 Stor  Univ    8   240.416370A8  3/3
  c               1    0 Data  Univ  n/a   240.41637000  3/3
  .
  .
  __ANSI_MODE     2    0 Stor  Univ    4   240.41641894  3/3
  .
  .
The FSN (File Sequence Number) and the SOM columns can lead you to the file and SOM, which supplied the export data symbol. For example, the _ANSI_MODE symbol comes from the subsystem library in the binding sequence, which would be XL.PUB.SYS, and the first SOM (SOM 0) with module name hp30026_01. Shown below are some lines from the SOM Description Area of the load map for the subsystem library. 

  NM Library File : XL.PUB.SYS
  Module Name     : hp30026_01
  
  FSN             :    2
  SOM             :    0
  
  LP              :      240.401001A0
  DP              :      240.41639000
  
  Shared Data     :  YES
  
  EXPORTED DATA SYMBOLS .....
  Symbol Name         Select Type Scope   Size     DP Addr       R/W
  -----------         ------ ---- -----   ----     ------------- ---
  .
  .
  __ANSI_MODE            YES Stor  Univ      4     240.41641894  3/3
  .
  .
Continuing with the PDD area, the remaining columns starting with Type through R/W are interpreted in the same manner as explained in the Export Data Section.

Compatibility Mode

A compatibility mode loader map shows information on the origin and destination of the reference. The exact origin or destination is identified by the file type, the segment within the file, and by the STT entry of the segment. The level of parameter checking is also listed. For example: 

  PROGRAM FILE SAMPLE.LOADER.MPEXL
  TERMINATE      PROG  0    4   0 SSL  0    2   41
  GETUSERMODE    PROG  0    3   0 SSL  0   13   44
  GETPRIVMODE    PROG  0    2   0 SSL  0   14   44
  
  301
The first entry reading across lists the name. The next four entries show the information for the reference origin. The last four show the information for the reference destination: 

                 Reference Origin Reference Destination
                 F T   L    S   S F T  L    S   S
                 i y   C    T   e i y  C    T   e
                 l p        T   g l p       T   g
                 e e              e e
  TERMINATE      PROG  0    4   0 SSL  0    2   41
  GETUSERMODE    PROG  0    3   0 SSL  0   13   44
  GETPRIVMODE    PROG  0    2   0 SSL  0   14   44
  
  301
The file types are:
PROG

Compatibility mode program file

SSL

SL.PUB.SYS

PSL

SL.PUB.account

GSL

SL.group.account

LC

(Level of file checking):

0

No checking

1

Check procedure type

2

Check number of parameters

3

Check parameter type

STT is the segment transfer table entry within the segment.

Seg is the logical segment number of the segment.

A list of the CSTX numbers (the single number 301 in this example) assigned to the segments of the program follows the load map. The first number in the list corresponds to logical Seg 0, the second to logical Seg 1, and so on.
DEBUG

Instructs the process to enter the system debugger just before executing the first instruction of the program. Once the debugger has been invoked, the commands available to the user depend upon the user's assigned capability. The default is not to enter the system debugger. This parameter is ignored in a job.

maxstack

The maximum CM stack area (Z-DL) size permitted, in 16-bit words. This parameter is included if you expect the size of the DL or the Z-DB areas to be changed during the program execution. But no matter what you specify, MPE/iX may change maxstack to accommodate table overflow conditions.

A value of -1 or a + sign (interpreted as a zero) causes the default value to be used.

The maxstack is always equal to the compatibility mode maximum default size if progfile is a native mode program.

parameternum

A value that can be passed to the program as a general parameter for control or other purposes. If the parameter is not specified, the default value is zero (0). If the executing program is a compatibility mode program, Q(initial)-4 contains the parameter value. Note: Q relative addresses are 16-bit word addresses. Q(initial) is the Q address for the outer block of the program.

MPE/iX provides an intrinsic (GETINFO) for retrieving the PARM parameter for a native mode process.

stacksize

The size of the CM local area, Z-Q, in 16-bit words. This value, if specified, must be in the range 512 to 32,767. It overrides the default stack size estimated by the MPE segmenter.

The stacksize is always equal to the compatibility mode maximum default size if progfile is a native mode program.

dlsize

The DL-DB area to be assigned initially to the CM stack. To accommodate system logging requirements, this area is always rounded upward in such a way that the distance from the beginning of the stack data segment to the DB address is a multiple of 128 16-bit words.

This value must be in the range -1 to 32,767. The default (which is used when no value or an invalid value is specified) is estimated by the MPE segmenter. A + sign for this parameter is interpreted as a zero.

The dlsize is always equal to the compatibility mode maximum default size if progfile is a native mode program.

nmstacksize

The maximum size in bytes to which the NM stack may grow. This must be a decimal number. If a value is specified which is less than the system-defined minimum (including values <= 0), the system-defined value will be used. If a value is specified which is greater than the system-defined maximum value, the system-defined maximum value will be used. A + sign for this parameter is interpreted as a zero.

The default is -1, which currently instructs MPE/iX to assign a system-defined constant as the value of nmstacksize.

nmheapsize

The maximum size, in bytes, to which the NM heap may grow. This must be a decimal number. If a value is specified which is less than the system-defined minimum (including values <= 0), the system-defined value will be used. If a value is specified which is greater than the system-defined maximum value, the system-defined maximum value will be used.

The default is -1, which currently instructs the command to assign a system-defined constant as the value of nmheapsize. A + sign for this parameter is interpreted as a zero.

G, P, or S

These parameters provide an efficient way to specify the executable libraries that may be used to load the program.

G

The program's group library is searched first, then its public account library is searched, and finally the system library is searched to resolve the program's external references.

P

The program's public account library is searched before the system library is searched to resolve the program external references.

S

Only the system library is used to bind the external references of the program. This is the default.

These parameters will result in a fail load if progfile contains a program name which cannot be expressed using the MPE syntax.

The group and account libraries referenced by this parameter must be named SL.group.account for compatibility mode programs and XL.group.account for native mode programs. Group and account are the group and account of the program, where the program resides.

If the LIB and XL parameters are missing, this parameter defaults to S. This parameter may not be used at the same time as the XL parameter.

"library"

Specifies the library or libraries to be searched, and the order in which they are searched to resolve any external references. This parameter is available only for native mode load operations. It may not be used at the same time as the LIB parameter. It must be delimited by a matching pair of quotation marks (either " or '). Compatibility mode ignores this parameter if it is specified. In native mode, this parameter overrides LIB= if both are specified.

If any library name in the list is not fully qualified, it will be qualified with a name consistent with the program file being loaded. Library names, except those in the system library, may be redirected with a file equation.

A default value for this parameter may be stored in the program file. The default is used only if the LIB and XL parameters are both omitted.

In a list of libraries, each library must have a privilege level equal to or greater than the privilege level of the library that precedes it in the list. The privilege level of any file is governed by the privilege level of the group in which it resides. For example, 


  RUN PROGA.grp.acct;XL='LIB1.PUB.TOOLS,LIB2.DIAG.SYS'
Suppose the group grp does not have privileged mode (PM) capability. We assume for this example that the user is able to execute PROGA.grp.acct. Suppose also that PUB.TOOLS does have PM capability, but that DIAG.SYS does not.

The program PROGA.grp.acct is able to load PUB.TOOLS. But PUB.TOOLS has PM capability. Therefore everything following it in the list must have PM capability, too. Since DIAG.SYS does not, the library search ends without loading LIB2.DIAG.SYS.

This prevents non-PM processes from "piggybacking" on legitimate PM processes.

NOTE: XL.PUB.SYS and NL.PUB.SYS, which are two of the three system libraries for MPE/iX, are searched automatically. The user does not need to specify them.

If you do specify one or both, place them at the end of your list of libraries. Otherwise, MPE/iX detects an error.

If you specify NL.PUB.SYS but not XL.PUB.SYS, only NL.PUB.SYS is searched. XL.PUB.SYS is ignored in this particular case. However, if you specify XL.PUB.SYS but not NL.PUB.SYS, both are searched despite the omission of NL.PUB.SYS.

An absolute pathname must be used when a library name is specified in HFS syntax. In addition, if progfile contains a name which can only be expressed in the HFS syntax, the file names specified in this item must be fully qualified.

To have an XL in the HFS, you must copy it from the MPE group to the HFS directory.

NOCB

Instructs the file system not to use the stack segment, PCBX, for its control blocks, even if sufficient space is available. This allows for expansion of the stack, using the DLSIZE and ZSIZE intrinsics, to the maximum possible limit at a later time.

NOCB affects only those programs that use the following types of file: MSG, RIO, and CIR. Programs using other types of files ignore the NOCB parameter.

Be aware, that NOCB causes the file management system to operate more slowly.

quotedstring

Allows the user to pass an ASCII string to the program that is to be run. The string must be delimited by a matching pair of quotation marks (either " or '). If you want a quotation mark to appear within the string, you may double it, as with most programming languages: can't must appear as can''t, " and " must appear as "" and "", 'but' must appear as ''but''. The maximum length of the string, including delimiters, is 255 characters. Refer to "Examples."

If the executing program is a compatibility mode program, Q(initial)-5 contains a byte pointer to the string, and Q(initial)-6 contains the number of characters in the string. The Q-relative addresses are 16-bit addresses. Q(initial) is the Q address for the outer block of the program. Default is that no string is passed, and the length of the string is set to zero.

MPE/iX provides an intrinsic (GETINFO) for retrieving the quotedstring for a native mode or compatibility mode process.

unsatproc

Specifies the (fall-through) procedure that is linked in the event that any of the external references cannot be resolved to one of the libraries available to the process. This is available only when loading a native mode program. It is ignored when loading a compatibility mode program. By default, MPE/iX shifts all alphabetic characters in unsatproc to uppercase; surrounding the parameter with quotation marks (" or ') prevents MPE/iX from performing the upshift and permits you to enter strings for case sensitive applications.

For instance: 


  ;UNSAT = terminate
The procedure TERMINATE is linked if one of the external references cannot be resolved to one of the available libraries. Because the value terminate is not delimited by quotation marks (" or '), the value is upshifted to TERMINATE. 

  ;UNSAT = "foo"
  
  ;UNSAT = 'foo'
Here the procedure foo is linked if one of the external references cannot be resolved to one of the libraries. In both cases, delimiting the value foo with quotation marks (" or ') causes MPE/iX to use the value as given, in lowercase.

If the user does not supply an UNSAT procedure and a process cannot be fully bound, the load fails.

An UNSAT procedure must reside in an XL. The UNSAT procedure cannot be placed in an NMOBJ file and linked with the rest of the program.

STDIN

Specifies the file to be used as $STDIN by the program being executed. If this parameter is omitted, or if nothing is specified after the equal sign, as in ;STDIN=Return, STDIN defaults to the standard input device for the job or session.

*formaldesig

The formal file designator for a file previously specified in a file equation.

fileref

The name of an existing permanent or temporary disk file.

$NULL

The actual file designator of a system-defined file that is always treated as an empty file. When referenced by another program, a program receives only an end-of-file indication when accessed. When referenced by a program as $STDLIST, the associated write request is accepted by MPE/iX, but no physical output is actually performed. Thus, $NULL can be used to discard unneeded output from an executing program.

PRI

The execution priority that the command interpreter uses for your program. BS has the highest priority; ES has the lowest priority.

DS and ES are intended for batch jobs and are not well-suited for interactive applications. Specifying a positive integer (#) permits you to set priority at points that lie between the preset priority levels BS, CS, DS, and ES. Accepted values for # are in the range 100 to 255, inclusive. Refer to the CREATEPROCESS intrinsic in the MPE/iX Intrinsics Reference Manual.

If you are in user mode (that is, nonprivileged) you may specify BS, CS, DS, or ES.

If you attempt to specify a priority higher than the priority permitted for your account or user name, MPE/iX sets the highest priority below BS. The default is CS. If you do not specify a value the default (the parent process's dispatching subqueue priority) is used.

CAUTION: Use care in assigning the BS queue. Processes at the BS priority can lock out other processes.

STDLIST

Allows the user to specify the file to be used as $STDLIST by the program being executed. If this parameter is omitted, or if nothing is specified after the equal sign, as in ;STDLIST=Return, then STDLIST defaults to the standard list device for the job or session. This parameter has the same subparameters as STDIN, but you may also specify the keyword NEW (for instance, ";STDLIST=filename,NEW").

NEW

The name to be assigned to a job/session temporary disk file consisting of 132-byte fixed ASCII records.

Operation Notes

This command executes a program prepared in a program file. It permits searching libraries (SLs for compatibility mode, XLs for native mode) to satisfy external references. Relocatable libraries (RL) are not searched.

If the volume set containing the file to be run is not mounted, this command implicitly causes that volume set to be mounted. The volume set has to be opened with a VSOPEN command.

If the program file is a temporary CM file, the logon group and account libraries for the current session along with SL.PUB.SYS are searched. If a program file is a temporary NM file XL.PUB.SYS and NL.PUB.SYS are also searched. Refer to the Accessing Files Programmer's Guide (32650-60010) for more information on file domains.

NOTE: NM and CM loader error messages are reported differently, allowing you to determine the system in which the error occurred.

NM Loader Error: ErrMessage (LDRERR nnnn)

CM Loader Error: ErrMessage (LOAD ERR nnnn)

The RUN command is parsed by the Compatibility Mode parser unless it is implied, in which case the Native Mode parser is used. To use the implied version of RUN simply omit the word run and enter the name of the program along with either the INFO or PARM parameters.

Because the Native Mode parser is used with implied run you can use quotes (" or ') with the program file name and/or the ;INFO= parameter. Also, quotes are not required if the parameter contains no delimiter characters such as a blank, comma, semicolon, quotemarks or equal sign. In addition, the ;INFO string can be up to 280 characters long and the ;PARM= value can be any signed 31 bit number. Without implied RUN the ;INFO limit is 255 characters and the ;PARM= value is limited to a signed 15 bit decimal or unsigned 16 bit octal or hex value.

NOTE: Programs whose name cannot be expressed using MPE syntax are not allowed to have PM, MR or DS capability. Programs linked with these capabilities cannot be loaded.

Users must have PH capability to load programs whose name cannot be expressed using MPE syntax, with PH capability.

CM programs cannot be loaded from the HFS directory.

Use

This command may be issued from a session or a job. It may not be issued in BREAK or from a program, unless the user or the calling program has PH capability. Pressing Break suspends the execution of this command. Entering the RESUME command continues the execution.

Examples

To list the references of a loaded program, enter: 

  RUN XLAB;LMAP
To run a program stored in the program file PROG4, beginning at the entry point SECLAB, enter: 

  RUN PROG4,SECLAB
The following example runs a program TESTPROG with $STDIN set to an old disk file named INPUT and $STDLIST set to the line printer: 

  FILE LPFILE;DEV=LP
  RUN TESTPROG; STDIN=INPUT;&
  STDLIST=*LPFILE
The next example runs a program using the STDIN parameter, setting $STDIN to an existing disk file named INPUT, this time referenced through a file equation. To set $STDLIST to a temporary disk file named RESULTS that is automatically created by the RUN command, enter: 

  FILE INFILE=INPUT,OLD
  RUN TESTPROG;DEBUG;STDIN=*INFILE;STDLIST=RESULTS,NEW
The following example of the RUN command uses the INFO= parameter to pass a string to the program: 

  RUN MYPROG;INFO= "A TEST WITH ""AND""&
  CHARACTERS"
In quotedstring, "AND" is bounded by an extra pair of quotation marks. As a result, the string passed to the program is: 

  A TEST WITH "AND" CHARACTERS

Related Information

Commands

LINK, PREP, XEQ, VERSION Utility

Manuals

CREATEPROCESS in MPE/iX Intrinsics Reference Manual



Chapter 11 Command List IX

Chapter 12 Command List X