Implementing Electronic Forms Solutions
with the FORMagic Host Developer Kit

Step-by-Step Technical Overview
(see User's Guide for complete details)

Note: These instructions apply specifically to the FORMagic/Host Developer Kit. They do not apply exactly as written to FORMagic/Windows. By reading steps 1 through 7, omitting steps 8-11, and using step 6 only as a general guide for modifying your Windows program, you will gain a fairly thorough overview of a Windows-only implementation. Note that you must bypass the Windows printer driver, in some appropriate manner, to pass the necessary form merge commands from a Windows program to the printer.


Step 1 - Installation

Download and install FORMagic/Windows. This client, along with the procedures below, will enable you to implement a complete, host-based electronic forms solution before purchasing the Host Developer's Kit.

The FORMagic/Windows client will be used to generate and test electronic forms. The Host Developer's Kit will convert generated electronic forms into a format which can be uploaded and stored on host systems and used with host print applications.

Step 2 - Design the form(s)

Design your form(s) with any PC-based product which can output to an HP-compatible laser printer. The design product can operate under any version of DOS, Windows, or OS/2.

We find that most of our customers are using some version of Word to create forms. Why? Because so many people already have it and know how to use it. Word also generates efficient forms and is easy to use. We are often amazed at how quickly our customers can generate very impressive forms with Word. But again, FORMagic allows you to use any product. If you can "place toner on the page" with it, FORMagic can turn your forms into electronic overlays that can be used in host applications. And, you can use almost any and every feature of your package to make your forms.

If you need to incorporate logos, signatures, images, etc., they must be in a format (PCX, WMF, GIF, etc.) supported by your design product. Just use your designer to "import" them, place them on the page, and scale them as required. When doing this, they become an integral part of the form, just as lines and boxes, and lose their identity as separate images.

Just use any and all of the features provided by your design product to create the complete form needed for your application. Print the form and tweak it as needed until you are satisfied that it's complete.

A note about scanning - many people ask about scanning forms. FORMagic will certainly let you use the scanning approach if you can print the scanned output to your laser printer as described above. But, we don't think you will be very happy with the results for several reasons:

In any case, it always takes a little time to merge a form with print data. With average forms, created with an efficient designer, we seldom hear comments from our customers that print speed is unsatisfactory. Small logos and signatures do not generally cause a significant speed loss. So, we can give some general guidelines for achieving maximum print speed with electronic forms applications.

Most of our customers meet these guidelines without consciously doing anything special. We seldom hear of problems; and any degradation is generally acceptable or even unnoticed.

If you need very fast first page output from electronic forms applications, such as customer checkout documents, then you must optimize everything. By the time you run an application, create a spool file, send it to the printer, start the printer motor, feed a page, compose the print data, merge the form, and eject the page, many seconds will have elapsed. It's very difficult to do this in less than 20 seconds unless everything operates at top speed; omitting the form will only save a couple of seconds!

Step 3 - Print the form to a file

There are many ways to do this, but Word makes it very easy. Just print your form normally, but turn on the "print to file" option. When capturing the file, you must select a printer which uses a driver which is compatible with all of the printers you will be using with your host application.

This may be difficult to do if you have a mixture of models from different manufacturers. But, the principles here are easy to understand. You cannot print a form created with a LaserJet 4 driver on a LaserJet II printer; the older printer simply does not support the commands used by the newer driver. You can create a form with a LaserJet II driver and print it on a LaserJet 4 printer; but the form will be significantly larger and less efficient than a form created with the newer LaserJet 4 driver. You can also have problems when crossing manufacturer lines with drivers and printers, even when they are both "compatible" with the same printer. For instance, forms created with a LaserJet 4 driver will sometimes print incorrectly on Lexmark printers.

Assuming you are not using older LaserJet II and III printers, the best rule is: use a LaserJet 4 (no suffixes) printer driver to capture the form. Why? Because it is highly compatible with almost all HP-compatible printers, and almost all companies use multiple types of printers. Or, they will eventually! It also creates very efficient forms. Of course, you can also use the latest printer driver which exactly matches the printer you will be using or one which is known to be compatible with all of your printers. Be sure to test the form on each printer type you will be using.

Never use the new PCL 6 drivers or PCL 5XL drivers - FORMagic does not support them; and they will print garbage in place of the form. Instead, use the LaserJet 4 driver or a PCL 5e driver matched to your printer(s).

Compatible Printers:

FORMagic allows you to use any HP-compatible laser printer that provides full PCL 5e support in firmware. Many inexpensive laser printers implement much of their functionality in the Windows printer driver which, of course, is not used by most hosts, so they will not work in all applications! These printers include the HP 4L, 5L, 1000, 1100, P2015, and others.

Most inkjet and multi-function printers will not work because they implement only PCL 3, not the higher level functionality of PCL 5e needed for electronic forms applications.

The following printers are compatible with FORMagic:

Step 4 - Convert the form into an overlay

Use FORMagic to convert the captured form "file" into an electronic forms overlay. This only takes a few seconds.

When creating the overlay, you must assign a name and number. The name will be used to manage the overlay within the host application. The number is used by the printer to merge the form with the data and can be anything between 1 and 9999. After conversion, you can optionally test the overlay from FORMagic to insure it is working properly.

Step 5 - Download the form to the printer

Forms, like fonts, must be resident in the printer before they can be used in merge applications. After you obtain the Developer's Kit, you can download forms directly from the host. For now, you must use the FORMagic client system to perform all downloads. Note: Beginning with FORMagic/Windows version 4, the Host Developer's Kit is active immediately after installation. You do not have to obtain it, or keys, for the trial. As in the past, overlays created during the trial will have embedded tag lines which will be removed when a permanent key is installed.

When a form is downloaded, no printing occurs, and no blank page is ejected. The only way to know a form is there is to test it or to watch the printer ready light blink a few times during the download. Average efficient forms download quickly, just a few seconds.

You do not have to download forms every time they are used; they will remain in the printer until something causes them to be removed:

If your application will use the same form throughout the day, you can simply download it during morning startup and leave it there. For infrequently used forms, such as statements, you will probably want to download it in your host procedure, call your application, then remove the form to free printer memory.

If you are concerned about the possibility of "losing" overlays, just download them in the job which controls your application. Thus, they will be downloaded every time they are needed; they simply replace the overlay if it is already there. This seldom creates a performance issue, so many of our customers do it this way.

You can also consider adding flash or disk memory to your printer(s). With such non-volatile memory, forms are retained during a power loss; you never have to re-download a form unless it is changed. Our optional FlashMagic Non-Volatile Memory Manager provides facilities to download standard FORMagic overlays into these types of memory devices.

What about memory usage? Most efficient overlays are only 20-50k in size. Most printers today come with 4MB or more of standard memory. About half of it is used by the printer's operating system, the balance is used by applications. The large memory is actually provided just to accomodate Windows graphics applications; if you are only using the printer with text-oriented applications, the larger memory is never used! So, there is generally a lot left for multiple forms.

If you have many large forms or older printers with less memory, you might need to add more memory; but fortunately, it's very inexpensive today.

Step 6 - Modify your host program to include a merge command

The FORMagic Host Developer's Kit requires that you embed a merge command into the print stream wherever a form is to be merged onto the page. This merge command is between 7 and 10 characters long depending on the overlay number (1-9999) assigned. You can use leading zeroes in the form number; and a constant length of 10 in all cases will often simplify programming. If the host OS is EBCDIC-based, SNA ASCII translation will probably be required.

The User's Guide explains the necessary command as well as SNA translation. Just place it anywhere on the page; we have designed the overlay generation process such that its location doesn't matter. It is generally easiest to place it on a blank line, starting in position 1, and print it with normal spacing just as if you were printing a regular text literal.

When the printer "sees" the command, it will merge the form with your data and print blanks in lieu of the command; the command itself will not be printed. Note that you can use appropriate logic to insert different forms on different pages, no forms on some pages, and even multiple forms on some pages, very easily.

Step 7 - Run your application

Now, just run your host application and enjoy the benefits of electronic forms technology.

Step 8 - Obtain the Host Developer's Kit

At this point, the merge application is working; but you still have to download forms manually from the FORMagic client. If that functionality is all you need, just purchase a client copy for each of the PC's from which you want to download overlays.

But, if you want to automate forms downloads from the host, call us and ask for a key for the Host Developer's Kit. We will provide a key that activates the Kit on an evaluation basis and converts overlays into a format that can be used with host applications. You won't have to re-install FORMagic; just install the key. Note: As mentioned earlier, you will not need a key when using version 4 or later for trial evaluation.

During the evaluation, an evaluation tag line will be added to all forms. After your application is tested and you purchase the Kit, we will provide a permanent key that also removes the tag line.

Step 9 - Develop procedures to upload, store, and download host overlays

You must develop your own application to manage forms on the host. The Kit will create two files for each overlay: one contains binary ASCII data that defines the form content and the other is an ASCII text file containing information about the form. The latter file will be helpful in creating a host application to manage multiple forms. Your host application must:

In any case, the storage and download utilities must faithfully store and download a duplicate of the original PC file. For example, if the Host Developer Kit creates an overlay file which is 21,345 bytes long, the same 21,345 bytes must ultimately be downloaded ("copied") to the printer. No bytes can be added, removed, or changed or the overlay will not be properly stored in the printer for use in merge applications.

If you are dealing with non-ASCII platforms, such as IBM EBCDIC mainframes, the same requirements apply. But, you will have to prevent ASCII-EBCDIC translation on upload; and you will have to prevent EBCDIC-ASCII translations on download. You can, however, pad the last record with hex zeroes if you are storing forms in files using fixed length records.

Providing the host storage and download utilities, or creating them, is a user responsibility. But, if you have questions or need help, just give us a call.

Step 10 - Generate and upload the host overlay

Use the Host Developer's Kit to generate the binary overlay file; then use your host utility to upload and store it on the host. This process will only take a minute or so for each overlay.

Step 11 - Test the form on the host

Use the host download utility to download the form to the printer. Then run your host application as done in Step 7. The results should be the same as seen previously, but the download is now being done from the host.

Now, you are ready to implement a permanant host job to control your production application. It will probably be identical to the one previously used with pre-printed forms, except for the added step to download forms.

Your application should now be completed and working, except your forms still contain the evaluation tag line. If the application meets your needs, call Keowee Systems to purchase the Developer's kit. After receiving payment, we will provide a permanent activation key that will also remove the tag line.

Q & A

Wow. That sounds complicated! ===> Not at all. In about five pages, we have described the complete process in full detail. We didn't omit anything you will encounter in most applications. Of course, we didn't describe every button you will have to push or click, but the entire process is described above.

Okay, I'm convinced. But what kinds of problems might I encounter? ===> That's a fair question and one we think systems professionals should always ask before any software is purchased. We try to support all environments, but that's very difficult to do today. There are just too many ways to assemble various hardware and software components from numerous manufacturers for us to guarantee that FORMagic will work in your environment without any integration issues.

That's why we include testing tools, offer FORMagic on an evaluation basis, and provide technical support to implement the host application before you buy the Host Developer's Kit. All you risk is your time. We can guarantee that we do not want you to purchase the Kit until your application is working and you are fully satisfied.

As for specific problems, here are the most common ones:

With ANY Keowee Systems product,
you only risk your time to try it!