Getting the Most from Lantica's Sesame Database Manager
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . October 7, 2024  1:16 am. PST

Introducing WordMerge Lite

How to get WordMerge Lite

"WordMerge Lite is really pleasant to use."  —Eugene L.

"Worked perfectly. Thank you for a great product as well as great support."  —Greg M.

"You've done it again — WordMerge Lite is a great piece of work, and so is your documentation on it."   —Jon M.

I used it and it worked like a charm.  —Cliff S.

"Just spent the weekend incorporating WordMerge Lite into all our Sesame applications. It's going to make my life so much easier!... Thanks for an exceptional contribution to the Sesame community. [more] Don N.

[All comments unsolicited]
 

A shorter version of the following review, which does not include the additional sections listed below, appears in the February 2006 issue of Inside Sesame. If you've already read that review, you can use the links below to skip to any section in which you may be interested:

Start where the Inside Sesame article leaves off
Big difference #3 — embedded images
The three types of WordMerge Lite files
WordMerge Lite's
user modifiable variables
Protecting WordMerge Lite settings
WordMerge Lite's
User Defined Functions
Requirements/compatibility
Known issues and troubleshooting

  • Viewing/printing merged docs
  • File naming
  • Folder naming
  • Page break problems
  • Merge fields not merging data
  • Words in output doc running together
  • Merged image sizing
  • Adding/enhancing merge fields
  • Turning off Word's Auto-Formatting for asterisks

WordMerge, one of the most versatile ways to merge your Sesame data with documents and labels, has been through a number of revisions since it appeared in Appendix 2 of the Sesame 1.0 Programming Guide. The "Subscriber Express" index at www.insidesesame.com/indexes/index_search_form.asp (run a Universal Search on "wordmerge") will list the Inside Sesame back issues containing details on these changes.

How WordMerge works
With WordMerge, you create your merge docs or labels in Microsoft Word and use its Mail Merge facilities to link them to the data source file produced by the WordMerge program you add to your Sesame form. When you click the WordMerge button, a picklist of merge docs displays. You select one, then choose whether to merge just the current record or all the records in the result set. WordMerge then generates the data source file and opens the selected doc in Word where the data is merged in.

Setting up WordMerge
WordMerge requires certain setup steps that involve the WordMerge program as well as the merge documents. To start, you have to decide which elements (fields) you'll want to use in any of your merge docs, then either hardcode them into the WordMerge program or list them in a text file that the program can read in.

With the first step done, you then run the WordMerge program to generate an initial data source file to link to your first merge doc. Problem is, WordMerge won't run until you have at least one Word doc where WordMerge expects it. And you can't finish a merge doc in Word until you have that data source file to link it to. It's a kind of Catch-22. You have to put a Word doc (any Word doc will do) in the folder where WordMerge expects it, then run WordMerge and select it. Only then — now that you have a data source file to link to — can you finish "configuring" your first merge doc.

Now finalize the merge doc by linking the data source file to it, inserting the merge fields, and becoming familiar with the various buttons and options on Word's Merge Toolbar. If any of the merge fields are dates, numbers or money, you're still not done. You'll need to apply Word formatting switches so dates don't come out like "2006/02/09" and numbers and money don't come out as "147.500000".

Later, should you need to add some previously existing or new fields to WordMerge's data source file, you have to be careful how you go about it. A Word merge doc will reject a data source file that doesn't conform to what it expects.

 All this is lot to ask of someone who isn't very accomplished in Word or Sesame.

WordMerge Lite simplifies things
WordMerge has a lot of strengths, but it has weaknesses as well, in addition to being difficult for many to set up. That's why we went back to the drawing board here at the Inside Sesame Labs and designed WordMerge Lite.

Calling it "WordMerge" Lite isn't really fair since, unlike WordMerge, all the merging is done in Sesame instead of in Word. But WordMerge Lite still involves Word documents, even though they're more like Q&A for DOS merge documents in the easy ("Lite") way you set them up to merge your data.

Just spent the weekend incorporating WordMerge Lite into all our Sesame applications. It's going to make my life so much easier! Until now, I had been building custom layouts for every form which required a merge print, simply because all the other work-arounds for not having a bundled word processor were much too complicated to use or train people on. This one is truly cut and paste for the "Sesame person" and point and click for the user.

We run all our applications as client-server to a Linux box, so this is truly an elegant solution for us, and puts some of the power back into the user's hands where it belongs. Now if we could do the same thing for on-the-fly reports!

A couple of notes regarding minimum requirements. I had no problem getting your program to work on a Windows 98 machine with Word 2000 installed.

Also, I was able to use Open Office 2 with very good results as well. This might be worth mentioning as it is a very good (free) alternative to the Office bundle if you just need some simple mail merges.

Thanks for an exceptional contribution to the Sesame community.

Don Newlin
City of Lloydminster, Alberta, Canada

Like WordMerge, you add a Merge Print or similarly-named button to your form in Designer, then paste in the WordMerge Lite program. But with WordMerge Lite that's all you need at the Sesame end. And what you have to do at the Word end is vastly simplified.

Note: WordMerge Lite has also been used successfully with merge documents created in Open Office's word processor as well as WordPerfect X3.

A sample database and Word merge doc are included in this month's subscriber download file. In our informal testing, WordMerge Lite worked well in Windows XP with Word 2000 or later. We'd like you, Dear Reader, to give WordMerge Lite a try using the sample database and merge doc. Let us know how you like it, and tell us what, if anything, you think would improve it.

Big Difference #1
With WordMerge Lite you don't need a formal Word merge document with all that that entails. Instead, you take a regular old Word document and add plain text merge tags to it that serve as placeholders for the data. Word's mail merge facilities aren't used at all. No data source file is required, so no linking is necessary. There's no merge toolbar, no data view vs. merge field view, and no having to print using Word's special Merge Print button.

Uses Q&A-like merge field tags
With WordMerge Lite you add your merge fields as simple tags like *Company* to match the Company element/field in your Sesame form. This involves more typing than WordMerge's way of inserting your merge fields from a picklist, but it does away with everything WordMerge requires just to get to the point where you can do that. Simply typing *Company* where you want the company name to go is pretty easy and intuitive. And it's more familiar to those coming from Q&A for DOS in that they can export their existing Q&A merge docs to Document ASCII and open them in Word with the merge fields they'll need already there.

(The WordMerge Lite program prints a field names reference list you can use when adding your field tags to your merge docs.)

At the Sesame end, there's no need specify which form elements (fields) to include in the data source file because no such file is involved. There's no need to go into programming or update an elements list to add, remove or change the fields to include in your merge docs. WordMerge Lite is natively aware of all the elements on your form and simply replaces the field tags in the target document with the corresponding data from those fields in your Sesame records. If you want to include a new field, you simply add the tag for it to the applicable merge doc(s) And WordMerge Lite will merge to it. No changes are required at the Sesame end.

But how does WordMerge Lite merge data with a doc that isn't a real Word merge doc? We'll get to that further ahead. For now, here are a few other ways that WordMerge Lite simplifies things.

No more Word 'formatting switches'
With WordMerge, merge documents can require tricky Word formatting switches to convert Sesame dates, times, numbers, money, and boolean values into more customary formats. WordMerge Lite takes care of all this with its own internal data formatting functions.

Supports double quotes and carriage returns
WordMerge Lite
handles double quote marks in data as well as carriage returns in multiline fields — two things that WordMerge can't. With WordMerge Lite, these appear in the merge document exactly as they appear in the database record.

More previewing/printing options
WordMerge Lite
does single or multiple record merges just like WordMerge by generating merged docs that open either in your browser or in Word (your choice) for previewing and printing. Each has its advantages, as you'll see.

Automatic saved copy of the merged doc
WordMerge Lite
retains a copy of the merged doc until it is overwritten the next time you merge to the same doc. This gives you the opportunity to archive a copy of a fully merged doc along with the option of emailing it as a file attachment.

Supports merged variables
For those who know their SBasic, WordMerge Lite can pass variables to the merge doc. For example, you could conditionally fill a vPara1 variable with text for certain records, and merge it to the matching *vPara1* merge field in the target doc, or store the result of a calculation in a variable and merge it to the matching merge field. If the variable happens to be blank for some records, the merge field tag for them simply disappears, just like any blank merge value.

XLookups are just another mergeable variable. You can run any "@X"-family command from the WordMerge Lite program, manipulate the retrieved data to suit, and replace the corresponding merge field in the target doc with it. There’s a section in the WordMerge Lite program reserved for custom merge variables like these.

In the sample database's WordMerge Lite program, you'll fine a commented out @XLookupAll demonstration example. When run in Sesame Runtime, the *vMyVar1* merge field in the WordMerge Lite Sample.doc will get the vMyVar1 variable containing the last names of all customers in the database whose last names begin with the same letter as the merged customer, with any duplicate names removed.

Merged image support
Both WordMerge and WordMerge Lite support static images such as a company logo in the document. But WordMerge Lite can merge variable images as well. So if you have an image field in your records, you can merge print that image right along with the rest of the record's data.

WordMerge Lite can even scale your merged images on-the-fly. By default, WordMerge Lite's vImgScale variable scales merged images to 75% of their actual size for merge printing, but you can adjust the scale factor by setting a larger or smaller value. Setting vImgScale to 100 merges your images at 100% of their actual size.

Personal settings editable on-the-fly
WordMerge Lite supports "sticky" preference settings for each user. The user can choose where to store their own merge docs, where to output/display them for printing (Word or browser), and how much to scale (up or down) any merged images. The application doesn't require password protection for this to work because each user's preferences file is stored in their own Sesame working directory and isn't dependent on a User ID.

WordMerge Lite's merge document selection menu includes an Other Options submenu with selections to view current personal preferences, change a preference, and print a list of element names to use as a guide when creating their own merge docs in Word.

WordMerge Lite easier to deploy
If you're an application developer with a client who needs merge printing, you'll find WordMerge Lite easier to deploy. With WordMerge, you normally need to set up a bunch of things for the client in advance and give them an initial data source file along with a linked Word merge doc to get them started. With WordMerge Lite, all they'll need are simple instructions on how to create their own merge docs that'll automatically be added to their WordMerge picklist of available merge docs.

If you're the in-house developer at your company, you'll find that WordMerge Lite enables co-workers to easily create their own merge docs after a brief orientation.

WordMerge Lite lets you change a number of key settings on-the-fly without having to go into the programming in Designer. You can easily change settings such as where your merge docs and any merged images are stored, the scale (size) factor for any merged images, and whether to display your output in Word or your browser.

Big Difference #2
Now we'll take up the question posed earlier — How does WordMerge Lite merge print to a Word doc that isn't a true Word merge doc?

When you've finished composing the document in Word and have added your merge tags, you save the doc as a regular Word file in the usual way.

Then you do one more thing — you use Word's Save As Web Page option to save it again, this time as an ".htm" file. It's this .htm or "Web page" file — a copy of the Word doc — that WordMerge Lite merges your data with.

Sesame can't merge data with native Word files because they're binary files. Open a Word .doc file in Notepad and you can't make sense of it. Neither can Sesame. But Sesame can read and process a text-only .htm file created by Word because htm/html (aka "Web page") files are nothing more than ASCII text.

Word 2000 and later versions do a good job of rendering native Word docs as .htm files. The .htm versions contain a lot of Word-centric HTML encoding — so that they'll look the same when opened in Word as the original Word docs they came from. But that's beside the point because you won't be using these .htm files on any Web site. All WordMerge Lite uses them for is to merge your data for printing. It's these .htm file versions of your Word docs that appear on your WordMerge Lite picklist (sans their .htm extensions) when you click the Merge Print button. And they're what the WordMerge Lite program chews through to produce your final merged docs.

The only additional step involved is saving the Word doc as a Web page .htm file after you've designed or redesigned it.

So if you can train your client (or co-workers) on how to add the merge tags to a doc then save it (no-brainer), then save it again to an .htm file (a couple of clicks), that's likely to be all the training they'll need.

WordMerge Lite goes to work when you select one of your merge docs. It makes a copy of the doc then replaces the field tags with the data from your record(s). It saves the resulting merged doc with either a ".doc" or ".htm" filename extension (your choice) then launches Word (or your browser) to display it for printing.

WordMerge Lite doesn't touch the original Word doc. It's always there for you to edit, save, then resave As Web Page to update the corresponding .htm file. WordMerge Lite it makes its own internal copy of the .htm file, then generates a new merged file with "_merged" tacked onto its filename.

Unlike WordMerge, when printing to Word with WordMerge Lite, you won't get that irksome prompt to save the merged doc when you quit Word after printing. But you can still save a copy of it if you want. 

For all but the most complex merge docs, WordMerge Lite's setup is fast and easy. You simply compose the document in Word, adding your merge tags, and apply any fonts, enhancements or layout options you like (including Word tables). You save the doc to the specified folder, then save it again As Web Page with an .htm extension to the same folder. You can now merge print to it.

When the original WordMerge is better
There are some cases where the original WordMerge is the better choice:

  • For docs where WordMerge Lite's internal data formatting functions can't replace the special Word merge field formatting switches you need. (WordMerge Lite's user defined functions are modifiable, however.)
     
  • Where you need programming in the merge document itself, or programming-like features such as Word Fields, IncludeText, AutoText, auto-merging other Word docs, or the like.
     
  • Where the document layout is exceedingly complex or printed elements need to be minutely positioned (as in printing to preprinted forms). In this case you can save the doc to an .htm file and see how Word renders it. If it meets your requirements, then you can use it with WordMerge Light.
     
  • Merge printing to label sheets is a job better suited for WordMerge or a Sesame data export. Word contains predefined label templates for all the popular label styles and sizes, and you need Word's merge facilities to merge data to them.
     
  •  If you're not using Windows 2000/Word 2000 or a later version of either.

For most merge printing needs, WordMerge Lite is far easier than WordMerge to get going with, particularly if you've never used WordMerge or you're not skilled with Sesame or Word.

Trying out the sample files
To make it easy for you to become familiar with the way WordMerge Lite works, the February 2006 Inside Sesame subscriber download file includes some sample files.

Wordmerge_Lite.dsr/.ddt is a modified version of the sample Customers.db application that comes with Sesame. A multiline field and an image field have been added to it (no images are supplied) so you can test how WordMerge Lite works with these if you like.

You can try out WordMerge Lite without having to change any of its programming variables by following these steps:

  1. Copy the Wordmerge_Lite.dsr/.ddt files into your C:\Sesame\Data folder.
     
  2. Create a new folder in C:\Sesame (not C:\Sesame\Data) named WMLDocs. Place the Wordmerge Lite Sample.doc into this new folder.
     
  3. Open Wordmerge Lite Sample.doc in MS Word 2000 or a later version.
     
  4. Click File / Save as Web page. If Word offers types of Web files to save to, chose plain Web Page (* .htm; *.html). Do not use the "Filtered," "Single File," ".mht," or ".msohtm" options in some versions of Word. Save the .htm file to the same WMLDocs folder.
     
  5. Start Sesame Designer, open Wordmerge_Lite.dsr, and click the Preview Application button.
     
  6. In Preview mode, open the Main Form in Search/Update mode and press F10 to retrieve all the records.
     
  7. Click the Merge Print button and you'll get a picklist with Wordmerge Lite Sample (the .htm extension doesn't show) and Other Options selections.
     
  8. Turn on your default printer and click Other Options. From the Options menu, click Print Field Names List.  Your printer should print a one-page list of Wordmerge_Lite Main Form element names and labels in alphabetical order.
     
  9. Click the Merge Print button again. This time select Wordmerge Lite Sample.
     
  10. From the next picklist, click THIS record only.

The document should open in Word with the data merged. It might not look quite right because Word will probably be in Web Layout view, so click View / Print Layout to see what it'll look like when printed. Go ahead and print the document if you like.

  1. Exit Word and return to your database.
     
  2. Press F7 for a new search, type wilman;hiller in the Last (last name) field, press F10, and Sesame should find three records.
     
  3. Click the Merge Print button. This time, select ALL Retrieved Records and answer YES at the confirmation prompt to merge them all.

The three merge docs should appear in Word. Click View / Print Layout to see what they'll look like when printed. (This view shows the page breaks as well.)

To print a merged image to either .doc or .htm output, add one to a record's Photo field, then print the recordto the WordMerge Lite Sample merge doc. If the image prints too large or small, adjust the Set Merged Images Scale option then retry. If the image doesn't print at all, make sure you've got the path right. Double-click on it in the record to find out the image element's value, such as pics\bob smith.jpg., then use the Set Merged Images Path option to specify the beginning portion of the path, such as c:\sesame\ for images stored in c:\sesame\pics.

To see how the merge doc looks in your browser, click Other Options on WordMerge Lite’s menu and select Set Output to .doc or .htm. Replace the .doc with .htm and click OK. Now merge print the doc. When it appears in your browser, select File / Page Preview to get a realistic view of what it will look like when printed.

Any header and footer codes in your browser’s File / Page Setup will also print, and your browser’s page margins may supersede those in the doc. If you don’t want to change your browser’s Page Setup for WordMerge Lite, you can always do your merge printing in Word.

You’ll probably find, though, that sending your merged output to the browser will be noticeably faster since browsers are generally more nimble and start faster than Word. After all, the .htm file you’re opening is native browser file anyway.

Creating your own merge docs
After you’ve played around with the sample files enough to see how WordMerge Lite works, it’s time to start creating your own merge docs. Simply compose them in Word, adding your merge field tags as you go.

If you're using asterisks to define your merge fields, Word may attempt to "AutoFormat" them, removing the asterisks and converting the text  to boldface. You can turn this off via Format / AutoFormat / Options.

When adding your merge fields, be sure not to leave spaces between the element name and the start and end delimiters:

Incorrect: *First Name * or * First Name* (trailing / leading space)
Correct: *First Name* (no trailing or leading space)

When enhancing a merge field, be sure the enhancement includes both the start and end delimiters:

Incorrect:  *Amount Owed*  (the asterisks are not bolded along with the field name)
Correct:  *Amount Owed*  (the asterisks are also in boldface)

When you’re done composing the document, run a spell check on it. For any of your merge fields that Word flags as misspelled words, click the Add to Dictionary button.

Save the document to the C:\Sesame\WMLDocs folder (or whatever folder you’ve specified for your WordMerge Lite docs), then save it again to the same folder as a "Web page" .htm file.

Important: When using File / Save as Web page, if Word offers different types of Web files to save to, chose plain Web Page (* .htm; *.html). Do not use the "Filtered," "Single File," ".mht," or ".msohtm" options in some versions of Word. Save the .htm file to the same WMLDocs folder.

Always choose Replace existing file if Word offers save options.

The following sections are not included in the WordMerge Lite review in the February 2006 issue of Inside Sesame.

Big Difference #3 — embedded images
Static images work well with WordMerge Lite but differently than in WordMerge. It won't require any more work on your part, but does merit a  discussion of its own. If you're not using any static (embedded) images in your original Word doc, you can skip this section.

You've probably pasted or inserted an image in a Word doc — a .bmp, .jpg or .png file of your company logo, perhaps — then resized the image to fit. When you saved the doc, that image became a part of it, embedded in the doc.

Now, WordMerge Lite can't work with your Word docs directly because they're binary files. WordMerge Lite works only with the ASCII .htm files that you create from your  Word docs. But ASCII files, by definition, can't contain images — they can only contain links to them. So how does WordMerge Lite deal with this?

When you save a Word document containing an embedded image to an .htm file (Save as Web page), Word automatically creates a subfolder under the folder where the document resides. It coughs up a copy of each embedded image in the doc and saves it to that new subfolder.

For example, if Prospects.doc (containing an image) resides in a folder named MergeDocs, Word will name the new subfolder Prospects_files. The images that Word extracts from Prospects.doc and places in this new subfolder are assigned new names by Word, names like image001.jpg, image002.jpg, and so on. None of this alters the original Word doc, and it's transparent and automatic, requiring no additional know-how or steps on your part.

This way, when Word generates the .htm file — Prospects.htm in the above example — it can insert in it links to the external image files that will tell the browser (and Word, if you opt to merge print your merge docs in Word) where to find them.

Note: To get a high image quality for your merge docs in Word, click Tools / Options. On the General tab, click the Web Options button. On the Pictures tab, under the Target Monitor section, select your screen size and set Pixels per inch to 300 to start with. You can always adjust these later if needed.

Word will also generate a filelist.xml file and put it into that same subfolder where it put the copies of the images. There's no need to get into xml here, but this ASCII file contains references both to the image filenames in the subfolder and to the .htm document that contains the links to them. Filelist.xml plays a security role and Windows needs it. If you attempt to rename or move the subfolder, Windows will warn you that the links to the .htm file that use the images referenced in it will be broken. If you do it anyway, or delete filelist.xml, you'll get a warning message every time you go to print a merge letter, and your images may disappear from it.

Note: If, after creating some merge docs in Word and saving them as .htm files, you decide to start using a new folder for your WordMerge Lite docs, you'll need to copy your original Word docs into that new folder, open each one in turn, and save it to an .htm file in the same new folder. Only this way will Word be able to generate the new subfolders for the images and xml file.

If there are no embedded images in the Word doc, then, of course, only the .htm file will be created — none of this other stuff will be generated or even matter.

But if you do have embedded images in the docs you're using to make your merge docs, then here's a recap of what to expect:

  • For every Save as Web page .htm file merge document you make from a Word doc with an image in it, Word will create a new subfolder with the relevant files in it.
     
  • WordMerge Lite outputs your finished (merged) file to the folder where your original .doc/.htm merge documents reside (the vDocsPath variable) but tacks on a "_merged" suffix to the filename so as not to overwrite the original file. WordMerge Lite updates all necessary links, including the one in the filelist.xml file.
     
  • Finally, to get everything on the same page, so to speak, and avoid any warning messages about files not being where expected, WordMerge Lite renames the subfolder that Word created when it generated the .htm file. If Word originally named it Prospects_files (for a document named Prospect.doc), WordMerge Lite will rename it, when necessary, to Prospects_merged_files to accommodate the merged output file Sesame generates named Prospects_merged.htm.

If all this sounds complicated, it is. Fortunately, WordMerge Lite (and Word) takes care of it all for you so you don't have even have to think about it much less deal with it.

The three types of WordMerge Lite files
Keep in mind that the folder where your merge docs reside will contain three files for each merge doc (substitute the name of the merge doc for filename):

filename.doc — the master or original Word merge doc.

filename.htm — the .htm (Web page) version made by saving filename.doc in Word as a Web page. filename.htm is what appears on the merge doc picklist (sans the .htm extension) and is the file that WordMerge Lite makes a copy of to merge the data into, then saves as filename_merged.doc or .htm.

filename_merged.doc or .htm — the output or merged document that WordMerge Lite produces and displays in Word or your browser. It's guts are always an ASCII htm file even though it may have a .doc extension. (The .doc extension is solely to enable WordMerge Lite and your operating system to open it in Word for printing.) If you want to save a copy of this doc so WordMerge Lite won't overwrite it, allow it to display in Word or your browser, then save it to a different folder, optionally giving it a new and more meaningful name, but leaving the extension as is.

When editing/updating a merge doc, always make your changes to filename.doc. Save fileneme.doc when finished, then do a Save as Web Page to make a fresh copy of filename.htm. Don't edit filename.htm directly. Don't save filename_merged.doc expecting to get a real Word document. Save it only to another folder if you want to have an archive copy of it.

Note: Because WordMerge Lite requires files with the same names but different extensions (.doc/.htm), you may find things are easier if Windows shows your file extensions. If Windows isn't showing your file extensions, in Windows Explorer or My Computer select Tools / Folder Options / View, and uncheck Hide extensions for known file types.

WordMerge Lite's user modifiable variables
The following variables in the WordMerge Lite program are user-modifiable. Do not change the variable names themselves

// Where the selectable/mergeable HTM docs are stored
var vDocsPath as String = "C:\Sesame\WMLDocs\"

Where tour .htm merge docs are stored. This is also where WordMerge Lite will save it's output ("_merged") files. You'll probably want to also store your original Word (.doc) master merge docs here — the one for use with WordMerge Lite. That way, when you edit and resave them to .htm, Word will put them here automatically. Note: This setting can be modified on-the-fly from WordMerge Lite's Other Options menu.

// Auto-generated list of available HTM merge doc filenames
var vListPath as String = vDocsPath + "list.txt"

The path and name of the file that WordMerge Lite will use to generate the picklist of merge documents.

// Command Line to generate above list
var vDir as string = "dir /b /o:n " + vDocsPath + "*.htm >" + vListPath

The command line that generates the list of merge documents.

 // Send output to Word (".doc") or browser (".htm")
var vExt as String = ".doc"

Leave as ".doc" (default) if you want your outputted merged docs to open in Word. Change to ".htm" if you want them to open in your browser. Note: This setting can be modified on-the-fly from WordMerge Lite's Other Options menu.

// Merge field tag(s) used in merge doc. Ex: *City* *State* *Zip*
var vStartTag as String = "*"
var vEndTag as String = "*"

The starting and ending merge tags that denote a merge field. WordMerge Lite will replace these tags, plus what's inside them, with the data from the matching field. The starting and ending tags do not have to be the same, and each can be more than one character.

// Path to merged image files in Sesame records
var vImgPath as String = "c:\Sesame\"

If the path to your images files is, for example, "c:\sesame\pics\Al Smith.jpg", then the image element's value will be "pics\Al Smith.jpg", so the variable needs only the first part of the path. Note: This setting can be modified on-the-fly from WordMerge Lite's Other Options menu.

Note: If you plan to merge images with your merge docs, take care when specifying your merged image path (vImgPath) in WordMerge Lite. The program can accommodate only one path. If the path to a merged image is c:\sesame\pics\fred_jones.jpg, remember that the  image field's value is likely to be pics\fred_jones.jpg, so the vImgPath variable needs to be c:\sesame\ and no more. WordMerge Lite will take care of concatenating the two to produce the full path: c:\sesame\pics\fred_jones.jpg.

// Image scale factor for *merged" images
// Ex: 75 = scale image to 75% of its actual size
var vImgScale as Int = 75

The best setting for this variable can be found by merge printing a record with an image in it. This variable assumes that the images in your records are all approximately the same width and height. (Sesame reduces images to fit in the element, but that's not necessarily their actual size.) Note: This setting can be modified on-the-fly from WordMerge Lite's Other Options menu.

// Protect settings (users can't change them)
// Merge docs path, output to .doc/.htm, image path & scale
// "no" = allow changes; "yes" = prevent changes
var vProtectSettings as String = "no"

This variable determines the options available from the WordMerge Lite's merge document selection picklist. If left at its default "no", settings for the following items can be changed on-the-fly for and by any particular user:

          Merge documents path
          Merged Images path
          Merged Images scale factor
          Output to .doc or .htm

If changed to "yes", WordMerge Lite's settings will be protected — that is, they won't appear on the Other Options menu as editable user preferences. See the section below on Protecting WordMerge Lite settings for more information.

// Optional custom variables to include in merge doc
// Ex: Current date as *theDate* merge field
var theDate as String = FD(@Date)

WordMerge Lite contains a default current date variable named "theDate" that  replaces every occurrence of *theDate* in the merge doc. "theDate" is run through the built-in FD() function that formats dates like this: "February 20, 2006".

// Declare any other merge variables below. Change the
// variable names to suit. Be sure to add them to the
// end of the MERGEIT() subroutine below. Also, be
// sure to add merge fields for them in the merge doc

var vMyVar1 as String
var vMyVar2 as String
var vMyVar3  as String

Add any custom variables in this section in place of the three "dummy" variables. If the variables are "simple" variables, you can optionally fill them here in the same way as the theDate variable is filled. But if your custom variables can't be initialized with a simple value assignment, declare them here, then perform the assignments either in the Main Program or in the space provided at the end of the MERGIT() subroutine

Protecting WordMerge Lite settings
The WordMerge Lite program contains a number of user-modifiable variables (see the above section on variables), four of which are likelier than the others to require modification, particularly during setup and testing by the developer or administrator. If the vProtectSettings variable is left at its default of "no", these four variables/settings can then be changed on-the-fly without having to open the form in Designer to edit the programming.

A simple four-element string array in [sesame working directory]\WMLSettings.txt stores the settings for these four variables on the PC of any user who modifies an one of them. The merge document selection menu includes a final ««««« Other Options »»»»» item which, if selected, displays a secondary menu with these options:

Print Field Names List
Set Merge Documents Path
Set Merged Images Path
Set Merged Images Scale
Set Output to .doc or .htm
View WordMerge Lite Settings

If any Set... option is selected, WordMerge Lite shows the current setting for it, prompts for the new setting, then saves it to the user's WMLSettings.txt file. Any changes are sticky, meaning that they are permanent until changed via the same procedure. Remember: Each WordMerge Lite user can set their own preferences.

If you don't want to let users set their own WordMerge Lite preferences, change vProtectChanges to "yes" when you deploy.

Figure 1 shows a sample WordMerge Lite merge doc selection menu. Figure 2A shows the Other Options submenu when vProtectSettings is set to "no". Figure 2B shows it when set to "yes".

Figure 1. Sample WordMerge Lite merge document selection menu.

Figure 2A. vProtectSettings set to "no".

Figure 2B. vProtectSettings set to "yes".

WordMerge Lite's built-in User Defined Functions
The WordMerge Lite program consist of the of the main program (with its three subroutines) in the On Element Entry event of a command button, and five data-formatting User Defined Functions (UDFs) in GLOBAL CODE.

Note: depending on the version of WordMerge Lite you have, the UDFs may be in the main program instead of in GLOBAL CODE.

These UDFs are called mostly from the MERGEIT() subroutine in the main program, where the element values are picked up and may need custom formatting (dates, numbers, etc.). You can move these UDFs to the main program, if you like, so that all the WordMerge Lite programming is in one place . If you do, place them directly under the last user-modifiable variable and above the first subroutine, as noted in the WordMerge Lite program.

For details on how these UDFs work, you can review them in WordMerge_Lite.db's Program Spec. If you know what you're doing, you can modify any of them (or add new ones) to accommodate particular needs.

FD() Converts date values in date elements and date variables from Sesame's internal YYYY/MM/DD format to the readable "February 8, 2006" format.

FT() Converts time values to the "4:55 pm" style from the raw/military "16:55" format. It doesn't do seconds.

FNM() Formats Number and Money values.

FBool() For boolean fields such as Yes/No and checkboxes. If the value is 1, the function returns "Yes". Otherwise it returns "No".

FImg() When the MERGEIT() subroutine encounters an image element, it first runs the image through the SCALE_PIC() subroutine which ascertains the image's width and height then scales it using the user-modifiable vImgScale variable (above). FImg() returns the full path to the image along with it's scaled width (w) and height (h) in a formal HTML-encoded format.

Requirements/compatibility
You'll need Windows 2000 or XP, Word 2000 or later and Internet Explorer 5.0 or later. We've gotten good results with the latest Firefox and even Netscape browsers, though Firefox does a far better job of rendering WordMerge Lite output containing images. If your merge docs are simple and don't include images, then most any modern browser should give you good results.

Known WordMerge Lite issues and troubleshooting

Viewing/printing merged docs
When you merge using the .doc filename extension (WordMerge Lite's default) the merged document will display in Web Layout view in Word and may not look right. Lines and paragraphs will be very long and the top and the margins won't show. Click View / Print Layout and the document should now look correct. The document should print correctly regardless of whether you're in Web Layout or Print Layout.

File naming
The following characters in WordMerge Lite filenames (including merged image filenames) will cause problems if the document contains any static or merged images:

$ & + , / : ; = ? @ " < > # % ! ' ( ) * - . { } | \ ^ ~ [ ] ` £

When naming your merge docs, use only alphanumeric characters with an optional  space or underscore between words.

Technical Note: With the exception of spaces, any character that normally requires URL encoding (Google "URL encoding") is likely cause trouble.

Folder naming
Any paths (folder names) involved in WordMerge Lite operations must be comprised strictly of alphanumeric characters and no spaces. Optional underscores are okay.

Page break problems
When a merge includes multiple records, WordMerge Lite inserts an empty paragraph marker (<p></p>) just before the page break command (page-break-before: always) at the end of each individual merge doc. The page break command needs the preceding empty paragraph to work reliably when the output file is viewed/printed in Word (.doc). Do not delete this empty paragraph.

Merge fields not merging data
When test-printing a new merge document, you many notice that one or more merge fields are not merging data as they should. You've checked that the merge field is correctly spelled (it exactly matches a layout element name on your form or a custom variable you've added to your WordMerge Lite program) and confirmed that the value that should be merging is not blank in the record being merged. Instead of the data being merged, the merge field itself (e.g. *theDate*) appears in the document.

If it's a variable (such as *theDate*) , make sure that you've told the WordMerge Lite program to merge to this merge field. You may have have declared and populated the variable, but failed to tell WordMerge Lite to merge it in the MERGEIT() subroutine.

If you've ruled out all of the above, then it may be a Word "spellcheck" issue, believe it or not. Fortunately, these are easily fixed:

1. Open the original Word doc.

2. Run a Spell Check on it. For each merge field it flags as misspelled, click Add to Dictionary.

3. Save the doc, then do a Save As Web Page to create a new .htm (Web page) file.

See if the merge field now properly merges the data.

Note: Having Grammar Checking turned on while editing your merge documents may also contribute to above problem. Grammar checking adds hidden markers to document files that can "corrupt" a merge field tag by inserting these markers between the asterisk and the field name. When a merge field tag is "corrupted", WordMerge Light can no longer match it to the field name in the database record.

If the original Word document was created with Grammar Checking turned on, run a Grammar Check on it. For each grammar error it finds that involves a merge field tag, tell Word to ignore the error. When done, resave the document and make a new .htm (Web page) file from it.

If the field still doesn't merge — and the field name contains spaces — the problem could be a "broken" merge field. This can happen when a merge field is line-wrapped (with a hard carriage return) on one of its spaces by Word when you do a Save As to an .htm file.

WordMerge Lite "flattens" the .htm file when processing it, temporarily replacing hard carriage returns with a special "^|^" string. You can make the WordMerge Lite program find merge fields containing this string and replace each one with a space.  Here's how. In the MERGEIT() subroutine you'll find this statement:

// Replace merge field tag with data
vNextDoc = @Replace(vNextDoc, vStartTag + vName + vEndTag, vVal)

Add the following lines under the above statement to fix instances where a field name containing one or more spaces is broken on the first or last space. This additional code temporarily adds a "^|^" to the field name, looks for a match in the doc and replaces any found with the value being merged.

vFix = @Replfir(vName, " ", "^|^")
vNextDoc = @Replace(vNextDoc, vStartTag + vFix + vEndTag, vVal)
vFix = @Repllas(vName, " ", "^|^")
vNextDoc = @Replace(vNextDoc, vStartTag + vFix + vEndTag, vVal)

You can declare the vFix variable at the top of the MERGEIT() subroutine.

More recent versions of the WordMerge Lite program "flatten" the document in a slightly different way. Find the following lines in your copy of the program:

// Flatten doc to prevent C/Rs in merge field tags
vDoc = @Replace(vDoc, @NL(), "^|^")

Change the second line to read:

vDoc = @Replace(vDoc, @NL() + "  ", "^|^")

This tells the program to replace each carriage return followed by two spaces with ^|^. (When generating the .htm file, Word, breaks lines at spaces, then indents the following line by two spaces. This is what causes the problem.) The aforementioned change, in conjunction with the vFix addition above, solved the "broken" field problem in all cases we've seen to date.

If all else fails, open the .htm file (the one generated by Word, not the already merged one) in Notepad and locate the offending merge field. Chances are there will be some errant bit of HTML code inside the merge field tag put there by Word when it made the file. Clean it out and resave the file to the same name and .htm extension. Merges to that tag should now be successful.

Words in the output document running together
When viewing a merged document, you may notice that spaces are missing between some words. For example, you might see a line like this:

Please review the attachedcontract and notify us of any changes...

Here the words "attached" and "contract" have run together. This problem is almost always caused by one or both of the following:

  • paragraphs in the original Word doc are tab indented
  • paragraphs in the original Word doc are formatted for full justification.

When you use tab indents or text justification in a merge doc, Word inserts its own proprietary "space-run" codes into the .htm (Web page) file in an attempt to account for HTML's lack of support of these formatting options. The "space-run" codes cause line breaks to occur at odd places and words to run together. The fix is to remove all tab indents and text justification from the original Word doc, save it, then remake your .htm file for use with WordMerge Lite.

Merged image sizing
When outputting to Word (.doc), there's a huge difference between the size at which Word 2000 displays merged images and they way Word 2003 displays them. (We haven't tested Word 2002 but it may be the same as Word 2003 in this regard.)  Word 2000 seems to reduce them to about one-third of what they should be.

In the MERGEIT() subroutine in the WordMerge program, you'll find this section:

/* Word 2000 displays merged images about 3 times too small, so
comment out one of the two statements below if merged images
display way too big or way too small in merged .doc */

// (1) Word 2000 -- If merged images display way too small.
// If vExt = ".doc" Then vVal = FImg(vImgPath + vVal, vWid*3, vHgt*3)

// (2) Word 2002/3 -- If merged images display way too big.
   If vExt = ".doc" Then vVal = FImg(vImgPath + vVal, vWid, vHgt)

If you're using Word 2000, uncomment the statement under (1) Word 2000... and comment the line under (2) Word 2002/3.... as shown. If you're using Word 2002/3 do just the opposite.

You need to do this only if you're outputting to Word and merging images in your Sesame records. This is not for static images that are embedded in the original Word doc.

Adding/Enhancing merge fields
When adding your merge fields, be sure not to leave spaces between the element name and the start and end delimiters:

Incorrect: *First Name * or * First Name* (trailing / leading space)
Correct: *First Name* (no trailing or leading space)

When enhancing a merge field, be sure the enhancement includes both the start and end delimiters:

Incorrect:  *Amount Owed*  (the asterisks aren't also in boldface)
Correct:  *Amount Owed*  (the asterisks are also in boldface)

Turning off Word's Auto-Formatting for asterisks
By default, Word 2003 will change *fieldname* to fieldname (remove the asterisks and change to boldface) as you type.

If you're using asterisks as your merge field tag:

You can click Edit / Undo AutoFormat  to remove the auto-formatting each time Word auto-formats a merge field.

Or, you can turn it off completely by clicking Format / AutoFormat / Options / AutoFormat and unchecking the particular checkbox that causes it. Do this also on the AutoFormat as You Type tab.

Conclusion
The WordMerge Lite program is more complex than the original WordMerge program because it does so much more for the user. It reduces Sesame setup to nothing more than adding a button to the form and pasting in the program, and greatly simplifies what it takes to create working merge documents in Word.

WordMerge Lite
doesn't expect the user to be highly skilled with Sesame or Word, yet its programming can be further customized by anyone with the know-how to do it.

If you have any questions about the programming or any aspect of WordMerge Lite's operation, contact us at office@insidesesame.com. WordMerge Lite is new, so we'd appreciate hearing your comments on it, details on anything that doesn't work as expected, or suggestions for improving it.