Volume 1

12

Chapter 12 Formulas

Formulas

This chapter describes use of formulas in the MP language. For a description of each formula, please
see Volume 3, Formulas.
Formulas, in this discussion, are applied to the two MP language statement types that allow formulas:
! the formula statement
! the conditional branching statement
Both of these statement types use the same syntax in the argument portion of the statement. The major
difference between the two types are the Boolean statement, which evaluates for zero or non-zero in the
result of the formula, and the formula statement, which makes an assignment to the variable that is the
target of the formula.

Difference between formulas and functions

Formulas refer to math operators and math formulas described in this chapter. The term function is
used to describe the unique mechanisms in the MP language that support the string select feature,
lookup table features, buffer files, and the user prompt feature. These function mechanisms rely on a
declaration in the post customization file for the feature and a formula as the calling method.
See Post Functions for more information.

Formula usage
Assignment formula types
Formula statements are assignment formulas. Assignment formulas are of three basic types:
! Simple assignmenta direct assignment of a value from the right side of the equation to the
variable on the left of the equals sign.
! Operator assignmentan assignment of a value calculated using the math operators. The result
of the equation is assigned to the left side variable.
! Formula assignmentsimilar to the operator assignment but the result of a formula function.
Formula functions are different from operators in that parameters are passed enclosed in the
parenthesis following the function label.
See MP Post Formula Types for more information.
Simple assignment example:
result assignment argument

x = 2

Operator assignment example:

June 2002

Mastercam Version 9 MP Post Processor Reference Guide 12-1

Chapter 12 Formulas

Volume 1

result assignment argument operator argument

x = 2 + 2

Formula assignment example:

result assignment function argument <argument>
c = atan2(x, y)

Operator and function assignments can be mixed and the order of evaluation controlled through the use
of parentheses.
x = abs(x) + int(y)
c = atan2((x + z), (y - 2))

Assignment formula usage

Assignment formulas are used in the definition and postblock areas in the post customization file
(.PST). There are several different ways to interpret the assignment formula depending the location
and the assignment operator used. Care must be taken to use the correct assignment operator within the
context of the post customization file area to avoid an incorrect interpretation by the post executable file
or illegal syntax. See Introduction to MP Post Processors for more information.
Assignment formulas in the definition area
Using the colon (:) (initialization)
When the assignment formula is used in the definition area of the post customization file, use the colon
(:) as the assignment operator to initialize a numeric variable. You may recognize this as the way to
declare a user-defined numeric variable.
Initialization assignment formulas must start in the first column of the post customization file.
Example of a numeric variable initialization:
real_var1 : 0
real_var2 : real_var1

Using the equal sign (=) (global formula)

The equal sign (=) makes the formula a global formula. Global formulas are evaluated any time the
target numeric variable is used as a postline statement or in a postline Boolean or formula.
Global assignment formulas must start in the first column of the post customization file.
Example of a global formula:
real_var1 = x
real_var2 = abs(x)

12-2 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

Initializing strings
Never use either the colon (:) or the equal sign (=) with a string variable initialization.
Example of a string variable initialization:
string1 STRING

Assignment formulas in the postblock area (=)

When the assignment formula is used in the postblock area of the post customization file, the
assignment formula can be used as a formula postline where it is evaluated when the postblock is
executed, or as the action in a Boolean formula. The equal sign (=) is the only valid assignment
operator in this scenario.
Example of a formula postline:
ppostblock #A postblock declaration
real_result = real_var1 + real_var2
string_result = string1 + string2

Example of a Boolean postline with the action an assignment formula:

ppostblock #A postblock declaration
if real_var, real_result = real_var1 + real_var2
if real_var, string_result = string1 + string2

Boolean formulas
Boolean statements that use the keyword if or while use a Boolean formula to evaluate for a zero or
non-zero condition. Any non-zero is interpreted as a true condition. In the if Boolean statement, a
true condition allows the action to be executed. In the while Boolean statement, a true condition
allows the action to be executed in a continuous loop.
The form of the Boolean formula is the same as the assignment formula except that the
result assignment is replaced with the keyword, and the action follows the statement.
Boolean formula examples:
keyword argument, action
if x, p_action
keyword argument operator argument, action
if x = y, p_action
keyword function argument <argument>, action
if fmtrnd(x) , p_action

June 2002

Mastercam Version 9 MP Post Processor Reference Guide 12-3

Chapter 12 Formulas

Volume 1

Boolean formula usage

The Boolean formula can only be used within the context of a Boolean postline.
Example of a Boolean formula:
ppostblock #A postblock declaration
if real_var1 = real_var2, p_action
if string1 = string2, p_action

Definitions
Before examining the operators and functions available in the MP language, you must understand the
terms that used in the operator and function descriptions. You also must understand some of the
underlying structures in the post executable, including the database order, to comprehend how the
formulas work. An understanding of these concepts is also needed to grasp the mechanism used with
functions.

Basic definitions
Cartesian coordinate system
A system that describes a point in space using three coordinate axes, any two which are perpendicular
to one another. Each axis is labeled. The location of a point in space can be described using ordered
triple sets of positions along the three axes. Cartesian coordinate systems are also known as
rectangular coordinates, for example, x, y, z:
Z

Right hand rule

The right hand rule is used to illustrate the standard Cartesian coordinate system. The middle finger on
the right hand represents the Z axis vector, the index finger represents the Y axis vector and the thumb
represents the X axis.
Use this method to determine the resulting vector direction in the 3D cross product. The middle finger
on the right hand represents the first vector, the index finger represents the second vector and the thumb
represents the resulting vector.

12-4 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

Z axis

Y axis

X axis

Scalar
A scalar value is a single numeric value that can be defined as a point on a number scale.
Vector
A vector is defined as a direction and magnitude. Three values are normally required to define a
vector. MP math functions always use vectors defined in the Cartesian coordinate system. The start
point is always 0,0,0 and is implied in the vector definition. The second point is a position some
distance from the start point. Thus any vector can be defined by the endpoint of the vector or the
second point. A 2D vector is a 3D vector with the Z component implied as zero.
Array
In the MP language, an array is defined by an ordered list of numeric variables that are formatted,
initialized, or predefined in the declared order. All arrays in the MP language are one-dimensional, but
you can imply multi-dimensional arrays by ordering several single dimension arrays.
var1
var2
var3
var4
var5

:
:
:
:
:

0
0
0
0
0

#User-defined numeric variables

Matrix
A matrix used in Mastercam and the MP math functions is described as the vector components of a
rectangular coordinate system. There are always nine elements in the matrix definition. The first 3D
vector describes the X axis, the second 3D vector the Y axis, and the third 3D vector the Z axis. Each
vector in the definition is unitized (see the next paragraph for a definition).

June 2002

Mastercam Version 9 MP Post Processor Reference Guide 12-5

Chapter 12 Formulas

Volume 1

Vector and matrix definitions

Unitized vector
A unitized vector has a unit length of one. Unitizing a vector allows simpler trigonometric, 2D, and 3D
mathematical evaluation of the vector.
Dot product
A dot product is the product of two unitized vectors with the resulting magnitude equal to the cosine of
the product. The result is a scalar value.
Cross product
A cross product is the product of two unitized vectors with the resulting magnitude equal to the sine of
the product and a direction perpendicular to both vectors. The right hand rule is used to determine the
vector direction in a 3D cross product.

Arrays in MP
All arrays in the MP language are one-dimensional because an array in the MP language is simply an
ordered list of variables. The order of this list is determined by the order in which the variables are
formatted, initialized, or predefined in the post executable. These can be described as implied arrays
because nothing other than the actual positions of the variables in the database denotes an array. They
are extremely sensitive to where the variables in the array are declared.
Note: Be very careful not to use predefined variables in a list of user-defined variables. It is difficult to
detect this error, and it causes unrelated variables to appear to change inexplicably.
Initialize and format numeric variables in identical order.You access the rest of the variables in the
array by selecting the first variable declared in the array. Functions using an array form as an argument
expect that the post writer has set up the variables in the correct order.
Note: A common mistake is to use the predefined variables t1 or t2 as user-defined variables in an
implied array. These labels have already been used in the intersection routines.
See Numeric Variables and String Variables for more information. Detailed descriptions and a listing
of the database order for all predefined numeric variables and predefined string variables are provided
in Volume 3, Numeric Variables and Volume 3, String Variables.

Entity and variable type definitions

Formula functions receive arguments and return values of specific types. The MP language has only
two types of variables:
! numeric values
! character strings
You can imply additional types by using the order of the variables in the database to create vectors,
matrixes, arrays, and lists used with buffers and parameter reading functions. Listed here are the types
and the structure that is expected:
12-6 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

value: A number, real or integer, directly inserted in the formula. For example:
10.

string literal: Character string consisting of alphanumeric characters surrounded by double quotes ().
For example:
ABC123

Note: MP does not support the use of string literals in formulas. Declare a user-defined string
and use the string variable name as an argument.
string: Character string variable consisting of alphanumeric characters. For example:
string1 ABC123

scalar: A single numeric variable representing a scalar value. For example:

var1 : 1

angle: A single numeric variable representing an angle in degrees. For example:

ang1 : 45

2d vector: Two numeric variables representing a planar vector. This form is also used to represent a
planar point.
Note: It is recommended that you always use 3D vectors, even with 2D vector routines.
v2_x : 1
v2_y : 1
v2_z : 1 # Not used but recommended

3d vector: Three numeric variables representing a vector with direction in space. This form is also
used to represent a point in space. For example:
v3_x : 1
v3_y : 1
v3_z : 1

line: Two 3D vectors representing the line end points in space. For example:
v3_x1
v3_y1
v3_z1
v3_x2
v3_y2
v3_z2

:
:
:
:
:
:

1 # Endpoint one
1
1
1 # Endpoint two
1
1

arc: One 2D vector, a scalar, and two angle variables. Five ordered variables are expectedarc center
on X, arc center on Y, radius, start angle, and the arc sweep.
v2_xc : 1
v2_yc : 1
radius : 1
astart : 1
asweep : 1
June 2002

Mastercam Version 9 MP Post Processor Reference Guide 12-7

Chapter 12 Formulas

Volume 1

matrix: Three 3D vectors representing the X axis, Y axis, and Z axis.

v3_xx
v3_xy
v3_xz
v3_yx
v3_yy
v3_yz
v3_zx
v3_zy
v3_zz

:
:
:
:
:
:
:
:
:

1 # Vector representing X axis

0
0
0 # Vector representing Y axis
1
0
0 # Vector representing Z axis
0
1

array: The array or listing can be any size that is needed. If the variables are user-defined, they must
be declared in the post customization file in the order required by the function.
Note: Be careful to avoid using predefined variables in the ordered declarations. If you are using
predefined variables, check the database order tables to determine how they are listed in memory.
Numeric variables and string variables cannot be mixed in the implied array. Each type is considered
separately.
If the array consists of user-defined numeric variables and you must format and initialize the variables.
The full array should then be included in both definitions.
Following is an example of 3D array initialization and format assignment.
v3_x : 1
v3_y : 1
v3_z : 1
fmt X 1 v3_x
fmt Y 1 v3_y
fmt Z 1 v3_z

Following is an example of string variables in an implied array:

string1
string2
string3
string4
string5

FIRST
SECOND
THIRD
FOURTH
FIFTH

Formula structure
A formula can be structured in many different ways depending on where it is used (assignment formula
or Boolean formula) and what arguments are contained in it. This section describes what variable types
can be combined in a formula, order of precedence, and the return types. The individual formula
descriptions give a detailed explanation of use and function.

12-8 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

Nesting types
Formulas are of three basic types:
! Simple assignment
! Operator assignment
! Formula assignment
These types can be combined or nested in an equation to perform calculations or resolve conditional
branching statements (if and while). The return type for the conditional branching statement must
always be a numeric value. This return value is a predefined numeric variable in the post executable
and has the label bool____result. The post executable examines this variable to see if it is 0 (false) or
non-zero (true) in evaluating the branching statement.
Note: Do not use bool____result directly because it is for internal use only in the post executable.
Formula assignments can be nested wherever the return type is a single numeric or string variable that
matches the argument type to be passed, for example:
result = (no2asc(65) = str_cap_a) + 1

Notice that the ASCII decimal 65 is converted to the character A, making a Boolean comparison to
the string (assumng it is also A), and adding the result of the comparison to the value 1. The result in
this case is 2.
The preceding example illustrates that the assignment types can be freely mixed as long as the rules are
followed relating to type matching, for example:
# Simple assignments
x = 1
x = y
str1 = str2

# Operator assignments
x = x + y
x = x^y
str1 = str2 + str3

# Formula assignments
c = abs (c)
c = atan2 (x, y)
str1 = no2str (65)
# Formula assignment and Operator assignment
x = fmtrnd(abs(x/2)) + y * 2

Do not nest vector or matrix function that return to a vector, matrix or implied array. These functions
must be coded on a separate line in the customization file and return to a vector, matrix or implied array
that is declared in the post or as predefined variables.

June 2002

Mastercam Version 9 MP Post Processor Reference Guide 12-9

Chapter 12 Formulas

Volume 1

Only formulas that return a scalar or single string may be nested. For example, assume these defined
arrays:
v3_x1 : 1
v3_y1 : 1
v3_z1 : 1
v3_x2 : 1
v3_y2 : 1
v3_z2 : 1
# This is not a legal formula, nesting a returned vector
v3_x2 = vequ(vscl(real_var,v3_x1))
# This is the correct form when the return is not a scalar
v3_x1 = vscl(real_var,v3_x1)
v3_x2 = vequ(v3_x1)

Understanding vector and matrix functions

Because the MP language was not designed with arrays as a native type, they must be implied by the
order in which they are entered into the internal database. The design of a formula function allows only
a single variable name to be passed on each argument and only a single variable name to be the return
variable. The formula functions rely on the user passing the first variable defined in the implied array
as the argument names in the function, for example:
Given the arrays:
v3d_x1 : 1
v3d_y1 : 2
v3d_z1 : 3
v3d_x2 : 1
v3d_y2 : 2
v3d_z2 : 3
v3d_xr : 0
v3d_yr : 0
v3d_zr : 0

The function call would use the first variable name from the implied array definitions and access the
immediately following variable names:
v3d_xr = vadd (v3d_x1, v3d_x2)

The resulting vector would be:

v3d_xr would equal 2.
v3d_yr would equal 4.
v3d_zr would equal 6.

Note: Operators (+,-,*,/,<,>,<=,>=,<>) always pass a single variable.

12-10 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

Precedence of operation
How a formula is evaluated is based on the precedence of its operators in relation to each other.
Following is a chart that describes the precedence of operation in MP language formula parsing. Those
operators with the highest precedence are at the top of the table. Highest precedence operators are
evaluated first from the left to the right in the formula statement.
Precedence can be controlled by using open and close parentheses. Do not confuse them with the
parentheses that encapsulate the formula parameters in formula functions. These must be used to
define the arguments passed with a function and can be considered part of the individual formula.

Precedence

Highest

Operator

Nesting parentheses and formulas: (, ), and f( )

Unary minus: -x
Power: ^
Multiplication, division: *, /
Addition, subtraction: +, Comparison operators: <, >, >=, <=, =, <>

Lowest

Logical operators: &, | (and, or)

Examples of evaluation of a formula statement with precedence:

y = x * z 6 evaluates x * z and subtracts 6 from the result.
y = x * (z 6) evaluates z - 6 and multiplies the result with x.

Boolean formula usage

Boolean formulas are conditions or comparisons that can be evaluated true or false (non-zero or zero;
the post executable returns 1 or 0). They are used in the conditional branching statement with the
keywords 'if' or while. The Boolean or logic operators for comparison are:

Symbol

=
<>
<
>
<=
>=
not
June 2002

Description

equal
not equal
less than
greater than
less than or equal
greater than or equal
opposite result of a logic statement
Mastercam Version 9 MP Post Processor Reference Guide 12-11

Chapter 12 Formulas

Volume 1

The logic operators for comparison are combined with the logic operators and (&) or or ( | ) to
evaluate the true and false intermediate results in the following way:
Symbol

Description

(result) (logic operator) (result) = evaluation

&

logical and

true & true = true

true & false = false
false & true = false
false & false = false
In logical and, all results must be true to
evaluate true.

logical or

true | true = true

true | false = true
false | true = true
false | false = false
In logical or, if any result is true, the
evaluation is true.

For example, the following will be evaluated to true or false:

x+1 > y
abs (x) < 1
x >= 0

The logic operators for comparison(<, >, =, and not) can be combined with & and | .
For example:
x>0&y>0
# Using the & (and) logic operator
abs (x) > 1 | x = 0 # Using the | (or) logic operator

The result of evaluating these examples when x = 1 and y = 0 would be:

x >= 0 & y >= 0
x=0&y=0
x = 0 | y+1
x<0 |y<0

then 1 and 1, so true and true evaluates true

then 0 and 1, so false and true evaluates false
then 0 or 1, so false or true evaluates true
then 0 or 0, so false or false evaluates false

The logic operators are used with the if and while keywords and a comma end delimiter to
complete the conditional branching statements. A true evaluation allows the action (the statement
following the conditional branching statement after the comma end delimiter) to be executed. The
action always follows the comma, for example:
if x = y, x = prv_x
if x > 0 & y > 0, "both x and y are positive"
while x < 10, pincx
while x > y | z = 0, pdoit

12-12 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

A single else keyword can be used to follow a Boolean postline (conditional branching statement and
action). If the conditional branching statement evaluates true, then the action after the statement is
executed. If the conditional branching statement evaluates false, then the action after the else
keyword is executed instead. For example:
if x = y, x = prv_x
else, y = prv_y

Rules for using if, while and else conditional branching statements
! if, while, and else keywords cannot start in the first column.
! Put a space between the keyword if, or while and the Boolean formula. For example:
valid :
invalid:

if x = 1, x = 0
ifx < y, x = y

# Requires a space

! Put a comma delimiter after the Boolean formula. For example:

valid :
invalid:

if abs (x) <= 1, pdoit

if x = 0 | x = 1 pdoit # Requires a comma after the Boolean conditonals

! When using the else keyword, also put a comma following that statement on the same postline as

a delimiter.
valid :

if abs (x) > 1, pdoit

else, pdontdoit

invalid:

if abs(x) + abs(y) > 0, pdoit

else pdontdoit
# Requires a comma after the else (else,)

invalid:

if x > 0,
x is positive, e
else
# Requires a comma on this line (else,)
, x is negative or zero, e # Cannot have the comma start on the line

! A conditional branching statement can be continued onto the next postline. To continue the

expression on the next postline, break the line at any point in the expression other than in a variable
label. For example:
valid:

if (x <> prv_x) |
(y <> prv_y) |
(z <> prv_z), pmotion
else, pnomotion

! A else conditional branching statement, if used, must appear immediately after the postline(s) in

the preceding if Boolean postline. For example:

valid :
valid :

invalid:

invalid:
June 2002

if x=0, pzero
else, pnonzero
if x > 0,
x is positive, e
else,
x is negative or zero, e
if x = 0, pzero
n, x, y, z, e
else, pnonzero
if x > y, x = y, else, x = 0
Mastercam Version 9 MP Post Processor Reference Guide 12-13

Chapter 12 Formulas

Volume 1

! The post executable considers only a single statement after the delimiter comma to be part of the

preceding conditional branching statement. For example:

valid:
invalid:

invalid:

if x > 0,
x is positive, e
if x > 0 & y > 0,
x is positive, e
y is positive, e # y is positive, will be output even
# if (x > 0) & (y > 0) evaluates to false.
if x = 0 | y = 0, x or y, or both, are zero
else, x is nonzero
y is nonzero # y is nonzero will always be
# output, whether x = 0 | y = 0
# evaluates to true or false.

Note: If more than one postline is needed with an if, while or else, call a separate postblock or
use bracketed postblocks.
See Postblocks for more information.
! A conditional branching statement cannot be the action of the conditional branching statement.

For example:
invalid:
invalid:
invalid:

if x > 0, if y > 0, both x and y are positive, e

if x > 0,
if y > 0, both x and y are positive, e
if x = 0, pzero1
else, if y = 0, pzero2

Note: Use a separate postblock or use bracketed postblocks to nest the conditional branching
statement.
See Postblocks for more information.
Note: When using the while conditional branching statement, make sure that the Boolean condition
will eventually evaluate false. If the condition never evaluates false, the post executable will remain in
an endless loop.

MP post formula types

Formulas can be divided into categories as represented here. When reading this document online, you
can use the links to jump to a list of the specific operators or functions in each category. For a detailed
description of each formula or function, see Volume 3, Formulas.
Basic math functions Math operators that perform the basic math functions (the assignment operator
(=), addition, subtraction, multiplication, division, etc.).
Logic operators Logical operators for Boolean evaluation. Operators to test for equal, greater than,
less than, and, or, etc.
Advanced math functions Math functions including square root, logarithms, absolute values,
rounding and others.

12-14 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

Trigonometric functions Standard trigonometric functions for sine, cosine and tangent of an angle.
An extremely useful function atan2 returns the solution of the arc tangent within the 360 degree range.
2D vector math Single plane functions for vector addition and subtraction, and scaling. Even when
working in a single plane, it is recommended that you describe numeric variables as 3D positions. 2D
vector math functions are used less frequently because the 3D vector math functions are more
powerful.
3D vector math 3D functions for vector addition and subtraction. Functions to rotate vectors and
points about an axis are also provided in this category.
Matrix math Matrix functions allow for mapping within the matrix that defines a Cartesian coordinate
system. Other matrix manipulation functions such as matrix transpose are also available.
Special MP functions Calls to the lookup table functions and buffer file function. Other unique
formulas to determine the negative, zero, or positive of a numeric variable are provided here.
Intersection functions Planar intersection routines for line-line, arc-line and arc-arc.
String functions String manipulation functions. String variables can be broken, values scanned from
a string, case changed, etc.
Conversion functions Formulas to convert strings to numeric variables.
File functions Powerful file manipulation functions to rename and remove files. File functions also
allow launching another program or Mastercam C-Hook.
Precedence functions Parentheses are used to control the precedence in an assignment formula or a
Boolean formula.
Binary functions Bit-wise functions.

June 2002

Mastercam Version 9 MP Post Processor Reference Guide 12-15

Chapter 12 Formulas

Volume 1

Post formulas by type

Please see Volume 3, Formulas for a description of the syntax of each formula.
Basic math functions
- (unary)
*
/
^
+
=
Logic operators
&
|
<
<=
<>
=
>
>=
not
Advanced math functions
abs
fmtrnd
frac
int
log
log10
round
sqrt
Trigonometric functions
acos
atan
atan2
cos
sin
tan
2D vector math
axb
dot
12-16 Mastercam Version 9 MP Post Processor Reference Guide

June 2002

Volume 1

Chapter 12 Formulas

lng
rot
vad
veq
vlh
vnr
vrh
vsa
vsb
vsc
3D vector math
dot3
lng3
rotp
rotv
vadd
vaxb
vequ
vnrm
vsca
vscl
vsub
Matrix math
matt
mmap
mmul
mteq
vmap
Special MP functions
finc
flook
fprm
frange
fsg1
fsg2
fsg3
updgbl
rbuf
rpar
slin
slout
vlin
vlout
June 2002

Mastercam Version 9 MP Post Processor Reference Guide 12-17

Chapter 12 Formulas

Volume 1

wbuf
Intersection functions
xaa
xla
xll
String functions
brksps
lcase
nwadrs
scan
strlen
strstr
ucase
updstr
Conversion functions
newfs
no2asc
no2str
plcval
File functions
dll
fclose
fexist
launch
mprint
remove
rename
Precedence functions
(
)
Binary functions
and
ger
good
ior
xor

12-18 Mastercam Version 9 MP Post Processor Reference Guide

June 2002