If you've ever planned a vacation for your family, you realize that a lot of
thought and planning must be put into the process. You need to arrange for
transportation, for a place to stay, and for transportation once you get there.
You need to plan for emergencies. What if one of the kids needs stitches, or
someone needs a special diet or medication? What if your reservations fall
through? You need to be prepared for all sorts of contingencies.

It's the same with planning a macro project. If you dive into any sizable
macro project without giving much thought to how the macro will work, you
will probably waste a lot of time recoding your macro later. You need to plan
for possible errors that might occur, goofy things that the users will try to do
with the macro, and for differences in the users' hardware.

The 80/20 Principle

You will write 80 percent of the macro in 20 percent of the time you spend on
it. You'll spend the other 80 percent of your time tweaking, enhancing, working on
error checking, or fixing bugs that make up 20 percent of the macro. But
that 20 percent is often the part that makes or breaks the macro.

You'll find you can cut down on the time you spend tweaking the macro if you
have planned well before you even start coding. Take into account what might
happen if a file the macro needs to open is not where it should be, or if the
user's screen only displays 640 by 480 resoulution instead of 1024 by 768
resolution, or if the user has selected the WPDOS keyboard rather than leaving
the default keyboard selected, or if one user maps network drives differently
than her coworkers.

So many things can go wrong with even the simplest macro. You need to consider
all possible problems before deploying your finished project or risk looking
foolish or incompetent to your boss and co-workers.

Here are a few pointers for planning macro projects:

Hardcode as little information as possible

When you hard code information, such as filenames, paths, or other data
throughout a macro, you risk getting errors and macro failures down the road.
Always store data in variables that are set at the top of the macro, or get
the information from the user, system variables or the Registry.

Use system variables when at all possible

System variables can return lots of information about the user's system and the
current document. You can get information such as default file paths, what the
current character is, what the position of the cursor is on a page, what page
the cursor is on, and so forth. By getting information dynamically with system
variables you minimize possible errors down the road.

Store information in the Registry or INI

If your macro needs data that is particular to a user, such as what workgroup the
person is in, or what their user color is, store this information in the Registry
or an INI file. You can let your users customize settings for the macro, which
you can store in the Registry. There is no need for each user to be stuck with
the same settings.

Check if documents, directories, or data exist

If your macro needs to open a file, check to make sure that file is there before
opening it. There are several commands in PerfectScript that you can use to check
if certain files or directories exist. For example, DoesFileExist, DoesDirectoryExist,
GetCurrentDirectory, and so on. Become familiar with these commands
so that you can use them when you need them.

You can also check whether a certain variable exists or contains a valid value.
If it does not, the macro can query the user for the correct information, store
it in the Registry for later use, and move on to the next task.

You can use IF(EXISTS(vVariable)) to check whether a certain variable exists and
IF(vVariable <> " ") to check to make sure a variable has a value.

For example,

Capture errors and redirect execution

If your macro will be doing a Search operation, make sure you use an ONERROR
command to handle the possibility that the string you'll be searching
for does not exist. If you don't capture and redirect execution when an
error occurs, the user will see an ugly dialog box telling them the macro is
being cancelled, and they won't have the slightest idea why.

For example,

Other commands that can be used to check for errors and other events are
ONCANCEL and ONNOTFOUND.

Make sure a document screen is available

We talked about this last month also. If your macro needs to open a
document, make sure the user doesn't already have the maximum documents open.
For example,

For more information on the commands that help troubleshoot potential errors,
see the WordPerfect Macro Online Help, or my book.

For information on ordering my book see my web page.

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 1998 by J. Jeppson.