Classic Computer Magazine Archive COMPUTE! ISSUE 79 / DECEMBER 1986 / PAGE 76

Mail Merge For SpeedScript

Jerry Starling

This productivity booster lets you produce personalized form letters by merging a SpeedScript word processing document with a file of names and addresses. A disk drive and printer are required.

Many word processors include a powerful feature known as mail merge, which allows you to create personalized form letters. If you're not familiar with a mail merge, here's how it works. First you create a file containing names and addresses (if you operate a business or conduct lots of correspondence, you probably have such a file already). Then you write a form letter with the word processor, leaving special markers in the places where each person's name and address will appear. To perform the mail merge, you tell the word processor which document and address file to use. The program automatically prints out a personalized letter for each person in the file, filling in the special blank spaces with each person's name and address. Although the technique is most often used to print form letters, you can use the same feature to merge any sort of data into a standard form document.

SpeedScript doesn't have a mail merge feature, bur you can accomplish the same goal with this program, "Mail Merge." With it, you can create computer-generated mail with a personal touch. You'll also be relieved of much of the tedium of preparing personalized letters for your club, church, or business. Type in and save the program; then read the following instructions carefully before you attempt to use it.

How To Use The Program

Before you can use Mail Merge, it's necessary to understand some basic facts about how it works. To produce personalized form letters, Mail Merge reads two sequential files. The first file is a document created with SpeedScript and the second is created by an address or database program. I use a commercial database program, but many programs can do the job. If you don't have a database program. Mail Merge can also create the address file (however, it does not have the ability to edit an existing address file). Another option is to use SpeedScript itself to create the address file: Simply type in the data using the format described below; then print the file to disk (note that this file must be printed, not saved, to disk). If you also save the address file from SpeedScript (using a different filename), you'll have the ability to edit the file.

The address file, of course, contains several items of information for each person. In database terminology, the term record is used to refer to each set of information (one person's name, address, city, state, zip code, and so on). Each item within the record is called a field. In a simple address file, the first field in the record might contain the person's salutation (Ms., Mr., Dr., or whatever); the second field could contain the person's name; the third, the person's street address; and so forth.

Mail Merge expects the address file to have a very simple record and field structure. Each field within the record ends with a carriage return (character 13) and the end of each record is marked with an extra carriage return. For instance, say that your address file contains records consisting of a name, address, and city for each person. In each record, a single carriage return appears after the name and address, while two carriage returns appear after the city to mark the end of the record. The complete file consists of a number of these records in sequence.

The form letter is written with SpeedScript and printed (not saved) to disk with SpeedScript's SHIFT-CTRL-P command. If you have some other file that creates sequential files, you can probably use those files with Mail Merge, as well.

The form letter must include special markers to show Mail Merge where to insert information from the address file. Each such marker is a number within square brackets ([ ]). When Mail Merge finds a number in square brackets, it reads a field from the address file. The number inside the brackets tells Mail Merge which field from the current record to print at that place in the form letter. Thus, at various places in the letter you might have the markers [1] and [3]. The marker [1] tells Mail Merge to insert field 1 at that place in the letter. The marker [3] tells the program to insert field 3 at the place where that marker appears. Note that the markers can appear in any order (marker [3] can appear before or after marker [1], and so on) and you can use the same marker as often as you want. For instance, you might want to print the person's name at several different places in the letter.

Another special indicator must appear as the very first line in the form letter. This marker tells Mail Merge how many fields each record contains. It consists of a left square bracket followed by the number of fields and a lowercase v character. For example, this indicator tells Mail Merge that each record in the address file contains five fields:


Mail Merge ignores everything in the document which appears before this indicator, so it also serves as a "start printing" command for the program. Mail Merge stores this value in a string array which it DIMensions with 25 elements in line 120. This means you can merge an address file whose records contain as many as 25 fields. To merge files with more fields, increase the value 25 in line 120 as needed.

A Walk Through

Here's a brief description of the prompts you encounter when using Mail Merge.

•Enter name of letter file. At this prompt, Mail Merge expects you to enter the name of the SpeedScript document (form letter) or other sequential form file which you previously printed to disk.

•Enter name of list file. Enter the name of the address file. If you have not already created an address file, enter a new filename for the file you are about to create.

•Create file or input from disk? Enter C to create a new address file or I to use a file that already exists. If you use an existing file, you'll skip ahead to the Enter date prompt (see below).

•How many variables per letter? This prompt appears only when you are creating a new address file. When it creates the file, Mail Merge needs to know how many fields (variables) are contained in a record. Enter that number (it should be the same as the number in the indicator at the beginning of the SpeedScript form letter).

•Enter name for variable. This name is used as a prompt while you are entering address file data. It will be repeated for each of the fields in the record.

•Enter END when all entries are entered. This is the data entry portion of Mail Merge. The program prompts you with the names you entered in the last step, storing the data you enter for the fields in each record. When you've finished entering all the data, enter END to terminate this section of the program.

•Enter date for letter (M/D/Y)? Mail Merge can insert a date wherever the form letter has the special indicator [date]. You must always enter a date, even if your form letter doesn't use it. Enter the date in the format M/D/Y. The year can be entered as either two digits or four digits. If you enter two digits, Mail Merge adds 19 in front of the digits you enter. For example, the year 1986 can be entered as either 86 or 1986. The month and day can be entered as either one or two digits. Enter 2 for the month of February, 12 for December, and so on. When it prints the letter, Mail Merge converts that date to the usual written format (December 24, 1986). The year can be entered as two digits (which assumes 19nn), or as four digits. The date is checked for validity, but February 29 is not considered a valid date by Mail Merge.

•Press RETURN when ready to input letter. This prompt indicates that Mail Merge is ready to store the form letter in memory. Insert the disk containing the form-letter file and press RETURN. Mail Merge reads the document, examining each line for special Mail Merge markers. As it reads each line, Mail Merge prints a period (.) on the screen. This process takes longer than simply loading the document, so be patient.

•Continuous form or single sheet feed? Mail Merge gives you the option of using continuous form (fan-fold) paper or feeding sheets in one at a time. Press C for continuous form or S for single sheet paper. Note that letters which exceed one page in length cannot be used with the single sheet option, since Mail Merge makes no provision for pausing except at the end of the document.

•Press RETURN when ready to begin printing. At this point Mail Merge is ready to print the final letters. Insert the disk containing the address file and make sure the printer is turned on. When the system is ready to print, press RETURN. Mail Merge proceeds to print a letter for each record in the address file.

•Press RETURN when ready. This prompt appears only if you select the single sheet paper option. It alerts you when it's time to insert each new sheet of paper.

•End of Job. Mail Merge has finished printing all the letters.

Programming Notes

Here's a description of the various sections of Mail Merge.

Lines Notes

100-110 Opening screen display; set maximum size for arrays for number document lines and number variables in list file.

120 Dimension arrays; read data for date conversion routine.

130-160 Input file information.

170-270 Create list file (optional).

280-300 Date formatting.

330-380 Read number of variables list file will contain.

390-500 Read document from; flag lines containing variables.

510-530 Select continuous or single sheet paper feed.

540-550 Request list file disk.

560 Open list file and printer.

570 Read a variable set from the list file; initialize the document line counter.

580 Check for a variable flag in the document line.

590 If no variable is found, print the line as is.

600-690 If a variable is found in the document line, insert variables and print the line.

700 Update document line counter; process next line.

710-720 End of document routine (entered from line 600). Eject page or wait for new sheet. Check for end of job. If not at end of job, read next variable set for next list file.

770-780 Wait for RETURN from keyboard.

790-810 Check for errors in input.

820-840 Data for date conversion routine.

850-880 Input list file variable set and print to screen.

890-910 Break down date elements from M/D/Y format.

920-980 Error message for improper document preparation.