11/08/90  pl1

Syntax as a command:  pl1 path {-control_args}


Function: invokes the PL/I compiler.


Arguments:
   path is the pathname of a PL/I source program; the pl1 suffix need
   not be given.  The archive component pathname convention is allowed.


Control arguments:
-source, -sc
   produces a source program listing.
-symbols, -sb
   produces a source program listing followed by a list of all the
   names used in the compilation.
-map
   produces a source program listing followed by a list of all the
   names used in the compilation, followed by a map of the object code
   generated.
-list, -ls
   produces a source program listing followed by a list of all the
   names used in the compilation, followed by an assembly-like listing
   of the compiled object program.


-single_symbol_list, -ssl
   produces a source program listing followed by a list of all the
   names used in the compilation.  The names are listed in one,
   alphabetized list.  If this control argument is not given and
   -symbols, -map or -list are specified, the names will be separated
   into four lists, arranged by declaration type.
-no_list, -nls
   don't produce a source program listing.  (Default)


-optimize, -ot
   invokes an extra compiler phase just before code generation to
   perform certain optimizations.  This control argument should not be
   used while the program is being debugged.
-no_optimize, -not
   don't invoke an extra compiler phase before code generation.
   (Default)


-table, -tb
   generates a full symbol table for use by the probe and debug
   commands.  This is the default unless -optimize is specified.
-brief_table, -bftb
   generates a partial symbol table that consists of only the
   information necessary to set breakpoints by source line number.
-no_table, -ntb
   don't generate a runtime symbol table.  This is the default if
   -optimize is specified.


-prefix STR
   if STR is not null, compiles the program as if it were preceded by
   the condition prefix "(STR):".  STR is a list of one or more PL/I
   condition names separated by commas and optional horizontal white
   space.  Since the program is compiled as if "(STR):" was inserted
   before the first line of the source segment, any condition names
   given in condition prefixes in the source segment override
   condition names for the same condition given in STR.  If STR is
   null, no additional condition prefix is used.  The condition names
   may specify enabled computational conditions or disabled
   computational conditions.


   The  condition  names  for  enabled  computational  conditions are:
   conversion,   conv,   fixedoverflow,  fofl,  overflow,  ofl,  size,
   stringrange,   strg,   stringsize,   strz,  subscriptrange,  subrg,
   underflow,  ufl,  zerodivide  and  zdiv.   The  condition names for
   disabled   computational   conditions  are:  noconversion,  noconv,
   nofixedoverflow,  nofofl, nooverflow, noofl, nosize, nostringrange,
   nostrg,    nostringsize,    nostrz,    nosubscriptrange,   nosubrg,
   nounderflow,  noufl,  nozerodivide and nozdiv.  STR may not contain
   condition  names  for  an  enabled  computational  condition  and a
   disabled  computational condition that identify the same condition.
   See  the  "Notes"  section  for  what  computational conditions are
   enabled by default.


-no_prefix
   turn off any condition prefixes that might have been previously set
   by the use of the -prefix control argument.
-profile, -pf
   generates additional code to count the number of times each source
   statement is executed.  See "Notes" section.
-long_profile, -lpf
   generates additional code to record the virtual CPU time and number
   of page faults taken by the execution of each source statement.
   See "Notes" section.
-no_profile, -npf
   don't generate code to meter the execution of source statements.
   (Default)


-brief, -bf
   omits text of error messages printed on the terminal.  Only the
   error number is indicated.
-long, -lg
   prints text of error message on the terminal the first time the
   message is issued.  (Default)
-severityN, -svN
   prints error messages whose severity is N or greater (N is 1, 2, 3
   or 4).  (Default is 1)


-check, -ck
   used for syntactic and semantic checking of a PL/I program; no
   object segment is created.
-no_check, -nck
   generate an object segment.  (Default)
-check_ansi
   generates warnings for each construct the compiler detects that is
   allowed by Multics PL/I but not by the ANSI standard X3.53-1976.
-no_check_ansi
   don't generate error messages for Multics dependent constructs.
   (Default)


-separate_static, -ss
   generates  separate  sections  in  the  object section for internal
   static variables and linkage information.
-no_separate_static, -nss
   place internal static variables in the linkage section.  (Default)


-debug, -db
   leaves  the  list-structured  internal representation of the source
   program intact after a compilation.  Use pl1$clean_up to discard it.
-no_debug, -ndb
   delete  the  internal  representation  after  compiling  a program.
   (Default)
-time, -tm
   prints  a table after compilation that gives the time (in seconds),
   number  of  page faults, and amount of free storage used by each of
   the phases of the compiler.  Same as pl1$times after a compilation.
-no_time, -ntm
   don't print a table of times used by each phase of the compiler.
   (Default)


-version
   prints out the current version of the compiler.  (Default)
-no_version
   suppresses printing of the current version of the compiler.


Notes:

 If   the  user  specifies  the  -source,  -symbols,  -map,  -list  or
-single_symbol_list  control  arguments,  the  pl1  command  creates a
listing  segment  named  path.list  in  the  working  directory.  If a
control argument and an incompatible alternative are both given on the
command line, the rightmost one is used.


 If  the user  specifies the -optimize control argument, the compiler
will invoke  an extra compiler phase   just before code generation to
perform certain optimizations, and a different algorithm to keep track
of the uses and references of variables. This algorithm  can warn the
user about   unexpected programming practices     under more general
conditions.   Some of which  may not be very obvious to users.   For
example,   both optimized and non_optimized compilation    may  list
different variables that have been referenced but never set.


The  statistics  recorded  by  the  -profile and -long_profile control
arguments  are  perprocess.   They  may  be  printed  with the profile
command.


By  default,  all  computational  conditions  are enabled except size,
stringsize, stringrange, and subscriptrange.

Refer  to  the  "Multics PL/I Specification," Order No.  AG94, and the
"Multics  PL/I  Reference  Manual,"  Order  No.  AM83, for information
about the PL/I language.
