WordPerfect Office

Reference: Levels, loops, and variables in programmed merges

The following topics provide information about using levels, loops, and merge variables when you program a merge.

Understanding levels

In a merge document you can have as many as 40 levels of execution per file. IF commands do not require a level; they can be nested indefinitely. Each SWITCH, FORNEXT, or WHILE uses one level.

NESTMACRO, NESTFORM, and NESTDATA do not require an execution level, because each nested file has 40 new execution levels.

However, they do require a nesting level. You can nest files 10 levels deep.

Merge uses separate stacks to maintain execution levels and nesting levels.

Understanding loops

Whenever the same commands repeat several times, that section of the merge is called a loop. When you create a loop, it is very important to have a way for the loop to end. If the loop does not have an end, there is no way to stop execution without pressing Esc or Ctrl + Enter.

There are many types of loops you can create with merge programming commands.

You can use an IF structure or you can use FORNEXT or WHILE. You can also create loops by going to or calling subroutines (with GO or CALL). The structure you should use for any given loop depends on the task you are trying to accomplish.

Understanding variables

A variable represents a place in memory where data is stored. As its name indicates, the data in a variable is changeable. You can use variables to calculate and keep track of text and numeric values that change during a merge.

Understanding system variables vs. user defined variables

There are two major types of variables in WordPerfect: system variables and user-defined variables. System variables are variables that WordPerfect creates and maintains; they contain information about the current state of the application. You cannot change the names or contents of these variables, but you can use their contents at any given time. System variables are listed in the Parameter Entry dialog box when you choose the system command.

User-defined variables are variables that you create. You determine the name and contents of these variables when you assign them. You can also perform operations on them to change their contents. There are two subcategories of user-defined variables: global and local.

Understanding global variables vs. local variables

Global variables are accessible from anywhere inside a merge or a macro. All global merge variables can be read by macros; macro variables can be read by merge commands if the PERSIST command is used in the macro.

Local variables are available only in a merge and are stored in a place in memory separate from global variables. They are accessible only from the file in which they are defined. For example, if you create a local variable named Number in a form file, the data file or other form files cannot access the information stored in it. When you nest merge files, the local variables in the parent file cannot be used in the nested file.

When you return to the parent file, the local variables in the nested file no longer exist, but the local variables in the parent file are once again accessible.

Local variables take precedence over global variables. For example, suppose you have both a global and a local variable named Number. If you try to access the global variable Number from inside a file where the local variable Number is accessible, you will get the contents of the local variable. The global variable Number still exists, but is inaccessible until you are no longer accessing the current merge file.

Naming variables

Variable names can be as many as 30 characters long for both global and local variables. Although you can use the same name for a local and a global variable, you cannot use the same name for any two local variables or any two global variables. You should not use the same name for a local variable and a label.

Variable names are not case sensitive. Abc, AbC, ABC, and abc are read as the same variable.

Variables receive their names when they are assigned. For more information, see “Assigning variables.”

Understanding variable contents

All user-defined variables can contain text or numbers. A user-defined variable can hold 127 characters.

Assigning variables

You assign a global variable with ASSIGN and a local variable with ASSIGNLOCAL. For example, the following two statements assign two different variables, one global and one local:

ASSIGN creates a global variable named Number with “45” as its contents. ASSIGNLOCAL creates a separate, local variable named Number with “36” as its contents. For more information, see “ASSIGN(var;expr)” and “ASSIGNLOCAL(var;expr).”

In addition to using ASSIGN and ASSIGNLOCAL, the following commands also assign variables:

The following rules determine whether the variables assigned by CHAR, GETSTRING, and LOOK are local or global in a merge:

FOR and FOREACH assign variables by the same rules as above, except that if no variable with the name used in the command exists (the third rule), a local variable is created and assigned by the command. This feature allows recursion using FOR and FOREACH in a merge.

If a variable already exists and you assign new contents to it, the previous contents will be replaced without warning.

Executing variables

You can execute (write out) a variable anywhere you want its contents to appear. For example, by executing a variable you can do the following:

To execute a variable, use VARIABLE. For example, the statement VARIABLE(Number) would execute the variable named Number.

Understanding variable duration

Local variables exist only in the file in which they are defined. Once you quit the file that defined the variables or once the merge ends, the local variables are erased (and the memory assigned to them is released). However, the contents of global variables remain in memory until you exit WordPerfect. To conserve memory, you should use local variables instead of global variables whenever possible.

If you want to erase a variable without exiting a file or exiting WordPerfect, assign nothing to the variable by using the following commands: ASSIGN(var;) or ASSIGNLOCAL(var;). These commands empty the variable of its contents and release the memory used by the variable. After you use this command, the variable no longer exists. It is a good idea to empty variables at the beginning of the merge in which they are used (unless the merge assigns new contents to them).

Understanding operations on variables

All variables can be compared to each other, and user-defined variables can have other operations performed on them. Operations are performed using various programming commands. See “Reference: Expressions in programmed merges” and “Reference: List of merge programming commands.”

Reference: Levels, loops, and variables in programmed merges