MPE/iX Commands Reference Manual > Chapter 10 Command List VIII

Commands PASCAL thru PURGEUSER

	MPE documents
	Complete PDF
	Table of Contents
	Index

PASCAL
PASCALGO
PASCALPREP
PASSWORD
PASXL
PASXLGO
PASXLLK
PAUSE
PLISTF (UDC)
PREP
PREPRUN
PRINT
PURGE
PURGEACCT
PURGEDIR
PURGEGROUP
PURGEJOBQ
PURGELINK
PURGEUSER

PASCAL

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

Syntax


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

Parameters

textfile

Actual file designator of the input file from which the source program is read. This can be any ASCII input file. Formal file designator is PASTEXT. Default is $STDIN. $STDIN is the current input device, usually your terminal.

uslfile

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

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

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is PASLIST. Default is $STDLIST. $STDLIST is usually the terminal if you are running Pascal/V interactively, or the printer if you are running a batch job.

quotedstring

INFO=quotedstring is used in the Pascal programming language to pass initial compiler options to a program. Pascal/V brackets the quotedstring with dollar signs and places it before the first line of source code in the text file.

Operation Notes

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

The formal file designators used in this command (PASTEXT, PASUSL, and PASLIST) 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.

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

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 a Pascal/V program entered from the standard input device and stores the object code in the USL file $OLDPASS. The listing is then sent to the standard list device.


  PASCAL

The next example compiles a Pascal/V program contained in the disk file PASCSRC, and stores the object code in the USL file PASCOBJ. The program listing is stored in the disk file LISTFILE.


  PASCAL PASCSRC,PASCOBJ,LISTFILE

Related Information

Commands: PASCALGO, PASCALPREP, PASXL, PASXLGO, PASXLLK PREP, RUN, LINK, LINKEDIT
Manuals: MPE Segmenter Reference Manual
HP Pascal/iX Reference Manual

PASCALGO

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

Syntax


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

Parameters

textfile

PASTEXT cannot be backreferenced as an actual file designator in the command parameter list. For further information, refer to the "Implicit FILE Commands for Subsystems" discussion of the FILE command.

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 PASLIST. Default is $STDLIST. $STDLIST is usually your terminal if you are running Pascal/V interactively, or the printer if you are running a batch job.

PASLIST cannot be backreferenced as an actual file designator in the command parameter list. For further information, refer to the "Implicit FILE Commands for Subsystems" discussion of the FILE command.

quotedstring

INFO=quotedstring is used in the Pascal/V programming language to pass initial compiler options to a program. Pascal/V brackets the quotedstring with dollar signs and places it before the first line of source code in the text file.

Operation Notes

The PASCALGO command compiles, prepares, and executes a compatibility mode Pascal/V program. If textfile is omitted, MPE/iX expects input from your standard input device. If you do not specify listfile, MPE/iX sends the program listing to the formal file designator PASLIST (default is $STDLIST).

The USL file created during the compilation is the system-defined temporary file $OLDPASS, which is passed directly to the MPE segmenter. It can only be accessed if you do not use the default for progfile. This is because the segmenter also uses $OLDPASS to store the prepared program segments, overwriting any existing temporary file of the same name.

Use

Examples

To compile, prepare, and execute a Pascal/V program entered from your standard input device, with the program listing sent to your standard list device, enter:


  PASCALGO

To compile, prepare, and execute a Pascal/V program from the disk file PASCSRC and send the program listing to the file LISTFILE, enter:


  PASCALGO PASCSRC,LISTFILE

Related Information

Commands: PASCAL, PASCALPREP, PASXL, PASXLGO, PASXLLK PREP, RUN, LINK, LINKEDIT
Manuals: MPE Segmenter Reference Manual
HP Pascal/iX Reference Manual

PASCALPREP

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

Syntax


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

Parameters

textfile

progfile

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

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

listfile

Actual file designator of the file to which the program listing is written. This can be any ASCII output file. Formal file designator is PASLIST. Default is $STDLIST. $STDLIST is usually your terminal if you are running Pascal/V interactively, or the printer if you are running a batch job.

quotedstring

A sequence of characters between two single quotation marks (apostrophes) or between two double quotation marks. You may use the delimiter as part of the string so long as the delimiter appears twice. Any occurrence of two single or two double quotation marks in a row is considered part of the string, and, therefore, not the terminating delimiter. INFO=quotedstring is used in the Pascal programming language to pass initial compiler options to a program. Pascal/V brackets the quotedstring with dollar signs and places it before the first line of source code in the text file.

Operation Notes

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

Use

Examples

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


  PASCALPREP

To compile and prepare a Pascal/V source program from the source file PASCSRC, store it in PASCPROG, and send the listing to your standard list device, enter:


  PASCALPREP PASCSRC,PASCPROG

Related Information

Commands: PASCALGO, PASCAL, PASXL, PASXLGO, PASXLLK PREP, RUN, LINK, LINKEDIT
Manuals: MPE Segmenter Reference Manual
Pascal/3000 Reference Manual

PASSWORD

Creates or changes a user password. (Native Mode)

Syntax


  PASSWORD

Parameters

None.

Use

This command may be issued from a session or in BREAK. It is breakable (aborts execution). It cannot be used if $STDIN or $STDLIST are redirected.

Operation

This command allows users to establish or change their own passwords. It may be issued interactively or programmatically within a session and prompts the user for required input. Passwords are not echoed (displayed) during input.

Example


  PASSWORD
  ENTER OLD USER PASSWORD:
  ENTER NEW USER PASSWORD:
  ENTER NEW USER PASSWORD AGAIN:
  PASSWORD WAS CHANGED SUCCESSFULLY.

The old user password is requested only if it exists.

Related Information

Commands: LISTUSER, ALTUSER
Manuals: None

PASXL

Compiles an HP Pascal/iX program. HP Pascal/iX is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. (Native Mode)

Syntax


  PASXL [textfile] [,[objectfile] [,[listfile] [,libfile]]]
    [;INFO=quotedstring]

Parameters

textfile

The name of the text file that contains the source code to be compiled. This is an ASCII file that you prepare with an editor such as EDIT/V. The formal file designator is PASTEXT.

If you are running HP Pascal/XL from your terminal, you will probably specify a disk textfile. If you do not specify textfile, then the default file is $STDIN. $STDIN is the current input device, usually your terminal.

When textfile is your terminal, you can enter source code interactively in response to the > prompt. When you have entered all the source code, type a colon (:) in response to the > prompt to end the interactive input.

The source code to be compiled can be a program or a list of modules.

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 either (1461) or NMRL (1033). Its formal file designator is PASOBJ. 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

The name of the file on which the compiler writes the program listing. It can be any ASCII file. The default is $STDLIST. $STDLIST is usually the terminal if you are running HP Pascal/iX interactively, or the printer if you are running a batch job. The formal file designator is PASLIST.

If your terminal is both textfile and listfile, the compiler does not write the program listing on the terminal.

If listfile is $NULL or a file other than $STDLIST, the compiler displays on $STDLIST those lines that contain errors.

libfile

The name of the HP Pascal/iX library file that the compiler searches if a search path is not specified with the compiler option SEARCH. The default is PASLIB in your group and account.

quotedstring

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

The quotedstring string is used in the HP Pascal/iX programming language to pass initial compiler options to the compiler. HP Pascal/iX brackets the quotedstring string with dollar signs ($) and places the string before the first line of source code in the text file.

NOTE: The formal file designators used in this command (PASTEXT, PASOBJ, PASLIST, and PASLIB) 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 PASXL command compiles an HP Pascal/iX program and stores the object code in a permanent file (objectfile) or in $OLDPASS if you do not specify an object file. If textfile is omitted, the compiler expects the source program to be entered from your standard input device. If you do not specify listfile, the compiler sends the program listing to the formal file designator PASLIST (default is $STDLIST).

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

Use

Examples

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


  PASXL

The next example compiles an HP Pascal/iX program contained in the disk file SOURCE and stores the object program in the object file OBJECT. The program listing is stored in the disk file LISTFILE.


  PASXL SOURCE,OBJECT,LISTFILE

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

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


  :PASCAL MAIN, SOMEUSL
  :PASCAL 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. In 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:


  :PASXL MAIN, OBJMAIN
  :PASXL 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
  PASXL MAIN, RLFILE
  PASXL SUB, RLFILE
  LINK RLFILE,SOMEPROG
  RUN SOMEPROG

Related Information

Commands: PASCALGO, PASCALPREP, PASCAL, PASXLGO, PASXLLK PREP, RUN, LINK, LINKEDIT
Manuals: HP Pascal/iX Reference Manual
HP Link Editor/XL Reference Manual

PASXLGO

Compiles, links, and executes an HP Pascal/iX program. HP Pascal/iX is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. (Native Mode)

Syntax


  PASXLGO [textfile] [,[listfile] [,[libfile]]]
    [;INFO=quotedstring]

Parameters

textfile

The name of the text file that contains the source code to be compiled. This is an ASCII file that you prepare with an editor such as EDIT/V. The formal file designator is PASTEXT.

If you are running HP Pascal/iX from your terminal, you will probably specify a disk textfile. If you do not specify textfile, then the default file is $STDIN. $STDIN is the current input device, usually your terminal.

The source code to be compiled can be a program or a list of modules.

listfile

If your terminal is both textfile and listfile, the compiler does not write the program listing on the terminal.

If listfile is $NULL or a file other than $STDLIST, the compiler displays on $STDLIST those lines that contain errors.

libfile

The name of the HP Pascal/iX library file that the compiler searches if a search path is not specified with the compiler option SEARCH. The default is PASLIB in your group and account.

quotedstring

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

NOTE: The formal file designators used in this command (PASTEXT, PASLIB, and PASLIST) 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 PASXLGO command compiles, links, and executes an HP Pascal/iX program. If textfile is omitted, the compiler expects input from your standard input device. If you do not specify listfile, the compiler sends the program listing to the formal file designator PASLIST (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

Examples

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


  PASXLGO

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


  PASXLGO SOURCE,LISTFILE

Related Information

Commands: PASCAL, PASCALGO, PASCALPREP, PASXL, PASXLLK PREP, RUN, LINK, LINKEDIT
Manual: HP Pascal/iX Reference Manual

PASXLLK

Compiles and links an HP Pascal/iX program. HP Pascal/iX is not part of the HP 3000 Series 900 Computer System Fundamental Operating Software and must be purchased separately. (Native Mode)<

Syntax


  PASXLLK [textfile] [,[progfile] [,[listfile] [,libfile]]]
    [;INFO=quotedstring]

Parameters

textfile

The name of the text file that contains the source code to be compiled. This is an ASCII file that you prepare with an editor such as EDIT/V. The formal file designator is PASTEXT.

When textfile is your terminal, you can enter source code interactively in response to the > prompt. After you enter the source code, type a colon (:) in response to the > prompt to end the interactive input.

The source code to be compiled can be a program or a list of modules.

progfile

The name of the program file on which the MPE/iX linker writes the linked program. The default is $NEWPASS.

listfile

If your terminal is both textfile and listfile, the compiler does not write the program listing on the terminal.

If listfile is $NULL or a file other than $STDLIST, the compiler displays those lines that contain errors on $STDLIST.

libfile

The name of the HP Pascal/iX library file that the compiler searches if a search path is not specified with the compiler option SEARCH. The default is PASLIB in your group and account.

quotedstring

A string of no more than 132 characters (including the single or double quotation marks that enclose it). The quotedstring is used to pass initial compiler options to the HP Pascal/iX compiler. HP Pascal/iX brackets the quotedstring with dollar signs ($) and places the string before the first line of source code in the text file.

Operation Notes

The PASXLLK command compiles and links an HP Pascal/iX program into a file on disk. If you do not specify textfile, the compiler expects input from the standard input device. If you do not specify listfile, the compiler sends the program listing output to the formal file designator PASLIST (default $STDLIST).

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

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

Use

Examples

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


  PASXLLK

To compile and link an HP Pascal/iX source program from the source file SOURCE, store it in PROG, and send the listing to your standard list device, enter:


  PASXLLK SOURCE,PROG

Related Information

Commands: PASCAL, PASCALGO, PASCALPREP, PASXL, PASXLGO, PREP, RUN, LINK, LINKEDIT
Manuals: HP Pascal/iX Reference Manual
HP Pascal/iX Programmer's Guide
HP Link Editor/XL Reference Manual

PAUSE

The PAUSE command allows the current task to be suspended or "sleep" for a specifiec number of seconds.)

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.

Syntax


  PAUSE [num_seconds]
    [[;JOB=] jobid]
    [[;INTERVAL=] interval_secs]
    [; {EXIST | WAIT | NOTEXIST}]

Parameters

Collectively EXIST, WAIT and NOTEXIST are referred to as the "while_state", since PAUSE sleeps "while" the specified state is true.

num_seconds

If num_seconds is specified without jobid PAUSE sleeps for that many seconds, or until the process issuing the pause is interrupted by the break signal. If "jobid" is also supplied then "num_seconds" has a different meaning. In this case it indicates the maximum duration for the PAUSE command, such that PAUSE should continue while the selected jobs are in their "while_state" or when num_seconds has expired, whichever is shortest. Thus, num_seconds represents the maximum length of the pause. If PAUSE completes but one or more jobs are still in their "while state" a CIWARN is reported.

NOTE: to pause while a job is in its "while_state" or until num_seconds has expired, whichever is LONGEST, one can execute the following two commands:
PAUSE x PAUSE job=y ;z
If after X seconds job Y is still in state Z then the second PAUSE continues while state Z applies. On the other hand, if after X seconds job Y is not in state Z then the pause is complete. or equal to zero.

jobid

can be one of: [#]Jnnn, [#]Snnn, [ jobname,] user.acct, @, @J, @S. Note if jobname is included than the jobid must be quoted since the comma is a command token delimiter.

If the JOB= parameter is specified then PAUSE sleeps while jobid is in its "while_state". jobid can be an executing, waiting, scheduled job, or a session. jobid can also name many jobs or sessions. Wildcarding is supported, and a non-wildcarded [jname,] user.acct can match several jobs or sessions. The job name value can be " ," or " @," to match all jobs or sessions without a job name. When more than one job or session matches jobid PAUSE sleeps while all matching jobs are in their "while_state". If the job executing PAUSE matches jobid it will not be selected.

interval_secs

If interval_secs is specified PAUSE sleeps for this many seconds between attempts to see if jobid is still in its "while_state". Otherwise, PAUSE sleeps a variable amount of seconds depending on the job state and the number of previous times a particular job has been polled. This computed method favors executing jobs that terminate quickly.

EXIST

(default) means to pause while all jobs and sessions matching "jobid" exist. These jobs can be scheduled, waiting, executing, etc., but as long as the SHOWJOB command displays one or more of the jobs defined by "jobid", the pause continues

WAIT

means to pause while the selected job or jobs are waiting. As soon as all the matching jobs are no longer waiting (meaning all the job states are no longer "introduced", "waiting", or "scheduled") the pause ends. The life cycle of a job is typically: [sched or waiting->] intro-> initializing-> exec-> [susp-> exec->] terminate. Waiting jobs are considered all job states left of and excluding "initializing". Non-waiting jobs are all jobs right of and including "initializing"

NOTEXIST

means to pause while the matching job or jobs do not exist. As soon as any jobs matching "jobid" exist (in any state) the pause completes. PAUSE might miss finding jobs that log off quickly. This is particularly true for a match on a single job/session number. A more practical use might be:

PAUSE job=@J;notexistwhich

means to sleep while no jobs exist. As soon as the first job is streamed the above pause stops.

Operation Notes

The value of this command lies in providing a way to suspend one activity while another process waits for a specific condition to exist, for example, forcing a job to "idle" while waiting for the creation of a key file or the setting of a crucial flag. You may use several MPE/iX commands to query user or system variables, or the system itself, in order to verify the existence of the desired condition.

In its simpliest form, the PAUSE command sleeps for "num_seconds", or less if BREAK is pressed. In this simple case no "jobid" is specified and all other command arguments are ignored. If the "jobid" parameter is specified then "interval_secs" and the remaining command parameters are relevant. When "jobid" is supplied PAUSE typically sleeps until the jobs or sessions matching "jobid" have terminated.

Use

This command is available from a program or in BREAK. You can execute BREAK while PAUSE is active. BREAK terminates the pause.

Examples

If a job must read data from a file called LOGDAT.GXK.PROCCTRL, which is to be created by a session, then the job may suspend activity pending a test for the existence of the vital file.

The example below shows how the PAUSE command can be used to synchronize a session to some job activity via the existence of a known file:


  STREAM JLOGEND
  #J123
  ...
  ...
  SETVAR START_CPU HPCPUSECS
  WHILE NOT FINFO("LOGDAT.GXK.PROCCTRL","EXISTS") AND &
    HPCPUSECS-START_CPU <5 DO
    PAUSE 2
  ENDWHILE
  DELETEVAR START_CPU

NOTE: The CPU seconds used by the WHILE loop is not allowed to exceed 5 seconds.

If the file does not exist and the WHILE loop has consumed less than five CPU seconds, then the job pauses for two seconds. This pause does not use CPU-time. The CPU check is included to prevent an infinite loop that may result if JLOGEND aborted unexpectedly and thus did not get a chance to build the LOGDAT file.

The following example pauses while job #J24 exists in the system job table, (JMAT) i.e., it is visible in SHOWJOB output.


  :PAUSE job=#j24

The next example sleeps as long as MANGER.SYS has any jobs or sessions running or waiting.


  :PAUSE job=manager.sys; exists

The next example pauses until the job just streamed starts executing.


  :STREAM myjob
  :PAUSE job=!hplastjob; wait

Or, sleeps until the job you just streamed completes.


  :PAUSE , !hplastjob

The following example sleeps until all jobs have logged off or 5 minutes, whichever occurs first.


  :PAUSE 300, @J
  :IF hpcierr = -9032 then

# pause terminated but one or more jobs are still runningThe next example pauses while all jobs (by naming convention only) in the PROD account are running.


  :PAUSE job="J@,@.PROD"

# note the quotes are requiredThe next example sleeps while the backup job ("JBACKUP,OP.SYS") has not been streamed. PAUSE reports CIWARN 9032 if the job is not streamed within 30 minutes.


  :PAUSE 1800, job="jbackup,op.sys"; notexist

The final example polls the system job table every 3 minutes looking for any job or session matching a user name that includes the letters "MGR", and waits for all such job/sessions to terminate before the pause ends.


  :PAUSE , @mgr@.@ , 180

Related Information

Commands: WHILE, INPUT, SHOWJOB
Manuals: None

PLISTF (UDC)

The PLISTF UDC executes the LISTFILE command to list descriptions of one or more disk files.

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


  SETCATALOG HPPXUDC.PUB.SYS;SYSTEM;APPEND

Syntax


  PLISTF [fileset] [,format_opt] [;outfile]

Parameters

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

fileset: Specifies a set of files to be listed, including MPE and HFS files. If fileset is not specified, the default is @.
format_opt: An output format option. If this parameter is omitted, the default is FORMAT=0, which shows only the file names. The format option must be specified as a numeric value. Format names (for example, QUALIFY) are not supported by this UDC. Refer to the LISTFILE command for a complete description of each available format option.
outfile: The name of the output file. If this parameter is omitted, the output is displayed to $STDLIST. The outfile supports both MPE and HFS syntax. The outfile cannot be $NEWPASS.

Operation Notes

The PLISTF UDC lists descriptions of one or more disk files at the level of detail you select. The UDC executes the following form of the LISTFILE command:

LISTFILE fileset ,format_opt [>outfile]

Use

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

If a permanent file exists with the same name as specified as outfile, then CIOR defaults are used rather than the PLISTF CCTL default.

Examples

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

Related Information

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

PREP

Prepares a compatibility mode program from a user subprogram library (USL) file onto a program file.

Syntax


  PREP uslfile, progfile
    [;ZERODB] [;CAP=capabilitylist] [;PMAP]
    [;RL=filename] [;MAXDATA=segsize] [;PATCH=patchsize]
    [;STACK=stacksize] [;DL=dlsize]
    [;NOSYM] [{;FPMAP | ;NOFPMAP}]

Parameters

uslfile

Actual file designator of user subprogram library (USL) file into which the program has been compiled.

progfile

Actual file designator of program file onto which prepared program segments are written. This can be any binary output file created in one of two ways:

By using the MPE/iX BUILD command to create a new file and specifying a file code of PROG or 1029, and one extent.
By specifying a nonexistent file in the progfile parameter, in which case a file of the correct size and type is created. This file is a temporary file.

ZERODB

Request to initialize to zero the initially defined, user-managed (DL-DB) area of the stack, as well as the uninitialized portions of the DB-Q (initial). Default is that these areas are not affected.

PMAP

Request to produce a descriptive listing of the prepared program to a file whose formal file designator is $SEGLIST. If no FILE command is found referencing $SEGLIST, the listing is produced on $STDLIST. Default is no listing.

segsize

Maximum permitted stack area (Z-DL) in words. This parameter should be included when it is expected that the size of DL-DB or Z-DB areas will be changed during program preparation or execution. Regardless of what you specify, MPE/iX may change the segsize to accommodate table overflow conditions.

If you prepare your program with segsize less than the configured minimum, the value is rounded up to the minimum or the amount needed by the program (as calculated by the MPE segmenter). The maximum actual segsize permitted a program is 31,232 words. You may prepare your program with a segsize larger than necessary so long as this maximum is not exceeded. If the specified segsize does exceed the maximum, it is rounded down to 31,232 words.

stacksize

Size of initial local data area (Z-Q initial) stack, in words. This value, if specified, must be between 511 and 32767 words. This parameter overrides the default stacksize estimated by the MPE segmenter.

dlsize

DL-DB area to be initially assigned to stack. This area is of interest mainly in programmatic applications. Due to system logging considerations, the DL-DB area is always rounded upward so that the distance from the beginning of the stack data segment to the DB-address is a multiple of 128 words. Specify a value between -1 and 32767 words. The default is estimated by the MPE segmenter.

capabilitylist

Capability class attributes associated with a program, specified as two-character mnemonics. If more than one mnemonic is specified, each must be separated from its neighbor by a comma. The mnemonics are:


  IA   =   Interactive Access
  BA   =   Local Batch Access
  PH   =   Process Handling
  DS   =   Extra Data Segments
  MR   =   Multiple RINs
  PM   =   Privileged Mode

You can only specify those capabilities assigned by the account manager or system manager. Default is IA and BA.

filename

Actual file designator of the relocatable library (RL) file to be searched to satisfy external references during preparation. This can be any permanent binary file of type RL. It need not belong to your logon group, nor have a reserved local name. This file, to which you must have READ and LOCK access, yields a single segment that is incorporated into the segments of the program file. For more information, refer to the MPE Segmenter Reference Manual (30000-90011). Default is that no library is searched.

patchsize

Specifies the size of the patch area. This size applies to all segments within the program file. The value you specify must be within -1 and 16380 words.

NOSYM

Suppresses the symbolic DEBUG option. Refer to the HPToolset/V Reference Manual (32350-90001).

FPMAP or NOFPMAP

Includes or excludes the internal PMAP information. FPMAP is a request to have internal PMAP information included in the program. NOFPMAP excludes PMAP information from the program when the system FPMAP or job/session FPMAP is on. If the symbolic DEBUG option is invoked, default is FPMAP. Otherwise the default is NOFPMAP.

Operation Notes

The PREP command prepares a compiled source program for execution. Unless you prepare the program into a previously created program file, PREP creates a temporary program file for you. It is a good idea to specify a nonexistent program file when you issue the PREP command. This way, MPE/iX creates a file of the optimum size and characteristics. (Refer to the "Examples" section.)

A compiled program is prepared by searching a relocatable library (RL) to satisfy references to external procedures required by the program. When the program is prepared, such procedures are linked to the program in the resulting program file. To use a relocatable library (RL), you must have READ and LOCK access to it.

NOTE: The MPE segmenter employs temporary files named T999SYM, SEGTMP01, and SEGTMP00. If you have created temporary files having these names, the segmenter attempts to purge them.

Use

Examples

In the following example, you use the PREP command to prepare a program from the USL file USLX and the MPE segmenter stores it in the program file PROGX. Since the MPE segmenter creates PROGX for you, it is a temporary file, and you must subsequently save it in the permanent file domain.


  PREP USLX,PROGX
  SAVE PROGX

Although you will get the best results by having the MPE segmenter create the program file for you, you can also use the BUILD command to create your own permanent program file. When you do so, be sure to specify a file code of PROG or 1029 and a numextents parameter value of 1, as shown below:


  BUILD PROGX;CODE=PROG;DISC=,1
  PREP USLX,PROGX

To prepare a program from the USL file named USLZ and store it in a program file named PROGZ, list the prepared program, assign a stacksize of 511 words, and limit access to PROGZ to those users having IA, BA, PH, and DS capability enter:


  PREP USLZ,PROGZ;PMAP;STACK=511;CAP=IA,BA,PH,DS

Related Information

Commands: PREPRUN, RUN
Manuals: MPE Segmenter Reference Manual

PREPRUN

Prepares and executes a compiled compatibility mode program.

Syntax


  PREPRUN uslfile [,entrypoint]
    [;NOPRIV] [;PMAP] [;NOCB] [;DEBUG] [;INFO=quotedstring]
    [;LMAP] [;STDIN= [{*formaldesig | fileref | $NULL }]]
    [;MAXDATA=segsize] [;PARM=parameternum]
    [;STDLIST= [{*formaldesig | fileref [,NEW] | $NULL }]]
    [;STACK=stacksize] [;DL=dlsize] [;PATCH=patchsize]
    [;RL=filename]
    [;LIB={ G | P | S}]
    [;NOSYM] [; {FPMAP | NOFPMAP}] [;CAP=capabilitylist]

Parameters

uslfile

Actual file designator of the USL file to which the program has been compiled.

entrypoint

Contains a character string, terminated by a blank, specifying the entry point (label) in the program where execution is to begin when the program is executed. The entrypoint parameter may be the primary entry point or any secondary entry point in the program's outer block. Default is primary entry point.

NOPRIV

Declaration that the program segments are to be placed in nonprivileged (user) mode. This parameter is for programs prepared with privileged mode (PM) capability and makes them accessible to nonprivileged users. Normally, program segments containing privileged instructions are executed in privileged mode only if the program was prepared with privileged mode capability class. (A program containing legally compiled privileged code, placed in nonprivileged mode, may abort when an attempt is made to execute it.) If NOPRIV is specified, all segments are placed in nonprivileged mode. (Library segments are not affected because their mode is determined independently.) Default is that segments of a privileged mode program remain in privileged mode.

PMAP

Request to produce a descriptive listing of the prepared program to a file whose formal file designator is $SEGLIST. If $SEGLIST is not found in a FILE command, the listing is produced on the current list device. Default is no listing.

DEBUG

Request to issue a DEBUG call before the first executable instruction of the program. Unless the user has READ and EXECUTE access to the program file, this parameter is ignored. If privileged mode (PM) capability has been assigned, the user is put into privileged mode debug. If not, the user is put into user mode debug. Default is that the DEBUG call is not issued.

LMAP

Request to produce a descriptive listing of the allocated (loaded) program to a file whose formal file designator is LOADLIST. If no FILE command referencing LOADLIST is found, the listing is produced on $STDLIST. Default is no listing.

ZERODB

Request to initialize to zero the initially defined user-managed (DL-DB) area and uninitialized portions of the DB-Q (initial) area. Default is that these areas are not affected.

segsize

Maximum permitted stack area (Z-DL) in words. This parameter should be included when you expect that the size of DL-DB or Z-DB areas will be changed during program preparation or execution. Regardless of what you specify, MPE/iX may change the segsize to accommodate table overflow conditions.

If you prepare your program with a segsize less than the configured minimum, the value is rounded up to the minimum or the amount needed by the program (as calculated by the MPE segmenter). The maximum actual segsize permitted a program is 31,232 words. You may prepare your program with a segsize larger than necessary so long as this maximum is not exceeded. If the specified segsize does exceed the maximum, it will be rounded down to 31,232 words.

parameternum

An integer containing a parameter to be passed to the new program (accessed through Q-4 of the outer block).

stacksize

Size of local data area, Z-Q (initial), in the stack, in words. If it is specified, this value must be between 511 and 32,767 words. The default is estimated by the MPE segmenter.

dlsize

DL-DB area to be initially assigned to stack. Due to system logging considerations, the DL-DB area is always rounded upward, so that the distance from the beginning of the stack data segment to the DB-address is a multiple of 128 words. The value you specify must be between -1 and 32,767 words. The default is estimated by the MPE segmenter.

G, P, or S

Searches the segmented procedure libraries of the program file's group and account. The G option searches the group library, the account library, and then the system library. The P option searches the account library then the system library. The S option searches the system library for external references to segmented procedures. Default is S.

capabilitylist

Capability class attributes associated with the program, specified in two-character mnemonics. If more than one mnemonic is specified, each must be separated from its neighbor by a comma. The mnemonics are:


  IA   =   Interactive Access
  BA   =   Local Batch Access
  PH   =   Process Handling
  DS   =   Extra Data Segments
  MR   =   Multiple RINs
  PM   =   Privileged Mode

You can specify only those attributes that you possess through assignment by the account manager or the system manager. Default is IA and BA.

filename

Actual file designator of the relocatable library (RL) file to be searched to satisfy external references during preparation of the program. This can be any permanent file of type RL, to which you must have READ and LOCK access. It need not belong to the logon group, nor does it require a reserved, local name. This file yields a single segment that is incorporated into the segments of the program file. Refer to the MPE Segmenter Reference Manual (30000-90011) for a description of RL files. Default is that no library is searched.

NOCB

Request that the file system not use stack segment (PCBX) for its control blocks, even if sufficient space is available. This permits you to expand your stack (with the DLSIZE or ZSIZE intrinsics) to the maximum possible limit at a later time. It does, however, cause the file management system to operate more slowly for this program.

quotedstring

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

The INFO=quotedstring parameter is used in some programming languages (for example, COBOLII, Pascal) to pass compiler options to a program. These options appear before the first line of source code in the text file.

$STDIN

This parameter allows the user to specify the file to be used as $STDIN by the program being executed. If omitted, or if nothing is specified after the equal sign, such as $STDIN=, then $STDIN defaults to the job or session's standard input device. You may use one of the following subparameters with $STDIN=:

*formaldesig

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

fileref

The name of an existing permanent disk file.

$NULL

The actual file designator of a system-defined file that is always treated as an empty file.

When referenced by a program as $STDIN, that 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.

STDLIST

This parameter allows the user to specify the file to be used as $STDLIST by the program being executed. If $STDLIST is omitted, or if nothing is specified after the equal sign, such as $STDLIST=, then $STDLIST defaults to the job or session's standard list device. This parameter has the same subparameters as $STDIN, but you may also specify the keyword NEW.

NEW: The name to be assigned to a job/session temporary disk file created with the system defaults. The system defaults of the new file are fixed length ASCII 132-byte records with a maximum file size of 1023 records.

patchsize

Specifies the size of the patch area. This size applies to all segments within the program file. The value specified must be within -1 and 16,380 words.

NOSYM

Suppresses the symbolic DEBUG option. Refer to the HPToolset/V Reference Manual for more information.

FPMAP or NOFPMAP

Operation Notes

The PREPRUN command prepares and executes a program compiled in a USL file. Both relocatable (RL) and segmented (SL) libraries are searched during the preparation process to satisfy external references.

The USL file created during compilation is a system-defined temporary file, $OLDPASS, which is passed directly to the MPE segmenter. It can be accessed only if you do not use the default for progfile. This is because the segmenter also uses the file $OLDPASS to store the prepared program segments, overwriting any existing temporary file of the same name.

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 RESUME continues the execution.

Examples

To prepare and execute a program from the USL file XUSL, with no special parameters declared, enter:


  PREPRUN XUSL

To obtain a descriptive listing of the prepared program, and a listing of the allocated (loaded) program, enter:


  PREPRUN XUSL;PMAP;LMAP

To prepare and execute a program from the USL file UBASE that begins execution at the entry point RESTART, that has a stacksize of 800 words, and searches an RL file named LIBA, enter:


  PREPRUN UBASE,RESTART;STACK=800;RL=LIBA

The following example prepares and runs a program with $STDIN set to the existing disk file INPUT. $STDLIST is set to the line printer:


  FILE LPFILE;DEV=LP
  PREPRUN TESTPROG;MAXDATA=10000;$STDIN=INPUT;&
  $STDLIST=*LPFILE

The next example also uses the $STDIN= and $STDLIST= parameters to prepare and run a program. This time, a file equation is used to set $STDIN to INPT, and to set $STDLIST to the temporary disk file RESULTS (which is automatically created by the RUN command).


  FILE INFILE=INPT,OLD;
  PREPRUN TESTPROG;DEBUG;$STDIN=*INFILE;$STDLIST=RESULTS,NEW

The following example of the PREPRUN command uses the INFO= parameter to pass a string to the program:


  PREPRUN MYPROG;MAXDATA=2000;INFO="A TEST WITH "" AND "" &
  CHARACTERS"

Note that the delimiting character is doubled within the string so that it appears on the printout as follows:


  A TEST WITH "AND" CHARACTERS

Related Information

Commands: PREP, RUN, XEQ
Manuals: MPE Segmenter Reference Manual

PRINT

Prints the contents of a file.

Syntax


  PRINT filename [OUT=outfile] [START=m] [END=n] [PAGE=p]
    [;UNN | NUM] [;NONUM]

Parameters

filename

Actual file name of the file to be printed to $STDLIST, unless outfile is specified as a destination. To specify an HFS file, begin the filename with a dot (.) or slash (/). The filename may specify either a temporary or a permanent disk file.

File equations are ignored unless an asterisk (*) precedes filename, indicating a backreference.

The filename may be $STDIN or $STDINX.

If you do not specify a file name, PRINT takes its input from $STDINX and continues to do so until you enter the :EOD command on a new line.

outfile

Specifies a destination other than $STDLIST for filename. If filename has embedded carriage-control characters (CCTL), PRINT inserts a blank in place of the CCTL in the outfile. New files are created TEMP. File equations are ignored unless an asterisk (*) precedes outfile, indicating a backreference. You must use a file equation to overwrite a permanent file.

You must use the ;SAVE option in the file equation to overwrite a permanent file.

If outfile is not interactive with the user's $STDIN file, the PAGE parameter is ignored. (Refer to the FRELATE intrinsic for additional information on "interactive pair" of files.)

To redirect output to the line printer (DEV=LP), you could use the following commands:


  FILE PRT;DEV=LP;CCTL
  PRINT MYFILE;OUT=*PRT

Specifies the record number of the first file record to be displayed. An m is relative to 1. If m is a negative number, it specifies a record location relative to the end-of-file, that is, -5 indicates the fifth record from the end-of-file. Zero is an invalid specification. Default is the first record of the file.

For byte-stream files, the first line (or "record") corresponds to the bytes from the beginning of the file to the first newline character, the second line contains bytes between the first newline character and the second newline character, and so on.

n

Specifies the last record of the file to be displayed. An n is relative to 1. If n is a negative number, it specifies a location relative to the end-of-file, that is, -5 indicates the fifth record from the end-of-file. Zero is an invalid specification. Default is the last record of the file.

NOTE: For byte stream files, you cannot display one or more records by specifying a negative number with the keywords START= or END=. If you try to do so, the result will be unpredictable because the end-of-file for byte stream files is the total byte count of the file, and not the number of the last record.

p

Specifies the number of lines to be displayed before a page break occurs. Default is 23 lines for interactive users and 0 (continuous) for non-interactive users (that is, in a job). Specifying 0 for p suppresses page breaks in the output and produces continuous output from the beginning to the end of the file.

If filename contains more than p records and you are working interactively, the command displays p lines and then prompts you for a reply indicating whether or not more output is desired, as follows:


  (NEXT/EOF) CONTINUE?

NEXT is the next record number to be printed, and EOF is the end-of-file value that would be displayed by LISTF <filename>,2. If you are reviewing a byte-stream file, NEXT displays the next logical record, whereas EOF is the byte count of the file.

Table 10-1 "PRINT Command Control" defines the range of valid responses to control the output.

Table 10-1 PRINT Command Control

Response Result

Y, Yes Continue printing at record next

N, NO, Break Stop printing

-m (integer) Continue printing at record next-m

+m (integer) Continue printing at record next+m

m (integer) Continue printing at record m

other, Return Continue printing at record next (default)

Responses are case insensitive. Note that Return instructs PRINT to continue printing.

In jobs, no prompt for continuing output is generated. Instead, a page-eject control character is written to outfile every p lines. A page value of zero suppresses all page breaks, and filename is printed from m through n, inclusive. This is the default for jobs.

UNN

Suppresses line numbering in the display, regardless of whether the disk file is numbered or unnumbered. UNN is the default.

NUM

Specifies numbering of the lines as they are displayed. The numbers appear in front of the line (record) being displayed. The number displayed is the actual line number for numbered files; for unnumbered files, relative numbering begins with 1.

NONUM

Requests that trailing digits at the end of each record in the file be displayed as part of the file content, rather than being interpreted as line numbers.

Operation Notes

This command prints the contents of filename to the standard list device, unless another destination is specified with the outfile variable.

If an interactive user takes more than HPTIMEOUT minutes to respond to the page number prompt, MPE/iX terminates the CI. This occurs only if HPTIMEOUT has been set to a positive value.

In a batch job, in which the filename defaults to $STDINX, some MPE/iX commands such as :EOD, EOF, JOB, EOJ, and DATA do not execute as part of the original job when they follow a PRINT command. For example, if a JOB command follows a PRINT command, only those commands preceding PRINT are executed in the original job, and nothing is printed. The JOB command following the PRINT command is taken as the start of a new job, which is then streamed as a second job.

Use

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

Examples

To send the contents of MYFILE to the line printer, enter the following commands:


  FILE XXX;DEV=LP
  PRINT MYFILE, *XXX

In this example, the file XXX is equated with the line printer. Then the file MYFILE is "printed" to the file *XXX.

Use EDIT/V to create the command file TAIL which prints the last 10 lines of a file:


  PARM FILE, LAST=10
  PRINT !FILE; START = -!LAST

The first line defines FILE as a required parameter of the command file and creates an optional parameter, LAST the default value of which is 10.

The second line instructs the PRINT command to print the dereferenced value of FILE (the value entered by the user). The second line also tells the command to use the negative of the dereferenced value of LAST (10 by default) as the starting point for printing (that is, 10 records from the end).

To print the last 10 records of the file called MYFILE, enter:


  TAIL MYFILE

To print the last 45 records of MYFILE, because entering the value 45 overrides the default value of 10, enter:


  TAIL MYFILE, 45

NOTE: The PRINT command itself can be used to create a file:


  PRINT $STDIN,TAILB
  PARM FILE, LAST=5
  PRINT !FILE; START = -!LAST
  :EOD
  SAVE TAILB

The SAVE command is used to make the file TAILB permanent since the default is temporary.

PRINT infile;NUM;NONUM would print the line numbers as in the case of UNNUMbered files, ie, line numbers starting from 1 for the first record and so on.

PRINT infile;UNN;NONUM
PRINT infile;NONUM

would consider the file as UNNUMbered file even when the file is a NUMbered file and print the contents as it is in the file.

[UFILEYES is an unnumbered file with trailing 8 characters as digits.]

PRINT UFILEYES


  aaaaaaaaaaaa
  bbbbbbbbbbbb
  cccccccccccc
  dddddddddddd
  eeeeeeeeeeee
  ffffffffffff
  gggggggggggg
  hhhhhhhhhhhh
  iiiiiiiiiiii
  jjjjjjjjjjjj
  kkkkkkkkkkkk
  llllllllllll

NOTE: The above file was considered by PRINT to be a numbered file and thus the trailing 8 bytes are truncated

PRINT UFILEYES;NONUM


  aaaaaaaaaaaa00010001
  bbbbbbbbbbbb00010002
  cccccccccccc00010003
  dddddddddddd00010004
  eeeeeeeeeeee00020001
  ffffffffffff00020002
  gggggggggggg00020003
  hhhhhhhhhhhh00020004
  iiiiiiiiiiii00030001
  jjjjjjjjjjjj00030002
  kkkkkkkkkkkk00030003
  llllllllllll00030004

HFS Example

The following command entry will print the last 10 records of the file called posix/doc/print.doc in the current working directory (CWD).


  PRINT ./posix/doc/print.doc;start=-10

Related Information

Commands: FCOPY, COPY
Manuals: None

PURGE

This command deletes one or more files from the system.

Syntax


  PURGE filereference [;TEMP]
    [; [ONERROR=] { CONTINUE | QUIT }]
    [; { AUTOLOCKWORD | NOAUTOLOCKWORD }]
    [; { CONFIRM | NOCONFIRM | CONFIRMALL }]
    [; { NOSHOW | SHOW }]
    [; { SHOWERRORS | NOSHOWERRORS }]

Parameters

filereference

The actual file designator of the file to be deleted, interpreted according to MPE-escaped semantics filereference, can be either an MPE file (i.e., one that uses MPE syntax) or it can be a POSIX file name beginning with a dot or a slash. For example, you can use the escaped pathname /SYS/PUB/FILE since it is equivalent to the MPE name FILE.PUB.SYS.

TEMP

Specifies that the file is a temporary file in the job/session temporary file domain. You can specify a filename in MPE or HFS syntax and may name a symbolic link that resolves to a filename. You must enter this parameter to delete a temporary file. The default is that a permanent file is assumed.

CONTINUE

Allows PURGE to continue until the end of the list is reached, regardless of errors. CONTINUE is the default option.

QUIT

Quits the execution of PURGE when it encounters an error and sets the CIERROR variable to the last execution error.

AUTOLOCKWORD

Directs PURGE to look up and resolve file lockwords automatically. Users with system manager (SM) capability can specify AUTOLOCKWORD for all files on the system. Users with account manager (AM) capability can specify AUTOLOCKWORD for all files within their account.

NOAUTOLOCKWORD

Requires the user to specify a file's lockword before the file is purged. This is the default.

CONFIRM

Verifies the filereference parameter by requiring you to validate the purge during command execution. Valid responses are "YES" or "NO". If you respond "YES", the PURGE command is executed. Pressing Break at the prompt is equivalent to responding "NO". CONFIRM is the default for sessions, unless the filereference designates a single file.

NOCONFIRM

Continues the purge without verification from the user. NOCONFIRM is the default for jobs or if the filereference designates a single file.

CONFIRMALL

Requests verification for each file before the purge is executed. A proper response is one of the following:

"Y" or "YES" to purge the file
"N", "NO", or Return to retain the file
"Q", "QUIT", or Break to stop the PURGE command

The CONFIRMALL option is ignored in jobs and when you are purging a single file.

NOSHOW

Suppresses the display of each successfully purged file. NOSHOW is the default.

SHOW

Displays the name of each successfully purged file.

SHOWERRORS

Displays each lower-level error which prevents a file from being deleted. The name of the file is shown, followed by the error message. By default lower-level errors are not displayed. You may also enter this option in the singular form, i.e. SHOWERROR.

NOSHOWERRORS

Suppresses the display of low-level errors. NOSHOWERRORS is the default. You may also enter this option in the singular form, i.e. NOSHOWERROR.

Operation Notes

Usage
You can enter this command from a session, a job, a program, or in break mode. Pressing Break does not affect this command.
You must have write access to a file to delete it.
Purging unrecognized files
If the file does not exist in the specified domain, the following message appears:
```
  FILE filename NOT FOUND, NO PURGE DONE. (CIWARN 383)
```
Purging non-private spool files
You can purge a non-private spool file by entering PURGE filename. You must specify the fully qualified file name (including .OUT.HPSPOOL). The PURGE command deletes the specified spool file and all links to the spool file directory. The spool file does not print after you purge it.
Purging files with wildcards
You can use wildcards to remove multiple files at once. You can also use the CONFIRMALL option to prevent accidental deletion of one or more files. Examples of the wildcard feature are listed in the Examples section below:

Examples

To delete a permanent file named PFILE, enter:
```
  :PURGE PFILE
```

To purge multiple files using wildcards


  :PURGE /users/jeff/bin/FILES/file@
  3 FILES matched
  Continue PURGE? (YES/NO) yes
  3 selected.  3 succeeded.  0 failed.

To purge multiple files interactively using wildcards
To purge a number of files, one at a time, in an interactive mode so that you can skip a file or stop your purge, you can use the CONFIRMALL option.
```
  :PURGE /users/jeff/bin/FILES/file@; CONFIRMALL
  3 FILES matched
  /users/jeff/bin/FILES/file1 ? (NO/YES/QUIT) yes
  /users/jeff/bin/FILES/file2 ? (NO/YES/QUIT) no
  /users/jeff/bin/FILES/file3 ? (NO/YES/QUIT) yes
  2 selected.  2 succeeded.  0 failed.
```
Type "q","quit", or press the BREAK key if you decide to stop the PURGE command completely.
To purge log files using wildcards
The following example shows you how to purge all log files within your current working directory that start with log, followed by any number from 0 - 9 (#), followed by any number of alphanumeric characters (@).
```
  :PURGE log#@
  10 FILES matched
  Continue PURGE?  (YES/NO) yes
  10 selected.  9 succeeded.  1 failed.
```
Since the PURGE command does not remove the currently opened log file, the command always returns "1 failed".

Related Information

Commands: ALTSEC, BUILD, LISTFILE, LISTSPF
Manuals: None

PURGEACCT

Removes an account and its groups and users from the system directory or from the specified volume set's directory.

Syntax


  PURGEACCT acctname [;ONVS=volumesetname]

Parameters

acctname

Name of the account to be deleted. This name must contain from one to eight alphanumeric characters, beginning with an alphabetic character.

volume- setname

The volume set from which the account is to be purged. Volume set names consist of from 1 to 32 characters, beginning with an alphabetic character. The remaining characters may be alphabetic, numeric, the underscore, and periods.

If you specify a volumesetname, you must specify the full name of the volume set.

The volumesetname specified refers to a previously defined volume set. When a volumesetname is specified, the volume set must be mounted, or the PURGEACCT command fails. When ONVS=volumesetname is specified, the account is removed from the volume set directory. When ONVS= is specified without volumesetname, the account is removed from the system directory.

Refer to the VSxxxxxx commands in this chapter.

Operation Notes

The system manager uses the PURGEACCT command to eliminate an entire account from the system. When PURGEACCT is executed during a session, MPE/iX displays a verification request to ensure that the wrong account is not deleted accidentally. Respond YES or NO to the message:


  ACCT acctname TO BE PURGED?

No verification message is printed when the PURGEACCT is entered in a job.

The PURGEACCT command removes every user not currently logged on and every group/file not in use. The order in which entries are purged is users first, then volume set definitions, files, groups, and finally the account. If the command is executed while the account is in use, the account remains on the system and active users, groups, and files are not purged from the account. To completely purge an account, you must execute PURGEACCT when the account is inactive.

CAUTION: Do not attempt to purge the SYS account. The SYS account cannot be completely purged, but you can destroy critical files by attempting to do so. If you execute PURGEACCT SYS, all groups except PUB are purged; all users except the system manager are purged; and all inactive files and system files in the PUB group are purged.

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

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.

Examples

To remove an account named ACCT1, enter:


  :PURGEACCT ACCT1
  ACCT ACCT1 TO BE PURGED? YES
  :

To purge the account FARFLE from the volume set TIME_LORD, you need to issue two commands:


  :PURGEACCT FARFLE
  ACCT FARFLE TO BE PURGED? YES
  :
  :PURGEACCT FARFLE;ONVS=TIME_LORD
  ACCT FARFLE TO BE PURGED? YES
  :

The first command informs the system volume set of the purge; the second informs the mountable volume set.

Related Information

Commands: PURGEGROUP, PURGEUSER
Manuals: None

PURGEDIR

Purges (unlinks) one or more directories.

Syntax


  PURGEDIR [dir=] dir_name
    [; { TREE | NOTREE | USENAME }]
    [; { CONFIRM | NOCONFIRM | CONFIRMALL }]
    [; { NOSHOW | SHOW }] [; { SHOWERROR | NOSHOWERROR }]

Parameters

dir_name

The name of the directory that is being purged (required). The dir_name is assumed to be an MPE name unless you begin it with a dot (.) or a slash (/) to indicate an HFS directory.

If dir_name is an HFS directory that ends in a slash and you don't include the NOTREE option, PURGEDIR deletes all objects at all levels under and including dir_name.

The use of wildcards is permitted. The dir_name cannot name root (/), an MPE group, or an account.

TREE

Purges all objects below and including dir_name. The dir_name may or may not end in a slash (/), with no error or warning reported. Since the MPE naming convention does not support a trailing slash (/), the TREE option is the only way to delete a non-empty, MPE-named directory with a single command.

NOTREE

Purges dir_name only if it is empty. If dir_name is an HFS name and ends in a slash (/), a warning tells you that NOTREE overrides the trailing slash (/).

USENAME

Indicates that dir_name alone controls whether or not all levels of directories and files are deleted. (This is the default.) If dir_name is an HFS name and ends in a slash (/), then it, and all objects under it are deleted. If dir_name does not end in a slash (/), then only dir_name is purged, assuming it is empty. USENAME only applies to HFS-named directories, and is ignored for MPE-named directories.

CONFIRM

Requires the user to confirm the purge of the directory. A different prompt is seen depending on whether dir_name is to be purged with the TREE option or with the trailing slash feature. CONFIRM is the default for sessions. CONFIRM is ignored for jobs.

NOCONFIRM

Purges dir_name (and all objects under it for TREE purges) without user confirmation. NOCONFIRM is the default for jobs.

CONFIRMALL

Requires the user to confirm each directory before the purge is executed. A proper response is one of the following:

"Y" or "YES" to purge the directory
"N", "NO", or Return to retain the directory
"Q", "QUIT", or Break to stop the PURGE command

The CONFIRMALL option is ignored in jobs and when you are purging a single directory.

SHOW

Displays to $STDLIST each file or directory under dir_name that was purged. Directory names are always displayed in an HFS syntax, even if the name was specified as an MPE name.

NOSHOW

Suppresses the display of each file and directory purged. NOSHOW is the default.

SHOWERROR

Displays on $STDLIST each lower-level error that prevents an object below dir_name from being deleted'. The object (file or directory) name is shown, followed by the error message. By default, lower-level errors are not displayed. SHOWERRORS is a synonym for SHOWERROR.

NOSHOWERROR

Suppresses the display of low-level errors. NOSHOWERROR is the default. "NOSHOWERRORS" is a synonym for NOSHOWERROR.

Use

You can issue the PURGEDIR command from a job, a session, a program, or in BREAK. Pressing Break terminates execution of this command. You must have TD access to each component in the dir_name pathname, and DD permission to the parent directory of dir_name. (Refer to the ALTSEC command for more information on directory access.) If wildcards are specified with dir_name, then RD access is required to the parent directory of each wildcard component. If the purge is multilevel, then TD, RD and DD accesses are necessary to each directory below dir_name.

Operation

The PURGEDIR command purges the directory dir_name. The dir_name cannot name an MPE account, an MPE group, a file, or root (/). Dot (.) and dot-dot (..) can be specified but cannot be purged.

By default PURGEDIR deletes an MPE-named directory. This means that dir_name must follow all MPE naming rules, unless it is prefixed with a dot (.) or a slash (/). Since the MPE name syntax defines three levels, fully (or partially) qualified MPE-named directories can only be created under MPE groups. Unqualified MPE-named directories are created relative to the CWD. Directories do not support lockwords, file equations, or system defined file names (for example, $NEWPASS). If dir_name begins with a dot (.) or a slash (/), then HFS naming rules are enforced.

The directory referenced by dir_name must be empty (except for dot (.) and dot-dot (..)) in order to be purged, unless a TREE purge is requested. A TREE purge may be requested as follows:

Specify the TREE option. (The dir_name parameter does not control a multilevel purge in this case). This is the only choice available if dir_name is an MPE name.
If dir_name is an HFS name, ends in a slash (/), and the ;NOTREE option is not requested, then a TREE purge occurs.

The dir_name parameter cannot reference root (/) because purging root is undesirable, and most likely is not what is intended.

A file or directory is not deleted if it is being accessed (opened); however, all non-accessed objects under dir_name are still purged. A final "IN USE" error indicates that dir_name was not deleted because one or more children objects could not be removed.

If CONFIRM is specified while your session is interactive, and it is legal for you to purge dir_name, then you are prompted to confirm the purge of dir_name. If a NOTREE purge is requested, the following prompt is displayed:


  DIRECTORY dir_name TO BE PURGED? (YES/NO)_

Valid responses are YES, Y, NO, and N (case insensitive). If a TREE purge is requested, the prompt is:


  PURGE ALL FILES BELOW AND INCLUDING dir_name? (ALL/NO)_

Valid responses are ALL, NO, and N (case insensitive).

NOTE: If dir_name is long, the prompt may wrap around. If dir_name is an MPE name, it is fully qualified in the prompt message. If the YES option is selected, then the purge is automatically confirmed without a prompt.

The SHOW option displays the name of each purged file and directory on $STDLIST. For example:


  :PURGEDIR ./mydir ;TREE ;SHOW
   ./mydir/abc
   ./mydir/dir1/dir2/file1
   ./mydir/dir1/dir2/file2
   ./mydir/dir1/dir2
   ./mydir/dir1/f1
   ./mydir/dir1/f2
   ./mydir/dir1
   ./mydir/file1
   ./mydir

The SHOWERRORS option displays any error that prevents an object from being deleted on $STDLIST after the object name is displayed. Object names are only displayed if an error occurs.

Examples

The following examples purge dir1, which is empty.


  :PURGEDIR /MYACCT/MYGRP/dir1
  :PURGEDIR /MYACCT/MYGRP/dir1;NOTREE
  :
  :PURGEDIR /MYACCT/MYGRP/dir1/;NOTREE
  NOTREE option overrides directory name ending in a "/".
    (CIWARN 9041)

The following examples purge dir1 and all objects below dir1.


  PURGEDIR /MYACCT/MYGRP/dir1/
  PURGEDIR /MYACCT/MYGRP/dir1 ;TREE

The next example shows the command to purge MYDIR.


  PURGEDIR mydir

The next example shows the command to purge MYDIR and all objects below.


  PURGEDIR mydir;TREE

The next example illustrates the SHOW and TREE options.


  :PURGEDIR dir;SHOW;TREE
   ./DIR/A
   ./DIR/B
   ./DIR/dir1/A
   ./DIR/dir1/B
   ./DIR/dir1
   ./DIR/C
   ./DIR
   
  :PURGEDIR /dir1/dir2;SHOW;TREE
   /dir1/dir2/file1
   /dir1/dir2/file2
   /dir1/dir2
  
  :PURGEDIR ./foo/;show
   ./foo/dir1_below_foo/f1
   ./foo/dir1_below_foo/f2
   ./foo/dir1_below_foo
   ./foo

The following command purges all empty directories under the CWD with TMP in their name.


  PURGEDIR @tmp@

The following command purges all directories under the CWD with names beginning with TMP, and all objects below these directories.


  PURGEDIR tmp@;TREE

The following command purges all directories under the CWD with names ending with tmp, and all objects below these directories.


  PURGEDIR ./@tmp/

The following command purges all empty directories rooted to /a/b.


  PURGEDIR /a/b/@

The following command purges all directories rooted to CWD/a@/b@ and all objects below these directories.


  PURGEDIR ./a@/b@/

You can use the PURGEDIR command to delete a directory and the files or directories it contains using wildcards. For example, to delete all directories rooted to MYACCT/MYGRP enter:


  :purgedir /MYACCT/MYGRP/@

To delete all empty directories under the CWD (Current Working Directory) with TMP in their name:


  :purgedir @TMP@

To delete all directories under the CWD with names beginning with TMP all objects below these directories:


  :purgedir TMP@; TREE

To delete all directories under the CWD with names ending with TMP all objects below these directories:


  :purgedir ./@TMP/

When wildcards are specified with dir_name, then RD access is required to the parent directory of each wildcard component. If the purge is multilevel, then TD, RD, and DD accesses are necessary to each directory below dir_name.

Related Information

Commands: CHDIR, LISTFILE, NEWDIR, PURGE, PURGEACCT, PURGEGROUP, LISTDIR (UDC), FINDDIR (UDC)
Manuals: None

PURGEGROUP

Removes a group (and all files belonging to it) from the system or from the specified volume set directory.

Syntax


  PURGEGROUP groupname [.acctname] [;ONVS=volumesetname]

Parameters

groupname

Name of the group in the logon account to be removed. This name must contain from one to eight alphanumeric characters, beginning with an alphabetic character.

acctname

Specifies the account in which the group is found. System manager (SM) capability is required to use this parameter.

volumesetname

Specifies a particular volume set from which the group is to be purged. The volume set must be one already defined and recognized by the system.

Volume set names consist simply of from 1 to 32 characters, beginning with an alphabet character. The remaining characters may be alphabetic, numeric, the underscore, and periods.

If you specify a volumesetname, you must specify the full name of the volume set.

If volumesetname is specified, the volume set must be mounted or the PURGEGROUP command fails. When the volumesetname parameter is specified, the group is removed from the volume set directory, and not the system directory.

Operation Notes

Account managers use the PURGEGROUP command to delete a group from their account. When the command is executed during a session, MPE/iX displays a verification request. Respond YES or NO to the message:


  GROUP groupname TO BE PURGED?

No verification message is printed if the PURGEGROUP command is entered in a job.

If the group resides on a mountable, non-system volume, the command succeeds only if the group's home volume set is mounted.

Entries are purged by volume set definitions first, files second, and finally the group. If no files in the group are in use, and the group itself is not in use, the PURGEGROUP command removes the entire group. Otherwise, only inactive files are removed. To completely purge the group in this case, reenter the PURGEGROUP command when neither the group nor its files are in use.

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.

CAUTION: Do not attempt to purge the PUB group of the SYS account. The public group of the system account, PUB.SYS, cannot be completely purged. If you specify this group in the groupname parameter, all non-system and inactive files are purged, which seriously impairs the proper functioning of the entire system.

Use

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

Account manager (AM) or system manager (SM) capability is required to execute this command. Account manager (AM) capability, however, may lack the appropriate privilege to purge all files and directories below an MPE group. If you lack sufficient access to purge all directories and files, an error occurs and the MPE group is not purged.

Examples

To purge a group named GROUP1, enter:


  :PURGEGROUP GROUP1
  GROUP GROUP1 TO BE PURGED? YES
  :

To purge the group LEELA in the volume set MY_VOL, you need to issue two commands:


  :PURGEGROUP LEELA
  GROUP LEELA TO BE PURGED? YES
  :
  :PURGEGROUP LEELA;ONVS=MY_VOL
  GROUP LEELA TO BE PURGED? YES
  :

The first command informs the system volume set of the purge; the second informs the mountable volume set.

Related Information

Commands: ALTGROUP, LISTGROUP, PURGEACCT, PURGEUSER, PURGEDIR
Manuals: Performing System Management Tasks

PURGEJOBQ

Removes a job queue

Syntax


  PURGEJOBQ qname

Parameters

qname: is the name of the queue to be deleted

Operation Notes

The PURGEJOBQ command deletes a job queue. The queue will be deleted only if it is empty, that is, if no jobs are waiting or executing in the queue. The default system job queue can not be purged. The user must have SM or OP capability to execute the command.

This command is available in a session, job. or in BREAK. Pressing Break aborts the execution of this command. This command is not allowed in SYSSTART.

Example


  :PURGEJOBQ myjobq

Related Information

Commands: NEWJOBQ, LISTJOBQ, SHOWJOB

PURGELINK

Removes a link. (Native Mode)

Syntax


  PURGELINK [LINK=] linkname

Parameters

linkname

The name of a symbolic link file. All rules regarding file name specification apply to this parameter.

This is a required parameter. You may not use wildcards in linkname or specify a file equation in place of linkname.

Operation Notes

A symbolic link is a special file that can point to a file, group, account, or directory. Links are established through the NEWLINK command, and they are removed through the PURGELINK command.

The PURGELINK command may be issued from a session, job, program, or in BREAK. PURGELINK requires Traverse Directory (TD) and Delete Directory entry (DD) permissions.

Example

For the following examples assume that a user is currently logged on as USER1 in the group SAFE.COMPANY.

To remove the link /COMPANY/SAFE/PAYROLL, enter the following command:


  :PUREGLINK PAYROLL

To remove the link /dira/scripts, enter the following:


  :PURGELINK /dira/scripts

Related Information

Commands: NEWLINK, PURGE, PURGEDIR, LISTFILE
Manuals: None

PURGEUSER

Removes a user from an account.

Syntax


  PURGEUSER user [.acctname]

Parameters

user: Name of the user to be deleted.
acctname: Specifies the name of the account in which the user is found. Default is the logon account of the account manager.

Operation Notes

Account managers use the PURGEUSER command to delete a user from an account. You are asked to verify the command only when it is executed during a session, and not from a job. To do so, respond YES or NO to the message:


  USER user TO BE PURGED?  (YES/NO)

An attempt to purge a user currently logged on to the system fails, and an explanatory message is displayed:


  IN USE: CAN'T BE PURGED.

The user can only be purged if the user is not logged on when the PURGEUSER command is issued. An attempt to purge MANAGER.SYS always fails, since this user can never be purged if the user is logged onto the system.

If files created by a purged user remain after the user is purged from the system, the system manager can remove them with the PURGEACCT command, or the account manager can eliminate them by executing PURGEGROUP.

Use

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

To execute this command, the account must be the same as the logon account of the command issuer unless that user has system manager (SM) capability.

Example

To remove a user named USER1, enter:


  :PURGEUSER USER1
  USER1 TO BE PURGED? YES

Related Information

Commands: PURGEACCT, PURGEGROUP, NEWUSER, ALTUSER
Manuals: Performing System Management Tasks

Chapter 10 Command List VIII

Chapter 11 Command List IX