Macro format and structure

Contents of Article


Introduction

Macro Prototype

Macro Code structure



Introduction


The format of a macro is a standard text file of thinBasic source statements stored in the SPFLite MACROS folder.  


For most users, the full path of this folder will be:


C:\Users\username\My Documents\SPFLite\MACROS

or

C:\Documents and Settings\username\My Documents\SPFLite\MACROS


The macro should be named  macname.MACRO, where macname is the name with which you will be invoking the macro.


The string "macname" is also what is returned by the Get_MacName$ function.  As with everything else in SPFLite, macro names are case insensitive.


Note:  Because the macro's name gets parsed as part of a primary command or line command, you cannot use all legal Windows file name characters in a macro name, but should generally limit them to letters, digits and underscore.  


Further, for line-command macros, the name must be even more restricted; the name cannot contain any digits, because they will be confused with numeric line-command operands.  For line commands, the macro name should normally only contain letters to avoid problems.  A few special characters were found to be acceptable, such as $ and @.  We have not exhaustively tested every possible character, but if you can create a legal Windows file name with it, it will usually be valid as a macro name, except for the characters + - * ? : . / and \.


Line Macro names and Block Mode

For single line macros (e.g. do THIS to a single line) there is no problem, the line command = the macro name.


When you want to create a macro that can act as a block mode command (like CC/CC) the following methods are used:




SET MACROMODE.macname = BLOCK | LINE


If a SET MACROMODE has been issued for a macro name, the convention about repeating the last letter does not apply.  Any length or format of macro name can be set unconditionally to a specific processing mode.

The only requirement SPFLite imposes on the format of a macro file is the macro prototype (or header), which must be the first line in the macro.  Like everything else in SPFLite, the prototype is generally case-insensitive, unless it has default operands used as string values in FIND or CHANGE commands, for instance.



Macro Prototype


The first line of a macro must always be the macro prototype. This is a simple thinBasic comment statement of the format:


' macname.MACRO [ def-operand-1 def-operand-2 ... ]


The .MACRO part of the prototype is required.  macname itself is optional, but should normally be the name of the macro.  The brackets shown mean the list of operands is optional; don't actually code brackets here.


Currently, SPFLite does not demand that macname, if coded, match the actual file name of the macro.  However, for documentation purposes, it is best that you do make the name agree, just to keep things straight as you develop and use your macros.  It is possible that a later release of SPFLite will require that the prototype name agree with the file name, so it's best to make them agree now.


You may optionally enter default values for macro operands (if your macro uses command-line operands).  These are simple space-delimited strings which provide defaults if the relative operand number is not overridden when the macro is called.   For example, given the following prototype:


' sample.MACRO  aaa  bbb  ccc


If the macro were invoked with the primary command line as Sample with no supplied arguments, then if the executing macro requested the number of operands via Get_Arg_Count it would receive 3.   Get_Arg$(1) would be aaa,  Get_Arg$(2) would be bbb, and Get_Arg$(3) would be ccc.


More details on retrieving macro operands and working with them will be found in Accessing Command Line Operands.



Macro Code structure


As described above, an SPFLite macro program is essentially "open code" in thinBasic and has no "structure" per se.  By that, it means there is no MAIN Sub/Function, execution just starts at the first line and continues on.


As a result, there is, by default,  no built in mechanism for SPFLite to 'pass in' the operands.   This is easily correctable by making the mainline code into a thinBasic SUB routine.  If this is done, then the command line operands can be made available as passed parameters.  


Before making this decision you should evaluate how you wish to handle your declared variables.   In Open Code, all DIM'd variables are effectively Global and are 'visible' throughout your program.   If you convert to structured mode and make the mainline a SUB, then DIM'd variables are only 'visible' throughout the mainline SUB.   If you use additional SUB routines, then they will need to be passed any working data they require.


More details of this support will be found in Accessing Command Line Operands.



Created with the Personal Edition of HelpNDoc: Easy EBook and documentation generator