2.3.1.7 Define Macro ($$x...$$)

This command defines a Cogsys macro x. A macro definition associates a sequence of Cogsys commands with a macro identifier. The macro identifier is a single character x which can then be called by the Run Macro command $x. Cogsys then executes the code for that macro. This provides an easy mechanism for encapsulating commonly used code in a testlist. Up to 20 macros may be specified, of 10384 characters each.

Note: Traditionally, a macro is a piece of code that looks like a function call but which is actually replaced by the code it represents before the program is processed. A Cogsys macro is not replaced in-line; rather it is a true function that is actually called with a return value pushed onto a call stack. However, the name "macro" was used in earlier versions, and it has stuck.

Starting with Cogsys version 3.0.9, macros may take arguments. Argument names are listed in square brackets immediately following the identifier, and are then embedded in the macro body in any order at any location. Up to 8 arguments can be used, and each argument can be up to 16 in size. When the macro is called with arguments, Cogsys replaces the ocurrence of the argument name in the body of the macro with the text actually passed. The argument name must be separated from the rest of the text by spaces or non-alphabetic characters, in order for the substitution to take place.

Macros are traditionally placed at the top of a testlist, however macros may be redefined at any time.

A macro body definition must be under 10384 characters long. Cogsys reserves an extra buffer, slightly larger than 10384 characters, for the expanded macro: (10400). If these bounds are exceeded, a run time error results.

Name:

Define Macro

Class:

Control

Code:

$$x...$$

Syntax:

$$macro-idmacro-body$$
$$macro-id[arg1,arg2,...]macro-body...arg1...arg2$$
macro-id is a single character from the set `0' -- `9' , `a' -- `j'.
macro-body is any sequence of Cogsys commands
arg1, ... are macro arguments

System:

Defines the macro macro-id to be macro-body.

Test Files:

MCDF_T01.IN: Tests basic operation

@CPress any key to run macro examples#R $$0@CThis is macro zero. It does not take arguments. Press any key#R@C$$ $$1been assigned$$ $$2been given$$ $$3entered$$ $$a[name,num,mac]Hi, name! You have $mac number num.$$ $$4[first,second]@C@1005first@1035second#W1000@C#W500$$ $0 $a[usman,3,2] Press any key for another illustration of this macro#R $a[russ,12,1] Press any key to redefine macro zero#R $$0This is macro zero redefined. Press any key#R$$ $0 Macro four displays letters on the screen. The letters are arguments one and two, letter one appearing on the left, and letter two appearing on the right. There are six letter pairs which are about to be displayed, with one second in between, and a half-second blank screen included. Press any key#R $4[A,B] $4[C,D] $4[B,A] $4[D,C] $4[Q,F] $4[T,X] Done. Press any key to exit.#R

MCDF_B01.IN: Times the overhead in 200 calls to blank macro

@CPress any key to time the overhead in 200 calls to a blank macro#R $$1$$ #Y[2,0] $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 $1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1$1 #Y[2,1] @1010Two hundred calls took $SV5 milliseconds @1210Press any key to time the overhead in @1310two hundred calls with one argument.#R@C $$2[x]$$ #Y[2,0] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] $2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1]$2[1] #Y[2,1] @1010Two hundred calls took $SV5 milliseconds @1210Press any key to exit#R

Examples:

input

$$aPress <return> to continue: #R$$
...
$a

cogsys

Defines the macro a. At the $a macro call, Cogsys prints `Press <return> to continue:' and waits for keypress.

input

$$1assigned$$
$$2given$$
$$a[name,num,mac]hi, name!
You have been $mac number num.$$
...
$a[usman,3,2]#R

cogsys

Defines three macros, 1, 2, and a. The macro a takes three arguments, `name', `num', and `mac'. The `$a' call invokes the macro with the values `usman', `3' and `2', respectively. The expanded $a macro is:

hi, usman! You have been $2 number 3.

When Cogsys reaches the `$2', it will expand that into the the body of the $2 macro, `given'. Thus, the final output of Cogsys:

hi, usman! You have been given number 3.

This illustrates how parametric macros and nesting are a powerful combination that let you describe complex strings with only a few characters.