Control Statements

MACRO OBJECTS

Although the 3D objects you may need can always be broken down into complex or primitive elements, sometimes it is desirable to define these complex elements specifically for certain applications. These individually defined elements are called macros.

CALL

CALL macro_name_string [,parameter_list]

CALL macro_name_string [,] PARAMETERS [name1=value1 , ... namen=valuen][[,]

RETURNED_PARAMETERS r1, r2, ...]

CALL macro_name_string [,] PARAMETERS ALL [name1=value1 , ...

namen=valuen][[,][RETURNED_PARAMETERS r1, r2, ...]

CALL macro_name_string [,]PARAMETERS value1 or DEFAULT [, ... valuem or DEFAULT]

Macro names cannot be longer than 31 characters.

Macro names can be string constants, string variables or parameters. String operations cannot be used with a macro call as a macro name.

Warning: If string variables or parameters are used as macro names, the called macro may not be included in the archive project, unless the “Include All Parts of Loaded Libraries” option is checked.

The macro name must be put between quotation marks (“,’,`,´,”,’,“,‘), unless it matches the definition of identifiers, i.e., it begins with a letter or a ‘_’ or ‘~’ character and contains only letters, numbers and the ‘_’ and ‘~’ characters. Otherwise, the quotation marks used in the CALL statement must be the same at the beginning and at the end, and should be different from any character of the macro name.

A macro name itself also can be used as a command, without the CALL keyword: macro_name [parameter_list]

macro_name PARAMETERS [name1=value1, ... namen=valuen] macro_name PARAMETERS ALL

The first type of macro call can be used with simple GDL text files as well as any library part, on the condition that its parameter list contains only single-letter parameters (A ... Z). This form of macro call can be used for compatibility with previous versions, but we recommend the second type. The meaning of the parameter list is the following: the value of parameter A will be the first value in the list, the value of parameter B will be the second value, and so on. If the (library part) macro does not have a single-letter parameter corresponding to the value, interpretation will continue by skipping this value, but you will get a warning from the program. No string type expressions are allowed with this method.

The second type can be used with full featured library parts or plain GDL text files. After the PARAMETERS keyword you need to list the parameter names of the called macro in any sequence, with both an ‘=’ sign and a value for each. You can use string type expressions here, but only give a string value to string type parameters of the called macro. Array parameters have to be given full array values. If a parameter name in the parameter list cannot be found in the called macro, you will get an error message. Parameters of the called macro that are not listed in the macro call will be given their original default values as defined in the library part called as a macro.

Control Statements

The third type can only be used with full featured library parts. In this case there is no need to specify the parameters one by one; all parameters of the caller are passed to the called macro. For a parameter of the macro which cannot be found in the caller, the default value will be used. If parameter values are specified one by one, they will override the values coming from the caller or parameters of the called macro left to be default. Macros can return parameters also in this case. At the caller's side, returned values can be collected using the RETURNED_PARAMETERS keyword followed by a varialble list. The returned values will be stored in these variables in the order they are returned in the called macro. The number and the type of the variables specified in the caller and those returned in the macro must not match. If there are more variables specified in the caller, they will be set to 0 integer. Type compatibility is not checked: the type of the variables specified in the caller will be set to the type of the returned values. If one of the variables in the caller is a dynamic array, all subsequent values will be stored in it.

See the syntax of returning parameters at “END / EXIT” on page 214.

A GDL macro has its own environment which depends on its calling order. The current values of the

MODEL, RADIUS, RESOL, TOLER, PEN, LINE_TYPE, MATERIAL, FILL, STYLE, SHADOW

options and the current transformation are all valid in the macro. You can use or modify them, but the modifications will only have an effect locally. They do not take effect on the level the macro was called from.

Giving parameters to a macro call means an implicit value assignment on the macro’s level. The parameters A and B are generally used for resizing objects.

The fourth type of macro call can also be used only with full featured library parts. In this case the actual parameter values have to be specified one by one in the order they are present in the called library part, no value can be missed, except from the end of the list. Using the DEFAULT keyword in place of a parameter actual value means that the actual value will be the default value stored in the library part. For the missing values defaults will be used automatically (the number of actual values m can be smaller than the number of parameters). When interpreting this kind of macro call there is no need to find the parameters by name to assign them the actual value, so even though it is more uncomfortable to use than the previous ones, a better performance can be achieved.

Examples:

CALL "leg" 2, , 5 ! A = 2, B = 0, C = 5 leg 2, , 5

CALL "door-1" PARAMETERS height = 2, a = 25.5, name = "Director"

CALL "door-1" PARAMETERS

! use parameter default values "door-1" PARAMETERS

In summary: whenever you do not need a parameter with a long name or of string type, using the text type GDL can be sufficient. This type of GDL can only be called with the first type of macro call, since it does not have a parameter list. On the other hand, if you do not wish to limit your macro parameter names to letters from A to Z, or if you want to include strings in the parameter list, your macro must be a library part and called according to the second type of GDL syntax.