//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 directives (to define the field names), one or more XMDATA directives (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 directive to define the measurement units which are required by the XTEXT directive, plus any other //GDI directives that you want (i.e. to combine application-generated output with the mail merge output).
The individual field names and data items must be delimited by the vertical bar (|). You can use multiple XMFIELDS and XMDATA directives, 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 directive 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.
