Fundamentals: Variables

A variable is a place-holder, a symbol that represents a quantity. It is an object that holds data and is uniquely named by the programmer. It holds the data that is assigned to it, until the data is changed or the variable is removed. Variables offer a way to indirectly store and pass data to macro functions or commands.

Variables are the cornerstone of all computer languages. It does not matter what programming language you are using, there will always be variables.

Before a variable can be used, it must be declared. When a variable is declared it is created in computer memory, a name is given to it, and the type of data it will hold is defined. Since a variable must be declared before it is used the declaration statement must precede the first use of the variable name in a macro.

When declaring a variable, you define the type of data that variable will contain. SmartCAM supports three data types, so there are three different declaration commands.

Data Types

The following are the three SmartCAM data type and the three related variable declarations.

A DECIMAL variable contains a real number, a number with a decimal fraction. An INTEGER variable contains a whole number, a number with no fraction. A STRING contains a series of text characters; such as a path, filename, or message to display to the user.

The declaration contains two parts, the data type with a colon separator, and the variable name. All SmartCAM variable names begin with a pound (#) character. This # character is a designator that tells SmartCAM that the item being referenced is a variable.

Variable Names

When a variable is declared, it is given a name. This name is the handle used to access the data stored in the variable. There are a couple of restrictions on what can be used as a variable name.

Additionally, while these are not language rules, the following are some variable naming recommendations.

You must declare a String variable before you can use it. While it is possible to just use numeric variables, meaning not declare them first, this is bad programming practice and should be avoided.

If you attempt to use a variable, as a macro command parameter or just typing it into a dialog/panel's input fields, SmartCAM will display a dialog box requesting the value for the variable. Enter the value. Each subsequent time that you use the variable name, SmartCAM will use the value you provided.

Variables As Macro Parameters

Variables can be substituted for actual final values, when used as parameters for macro commands or even directly in the user interface. This ability provides a lot of opportunities and options. For example, it can be used to create a macro used to handle family of parts (that is, parts with similar geometry). Instead of hard-coding the coordinate information, for example, use variables. The following example creates a rectangle.

START_PROF[XE=#XS2,YE=#YS2,LV=#LV]
LINE_PROF[TI=0,ZE=#LV,DS=#D1,N=#AN,SS=2,SE=0,SP=2]
LINE_PROF[TI=0,ZE=#LV,DS=#D2,AN=#AN+90,SS=2,SE=0,SP=2]
LINE_PROF[TI=0,ZE=#LV,DS=#D1,AN=#AN+180,SS=2,SE=0,SP=2]
LINE_PROF[TI=0,ZE=#LV,DS=#D2,AN=#AN+270,SS=2,SE=0,SP=2]

In this example #LV, #D1, #D2, and #AN are user variables, in a macro that creates rectangles of different sizes and at different angles. The first time, SmartCAM will prompt you for the value of each variable, as they are encountered. You could modify the macro to actually prompt the user for the values for each of the variables. Or even, create a UI using Visual CTK, with input prompts and labels for the variables.

Scope

A variable's scope refers to when and where a variable can be accessed. All variables in SmartCAM have a global scope. It does not matter where they are defined, once defined they are available to all subsequent macros. Once defined the variable will persist even after the macro is finished running.

To see this, from your SmartCAM application run Macro - Variables. This opens the Macro Variables dialog which shows all simple SmartCAM user variables, their data type, and current contents.

Once defined a variable will continue to persist until one of the following:

Arrays are an exception to this. An array's scope is the duration of the macro, when the macro ends, all arrays are removed. Unlike the simple INTEGER, DECIMAL, and STRING data types, the variables will not remain and cannot be queried from the Macro - Variables dialog box.

Using Variables

The following examples show how variables are used. Each MCL fragment is a small macro that can be run. Simply copy and paste the text into a text file and save the file with an .MCL extension. Once the macro is saved, run the macro from your SmartCAM application. Select Macro - Execute, type in or use File Select to locate the MCL file. Then press the Accept button to run it.

Hello World

There is a long standing tradition in the computer world that the first program shown in any programming book, tutorial, or classroom lesson is called "Hello World." This is an extremely simple program that, when run, just displays the text welcome, "Hello World."

Here is the Hello World program.

STRING:#GREETING
#GREETING="Hello World!"
PAUSE[TX=#GREETING]

When run, a message box will be display that looks similar to:

In this example, a STRING variable named GREETING is declared. The next macro command tells the variable #GREETING to store the string literal "Hello World!" Finally, a macro command called PAUSE[] is run that displays the contents of the variable.

Literals

When programming, a Literal is a letter, number, symbol, or string that stands for itself. In the previous example the text string "Hello World!" was a literal. You can rewrite the first example macro without using variables and get the same results.

Here is the Hello World macro written without using variables, but using a literal string.

PAUSE[TX="Hello World!"]

When run, you will get the same results as the original macro. Notice that the TX parameter of the PAUSE[] macro command is looking for a string. The string can be a string literal, as in the second example. Or a string variable, as in the original example.

Assigning Data To Variables

The following shows various ways data can be assigned to a variable.

DECIMAL:#DEC
#DEC=1.5
PAUSE[TX="DEC=" + FMT(#DEC, "D3.4")]

As previously covered, the TX parameter of the PAUSE[] macro command is expecting a STRING. However, the variable #DEC is not a STRING, it is a DECIMAL. This means you cannot pass #DEC to the TX parameter. The macro function FMT() converts the DECIMAL number into a STRING. The original numeric variables are unchanged.

When you run this macro, a message will appear as in the earlier examples. The text of the message will display:

DEC=1.5

In many cases, you can assign the original data to a variable when you declare it.

DECIMAL:#DEC = 1.5
PAUSE[TX="DEC=" + FMT(#DEC,"D3.4")]

This, fundamentally, does the same thing as the previous example. It declares the variable #DEC and assigned the value 1.5 to it. When you run this macro you will get the same output as above.

Data can be assigned to INTEGER and STRING variables in the same fashion. When working with STRING data remember it must be surrounded by quotes. When converting INTEGER data into a string, use the ITOA() function.

DECIMAL:#DEC = 1.5
INTEGER:#INT = 2
string:#str = "A String"
PAUSE[TX="DEC=" + FMT(#DEC,"D3.4") + " and INT=" + ITOA(#int) + " and STR=" + #STR]

When run the above macro will create a message box containing:

DEC=1.5 and INT=2 and STR=A String

Notice how the macro used both upper and lower case for variable names and macro declarations. For example the variable #STR is declared with lower case and used in upper case and the inverse is true for #INT. SmartCAM is not case-sensitive.

Including Variable Declarations

In some cases, it is helpful to split up macros into several different .MCL files. These macros are then called from a main macro file, using the MAC_EXE[] command. In these cases it is often helpful to declare all variables, used by all the different related macros, in a single macro file.

This variable declaration macro is then called at the start of the main macro. This establishes all the needed variables and their data types in a single easy to edit package.

The macro system has a special command for just such purposes, it is the INCLUDE statement.

The "include" statement is followed by a quoted path and filename of the macro file to include. This included file is treated like inline code. Example:

Variable Definition Macro: VARDEF.MCL

INTEGER:#IVAR
STRING:#SVAR

Main Macro: MAIN.MCL

// Include the needed variables
INCLUDE "C:\\MACROS\\VARDEF.MCL"
#IVAR=1
#SVAR="Text String"

When the macro is parsed, the file referenced by the INCLUDE statement is treated like inline code. To the macro parser, MAIN.MCL looks like:

// Include the needed variable
INTEGER:#IVAR
STRING:#SVAR
#IVAR=1
#SVAR="Text String"

The format for the INCLUDE statement is the "include" keyword followed by a quoted string that contains the path and filename of the macro file to include. Like other path strings in the SmartCAM macro system, backslashes must be doubled: C:\\PATH, not C:\PATH.

The path\filename can either be an absolute path or a relational path. If it is a relational path, the path relation is based on the location of the currently running macro.

The ability to include a macro is designed to support easy declaration and definition of macro variables, the included macro file should only contain variable declarations. However, any macro code that exists in the included file will be treated like in-line code, in the calling macro. Having macro code, other than variable declarations, is not recommended but it is also not excluded.

Evaluation Order

When making variable assignments, SmartCAM will solve the expression on the right-hand side of the assignment statement first. After the evaluation is complete, it then assigns the data to the variable on the left-hand side of the assignment character (the = sign). This allows the macro to use the same variable on both sides of an assignment. Example:

INTEGER:#COUNTER
#COUNTER=1			// Counter now equal to 1
#COUNTER=#COUNTER+2		// Counter now equal to 3

This ability is important when the programmer starts working with loops and branching and needs to keep a running total or counter of various activities or values.

Related Topics

Expressions

Macro Development Fundamentals Overview

SmartCAM Automation Overview