Mail/Merge Support

The product supports two kinds of mail-merge fields.

RTF type mail/merge fields:

First, the RTF type of mail-merge is created using the TerInsertField function, and populated using the TerChangeField function for each field in the document. The TerLocateField function is used to locate the RTF type of fields in the document. The advantage of using the RTF type of mail-merge field is that the field-name is stored separately from the field-data. Therefore, when the data is applied to the field using the TerChangeField field, you can still use the field-name to locate the field again. Click here for the detail description of these Mail-merge functions.

Double-underline type mail/merge fields:

The second type of fields are created by simply typing the field name and then underlining it. Please refer to the merge.rtf file for an example. The advantage of using this type of fields is that you can merge all fields in one call to the TerMergeFields function. The second advantage is that you are able to do merge and print as one step without opening a TE window using the TerMergePrint or TerMergePrintVB functions. In this topic we will explore this simple type of mail merge operation.

The simple mail/merge method consists of two components. The first component involves the user who creates a document containing the data field names. The second component is your application which calls the mail/merge print API to print a mail/merge document replacing the field names with field data.

Creating a Mail/Merge Document: A mail merge document is very similar to an ordinary document. To insert a field name in a document, do the following:

Input the field name using the keyboard.
Highlight the text for the field name.
Select the 'double underline' option from the font menu to apply the double underline style to the field name. The 'double underline' style is used to indicate the field names.

Printing a Mail/Merge Document: A mail merge document must be printed within your program's control. (The 'Print' option in the 'File' menu can not be used to print a mail/merge document).

Your program initiates a mail/merge printing by using the 'TerMergePrint' function. Please refer to the 'Application Interface Functions' chapter for the complete description of this function.

Your application passes the print specification to the 'TerMergePrint' function using the 'StrPrint' structure variable. The 'TerMergePrint' function is called for each record that you wish to merge and print in the document. The following two member variables within the 'StrPrint' structure are used for supplying data for the field names:

MergeFields: This field specifies the pointer to a list of mail merge field names. Each field name must be separated by a '|' character. The list must be terminated by a NULL character. If you do not wish to merge field data, set this field to NULL.

MergeData: This field specifies the pointer to a list of mail merge data strings. Each data string must be separated by a '|' character. The number of data elements in the 'MergeData' array MUST be the same as the number of elements in the 'MergeFields' array. The list must be terminated by a NULL character. If you do not wish to merge field data, set this field to NULL.

Example:

MergeFields="name|address|city|st|zip";
MergeData="Jim|139 Main St|Springfield|MA|02371"

The 'TerMergePrint' function scans the document to extract the field names. If a field name is found in the 'MergeFields' array, the corresponding string in the 'MergeData' is used to replace the field name with the data string in the document.

If the field name is not found in the 'MergeFields' array, the 'TerMergePrint' function sends a TER_MERGE message to the parent window. The 'lParam' argument for this message contains a far pointer to the field name. If your application processes this message, it should return a far pointer to the corresponding data string.

Example of processing the TER_MERGE message:

case TER_MERGE:
if (lstrcmpi((LPSTR)lparam,"date")==0)
return (long)(LPSTR)"Jan 1, 1995";
break;

This example returns 'Jan 1, 1995' as a data string for the 'date' field.