PerfectScript Journal
 
July 1997: Creating Your Own Custom Macro Commands 

Have you ever created a macro routine that you ended up using over and over in many different macros? If you have, you'll find that making that routine into a custom macro command will be very handy. This month we'll look at using the PROCEDURE and FUNCTION commands to create custom macro routines. You can then use your own routines just as though they were built-in macro commands. This is very useful, especially when the routine is one that is used multiple times in the same macro. 

There are two types of custom routines: PROCEDURES and FUNCTIONS. With both, you can pass in parameter values that might change from macro to macro; and you can place the routine in a macro library or leave it in your main macro. The difference is that with a FUNCTION, you can pass a value back to your main macro.

PROCEDURES

To create your own custom PROCEDURE, place your code between PROCEDURE and ENDPROC commands. Provide a name for your PROCEDURE just after the PROCEDURE command, followed by parentheses. If you need to pass in a parameter, place the parameter name in the parentheses. Then, place that name within the code where that value will be needed. The following is an example of macro code that has been converted to a PROCEDURE. Note how the parameters vColumn, vRow, and vHeader have been placed at appropriate spots withing the macro code. 


PROCEDURE MakeTable(vColumn; vRow; vHeader)
TableCreate (Columns: vColumn; Rows: vRow)
SWITCH (vHeader)
  Caseof 1: TableHeader (Yes!)
  DEFAULT: TableHeader (No!)
  ENDSWITCH
TableFormatJustification (Justification: Left!)
TablePosition (PositionVal: AlignFull!)
ENDPROC

To create a table, I can now just call MakeTable and pass in the three parameters (the number of columns, the number of rows, and whether I want the first row to be a header row -- a value of 1 means Yes and any other value means no). 

MakeTable(5; 6; 1)

If I need to make several of tables, this little routine saves me lots of time and keeps the size of my macro to a minimum.

FUNCTIONS

Creating a FUNCTION is similar, except I can pass a value back to the main part of the macro. The following function takes a value that I pass in, multiplies it by a random number, then passes the answer back:

FUNCTION FindValue (vValue)
vNewValue:=vValue*RandomNumber(1; 10)
RETURN (vNewValue)
ENDFUNC

To use the FUNCTION I use the command:

vNewValue=FindValue(25)

Note how I must use the FUNCTION as an expression. In this case I am assigning its return value to a variable.  

You can use PROCEDURES and FUNCTIONS to help you organize and modularize your macro code. When you use PROCEDURES and FUNCTIONS, keep in mind that any local variables you set in the PROCEDURE or FUNCTION is only accessible to PROCEDURE or FUNCTION. Likewise, any local variables that you set in the main part of the macro cannot be accessed by a PROCEDURE or FUNCTION, unless you pass it in as a parameter.

You can learn more about variables, PROCEDURES and FUNCTIONS in my book.

If you have topics you'd like to see covered in The PerfectScript Journal, email the author. Type PSJournal-Story in the Subject line.
Copyright Notice: The information included in the PerfectScript Journal is protected by US Copyright. The author grants you the right to use the routines in your own macros as needed. You may not sell, distribute, or publish them in any form.
If you choose to use the information here, you do so entirely at your own risk. No representations are made regarding the fitness of this information for your   particular purpose, or for your ability or inability to use the information. You   are advised to make backups of all relevant files before implementing any suggestion  or technique.
© Copyright 1997 by J. Jeppson.