12/02/85  pl1_macro, pmac

Syntax as a command:  pmac in_path {out_path} {-control_args}


Function: invokes the stand-alone pl1 macro processor to translate a
segment in accordance with the defined pl1 macro language.


Arguments:
in_path
   is the pathname of the source segment.  The source segment name must
   have at least three components, a suffix of "pmac", and a
   penultimate component of "pl1" or "cds" or "rd".  If you don't
   supply the suffix, it is assumed.  The star convention is not
   supported.
out_path
   is the pathname of the macro processed output segment.  If you
   haven't used -print or -process_dir, then the name of the inpath
   less the suffix is assumed if not given.  The outpath cannot be the
   same segment as the inpath.  The equal convention is not supported.
   This argument is incompatible with -print and -process_dir.


Control arguments:
-arguments STRs, -ag STRs
   passes the strings as command line arguments.  It must be the last
   control argument, and at least one STR must follow.  These arguments
   are used in conjuntion with the %isarg macro construct (see "Notes
   on command line argument testing" below).
-call STR
   calls STR as a command after the translation is complete if the
   macro processor does not discover an error.
-no_version, -nver
   does not print the version of pl1_macro.


-parameter IDENTIFIER VALUE, -pm IDENTIFIER VALUE
   sets the value of macro replacement identifiers on the command line.
   IDENTIFIER must be a pl1 identifier; VALUE, a decimal integer, a bit
   string constant, a character constant, or an identifier.  (See
   "Notes on command line constants and their defaults.")
-print, -pr
   prints the macro processed output on user_output rather than place
   it in a segment.
-process_dir, -pd
   places the macro processed output in the process directory rather
   than in your working directory.


-target STR, -tgt STR
   makes the macro processor interpret STR as a target machine and sets
   the %target builtin (see "Notes on code for different target
   machines").
-version, -ver
   prints the version of pl1_macro.  (Default)


List of macro constructs and builtin variables:
%INCLUDE <identifier>;
   provides an expansion time include file feature.
%INCLUDE <quoted-string>;
   provides an expansion time include file feature.
%abort <char_string>;
   allows you to send messages to user_output at macro time and sets
   the minimum value of pl1_macro_severity_ to four.
%default <identifier> to <constant-expression>;
   is ignored if the identifier has been used in a parameter statement;
   otherwise, causes the same substitution behavior as %replace.
%error <char_string>;
   allows you to send messages to user_output at macro time and sets
   the minimum value of pl1_macro_severity_ to three.


%if <constant-expression> %then <token-string>
   where <token-string> is a possibly null string of tokens and the
   <constant-expression>'s must evaluate to a bit_string constant.
%isarg (<char_string>)
   is a macro builtin function that returns a value of data type bit
   (1).
%isarg (<pl1-token>)
   is a macro builtin function that returns a value of data type bit
   (1).
%isdef (<identifier>)
   is a macro builtin function that returns a value of data type bit
   (1).
%print <char_string>;
   allows you to send messages to user_output at macro time and sets
   the minimum value of pl1_macro_severity_ to zero.


%replace <identifier> by <constant-expression>
   where <constant-expression> is an expression whose operands are
   either constants or identifiers previously defined in other
   statements or on the command line.
%set <identifier> to <constant-expression>
   is like %replace in the way it deals with replacement activity and
   constant expression evaluation, conflicts with parameters, etc.
%target (<identifier>)
   is a replacement identifier of data type bit (1) whose value is
   true only if the value of the <identifier> is equal to the value of
   the identifier given as the argument of -target on the command
   line.


%warn <char_string>;
   allows you to send messages to user_output at macro time and sets
   the minimum value of pl1_macro_severity_ to one.
[%else <token-string>] %endif
   where <token-string> is a possibly null string of tokens.
[%elseif <constant-expression> %then <token-string>]...
   where <token-string> is a possibly null string of tokens and the
   <constant-expression>'s must evaluate to a bit_string constant.


Notes on basic replacement construct: To facilitate the use of named
constants in places where internal static options (constant) don't
work (e.g., label arrays and functions of named constant), there are
three ways of defining replacement identifiers--pl1_identifiers that
are transformed at lex level to their defined values--by the %replace
statement, by the %set statement, and, on the command line, by the
%default statement.


Notes on macro time constants:
   %replace <identifier> by <constant-expression>
where <constant-expression> is an expression whose operands are either
constants or identifiers previously defined in other statements or on
the command line.  The valid operators are the arithmetic ones (+, -,
*, and /) the concatenation operator (||), the logical operators (^, &,
and |), and the relational operators (=, ^=, <, <=, >, >=, ^>, and ^<).
Arithmetic values are represented internally as fixed binary (71).
Parentheses can be in all expressions.  The usual semantics of
expression evaluation apply, and pl1-like conversions are not done
implicitly.


Semantic Rules--
   1. All replacement identifiers must be lexically declared by a
      replace statement prior to use.
   2. A replacement identifier may not appear lexically prior to its
      declaration in a replace statement.  This is to insure that its
      meaning remains constant throught the compilation unit.
   3. Once declared, a replacement identifier may not be redefined to
      have a different value by a replace statement, nor is there any
      way to "undefine" a replacement identifier; however, to
      facilitate replacement identifiers being used in a variety of
      include files, redeclaration to the same value is permitted.


   4. After its declaration, the replacement identifier is replaced
      where it appears as a token in the lexed source by the value
      defined in the replace statement.
   5. Replacement identifiers have four data types: arithmetic, bit,
      character, and identifier.  For all data types, operands must
      agree with their operators.  The identifier data type is
      associated with no operator except the = and ^= comparison.


Notes on macro time variables:
   %set <identifier> to <constant-expression>

The %set statement is like the %replace statement in the way it deals
with replacement activity and constant expression evaluation, conflicts
with parameters, etc.  The only difference is that the placement
identifier declared in an %set statement may appear in another %set
statement with a different value.  Its replacement rule is that it uses
the value set in the last %set statement (in the lexical sense).  The
use of variables in any two of %default, %replace, and %set statements
is not allowed.


Notes on command line constants and their defaults: The -parameter
control argument allows the virtual equivalent of a replacement
identifier declaration on the command line.

The macro processor uses the replacement identifiers as though they had
been declared in %replace statements, with two important differences:
(1) these parameters must not be declared in the source in a %replace
statement, even to the same value; (2) they must be declared in a
%default statement.  If the same identifier appears in more than one
instance of a "-pm IDENTIFIER VALUE" triplet, the last such triplet
takes effect.

   %default <identifier> to <constant-expression>;


If the identifier has been used in a parameter statement, this
statement is ignored except to check that the data type of the constant
given in the command line and the data type of the expression in the
statement agree; otherwise, this statement causes the same substitution
behavior as a %replace statement.


Notes on macro variable declaration builtin:
   %isdef (<identifier>)
is a macro builtin function that returns a value of data type bit (1).
Its value is true only if the argument is a macro replacement
identifier that you have lexically declared either in a %default, %set,
or %replace construct prior to using %isdef or as a command line
parameter.


Notes on command line argument testing:
   %isarg (<pl1-token>)
   %isarg (<char_string>)
is a macro builtin function that returns a value of data type bit (1).
Its value is true only if the argument is one of the character strings
following -arguments on the command line.

The character string form of the argument is necessary if a command
line argument is a string according to the command processor, but is
not a pl1 token (e.g., 34xy).  If the argument to %isarg is a character
string, it is dequoted and the dequoted value is used in the test; for
example, if the command line has -ag 34xy, the test in the source must
be phrased as %isarg ("34xy"), rather than %isarg (34xy) because the
macro processor works on pl1 tokens.  So use only identifiers as
command line arguments, to facilitate more reasonable-looking code.


Notes on conditional compilation:
   %if <constant-expression> %then <token-string>
   [%elseif <constant-expression> %then <token-string>]...
   [%else <token-string>] %endif
where <token-string> is a possibly null string of tokens and the
<constant-expression>'s must evaluate to a bit_string constant.
Semantic Rules--
   1. The usual semantics of if-then-elseif-then-else statements apply.
      If the boolean expression in the test clause equals ""b, then the
      condition is false, otherwise it is true.  The %elseif and %else
      terms are optional, but the %then and %endif keywords are
      required.
   2. The conditional compilation construct is invalid if all the
      constant expressions do not evaluate to proper logical values.


   3. There is no restriction on what may appear as the object
      token-string of a then or else clause.  In particular it may be
      standard pl1 tokens or further macro constructs such as %replace,
      %include, etc.
   4. In order to facilitate the maintainability of code, use the
      conditional compilation facility to construct token strings that
      comprise entire pl1 statments, rather than code fragments.


Notes on code for different target machines: there is a strategy for
informing translators which machine they should generate code for.
The macro processor also uses this same strategy for use in
conditional compilation.

   %target (<identifier>)
is a replacement identifier of data type bit (1) whose value is true
only if the value of the <identifier> is equal to the value of the
identifier given as the argument of -target on the command line.  If
you use %target without -target, a default value is supplied and an
error of severity 2 indicated.  If you don't use %target, then you need
supply no information on the command line about the target machine.


There are currently two flavors of target machines.  The names l68,
6180, and dps8 are cannonically equivalent and refer to the standard
Multics cpu's.


Notes on expansion time include files:
   %INCLUDE <identifier>;
   %INCLUDE <quoted-string>;
provides an expansion time include file feature.  Include files are
found through the translator search rules and have the same naming
conventions as compile time include files.  You are permitted a maximum
of 255 include files in one expansion, and you can nest them 64 deep.
This differs from %include in that the macro processor merely checks to
see that the %include statement is syntactically correct and outputs
the statement.


Notes on user-generated messages:
   %print <char_string>;
   %warn <char_string>;
   %error <char_string>;
   %abort <char_string>;

The macro processor sets a severity, an external fixed binary (35)
variable, called pl1_macro_severity_.  These four constructs allow you
to send messages to user_output at macro time and set the minimum value
of pl1_macro_severity_ to zero, one, three, and four respectively.  The
%abort construct immediately aborts the macro_processor.  The
char_string can be generated as a result of macro time activity.


Notes on skip and page macros: These are features that the pl1
compiler accepts.  The macro processor checks them for syntactic
correctness and passes the statement through.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved