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.
- DECIMAL - Declaration DECIMAL:#VARNAME
- INTEGER - Declaration INTEGER:#VARNAME
- STRING - Declaration STRING:#VARNAME
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.
- Acceptable characters are letters (a to z), digits (0 to 9) and underscore (_).
- All variable names must start with a letter.
#A1
is good, while#1A
is not valid. - Variable names have a 12 character size limit.
- Variable names are not case-sensitive, so
#S
and#s
reference the same variable.
Additionally, while these are not language rules, the following are some variable naming recommendations.
- Never give a variable the same name as a macro command or function; it will cause confusion.
- Give variables descriptive names. For example the name
QRPT12
gives no indication of what the variable is for, however,XPOSN
suggests the variable is a holder for the X-axis position. - Preface variables with the data type. For example
SMSG
begins with an "S" so it is aSTRING
variable. The variableICOUNTER
is anINTEGER
, andDXPOSN
is aDECIMAL
. For simple macros with few variables, this is not likely to be needed. But when working with large, complex macros a little reminder of the data type may save some time and prevent some mistakes.
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:
- Macro command
VAR_REMOVE
orVAR_REMOVE_ALL
is run. - The Remove or Remove All button on the Macro Variables dialog is triggered.
- SmartCAM is exited.
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