perm filename SNAIL.MJC[S,DOC] blob sn#354909 filedate 1978-05-12 generic text, type C, neo UTF8
C00001 00001
C00004 00002	                                 S N A I L
C00007 00003	                         SNAIL: EDIT-Class Commands
C00014 00004	                       SNAIL: COMPILE-Class Commands
C00016 00005	                SNAIL: DOCUMENT-Type COMPILE-Class Commands
C00018 00006	                 SNAIL: LOADBUF-Type COMPILE-Class Commands
C00023 00007	                 SNAIL: COMPILE-Type COMPILE-Class Commands
C00035 00008	                         SNAIL: More on File Names
C00037 00009	                          SNAIL: More on Switches
C00039 00010	                    SNAIL: Concatenation of Source Files
C00042 00011	                     SNAIL: Producing Symbolic Listings
C00046 00012	                SNAIL: Generating Core Images and DMP Files
C00051 00013	                          SNAIL: Library Searches
C00054 00014	                    SNAIL: Alternate Processor Features
C00058 00015	                         SNAIL: Translator Switches
C00060 00016	                           SNAIL: Loader Switches
C00062 00017	                            SNAIL: Command Files
C00065 00018	                            SNAIL: CREF Command
C00066 00019	                       SNAIL: Switch Function Summary
C00070 00020	                SNAIL: LOADER Switches and LINK Equivalents
C00074 00021	                           SNAIL: Error Messages
C00079 ENDMK
                                 S N A I L

This documentation  is  extracted from  Appendix 1  of  the Monitor  Command
Manual, which can be  found online in the file MONCOM.BH[S,DOC]  or in print
as SAILON 54.5.

SNAIL is  a program  which interprets certain  monitor commands  for editing
files, compiling and loading  programs, and loading the line  editor buffer.
It simplifies these tasks when necessary by expanding concise  user commands
into  the different  forms  used by  editors, language  processors,  and the
loaders.  Without  user intervention,  SNAIL will  run the  correct language
processors to translate the user's files, and will run a loader to create an
executable core image containing the user's program.  SNAIL also  provides a
convenient means of communication between editors and other processors.

(You may occasionally encounter a bug in SNAIL.  When this unfortunate event
happens,  you should run TSNAIL,  a version of SNAIL which includes RAID and
various debugging routines.  To use TSNAIL,  type  R TSNAIL  to the monitor,
then type the SNAIL command in answer to the asterisk prompt.  TSNAIL pauses
occasionally  to display interesting information;  type a blank  to continue
processing.  When TSNAIL exits,  save the core image and notify  MJC  of the

SNAIL knows about certain  standard processors.  These are the  editors: SOS
and TECO;  the compilers:  SAIL, FAIL,  F40 (FORTRAN),  MACRO, and  PAL; the
document compilers: PUB and POX; the debuggers: BAIL, RAID, and DDT; and the
loaders: LOADER and LINK.

The E editor includes within it the SNAIL functions, so its "SNAIL" commands
run  E directly  rather than  via the  SNAIL program.   Nevertheless,  the E
commands are included here because they are operationally similar.

The SNAIL commands are divided into three classes: EDIT, COMPILE, and CREF.
                         SNAIL: EDIT-Class Commands

There are six EDIT-class commands,  two for each of the three  commonly used

                                         Command Name
               Program            Create File    Edit File

               E                  CETV           ETV
               SOS                CREATE         EDIT
               TECO               MAKE           TECO


These commands take a file name as the argument.  SNAIL will call the editor
and tell it to initialize the file of that name.  For CREATE, SOS is started
in line  insertion mode.   TECO (the  MAKE command)  will be  initialized to
write on the specified file.


These commands take a  file name (with optional project-programmer  name) as
the argument.  SNAIL remembers the name of the last file that was  edited in
a tmpcor file named ED.  (A tmpcor file is a simulated file kept in  core by
the monitor until the job is logged out.)  If an EDIT-class command is given
without an argument, SNAIL will use the argument that it remembered.

If no extension is specified in the argument and no file with the given name
and blank extension can be found, then the user's directory is  searched for
any file with  the given name and  one of several standard  extensions.  The
standard extensions are searched in the order:


If none of these is found,  the first file listed in the directory  with the
correct name and any extension is edited.

If a user  specifies a disk  area other than  his own current  (alias) area,
then the edited file will be put  on his disk area and the source  (from the
other area) will not be changed.

The editors have a  read-only mode in which  files may be examined  by using
editor commands, but not changed.   To get read-only mode type /R  after the
file name in  the edit command (e.g.,  ETV M.SAI/R).  Read-only mode  in SOS
prohibits any  commands that would  change the file.   In the E  editor, the
mode may be changed from read-only to read-write at any time.


These are the create  and edit commands for the  E editor.  They do  not run
the SNAIL program; instead,  E itself simulates the SNAIL  functions.  There
are some differences between these and the other editor commands:

1.  The command can include /nP  and /nL switches for page and  line numbers
and the  /N switch for  no-directory mode  as well as  /R for  read-only.  E
saves its position in the file when it exits, so a later ETV command with no
argument will continue the edit from the same point in the file.

2.  If you specify  a PPN with the filename  given, E will let you  edit the
file on that disk area instead  of copying the file to your current  area as
the other editors do.


The READ command starts E in a special mode, called book mode, used  to read
long  files over  an extended  time period.   In this  mode, E  does several
things differently from the normal editing procedure:

1.  If there is a file with the name in the READ command, the extension BKP,
and a PPN matching either that given in the command, your ALIAS PPN, or your
login PPN (tried  in that order),  it is used as  a SNAIL file  to determine
where to  start editing  the specified  file.  This  "bookmark" file  is not
deleted by  LOGOUT, so  you can continue  reading at  a later  session.  The
file, if found, is updated when you  exit from E; if there was no  BKP file,
one is created  on your (alias)  area when you  exit.  However, if  you exit
from E while on the last page  of the file, the BKP file will be  deleted (E
assumes you have finished reading the book in this case).

2.  A READ command with no  argument uses tmpcor files like the  ETV command
does, but the  tmpcor filename used is  different, so you can  alternate ETV
and READ commands for different files with no confusion.

3.  E does not allow you to modify the file when using book mode.
                       SNAIL: COMPILE-Class Commands

There  are three  types  of COMPILE-class  commands:  COMPILE-type commands,
which  abbreviate a  series  of commands  to compilers  (and  other language
processors) and loaders;  DOCUMENT-type commands, which process  a document;
and LOADBUF-type commands, which load the line editor buffer with a sequence
of commands  much like  the DO  processor (see  Section 5.7  of the  Monitor
Command  Manual, in file MONCOM.BH[S,DOC]).  Each  COMPILE-class command, if
given with  arguments, remembers both  the command  and the  arguments in  a
tmpcor file  named CM.   This  is useful  because all  the editors  allow an
exit-and-go command  (in SOS, the G command; in E, the CONTROL-X GO command;
in TECO, the EG command).   The exit-and-go feature runs SNAIL in  a special
way which makes SNAIL re-execute the command that it remembered.
                SNAIL: DOCUMENT-Type COMPILE-Class Commands

The DOCUMENT-type COMPILE-class commands are the easiest to describe.  These
commands,  PUB and  POX,  run the  document  processors PUB  and  POX.  Both
commands take  a file name  as an argument,  with optional switches.   If an
extension is  specified with the  file name, that  file is processed  by the
appropriate  document processor.   If, on  the other  hand, no  extension is
specified with the file name, the user's directory is searched first for the
file  with the  given name  and  extension .PUB  or .POX,  depending  on the
command, then for the file with the given name and no  extension.  Whichever
of those  files is found  first is the  one which will  be processed  by the
document processor.

Switches  to  the  document  processor  may  be  specified   in  parentheses
immediately following the file name.

Examples of use:

        POX FOO.POX
        PUB FOO.PUB(LH)
        PUB XXX

The last of these will run  PUB on the file XXX.PUB if it  exists, otherwise
it will run PUB on XXX.
                 SNAIL: LOADBUF-Type COMPILE-Class Commands

The second  type of  COMPILE-class commands  are the  LOADBUF-type commands.
There  are three  such commands:  RER, RERUN,  and PROCESS.   These commands
incorporate some of the features  of the DO processor, allowing the  user to
take advantage of  the exit-and-go feature of  the editors for  an arbitrary
sequence  of  commands  without  paying  the  penalty  of  running  an extra

The RER  and RERUN commands  are similar  in form.  Both  are followed  by a
processor name, an optional core size for the processor, a double-arrow, and
a string (called the object string) terminated by a line feed.   SNAIL swaps
control to the designated processor after loading the object string into the
line editor buffer.   The only difference is  that the processor in  the RER
command is  retrieved from the  SYS: disk area,  while the processor  in the
RERUN command is  retrieved from the  user's own disk  area, or one  that he
specifies explicitly.  This distinction is  the same one made between  the R
and RUN monitor commands.

The PROCESS  command is  followed by  a double-arrow  and an  object string,
terminated by a  line feed.  After loading  the object string into  the line
editor buffer, SNAIL exits.

SNAIL preprocesses  the object  string for all  three commands  by replacing
occurrences of  the character double-arrow  ("↔") by a  carriage return-line
feed.    The   DO   processor   also   does   this.    However,   the  other
character-replacement features of DO are not currently implemented.

The RER and RERUN  commands are compatible in  the following way.  If  a RER
command with its arguments has  been previously given by the user  and saved
by SNAIL in a tmpcor file, and the user subsequently types RERUN without any
arguments, the effect will be that of typing RERUN with the arguments of the
previous RER  command.  That is,  the processor will  be retrieved  from the
user's disk area  instead of from the  system disk area.  Analogously,  if a
RER command with no arguments is given and the command file contains a RERUN
command, the  designated processor  is retrieved from  the system  disk area
instead of the user-specified disk area.  In either case, the core  size and
object string are processed as described above.

If a  PROCESS command is  given with no  arguments, the command  tmpcor file
must contain a PROCESS command.  If a RER or RERUN command is given  with no
arguments, the  command tmpcor  file must  contain a  RER or  RERUN command.
Otherwise an error message will  be printed and the line editor  buffer will
not be loaded.

Examples of use:

        RER IL↔(DSKIN FOO)↔

The first two examples will do  the same thing.  The third example  could be
used  to allow  alternating use  of  RER and  RERUN to  compare  the current
version of ILISP with a new version.
                 SNAIL: COMPILE-Type COMPILE-Class Commands

The last type of COMPILE-class  command to be described is  the COMPILE-type
command.   There  are  six COMPILE-type  commands:  COMPILE,  LOAD, PREPARE,
DEBUG, EXECUTE, and TRY.  Following the command, the user lists  files which
are to be compiled or loaded.

All  COMPILE-class  commands  normally cause  compilation  of  the specified
source files.  All but the  COMPILE command may cause execution of  a loader
(LOADER or LINK) to create a core image, possibly including a debugger.  The
table below summarizes the actions of the COMPILE-type commands.

            REL file   Core Image   Debugger   Execution

  COMPILE     yes
  LOAD        yes         yes
  PREPARE     yes         yes          yes
  EXECUTE     yes         yes                  starts the user program
  TRY         yes         yes          yes     starts the user program
  DEBUG       yes         yes          yes     starts the debugger

The  COMPILE  command  takes  as arguments  one  or  more  file descriptors,
separated by commas.  SNAIL will cause the appropriate translator to be used
for each of the files.  The  COMPILE command does not produce a  core image;
to get an executable core image one of the other COMPILE-type  commands must
be used.

LOAD does a COMPILE if necessary and then starts a loader (LOADER  or LINK).
The loader  takes the .REL  files that were  generated by the  compilers and
combines them into  an executable core image.   When the loader is  done, it
exits to the monitor.   This command makes a  core image but does  not start
it.  If any SAIL program is loaded, the loader will be instructed to request
the current SAIL segment.

PREPARE is like LOAD, but a debugger (BAIL for SAIL programs, RAID for other
programs when the user  is at a display,  and otherwise DDT) is  loaded with
the user's program.

EXECUTE is like LOAD, but instead of exiting, the loader starts  the program
it loaded at its specified starting address.

The TRY command  is like EXECUTE,  but it loads  a debugger (BAIL,  RAID, or
DDT, as in the PREPARE command) with the user program.  Execution  starts at
the program's starting address.

DEBUG is  like TRY except  that rather than  starting the user's  program it
starts the debugger (RAID or DDT -- if the debugger is BAIL this  command is
treated  exactly  the same  as  TRY).  The  user  may give  commands  to the
debugger to start his program, to plant breakpoints, etc.

SNAIL  writes  tmpcor files  for  each processor  involved  in  compiling or
loading  the  files specified  in  the user's  command  string.   SNAIL also
attempts to minimize unnecessary compilations by checking the creation dates
for the files the user wants compiled; for example, if the command was


and the file X1.REL  has a later creation  date than the file  X1.SAI, SNAIL
assumes that  X1.SAI has not  been changed since  it was last  compiled, and
omits X1.SAI when it tells SAIL which files to compile.  If the REL file and
the source file have the same time written, then the file is  compiled again
for safety, in case the source has been changed.

The user can override SNAIL's date-checking by specifying  certain switches.
A  SNAIL switch  is selected  by  including a  slash ("/")  followed  by the
appropriate switch name.  Switches which affect the date-checking actions of
SNAIL  are  the  following,  where  an  asterisk  ("*")  following  a switch
indicates that that switch selection is the default for SNAIL:

  /COMPILE    Force  recompilation  without  checking  the  dates  of .REL
  /-COMPILE * Check dates  of both  source, .DMP, and  .REL files  and act
  /REL        Force loading from the .REL file if it exists.
  /-REL     * Check dates  of both  source, .DMP, and  .REL files  and act
  /NOLOAD     Don't issue a loading request for this file.
  /-NOLOAD  * Issue a loading request for the file if one is called for.
  /LONLY      (Implies /COMPILE, /NOLOAD,  and /NODMP.)  A  listing should
              be made for this file, but no load request for it  should be
  /-LONLY   * Treat this file normally.
  /CONLY      (Implies /COMPILE, /NOLOAD, and /NODMP.)   A cross-reference
              listing should be  made for this  file, but no  load request
              for it should be issued.
  /-CONLY   * Treat this file normally.
  /LIBRARY    (Implies /REL.)  Force the  loader to search this file  as a
  /-LIBRARY * Treat this file normally.
  /NODMP      Don't  include the  .DMP file  in date-checking  or deciding
              which file  to give  control to first.   This switch  has no

SNAIL remembers the last  COMPILE-type command with arguments it  was given,
just as it does for  DOCUMENT-type commands and LOADBUF-type commands,  in a
tmpcor file named CM.  This "remembering" may be turned off for COMPILE-type
commands by using the /NOCMFI  switch; if this switch appears in  a command,
the CM file  will not be  written for that  command.  This switch  is useful
when using either a LOADBUF-type command or the DO processor,  and including
within the  command string another  SNAIL COMPILE-class command;  if /NOCMFI
were not specified, the second command would be saved in the CM file instead
of the first.

The simplest way to translate  several programs is to create them  with file
extensions which define the processor to be used; then give a single COMPILE
command with all these names separated by commas.  (If a  standard extension
is  specified  for a  file,  SNAIL cannot  be  convinced to  use  some other
processor.)  Extensions which SNAIL knows about are the following:

  .FAI     signals a Fail program
  .SAI     signals a Sail program
  .MAC     signals a Macro program
  .F4      signals a Fortran program
  .PAL     signals a Palx program

SNAIL does  not require  file extensions  to be  typed explicitly.   For the
command COMPILE FOO, SNAIL  will look for any  file named FOO and  check its
extension.   If a  file FOO  is found  that does  have one  of  the standard
extensions, SNAIL will select the corresponding translator.  If a  file does
not have a standard extension, SNAIL can be told which translator to  use by
giving that information  in the command  string.  Switches which  tell SNAIL
which translator to select are the following:

  /FAIL    Process this file with the Fail assembler.
  /-FAIL   Process this file with some translator other than Fail.
  /SAIL    Process this file with the Sail compiler.
  /-SAIL   Process this file with some translator other than Sail.
  /MACRO   Process this file with the Macro assembler.
  /-MACRO  Process this file with some translator other than Macro.
  /F4      Process this file with the Fortran compiler.
  /-F4     Process this file with some translator other than Fortran.
  /PALX    Process this file with the Palx assembler.
  /-PALX   Process this file with some translator other than Palx.
                         SNAIL: More on File Names

A project-programmer name (PPN) may  be included with each file name  in the
command for COMPILE-type commands, just like for other SNAIL  commands.  The
PPN specifies the  disk area from  which the file is  to be read.   The PPN,
enclosed in square brackets ([ and ]), usually follows a file name;  in this
case the PPN applies only to the preceding term.  If a PPN appears  before a
file name, then that PPN is  sticky (i.e., it applies to all the  terms that
follow) for the rest of the command until another sticky PPN is seen.

A name followed  by a colon  (:) is a device  name (which is  sticky).  Some
devices are non-directory devices (for instance, TTY: and MTA:); a file name
need not follow specification of such a device.  For example, the command


compiles, using the SAIL compiler, input from the user's terminal.
                          SNAIL: More on Switches

Switches are allowed in COMPILE-class commands by including a slash  (/) and
the switch name,  e.g., /LIST.  Switches allow  the user to  select options.
In general, a switch placed  before a file name is sticky.   Switches placed
after a file  name are not  sticky; they apply  only to the  preceding term.
Specifying  a  minus ("-")  before  a  switch turns  off  that  switch.  For
example, the command


will compile the files A and B using the FAIL assembler, and will  compile C
using some other translator depending on extensions of files with  file name
                    SNAIL: Concatenation of Source Files

It is  often desirable to  break up  a program into  two (or  more) separate
files which have only  one END statement at the  end of the last  file.  One
reason for breaking up a program is because it is very long, and it would be
inconvenient  to  keep and  edit  such  a large  file.   Another  reason for
separating a program is to allow a portion of the program text to be shared.
Several files can be processed together as one big translation by separating
their names with plus signs (+) rather than with commas.  For example,


treats the files DATA and PROGRM as if they were one large file and produces
one relocatable binary file, PROGRM.REL.  SNAIL will not allow concatenation
of source files that specify inconsistent processors.

Normally, the REL file  will have the name of  the last file in  the command
string; it can be given some  other name by putting the desired name  and an
equals sign (=) at the front of the argument list, e.g.,


would do one translation as if SYMS, PROGRM, and IOPACK were one  large file
and produce relocatable binary output on the file FOO.REL.

Occasionally,  a header  file must  be assembled  with several  other files,


The brokets (< and >) feature allows this to be done more simply:


Brokets may not be nested.  Also, a plus sign may not follow a right broket;
e.g., the following command is illegal:

        COMPILE <A,B,C>+ENDS 
                     SNAIL: Producing Symbolic Listings

Assembly listings have the original code as it appears in the file  plus the
octal values that the code  represents with the relative locations  that the
octal values go in.  Assembly listings can be generated by means of a /LIST,
/LONLY, /CREF, or /CONLY switch in the command.

The /LIST and /LONLY switches will produce a file with the same name  as the
REL file and extension LST.  Such  a file may be spooled or typed.   The two
switches differ  in that  the /LONLY switch  implies /COMPILE,  /NOLOAD, and
/NODUMP; i.e., it means  that the only thing to  do with the file is  make a
listing for it, and  no REL file will be  generated by the compiler  for the
source  file.  Note  that COMPILE FOO/LIST  will not  compile anything  if a
current FOO.REL exists (this  is another instance where the  /COMPILE switch
is useful).  The /LIST may be used  as a sticky switch or it may  be applied
to  particular  terms.   The  inverse  switches  are  /-LIST   and  /-LONLY.
(Processors other than the assemblers may also produce listings.)

If either the /CREF switch  or the /CONLY switch appears, instead  of /LIST,
it generates  an expanded listing  that includes a  list of all  the symbols
(identifiers) used in the program and the line numbers on which  each symbol
appears.  This  is called  a cross-reference  listing.  These  listing files
cannot  be  printed  directly.   Instead,  they  must  be  processed  by the
cross-reference lister program, CREF.  This is done by the CREF command (see
page  18).  The  /CONLY switch  differs from  the /CREF  switch in  that the
source file will always be compiled, and no binary file will be generated by
the compiler  for the source  file.  The distinction  between the  /CREF and
/CONLY  switches is  the same  as  that for  the /LIST  and  /LONLY switches
described above.  Note: not all the processors can produce a cross-reference
listing.  Consult the appropriate manual to find out if a given processor is
capable of generating one.
                SNAIL: Generating Core Images and DMP Files

The  commands  EXECUTE,  DEBUG,  LOAD, PREPARE,  and  TRY  each  generate an
executable core image.  Core images are made by translating source files (as
in the COMPILE command) and  then running a loader (either LINK  or LOADER),
which takes  the REL files  and produces  a core image  from them.   For the
DEBUG, PREPARE, and TRY commands, the loader is instructed to load a copy of
RAID (or DDT if the user is at a Teletype) and the program symbol table with
the core image.

Several SNAIL switches are relevant to the selection of a loader, and to the
actions of  the loader once  it starts loading.   These switches  are listed
below.  None of these switches may be negated; i.e., a minus sign may not be
used with them.

  /LINK    The LINK loader will be used to create the user's core image.
  /LOADER  The LOADER loader will be used to create the user's core image.
  /BAIL    If the command specified  a debugger (i.e., if the  command was
           DEBUG, TRY, or PREPARE), BAIL will be loaded.
  /RAID    If the command specified a debugger, RAID will be loaded.
  /DDT     If the command specified a debugger, DDT will be loaded.
  /MAP     The absolute values of all the global symbols will be listed in
           a legible way  on a file named  MAP.MAP; this may not  work for
  /NOSAISEGThe Sail segment will not be loaded.
  /SAVE    A disk dump will be made of the core image.  The dump file will
           have the same name as the first REL file and extension .DMP; it
           can be given some other name by putting the desired name  and a
           left arrow (←) in the command string.  /SAVE is  unnecessary if
           the left-arrow construct is used.

The command


translates the programs SINE and COSINE, producing SINE.REL  and COSINE.REL.
The LOADER is  run.  Because the TRY  command requests a  debugger, RAID.REL
(or DDT.REL) is  loaded from the system  area.  SINE.REL and  COSINE.REL are
loaded next.  Then  the LOADER makes  a dump copy of  the core image  in the
file DUMP.DMP and starts the program.

If  there already  exists a  DMP file  of the  right name  and if  it  has a
creation date more recent than those of the source files, no loading will be
done.  Instead, the  dump copy itself will  be called in.  Reloading  may be
forced by the /NODMP or /NODUMP switch in the command line.  Both  an equals
sign and a left arrow may be included in a command string.  For example:

   COMMAND                       REL       DMP

                          SNAIL: Library Searches

Several REL files may  be combined into a  library.  A library is  a special
REL file from which  routines may be independently selected.   Library files
are made by combining REL files together using the FUDGE2 program  (which is
described in  DEC documentation).   For example,  sine, cosine,  and tangent
routines  might be  combined  into a  trig  library, TRIG.REL.   Then,  if a
particular program used just the sine routine, instead of loading the entire
trig package it would be able  to select only the sine routine.   The loader
will search library files and  load only the programs that are  needed.  The
/LIBRARY switch after the name of a library file tells SNAIL to request this
loader feature.  The  /LIBRARY switch may also  be used as a  sticky switch;
its inverse is /-LIBRARY.  Suppose there is a program called NLT  which uses
the  sine  routine  that  was  included  in  TRIG.REL.   Then   the  command
LOAD NLT,TRIG/LIBRARY will cause NLT to  be loaded and TRIG to  be searched.
The LOADER notices that NLT requires SINE.REL and searches TRIG.REL  for it.
Suppose  another program,  XLT, requires  routines from  two  library files,
TRIG.REL and IOPACK.REL, and must  be loaded with another program  LT.  Then
any one of the following commands could do this:


Programs which  use library  files must  be placed  before the  library file
names in the command.  This is because the loader cannot know  what routines
to extract from each library  until it has loaded the programs  that require
library routines.
                    SNAIL: Alternate Processor Features

Processors other than SAIL, FAIL,  FORTRAN, PALX, or MACRO may  be specified
by using  the alternate processor  feature.  The  switch /PROCESSOR DEV:NAME
specifies an alternate processor.  In  this switch, DEV (assumed to  be DSK,
if absent) is the device name on which to find NAME.DMP, the core image file
of the alternate processor.  Once the /PROCESSOR switch is used,  SNAIL will
recognize the extension NAM (i.e., the first three letters of  the processor
name) and  the switch  /NAME (the processor  name) in  the command  line.  A
project-programmer  name  or  device  name may  be  used  in  specifying the
alternate processor.

For example,  for a  user to translate  the program  SINE using  a processor
named PROC on his disk area, he could use the command:


When a  standard processor is  used, it is  known that it  will take  a text
source file and  produce a binary  REL file, and  possibly a text  LST file.
With  alternate  processors  there  is  no  such  guarantee.   An  alternate
processor may process a text file  into a new text file which  becomes input
to a standard processor.  It is possible to specify all these functions in a
single COMPILE-type command.

If  an alternate  processor generates  a text  file instead  of a  REL file,
loading  must  be inhibited.   The  /NOLOAD switch  accomplishes  this.  The
/NOLOAD switch must be used for  each term that does not produce a  REL file
(except in the COMPILE command, which does no loading anyway).   The inverse
switch is /-NOLOAD.

Suppose the preprocessor, PRE, translates the file BAZ into a file FOO which
is a FAIL program.  FOO must be translated when PRE is done.  Also, MAIN and
SINE must be translated and loaded with FOO.  The command:


will do all of this.  The /FORWARD switch is necessary because the  file FOO
does not  exist at the  time the command  is given.  Including  the /FORWARD
switch  prevents SNAIL  from looking  for FOO;  SNAIL will  assume  that FOO
magically appears before FAIL is called.  The inverse switch is /-FORWARD.

The processor  DO (see Section  5.7 of the  Monitor Command Manual,  in file
MONCOM.BH[S,DOC])  is another  example of  an alternate  processor.   The DO
program writes the CM tmpcor file to force the exit-and-go command  from the
editors to run DO again.
                         SNAIL: Translator Switches

Switch names enclosed in parentheses "(" and ")" are passed directly  to the
translator.  The  documentation for  each of  the translators  explains what
switches  are available.   The switches  passed in  this way  appear  on the
source file specification.  Sometimes it is necessary to put switches on the
binary  or listing  term.   For this  purpose,  there are  two  other switch

The construction (#1,#2), where #1 and #2 are any switch strings,  passes #1
to the binary term and  #2 to the source term.  The  construction (#1,#2,#3)
passes #1 to the binary term, #2  to the listing term, and #3 to  the source
term.  For example,


will pass the  switch string "AX"  to the binary  term, "BY" to  the listing
term, and "CZ" to the source term.
                           SNAIL: Loader Switches

Switches  to  the  loader  may  be  specified  in  a  COMPILE-class command.
Switches to LOADER appear as a  percent sign (%) followed by a letter  (or a
number and a letter) in the command string of one of the LOAD, TRY, EXECUTE,
PREPARE,  or DEBUG  commands;  switches to  LINK  appear as  a  percent sign
followed by some character not  appearing in the switch string,  followed by
the switch string, followed by the character that appeared after the percent
sign.   In either  case,  the switch  string  is directly  specified  to the
appropriate loader.  Examples:

        TRY BIGPRG.SAI%100K

LOADER and LINK switches are listed at the end of this document.  For a full
description  of  what  the  other  switches  above  mean,  consult  the  DEC
documentation  for  LOADER  and  LINK.  The  LOADER  has  been  modified for
Stanford, so the DEC documentation does not accurately reflect the  state of
the software.  Consult a wizard if necessary.
                            SNAIL: Command Files

COMPILE-class commands are sometimes too long to fit on one line, or are too
complex to be typed correctly every time.  To solve this  problem, arguments
can be read from a file.  The text contained in such a file is read by SNAIL
as if it had been typed as the arguments to a command.  The command file may
contain any features available in a COMPILE-class command.  Any text between
a  semicolon  and  the  next  line-feed  is  ignored;  carriage-returns  and
line-feeds are  also ignored,  and hence may  not be  used to  separate file
names or other identifiers.

To use a term as a command file write an at sign (@) before the command file
name, e.g., LOAD @SYS.  Upon scanning  the at-sign followed by a  file name,
SNAIL  looks  for  a  command  file with  that  name;  if  no  extension was
specified, SNAIL checks first for the file with extension .CMD, then for the
file with no extension and  the specified name.  The command file  SYS might
look like the following file which is used to assemble the  entire operating

                            SNAIL: CREF Command

This command  causes a cross-reference  listing to be  made.  All  the files
made from COMPILE-class commands which used the /CREF switch  are processed;
for each such  file, a cross-reference listing  is generated in a  file with
extension LST and the name of the file being processed.  (LOGOUT makes SNAIL
forget which listing  files to process.)   The CREF command  activates SNAIL
which in turn activates the CREF program in a special way.  The CREF program
when activated in this way reads a file that SNAIL wrote which  contains the
names of the files to process.
                       SNAIL: Switch Function Summary

A  "-" in  the column  headed "*"  means the  switch can  be  negated; e.g.,
/-COMPILE is legal.

  Switch     Abbrev *  Meaning

  /BAIL      /B        Use BAIL if a debugger is required.
  /COMPILE   /COM   -  Force re-compilation without checking the  dates of
                       REL files.
  /CONLY     /CON   -  Force re-compilation  and produce only  an extended
                       listing to be input to the CREF processor.
  /CREF      /C     -  Request a cross-reference listing.
  /DDT       /D        Use DDT if a debugger is required.
  /F4        /F4    -  Use F40 (FORTRAN) for this term.
  /FAIL      /F     -  Use FAIL for this term.
  /FORTRAN   /FORT  -  Use F40 (FORTRAN) for this term.
  /FORWARD   /FORW  -  Prevent SNAIL from looking for this file  to decide
                       if the REL file is up to date.
  /LIBRARY   /LIB   -  Force the loader to search this term as a library.
  /LINK      /LIN      Use the LINK loader to create the core image.
  /LIST      /L     -  Request a listing file.
  /LOADER    /LOA      Use the LOADER loader to create the core image.
  /LONLY     /LON   -  Force  re-compilation  and produce  only  a listing
  /MACRO     /M     -  Use MACRO to translate this term.
  /MAP       /MAP      Request a loader map of global symbols.
  /NOCMFI    /NOC      Don't generate a CM command file for this command.
  /NODMP     /NOD      Force re-loading without checking the dates  of DMP
  /NOLOAD    /NOL   -  Prevent a loading request for this term.
  /NOSAISEG  /NOS      Load SAIL programs with the SAIL library instead of
                       the SAIL segment.
  /PALX      /PA    -  Use  PALX  to translate  this  term  (produces .BIN
  /PROCESSOR /PR    -  Specify an alternate processor.
  /RAID      /RA       Use RAID if a debugger is required.
  /REL       /RE    -  Force loading from the REL file if it exists.
  /SAIL      /S     -  Use SAIL to translate this term.
  /SAVE      /SAV      Force the  LOADER to  make a DMP  file of  the core
                SNAIL: LOADER Switches and LINK Equivalents

  LOADER LINK              Meaning
  Switch Equivalent

  %A     %"CONTENT:ZERO"   Causes a  listing of all  global symbols  to be
  %B     %"SYMSEG:LOW"     BLT symbols down when done loading.
  %1B                      BLT symbols to upper segment.
  %C                       Chain beginning with Common.
  %D     %"TEST:DDT"       Load DDT.
  %E     %"EXECUTE"        Start up program when done loading.
  %F     %"SYSLIB"         Enter library  search mode; search  all default
  %G     %"GO"             Finish loading, make final links, and exit.
  %H     %"DEBUG:RAID"     Load and start RAID.
  %I     %"NOSTART"        Ignore starting address of this program.
  %J     %"START"          Use starting address of this program.
  %nK    %"RUNCOR:n"       Adjust  to n  K of  core (2n  pages)  when done
  %L     %"SEARCH"         Search this file as a library.
  %M     %"MAP:END"        Print storage map.
  %N     %"NOSEARCH"       Leave library search mode.
  %nO    %"SET:.LOW.:n"    Set program origin to n, absolute.
  %P     %"NOSYSLIB"       Inhibit automatic library search  for undefined
  %Q     %"SYSLIB"         Allow automatic library search.
  %R                       Chain beginning with resident module.
  %S     %"LOCALS"         Load symbol table also.
  %T     %"DEBUG:DDT"      Load and start DDT.
  %U     %"UNDEFINED"      Print current list of undefined globals.
  %V     %"TRY:RAID"       Load RAID.
  %W     %"NOLOCALS"       Load without symbols.
  %X     %"CONTENT:NOZERO" Do not list all globals.
  %Y                       Load SAILOW for 2 segment SAIL programs.
  %Z     %"RUN:LINK"       Restart LOADER.
  %<                       Disallow loading into upper segment.
  %1<                      Allow loading into upper segment and load there
  %n<                      (n≥400000) Set upper segment relocation to n.
  %-<                      Allow loading  into upper  segment and  load in
                           lower next.
  %?                       Sort symbols.
                           SNAIL: Error Messages

                               Obvious errors

No command file.
Incompatible commands.
        You gave a command with no arguments, and either no command had been
        saved or the two commands (the  one you typed and the one  which had
        been saved) aren't compatible.

Unrecognizable file name.
No such device.
Unrecognizable processor name.
        You mistyped a file or processor specifier.

Not a display.
        You're trying to load the line-editor buffer and you're not  using a

Missing double-arrow or invalid core size.
Missing double-arrow.
        The LOADBUF-type commands must always be followed by a double-arrow.

Too many files.
        Currently the PUB  and POX document  compilers can only  process one
        document at a time.

File not found.
        Either some file named in the command does not exist, or  it doesn't
        exist with the  correct extension.  You'll  get this message  if you
        try to use the /FAIL switch with FOO.SAI, for instance.

Unknown command.
Command error.
Illegal character.
        Something is wrong with what you typed, and SNAIL didn't find in the
        command what it expected to  find.  For example, a file  name didn't
        follow an at-sign.

Nested brokets illegal.
Unbalanced brokets.
Can't use "=" with brokets.
        You're not using  brokets correctly.  Each  of the files  within the
        brokets  will  produce  a  different  REL  file,  so  the equal-sign
        construct can't be used.

Unknown switch.
Negation of this switch not allowed.
Invalid switch string.
Illegal LOADER switch.
Illegal LINK switch.

                               Subtle errors

Empty command file.
Error in command file.
Tmpcor file too big.
        The CM command file which  SNAIL is attempting to read is  messed up

Storage overflow.
        Your  command included  too much  of something  (file  names, device
        names,  alternate  processor  specifications,  translator  or loader
        switches), or there are too  many files in your directory  that have
        to be date-checked.

               Horrible errors (a wizard should be consulted)

SNAIL bug.
SNAIL allocation error.
        Typing  CONTINUE  followed  by a  carriage  return  when  the latter
        happens might work.

Can't open channel.
        This is probably a bug in SNAIL.

Couldn't create file.
        A disk  file could  not be  written correctly.   Possibly a  file is
        write protected or in use by some other job.  Otherwise you may need

UFD missing.
        You are aliased to a non-existent disk area.  Otherwise, you  need a