subject: MAIL-MERGE OVERVIEW purpose: After creating a general letter or document, Mail-Merge will allow you to tailor it so that it can be sent to numerous sources. Mail-merge will accept data from a defined import file (or from the keyboard) and plug that data into the generalized document where desired. You can also define if and where to pull in other files or parts of files into the generalized document. Finally, the addresses of selected records can automatically be saved to an "address" file to be used by PC-Label for printing labels or envelopes. example: You are writing letters to accompany your Christmas cards and would like to personalize them. With the recipients of your Christmas cards defined in a database (PC-File, PC-Calc, a comma-delimited file, or two different types of text files) consisting of their names, addresses, etc., the information can be pulled into specific locations of your "generalized" letter. In addition, a personalized paragraph could be placed in the letter where desired. The letter might look as follows: °ĆÄÄÄÄÄÄÄÄÄÄ Bgn Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄÄ´ °.fspec chrstmas.imp °ĆÄÄÄÄÄÄÄÄÄÄ End Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄÄ´ °. ° °ĆÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Tab Line ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ °.LABEL c:\list\mail.add °.GROUP °. °. °. °., . . °.EGROUP °.ELABEL °ĆÄÄÄÄÄÄÄÄÄÄÄ Default Tab Line ÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ° °Dear ., As you can see, my cards are late again! .P>, this has been a hectic year for the Earl family. °. °. °.IF CLOSE_FRIEND=YES c:\list\prsnal.pct °.IF NAME=Button c:\list\spcl.pct 20 10 °.INCLUDE c:\list\vacation.pct ° °. ° °Dick 237 subject: MAIL-MERGE PROCESSING setup: Create the template document. Define the data source between the beginning and ending Mail-Merge Special Lines. These lines can be entered into your text file from the Main Menu by selecting the (L)ines option, then (L)ines special, and finally (M)ailmerge defn. running: Select (P)rint from the main menu and set the Mail Merge toggle to ON. Then press F10. PC-Type II will inspect the document for any errors. If an error is found you will be notified and the Mail-Merge process will be terminated to permit you to correct the problem (e.g., database file cannot be found, or field name specified in document does not exist in the database). If no errors are found, a copy of the document will be saved to disk in a temporary file and the Mail-Merge process will begin. As records are found which match the selection criteria, you will be asked if the record selected is to be used in your document. You can skip the record, accept the record, or accept the record and specify that you want all subsequent matches to be accepted. PC-Type II will begin substituting the data from the accepted record, pulling in specific text from other files, reformatting as requested and deleting extraneous lines such as the Mail-Merge definition lines. Whenever a KEYIN request is encountered (or if you are running Mail-Merge using the Keyboard mode), PC-Type II will pause while you enter the desired text. If you press the Esc key when entering text data, you will be asked if you want to reenter the data, start the current document over again, or skip this document totally. After the document is completed, printing will begin. When the document has been printed, PC-Type II will reload the original document saved on disk and repeat the process. When there are no more records which match the selection criteria, PC-Type II will reload the original file and you will be returned to normal PC-Type II operation. NOTE: This process can be stopped at any time by pressing the Esc key. 238 subject: MAIL-MERGE DEFINITION BLOCK purpose: The definition block describes to PC-Type II where to find the data to be filled into the designated areas in the text. Except for PC-File import data, data fields are not named. The import portion of PC-Type II assigns default names to these other data fields as FIELD1, FIELD2, .... FIELDn. In order to make the field names more descriptive, aliases can be defined for these default names. These aliases, if any, must also be placed within the definition block. (See "Mail-Merge Definition .fieldn" on page 251.) You can also override the data to be loaded into certain input fields or create special fields with specific substitution text. This data also goes into the definition block. (See "Mail-Merge Definition .force" on page 252.) Finally, you can specify field names used in .IF equations within the definition block if the data source is defined as KEYBOARD. With a KEYBOARD data source, all data is entered by the user from the keyboard. The data is entered in the order in which it is encountered. The response to the data for each field name is remembered so the information for any given field only needs to be entered once. With KEYBOARD entry, if an .IF equation (which is used to determine if some external text should be loaded from another file) is encountered, the data for the fields in the equation must already be present. To ensure that it is present, an entry such as . can be made in the definition block. (See the last example on the next page.) NOTE: The entire Mail-Merge definition block is deleted from the document before it is printed. examples:°ĆÄÄÄÄÄÄÄÄÄÄ Bgn Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄ´ °.fspec Define °ĆÄÄÄÄÄÄÄÄÄÄ End Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄ´ In this example, the source for the input data has not yet been defined. Define tells PC-Type II to ask you to define the source before it will begin the Mail-Merge. 239 °ĆÄÄÄÄÄÄÄÄÄÄ Bgn Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄ´ °.fspec c:\list\chrstmas.imp °.force CLOSING,"Merry Christmas," °ĆÄÄÄÄÄÄÄÄÄÄ End Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄ´ This example will use the already defined import file CHRSTMAS.IMP stored in subdirectory LIST on drive C. The standard data normally contained in the field CLOSING will be overridden with the text "Merry Christmas,". °ĆÄÄÄÄÄÄÄÄÄÄ Bgn Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄ´ °.fspec Keyboard °. °. °ĆÄÄÄÄÄÄÄÄÄÄ End Mail-Merge Def. ÄÄÄÄÄÄÄÄÄÄ´ In this example, you will enter all field data via the keyboard. You will be asked for the data in the fields XMAS_LIST and ZIPCODE first, presumably to determine whether text should be brought in from another file through an .IF statement. 240 subject: MAIL-MERGE DEFINITION .fspec purpose: The .FSPEC line in the Mail-Merge definition block defines the source of the data to be substituted into the Mail-Merge document. format: .FSPEC filespec -or- .FSPEC define -or- .FSPEC keyboard discussion: "FILESPEC" is the file specification of a .IMP file defined through the IMPORT option of the Configuration menu. The file specification can contain the drive and path. If no drive is specified, the default drive is assumed. If no path is specified, the default directory is assumed. The file specification MUST contain the filename and the .IMP file extension. This .IMP file contains the information describing the type of the data source, (PC-File, PC-Calc+, ASCII files, etc.), and the selection criteria for which records are to be selected. "DEFINE" instructs PC-Type II that a new .IMP file is to be created at the beginning of the Mail-Merge process. (See "Import" in the Configure section.) When a new .IMP file is created at the start of Mail-Merge, you will be asked if you want to load the new definition into the Mail-Merge definition block. If you answer Y, Mail-Merge will be stopped and you can move the cursor to the 'D' of "DEFINE" and press Ctrl _ to replace "DEFINE" with the actual file specification. If you answer N, Mail-Merge will continue and "DEFINE" will remain in the definition block. "KEYBOARD" implies that all field data normally extracted from a data source will be entered by you through the keyboard. You will be asked to enter the data for each field as it is encountered. However, PC-Type II will remember your answers so you will not have to enter the information more than once per document printed. If you have .IF statements in the document, the data for the fields in the .IF equation MUST have been entered before the .IF statement, or no external text will be brought into the file. If the fields in the .IF statement do not appear first, enter them in the Mail-Merge definition block as standard fields. This works successfully since the entire definition block is deleted from the file before it is printed - so these fields of data will not appear in the output document. 241 examples: .FSPEC c:\list\chrstmas.imp The import file CHRSTMAS.IMP in subdirectory LIST on drive C is used to define the data source. .FSPEC keyboard . You will enter the data from the keyboard. The field ZIPCODE has been used in a .IF statement. It is included in the Mail-Merge definition block so that its data will be available to the .IF statement. 242 subject: MAIL-MERGE DEFINITION .fieldn purpose: The .FIELDn line of the Mail-Merge definition block is an optional entry and should not be used if the data source is PC-File or the keyboard. All other data sources, however, default to the field names FIELD1, FIELD2, .... FIELDn. Since these names are not very descriptive, the .FIELDn records can be used to provide a more meaningful reference to the desired contents of a field. NOTE: even though the .FIELDn record is defined, you can still use FIELD1, ... FIELDn if you desire. format: .FIELDn alias where "n" is the field number and "alias" is the name to be used as a substitute. "n" must be greater than zero and no larger than 128. The alias name can be up to 25 characters in length. (Imbedded blanks are not recommended.) example: Assume your data source is of the ASCII line format as shown below: Jones~Pam 123 S. Addison Redmond WA 98052 Smith~Tom ABC N. Zebra Kent WA 98032 ... FIELD1------- -FIELD2-------- --FIELD3-----FIELD4-FIELD5 PC-Type II's import program will define these fields as shown above. You could define the following alias records: .FIELD1 name .FIELD2 address .FIELD3 city .FIELD4 state .FIELD5 zipcode and use them as "NAME" is used in the line: We are hoping that you, ., can be present at ... 243 subject: MAIL-MERGE DEFINITION .force purpose: The optional .FORCE line(s) in the Mail-Merge definition block are used to force the text presented in the line into all fields in the document containing the field name referenced in the line. The field name referenced MAY but DOES NOT HAVE TO BE a valid field name in the data source. If it is not a valid field name in the data source, then the .FORCE line can be thought of as a convenient location to place phrases which can change from application to application of the Mail-Merge document. If it is a valid field name, then the data normally contained in that field of the source will be overridden by the text in the .FORCE line. NOTE: .FORCE text will not be substituted for standard field data in a .IF statement equation. format: .FORCE fieldname,"text" Fieldname should not exceed 25 characters. The comma is required. The quotation marks around the text are recommended. examples: .force SALUTATION,"Merry Christmas" ... . ., ... If FIRST_NAME is Dick, this would result in: Merry Christmas Dick, .force SET_DATE,"." ... I was born on . in Lakewood, Ohio. ... If the default setting for the DATE STAMP is of the form "weekday month date, year", the above example would result in: I was born on Wednesday April 14, 1943 in Lakewood, Ohio. After making a field substitution, Mail-Merge goes back to the start of the document before searching for the next field. Thus, substituting a new field for an existing field allows the new field to be processed as well. This is the case in the last example. 244 subject: MAIL-MERGE .include purpose: The .INCLUDE line permits you to pull all (or part) of an external file into a Mail-Merge document at a specified location. The material pulled in can contain more Mail-Merge directives. For example, the external file could include its own .INCLUDE or .IF definitions. However, external files should not include a Mail-Merge definition block. Field substitution requests in the external file must refer to the same .IMP source data. NOTE: If Mail-Merge directive errors exist in the information "included", the Mail-Merge will stop since the included files are not pre-checked for errors. For example, if an .INCLUDE statement in an included file referenced a file which cannot be found, then Mail-Merge will issue an error message and stop. format: .include filespec {n {m}} The format of the data after the .include is identical to the format of the Command Line GET or EDIT command. FILESPEC can include a drive and directory. If no drive is present, the default drive is assumed. If no directory is present, the default directory is assumed. The FILESPEC MUST include the filename and extension of the external file to be included. {n {m}} are two optional parameters. If they are not present, then the entire file specified will be included in the Mail-Merge document. If only n is present, then the file specified will be loaded from line n to the end of the file. If both n and m are specified, then m lines will be included starting at the nth line in the file specified. example: The line of text below is brought in from another file. .include c:\list\external.pct 10 1 The line of text above is brought in from another file. If the file EXTERNAL.PCT in subdirectory LIST on drive C contained 50 lines, like: This is the first line of text in external.pct This is the second line of text in external.pct ... then the example would result as: The line of text below is brought in from another file. This is the tenth line of text in external.pct The line of text above is brought in from another file. 245 subject: MAIL-MERGE .if purpose: The .IF line is a "conditional" .INCLUDE line. Unless certain requirements pertaining to the current import source record are met, then the .IF line is ignored. If the requirements are met, then the line will behave exactly as if it were an .INCLUDE line. format: .if (condition) filespec {n {m}} FILESPEC {n {m}} is identical to the description under .INCLUDE. CONDITION is identical to the format for the COMPLEX SEARCH described in the IMPORT section. See that section for details. In summary, CONDITION is an equation relating to the contents of the current import source record being processed. If all the conditions in the equation are met, the result is TRUE and the .IF inclusion will be executed. NOTE:‹The parentheses around CONDITION are ‹recommended. ¨ ‹.FORCE fields will not work in the CONDITION ‹equations. However, the .FIELDn aliases will ‹be substituted and will work. example: Assume the source import record being processed contains the data "Renton" in the field CITY and the data "WA" in the field STATE. ... .if ((CITY="Renton")ō& (STATE="Wa")) external.pct 10 1 .if ((CITY="Kent") ō& (STATE="Wa")) external.pct 20 5 ... In the above example, the conditions for the first .IF line are met, so the tenth line of the file EXTERNAL.PCT in the default directory will replace the .IF line. The condition CITY="KENT" in the second .IF line are not met, so the second .IF line will be deleted from the document. 246 subject: MAIL-MERGE DATA FIELDS purpose: The Mail-Merge data fields are the heart of Mail-Merge for it is here that the actual fields of data from the source import file are substituted. PC-Type II looks for a Mail-Merge data field definition in the document. When it finds one, it determines the type of data to be substituted. If the data to be substituted agrees with a field name in the source import record being processed, then the contents of that field in the record are used to replace the data field definition. format: .{fmt>} .[field description] <..> VARIABLE SUBSTITUTION - Data will be extracted from the data source indicated and excess spaces to the right and left of the data will be removed before substitution takes place. [..] FIXED LENGTH SUBSTITUTION - Data will be extracted from the data source indicated. If the number of character spaces between the brackets is greater than the number of characters in the data source, blanks will be added. If the size of the data source is greater than the space provided, then the data source will be truncated on the right. (This is useful for lining up data in columns.) fmt> OPTIONAL FORMAT DIRECTIVE - This optional feature permits you to reformat a line or paragraph after a variable data substitution has been made. The options are: L - reformat line (left-justified) C - reformat line (centered) R - reformat line (right-justified) J - reformat line (justified at right and left) P - reformat paragraph (left-justified) PL - (same as P) PC - reformat paragraph (centering each line) PR - reformat paragraph (right-justified) PJ - reformat paragraph (justified right and left) NOTE: As data is substituted, the conventions defined by the active Tabs are honored. If paragraph wrapping is ON, then reformatting is normally not required unless you want right justification or centering. If paragraph wrapping is OFF, then reformatting may be required. 247 subject: MAIL-MERGE DATA FIELD - date purpose: The DATE field type will allow you to substitute a date in the DATE STAMP format requested in Configure. Normally DATE works off your system clock. formats: . . DATE* implies the system date will be used. The * is optional, but is recommended to avoid conflicts with data source field names. DATE (MM,DD,YY) implies the date month (mm) day (dd) year (yy) will be used. This allows you to reference a specific date. VALUE is an optional parameter and can be of the form: +n or -n where the + and - signs are required and n refers to the number of days to add to or subtract from the specified date. examples: Assume the DATE STAMP format selected is of the form: Wed Jan 14, 1987 and the system date is October 1, 1988. Today is .. --> Today is Sat Oct 1, 1988. Respond by .. --> Respond by Mon Oct 31, 1988. On ., --> On Sat Aug 13, 1988, . --> Wed Aug 10, 1988 248 subject: MAIL-MERGE DATA FIELD - time purpose: The TIME field type will allow you to substitute a time in the TIME STAMP format requested in Configure. Normally TIME works off your system clock. formats: . .