The Pgm Functions Library

joe · July 26, 2005

Download Pages

The PGM Functions Library™ enhances Macro Express functionality by providing categories of pre-designed, callable, reusable functions all in a standard Macro Express library file (.mex), which may be imported into your macro applications.

PGM Functions Library download page.
PGM Functions Library User Guide download page.
PGM Functions Library User Guide view online (must have Adobe Acrobat).

Reusable Macro Functions

Any repeatable task performed on your computer is a candidate to be a macro, of course. But did you know that any repeatable task that your macro performs is a candidate to be a reusable function? Think of reusable functions as custom-built commands, or black boxes, which extend the Macro Express built-in commands to suit your needs. Imagine having an unlimited number of commands available at your fingertips to do almost any imaginable task.

Macro Express contains approximately 300+ built-in, ready-to-use commands, so why in the world would anybody want, or need more? Because we, as users and developers, always want more, and … well, just need more. Even if Macro Express had 1,000 commands, this would still be true. Why? Because, like any other programming language, the commands themselves are just building blocks used in the construction of both simple and complex tasks.

Complex tasks, or macros, can be built from a series of simple tasks (reusable functions), which in turn, are built from the Macro Express commands. The PGM Functions Library provides for you some of these simple, but ready-made tasks.

If you need to:

Easily create reusable functions
Use multiple functions without overwriting variables
Time your macros for efficiency
Reliably launch applications
Keep an unattended operations log of events
Do date calculations
Manipulate strings
Parse strings
Search strings
Count the occurrence of one string in another
Convert decimal values to hexadecimal strings
Find square roots
Compare files and folders
Parse path names
Validate file names

… then the PGM Functions Library is for you!

How They Work

Plain and simple … every one of our functions is called via the Macro Express Macro Run command. Let us assume, for the moment, that your building a macro to save data from user input, or other application, to a file. Some if it is in hexadecimal format and needs to be converted. Normally, you would simply place code in your macro to handle the conversion. Like this:

// Convert a hex string %T10% to a decimal value %D10%
Variable Modify String: Uppercase %T10%
Variable Set Integer %N1% from Length of Variable %T10%
Variable Set Decimal %D10% to 0
Repeat with Variable using %N1%
 Variable Modify Integer: %N3% = %N1% - %N2%
 Variable Modify String: Copy Part of %T10% to %T1%
 Switch (T1)
   Case: A
     Variable Set Decimal %D1% to 10
   End Case
   Case: B
     Variable Set Decimal %D1% to 11
   End Case
   Case: C
     Variable Set Decimal %D1% to 12
   End Case
   Case: D
     Variable Set Decimal %D1% to 13
   End Case
   Case: E
     Variable Set Decimal %D1% to 14
   End Case
   Case: F
     Variable Set Decimal %D1% to 15
   End Case
   Default Case
     Variable Modify String: Convert %T1% to decimal %D1%
   End Case
 End Switch
 If Variable %N3% = 0
   Variable Modify Decimal: %D10% = %D10% + %D1%
 Else
   Variable Set Decimal %D2% to 1
   Repeat with Variable using %N3%
     Variable Modify Decimal: %D2% = %D2% * 16
   Repeat End
   Variable Modify Decimal: %D3% = %D2% * %D1%
   Variable Modify Decimal: %D10% = %D10% + %D3%
 End If
Repeat End

Pretty intense, huh? Sure, this takes care of the problem for this macro, but what about the next macro that needs the same capability? You could, of course, use copy and paste. However, what if the variables used here are used for something else in the macro that you are pasting to? They would all need to be changed. Here's the solution (you knew it was coming): use our function.

// Convert a hex string to a decimal value
Variable Set String %T1% "E2B5C6" // Hexadecimal
Write Registry String: "ParameterString1" // Pass it
Macro Run: { Math - Hex to Decimal } // Convert it
Read Registry Decimal: "ReturnDecimal1" // Read the results, D1 = 14,857,670

See the Macro Run command? It is calling one of the functions in our library. You set a value to pass just prior to making the call and then read the results immediately afterwards. In this case %T1% holds the hexadecimal string to be converted, and %D1% is used to read the returned answer. Plain and simple, reusable, and ready-made for cutting and pasting!

Why They Work

Because we have no clue as to which variables your functions use, and have no desire to overwrite them when calling one of ours, we save yours before writing ours, and then restore them when finished.

Take another look at the above example. The called { Math - Hex to Decimal } function also uses the %T1% variable to do its work, however, because it saves the current set of variables prior to overwriting them and then restores them at the end, your variables are never changed.

Functions by Category