January 1998 Feature: PerfectScript Journal

January 1998: The FORNEXT Command

The most powerful command (at least in my opinion) is the FORNEXT command and its close cousin the FOR command. The two commands will get you the same results -- it's just a matter of personal preference for which one you'll use most often.

FORNEXT is used to repeat a command or series of commands a certain number of times. You can save lots of wear and tear on yourself, and keep your macro's length manageable with this command.

How Does It Work?

The FORNEXT loop works by assigning the Start value to a variable. The commands in the loop are then invoked. After the commands are done, the macro hits the ENDFOR command, which sends execution back to the FORNEXT command. The value of the variable is incremented by the Increment value, and the commands are performed again.

This pattern continues until the value of the variable exceeds the Stop value. When this happens, the macro breaks out of the FORNEXT loop and the command following the ENDFOR command is invoked.

The syntax for the FORNEXT command is as follows:


FORNEXT(variable; start; stop; increment)
   // the commands to be invoked
ENDFOR

The Parameters

Variable

The first parameter in the FORNEXT command is a variable name. This is a name that you supply. Many people use the letter i for the variable name. I personally use x. You could also use vCounter, ralph, or anything else that suits your fancy. If you nest FORNEXT loops, you'll need to pick a different name for each nested FORNEXT loop.

When the FORNEXT loop begins execution, the variable is assigned the Start value. With each iteration, the value changes, based on the Stop value and the Increment value. Often, this value is used within the loop.

Start

In the Start parameter, give the value that you want to be assigned to the variable first. Commonly, the value of 1 is used here, but you can specify any numeric value. You can even place the name of a variable that contains a numeric value.

The Start value should be smaller than the Stop value when the Increment value is a positive number, and larger than the Stop value if the Increment value is a negative number.

Stop

In the Stop parameter, give the last value that you want assigned to the variable. This can be any numeric value, or the name of a variable that contains a numeric value.

Increment

In the Increment parameter, specify the increment at which you want the value of the variable to be incremented. This parameter is optional. The default value is 1. This value can be either a positive or negative number.

If you use the default 1, or specify another positive number here, the Start value must be lower than the Stop value.

If you use a negative number here, the Start value must be higher than the Stop value.

Examples

Now for a few examples of the FORNEXT command in action:


// This example types out the numbers 1 thru 10
FORNEXT(x; 1; 10)
   Type(x)
   HardReturn
ENDFOR

// This example types out every other number from 1 thru 10
FORNEXT(x; 1; 10; 2)
   Type(x)
   HardReturn
ENDFOR

// This example types out the numbers 1 thru 10, backwards
FORNEXT(x; 10; 1; -1)
   Type(x)
   HardReturn
ENDFOR

The examples above are very simple, and really don't do anything useful, but they illustrate how FORNEXT can be used to automate repetitive tasks. You'll be amazed at how many things you will use the FORNEXT command for. Here are a few examples:

	Number the rows in a table
	Parse characters from a string (use the string length as the Stop value)
	Create multiple copies of a document or portion of a document
	Duplicate any set of commands a certain number of times

For more information on FORNEXT, FOR, and FOREACH, 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.