                  Mach3 VB Macro Pre-Processor

                       by Ray Livingston
                       jagboy@pacbell.net


1. Introduction

VBPP is a very rudimentary macro pre-processor for Mach3 macros. It provides the
following capabilities:

* Include files for sharing common definitions across macro files
* Simple text macro capability

VBPP is written in Perl, and requires ActiveState perl to function. ActiveState
Perl is a free download from www.activestate.com.


2. Operation And File Structure

VBPP reads in macro source files with the .m3m extension, and writes out Mach3
macro files with the .m1s extension. All .m3m files are assumed to be in the
"current" directory when VBPP is run. All .m1s files are written to a single
directory, which defaults to the "current" directory, but can also be
re-directed to any directory by means of a command line argument. The default
VBPP batch file directs all .m1s files to be written to the
C:\Mach3\macros\Mach3Mill directory.


2.1 Installation

Download and install ActiveState Perl. Install to the default location of
C:\Perl.

Copy the VBPP.pl file to C:\Perl\site\lib\VBPP

Copy the example files to any convenient location


2.2 Command Line Syntax And Options

Command line syntax is:

    C:\Perl\bin\perl.exe "C:\Perl\site\lib\VBPP\VBPP.pl" <options>
    
Where <options> can be any of:

    -f inputfile
    -D outdir
    
    The "-f inputfile" option allows a single file to be processed.  "inputfile" is the path to the .m3m file to be processed.
    
    The "-D outdir" option allows the output directory for all .m1s files to be specified/
    
The contents of the default VBPP .bat file is:

    REM Change the following line to point to your .m3m source directory
    cd C:\Perl\site\lib\MyMach3Macros
    REM Change the following line if you want your .m1s files written somewhere else
    C:\Perl\bin\perl.exe "C:\Perl\site\lib\VBPP\VBPP.pl" -D C:\Mach3\macros\Mach3Mill
    Pause


3. Syntax Summary

The macro file can contain any of the following constructs:


3.1 #include "filename"

The #include directive will parse the file whose name or path is given by
"filename" and copy any required definitions into the .m1s file.

Include files may contain VB constant definitions of the form "Name = Value '
Comment", as well as comment lines and macro definitions (see below). Include
files may be nested, but nesting is not encouraged.

Examples:

    #include "common.def"
    #include "c:\Mach3\macros\myincludes.inc"


3.2 #filename "outfilename"

The #filename directive allows the name of the output .m1s file to be explicitly
specified. This is convenient for allowing your .m3m files to have meaningful
symbolic names, while still allowing VBPP to directly output valid Mach3 M-macro
filenames.

Note that if you give a full path in the #filename directive, the -D command
line option will not work correctly.

Examples:

    #filename "M123.m1s"
    #filename "C:\Mach3\macros\MyMacros\M123.m1s"
    

3.3 Macro Invocation

A macro invocation consists of a valid macro name, preceded by the "@"
character, and followed by zero to nine arguments. The macro definition must
appear in one of the files given by the #include directives. See the following
section for a description of the syntax for macro definitions.

Examples:

    @MyGoToPosMacro 1.234 2.345.3.456
    

4. VBPP Macros


4.1 Macro Introduction

VBPP macros are very rudimentary test-replacement macros, with up to ten
arguments. All required macro definitions must appear in one of the #include
files. Macros can be nested, but only to VERY limited extent: All nested macros
must be defined before they are invoked, and ONLY the outermost macro can use
arguments.  If I get energetic sometime, I'll remove these restrictions.

The basic syntax of a macro definition is as follows:

    #macro macroname
    MACRO BODY HERE
    #endm
    
The macro name given by macroname may contain any combination of letter, digits,
and underscores, but must start with a letter. The macro body may contain any
valid VB code. If arguments are required, they are represented by the @0-@9
"placeholders" in the macro definition. The placeholders will be replaced with
the actual argument values when the macro is invoked. The first argument will
replace @0, the second will replace @1, etc.

Example Macro Definitions:

#macro WaitUntilStopped
' Wait until machine is stopped
While IsMoving ()
    Sleep 10
Wend
#endm

#macro CallSubMacro
' Increment BusyFlag
BusyFlag = GetUserDRO(MacroBusySemaphoreDRO)
SetUserDRO(MacroBusySemaphoreDRO, BusyFlag + 1)
Sleep 100
' Call the Sub macro
Code @0 & " P" & @1 & " Q" & @2
' Wait until it's finished
While GetUserDRO(MacroBusySemaphoreDRO) > BusyFlag
    Sleep 100
Wend
#endm

Example Macro Invocations (assuming above macros are defined in Common.def):

#include "Common.def"

CornerFindMacro = "M123"
XAxisPlus = 2
YAxisMinus = 4

#WaitUntilStopped       ' Wait until all movement stops

#CallSubMacro CornerFindMacro XAxisPlus YAxisMinus   ' Probe LR corner of workpiece


