r---~---,---I
: Name : Operation : Operand :
~---J---~---I : A : MEND : Not used, must:
:' sequence : : not be present:
I, symbol or : I II
I I
t not used : I I
L _________________________ ~ _______________ ~
This statement also tells the assembler to terminate processing of a macro defini-tion. ~rocessing can be terminated at some other point in a macro definition through the MEXIT instruction.
MACRO INSTRUCTION PROTOTYPE
The macro instruction prototype statement (also called the prototype statement) specifies the name entry, mnemonic opera-tion code, and the form of all macro instructions that refer to the macro definition. It must be the second state-ment of every macro definition. The typical form of this statement is:
r---r---r---.
: Name : Operation: Operand :
I, - - - - ----1""- - - -t" - - - ---I
: A symbolic: A symbol : Zero to 100 (200 for : : parameter: : F assembler) symbolic:
: or not I I parameters, separatedl
I u s e d : : by commas :
L __________
L _________ ~ ____________________ ~The symbolic parameters are used in the macro definition to represent the name entry and operands of the corresponding macro instruction. A description of sym-bolic parameters appears following Model Statements.
The name entry of the prototype state-ment may be unused or i t may contain a
symbolic parameter.
The symbol in the operation entry is the mnemonic operation code that must appear in
all macro instructions that refer to this macro definition. The mnemonic operation code must not be the same as the mnemonic operation code of another macro definition in the source program or of a machine instruction or assembler instruction.
The operand may contain zero to 100 (200 for F assembler) symbolic parameters
separated by commas.
The following is a prototype statement. L _______ L ____________ L ____________________ ~
Alternate Statement Form
The prototype statement may be written in a form different from that used for machine or assembler instructions. The normal form is described in Part 1 of this publication. continue column, the information entered on that line is considered to be comments, and the operand field is considered terminated. Any subsequent continuation lines are considered to contain only comments.
Note: A prototype statement may be
written on as many continuation lines as is necessary to contain 100 (200 for F assem-bler) operands and associated comments.
The following examples illustrate: (1) the normal statement form, (2) the
I
NAMEl IOPl IOPERANDl,OPERAND2,OPERANIX:I I
I
D3 THE NORMAL FORMI
Il-________
L ______ • ________________________i_:
I I I
I _________
l ______
l ________________________ .~MODEL STATEMENTS
Model statements are the macro definition statements from which the desired sequences of machine instructions and certain assem-bler instructions are generated. Zero or more model statements may follow the
proto-type statement. A model statement consists of one to four entries. They are, from machine, assembler, or macro instruction mnemonic operation code, except COPY, END, mne-monic operation codes. Variable symbols may not be used to generate the name and
---, \, rules for paired apostrophes, ampersnads, and blanks, as macro-instruction operands.
(See "Macro-Instruction Operands" in section 8.) Sequence symbols must appear in the operand entry of AGO and AIF in-structions.
The comments entry may contain any
combination of characters. Substitution by the use of variable symbols is not allowed.
substituted statements may not have blanks in any fields except between paired apos-trophes. They may not have leading blanks in the name or operand fields.
SYMBOLIC PARAMETERS
A symbolic parameter is a type of variable symbol consisting of an ampersand followed by one to seven letters and/or numbers, the first of which must be a letter. Symbolic parameters appear in prototype and model statements. They are assigned values by the programmer when he writes a macro-instruction. The programmer may vary statements that are generated for each occurrence of a macro-instruction by vary-ing the values assigned to symbolic param-eters.
The programmer should not use &SYS as the first four characters of a symbolic parameter.
The following are valid symbolic param-eters:
(first character after ampersand is not a letter)
(more than seven characters after the ampersand) (contains a special
charac-ter other than initial ampersand)
&IN AREA (contains a special charac-ter, i.e., blank, other than initial ampersand) The following is an example of a macro-definition. Note that the symbolic
parameters in the model statements appear in the prototype statement.
r---T---T---,
I Name I Operation I Operand I
~---+---+---~
Header I I MACRO I I
Prototypel&NAME IMOVE I &TO,&FROM I
Model I&NAME 1ST I 2, SAVE I
Model I I L 12, &FROM
I
Model l i S T 12,&TO I
Model I IL I 2, SAVE I
Trailer L _______ I ~ I MEND __________ _ i I _ _ _ _ _ _ _ _ _ _ _ _ J I
Symbolic parameters in model statements are replaced by the characters of the macro-instruction operand that correspond to the symbolic parameters.
In the following example the characters HERE, FIELDA, and FIELDB of the MOVE macro-instruction correspond to the symbolic parameters &NAME, &TO, and &FROM,
respectively, of the MOVE prototype state-ment.
r---T---T---,
I Name IOperation I Operand I
~---+---+---~
I HERE I MOVE IFIELDA,FIELDB I
L-_____ ~ ___________ ~ ______________________ J
Any occurrence of the symbolic parame-ters & NAME, &TO, and &FROM in a model statement will be replaced by the charac-ters HERE, FIELDA, and FIELDB, respective-ly. If the preceding macro-instruction was used in a source program, the following assembler language statements would be generated:
L-_____ ~ ___________ ~ ______________________ J
The example below illustrates another use of the MOVE macro-instruction using different operands than those that appear in the preceding example.
r---T---.---,
not replaced by the corresponding charac-ters of the macro-instruction.Concatenating Symbolic Parameters with Other Characters or Other Symbolic Parameters statement is immediately preceded or fol-lowed by other characters or another sym-bolic parameter, the characters that· cor-respond to the symbolic parameter are com-bined, in the order given, in the generated statement, with the other characters or the characters that correspond to the other symbolic parameter. This process is called concatenation.
The macro-definition, macro-instruction, and generated statements in the following example illustrate these rules.
r---.---~---,
IName IOperationlOperand I
~---+---+---~
Header I I MACRO I I
Prototype I & NAME I MOVE I&TY,&P,&TO,&FROMI Model I&NAMEIST&TY I 2, SAVEAR EA I
GeneratedlHERE ISTD 12,SAVEAREA I
Generated I ILD 12,FIELDB I the macro-instruction corresponds to sym-bolic parameter &TY. Since &TY is preceded by other characters (i.e., ST and L) in the model statements, the character that cor-responds to &TY (i.e., D) is concatenated the corresponding generated statements.
The characters FIELD, A, and B correspond to the symbolic parameters &P, &TO, and
&FROM, respectively. Since &P is followed by &FROM in the second model statement, the symbolic parameter he must immediately follow the symbolic parameter with a sym-bolic parameter. A period that immediately follOWS a symbolic parameter does not
appear in the generated statement.
The following definition, macro-instruction, and generated statements illustrate these rules.
Header
I & NAME I MOVE I&P,&S,&Rl,&R2 I I&NAMEIST I&Rl,&S.(&R2) I I IL I&Rl,&P.B I
o
The symbolic parameter &P is used in the second and third model statements to vary part of the operand field of each of the corresponding generated statements. The characters FIELD of the macro instruction correspond to &P. Since &P is to be conca-tenated with a letter (i.e., B and A) in each of the statements, a period immediate-ly follows &P in each of the model state-ments. The period does not appear in the generated statements.
Similarly, symbolic parameter &S is used in the first and fourth model statements to vary the operand fields of the correspond-ing generated statements. &S is followed by a period in each of the model state-ments, because i t is to be concatenated with a left parenthesis. The period does not appear in the generated statements.
Comments Statements
A model statement may be a comments state-ment. A comments statement consists of an asterisk in the begin column, followed by comments. The comments statement is used by the assembler to generate an assembler language comments statement, just as other model statements are used by the assembler to generate assembler language statements.
The programmer may also write comments statements in a macro definition which are not to be generated. These statements must have a period in the begin column, immedi-ately followed by an asterisk and the com-ments.
The first statement in the following example will be used by the assembler to generate a comments statement; the second statement will not.
r---,
I Name loperation 1 operand 1
~---~----~
I
*
THIS STATEMENT WILL BE GENERATED I 1.* THIS ONE WILL NOT BE GENERATED IL _________________________________________ J
The use of variable symbols for substi-tution in comments statements is not allowed. The
*
or.*
of a comment state-ment, therefore, cannot be created by sub-stitution for a variable symbol.COpy STATEMENTS
A COpy statement is not a model statement.
COpy statements may be used to copy model statements and MEXIT, MNOTE, and condi-tional assembly instructions into a macro definition from a system library, just as they may be used outside macro definitions to copy source statements into an assembler language program. Under the DOS D Assembler, 10K Variant, the coding to be included is obtained from the system source statement library. Under the DOS D Assembler, 14K Variant, and the DOS F Assembler, the coding to be included is obtained from the private source statement library, if one is assigned, or from the system source library, in that order of precedence. Under the TOS D Assem-bler, 10K and 14K Variants, the coding to be included is obtained from the standard private library.
The form of this statement is:
r---T---T---,
I Name I Operation I Operand I
~---+---+---~
INot used, I COpy I A symbol I
Imust not I 1 I
Ibe present I L-__________ ~ __________ i _ I ________________ J I
The symbol in the operand entry iden-tifies the section of coding to be copied.
The symbol must not be the same as the operation mnemonic of a macro definition in a source statement library. Any statement that may be used in a macro definition may be part of the copied coding, except MACRO, MEND, COPY, and prototype statements.
statements COPYed into the program must obey the restrictions on ordering of state-ments. For example, COpy must be between global and local declarations in the macro definition or in the main program if the COPYed text contains global and local·
declarations.