MC-Basic Language Fundamentals

See Also

• MC-Basic Commands - a list of all MC-Basic commands
• MC-Basic Constants - a list of keywords that can be used instead of explicit numeric values for parameters that have a discrete range of possible values
• MC-Basic Operators - the different types of operators and their relative precedence
• MC-Basic Programs - projects and tasks
• MC-Basic Libraries - reusable code for subroutines and functions
• MC-Basic Generic Elements - reusable code for setup or query properties
• MC-Basic C-Interface
• Error Codes

Introduction

The softMC is programmed in MC-Basic, a version of the BASIC programming language enhanced for multitasking motion control. If you are familiar with BASIC, you already know much of MC-Basic.

To develop your application on the softMC, you must install ControlStudio.

Command Reference Format

All MC-Basic commands are presented in the list of MC-Basic Commands. The reference entry for each command contains the information needed for correct use of the command or property. Each entry for a command or property contains all or most of the following elements:

Description	A description of the command or property.
Short Form	Where applicable, a short form of the longer command can be used to simplify typing the command or property name. In such instances, the short form is denoted. The short form of a command or property name may be used interchangeably with the long version.
Syntax	In describing the syntax of an instruction, different notations are used.
< >	Field to be filled by user. For example, ABS ( <expression> ) indicates that <expression> is the user\’s data.
\{ \}	Optional data. Many instructions have optional fields, which are used to override default values. For example, the VelocityCruise property is optional within a Move command. However, there is an exception to this rule, in that \{ \} are used for vector notation. When the optional data may be repeated, an asterisk (\*) is used to indicate this.
|	Or. Indicates that either one of the values may be used.
Availability	Various versions of the firmware add new features, and often significantly change the syntax or behavior of commands and properties. The attribute Availability included in the descriptions denotes the applicability of each function (command, property)to the specified version of the firmware.
Type	Refer to the section Data Types, below.
Range	Range of valid values
Units	When parameter values imply dimensional units of measurement, these units are specified in the description of the command or property where they apply.
Default	Default value
Scope	Instructions can be executed from any of three contexts: the configuration file (CONFIG.PRG), the terminal, and within a task. Not all instructions can be executed from all three contexts; their scope of operation is limited. For each instruction, the scope of operation is defined.
Limitations	Even when an instruction can be executed in a given context, there may still be limitations on its use. For example, a MOVE command can be executed from within a task, but there is a limitation in that the motion element being moved must first be attached to the task by the ATTACH command.
Examples	Examples of use
See Also	Links to related commands

Instructions

Instructions are the building blocks of BASIC. Instructions set variables, call functions, control program flow, and start processes such as events and motion. In this documentation, the terms instruction and command are used interchangeably.

Syntax is the set of rules that must be observed to construct a legal command (that is, a command the softMC can recognize).

MC-Basic is line-oriented. The end of the line indicates the end of the instruction. Whitespace (i.e., spaces and tabs within the statement line and blank lines), is ignored by the BASIC interpreter. You can freely use indentation to delineate block structures in your program code for easier readability. The maximum allowed length of a line is 80 characters.

MC-Basic is case insensitive. Commands, variable names, filenames, and task names may be written using either upper case or lower case letters. The only exception is that when printing strings with the “Print” and “PrintUsing” commands, upper and lower case characters can be specified.

Syntax uses the following notation:[ ]indicates the contents are required{ } indicates the contents are optional for the command

Example lines of text are shown in Courier type font and with a border:

X = 1

Types of Instructions

There are many types of instructions: comments, assignments, memory allocation, flow control, task control, and motion.

Comments allow you to document your program. Indicate a comment with either the Rem command or a single apostrophe ('). You can add comments to the end of an instruction with either Rem or an apostrophe.

Rem This is a comment
' This is a comment too.
X = 1 'This comment is added to the line X = 1X = 1 REM This is a comment too

Use comments generously throughout your program. They are an asset when you need support from others and they avoid confusing code.

Declarations allocate softMC memory for variables and system elements (groups, cam tables, etc.). This might be a simple type as an integer, or a complex structure as a cam table.

Assignments Assignment instructions assign a new value to a variable.

The syntax of an assignment is [Lvalue] [=] [expression]

For example:

X = Y + 1

The term, Lvalue, is a shorthand notation, which indicates the value to the left of the equals sign. Valid Lvalues are variables or writable properties, which can be assigned. Expressions can be variables, constants, properties and function calls, as well as various combinations of them in arithmetic and logical statements . An exception to this rule is generic elements’ assignment, at which the right side of the equal sign is not an expression, but an axis or a group (either real or generic), and Lvalue is a generic elements. If you assign a Double (floating point) value (expression, variable or constant) to a Long variable, the fractional portion of the double value is truncated, and the integer portion is assigned to the long variable. To query a variable or expression from the ControlStudio terminal window, use the PRINT or ? command:

PRINT 1/100
? X1

MC-Basic also provides the standard PRINTUSING (PrintU) command for formatted printing.

Commands for flow control change the way your program is executed. Without flow control, program execution is limited to processing the line immediately following the current command. Examples of flow control include GOTO, FOR…NEXT, and IF…THEN.

MC-Basic is a multitasking language in which many tasks can run concurrently. Generally, tasks run independently of each other. However, tasks can control each other using inter-task control instructions. One task can start, idle, or terminate another task.

Most commands are started and finished immediately. For example:

x = 1 ' this line is executed completely…
y = 2 ' …before this line is started

For general programming, one command is usually finished before the next command starts. Effects of these commands do not persist beyond the time required to execute them. However, the effects of many other commands persist long after the execution of the command. In general programming, for example, the effects of opening a file or allocating memory persist indefinitely. In real-time systems, persistence is more complicated because the duration of persistence is less predictable.

Consider a command that specifies a 1,000,000 counts move on an axis named, A2:

Move A2 1000000.0
Y = 2

The softMC does not wait for the 1,000,000 move to be complete before executing Y=2. Instead, the first command starts the motion and then the softMC continues with the next line (Y = 2). The move continues well after the move command has been executed.

Persistence can affect programs. For example, you may not want to start one move until the previous move is complete. In general, you need access to persistent processes if you are to control your program according to their state of execution. As you will see later, MC-Basic provides this access.

Line Concatenations

Performs concatenation of program or command line input. Useful when input string is longer than translator buffer (128 chars).

Symbol

\

Example

A = B + \
C + D

Is equal to:

A = B + C + D

Constants and Variables

All constant, variable and system element names must start with an alphabetical character (a-z, A-Z) and may be followed with up to 31 alphabetical characters, numbers (0-9) and underscores (“_”). Keywords may not be used as names.

Constants

Constants are numbers that are written as ordinary text characters,

See Also: MC-Basic Constants

Variables

You must declare a variable in MC-Basic before you can it. In the declaration, you define variable name, scope and variable type. MC-Basic supports Long for integer values, Double for floating point values, and String for ASCII character strings.

Besides these basic types, MC-Basic also supports Structure-like variables and some MC-Basic specific types, such as points (Joints and Locations), generic motion elements (Axes and Groups) and UEAs (user error assertions-Errors and Notes).

DeleteVar deletes a global variable. Since variable name can include wildcards, a single DELETEVAR can be used to delete more than one variable.

DeleteVar int1
DeleteVar int* ' Deletes all variables starting with int

Current values of global variables (both scalar and arrays) can be stored in a Prg file, in assignment format, within an automatically executable Program Continue…Terminate Program block. Obligatory parameters of SAVE are the name of storage file, and type of stored variables (could be all types). Optional parameters are robot type (for point variables), variable name (which may include wildcards) and mode of writing to storage file (overwriting or appending). Variable types available for storage through SAVE are longs, doubles, strings, joints and locations, but not structures, user-defined exceptions nor generic motion elements.

Save File = “IntFile.Prg” Type = All VariableName = “int*”
‘ Save all variables starting with int in IntFile.Prg (overwrite file)
Save File = “Points.Prg” Type = Joint RobotType = XYZR Mode = Append
‘ Append all joint-type points with XYZR robot-type to Points.Prg file

Scope defines how widely a variable can be accessed. The broadest scope is global. A global variable can be read from any part of the system software. Other scopes are more restrictive, limiting access of variables to certain sections of code. MC-Basic supports three scopes: global, task, and local. Task variables can be read from or written to anywhere within the task where it is defined, but not from outside the task. Local variables can only be used within their declaration block, i.e. program, subroutine or function blocks. The scope of a variable is implicitly defined when a variable is declared using the keywords: Common, Shared, and Dim.

Global variables can be defined within the system configuration task, Config.Prg, within a task files (Prg files), before the program block, within library files (Lib files), before the first subroutine or function block, or from the terminal window of ControlStudio. To declare a variable of global scope use the Common Shared instruction.

Task variables are defined within a task or a library. To declare a variable of task scope use the Dim Shared instruction.

	NOTE
	All Dim Shared commands must appear above the Program statement in task files. In library files, all Dim Shared commands must appear above the first block of subroutine or function. The values of variables declared with Dim Shared persist as long as the task is loaded, which is usually the entire time the unit is operational. This is commonly referred to as being static.

Local variables are defined and used within a program, a subroutine, or a function. To declare a local variable, use the Dim instruction. The Dim command for local variables must be entered immediately below the Program, Sub, or Function statement. Local variables cannot be declared within event blocks, and events cannot use local variables declared within the program.

Data Types

Numeric Data Types

MC-Basic has two numeric data types: Long and Double. Long is the only integer form supported by MC-Basic. Long and Double are MC-Basic primitive data types.

Type	Description	Range
Long	32 bit signed integer	-2,147,483,648 (MinInteger) to 2,147,483,647 (MaxInteger)
Double	Double precision floating point (about 16 places of accuracy)	±1.79769313486223157 E+308

String Data Type

MC-Basic provides the string data type which consists of a string of ASCII-coded characters. MC-Basic strings are dynamic. Reallocation of memory for new strings is preformed through a simple assignment of the string variable, and there is no need to specify the length of the new string. A full complement of string functions is provided to create and modify strings.

Type	Description	Range
String	ASCII character string (no string length limit)	0 to 255 (ASCII code)

String parameters are based on the 8-bit ASCII character code set, which comprises 255 character codes, with code values from 1 to 255.

UTF-8

@@@@

See Also: LINK TO NEW PAGE

@@@@

In UTF-8 supporting versions (4.5.1 and higher), range was expanded to character codes from 0 to 255, since NULL characters are no longer cut out from strings. If string functions are used with parameter values outside the specified range, the behavior of the function may vary (e.g., the function may return an error message, the function may return a value different from the correct value, or the function may return the correct value). String values must be delimited by double quotes (“string value”). The maximum number of characters allowed in a string is limited only by the amount of free memory space.

Point Data Types

See Also: NEW PAGE "POINTS"

MC-Basic has two point data types: JOINT and LOCATION. A point variable is related to a robot type. Robot type examples: XY – two axes XY table, XYZ – three axes XYZ system, XYZR – three cartesian axes + roll, etc.

Type	Description	Range
Joint	A set of 2-10 double precision floating point joint (motor) coordinates	±1.79769313486223157 E+308 for each coordinate
Location	A set of 2-10 double precision floating point cartesian coordinates	±1.79769313486223157 E+308 for each coordinate

@@@@@@

INSERT HERE A DESCRIPTION ABOUT "GENERIC POINTS" AND A LINK TO NEW PAGE "GENERIC POINTS"

@@@@@@

Structures

MC-Basic enables definition of structure-like data types, composed of a limited number of long, double, string and point (joint and/or location) scalar and array elements. Array elements can have only a single dimension. Name of structure type and composition of elements are defined by the user within configuration file (Config.Prg).

Type	Description	Range
0-100 longs	32 bit signed integer	-2,147,483,648 (MinInteger) to 2,147,483,647 (MaxInteger)
0-100 doubles	Double precision floating point (about 16 places of accuracy)	±1.79769313486223157 E+308
0-100 strings	ASCII character string (no practical limit to string length)	0 to 255 (ASCII code)
0-100 points (joints and/or locations)	A set of 2-10 double precision floating point coordinates	±1.79769313486223157 E+308 for each coordinate
0-10 long arrays	1-32,767 32 bit signed integers	-2,147,483,648 (MinInteger) to 2,147,483,647 (MaxInteger)
0-10 double arrays	1-32,767 double precision floating point elements	±1.79769313486223157 E+308
0-4 string arrays	1-32,767 ASCII character strings	0 to 255 (ASCII code)
1-2 point (joints and/or locations) arrays	1-32,767 sets of 2-10 Double precision floating point coordinates	±1.79769313486223157 E+308 for each coordinate

@@@@@@@@@@@@@@@@@@ Template:border="0" cellpadding="5" cellspacing="0" valign=”top”

End If

where:

If…Then must be followed by at least one statement.

Else is optional, but if present must be followed by at least one statement.

There is no Else if. If you use an If after an Else, you must place the If on a new line.

Select…Case is an extension of If…Then. Anything that can be done with Select…Case can also be done with If…Then. Many times, Select…Case simplifies programming logic.

On the first line of a Case block of commands, you specify the variable or expression you want tested. For example:

Select Case I

Tests the variable I for a range of conditions.

You can also select expressions:

Select Case I - M/N

After you have specified the variable or expression, list one or more values or value ranges that the variable can take. There are four ways you can specify cases:

Exact Value

Logical Condition

Range

Else

The syntax of Select…Case is:

Select Case SelectExpression

{Case Expression1

{statements to be executed if SelectExpression = Expression1}}

{Case Expression2 {statements to be executed if SelectExpression = Expression2}}

{Case Is RelationalOperator Expression3 {statements to be executed if the condition is true}}

{Case Expression4 To Expression5 {statements to be executed if SelectExpression is between values}}

{Case Else {statements to be executed if none of the above conditions are met}}

End Select

where

SelectExpression is a Long, Double or String expression

in Case…To…, if Expression4 > Expression5, the case is never true; no error is flagged.

Select…Case block. The following example puts all four types of cases together:

Program
Dim N as Long
Select Case N
Case 0
Print "N = 0"
Case 1
Print "N = 1"
Case is >=10
Print "N >= 10"
Case is < 0 ‘No requirement for statements after Case
Case 5 TO 9
Print "N is between 5 and 9"
Case Else
Print "N is 2, 3, or 4"
End Select
End Program

For…Next statements allow you to define loops in your program. The syntax is:

For counter = Start To End {Step Size}]

{Loop Statements}

Next {counter}

where

If Size is not defined, it defaults to 1.

The loop is complete when the counter value exceeds End. For positive Size, this occurs when counter>End. For negative Size, when counter<End.

Counter, Start, End, and Size may be Long or Double.

For example:

For I = 2 TO 5
Print "I = " I 'Prints 2, 3, 4, 5
Next I

For I = 4 TO 2 STEP –0.5
Print "I = " I 'Prints 4.0, 3.5, 3.0, 2.5, 2.0
Next

While…End While allows looping dependent on a dynamic condition. For example, you may want to remain in a loop until the velocity exceeds a certain value.

The syntax of While is:

While Condition

{statements to execute as long as condition is true}

End While

where

The condition is evaluated before any statements are executed. If the condition is initially false, no statements are executed.

Statements are optional. If none are included, While…End While acts as a delay.

You can have any number of statements (including zero) to be executed.

For example:

Program
While A2.VelocityFeedback < 1000
Print "Axis 2 Velocity Feedback still under 1000"
End While
End Program

Using the While or Do…Loop, the CPU repeatedly executes the While block (even if the block is empty). This is sometimes a problem. These commands do not relinquish system resources to other tasks. If you want to free up CPU resources during a While block or Do…Loop, include the Sleep command within the block as follows:

Program
While A1.VCmd < 1000
 Sleep 1
End While
End Program

The Do...Loop is similar to While except that the statement block is executed before the first evaluation of the condition. With the Do...Loop, the statement block are always executed at least once. Do...Loop also allows an option on the condition. Use While to execute while the condition is true, or Until to execute while the condition is false. The syntax of the Do...Loop is:

Do

{statements}

LOOP While|Until Condition

where:

The statements are executed at least once.

Statements are optional. If none are included, Do...Loop acts as a delay.

For example:

Dim Shared i as Long
Program
i = 0
Do
i = i + 1
Print i
Loop Until i = 10
End Program

or, equivalently, you can use Loop While:

Dim Shared i as Long
Program
i = 0
Do
i = i + 1
Print i
Loop While i < 10
End Program

GoTo unconditionally redirects program execution. The syntax is:

GoTo Label1

…

Label1:

where:

Label1 is a valid label within the same task as the GoTo.

The label must be on a separate line.

You can only branch within a Program, Event, Function, or Subroutine.

You can GoTo a label placed within a program block (If…Then, For…Next, Select…Case, While…End While, and Do...Loop) only if the GoTo and label are within the same block.

If the program is within a program block, you cannot GoTo a label outside that block.

Avoid GoTo wherever possible. History has shown that excessive use of GoTo makes programs harder to understand and debug. Use the other program control statements whenever possible.

Error Trapping

There are four ways to specify catch statements: Exact Value, Logical Condition, Range, and Else. The syntax used is:

Catch Error_Number {statements to execute if error Error_Number had occurred}

Catch Is <RelationalOperator> Error_Number {statements to execute if the condition is true}

Catch Error_Number1 To Error_Number2 {statements to execute if error number is between values}

Catch Else {statements to execute if all other errors had occurred}

where:

The number of Catch statements is not explicitly limited.

Error_Numbers can only be long-type numeric values.

In Catch…To…, if Error_Number1 > Error_Number2, the catch statement is never true and no error is flagged.

Catch statements are used within three types of error trapping blocks.

The Try block is designed to trap synchronous errors within task context (For more details, see the Error Handling section). There is no explicit limitation on the number of Try blocks instances in a program. The syntax for a Try block is:

Try

{code being examined for synchronous errors}

{Catch Error_Number {statements to be executed}}

{Catch Is <RelationalOperator> Error_Number {statements to be executed}}

{Catch Error_Number1 To Error_Number2 {statements to be executed}}

{Catch Else {statements to be executed}}

{Finally {statements to be executed if an error was trapped}}

End Try

An example of a Try block, designed to catch errors in the loading process of Task1.Prg:

Try
Load Task1.Prg
Catch 4033 ‘ File does not exist
Print “Task not found”
Catch 6007 ‘ Task must be killed first
KillTask Task1.Prg
Unload Task1.Prg
Load Task1.Prg
Catch Else
Print “Error while loading Task1.Prg”
Finally
Print “Caught error: “ Task1.prg.Error
End Try

The OnError block is designed to trap and process both synchronous and asynchronous errors in a task. OnError traps errors not trapped by the Try/Finally mechanism within the task. (For more details, see “Error Handling” section). Only one instance of OnError may exist in a program. The syntax for OnError block is:

OnError

{Catch Error_Number {statements to be executed}}

{Catch Is <RelationalOperator> Error_Number {statements to be executed}}

{Catch Error_Number1 To Error_Number2 {statements to be executed}}

{Catch Else {statements to be executed}}

End OnError

An example of an OnError block, designed to stop motion in case of a motion error:

OnError
Catch 3001 To 3999 ‘ Motion errors
System.Motion = 0
A1.Enable = 0
? VESExecute("System.Motion = 1")
A1. Enable = 1
Print "Caught a Motion error: " ThisTask.Prg.Error
Catch Else
Print "Caught a non-Motion error: " ThisTask.Prg.Error
End Onerror

The OnSystemError block is designed to trap and process both synchronous and asynchronous errors in all tasks, as well as errors that occur within the context of the system (For more details, see the Error Handling section). Only one instance of OnSystemError may exist in the system. The syntax for OnSystemError block is:

OnSystemError

{Catch Error_Number {statements to be executed}}

{Catch Is <RelationalOperator> Error_Number {statements to be executed}}

{Catch Error_Number1 To Error_Number2 {statements to be executed}}

{Catch Else {statements to be executed}}

End OnSystemError

An example of an OnSystemError block, designed to monitor errors in task Errors.Prg:

OnSystemError
Catch Is < 12000
Print “Caught a MC error: ” System.Error
‘ MC errors
KillTask Errors.Prg
Catch Is > 20000
Print “Caught a user error: ” System.Error
‘ User defined errors
KillTask Errors.Prg
End OnSystemError

Nesting

Program control commands can be nested. Nesting is when one program control command (or block of commands) is within another. There is no specified limit on the number of levels of nesting.

For example, the following program nests a WHILE…END WHILE sequence within a FOR…NEXT sequence:

For I = 1 to 10
 N=5
 While N>0
  N=N-1 'This command will be executed 50 times
 End While
Next I

There is no specified limit on the number of levels of nesting. The Sample Nesting Program in Appendix A shows numerous combinations of nesting.

FAQs

FAQs - MC-Basic - Ask the developers a question