Reviewed May 2008

//XMFIELDS, fldnam1|fldnam2|...|fldnamN

//XMDATA, data1|data2|...|dataN

//XTEXT, left, top, right, bottom, fspec{, pageoffset}

These commands facilitate mail merge with XTEXT.

Mail merge is supported only by XTEXT documents in RTF or SSE format. To create the template, edit the document and insert field names by highlighting them and pressing Control-D to give them the double underline style. To perform the merge/print operation, insert one or more XMFIELDS statements (to define the field names), one or more XMDATA statements (to define the field replacement data), and one or more XTEXT directives (one for each page or rectangle of output). You will also need at least a SETMAPMODE statement to define the measurement units which are required by the XTEXT statement, plus any other //GDI directives that you want (i.e. to combine application-generated output with the mail merge output).

Syntax:

The individual field names and data items must be delimited by the vertical bar (|). You can use multiple XMFIELDS and XMDATA statements, if you have a lot of fields (or long data). The important thing is that the Nth data item matches up with the Nth field name. (So in the example above, all occurrences of "fldnamN" in the document would be replaced by "dataN".

XMFIELDS and XMDATA both require a single comma after the name of the directive, but after that, the fields are delimited with |. Fields may contain commas and quotes but they are treated like any other character.

The optional pageoffset parameter is used to specify the starting position within the fspec document for the merge. Use negative numbers for page numbers, positive for byte offsets. (-1 = page 1, -2 = page 2, etc.)

Note that the XMFIELDS and XMDATA definitions remain live for the duration of the spool operation (i.e. the processing of the text file containing those directives, not the RTF documents reference by XTEXT). Also note that the XTEXT statement used for the mail merge operation is identical to that previously documented for printing regular XTEXT text. (The only difference between XTEXT mail merge/print and regular XTEXT printing is whether there are fields defined which match up with fields in the document. So you could, for example, define a set of 30 fields and corresponding data items, then issue several XTEXT commands which may or may not reference any of those fields.)

Example:

//SETMAPMODE,LOENGLISH

//XMFIELDS,Name|Address|City

//XMDATA,Jack|123 Main St.|Woodland Hills

//XTEXT,50,50,800,1000,mydoc.rtf,-1

^L

//XTEXT,50,50,800,1000,mydoc.rtf,-2

In the above example, we are printing a 2 page mail merge document. Note the need for the chr(12) (appearing as "^L") to mark the page break.

History

2008 May, A-Shell 5.1.1111:  Added to GDI Printing Directives.