!==============================================================================
! This help file really documents our XPASCAL command, not XCOMPILE.   For  all
! the languages that we use, we define explicit  symbols  which  call  XCOMPILE
! but the students never really know that there is one common  procedure.   For
! example, for pascal we define the symbol
!	$ XP*ASCAL :== @ACC_USERCOM:XCOMPILE.COM PASCAL
!
! Therefore, this help file doesn't ever acknowledge the existence of the first
! parameter to XCOMPILE - the language name.  Other than this slight adjustment
! this help file accurately reflects XCOMPILE.
! 
!=============================================================================!
!  DIVISION   I	:				     HELP MODULE DECLARATION  !
!=============================================================================!
!									      !
!      -----------------------------------------------------------------      !
!      SECTION 01 :					 INITIAL VERSION      !
!      -----------------------------------------------------------------      !
!									      !
!      File Specification: ACC_HELP:XPASCAL.HLP				      !
!      Author		 : Harlan H. Bloom				      !
!      Initial version	 : 01.00.00 06-NOV-1985	VMS 4.2			      !
!									      !
!      -----------------------------------------------------------------      !
!      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)............	XPASCAL				      !
!	 Key 2 ........................	  Parameters			      !
!	 Key 2 ........................	  Operation			      !
!	 Key 2 ........................	  Example			      !
!	 Key 2 ........................	  Errors			      !
!	   Key 3 ......................	    FATALERR			      !
!	   Key 3 ......................	    IVKEYW			      !
!	   Key 3 ......................	    NOSUCHPROG			      !
!	   Key 3 ......................     Rename File Name		      !
!	   Key 3 ......................	    TOOMANY			      !
!									      !
!=============================================================================!
!
!
!=============================================================================!
! Key 1								      XPASCAL !
!=============================================================================!
!
1 XPASCAL
This will compile a  user-specified  program  written  in  the  PASCAL
language.  Optionally, during compiling of your program you can have a
compiler listing of your program sent to the line printer or put  into
a  file for future reference.  Also, you can use the Symbolic Debugger
or XRUN programs to aid in debugging your programs.

Format:

     XPASCAL program [listopt] [compileopt] [linkopt] [runopt]
!
!=============================================================================!
! Key 2								   Parameters !
!=============================================================================!
!
2 Parameters
program

  This is the name of your program that you wish to have compiled  and
  run.  This parameter is required.

listopt

  These  options are designed to help you in debugging or running your
  programs.  This parameter is optional.  If you would like  to  leave
  this  parameter  blank  in order to use the other parameters, please
  use a pair of double quotes (""). Valid keywords are:

    FILE    - Have the compiler listing written into a file.
    LP      - Have  the  compiler listing printed on the line printer.
    DEBUG   - Include the symbolic debugger with your program.  If you
              wish to use the symbolic debugger  to  aid  in  locating
              logic errors in  your  program,  you  must  select  this
              option.  The symbolic debugger  must  be  compiled  with
              your program.
    XRUN    - Run the program using XRUN.

compileopt

  Any qualifier available on the PASCAL command may be  entered  here.
  Enclose  all  such  qualifiers in double quotes.  The qualifiers you
  specify will be appended to the PASCAL command executed by  XPASCAL.
  This  parameter  is  optional.   If  you  would  like  to leave this
  parameter blank in order to use the other parameters, please  use  a
  pair of double quotes ("").

linkopt

  Any qualifier available on the LINK command  may  be  entered  here.
  Enclose  all  such  qualifiers in double quotes.  The qualifiers you
  specify will be appended to the LINK command  executed  by  XPASCAL.
  This  parameter  is  optional.   If  you  would  like  to leave this
  parameter blank in order to use the other parameters, please  use  a
  pair of double quotes ("").

runopt

  Any qualifier available on the RUN  command  may  be  entered  here.
  Enclose  all  such  qualifiers  in double quotes.  This parameter is
  optional.  The qualifiers you specify will be appended  to  the  RUN
  command executed by XPASCAL.
!
!=============================================================================!
! Key 2								    Operation !
!=============================================================================!
!
2 Operation
XPASCAL  is designed to make compiling, linking  and running a program
simpler.  It allows you to enter only one command instead of having to
type in the three commands PASCAL, LINK, and RUN.

Here  is  an  example  to  illustrate  how  the  conventional  way  of
compiling, linking, and running a program compares to  using  XPASCAL.

First,  the  conventional  way  to  compile,  link and run the program
FRED.PAS:

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

Now, here is how XPASCAL works using the same sample program:

  $ XPASCAL FRED.PAS
  %XPASCAL-I-CSTART, starting compile 28-SEP-1985 10:10:05.82
  %XPASCAL-I-RSTART, starting run 28-SEP-1985 10:10:13.64
  Please type in a number: 5
  Please type in a second number: 3
  The sum of the numbers is 8

If you do not give a file type (i.e.:  .PAS) then XPASCAL will  expect
to  find  a  file  type  of  .PAS  on the file name when you enter the
command.  If you do not have this file type on the file name,  XPASCAL
will  abort  with  an error.  Also if you have a file type of a period
("."), XPASCAL will give a message on how to put a correct  file  type
on the program name.  Please follow the example.
!
!=============================================================================!
! Key 2								      Example !
!=============================================================================!
!
2 Example
The easiest method of using XPASCAL requires you  to  only  enter  the
name of the program to compile, link and run:

  $ XPASCAL EXAMPLE.PAS
  %XPASCAL-I-CSTART, starting compile 28-SEP-1985 10:10:05.82
  %XPASCAL-I-RSTART, starting run 28-SEP-1985 10:10:13.64
  (you would enter any input your program expects)

After the RSTART message, your program will execute just as if you had
entered the RUN command.  If your program prompts for input,  you  can
now enter it.

The way to get a compiler listing of your program is to use the LP option:

  $ XPASCAL EXAMPLE.PAS LP
  %XPASCAL-I-CSTART, starting compile 28-SEP-1985 10:10:05.82
  %XPASCAL-I-RSTART, starting run 28-SEP-1985 10:10:13.64
  (you would enter any input your program expects)

  Job EXAMPLE (queue SYS$PRINT, entry 1) pending

When the line printer stops printing, you can then  get  your  program
listing.

There  are  times that you may need to use different options with your
program.  This example shows you  how  to  use  a  compile  option  to
increase  the  number of errors the PASCAL compiler will detect before
terminating.  Similar commands can be used  to  specify  link  or  run
options as well.

  $ XPASCAL EXAMPLE.PAS "" "/ERROR_LIMIT=100"
  %XPASCAL-I-CSTART, starting compile 28-SEP-1985 10:10:05.82
  %XPASCAL-I-RSTART, starting run 28-SEP-1985 10:10:13.64
  (you would enter any input your program expects)
!
!=============================================================================!
! Key 2								       Errors !
!=============================================================================!
!
2 Errors
Errors detected  by  XPASCAL  are  prefixed  with  the  facility  name
%XPASCAL.   These errors are described in the sub-topics which follow.
Also, if you specify  any  compileopt,  linkopt  or  runopt,  you  may
receive  other  error  messages  from  the  system  if the options are
incorrect.
!
!=============================================================================!
! Key 3								     FATALERR !
!=============================================================================!
!
3 FATALERR
%XPASCAL-E-FATALERR, internal inconsistency

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

One of the words given in  the  listopt  parameter  is  not  known  to
XPASCAL.  Please reenter the command with a correct keyword.

These are the keywords that may be used:
  DEBUG
  FILE
  LP
  XRUN

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

The specified program does not exist.  Please reenter the command with
an existing program name.
!
!=============================================================================!
! Key 3							     Rename_File_Name !
!=============================================================================!
!
3 Rename_File
No specific error message is displayed but you  will  receive  a  text
mesage similar to the following:

+------------------------------------------------------+
|                                                      |
|     XPASCAL expected to find:                        |
|          FRED.PAS                                    |
|     No  such program  was  found.  A file  named     |
|          FRED.;                                      |
|     is present.  This can happen if  you  failed     |
|     to  specify  a  file  type  when  you  first     |
|     created this file in the editor.                 |
|                                                      |
|     If  your  program  is  really  in  the file:     |
|          FRED,;                                      |
|     you should rename your program to:               |
|          FRED.PAS                                    |
|                                                      |
|     The command to do this is:                       |
|                                                      |
|     RENAME FRED.;* FRED.PAS;*                        |
|                                                      |
|     You must do this yourself, this program will     |
|     not do it for you.                               |
|                                                      |
+------------------------------------------------------+

XPASCAL assumes your program is in a file with a type of .PAS. In this
case, it did not find such a program but it did find  a  file  with  a
null type.

If  you  forget to specify a file type when you first created the file
in an editor, you will end up with this situation.

For example, if you entered:

  $ EDT FRED

you will end up with a file in you directory

  $ DIRECTORY

  FRED.;1

To correct the file type, all you need to do is enter the command:

  $ RENAME FRED.;* FRED.PAS;*
!
!=============================================================================!
! Key 3								      TOOMANY !
!=============================================================================!
!
3 TOOMANY
XPASCAL-E-TOOMANY, too many parameters

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