MAC[RO]

Syntax

   MAC[RO] name {body}
   MAC[RO] name [ (parameters) ] {body}
   MAC[RO] name [ (parameters) ] [options] {body}

Parameters

name

The name of the macro that is being defined. Names must begin with an alphabetic character and are restricted to thirty-two (32) characters, that must be alphanumeric, or "_", or " ' ", or "$". Longer names are truncated (with a warning). Names are case insensitive.

All macros are functions that can be used as operands within expressions to return a single value of a specified type.

A default macro return value can optionally be specified directly following the macro name. The return_type must be preceded by a colon. The default return_value must be preceded by an equal sign, and can be entered as an expression. Below is a syntax of a macro call, followed by examples:

   macro name [:return_type] [= return_value]

For example:

   macro getnextptr:s16 = -1            {body}
   macro tblname = "UNDEF"              {body}
   macro tblsize:u32 = max * entrylen   {body}
   macro fmtstring:str                  {body}

If the default macro return_value is not specified, one is assigned automatically, based on the type of the macro. The following table lists the default return_values that are based on the macro's return_type:

Macro Return Type

Default Return Value

BOOL

FALSE

U16, S16, U32, S32, SPTR

0

LPTR

0.0

CPTR class

0.0 (based on type)

STR

' ' (null string)

By default, a macro is assigned the return value of 0 as a signed 32-bit number.

( parameters )

Macros can optionally have a maximum of five declared parameters. Parameter definitions are declared within parentheses, separated by blanks or commas.

   ( parm1def parm2def,  parm3def, parm4def parm5def )

Parameter names have the same restrictions as macro names. Names must begin with an alphabetic character and are restricted to thirty-two (32) characters, that must be alphanumeric, or an underscore (_), a single quotation (`or'), or a dollar sign ($). Longer names are truncated (with a warning). Names are case insensitive.

Each parameter definition can include an optional parmtype declaration that must follow after a colon. In addition, a default initial value for the parameter can optionally be specified, preceded by an equal sign. The initial value can be an expression. Below is a syntax of a parameter description, followed by examples:

   ( parmname1 [:parmtype1] [=parm_default_value1], ..

   ( addr:sptr=c000104c, len=0, count=20 )
   ( p1:u32=$100, p2=40-!count  p3:str="totals")

When a macro is invoked, a local variable is declared for each parameter, just as if the following command(s) had been entered:

   LOC parmname1 :type1= default1
   LOC parmname2 :type2= default2  ... etc.

Parameters are referenced within the macro body in the same manner that local variables are referenced. The parameter name can be preceded by an optional exclamation mark (!) to avoid ambiguity.

When execution of the macro body is completed, the local variables declared for the parameters are automatically deleted.

{body}

The macro body is a single command, or a list of commands, entered between curly braces. Multiple commands must be separated by semicolons. The commands in this body are executed whenever the macro is invoked. For example:

                   { CMD }
   { CMD1; CMD2; CMD3; .. CMDn }

Unterminated command lists, introduced by the left curly brace, can span multiple lines without the use of the continuation character (&) between lines. Additional command lines are automatically digested as part of the cmdlist until the closing right brace is detected.

   { CMD1;
     CMD2;
     CMD3;
         ...
     CMDn }

The RETURN command is used within the macro body to return a specified value and to exit the macro immediately. If a RETURN command is not supplied within the macro body, the macro exits when all commands have been executed, and the default return value is used.

options

Special macro options can be specified following the parameter declarations that precede the macro body. Any number of these options can be specified in any order. Each option is specified as a keyword, followed by a (case sensitive) string value:

• MACVER = version_string

• MACKEY = keyword_string

• MACHELP = help_string

The following are typical valid declarations for macro options:

• MACVER = 'A.00.01'

• MACKEY = "PROCESS PIN PARENT"

• MACHELP = "Returns the pin number of the parent process"

By default, the null string (' ') is assigned for unspecified options.

Examples

   $nmdat > macro showtime {wl 'The current time is: ' time}
   $nmdat > showtime
   The current time is:  2:14 PM

   $nmdat > macro starline (num:u16=#20) {
   {$1} multi > while num > 0 do {
   {$2} multi >   w '*';
   {$2} multi >   loc num num -1 };
   {$1} multi > wl }

   $nmdat > starline (5)
   *****

   $nmdat > starline (#60)|
   ************************************************************

   $nmdat > starline
   ********************

   $nmdat > starline (-3)
   Parameter type incompatibility.  (error #4235)
     expected the parameter "num:U16"  for "starline"
     starline (-3)
                 ^
    Error during macro evaluation.  (error #2115)

   $nmdat > mac fancytime {starline(#30); showtime; starline(#30)}
   $nmdat > fancytime
   ******************************
   The current time is:  2:17 PM
   ******************************

   %nmdebug > mac printsum (p1,p2=0) {wl "the sum is " p1+p2}
   %nmdebug > printsum (1 2)
   the sum is $3
   %nmdebug > printsum 3 4
   the sum is $7
   %nmdebug > printsum 5
   the sum is $5

 %cmdebug > mac is (p1="DEBUG",p2:str="GNARLY") {wl p1 "is very" p2.}
 %cmdebug > is ("MPE" 'mysterious')
 MPE is very mysterious.
 %cmdebug > is ("mpe")
 mpe is very GNARLY.
 %cmdebug > is
 DEBUG is very GNARLY.

   %nmdat > mac double (p1) { return p1*2 }
   %nmdat > wl double(2)
   $4
   %nmdat > wl double(1+2)+1
   $7

   %nmdat > mac triple (p1:INT) { return p1*3 }
   %nmdat > wl triple(2)
   $6
   %nmdat > wl triple (double (1+2))
   $12

   $nmdebug > { macro factorial=1 (n)
   {$1} multi >  machelp = 'Returns the factorial for parameter "n"'
   {$1} multi >  mackey  = 'FACTORIAL UTILITY ARITH TEST'
   {$1} multi >  macver = 'A.01.00'
   {$1} multi >  { if n <= 0
   {$2} multi >    then return
   {$2} multi >    else if n > 10
   {$2} multi >         then { wl "TOO BIG"; return}
   {$2} multi >         else return n * factorial(n-1)
   {$2} multi >  }
   {$1} multi > }

   $nmdebug > wl factorial(0)
   $1
   $nmdebug > wl factorial(1)
   $1
   $nmdebug > wl factorial(2)
   $2
   $nmdebug > wl factorial(3)
   $6
   $nmdebug > wl factorial(123)
   TOO BIG
   $1

Discussion - Macro Parameters

   $nmdat > { macro double( num=$123, loud=TRUE)
   {$1} multi > { if loud
   {$2} multi >   then wl 'the double of ', num, ' = ', num*2;
   {$2} multi >   return num*2}
   {$1} multi > }
   $nmdat >

Macro Functions

   $nmdat > wl double(1,false)
   $2

   $nmdat > wl double(,false)
   $246

   $nmdat > wl double ()
   the double of $123 = $246
   $246

   $nmdat > wl double
   the double of $123 = $246
   $246

Macro Commands

   $nmdat > double 1
   the double of $1 = $2

   $nmdat > double (2)
   the double of $2 = $4

   $nmdat > double 3 true
   the double of $3 = $6

   $nmdat > double ( (1+2)*3 )
   the double of $9 = $12

   $nmdat > double
   the double of $123 = $246

   $nmdat > double 6,false
   $nmdat >

Limitations, Restrictions