!=============================================================================!
!  DIVISION   I	:				     HELP MODULE DECLARATION  !
!=============================================================================!
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 01 :					 INITIAL VERSION      !
!      -----------------------------------------------------------------      !
!									      !
!      File Specification: ACC_HELP:XRUN.HLP				      !
!      Author		 : Harlan H. Bloom				      !
!      Initial version	 : 01.00.00 21-AUG-1985	VMS 4.1			      !
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 02 :				    MODIFICATION HISTORY      !
!      -----------------------------------------------------------------      !
!									      !
!      vv.uu.ff	dd-mmm-yyyy VMS	v.u: Name				      !
!				     Reason for	modification.		      !
!									      !
!=============================================================================!
!  DIVISION  II	:				  HELP MODULE SPECIFICATIONS  !
!=============================================================================!
!									      !
!      Key 1 (Command name)............	XRUN				      !
!	 Key 2 ........................	  Parameters			      !
!	 Key 2 ........................	  Operation			      !
!	 Key 2 ........................	  Example			      !
!	 Key 2 ........................	  Errors			      !
!	   Key 3 ......................	    CONFLICT			      !
!	   Key 3 ......................	    FATALERR			      !
!	   Key 3 ......................	    IVKEYW			      !
!	   Key 3 ......................	    NOSUCHFILE			      !
!	   Key 3 ......................	    NOSUCHPROG			      !
!	   Key 3 ......................	    NULFIL			      !
!	   Key 3 ......................	    TOOMANY			      !
!									      !
!=============================================================================!
!  DIVISION III	:					       SPECIAL NOTES  !
!=============================================================================!
!									      !
!									      !
!=============================================================================!
!
!
!=============================================================================!
! Key 1									 XRUN !
!=============================================================================!
!
1 XRUN
This  will  run a user-specified program, writing the output to a disk
file.  Optionally, this file can then be printed on the line  printer.
When  you  use  XRUN,  none of your program output will show up on the
terminal.  Please anticipate this so you are  not  caught  unaware  of
what is happening.

Format:

     XRUN program [listfile] [keywords]
!
!=============================================================================!
! Key 2								   Parameters !
!=============================================================================!
!
2 Parameters
program
  This is the program that you wish to run.  If you omit the file type
  (EX.: .EXE), a default  file  type of .EXE will be added to the file
  name.  If you do not specify the program name, the error  NOSUCHPROG
  will occur.  This parameter is required.

listfile
  This  is  the  file  to which the program output will be sent.  This
  parameter is optional.  If you do not specify a file name, a default
  listfile  will be used.  This default is formed by using the name of
  the program file specification and adding the file type of .XRUN.

keywords
  Indicated how XRUN should perform.  If all keywords are omitted, NEW
  and PRINT will be used by default.

  The valid keywords are:

    APPEND    Append this run to the listfile specified.  The listfile
              must already exist.
    NEW       Default.   The  listfile  is  created as a new file.  If
              there are previous versions of the listfile, then a  new
              version will be created.
    PRINT     Default.   Print  the listfile on the line printer after
              the run completes.
    QUIET     XRUN will not display any messages to the user.
!
!=============================================================================!
! Key 2								    Operation !
!=============================================================================!
!
2 Operation
Before using XRUN, it is important to have some understanding  of  how
XRUN  works.  XRUN is designed to make the transfer of output from the
terminal to the lineprinter easier.  A concession that you  will  have
to  make is not seeing any program prompts on your terminal.  The only
information that you will see from your  program  is  the  information
that you type on the keyboard.

Here is an example to illustrate how the conventional way of running a
sample  program  compares  using XRUN.  The first example is running a
sample program the conventinal way:

  $ RUN FRED
  Please type in a number: 5
  Please type in a second number: 3
  The sum of the numbers is 8.

The next example is how XRUN works using the same sample program:

  $ XRUN FRED
  +-----------------------------------------------------------------+
  |                                                                 |
  |  NOTE:                                                          |
  |         All of the output from your program will be sent  to a  |
  |  file in your directory.  You must anticipate  and  enter  all  |
  |  program input required.  Program prompts will NOT  appear  on  |
  |  the terminal.                                                  |
  |                                                                 |
  |  When you have completed running your program, the information  |
  |  in the output file will be printed.                            |
  |                                                                 |
  |  The output from this program is in :                           |
  |  FRED.XRUN                                                      |
  |                                                                 |
  +-----------------------------------------------------------------+
  5
  3
  $

As  you  can  see,  none  of the program prompts even showed up on the
terminal.  In this example, a copy of the program output went  to  the
lineprinter  to be printed. A copy is also in your directory under the
name FRED.XRUN.
!
!=============================================================================!
! Key 2								      Example !
!=============================================================================!
!
2 Example
This example shows the easiest method of using XRUN, just enter the
name of the program to run:

  $ XRUN EXAMPLE
  +-----------------------------------------------------------------+
  |                                                                 |
  |  NOTE:                                                          |
  |         All of the output from your program will be sent  to a  |
  |  file in your directory.  You must anticipate  and  enter  all  |
  |  program input required.  Program prompts will NOT  appear  on  |
  |  the terminal.                                                  |
  |                                                                 |
  |  When you have completed running your program, the information  |
  |  in the output file will be printed.                            |
  |                                                                 |
  |  The output from this program is in :                           |
  |  EXAMPLE.XRUN                                                   |
  |                                                                 |
  +-----------------------------------------------------------------+
  (you would enter any input your program expects)

After  the  bottom line is written out, you may then enter all program
input that is required.

If you enter the keyword QUIET, then the  box  shown  in  the  example
above will not be printed on your terminal.
!
!=============================================================================!
! Key 2								       Errors !
!=============================================================================!
!
2 Errors
Errors  detected  by  XRUN  are prefixed with the facility name %XRUN.
These errors are described in the sub-topics which follow.
!
!=============================================================================!
! Key 3								     CONFLICT !
!=============================================================================!
!
3 CONFLICT
%XRUN-E-CONFLICT, NEW and APPEND are conflicting operations

The keywords NEW and APPEND have opposite  meanings.   Please  reenter
the command omitting one of the keywords, or both.
!
!=============================================================================!
! Key 3								     FATALERR !
!=============================================================================!
!
3 FATALERR
%XRUN-E-FATALERR, Internal inconsistency

You should never receive  this  error.   If  you  do,  please  contact
Academic Computing Center.
!
!=============================================================================!
! Key 3								       IVKEYW !
!=============================================================================!
!
3 IVKEYW
%XRUN-E-IVKEYW, unrecognized keyword - check validity and spelling

One of the words given in the keyword  list  is  not  known  to  XRUN.
Please  reenter  the  command  with  a correct keyword.  If you do not
enter any keywords at all, the keywords NEW and PRINT will be used  by
default.

These are the keywords that may be used:
  APPEND
  NEW
  PRINT
  QUIET

For  an  explanation  of  what  the keywords mean, please refer to the
PARAMETERS section of this help text.
!
!=============================================================================!
! Key 3								   NOSUCHFILE !
!=============================================================================!
!
3 NOSUCHFILE
%XRUN-E-NOSUCHFILE, no such file

The  specified  listfile  does  not  exist  and the keyword APPEND was
specified.  Please reenter the command with an existing file name,  or
omit the APPEND keyword.
!
!=============================================================================!
! Key 3								   NOSUCHPROG !
!=============================================================================!
!
3 NOSUCHPROG
%XRUN-E-NOSUCHPROG, no such program

The specified program does not exist.  Please reenter the command with
an existing program name.
!
!=============================================================================!
! Key 3								       NULFIL !
!=============================================================================!
!
3 NULFIL
%XRUN-E-NULFIL, missing or invalid file specification - respecify

The specified listfile is not correct according to  the  VAX/VMS  file
specification  rules.   Please  reenter  the  command  with  a correct
listfile specification or omit the listfile parameter entirely.
!
!=============================================================================!
! Key 3								      TOOMANY !
!=============================================================================!
!
3 TOOMANY
XRUN-E-TOOMANY, too many parameters

XRUN only allows three parameters. You have specified more than three.
Reenter the XRUN command correctly.  If you  are  specifying  multiple
keywords  as  the  third  parameter,  make  sure that the keywords are
separated be commas  only  -  no  extra  spaces.   If  you  do  insert
additional   spaces,   XRUN   may  incorrectly  count  the  number  of
parameters, resulting in this error message.
!
!=============================================================================!
!							   END OF HELP MODULE !
!=============================================================================!
