Reference: The Merge toolbar and programming commands

The Merge toolbar displays at the top of the document window when you create a form document or a data file for a merge. You can control a merge and edit merge files by using the Merge toolbar.

You can also control a merge by using merge programming commands. The merge commands are similar to codes used in computer programming languages. For example, you need to specify parameters for some commands, and you can create subroutines, a set of commands that can be repeated in a merge.


Using the Merge toolbar

WordPerfect Office btnbacktotopproc Reference: The Merge toolbar and programming commands

When you create a form document or a data file for a merge, the Merge toolbar displays at the top of the document window.

WordPerfect Office merge3 Reference: The Merge toolbar and programming commands

This is the Merge toolbar.

You can control a merge and perform specific merge functions by using the Merge toolbar. The Merge toolbar is context-sensitive, which means that the buttons available on the Merge toolbar change according to the task you are performing. For example, you would see different buttons for performing a keyboard merge and for editing a data table file.

You cannot hide the Merge toolbar for a merge form document or merge data file. If it is not visible, then the active file is not a form document or a merge data file.


Prompting for user input and message display

WordPerfect Office btnbacktotopproc Reference: The Merge toolbar and programming commands

Several commands are used to display a message for, or request information from, the person running the merge. You can use a message to inform the user of the progress of the merge or you can use a prompt to remind the user of the kind of information needed in a fill-in form.

The following table lists commands displaying a message or prompt and shows how they differ from each other:

Command
Action and user input
PROMPT (followed by WAIT)
Displays message for the duration of the WAIT command; no user input is required.
STATUSPROMPT
Displays message until another message is displayed; no user input is required.
KEYBOARD
Displays message and asks for keyboard input; text is inserted in the document. The user types information and clicks Continue on the Merge toolbar (or presses Alt + Enter).
GETSTRING
Displays message and asks for keyboard input; text is assigned to a variable. The user types information and presses Enter.
CHAR
Displays message and asks for one-character input; the character is assigned to a variable. The user types one character.
LOOK
No message; checks whether a key has been pressed. If a key has been pressed, the key is assigned to a variable; otherwise, the variable is deleted. The user types one character or nothing (merge does not pause for input).

Reusing commands with subroutines

WordPerfect Office btnbacktotopproc Reference: The Merge toolbar and programming commands

You can create a subroutine to call a set of commands which are repeated several times in a merge. You do not need to add them each time. You can add them once, label them as a subroutine, then return to them (or call them) each time you want them to run.

The three commands used to define and call a subroutine are described in the following table.

Command
Action and user input
CALL(label)
Stops the merge and directs it to execute the subroutine. The label parameter must match the name of the label.
LABEL(labelname)
Marks the beginning of the subroutine. The labelname parameter is a unique name that identifies the subroutine.
RETURN
Marks the end of the subroutine and returns the merge to the line after the CALL command. If you do not add the RETURN command, the merge will continue in an infinite loop or will not continue correctly.

Using multiple files and macros in a merge

WordPerfect Office btnbacktotopproc Reference: The Merge toolbar and programming commands

A merge can consist of more than one data file or form file, and it can include multiple macros. This may be useful if you want to merge different documents with the same data or if you have multiple data sources to merge. There are three ways to connect merge files: nesting, chaining, and substituting.

Nesting

Nesting a file or macro is like calling a subroutine. The merge pauses while the nested file or macro runs, then continues after the nested file has finished. This is useful if you use certain procedures frequently in your merges because you can save them in smaller files.

You can have multiple levels of nesting. A merge file can nest a second file or macro, which in turn nests another file, and so on. The three nest commands are described in the following table.

Command
Action and user input
NESTDATA(filename)
Changes to another data source. After that data has been merged with the form file, the merge returns to the first data source. Include a full path with the filename.
NESTFORM(filename)
Pauses the merge and changes to another form file. After that file has merged completely, the original merge continues. Include a full path with the filename.
NESTMACRO(macroname)
Pauses the merge, plays the macro, then continues the merge after the macro ends. You do not need to add a full path or the .wcm filename extension to the name of the macro.


Chaining

Chaining another file or macro starts that file or macro when the original merge is finished. This is one way to run multiple merges one after the other instead of starting each one manually. Only one chain command is used in a merge file; if there are more than one, the last one is used. The three chain commands are described in the following table.

Command
Action and user input
CHAINDATA(filename)
Merges records from the second file when all records from the first data source have been merged. Include a full path with the filename.
CHAINFORM(filename)
Merges the new form file when the original form file has finished. Include a full path with the filename.
CHAINMACRO(macroname)
Plays the macro after the merge has finished. You do not need to add a full path or the .wcm filename extension to the name of the macro.


Substituting

Substituting another form or data file is another way to change from one merge file to another. However, a substitute command moves the merge immediately to the second file without finishing the original merge file. When this happens, the new merge does not return to the original merge. The two substitute commands are described in the following table.

Command
Action and user input
SUBSTDATA(filename)
Changes to the new data file and begins merging its records. Include a full path with the filename.
SUBSTFORM(filename)
Changes to the new form file and begins executing the merge commands in the file. Include a full path with the filename.

Understanding merge code parameters

WordPerfect Office btnbacktotopproc Reference: The Merge toolbar and programming commands

Most merge programming codes use parameters (also called arguments). In the following table, parameters are enclosed in parentheses and any optional parameters are enclosed in square brackets. When there are two or more parameters, they are separated with a semicolon.


Merge code parameters

You need to enter the correct parameters and arguments as required for the merge code. The following table lists parameters and their arguments.

Parameter
What you do
(expr);(subexpr)
Enter a number, string, variable, command, expression, or a combination of these
(label)
Enter a unique label name
(var)
Enter a unique variable name
(field)
Enter a unique name or field number
(filename)
Enter a filename, including the full path
(macroname)
Enter a unique macro name; the full path is optional and no .wcm extension is needed.
(title)
Enter the title of the dialog box
(prompt);(message)
Enter information to display on the screen
(comment)
Enter a description of what the merge does; this does not display on screen.

Reference: The Merge toolbar and programming commands