ML/I User’s Manual — Sixth Edition ¶

2.4.1 Examples of macros ¶

It may be instructive at this stage to consider a few more examples of macros. These examples, which are listed below, are all of simple macros with fixed delimiters. Macros with more elaborate patterns of delimiters will be considered later. Note that ML/I could be used to add these macros to any desired programming language, whether high or low level.

Example 1

A macro to generate a loop, which has form:

DO {arg A} TIMES {arg B} REPEAT

Here the delimiters are DO, TIMES and REPEAT. DO is the name delimiter, and TIMES and REPEAT are secondary delimiters. REPEAT is the closing delimiter. ML/I does not require that macro calls be written on a single line, and calls of this macro would tend, in practice, to span several lines of text.

Example 2

A macro of form:

MOVE FROM {arg A} TO {arg B};

The name of this macro consists of the two atoms MOVE FROM.

Example 3

A macro to interchange two variables, which has form:

INTERCHANGE ( {arg A}, {arg B} ) {NL}

In this example, both the name and the closing delimiter consist of more than one atom: the name is INTERCHANGE followed by a left parenthesis, and the closing delimiter is a right parenthesis followed by a newline. Note that ML/I does not, like some software, truncate long names such as INTERCHANGE.

Example 4

Assume that within a program two different names, COUNT and CONT, have inadvertently been used for the same variable. This error could be corrected using ML/I, with CONT defined as a macro with COUNT as its replacement text. Here the name delimiter, CONT, is also the closing delimiter.

The reader should, at this stage, appreciate why ML/I considers text as a sequence of atoms rather than a sequence of individual characters. If the latter were the case, ML/I would be liable to take names such as DOG and RANDOM as calls of the above macro DO, since each name contains the letters DO. As the situation stands, however, the letters DO would only be taken as a macro call if they were surrounded by punctuation characters.

2.4.2 Delimiter structures ¶

The macros considered so far have had fixed delimiters. However, it is possible to have macros with any number of alternative patterns of delimiters. As a very simple example of this, consider the ESUB macro. In X123 Assembly Language, statements are terminated with either a tab or a newline, and so it would be desirable to have both of these as alternatives for the closing delimiter of ESUB.

In order to specify the pattern of possible delimiters of a macro, the user specifies a delimiter structure. Each macro has its own delimiter structure, and other constituents of the environment also have delimiter structures. A delimiter structure is a set of delimiter specifications, each of which is a sequence of one or more atoms. These sequences of atoms need not be distinct. One or more of these delimiter specifications are designated as names of the structure. The remainder are secondary delimiters. With each delimiter specification is associated a specification of its successor(s). This may be:

• null,
• another delimiter specification within the structure,
• a set of alternative delimiter specifications within the structure.

Successors specify what to search for next when scanning. A delimiter with a null successor is a closing delimiter. As an illustration of the use of a delimiter structure, consider the scanning of a macro call. During this scanning, each time a delimiter is found, the delimiter structure of the macro being called is referenced to find the successor(s) of the current delimiter, and subsequent text is then scanned to try to find this successor. This process continues until a closing delimiter is found.

As an example of a delimiter structure, the delimiter structure of the ESUB macro would contain three delimiter specifications with the following information about them:

The rules for setting up delimiter structures (see Specification of delimiter structures) ensure that they have certain properties. Among these properties are the following:

• If there is more than one name, each name is represented by a different sequence of atoms.
• If a delimiter structure has alternative successors, each is represented by a different sequence of atoms.
• The structure is connected. This means that it must be possible to reach each secondary delimiter by a sequence of successors from some name.

2.4.3 Optional and repeated delimiters ¶

It is possible, by designing a suitable delimiter structure, to have a macro with a variable number of arguments; in particular, a macro with optional arguments and/or with an indefinitely long list of arguments. For instance, suppose it is desired to implement a macro with alternative forms:

IF {argument} THEN {argument}
END

and

IF {argument} THEN {argument}
ELSE {argument}
END

This is done by specifying that either ELSE or END is the successor of THEN. END is a closing delimiter, and ELSE has successor END. As a second example, consider a macro of form:

SUM {argument} [ (+) {argument} *?];
                 (-)

This macro has an indefinite number of arguments, separated by plus or minus signs. Its delimiter structure has four members as follows:

2.4.4 Macro definitions ¶

Now that the basic concepts behind macros have been introduced, it is possible to explain more exactly what makes up a macro definition. Macro definitions are the most important constituents of the environment. A macro definition consists of:

1. A delimiter structure. The name delimiter(s) of this structure are the macro names.
2. A piece of replacement text.
3. An integer, exceeding two, called the capacity. The purpose of this is explained in Macro-time variables.
4. An on/off option. If this option is on, the macro is called a normal-scan macro; otherwise it is called a straight-scan macro. The effect of this option is explained in Name environment used for examples.

The reader need not for the moment be concerned with (c) and (d), since nearly all macros will be normal-scan and will have a capacity of three.

2.4.5 The difference between macros and subroutines ¶

There is often confusion between the purpose of macros and the purpose of subroutines (or procedures). Macros, however, always generate in-line code, and so this code is inserted as many times as the macro is called. Subroutines use out-of-line code, and there is only one copy of this code for a particular program. Thus, macros are used only when the code to be inserted is short or highly parameterised. It would not be convenient, for instance, to use subroutines to perform the functions of any of the macros used as examples in previous Sections.

2.4.6 Impossible replacements ¶

It is worth noting some of the types of replacement that it is not possible to perform by means of macros. Below are two examples of illegal syntax of macro calls, together with possible correct forms.

1. Wrong: {arg A} = {arg B};
   since each macro call must start with a macro name.

   Right: SET {arg A} = {arg B};
   Here SET is used as the macro name.

2. Wrong: $ {character}
   It is not possible to define an argument as the character (or atom) immediately following a given name. Every argument must be followed by some predefined delimiter.

   Right: $ {argument};
   Here a semicolon is used as the closing delimiter.

2.6.1 Macro-time variables ¶

Macro variables are integer or character variables available to the user at macro-time. ML/I contains facilities for performing arithmetic on these variables (where appropriate), testing their values, and inserting their values into the text. They are useful as switches and for counting (e.g. in processing macros with a variable number of arguments), as well as for storing information which may be needed later on in a process.

There are four kinds of macro variable, namely:

1. permanent variables, referred to as P1, P2, …
2. system variables, referred to as S1, S2, …
3. temporary variables, referred to as T1, T2, …
4. character variables, referred to as C1, C2, …

Permanent, temporary and system variables are used to store integers. Character variables are used to store character strings.

Permanent, system and character variables have global scope; this means they can be referred to anywhere. An implementation-defined number of each is allocated at the start of each process, and these remain in existence throughout. The user may allocate extra permanent variables and character variables (but not system variables) if desired, see MCPVAR, and MCCVAR. The difference between permanent/character and system variables is that the former have no fixed meanings and are free for users to use as they wish, but the latter have fixed implementation-defined meanings associated with controlling the operation of ML/I. For example, in a given implementation, system variable S20 might control the listing of the source text; if it was zero no listing would be produced and if it was one there would be a listing. Sections 5 and 7 of each Appendix describe the meanings of system variables (if any) and state the number of permanent and system variables that are initially allocated. System variables 1 to 9 are normally the same in most implementations, and are described in Use of system variables.

Temporary variables, on the other hand, have a more local scope. During the evaluation of the source text there are no temporary variables in existence. However, each time a macro call is made a number of temporary variables is allocated, and these remain in existence while the replacement text of the macro is being evaluated. The number of temporary variables allocated at the call of a macro is given by the capacity of the macro (see Macro definitions). The capacity is usually three. If temporary variable N is referenced during the evaluation of the replacement text of a macro call, this is taken to mean the Nth temporary variable associated with the call. Since, as will be seen later, it is possible to have macro calls within macro calls, it is possible to have several allocations of temporary variables in existence at the same time.

2.6.2 Initialisation of macro variables ¶

The initial number and values of permanent variables are defined in Section 5 of each Appendix.

The initial number and values of system variables are defined in Section 7 of each Appendix.

The initial number of character variables is always zero; it is necessary to allocate a suitable quantity before use (see MCCVAR).

The first three temporary variables of each allocation are initialised as follows (all other temporary variables have undefined initial values):

T1

the number of arguments of the current macro call.

T2

the number of macro calls so far performed by ML/I during the current process. The importance of this number is that it is unique to the current call.

T3

the current depth of nesting of macro calls (i.e. the number of calls, including the present one, currently being processed; calls of operation macros (see Operation macros) are not counted here, though they do count toward the setting of T2).

It is to be emphasised that these are initial values, and the user is free to change them if desired (in this way, temporary variables are unlike system variables. If the values of system variables—even those without assigned meanings—were changed arbitrarily it might have unwanted effects).

2.6.3 Subscripts and macro expressions ¶

In the previous Sections, macro variables were specified by a letter followed by a number (e.g. P2), but there are other possibilities. The general form of a macro variable is:

(P)
(S) {subscript}
(T)
(C)

where a subscript is an unsigned positive integer, or an integer macro variable (but not a character variable). The value of the subscript specifies the macro variable to be referenced. Thus, if T3 has value 4, then PT3 would specify P4. As a more complicated example, if T1 had value 2 and P2 had value 6, then TPT1 would specify the sixth temporary variable. If character variable 3 contained the string 16, it would be wrong to write PC3 in order to reference permanent variable 16; however, it would be possible to obtain the same effect by using an insert, in which case the user would write P%C3. instead.

Macro variables can be combined into macro expressions, which are used when it is desired to perform arithmetic calculations during macro generation. Examples of macro expressions are:

1, -6, 3-S1, -TT1-145/P2+P3+6

Multiplication is represented by an asterisk, and division by a slash. Bitwise logical operations are also supported; ampersand (&) is used for logical “and”, and vertical bar (|) for logical “or”. The general form of a macro expression is:

{primary} [ (+) {primary} *?]
            (-)
            (*)
            (/)
            (&)
            (|)

where a primary has the form:

[ (+) *?] {operand}

and an operand is an unsigned integer or an integer macro variable. Redundant spaces can occur anywhere in macro expressions except within operands.

The result of a macro expression is the integer derived from calculating the expression by the ordinary rules of arithmetic. Unary operators are performed first, followed by the binary operators from left to right, with the proviso that multiplication and division take precedence over addition and subtraction. Division is truncated to the greatest integer that does not exceed the exact result. Division by zero is detected as an error. Examples of the results of macro expressions are:

2.6.4 Character variables ¶

Strictly speaking, character variables should be called character string variables, or just string variables, but since their names begin with the flag character C, rather than S (which is already taken for system variables), we shall persist with the original term.

Character variables can store character strings of any length, up to a maximum known as the range. For a given ML/I process, all character variables have the same range, chosen by the user when initially allocating the first character variable. When the value of a character variable is inserted, the length of the inserted text will be the length of the string last stored in the variable, rather than the range (i.e. no trailing spaces are included unless originally stored as such).

Character variables are particularly useful as an efficient solution to the problem of ‘remembering’ pieces of text which are to be recalled at some later point in the ML/I process. An alternative solution would be to use the MCFOR macro described in Macro-time loop.

2.6.5 Integer overflow ¶

Each implementation has a maximum absolute value which must not be exceeded by any integer derived during the calculation of a macro expression or subscript. The effect of exceeding this value is implementation-defined. See Section 5 of the relevant Appendix for details.

2.6.6 Macro labels ¶

Since there is a facility for a macro-time ‘goto’, there is also a facility for placing macro-time labels. These are called macro labels. Each macro label is designated by a unique positive integer.

2.6.7 Macro elements ¶

Macro variables, macro labels, arguments and delimiters are collectively called macro elements. It is convenient to regard macro elements as part of the environment. The full details of how macro elements are added to the environment are explained later; see Dynamic aspects of the environment. In essence, the rule is that every time a macro is called its arguments and delimiters, plus a set of temporary variables, are automatically added to the environment, and this supplemented environment is used to evaluate the replacement text of the call. Similarly, when a macro label is encountered, its position is ‘remembered’ by adding it to the environment.

2.6.8 Insert definitions ¶

It is now possible to define the constituent of the environment, called an insert definition, which is used for such purposes as to tell ML/I to insert a particular argument of a macro at some point in its replacement text. An insert definition consists of:

1. A delimiter structure. Since all inserts have fixed delimiters and exactly one argument, this delimiter structure will be a simple one. It will consist of a name with a single successor, this successor being a closing delimiter.
2. An on/off option. If this option is on, an insert is called protected; otherwise it is called unprotected. The use of this option, which need not be of much concern to the average reader, is described later; see Protected and unprotected inserts.

At each point where the user wishes something to be inserted, they should write the following construction, called an insert:

{insert name} {argument} {delimiter}

In the rest of this manual, for the purpose of examples, it will be assumed that the atom % is an insert name, with the atom . as its closing delimiter. With this assumption, the following are examples of inserts (the exact meaning of these will become apparent later):

%A6.  %P1.  %LT2.  %WA P9-16*T3.

On encountering an insert, ML/I evaluates the argument of the insert (in case it contains macro calls, etc.) and the resulting value text acts as a specification of what to insert. The value text must consist of a flag followed by a macro expression. In the first above example, the flag is A and the macro expression is 6. The flag may be null, or it may be any of the following: A, B, D, L, WA, WB or WD. Any number of redundant spaces is allowed before, after or within a flag.

The meaning of the various flags is explained below. In each explanation, ‘N’ is used to represent the value of the macro expression following the flag. More examples are given in the next Section. An attempt to insert something which does not exist (e.g. the third argument of a macro with only two arguments) results in an error. The meanings of the flags are:

1. A. This flag is used within the replacement text of a macro to evaluate and insert the Nth argument of a call of the macro. Any spaces at the beginning or end of the argument are deleted before it is evaluated. In the case of this flag, and in cases b) and c) below, the piece of text that is evaluated and inserted is called the inserted text.
2. B. As case a), except that spaces are not deleted.
3. D. As case b), except that the Nth delimiter, rather than the Nth argument, is inserted. The name of a macro is considered as delimiter zero, and the Nth delimiter is thus the delimiter following the Nth argument.
4. WA, WB, WD. As cases a), b) and c) respectively, except that the inserted text is not evaluated but is inserted literally, exactly as written (W stands for ‘written’). The difference between this and the previous cases arises if the inserted text itself involves macro calls, inserts, etc. In the previous cases these are evaluated; in this case they are not.
5. Null. The numerical value of N, represented as a character string, is inserted. This character string contains no redundant leading zeros. It is preceded by a minus sign if N is negative; otherwise no sign is present.
6. L. This is used to place a macro label, and is rather different from the above cases in that nothing is inserted (i.e. the value of the insert is null). The label N is, if acceptable, added to the current environment and may be the subject of a macro-time ‘goto’. A macro label is acceptable if it is inserted within a piece of replacement text or inserted text and has not already been defined within that text. It is legal to insert a label in the source text, but since, as will be seen later, it is not possible to have a backward ‘goto’ within the source text, such labels are not added to the environment (i.e. they are ‘forgotten’). Macro labels are local to the piece of text in which they occur, and there is no harm in using the same label numbers within different pieces of text. Label numbers can be chosen arbitrarily, except that they must be positive.

2.6.9 Examples of inserts ¶

The following examples illustrate the use of inserts:

• The replacement text of the ESUB macro (see Macros and delimiter structures) might be written:

  CMA
  ADD     %A1.
  CMA     {NL}
  

  or even:

  CMA
  ADD     %A1.
  CMA     %D1.
  

  The latter form would have the advantage of inserting newline or tab, according to which one was written in the call.

• In the case of the DO macro (see Examples of macros), the replacement text would involve an execution-time label. It is imperative that a different execution-time label be generated for each call of DO. This could be achieved by using the initial value of T2. The label could, for example, be written:

  ZZ%T2.
  

  In this case, if two successive calls of DO occurred at the start of the source text, then ZZ1 would be generated at the first call and ZZ2 at the second.

• If SWITCH is a macro name with replacement text P1, then it is possible to write:

  %SWITCH.
  

  to insert the first permanent variable. The reason is that the argument of an insert is evaluated before being processed, and the call of the SWITCH macro would be performed during this evaluation.

• The occurrence of %A1. in the replacement text of the macro call:

  MOVE FROM JACK TO JOHN;
  

  would cause JACK to be inserted, whereas the occurrence of %B1. would cause JACK enclosed in spaces to be inserted.

• If it is desired to insert the name of a macro into its replacement text, this can be done by writing %WD0. (the reason for this facility is that macros can have several alternative names). In general it would be wrong to use %D0. instead, since this form causes any macro calls within the delimiter to be performed. But delimiter zero is the macro name itself, and hence an endless recursive loop is likely. In fact, when inserting delimiters it is usually better to use a W.
• This example rather jumps the gun in that it uses the macro-time statements MCSET and MCGO which have not yet been defined. However, if the reader cares to try to understand this example at this stage, it may give a useful insight into the purpose of the preceding material. The example shows how the replacement text of the SUM macro could be written—the comments at the side are for the reader’s benefit and do not form part of the replacement text. The blank lines are not part of the replacement text, either.

  LAC %A1.	Generate code to load accumulator
  	with first argument.
  MCSET T2 = 1	Use T2 as loop counter.
  %L4.MCGO L1 IF %DT2. = +	Test if current delimiter is plus …
  MCGO L2 IF %DT2. = -	… or minus.
  MCGO L0	If neither then exit (L0 has a
  	special meaning, namely ‘return’).
  %L2. ESUB %AT2+1.	Generate code to subtract the
  	current argument.
  MCGO L3
  %L1. ADD %AT2+1.	Generate code to add current argument.
  %L3.MCSET T2 = T2 + 1	Increase T2 and continue loop.
  MCGO L4

2.7.1 Matched skips and straight skips ¶

Assume the user has written the comment:

COMMENT THIS COMMENT MARKS THE HALF-WAY STAGE;

In this case, the skip name COMMENT appears within an argument of the skip COMMENT. However, it is clearly undesirable that ML/I should treat the second COMMENT as a nested skip and try to match it with a semicolon. To prevent this happening, COMMENT would be defined as a skip with the matched option off. This is called a straight skip.

However, there are applications of skips where it is desirable for nested skips to be recognised, and such skips have the matched option on. They are called matched skips. Literal brackets, which are described in Literal brackets, are an example of the application of a matched skip. If ML/I encounters any skip name during the scanning of a matched skip, it matches the nested skip with its delimiters before matching the containing skip with its delimiters. The scanning process is described in more detail in The method of searching for delimiters. In a nest of skips, the value is entirely controlled by the options associated with the outermost skip.

2.7.2 Literal brackets ¶

It is usual to have in each environment a skip definition consisting of a name and a closing delimiter with the options set in such a way that at every occurrence of the skip the argument is copied and the delimiters deleted. Such skips are called literal brackets. It will be assumed in the rest of this manual that the name < with closing delimiter > have been defined as a pair of literal brackets. If it was required to copy a piece of text literally over to the value text, ignoring all macro calls and inserts, then the text would be written:

< {text} >

The process of evaluation would consist simply of removing the literal brackets. Literal brackets always have the matched option on. The reason for this will become apparent in Use of literal brackets for surrounding operation macro arguments.

2.7.3 Example of a matched skip ¶

The following example, which is rather more complicated than any situation likely to arise in practice, illustrates the full implications of the rules for the matching of skips.

In the text:

< AAA < BBB COMMENT < ; CCC > DDD >

the initial < is matched with the last >. (The occurrence of < after COMMENT is not recognised as a skip name, since COMMENT is a straight skip). The value of this text is:

AAA < BBB COMMENT < ; CCC > DDD

This value is independent of how the delimiter and text options for COMMENT are set.

2.7.4 Warning markers ¶

Up to now, ML/I has been described as if every occurrence of a macro name not within a skip is taken as the start of a macro call. In fact, this is only true if the environment is in free mode.

If desired, the user may place the environment in warning mode by defining one or more warning markers. Any atom or series of atoms may be defined as a warning marker. In warning mode, each macro call must commence with a warning marker. Optional spaces are allowed between the warning marker and the macro name which follows it; this means that in warning mode it is not possible to have a macro name that begins with a space. Thus, if CALL were a warning marker, the ESUB macro would be called by writing:

CALL ESUB X {NL}

In warning mode, each occurrence of a warning marker must be followed by a macro name; failure to do so will result in an error message. The message can be suppressed by setting system variable S3 (see Use of S1 to S9) to one. This is useful if macro calls in the source text are only to be recognised in certain positions, e.g. following a tab or at the start of a line. In such examples the characters ‘tab’ or ‘startline’ could be defined as warning markers, and, assuming that not all occurrences need to be followed by macro calls, S3 could be set to one to suppress the message.

Note that, if a warning marker is not followed by a macro name, it is treated as if it were not a construction name at all and is thus normally copied over to the value text. This applies irrespective of whether S3 is being used to suppress the error message.

The essential difference between warning mode and free mode is that in the first case all macro calls have to be specially marked by preceding them with warning markers, whereas in the second case all macro names that are not to be taken as macro calls have to be specially marked by enclosing them in skips.

Note that warning markers only apply to macro calls, and must not be used to precede inserts or skips. These latter are always recognised, irrespective of the mode of the scan.

2.7.5 Stop markers ¶

Normally, if a delimiter of a macro call in the source text is accidentally omitted or wrongly specified, then the remainder of the source text might be scanned over in searching for the missing delimiter.

Thus, there is a construction called a stop marker. Stop markers are only recognised when searching for a delimiter of a construction in the source text. Outside of this context, stop markers are not part of the environment. If it encounters a stop marker, ML/I gives a message to signal that the current construction(s) are unmatched. The text from the construction name up to (but not including) the stop marker is ignored, and scanning is resumed at the stop marker itself. For example, if the source text read:

MCDEF IF THEN NL
AS <. . .>

and newline were then declared as a stop marker, and further source text included:

IF X = Y THIN GO TO Z

then ML/I would take the final newline as a stop marker and would give the error message:

Delimiter THEN of macro IF in line . . . not found

Stop markers obey the normal rules for name clashes, See Ambiguous use of names. Hence if, in the above example, THIN were replaced by THEN, then the final newline would be treated as a delimiter of IF rather than as a stop marker, and there would be no error message. An implication of this is that if the following definition were added to the above text:

MCSKIP DT, COMMENT N1 OPT NL N1 OR ; ALL

then

COMMENT XXX
YYY
ZZZ;

would not cause an error since all newlines would be treated as delimiters, not stop markers. In general, therefore, it is possible (though tortuous in all but the simplest cases) to define constructions that may be arbitrarily long even if stop markers have been defined.

Note that stop markers override the normal scope rules in that they are recognised within skips and within straight-scan macros. They are treated as local constructions.

Stop markers will stop forward searches for labels in the source text, as well as the scan for unmatched constructions.

5.1.1 Keywords ¶

Within a structure representation the atoms are separated out by layout characters, i.e. spaces, newlines, tabs, etc.—in the above examples spaces have been used. Apart from acting as separators, layout characters are totally ignored within structure representations. Thus a problem arises when it is desired to specify a layout character as a delimiter, or as a constituent atom of a multi-atom delimiter. This problem is overcome by using layout keywords to stand for layout characters. In particular:

SPACE

means a space

TAB

means a tab

SL

means a startline

NL

means a newline

SPACES

means a sequence of one or more spaces

In addition, each implementation may have its own extra layout keywords. See Section 6 of the relevant Appendix for details. The characters represented by these keywords are treated as layout characters and hence, within structure representations, are exactly equivalent to newlines or spaces. Note that layout keywords only apply within structure representations.

The following are examples of delimiter structures using layout keywords:

1. ESUB NL
2. SPACE
3. SL WITH * (a * character at the beginning of a line)
4. SPACE WITH SPACES (means two or more spaces)
5. LD WITH SPACES SPACES NL

A construction defined using e) above would be analysed thus:

LD                       X                         Y   {NL}
 \_____________________/   \_____________________/       |
            |                         |                  |
       delimiter 0             delimiter 1           delimiter 2

Note how all the spaces following LD are absorbed into the name; if they had not been defined to be part of the name they would have been taken as the first delimiter.

It is permissible to use SPACES before or after WITHS; in these cases it is exactly equivalent to SPACE.

In addition to these layout keywords, there are other keywords that apply within structure representations. These are: WITH, WITHS, OPT, OR, ALL and any atom commencing with the letter N followed by a digit. Keywords are reserved words and cannot be used as the atoms of delimiters. However, if it is necessary to define, say, WITH as a delimiter name, then the keyword WITH could be changed to something else (e.g. +) by using the MCALTER macro described in MCALTER.

5.1.2 The consequences of evaluation ¶

Since structure representations occur as arguments to operation macros, they are evaluated before being processed. Two consequences of this, one beneficial to the user and the other a nuisance, are as follows.

The beneficial consequence is that much-used alternatives can be generated artificially. Assume, for example, that a large number of macros have the form:

NAME ( {argument} ) {NL}

where NAME varies from macro to macro. In this case it would be useful to define a macro PARENS with replacement text:

WITH ( ) WITH NL

Then a macro DOG of the above form could be defined by writing:

DOG PARENS

The mischievous consequence arises if an attempt is made to redefine a macro. Assume that a macro EMPLOYEE is defined thus:

MCDEF EMPLOYEE AS < J. SMITH >

and then subsequently an attempt is made to redefine it by writing:

MCDEF EMPLOYEE AS < J. BLOGGS >

In this second definition, the structure representation is J. SMITH since EMPLOYEE is replaced by its value. Hence a macro J would be defined with secondary delimiters . and SMITH. The end result would probably be a puzzling error message, perhaps that a delimiter of the macro J was missing.

To avoid problems such as this, it is imperative to enclose a name in literal brackets if it is being redefined. The same applies if the name of one macro occurs as a delimiter of another. In fact, it is not a bad rule to enclose all structure representations in literal brackets except where constructions such as PARENS are being used. The correct way to redefine EMPLOYEE would be:

MCDEF <EMPLOYEE> AS < J. BLOGGS >

5.1.3 Introduction to more complicated cases * ¶

The Sections which follow describe facilities for setting up more and more elaborate delimiter structures. Readers are recommended to read on until they know enough for their own applications, and then to skip the rest. Readers who are only interested in fixed delimiters may give up now.

In order to specify the delimiter structure of a construction it is necessary to specify the name(s) of the construction and the successor(s) of each delimiter that is not a closing delimiter. In the simple cases described above, the structure representation consisted of the name of the construction, and then each succeeding delimiter followed by its successor until the closing delimiter. In more complicated cases it is necessary to have two other mechanisms for specifying successors, namely option lists and nodes. Furthermore it is convenient to imagine that a special symbol @ occurs at the start of each structure representation, and another symbol • at the end. With this convention any successor of @ is the name of a construction, and any delimiter with • as a successor is a closing delimiter. The paragraphs which follow contain informal introductions to the concepts of option lists and nodes. More exact details are given in the next Section.

Option lists are used to specify that a delimiter has several optional alternatives as successor. The essential form of an option list is:

OPT {branch 1} OR {branch 2} OR . . . OR {branch N} ALL

The ordering of the branches is immaterial. An example of the use of an option list is in the following structure representation for the ESUB macro:

ESUB OPT TAB OR NL ALL

If, in addition, it was decided to allow SUBTRACT as an alternative name to ESUB, then its structure representation would be:

OPT ESUB OR SUBTRACT ALL OPT TAB OR NL ALL

In the ordinary way, the successor of the delimiter at the end of a branch is taken as the delimiter following the ALL concluding the option list. In other words, the branches may be thought of as coalescing at the delimiter following ALL (thus in the example above both ESUB and SUBTRACT have either tab or newline as alternative successors, and both tab and newline have the imaginary symbol • as successor and are therefore closing delimiters). However, as will be seen, it is possible to override this coalescing effect by the use of nodes.

Nodes are used for defining the successor of a delimiter to be a delimiter or option list elsewhere in the structure representation. The use of nodes in structure representations is analogous to the (much despised) use of labels in programming languages. As the reader will know, the statements in a programming language are written in sequence and the ‘successor’ of each statement is normally taken as the statement which follows. However, the user can specify a different successor by the use of labels. A label is ‘placed’ on one program statement and is then ‘gone to’ after any program statement which requires the labelled statement as successor. In exactly the same way, nodes are used to specify the successors of delimiters.

A node is represented as a node flag followed by a positive integer. The normal node flag is the letter N, but this can be changed if desired using the MCALTER macro of MCALTER. It will be assumed in this manual that the node flag is N. A node is placed by writing its name before any delimiter name or option list. A node can be ‘gone to’ only from the end of a branch of an option list or from the end of a structure representation. A ‘goto’ is indicated simply by placing the name of the appropriate node at the desired point (although the name of a node is used both to place it and to go to it, there is no ambiguity, owing to the different context in which each occurs). As a simple example of the use of nodes, consider the structure representation of a SUM macro which allows any number of arguments separated by plus or minus signs and terminated by a semicolon. A typical call of SUM would be:

SUM A + B - C + D ;

The structure representation of SUM is:

SUM N1 OPT + N1 OR - N1 OR ; ALL

This is interpreted thus. SUM is followed by either a plus sign, a minus sign or a semicolon. Node N1 is placed before the option list. The successor of both plus and minus is defined by going to N1, and N1 is associated with the alternatives plus, minus and semicolon. The successor of semicolon, on the other hand, is taken as the delimiter which follows ALL, which is •. Hence the semicolon is a closing delimiter.

There are no particular restrictions on the use of nodes. Any number of nodes may be placed within a structure representation provided, of course, that they have different numbers. Any positive integers may be chosen to designate nodes; no particular sequence is required. Node numbers are local to the structure representation in which they occur, and hence there is no relation between the nodes of one structure representation and those of another. Thus the same node numbers may be used in each case. There are no restrictions on the scope of a ‘goto’; thus it may dive into an option list or alternatively come out of one.

The node N0 (N zero) has a special usage, namely to denote an exclusive delimiter. Node N0 may be gone to, but it cannot be placed. If the successor of a delimiter is specified by N0, then this delimiter is taken as an exclusive delimiter. Apart from N0, it is illegal to go to a node without placing it.

5.1.4 Full syntax of structure representations * ¶

Before describing the general form of a structure representation, it is necessary to describe a number of syntactic sub-components. These are:

1. A nodeplace represents the placing of a node, and is specified by the node flag followed by an unsigned positive integer.
2. A nodego represents the action of going to a node, and is also specified by the node flag followed by an unsigned integer (in this case, and case a) above, any redundant leading zeros are ignored).
3. A delspec represents the specification of a delimiter or an option list, and is of form:

   [{nodeplace} ?] ({delimiter name}                                    )
                   ( OPT {branch} [ OR [{nodeplace} ?] {branch} *?] ALL )
   

   where a {branch} is of form:

   {delimiter name} [ {delspec} *?] [ {nodego} ?]
   

(the reader may like to look ahead to the examples in Examples of complex structure representations, at this point). Note that each branch must begin with a delimiter name, called the branch name. The branch names are the possible alternative successors of the delimiter preceding the option list, and must all be different. Thus no sequence of atoms must match more than one branch name, and the following option list is therefore incorrect:

OPT X WITH SPACE WITH Y . . . OR X WITHS Y . . . ALL

since X Y could be the name of either branch.

As was seen from the preceding example of the SUM macro, nodeplaces immediately preceding an option list associate the node with all the options of the list. The syntax forbids a nodeplace immediately after OPT, and a nodeplace immediately following OR has a special meaning in that it associates the node not only with the delimiter name that follows it but also with the names of all subsequent branches of the option list. As an example, assume that the SUM macro was extended to allow the user the option of assigning the answer by writing, for example:

SUM X = Y+Z;

to calculate Y+Z and assign the answer to X, or:

SUM Y+Z

to calculate Y+Z and leave the answer in an accumulator.

Here SUM has an optional first argument delimited by an equals sign. Its structure representation could be written:

SUM OPT = N1 OR N1 + N1 OR - N1 OR ; ALL

In this case N1, which is placed after the first OR, is associated with the alternatives plus, minus and semicolon.

It is also important to ensure that the structure does not become unconnected; for example, the following structure representation is not valid:

N1 OPT , N1 OR : N1 All

because the structure is a closed loop.

Now that the sub-components have been described it is possible to give the general form of a structure representation. This is:

[ {delspec} *]  [ {nodego} ?]

5.1.5 Examples of complex structure representations * ¶

This section contains the general forms of some possible constructions, together with the structure representation of each.

Example 1

General form

Either:

MEASURE {arg A} METRES {arg B} . {arg C} ;

or

MEASURE {arg A} YARDS {arg B} FEET {arg C} INCHES {arg D} ;

Structure representation

MEASURE OPT METRES . OR YARDS FEET INCHES ALL ;

In the second form, if it is desired to allow the INCHES field optionally to be omitted, then the structure representation could be written:

MEASURE OPT METRES . ; OR YARDS
     OPT FEET N1 OR N1 INCHES ; OR ; ALL ALL

Here, N1 is associated with the possibilities INCHES and semicolon. In this form the semicolon is mentioned three times. The structure representation could also be written in the following form, where the semicolon only occurs once:

MEASURE OPT METRES . N2 OR YARDS
        OPT FEET N1 OR N1 INCHES N2 OR N2 ; ALL ALL

(The diagram in the next Section may be an aid to understanding this.)

Example 2

General form

[ / {argument} *?] END

Structure representation

N1 OPT / N1 OR END ALL

This macro has two possible names: / and END.

Example 3

General form

(LOAD Q)
(LOAD Q)  {arg A}, {arg B} {NL}
(STORE )

where the newline is an exclusive delimiter.

Structure representation

OPT LOAD OR LOAD WITHS Q OR STORE ALL , NL N0

5.1.6 Possible errors in structure representations ¶

Great care must be taken in writing structure representations, as errors can have very unfortunate results. In complex cases it may be useful to use a diagram. For example, the following represents the MEASURE macro of the previous Section in its final improved form:

      MEASURE          METRES             .
@ ---------------+---------------+--------------->-- N2
                 |
                 |
                 |     YARDS            FEET
                 +---------------+--------------->-- N1
                                 |
                                 |
                                 |     INCHES
                 N1 -------------+--------------->-- N2
                                 |
                                 |
                                 |        ;
                 N2 -------------+--------------->-- •

Special points to be watched in writing structure representations are the use of keywords and the possible differences between the structure representation as written and its evaluated form. Remember that keywords cannot be used as delimiter names.

If ML/I does reject a structure representation as illegal (giving the message of Illegal syntax of argument value), then the following are some of the possible causes:

• Illegal syntax; for example: unmatched OPT, node after OPT, two nodes in succession, branch without a name, placing of node zero, node names such as N1A.
• Keyword used as a delimiter.
• Undefined or multiply-defined node.
• Two branches with the same name.
• Misuse of WITH or WITHS; e.g. GO WITH TO, X WITHS N1.
• Structure with no closing delimiter.
• Unconnected structure. For example, the delimiter D is not connected to the main structure in the following case:

  NOGOOD N1 OPT A N1 OR B N1 ALL D
  

5.2.1 MCWARN ¶

Purpose

Definition of a local warning marker.

General form

MCWARN {arg A} {NL}

Examples

1. MCWARN $
2. MCWARN CALL WITHS THIS WITHS MACRO

Restrictions

{arg A} must be a structure representation consisting simply of a single delimiter name.

Notes

If a warning marker is not followed by a macro name, an error message is generated. This message can be suppressed by setting S3 to a value of one.

System action

{arg A} is added to the current environment as a local warning marker, and the current environment is placed in warning mode.

5.2.2 MCINS ¶

Purpose

Definition of a local insert.

General form

MCINS [ {arg A}, ?] {arg B} {NL}

Examples

1. MCINS * .
   defines a protected insert with name * and closing delimiter ..
2. MCINS U, INSERT HERE
   defines an unprotected insert called INSERT, with closing delimiter HERE.

Restrictions

{arg A}, if it exists, must consist of the letter P or the letter U. Redundant spaces are allowed. {arg B} must be a structure representation of form:

{delimiter name} {delimiter name}

System action

A new local insert definition is added to the current environment. The delimiter structure of the new insert is represented by {arg B}, and the insert is defined as protected unless {arg A} exists and consists of the letter U, in which case it is defined as unprotected.

Notes

1. Unprotected inserts are only needed for sophisticated applications of ML/I, and users with simple applications can safely omit {arg A}.

5.2.3 MCSKIP ¶

Purpose

Definition of a local skip.

General form

MCSKIP [ {arg A}, ?] {arg B} {NL}

Examples

1. MCSKIP MT, ( )
   defines ( and ) as literal brackets.
2. MCSKIP N WITH . WITH B WITH . ;
   deletes comments that start with N.B. and end with a semicolon.
3. MCSKIP DT, ' '
4. MCSKIP NONL NL
5. MCSKIP T, NOPUNCT N1 OPT , N1 OR . N1 OR END ALL
   causes all commas and periods between NOPUNCT and END to be deleted.
6. MCSKIP STATIC
   deletes all occurrences of STATIC. Note that the delimiter structure of a skip can specify any number of delimiters, although usually there will be one, as in this example, or two.

Restrictions

{arg A}, if it exists, must have the form:

[ (M) *?]
  (D)
  (T)

Redundant spaces are allowed. {arg B} must be a structure representation.

System action

A new local skip definition is added to the current environment. The delimiter structure of the new skip is represented by {arg B}, and the matched option, the text option and the delimiter option are set if {arg A} contains the letter M, T or D, respectively. If {arg A} is omitted, none of the options are set.

Notes

1. The letters in {arg A} can be in any order.
2. If {arg A} is omitted and {arg B} contains a comma, then this comma should be enclosed in literal brackets to prevent it being taken as a delimiter of MCSKIP.

5.2.4 MCDEF ¶

Purpose

Definition of a local macro.

General form

MCDEF [ {arg A} VARS ?] {arg B} (AS  ) {arg C} {NL}
                                (SSAS)

Examples

1. MCDEF ARRSIZE AS 6
2. MCDEF ESUB NL
AS < CMA
     ADD  %A1.
     CMA
>
   is a definition of the ESUB macro used in examples.
3. MCDEF 6 VARS CALCULATE AS . . .
   defines a macro named CALCULATE which has six temporary variables.
4. MCDEF (OPT + OR - OR * ALL) AS <%D1. %A1. %A2.>
   This macro converts fully parenthesised algebraic notation to Polish Prefix notation. Thus, for example, it would convert

   ((PI * 26)-LENGTH)
   

   to

   - * PI 26 LENGTH
   

5. MCDEF PARENS AS WITH ( ) WITH NL
   defines the PARENS macro used in The consequences of evaluation.
6. MCDEF NOTE ; SSAS < [%WA1.] >
   is the definition of the straight-scan macro NOTE used as an example in Name environment used for examples. SSAS stands for ‘straight-scan AS’.
7. MCDEF CALL NL N0 AS . . .
   defines a CALL macro with newline as an exclusive delimiter.

Restrictions

{arg A}, if it exists, must be a macro expression and {arg B} must be a structure representation.

Order of evaluation

{arg A}, {arg C}, {arg B}.

System action

A new local macro definition is added to the current environment. The delimiter structure of this new macro is represented by {arg B}, the replacement text is specified by {arg C} and the capacity (i.e. the number of temporary variables) is the greater of the result of {arg A} and three. The capacity is three if {arg A} is omitted. The new macro is set up as a normal-scan macro if MCDEF is called with delimiter AS, and as a straight-scan macro if the delimiter SSAS is used.

Notes

1. The replacement text is normally enclosed in literal brackets to delay evaluation until macro call time, and to ensure that any newlines within the replacement text are not taken as the closing delimiter of MCDEF.
2. If it is desired that the replacement text be treated as a literal when the macro is called as well as when it is defined, then it is necessary to enclose the replacement text in double literal brackets (see example in Interchanging two names).

5.2.5 MCNOWARN, MCNOINS, MCNOSKIP and MCNODEF ¶

Purpose

Deletion of local constituents of the current environment.

General form

1. MCNOWARN
2. MCNOINS
3. MCNOSKIP
4. MCNODEF

System actions

These macros respectively delete all local warning markers, all local insert definitions, all local skip definitions and all local macro definitions from the current environment. In addition, MCNOWARN causes the current environment to be placed in free mode unless there are any global warning markers.

Notes

1. Note that these macros do not have newline as a closing delimiter.
2. In current implementations, no storage is released if a constituent of the environment is deleted by one of these macros.
3. See the example in Deleting a macro, for a method of deleting individual constructions from the environment.
4. If MCNOWARN is to be meaningful, it must be preceded by a warning marker.
5. MCNODEF does not cause the operation macros to be deleted from the environment since they are global.
6. There is no MCNOSTOP.

5.2.6 MCWARNG, MCINSG, MCSKIPG and MCDEFG ¶

Purpose

Global equivalents of MCWARN, MCINS, MCSKIP and MCDEF.

General form

Similar to those of the corresponding local macros.

Examples

1. MCWARNG MACRO
2. MCINSG /.
3. MCSKIPG DT, TEXT : :
4. MCDEFG %A1. WITH ( , ) AS < . . . >

Restrictions

The restrictions on the forms of arguments are the same as for the corresponding local macros.

System actions

As for the corresponding local macros except that the newly-defined constituents are global rather than local.

Notes

1. If a global NEC macro is called in the source text, the effect is the same as if the corresponding local macro had been called (except for certain differences if the name is multiply-defined). Global constructions are not, however, deleted by the macros MCNOWARN etc. described in MCNOWARN MCNOINS MCNOSKIP MCNODEF. For reasons of efficiency the user is recommended to use local macros where possible.
2. If a call of MCWARNG occurs, all subsequent text processing will be in warning mode, since it is impossible to delete a global warning marker.

5.2.7 MCSTOP ¶

Purpose

Definition of a stop marker.

General form

MCSTOP {arg A} {NL}

Examples

1. MCSTOP NL
2. MCSTOP STOP WITHS RIGHT WITHS HERE

Restrictions

{arg A} must be a structure representation consisting simply of a single delimiter name.

Notes

Stop markers are always local constructions; there is no MCSTOPG.

System action

{arg A} is added to the current environment as a stop marker.

5.2.8 MCALTER ¶

Purpose

Alteration of the secondary delimiters of operation macros or of the keywords used in structure representations.

General form

MCALTER {arg A} TO {arg B} {NL}

Examples

1. MCALTER
TO ;
MCALTER AS TO : ;
   After these two calls of MCALTER, Example (a), of MCSKIP, would be written:

   MCDEF ARRSIZE : 6;
   

2. MCALTER WITH TO +
MCDEF JOIN + ( WITH ) AS . . .
MCALTER + TO WITH
   Here, WITH is changed to + and then back to WITH again in order to define macro JOIN( with delimiter WITH.
3. MCALTER N TO 9
   This changes the node flag to the character 9.
4. MCALTER SPACE TO BLANK

Restrictions

{arg A} and {arg B} must be single atoms. {arg A} must be either a secondary delimiter of one or more operation macros, or one of the keywords used in structure representations. {arg B} must not be longer than the system name of any delimiter or keyword matched by {arg A}. If {arg A} is the node flag (i.e. the letter N or whatever has replaced it) then {arg B} must be a letter or a digit.

Order of evaluation

{arg B}, {arg A}.

System action

{arg B} is substituted in place of {arg A} wherever {arg A} occurs as a secondary delimiter of an operation macro or as a keyword.

Notes

1. MCALTER cannot be used to change the names of operation macros.
2. It is very dangerous to change a keyword or delimiter to become the same as another keyword, for instance:

   MCALTER UNLESS TO IF
   

   The effect of an alteration such as the above on subsequent processing is undefined, since it depends upon the order in which delimiters are scanned.

3. In the unlikely event of a call of MCALTER specifying several replacements, some of which are valid, and some of which are invalid because of the length of {arg B}, then the number of valid replacements that are performed before the call is aborted is undefined.
4. In the MCGO macro (and in any other macro where the action taken depends upon the form of the delimiters), the delimiters are examined immediately the macro is called and no call of MCALTER within an argument can affect the action of the containing macro.
5. Since the operation macros are global, the effect of MCALTER is also global.
6. It has been assumed in examples throughout this manual (apart from this Section) that no calls of MCALTER have occurred.
7. Since MCALTER has a global effect, it is not recommended to use it locally to a piece of replacement text. If it is used locally, MCALTER must be called again before leaving the replacement text in order to cancel the changes that have been made.
8. A layout keyword can be MCALTERed to be the same as the character it represents, e.g.:

   MCALTER NL TO <
   >
   

   This will effectively delete the layout keyword, e.g. after the above MCALTER, newline would stand for itself within structure representations —it would not act as a separator.

5.3.1 MCLENG ¶

Purpose

Function to find the length of a character string.

General form

MCLENG ( {arg A} )

The left parenthesis is part of the macro name. It may optionally be preceded by spaces.

Examples

1. MCLENG (%A1.)
2. MCLENG(%A1.%D3.PIG)

System action

The value of this function is the number of characters in {arg A}. This number is represented as a character string in the way described in item (e) in Macro elements.

5.3.2 MCSUB ¶

Purpose

Function to access a substring.

General form

MCSUB ( {arg A}, {arg B}, {arg C} )

The left parenthesis is part of the macro name. It may optionally be preceded by spaces.

Examples

1. MCSUB (ABC/XYZ, 3, 6)
   This function has value C/XY.
2. MCSUB (ARGUMENT, -2, 0)
   This function has value ENT, since non-positive results of {arg B} and {arg C} specify offsets from the end of {arg A}.
3. MCSUB(%D2.,1,1)
   The value of this function is the first character of the inserted delimiter.
4. MCSUB (%A3. Y%D3., 1, P3 - T6 + 7)

Order of evaluation

{arg A}, {arg B}, {arg C}. However, {arg C} is not evaluated if VB (see below) is greater than L (see below) or is less than one.

System action

Let L be the number of characters in {arg A}, let RB be the result of {arg B}, and let VB be derived from these values by the following rule:

        (RB if RB > 0
VB =    (
        (L + RB otherwise

Let VC be derived from the result of {arg C} by a similar rule. The value of a call of MCSUB depends upon whether VB and VC describe a valid substring of {arg A}. This occurs if:

1 <= VB <= VC <= L

If this relation does not hold, the value of MCSUB is null. If the relation holds, the value of MCSUB is the substring of {arg A} from character position VB up to and including character position VC, the first character of {arg A} being taken as character position one.

Notes

1. In the case where the relation holds, the value of MCSUB consists of VC-VB+1 characters.
2. The value of MCSUB is not itself evaluated. Thus the value of example b) above would be ENT even if ENT was a macro.

5.4.1 MCSET ¶

Purpose

Macro-time assignment statement.

General form

MCSET {arg A} = {arg B {NL}

Examples

1. MCSET P10 = 3
2. MCSET T6 = -4
3. MCSET TT3 = TP4 - 109 + 25/P1
4. MCSET T%A1. = %A1. + 17

where the value of the inserted argument is a positive integer.

Restrictions

{arg A} must be the name of a macro variable in the current environment ({arg A} may contain redundant spaces at the beginning or the end). {arg B} must be a macro expression if {arg A} describes an integer macro variable, or an arbitrary character string (of length no greater than the current range) if {arg A} describes a character macro variable.

System action

The result of {arg B} is assigned to the macro variable designated by {arg A}.

Notes

1. When values are assigned to character variables, the whole of the second argument to MCSET (after the usual deletion of spaces at the beginning and end of the argument) is assigned to the specified character variable. If leading or trailing spaces are to be preserved, the argument must be enclosed in literal brackets. For example:

   MCSKIP MT,<>
   MCSET C1 =      ABC	length of contents of C1 is three
   MCSET C1 = <    ABC   >	length of contents of C1 is ten

2. No particular operators are provided for the manipulation of character variables, since the basic ML/I facilities are sufficient. To add together (concatenate) two character variables, simply insert both of them:

   MCSET C1 = %C2.%C3.
   

5.4.2 MCNOTE ¶

Purpose

Generation of user’s own error and debugging messages.

General form

MCNOTE {arg A} {NL}

Examples

1. MCNOTE %A3. is illegal argument
2. MCNOTE Occurrence number %P1. of <CONT>

System action

{arg A} is printed on the debugging file (see Error messages) as if it were a system message. A newline is inserted in front of it, and it is followed by a printout of the context of the call of MCNOTE.

Notes

1. If example b) occurred in line 3 of a macro CONT, then the output might be:

   Occurrence number 33 of CONT
   detected in
   line 3 of macro CONT with no arguments
   called from
   line 267 of source text
   

2. Notes d) and f), of Notes on context print-outs, do not apply to the printing of {arg A}.

5.4.3 MCGO ¶

Purpose

Macro-time ‘goto’ statement or conditional ‘goto’ statement.

General forms

1. MCGO {arg A} {NL}
2. MCGO {arg A} (IF    ) {arg B} (= ) {arg C} {NL}
             (UNLESS)         (BC)
                              (EN)
                              (GE)
                              (GR)
   The meanings of the respective mnemonic second delimiters are: Belongs to Class, Equals Numerically, Greater than or Equals, and GReater than.

Examples

1. MCGO L1
2. MCGO LT1
3. MCGO L6 IF %D1. = +
4. MCGO L0 UNLESS P3 - T5 GE - 6
5. MCGO L T3 - P7 + 4 UNLESS %A6. BC N
   This tests whether argument six is a number (Belongs to the Class of Numbers).

Restrictions

{arg A} must consist of the letter L (optionally preceded by redundant spaces) followed by a macro expression. The result of this macro expression must never be negative and, furthermore, it must not be zero if MCGO is called from the source text. If the second delimiter is BC then {arg C}, which is the name of a class, must consist of one of the following letters:

I

(for identifier)

L

(for letter)

N

(for number)

together with any desired number of spaces. If the second delimiter is EN, GE or GR then {arg B} and {arg C} must both be macro expressions.

Order of evaluation

{arg B}, {arg C}, {arg A}. In form b), {arg A} is evaluated only if the condition holds.

System action for form b)

{arg B} and {arg C} are compared to yield a true or false value. If the second delimiter is EN, GE or GR, then numerical comparison is performed; otherwise character comparison is performed. The method of comparison depends on the second delimiter in the following way:

=

A true value results only if {arg B} and {arg C} are identical strings of characters.

BC

If {arg C} is the letter I, then a true value results only if {arg B} is of form:

[ {letter} *]
  {digit }

If {arg C} is the letter L, then a true value results only if {arg B} is of form:

[ {letter} *]

If {arg C} is the letter N, then a true value results only if {arg B} is of form:

[ (+) *?] [ {digit} *]
  (-)

EN, GE, GR

In these cases a true value results only if the result of {arg B} is, respectively, numerically equal to, greater than or equal to, or greater than the result of {arg C}.

If the comparison yields a false value and the second delimiter is IF, or if the comparison yields a true value and the second delimiter is UNLESS, then no further action takes place. Otherwise the system action for form a) is now performed.

System action for form a)

Let N be the result of the macro expression in {arg A}. If N is positive, then the point of scan is changed to the point associated with macro label N (see below for a fuller description). If N is zero, then processing of the current piece of text is abandoned and evaluation proceeds as if the end of the current piece of text had been reached. Thus when N is zero a MCGO serves a similar function to the RETURN statement found in many high-level languages. This ‘return’ facility may be used within inserted text or replacement text but not within the source text.

Notes

1. Note that leading and trailing spaces are removed before {arg B} and {arg C} are evaluated. If it is required that these spaces take part in the comparison, they should be enclosed in literal brackets.
2. If it is desired to achieve the effect of a backward ‘goto’ in the source text, then the required loop must be defined as the replacement text of a macro call. For an example, See Macro-time loop.
3. Optimising macro-generated code, as well as Differentiating special-purpose registers and storage locations, contain examples of the use of MCGO.
4. The user should be very careful to differentiate between the two relational operators = and EN. Note that the relation:

   P1 EN P2
   

is true if the first two permanent variables have the same value, whereas:

P1 = P2

is, of course, never true. Note that:

%P1. = %P2.

is equivalent to:

P1 EN P2.

Exact description of a ‘goto’ *

The following is a more exact description of the action of ML/I in performing a ‘goto’ when N is positive.

If label N, which is called the designated label, is present in the current environment then the action of ML/I is simply to change the point of scan to the point associated with the designated label. Otherwise a forward search for the designated label is performed, starting at the current point of scan. If a macro call or skip is encountered during this search, the search is suspended until the end of the macro call or skip is found. Each time an insert is encountered outside a call or skip, the argument is evaluated and the search ends when an insert which ‘places’ label N is found (or, in the error case, at the end of the current piece of text). No value text is generated during a search and no macro calls are performed (except conceivably during the evaluation of the argument of an insert). At the end of the search the action of ML/I is concluded by setting the point of scan as the point immediately after the designed label.

Any labels encountered in the forward search (including the designated one) are added to the current environment provided that it is possible to satisfy the rules of part f) of Macro elements. If an error is detected during a forward search then the appropriate error message is output in the normal way.

5.4.4 MCPVAR ¶

Purpose

Allocation of extra permanent variables.

General form

MCPVAR {arg A} {NL}

Examples

1. MCPVAR 100
2. MCPVAR T1+3

Restrictions

{arg A} must be a macro expression.

System action

Let N be the result of {arg A}. If N is greater than the current number of permanent variables, then the number of permanent variables is increased to N; otherwise no action is taken. The values of the new permanent variables are set to zero, and the values of the previously allocated ones remain unchanged.

5.4.5 MCCVAR ¶

Purpose

Allocation of extra character variables.

General form

MCCVAR {arg A} [ , {arg B} ?] {NL}

Examples

1. MCCVAR 50
2. MCCVAR T1*4

Restrictions

{arg A} and {arg B} must be macro expressions.

System action

Let N be the result of {arg A}, and let M be the result of {arg B}.

If this is the first call of MCCVAR in the current process, {arg B} must be present, and the current range is set to M. If this is not the first call of MCCVAR, {arg B} may be omitted; however, if {arg B} is present, M must equal the current range (in other words, the range may not be altered once it has been set).

If N is greater than the current number of character variables, then the number of character variables is increased to N; otherwise no action is taken. The values of the new character variables are set to null (the empty string), and the values of the previously allocated ones remain unchanged.

6.4.1 Illegal macro element ¶

Message

{flag} {number} is illegal macro element

Description

The {number}, which is the value of the subscript or macro expression associated with the {flag}, is either too large or too small. Alternatively, macro elements of the type designated by the {flag} do not exist in the current environment (e.g. there are no arguments or temporary variables in the source text).

System action

The current operation macro or insert is aborted.

6.4.2 Arithmetic overflow ¶

Message

Arithmetic overflow

Description

Overflow has occurred during the evaluation of a macro expression or subscript. This message occurs when an attempt is made to divide by zero. It may also occur under other circumstances, but these are implementation-defined (see Section 5 of relevant Appendix).

System action

The current operation macro or insert is aborted.

6.4.3 Illegal input character ¶

Message

Illegal input character

Description

A character of the source text is not in the character set of the implementation.

System action

The illegal character is replaced by a fixed implementation-defined character called the error character (see Section 4 of relevant Appendix). A typical error character is the question mark.

6.4.4 Illegal macro name ¶

Message

Illegal macro name after warning, viz "{atom}"

Description

A warning marker is followed, possibly with intervening spaces, by the given {atom} which is not a macro name (nor the start of a multi-atom macro name). If this error occurs within an argument, the above message is printed both when the argument is originally scanned and also each time it is inserted.

System action

The warning marker is treated as if it had not been recognised as an environmental name, and the atom which follows is treated as if no warning marker had occurred. Thus, for example, a skip name following a warning marker will be treated as a skip name.

This message is suppressed altogether if system variable S3 is set to one (see Use of S1 to S9).

6.4.5 Unmatched construction ¶

Message

Delimiter {name} [or {name} *?] of (macro ) {name}
                                   (skip  )
                                   (insert)
in line {number} of current text not found

Description

The given construction which starts in the given line of the current piece of text is not complete. Note that the line number is relative to the current piece of text. When the error was detected the scan was searching for the given delimiter (or for one of the given alternative delimiters). The error is detected only when the scan reaches the end of the source text or the end of a piece of inserted text or replacement text, or a stop marker is encountered.

Possible causes

A mismatch of the delimiters of a construction nested within the given one can cause this error since delimiter matching is liable to get out of phase as a result. Alternatively, an incorrect specification of a delimiter structure can cause delimiters to be matched in a way not intended by the user and, again, the error may be in a nested construction rather than in the given one.

System action

In the call and insert cases, the effect is as if the text from the macro or insert name to the current point of scan was deleted. In the skip case, text skipped over is treated in the normal way and the skip is artificially terminated.

6.4.6 Illegal syntax of argument value ¶

Message

Argument {number} has illegal value, viz "{value}"

Description

The given value of an argument to an operation macro or insert has not the required syntax. For operation macro arguments see appropriate ‘Restrictions’ subsection of The NEC macros, System functions, or Further operation macros, or if the argument is (supposed to be) a structure representation then see Possible errors in structure representations. For arguments to inserts, see Macro elements.

System action

The current operation macro or insert is aborted.

6.4.7 Redefined label ¶

Message

Label {number} is multiply-defined

Description

An attempt has been made to re-define a label that has already been defined within the current text.

System action

The new definition is ignored.

6.4.8 Undefined label ¶

Message

Label {number} referenced in line {number} of current text not found

Description

A call of MCGO references an undefined label. This error is detected when the scan reaches the end of a piece of text (since it performs a search for the missing label). If any constructions are unmatched, the relevant message(s) (of Unmatched construction) are printed with this message.

Possible causes

An attempted backward MCGO in the source text or an attempted MCGO from one piece of text to another can cause this error. Alternatively, it can be caused by an unmatched construction within the scope of a forward MCGO.

System action

The effect is as if the designated label had been found at the very end of the current piece of text.

6.4.9 Storage exhausted ¶

Message

Process aborted for lack of storage
[possibly due to {other messages} ?]

Description

ML/I has used up all its available storage. If the current text is the source text then the following additional information is given: if there are any constructions currently unmatched, or if a search is being made for a macro label as the target of a MCGO, one or more of the relevant messages (of Unmatched construction, and Undefined label) are printed with this message.

Possible causes

Storage is taken up by macro variables, by the name environment, by a macro call or insert in the source text, and by nested calls and/or inserts. Hence an unmatched macro call in the source text or a call with a very long argument can cause this error. Alternatively, it can be caused by an endless or very deep recursive nest, by the name environment being too big, or by a combination of all these factors.

System action

The current process is aborted.

6.4.10 System error ¶

Message

System error {number}

Description

There has been a machine error, an operating error or an error in the implementation of ML/I. The value {number} indicates the location within the ML/I logic where the error was detected, and in general will be useful only when reporting the error to the implementor.

System action

The current process is aborted.

6.4.11 Subsidiary message ¶

Message

(Macro ) {name} aborted due to above error
(Insert)

Description

This message occurs as a subsidiary message every time an error causes the operation macro or insert currently being performed to be aborted. Any construction that has been aborted is given a null value.

6.4.12 Statistics ¶

Typical

At end of process: {number} lines, {number} calls

Description

The occurrence of this message is implementation-defined (see Section 4 of relevant Appendix). It is usually output at the end of a process and sometimes at intermediate stages as well. The number of lines of source text that have so far been scanned, together with the total number of macro calls performed (the value used as an initial setting of T2) is output.

6.4.13 Version number and current constructions ¶

Message

Version {version-string}
 .     .
Stops are
 .     .
Macros are
 .     .
Warnings are
 .     .
Inserts are
 .     .
Skips are
 .     .

Description

It is implementation-defined whether this message is output by default. {version-string} is the version of the machine-independent logic of ML/I. The version message is followed by a list of all the currently defined constructions, grouped by type.

This message is purely informational, but may be useful in identifying certain problems.

6.4.14 Implementation-defined messages ¶

Description

Each implementation may have its own particular messages. See Section 4 of the relevant Appendix for details.

7.2.1 Jumping over expanded code ¶

If macros are used in an assembly language, great care must be taken with instructions of the form ‘jump to location counter + N’, since there may be macros within the scope of the jump which expand into several machine instructions. The same applies to machine instructions of the form ‘skip one instruction’. For this reason it is helpful to choose macro names that cannot be confused with the names of machine instructions.

7.2.2 Generation of unique labels ¶

If a macro generates code which involves an execution-time label, then a different label must be generated at each call of the macro. The technique described earlier, in part b) of Insert definitions, can be used for this purpose. The same applies, in some cases, to execution-time temporary variables.

7.2.3 Lower case letters ¶

Note that only upper case letters may be used for vocabulary words of ML/I. This applies to the names and secondary delimiters of operation macros, to keywords and to insert flags. Further note that, for example, PIG, Pig and pig are three different atoms.

7.2.4 Use of newlines in definitions ¶

Remember that layout characters within replacement text are treated like any other characters. They should therefore be used with great care as they affect the format of the output text. Thus:

MCDEF LOAD AS <LD>
    LOAD  X

would generate:

    LD  X

whereas:

MCDEF STORE
AS  <ST
>
    STORE  Y

would generate:

    ST
  Y

Moreover:

MCDEF JUMP AS
<B>
    JUMP  LB6

would generate:

B
      LB6

since JUMP would be defined as a null macro.

7.2.5 Use of redundant spaces ¶

As a general rule, extra spaces are ignored within text that forms an instruction to ML/I, but are treated like any other character within text that ML/I manipulates.

Spaces may be chosen as construction names, but, in any context where spaces are ignored, they are ignored even if space is a construction name. In particular, spaces are ignored after warning markers so, when in warning mode, it is not possible to have a macro name commencing with a space.

Below is a list of some of the places where spaces are ignored:

1. At the beginning or end of an argument to an operation macro (before evaluation).
2. Ditto for an argument to a substitution macro, provided the insert flag B is not used.
3. After a warning marker.
4. Within a macro expression (except within variable names or constants).
5. Within the argument to an insert (except within variable names or constants).
6. Within the values of those operation macro arguments that specify options. Within structure representations, one or more spaces act as a separator.

7.3.1 Interchanging two names ¶

Problem

It is desired to interchange the names PIG and DOG in a piece of text.

Solution

The complete name environment is set up as follows:

MCSKIP MT, < >
MCDEF PIG AS <<DOG>>
MCDEF DOG AS <<PIG>>

and the desired result is achieved by evaluating the given text under this environment.

Notes

1. In this example there is no necessity to have an insert definition in the environment.
2. Notice that two pairs of literal brackets are used to surround the pieces of replacement text. One pair is stripped off at definition time and the second at replacement time. If the brackets were omitted, ML/I would endlessly replace PIG by DOG by PIG by DOG …

7.3.2 Removing optional debugging statements ¶

Problem

It is desired to include a number of extra statements in a FORTRAN program in order to aid in debugging its execution. These are to be removed when the program is debugged. Each statement ends with a newline.

Solution

Some unique atom, say DEBUG, is written at the beginning of each debugging statement. Before the FORTRAN program is compiled it is passed through ML/I. If it is desired to include the debugging statements, then the following skip definition is placed in the name environment:

MCSKIP DEBUG

This causes each occurrence of DEBUG to be deleted. When it is desired to delete the debugging statements then the following skip definition is used:

MCSKIP DEBUG NL

If DEBUG is always to be at the beginning of a line, it may be better to define the skips with:

MCSKIP SL WITH DEBUG

and

MCSKIP SL WITH DEBUG NL

as this will prevent matches with DEBUG if it occurs elsewhere in the scanned text.

7.3.3 Inserting extra debugging statements ¶

Problem

It is desired in an X123 Assembly Language program to replace every occurrence of DAC COW (deposit accumulator at COW) by a call to a subroutine (which perhaps prints the value assigned to COW). This call has form JMS TYPCOW.

Solution

MCDEF DAC WITHS COW AS <JMS TYPCOW>

7.3.4 Deleting a macro ¶

Problem

It is desired to delete the macro GONE from the current environment.

Solution

The following skip accomplishes this:

MCSKIP D, <GONE>

Notes

1. The literal brackets prevent GONE being called during the evaluation of the second argument of the above MCSKIP.
2. Strictly speaking, the macro GONE is overridden rather than deleted (see part a) of Implications of rules for name clashes.

7.3.5 Differentiating special-purpose registers and storage locations ¶

Problem

It is desired to define an INTERCHANGE macro for X123 Assembly Language so that, as well as being used to interchange the values of two storage locations, it can be used to interchange the accumulator with a storage location. In the latter case ACC is written as the first argument of the call.

Solution

Assuming the existence of a MOVE FROM macro, which moves the value of one storage location into another, the definition of INTERCHANGE is written:

MCSKIP " WITH " NL
MCDEF INTERCHANGE WITH ( , ) WITH NL
AS <MCGO L1 IF %A1. = ACC
MOVE FROM %A2. TO TEMP;MOVE FROM %A1. TO %A2.;
MOVE FROM TEMP TO %A1.;
MCGO L0
%L1.     DAC TEMPAC        "" deposit accumulator in TEMPAC
MOVE FROM %A2. TO TEMP;MOVE FROM TEMPAC TO %A2.;
     LAC TEMP              "" load accumulator from TEMP
>

Note the use of the initial skip here, to provide a comment facility.

7.3.6 Testing for macro calls ¶

Problem

It is desired to find out whether an argument of a macro call itself involves any macro calls, inserts or skips.

Solution

Compare the written form of the argument with its evaluated form (it is assumed that any construction occurring within the argument would cause these two forms to be different). The following is an example of how the test might be written:

MCGO L1 IF %A1. = %WA1.

Alternatively, if it was only required to test if the argument involved any macro calls, the test might be written:

MCGO L1 IF MCNODEF%A1. = %A1.

provided that % had been defined as an unprotected insert.

7.3.7 Searching ¶

Problem

It is desired to search the source text to find all occurrences of given atoms.

Solution

Define macros such as:

MCDEF X
AS <MCNOTE HERE IS <X>
>

It is best to send the output text itself to a null output file so that the only printed output is the MCNOTE messages.

7.3.8 Bracketing within macro expressions ¶

Problem

Parentheses cannot be used within macro expressions.

Solution

Use nested inserts. For example to insert the value of:

(P1+6)/(P3-2)

write:

%%P1+6./%P3-2..

7.3.9 Deletion from source text only ¶

Problem

It is desired to delete a given atom only if it occurs in the source text.

Solution

Use temporary variable three, e.g.:

MCDEF X AS <MCGO L0 IF T3 EN 1
%WD0.>

7.3.10 Locating missing delimiters ¶

Problem

A missing delimiter may cause ML/I to ‘run away’ while scanning, perhaps causing it to exhaust the available storage. Although the error messages will locate the problem, they are likely to be excessive.

Solution

Define a stop marker. Experience with stop markers has shown that, in nine out of ten applications of ML/I, it is a good idea to include:

MCSTOP NL

in the environment. It is best to make this the last definition, since calls of certain operation macros may legally straddle several lines.

7.3.11 Handling line-oriented input ¶

Problem

ML/I treats its input as ‘free format’, whereas a particular piece of input is line oriented and therefore difficult to handle.

Solution

Use startlines. For example, suppose that it is desired to handle labelled and unlabelled statements in X123 Assembly Language separately. Assume that statements are one per line, and that unlabelled statements begin with at least one space, but that labels must occur at the start of a line. The macro to handle unlabelled statements would look like this:

MCDEF SL WITH SPACES . . . NL AS . . .

and the macro to handle labelled statements could be defined as:

MCDEF SL . . . NL AS . . .

remembering, of course, to turn startlines on (see Use of S1 to S9) before scanning the actual X123 program. Note that although both macro names begin with the atom SL, ML/I will always try to find the longest match, so there is no danger that an unlabelled statement will cause a call of the macro intended for labelled statements.

Notes

It is possible to achieve a similar effect by using macros starting with a newline, with the closing delimiter being another newline as an exclusive delimiter. However, this is rather more tricky than using startlines.

7.4.1 Macro-time loop ¶

Problem

A macro-time iteration statement is required in order to generate repetitive text.

Solution

The macro MCFOR defined below serves this purpose. It allows the step size to be optionally omitted; in this case a step size of one is assumed. MCFOR should be regarded as a ‘black box’ by the reader who finds the definition below hard to understand. The part labelled by L2 is to deal with a negative step size.

MCDEF MCFOR = OPT STEP N1 OR N1 TO ALL NL REPEAT
AS<MCSET %A1. = %A2.
MCSET T3 = 1
MCGO L1 IF T1 EN 4
MCSET T3 = %A3.
MCGO L1 IF T3 GR 0
%L2.MCGO L0 IF %AT1-1. GR %A1.
%AT1.MCSET %A1. = %A1. + T3
MCGO L2

%L1. MCGO L0 IF %A1. GR %AT1-1.
%AT1.MCSET %A1. = %A1. + T3
MCGO L1
>

Examples

1. To generate the twenty instructions:

   JMP LAB1
   JMP LAB2
     . .
     . .
   JMP LAB20
   

   one could use:

   MCFOR P1 = 1 TO 20
   JMP LAB%P1.
   REPEAT
   

2. To generate the above twenty instructions in reverse order:

   MCFOR P6 = 20 STEP -1 TO 1
   JMP LAB%P6.
   REPEAT
   

3. To generate the first ten powers of two:

   MCSET P2 = 1
   MCFOR P1 = 1 TO 10
   %P2.MCSET P2 = P2+P2
   REPEAT
   

Notes

1. The controlled variable must be a permanent variable (if it were a temporary variable, MCFOR would try to use its own temporary variables rather than those of the calling environment thus causing an error).
2. The initial value, step size, and final value must be macro expressions not involving temporary variables.
3. MCFOR is a substitution macro, not an operation macro.
4. Calls of MCFOR may be nested.
5. MCFOR can be used to perform loops within the source text, thus surmounting the restriction that source text ‘gotos’ are not allowed.

7.4.2 Examining optional delimiters ¶

Problem

An IF macro has form:

IF {arg A} (GE) {arg B} THEN . . .
           (GR)
           (LT)
           (= )
           (etc.)

Within the replacement text of IF, it is desired to examine the form of the first delimiter and go to L1 if the delimiter is GE, to L2 if it is GR, etc. This problem can obviously be solved by writing a large number of conditional MCGO statements but this would make the IF macro very slow and cumbersome.

Solution

The various possible delimiters can be defined as macros thus:

MCDEF GE AS 1
MCDEF GR AS 2
    etc.

and then the requisite switch statement can be written:

MCGO L%D1.

Notes

1. The definition of the delimiters of IF as macros does not affect the scanning of a call of the IF macro since the use of an atom as a delimiter takes precedence over its use as a macro name.
2. It is necessary to place the definitions of GE etc. after the definition of IF or else to enclose the structure representation of IF within literal brackets.
3. The technique will not, as it stands, work for name delimiters. However, see Constructions with restricted scopes).

7.4.3 Dynamically constructed calls ¶

Problem

It is required to implement a WHILE macro of form:

WHILE {arg A} (GE) {arg B} DO
              (GR)
              (LT)
              (= )
              (etc.)
{arg C}
END

Within the replacement text of this macro it is desired to call the IF macro with the first delimiter of this call of IF the same as the delimiter that occurred in the call of WHILE. However, as was seen in Dynamically generated constructions, it is not possible to do this by writing:

IF . . . %WD1. . . . THEN . . .

Solution

It is necessary to use a temporary macro definition to build up the text for the required call of IF and then to call the temporary macro. This could be achieved thus:

MCDEF <temp> AS <IF> . . . %WD1. . . . THEN . . .
temp

Notes

1. WD1 was used rather than D1 since GE etc. are macros and it is not desired to call them at this stage.
2. Note that the insert %WD1. is not enclosed in literal brackets and is thus inserted when temp is defined. Thus if this delimiter were GR, then the replacement text of temp would be:

   IF . . . GR . . . THEN . . .
   

   and calling temp would then accomplish the required call of IF.

3. temp is enclosed in literal brackets when it is defined in case there is already a temp macro in existence. This might arise, for example, if the WHILE macro was called recursively.
4. temp should be a local macro rather than a global one so that the storage it occupies is released when an exit is made from the WHILE macro.
5. This general technique can be used in all cases where it is required to build up a call dynamically. The next Section contains a further example of the technique.

7.4.4 Arithmetic expression macro ¶

Problem

A macro whose name is ( has been designed so that, when supplied an arithmetic expression as argument, it generates assembly code to calculate the value of the expression and to place the resultant value in an accumulator. This macro will be referred to as the parenthesis macro. A typical call of the parenthesis macro might be:

(PIG + (Y/6)*Z - 16)

This involves a nested call of the same macro. The arguments of the outer call are PIG, (Y/6), Z and 16, and the delimiters are +, * and -. It is desired to use this macro to implement a SET macro, which allows a macro expression as argument. Calls of SET might be:

SET DOG = Y
SET VAR = (VAR + 6)/I3 - PIG

Solution

The solution to this problem is not to give the SET macro a complicated delimiter structure but rather to regard it as a macro with two arguments. The second argument is then passed down to the parenthesis macro, which breaks it down into operators and operands. The SET macro is defined:

MCDEF SET = NL
AS <MCDEF temp AS <(>%WA2.<)>
temp
(instruction to store the result in %A1.)
>

Notes

1. Notice the use of temp to build up a call of the parenthesis macro. In the second of the above examples of SET, for instance, temp would be defined as:

   ((VAR+6)/13 - PIG)
   

   When temp was called, it would result in a call of the parenthesis macro with arguments (VAR+6), 13 and PIG.

2. It would have been wrong to call the parenthesis macro from within SET by writing simply (%A2.), since this would have been interpreted as a call with one argument.

7.4.5 Formal parameter names ¶

Problem

It is desired to use the name TAXRATE for the first formal parameter of the macro DEDUCT.

Solution

The first part of the definition of DEDUCT is written:

MCDEF DEDUCT . . . AS <MCDEF TAXRATE AS %A1.
. . .

Thereafter within the replacement text of DEDUCT, TAXRATE can be written in place of %A1. whenever the first parameter is required.

7.4.6 Intercepting changes of state ¶

Problem

It is desired in X123 Assembly Language to generate some decimal constants within the replacement text of a macro SIZE. However, X123 Assembly Language has two statements, DECIMAL and HEXADECIMAL, to control the base to which constants are to be written, and this might vary between calls of SIZE. Furthermore, it is desired that a call of SIZE should not change the base behind the user’s back.

Solution

A permanent variable, say P10, is used as a switch, the value zero being used to indicate a hexadecimal base. The following is written at the start of the source text:

MCSET P10 = 0
MCDEF HEXADECIMAL AS <MCSET P10 = 0
%WD0.>
MCDEF DECIMAL AS <MCSET P10 = 1
%WD0.>

and the definition of SIZE is written:

MCDEF SIZE AS <MCSET T1 = P10
DECIMAL
   .
   .
   .
MCGO L0 IF T1 EN 1
HEXADECIMAL
>

thus ensuring that the base is returned to its original state.

Note

This technique is also useful for the following problem: the user has written a macro SUBS to generate code for subscripted vectors and it is necessary that SUBS generates different code for the two following calls:

1. LAC SUBS (V, 1)    Load accumulator from element
2. DAC SUBS (V, 1)    Store accumulator in element

The problem is solved by using the above technique to cause LAC and DAC to set a switch which the SUBS macro can then test to find out which instruction preceded its call.

7.4.7 Remembering code for subsequent insertion ¶

Problem

It is desired to design two macros, remember and insert, to enable the user to remember text for subsequent insertion. These macros are used in the following way. remember is called with a piece of text as argument. remember does not generate any code but remembers its argument for subsequent insertion. When the insert macro is called, all the pieces of text that have been remembered are inserted.

Solution

A sequence of global macros I1, I2, …, IN is used, the value of N being given by a permanent variable, say P10. Each macro represents a piece of text that is to be remembered. The definitions of remember and insert would be written:

MCSET P10 = 0
MCDEF remember ;
AS <MCSET P10 = P10 + 1
MCDEFG I%P10. AS %A1.
>
MCDEF insert AS <MCFOR P1 = 1 TO P10
RECALL I%P1.
REPEAT>

where MCFOR is the macro of Macro-time loop, and RECALL is a macro defined thus:

MCDEF RECALL NL
AS <MCDEF temp AS %A1.
temp>

An alternate solution, which is much faster but which places limitations on the size of each item, can be devised using character variables. This is left as an exercise for the reader, as it is merely a degenerate form of the above solution.

Notes

1. The above solution tries to minimise the amount of storage used. It would have been possible to do without the RECALL macro, but this would have involved N redefinitions of temp within the MCFOR loop and so, albeit temporarily, using up rather more storage.
2. Note that the macros I1 etc. must be global whereas the macro temp should be local.
3. An apparently promising technique for this problem which may fail because of excessive use of storage is the following. The entire remembered text is maintained by redefining the insert macro as below each time remember is called:

   MCDEF remember ;
   AS <MCDEFG <insert> AS insert%A1.
   >
   

   The trouble with this approach is that old versions of insert can never be released, thus using up a very considerable amount of storage.

7.4.8 Constructions with restricted scopes ¶

Problem

It is desired to assign different meanings to a macro X within different scopes. One meaning is to apply within the replacement text of a set of macros Ml, … , MN whereas another meaning is to apply elsewhere.

Solution

One solution is to redefine X as a local macro within each of M1 to MN, but this is tiresome if N is large, and slower than the method below even if N is one. A better solution is to place the two following definitions at the start of the source text:

MCDEFG X . . . AS <{replacement to be used in M1 to MN}>
MCDEF <X . . . > AS <{replacement to be used elsewhere}>

The second definition overrides the first. Within the macros M1 to MN the first definition can be re-incarnated by calling MCNODEF, which deletes the second definition. Any macros besides X that were used within M1 to MN should also be defined as global.

Notes

1. This technique can be used in a variety of applications. It is the best solution in almost all situations where a macro or set of macros has restricted scope, but where this scope does not consist simply of the replacement text of a single macro. Even in the latter case the technique is useful as it is faster than setting up the local definitions every time a macro is called.
2. This technique can be used to extend the technique described in Examining optional delimiters, to make it work for name delimiters. For example, if a macro had alternative names A and B and, within the replacement text of this macro, it was desired to insert the number 206 if the name was A and the number 15 if the name was B then this could be achieved, assuming % to be an unprotected insert, by writing:

   MCDEFG A AS 206
   MCDEFG B AS 15
   MCDEF <OPT A OR B ALL . . .>
   AS <. . . MCNODEF%D0. . . .>
   

7.4.9 Optimising macro-generated code ¶

Problem

It is desired to optimise some assembler code generated by ML/I, in particular to cut down possible inefficiencies at the boundary between successive macros.

Solution

There are basically two approaches to producing optimal code:

1. Code can be optimised as it is produced. Typically this would involve using the permanent variables to maintain some sort of indication of the previous instruction(s) generated.
2. A second pass can be made through the macro generated code, to search for various inefficient sequences of instructions.

Except in simple cases, the second method is usually the better. In many machines, considerable optimisation can be performed by maintaining where possible an indication of the contents of the accumulator(s) or other special-purpose registers and thus cutting out redundant loading instructions. This can be done by defining macros to map into numbers all the variables used in the code being generated. A permanent variable, say P1, could be used to indicate whether the accumulator was known to contain the current value of a particular execution-time variable. If so, P1 could contain the number of the variable, otherwise it could be zero. P1 would need to be zeroised when a label was placed, a subroutine was called, etc. This might be achieved by defining a macro with many alternative names, covering all the situations where the accumulator was clobbered. The macro might be:

MCDEF OPT , OR JMS OR ADD OR . . . ALL
AS <MCSET P1 = 0
%WD0.>

(assuming that a comma marks the end of a label and JMS, ADD, etc., are instructions that clobber the accumulator).

7.4.10 Macro to create a macro ¶

Problem

This problem illustrates the use of a macro to set up the definition of another macro. The problem is as follows. It is desired to design a macro EQUATE which equates one vector to part of another. Thus the call:

EQUATE VEC1 TO VEC2 OFFSET 3

would cause each subsequent reference to an element of VEC1, which has form, say:

VEC1( {subscript} )

to be translated into a reference to the corresponding element of VEC2, namely:

VEC2( {subscript} +3)

Solution

The macro EQUATE would be defined thus:

MCDEF EQUATE TO OFFSET NL
AS <MCDEFG %A1. WITH ( ) AS %A2.(<%A1.>+%A3.)
>

Examples

1. The call:

   EQUATE VEC1 TO VEC2 OFFSET 3
   

   would be equivalent to writing the definition:

   MCDEFG VEC1 WITH ( ) AS <VEC2(%A1.+3)>
   

Note

The main source of error in this sort of problem is to confuse the arguments of the macro that creates the definition with the arguments of the new macro being defined. The rule is that the latter should be enclosed doubly in literal brackets. Hence in the replacement text of EQUATE, the arguments within single literal brackets are the arguments of EQUATE, which are inserted when the new macro is defined, and the argument within double literal brackets is the argument of the new macro, which is inserted when the new macro is called.