Chapter 8

MERGING WITH WORDPERFECT

 

Dear _______:
We'd like to introduce you to our new _______.  We're sure you'll
find the price of $_______ an attractive buy in today's market. 
Please call _______ for more information at ______.
Form letters like this are typical uses for merging with WordPerfect. To complete the picture, you provide a list of names, addresses, or other variable information in another document; WordPerfect then plugs this text into the blanks of your form document.

Form letters are a popular use of merging, but you can apply the process to building mailing labels, database documents, invoices, and more. You can also use WordPerfect's merge functions to build boilerplate documents, such as legal contracts and business proposals.

This chapter discusses the WordPerfect merge feature, detailing its many commands and functions. You'll learn the basics of merge document preparation, how to use advanced commands to build sophisticated "smart" merges, and how to integrate merges and macros together.

Note that the merge language in WordPerfect 5.1 is almost as rich and complex as the macro language. An entire book is needed to do the merge language justice, and as this is really a book on macros, we can only concentrate on the basics in this chapter (however, future chapters offer additional examples of using merges to build templates or complement macros). As with macros, your own experimentation will help you discover new and improved ways of using WordPerfect's merge commands.

 

MERGE DOCUMENT BASICS

The process of merging is taking data from one file, and fusing it into a "master" document. WordPerfect needs two basic components to perform a merge: a primary document that serves as the "master," and a secondary document that contains the data.

Primary merge files must be standard WordPerfect documents, containing at least one merge command. Typically, the primary document will contain both text and merge commands. The text is entered into all documents created by the merge, and the commands the merge process.

Secondary merge files can take many forms:

Most often, you'll use standard WordPerfect documents and keyboard entry for secondary merge data. DOS text files can be used if you're merging information exported from another word processor, database, or electronic spreadsheet program. The Shell Clipboard (accessible only if you own WordPerfect Shell) allows you to conveniently merge data from any WordPerfect document, or from other document created by a program accessible by Shell (such as PlanPerfect and DataPerfect).


The Primary File

Similar to the WordPerfect macro language, text shown in upper-case and surrounded by braces are merge commands (merge commands are now displayed in bold, however). And as with macros, you enter these commands by accessing them from a menu or pop-up box. Pressing [Shift]-[F9] displays this menu at the bottom of the screen:

1 Field; 2 End Record; 3 Input; 4 Page Off;

5 Next Record; 6 More:

The first five options insert one of the more common merge commands into the document. For example, pressing F enters a {FIELD} command in the document. Many of the merge commands expect arguments (which are terminated with the tilde character, the same as in macros). WordPerfect prompts for these arguments when you enter merge commands. Provide the argument (in the case of the {FIELD} command, the name of the field), then press [Enter]. Or, just press [Enter] to skip the argument. You can always add (or edit) it later.

Pressing M (for More) displays the pop-up box. This box contains all of the WordPerfect merge commands. Many of them will be familiar to you, as they are identical to the commands in the macro language. A few others, pertinent only to merging, have been added. These commands are detailed later in this chapter.

Tip: As a shortcut, you can access the merge command pop-up box by pressing [Shift]-[F9] twice.

You select the commands in the merge list the same as you do the macro commands in the macro editor. Refer to Chapter 4, "Learning the Macro Programming Language," for more details. To exit the box without choosing a command, press the [Esc], Cancel, or Exit keys.

Note that merge commands entered into the document are really special WordPerfect codes. The Reveal Codes screen shows that the merge commands are unique codes, not text enclosed in braces. You can copy and paste merge codes just as you can other WordPerfect codes. If you'd like to delete the code, position the cursor over it and press the [Delete] key.


The Secondary File

The secondary file contains the data you want plugged into the primary document. Secondary documents are divided into fields and records. Each field denotes a variable you want plugged into the primary document. The name (or number) of the field identifies the data so that it can be entered at the appropriate blank in the primary file.

A complete set of fields (for a particular client, proposal, collections letter, or whatever) is a record. WordPerfect repeats the merge process for each record in the secondary file. The merged result is contained in one large file, which you can then edit, format, save, and print.

For example, let's say you're creating a form letter for clients that announces your new address. Each form letter is "personalized" with the client's name and address. For each record in the secondary file, WordPerfect creates a fresh letter, complete with boilerplate text and variable data. Each letter is separated by a hard page. The letters, which are strung together in one document, can now be saved or printed.

NOTE: During the merge process, WordPerfect accesses but does not alter the primary or secondary documents. The resulting merged text is generated as a brand new document. You can use this techniques to create document-making templates where the original is never edited.

The basic secondary merge file contains just three commands:

WordPerfect automatically appends a hard page code -- [HPg] -- after the {END RECORD} command. This code is not necessary, but helps you to see the demarcation of records while viewing the secondary file on the screen. A typical secondary file, with {FIELD NAMES}, {END FIELD}, and {END RECORD} commands, is shown in Figure 8-4.


Executing the Merge

With the primary and secondary documents created (and saved on disk), you can now execute the merge. Follow these four steps (be sure the document screen is empty before starting):

  1. Press [Ctrl]-[F9] (for Merge/Sort).
  2. Press M for Merge.
  3. Type the name of the primary file, and press [Enter].
  4. Type the name of the secondary file, and press [Enter].

MERGE COMMANDS

WordPerfect's 66 merge commands look daunting at first. But you're already at least somewhat familiar with the program's macro commands, you're on your way to learning the merge language. The majority of the merge commands are identical in function to the macro commands of the same name -- for example, the {ASSIGN} command in the merge language serves the same function as the {ASSIGN} command in the macro language.

The following is a list of all merge commands. Those commands marked with an * (asterisk) are identical to those found in the macro language. Those commands marked with a + (plus) are identical to those found in the macro language, expect for minor differences. Commands that are unmarked are unique to the merge language.

* ASSIGN

* BELL

* BREAK

* CALL

* CANCEL OFF

* CANCEL ON

* CASE

* CASE CALL

CHAIN MACRO

CHAIN PRIMARY

CHAIN SECONDARY

* CHAR

+ COMMENT

CTON

DATE

DOCUMENT

* ELSE

END FIELD

* END FOR

* END IF

END RECORD

* END WHILE

FIELD

FIELD NAMES

* FOR

* GO

* IF

IF BLANK

* IF EXISTS

IF NOT BLANK

* INPUT

KEYBOARD

* LABEL

+ LEN

LOCAL

* LOOK

+ MID

MRG CMND

NEST MACRO

NEST PRIMARY

NEST SECONDARY

* NEXT

NEXT RECORD

NTOC

* ON CANCEL

* ON ERROR

PAGE OFF

PAGE ON

PRINT

PROCESS

* PROMPT

* QUIT

* RETURN

* RETURN CANCEL

* RETURN ERROR

REWRITE

* SYSTEM PROMPT

* STEP OFF

* STEP ON

STOP

SUBST PRIMARY

SUBST SECONDARY * SYSTEM

* TEXT

* VARIABLE

* WAIT

* WHILE

NOTE: While the message commands -- {CHAR}, {TEXT}, {PROMPT}, {INPUT}, and {STATUS PROMPT} have the function in merges as they do in macros, certain limitations do exist. WordPerfect does NOT allow you to include cursor positioning or character attributes codes with the message. Other limitations are noted later in this chapter.

Here's a run-down of the unique merge commands, as well as those that use the same name as their macro counterparts, but function differently.

 

CHAIN MACRO

The {CHAIN MACRO} command serves the same purpose as the {CHAIN} command found in the macro language. When the merge encounters this command, it chains off to the specified macro.

 

CHAIN PRIMARY

The {CHAIN PRIMARY} command chains the merge to a new primary document. Chaining doesn't take place until the first primary document has finished.

 

CHAIN SECONDARY

This command chains the merge to a new secondary document. As with {CHAIN PRIMARY}, the chaining doesn't occur until the first secondary document is finished.

 

COMMENT

The {COMMENT} command is identical to the {;} command, used in macros. You use the {COMMENT} command to provide remarks within a primary or secondary file, and to format a primary file for easier reading (see the section "Formatting Primary Files," below, for more information).

 

CTON

{CTON} serves the same general purpose as the {KTON} macro command, See also {NTOC}.

 

DATE

{DATE} inserts the current date, as set by DOS, into the merged document.

 

DOCUMENT

The {DOCUMENT} command includes the entire contents of the indicated document into the merge. The file can be most any size -- from a single word to entire pages. The {DOCUMENT} command is most often used for document assembly, as detailed in Chapter 10, "Letters, Memos, and Boilerplate Correspondence."

 

END FIELD

The {END FIELD} command marks the end of a field in a secondary document.

 

END RECORD

The {END RECORD} command makes the end of a record in a secondary document.

 

FIELD

{FIELD} is used to entry a variable placeholder in a primary document. After the {FIELD} command, enter the field name or number you want to use there. For example, if you want to enter the client's ZIP code at a particular point in the merge, you could use {FIELD}zip~. Remember: to use field names, you must establish the names at the beginning of the secondary merge document, using the {FIELD NAMES} command.

 

FIELD NAMES

The {FIELD NAMES} command declares the names of fields you are using in the secondary data document. The names of the fields can then be used within the primary document. The {FIELD NAMES} command, and the names of the fields, should appear at the very beginning of the document. See the section, "Using Field Names," later in this chapter, for more information.

 

IF BLANK

The {IF BLANK} command checks if a field is blank. Uses the same construction as the {IF} command.

 

IF NOT BLANK

{IF NOT BLANK} is the logical opposite to the {IF BLANK} command; it checks if a field is NOT blank.

 

KEYBOARD

The {KEYBOARD} command temporarily freezes merge execution and allows you to enter the secondary variable data directly from the keyboard. Your entry is included in the merged document. The {KEYBOARD} command is most often used with the {PROMPT} command so that a message of some type is displayed prior to halting the merging. To reactivate the merge (signal that you're done entering text), press the [F9] key.

 

LEN

The merge {LEN} command is almost identical to the {LEN} command used in macros, except that within a merge, the argument can be a full expression, not just a variable.

 

LOCAL

The {LOCAL} command serves as the same function as {ASSIGN}, except that it creates a variable that is used only within the current merge session. After the merge stops, the variable is erased. Conversely, variables you create with the {ASSIGN} command (or any other merge/macro command that creates a variable, such as {TEXT} or {CHAR}) can be shared between all merges and all macros. Note: You cannot assign a local variable with the same name as a label you've already provided in a primary merge document.

 

MID

The merge {MID} command is almost identical to the {MID} command used in macros, except that within a merge, the first argument can be a full expression, not just a variable.

 

MRG CMND

The {MRG CMND} command lets you insert codes, text, and commands into the document that's being created by the merge. The normal function of codes and commands are ignored. The {MRG CMND} command is always used in pairs; the text, commands, and codes between the two {MRG CMND}s are sent directly to the merged document.

 

NEST MACRO

The {NEST MACRO} command functions the same as the {NEST} command found in the macro language. When the macro is finished, control returns to the merge.

 

NEST PRIMARY

{NEST PRIMARY} temporarily nests execution to a new primary merge document. When the nested file is finished, control returns to the original primary document.

 

NEST SECONDARY

{NEST SECONDARY} temporarily nests execution to a new secondary merge document. When the nested file is finished, control returns to the original secondary document.

 

NEXT RECORD

The {NEXT RECORD} command moves the record pointer (the invisible road sign WordPerfect uses to remember the current record it's working with) to the next record. This command is most often used to skip records that don't meet certain criteria. For more details, see the section "Making Smart Merges," later in this chapter.

 

NTOC

{NTOC} serves the same general purpose as the {NTOK} macro command, See also {CTON}.

 

PAGE OFF

The {PAGE OFF} command eliminates the hard page between documents that have been merged (normally, WordPerfect inserts a hard page code to separate each document created by a single secondary file record).

 

PAGE ON

{The PAGE ON} command cancels {PAGE OFF}.

 

PRINT

Use the {PRINT} command to send the merged output directly to the printer. The {PRINT} command is helpful when you don't want to create a separate merged document, or when the merged document is too large to fit in memory.

 

PROCESS

The {PROCESS} command is used to execute a series of commands when they are encountered in a secondary merge files, even if you've created a "smart" merge that scans the records for specific data. The {PROCESS} command is used in pairs; those codes between the {PROCESS} commands are executed the moment they are encountered.

 

REWRITE

Merges are always executed with display off. The {REWRITE} command refreshes the screen and displays the result of the merge so far.

 

STOP

{STOP} is used to terminate a macro. {STOP} has a similar function to {QUIT}, except that it ignores the remainder of the primary file. With the {QUIT} command, WordPerfect reads the remainder of the primary file, and may include it (along with text, codes, and commands) in your merged document. Use {STOP} if you want to halt merge execution, and don't want the rest of the primary document included in the finished merged document.

 

SUBST PRIMARY

The {SUBST PRIMARY} command replaces the current primary document with another of your choice.

 

SUBST SECONDARY

The {SUBST SECONDARY} command replaces the current secondary document with another of your choice.

 

LIMITATIONS OF MERGES

The merge feature is a useful tool in WordPerfect power word processing, but it does have some limitations with respect to macros. You'll want to know about these limitations when you're not sure whether you should use a macro or merge to solve some sticky WordPerfect problem. Even though a merge may appear to be the logical choice, you may be required to use a macro if you want to implement certain capabilities.

 

DIFFERENCES BETWEEN VERSIONS 5.0 AND 5.1

The following is a list of merge codes used in version 5.0 (and earlier), and their WordPerfect 5.1 counterparts.

Version 5.0 Command Version 5.1 Command
^C {KEYBOARD}
^D {DATE}
^E {END RECORD}
^F {FIELD}
^G {CHAIN MACRO}
^N {NEXT RECORD}
^O {PROMPT}
^P {NEST PRIMARY}
^Q {QUIT}
^R {END FIELD}
^S {SUBST SECONDARY}
^T {PRINT}
^U {REWRITE}
^V {MRG CMND}

TERMINATING A MERGE

Many merges start and finish in a matter of seconds. Of course, this all depends on the speed of your computer the complexity of your primary and secondary files. If the merge takes more than a few seconds, or pauses to allow user entry, you may have occasion to terminate it prematurely. For example, you may want to stop the merge if you discover that you're entering the wrong information for a group of clients.

There are two ways to terminate a merge:

 

FORMATTING PRIMARY FILES

As with macros, formatting the text and commands in a primary merge document makes the file easier to read, and -- if a problem should occur -- diagnose. Unlike macros, however, you can't simply add new lines and tabs to format merge data. The reason: every character, including hard returns and tabs, entered into a primary document is repeated when the document is merged. Hard returns you use for formatting the primary file add extra blank lines in the finished merged document. Likewise, extra formatting tabs are passed along to the merged document as tab characters.

To format a primary (or secondary) merge document for readability, you must use the {COMMENT} code to break the lines, such as:

{PROMPT}Enter your name here~{COMMENT} ~{KEYBOARD}

The comment stretches from the end of the first line to the beginning of the second line (note the tilde before the {KEYBOARD} code. The hard return is entered after the {COMMENT} code. Because the hard return is part of a comment, WordPerfect doesn't include it in the merge. Of course, you can add other characters within the comment, as well, including additional hard returns, tabs, and commenting remarks. While adding {COMMENT}s just to format the merge document may seem like a lot of hassle, if the document involves is any complexity at all, the {COMMENT} commands and formatting will pay off in the end.

 

USING FIELD NAMES

WordPerfect 5.1 lets you use field names or field numbers in primary documents. The names or numbers refer to specific fields in the secondary merge file. Field names allow you to refer to fields by name, instead of some easily forgotten number. For example, compare the following primary merge documents. One uses numbers and the other names. You'll find that referring to fields by name makes it easier to create, refine, and edit your primary merge documents.

Document With Field Numbers

{FIELD}1~ {FIELD}2~
{FIELD}3~
{FIELD}4~, {FIELD}5~  {FIELD}6~

Dear {FIELD}1~ {FIELD}2~: 
Thank you for allowing us to review your resume for the position of
{FIELD}7~. 

We have carefully reviewed your qualifications and find we do not
have an appropriate position for you at this time.  We will keep your
resume on file for six months, and should a position that matches
your qualifications develops, we will contact you.

We appreciate your interested in employment at <name of company>, and
wish you continued success.

Sincerely,


Document With Field Names

{FIELD}firstName~ {FIELD}lastName~
{FIELD}address~
{FIELD}city~, {FIELD}state~  {FIELD}ZIP~

Dear {FIELD}firstName~ {FIELD}lastName~:

Thank you for allowing us to review your resume for the position of
{FIELD}position~.

We have carefully reviewed your qualifications and find we do not
have an appropriate position for you at this time.  We will keep your
resume on file for six months, and should a position that matches
your qualifications develops, we will contact you.
    
We appreciate your interested in employment at <name of company>, and
wish you continued success.


Sincerely,


To use field names, you need only "declare" the names at the very beginning of the secondary merge files (these names should precede any fields, codes, or other text). For each secondary merge file that uses field names, you should include the following commands and text:

  1. Start the document with the {FIELD NAMES} command.
  2. Enter each field name, and end it with a tilde.
  3. For readability, add a hard return after each name.
  4. Repeat the process for each field.
  5. After the last name, add a second tilde (this terminates the {FIELD NAMES} command.
  6. Include an {END RECORD} command. This tells WordPerfect that the data to follow are the actual records.

TIP: fter inserting the {FIELD NAMES} command from the merge command list, WordPerfect will prompt you for the names you want to use. Enter the name, then press [Enter]. Repeat this process until all the names are entered. After the last name, press [Enter] a second time. WordPerfect will automatically end the field names with the terminating tilde and the {END RECORD} command.

When entering the data for each record in the secondary file, WordPerfect will prompt you for the desired field. Because you've declared names for the fields, WordPerfect will ask for the fields by name: Name, Address, City, State, ZIP, and so forth. This makes it easier to enter the field information, and helps reduce the chance of errors.

 

MAKING SMART MERGES

In WordPerfect 5.1, you can give your merges some intelligence. This intelligence is imparted by using the now-familiar {IF} and {CASE} commands, as well as the other conditional branching commands found in the merge language.

Perhaps the best example of a smart merge is entering some type of search criteria and using it to locate a specific record in a secondary data file. Once found, that record is used to merge with the primary file, and the finished document results.

The secondary file is constructed in the usual manner. For ease of use, the fields should be named. Here's an example of a secondary data document used as a client address file.

{FIELD NAMES}Name~Address~City~State~ZIP~~{END RECORD}
=======================================================
Fred Silverstein{END FIELD}
PO Box 1187{END FIELD}
New York,{END FIELD}
NY{END FIELD}
10000{END
RECORD}=======================================================
Mickey Mouse{END FIELD}
1000 Main Street{END FIELD}
Santa Cruz{END FIELD}
CA{END FIELD}
95000{END RECORD}
=======================================================
Bill Bailey{END FIELD}
Apt A{END FIELD}
Anytown{END FIELD} IL{END FIELD}
42000{END RECORD}
========================================================


The primary file includes a prompt so that the user can enter the search criteria. Also in the primary file is an {IF} construction that tests the "Name" field against the Look_Name variable. If there's a match, then the name and address is merged. If there's no match, then the merge continues to the next record.

{TEXT}Look_Name~Enter the client name~{COMMENT}
~{LABEL}loop~{COMMENT}
~{IF}"{VARIABLE}Look_Name~"!="{FIELD}Name~"~{COMMENT}
~{NEXT RECORD}{COMMENT}
~{GO}loop~{COMMENT}
~{END IF}{COMMENT}
~{FIELD}Name~
{FIELD}Address~
{FIELD}City~, {FIELD}State~  {FIELD}ZIP~{COMMENT}
~{QUIT}

You can modify this short primary document so that you can search on any criteria, using any field names. Note the use of the {COMMENT} commands to format the primary file, and make it readable.

 

MERGE TOOLS

WordPerfect uses special codes to denote merge commands that have been entered into primary and secondary documents. These commands can be viewed within WordPerfect (unless you've turned the display off, using the Merge Codes Display command, as detailed below). However, these codes don't appear when the document is printed. If you'd like to make these codes visible for printing, you can convert them to text using the MRGTOTXT.WPM (for merge-to-text) macro, provided on the Applications Disk.

Conversely, you can use the TXTTOMRG.WPM (for text-to-merge) macro to convert text into merge codes. You can use the TXTTOMRG.WPM macro (which included on the Applications Disk) to re-convert merge codes that you've translated to text. Or, you can use the macro as a merge-writing tool, where you can compose a merge document completely in the WordPerfect editing screen.

To use either macro, press [Alt]-[F10] and type MRGTOTXT or TXTTOMRG, as desired. Press [Enter]. The document will then be converted. Conversion time is approximately 30 codes in 10-15 seconds, depending on the speed of the computer. Extremely long or complex documents may take up to several minutes to convert. However, the average merge document takes less than 20 seconds to convert.

MRGTOTXT.WPM always converts the entire document (minus footnotes, headers, and other special editing structures, which you can convert separately). You can start the macro anywhere within the document.

TXTTOMRG.WPM only converts from the current cursor position onward. The macro finds merge code text that is capitalized and enclosed in braces, such as {STOP} or {NEST PRIMARY}. If the macro finds a code it doesn't recognize -- {NSET} for example, instead of {NEST} -- it will stop and warn you that no matching merge code exists. You can either skip the code and restart conversion, or edit the code, and begin again (before restarting, position the cursor at the beginning of the edited code).

MRGTOTXT.WPM performs the same basic function as the CODES macro supplied with WordPerfect 5.1, but it only converts merge codes. It leaves all other WordPerfect codes alone. With the codes converted, you can print the document and the text for the codes will appear on paper. You'll probably want to save the converted document with a unique name, so that you don't erase your original merge document. Of course, if this happens, you can use TXTTOMRG.WPM to restore the text back to merge codes.

You'll find additional tools you can use to create merge documents in the next chapter, "Letters, Memos, and Boilerplate Correspondence." Among the topics you'll find details on building document templates using the merge feature, using the {DOCUMENT} command for document assembly, creating intelligent document assembly merges to connect any number of WordPerfect documents together, and a handy macro and primary merge document for simplifying the task of making secondary data files.

Note that you can turn the display of merge commands within the WordPerfect editing screen on and off. Normally, it's on (merge commands displayed). You can turn it off by following these steps:

  1. Press the Setup key ([Shift]-[F1]).
  2. Press D, E, and M to access the Merge Codes Display command.
  3. Answer No to turn the merge command display off.

With the merge commands invisible, you can still use the MRGTOTXT.WPM macro, as the merge codes remain in the document.

 

IMPORTANT TOPICS

This chapter detailed the basics of the WordPerfect merge language.

  1. Press [Ctrl]-[F9].
  2. Press M.
  3. Enter the name of the primary file; press [Enter] when done.
  4. Enter the name of the secondary file; press [Enter] when done.

---

 Top Contents

WordPerfect 5.1 Macros and Templates
Electronic Edition
Copyright 1990, 1997, Gordon McComb.  All Rights Reserved.
First published by Bantam Electronic Publishing, 1990.
http://www.gmccomb.com/