An actuallist specifies the parameters M passes to the invoked routine. The actuallist contains a list of zero or more parameters enclosed in parentheses, immediately following a DO or extrinsic function.

An actuallist:

Example:

GTM>DO MULT(3,X,.RESULT)

This example illustrates a DO with parameters. The actuallist contains:

An actualname starts with a leading period (.) delimiter, followed by an unsubscripted local variable name. Actualnames identify variables that are passed by reference, as described in a subsequent section. While expressions in an actualname are evaluated when control is transferred to a formallabel, the variables identified by actualnames are not; therefore, they do not need to be defined at the time control is transferred.

A formallist specifies the variables M uses to hold passed values. A formallist contains a list of zero or more parameters enclosed in parentheses, immediately following a label.

A formallist:

Example:

MULT(MP,MC,RES)
SET RES=MP*MC
QUIT RES

In this example, illustrating a simple parameterized routine, the formallist contains the following items:

An example in the section describing "Actuallists" shows an invocation that matches this routine.

A label followed by a formallist is called a formallabel.

M performs an implicit NEW on the formallist names and replaces the formallist items with the actuallist items.

M provides the actuallist values to the invoked procedure by giving each element in the formallist the value or reference provided by the corresponding element in the actuallist. M associates the first name in the formallist with the first item in the actuallist, the second name in the formallist with the second item in the actuallist and so on. If the actuallist is shorter than the formallist, M ensures that the formallist items with no corresponding value are in effect NEWed. If the formallist item has no corresponding item in the actuallist (indicated by two adjacent commas in the actuallist), that item in the formallist becomes undefined.

If the actuallist item is an expression and the corresponding formallist variable is an array, parameter passing does not affect the subscripted elements of the array. If an actualname corresponds to a formallist variable, M reflects array operations on the formallist variable, by reference, in the variable specified by the actualname.

M treats variables that are not part of the formallist as if parameter passing did not exist (i.e., M makes them available to the invoked routine).

M initiates execution at the first command following the formallabel.

A QUIT command terminates execution of the invoked routine. At the time of the QUIT, M restores the formallist items to the values they had at the invocation of the routine.

A QUIT from a DO does not take an argument, while a QUIT from an extrinsic must have an argument. This represents one of the two major differences between the DO command with parameters and the extrinsics. M returns the value of the QUIT command argument as the value of the extrinsic function or special variable. The other difference is that M stacks $TEST for extrinsics.

For more information, see “Extrinsic Functions” and “Extrinsic Special Variables”.

Example:

SET X=30,Z="Hello"
DO WRTSQR(X)
ZWRITE
QUIT
WRTSQR(Z)
SET Z=Z*Z
WRITE Z,!
QUIT

Produces:

900
X=30
Z="Hello"

M passes the actuallist values to the invoked routine using two parameter-passing mechanisms:

A call-by-value passes a copy of the value of the actuallist expression to the invoked routine by assigning the copy to a formallist variable. If the parameter is a variable, the invoked routine may change that variable. However, because M constructs that variable to hold the copy, it deletes the variable holding the copy when the QUIT restores the prior formallist values. This also means that changes to the variable by the invoked routine do not affect the value of the variable in the invoking routine.

Example:

SET X=30
DO SQR(X)
ZWRITE
QUIT
SQR(Z)SET Z=Z*Z
QUIT

Produces:

X=30

A period followed by a name identifies an actualname and causes a call-by-reference.

A call-by-reference passes a pointer to the variable of the invoked routine so operations on the assigned formallist variable also act on the actualname variable. Changes, including KILLs to the formallist variable, immediately have the same affect on the corresponding actualname variable. This means that M passes changes to formallist variables in the invoked routine back to the invoking routine as changes in actualname variables.

Example:

SET X=30
DO SQR(.X)
ZWRITE
QUIT
SQR(Z)SET Z=Z*Z
QUIT

Produces:

X=900

The standard does not provide for indirection of a labelref because the syntax has an ambiguity.

Example:

DO @X(1)

This example could be:

GT.M processes the latter interpretation as illustrated in the following example.

Example:

The syntax:

SET A(1)="CUBE",X=5
DO @A(1)(.X)
WRITE X,!
QUIT
CUBE(C);cube a variable
SET C=C*C*C
QUIT

Produces the result:

125

GT.M follows analogous syntax for routine indirection:

DO ^@X(A) invokes the routine specified by X(A).

DO ^@(X)(A) invokes the routine specified by X and passes the parameter A.

DO ^@X(A)(A) invokes the routine specified by X(A) and passes the parameter A.