Fundamentals: Functions and Commands

A macro command or function is a single macro command which performs a specific task. The macro statement which selects and groups all elements on a specific layer (LAYER_GRP[]) is an example of a macro command. A macro statement completes a specific task, in the previous example it selects all elements on a given layer and adds them to the active group.

SmartCAM supports two types of macro statements: functions and commands.

A macro "command" does not return a value and is generally very closely related to SmartCAM control panel or dialog box. When you use Macro - Record you are recording macro commands.

Commands use square brackets ([]) to hold function parameters and each parameters is associated with a function parameter variable. Example:

LAYER_GRP[LY=1, AR=0]

In this example, the parameters - LY and AR - are enclosed by square brackets. The function parameter variable "LY" is set to "1" and the "AR" parameter is set to "0."

"Functions" are slightly different than Commands. Long time SmartCAM users will know these as "Snap" functions. However, the breadth of these functions has long expanded past simple snapping. Macro Functions return a value from the command, they use parenthesis to contain parameters, and they are generally not associated with a given SmartCAM User Interface component. Additionally, the parameters for a function are not associated with a specific parameter variable.

Functions are commonly used to make Macro Commands more flexible. An example of a macro function is:

#CLEARANCE = CLR(1)

In this example the CLR() function is called. It returns the clearance value for the element number provided as a parameter - in this case "1." The clearance for element 1 is returned to the calling macro and in this example stored in the variable #CLEARANCE.

A parameter is the data passed to a macro command or function that gives the macro procedure the information it needs to successfully complete its task.

In the above LAYER_GRP[] macro command example, the two parameters are the layer number to group and whether the function should add or remove the elements from the active group. Without this information a call to LAYER_GRP[] is meaningless, since it doesn't have enough information to run. In practice, calling a macro command or function without the required parameters will generate an error.

Not all macro commands or functions require parameters. For example the macro function TOTEL(), which returns the total number of elements in the current process model, does not need nor have a parameter value. It is unnecessary for this function. The same applies to the FULL[] macro command, which is the same as View - Full and adjusts the graphics view to show all visible elements.

All parameters have a Data Type. When passing data as a parameter the data being sent must be of the correct type, otherwise an error is generated. Example:

DECIMAL:#ELMT=1.5
INTEGER:#CLEAR
//	Get Clearance value for element
#CLEAR=CLR(#ELMT)

This macro will not work; it is an example of why parameters have a specific data type. The CLR() function expects an integer as the parameter and returns a decimal value. In the above example, the data types have been reversed.

Using this example, the parameter fails because a decimal parameter makes no sense. What is element 1.5?

Additionally, using an integer to contain the return value will not work either. If the clearance returned is 0.5, it would be stored in the Integer as 0.

Always use the correct data type for each parameter and for the return value.

Note: when the parameter is an element number, you can substitute the element's name if there is one. For named elements, you can use the name in quotes instead of the number. For example, if element #1 is named "PSTART". You can use either of the following:

#CLEAR=CLR(1)

or

#CLEAR=CLR("PSTART")

Parameter Order

When working with macro commands, the parameter order is not very important. Since in a command, each parameter is prefaced by a function parameter variable; for example LY= in the LAYER_GRP[] command.

However, for macro functions the order is very important. For example, the macro function CPX() which returns the X axis value of a given control point in a spline or polyline. The parameters for this function are: Element, then Control Point number. Example:

#XVAL=CPX(1, 2)

This says return the X-axis value for the second control point in element number 1. If you transpose the values you are instead asking for control point 1 in element 2 - which is not the correct evaluation.

Macro functions return a value. The CPX() function returns the X-axis value for a given control point in a selected spline or polyline. The value can be stored in a variable, used as part of a Branching evaluation, or passed as a parameter to another function.

Stored in Variable

When storing the results of a return value in a variable, make sure the variable data type matches the return value data type. For example, if the return value is a STRING, don't try to assign it to a DECIMAL variable.

An example of storing a return value in a variable.

STRING:#FPATH		// path and filename of current process model file
#FPATH=SHPFILE()

The SHPFILE() function returns a string containing the path and filename of the current process model file. The above example stores this returned value in the STRING variable #FPATH.

Used in Branching Evaluation

The return value from a function can be used as an operand to a branching evaluation. Example:

// If element type is ARC display message
IF(TYP(1) = 3) THEN
	PAUSE[TX="It is an ARC."]
ENDIF

The TYP() macro command takes an integer as a parameter. The parameter is the element number. It returns an integer, where the integer is a value that gives the element type: i.e. point, line, arc, helix, polyline, etc.

The above example, checks the return value of TYP, if it is an ARC, it displays a message, otherwise it just continues running.

In the above example, the element type returned is not preserved. If the program needs the value again, it should be stored in a variable. Example:

INTEGER:#ELTYPE
			
#ELTYPE=TYP(1)		// get element type
IF(#ELTYPE = 3) THEN
	PAUSE[TX="It is an ARC."]
ENDIF

Parameter to another Function

It is possible to nest functions within functions; where the return value of the innermost function is the parameter to the next higher level. While this makes for tighter macro code, it is more difficult to debug.

//	Get path to current process model, without filename
STRING:#PMPATH		// holds path
#PMPATH = GET_PATH(SHPFILE())

GET_PATH() returns the path part of a path/filename.ext string. SHPFILE() returns a path/filename.ext of the current Process Model. In this example, the return from SHPFILE() is passed directly to the GET_PATH() function, and the results stored in #PMPATH.

A function signature is a description of a macro command or function's return value and parameters. It describes the data type used and the parameter order in the parameter list. When SmartCAM compiles a macro it checks the supplied parameters and variable used for the return value against the function signature. If they do not match, then an error is generated.

An example of a Function Signature is:

INTEGER TYP(INTEGER)

This is the function signature for the TYP() macro function, which takes an integer (the element number) as a parameter and returns an integer.

The Learning SmartCAM topics that contain the full list of Macro Commands and Macro Functions includes function signatures for all macro commands and functions. Single letter initials are used instead of spelling out the full data type. Example:

I=TYP(I)

As before, TYP() takes an Integer (I) parameter and returns in Integer.