Programming with Print Wizard

Introduction

Print Wizard offers two convenient tools for the programmer.

First, through the Print Wizard DLL a programmer can incorporate the features of Print Wizard directly in to his/her program.

Second, if you prefer a simpler approach, the programmer can actually embed the PWML (Print Wizard Markup Language) directly in to the print output stream of the report. The output can be passed off to Print Wizard in a couple of different methods, letting Print Wizard do all the necessary work outside of your program.

Additional information on the use of Print Wizard can be found in the Print Wizard Technical Description.

The Print Wizard DLL

Print Wizard is provided as a callable module, PWDLL.DLL, that can be called from many programming languages, including Visual Basic (VB) and Visual Basic for Applications (VBA). This makes a very easy way to get basic or advanced printouts from these languages without delving into the Windows printer API. In fact, you can create printout with as little as one call.The following VB subroutine shows the interface, and demonstrates the use of some:

End Sub

Note that all integers are 32-bit.

For more information on incorporating PWDLL.DLL in to a program, give us a call.

Print Wizard's Markup Language

Print Wizard's markup language (PWML) is based on HTML. This has several advantages. It is known by many programmers and web designers. It is based entirely on printable ASCII characters. It can be created with any programming language. And it adapts easily to dealing with text-only data.But HTML is lacking in two key areas: precision and pagination. It does not allow precise placement of print elements. And it is designed primarily for the screen, not the printer; it has no concept of a page break. (Some of these issues are being addressed, with CSS for instance). So Print Wizard's markup language extends HTML in these and some other areas. Conversely, Print Wizard is targeted at printing "line printer" type legacy printouts. Thus it does not (yet) handle text justification or word wrapping. Print Wizard allows you to move incrementally into the markup language. Suppose you have a print file that contains 132 columns of data. If you feed this to Print Wizard when it is set to portrait orientation, Print Wizard will compress the font horizontally in order to fit 132 columns onto the page. But now suppose you require that report to print out in landscape orientation. You can simply add to the beginning of the file:

and you will accomplish your objective. Similarly, you could specify other "job-level" parameters such as paper size, bin selection, font, line spacing, and lines per page. You could even specify a form overlay (or watermark). But the original text would not need to be changed at all.At the next level, to use bolding, italics, or underlines, you could insert simple tags like "" to start bolding and "" to end bolding, in the body of your report. You could also indicate special characters, such as "€" for the Euro character. You would need to change the <PLAINTEXT> above to <PRE>, so that tags would be recognized.

But in <PRE> mode, your existing data might contain things that looked like tags ("<") or like character entities ("&"), so you'd have to change "<" to "<" and change "&" to "&". To avoid that need, there is <LEGACY> mode. In <LEGACY> mode tags (starting with "<") and character entities (starting with "&") must be preceded by a "trigger" control character, which is normally control-Z; otherwise, they are not recognized, but are printed as plain text.

Getting data to the PRINTWIZ.EXE program

The freestanding Print Wizard program is completely contained in the file PRINTWIZ.EXE. This is a console-mode program that ordinarily has NO user interface. It is driven completely by command-line parameters. Thus it can be initiated by another program or a batch string to print a particular file, a group of files as specified by a wildcard, or any files that get dropped into a particular directory. It can even process and print files that exist on web or FTP servers.

Printwiz.exe starts with an assumption that it should print in the Courier New font, on the Windows default printer. Properties such as paper size and orientation are taken from that printer's properties as set in the Windows control panel. Print Wizard also assumes that incoming text data is in the DOS (OEM) character set.

Parameters

Print Wizard is started with a command in the form:

Printwiz [parameters] filespec

The [parameters] are optional, and are case insensitive. Don't enter the "[" and "]". Here is a partial list of possible parameters (see the Print Wizard manual for more):

/s means do printer setup first
/l[logfile] indicates logging (default to screen)
/p"printer string" sets which printer, by its Windows name, such as
/p"HP LaserJet III"
/f[filename] means print to file (or device)
/bh means duplex with horizontal binding (requires duplex printer)
/bv means duplex with vertical binding (requires duplex printer)
/I means file is in ISO character set (otherwise assume PC set)
/w means wait for despooling
/d means delete (combine with /w for wait-then-delete)
/k means keepalive
/cnnn sets baud rate to ''nnn'' if printing "raw" to a serial printer
/vLEVEL=xxx forces print level to "xxx", which can be "HIGH" or "LOW" or "RAW"
/vTAGS=OFF turns off tag processing, in order to print HTML or PWML source
/vDEBUG turns on debugging mode
/r means to rename the file (to a unique name) while it is being printed

The filespec can be

1) a single file,
2) a dash ("-"), which means to use standard input (stdin)
3) a wildcard,
4) a URL.

Examples are provided below.

Active mode

This is the mode where you simply tell Print Wizard to print a particular file. For instance, to print a file on the default printer:

printwiz myreport.txt

To print a group of files on a specified printer:

printwiz /p"My Deskjet" \temp\*.txt

Printers are identified by name. The name given must match what is shown in the Printers control panel.

To print a file from an FTP server:

printwiz ftp://somehost.com/pub/myfile.txt

Note that Print Wizard will do an anonymous connection to FTP.

Despool mode

Print Wizard can act as a despooler, in which it runs in the background, watching a particular directory (or other wildcard spec) for files which have been created and released there. For each file, it will print it as indicated, and delete it. It can optionally wait until the Windows spooler reports that it is fully printed before deleting it. A typical use would be:

printwiz /k /w /d /l c:\spool\*.*

Note that if you're running an old DOS program under Windows, you may be able to configure the DOS program to "print to file" to a specified file name in the "c:\spool" directory, and thereby use Print Wizard to process your DOS program's output. If the program has some ability to drive different kinds of printers (inserting escape sequences), try configuring it to print to a "generic" printer, so Print Wizard can function fully.

If you add a "/r" parameter to the line above, Print Wizard will rename the file to a temporary, unique file name before printing (and then deleting) it. That way, if you start another print job during the time Print Wizard is printing the first print job, there will be no name collision.

Default print processor

You can tell Windows that you want to use Print Wizard to print files of certain extensions (such as ".TXT", ".PWL", etc.). Then, in Windows explorer, you can point to one of these files, right-click, and choose "print". Also, this technique is necessary when you want to use Print Wizard to fax certain files (such as with MAPISEND, explained below).To do this:

Start up Windows Explorer (not Internet Explorer)

Go to "View:Folder Options"

Click on "File Types"

Click on "New Type"

In "Description of type", enter "Print Wizard document"

In "Associated extension", enter a list of file extensions, such as "txt pwl"

Click on "New"

In "Action", enter "print"

In "Application used to perform action", enter the full pathname of the PRINTWIZ.EXE

Click on "New"

In "Action", enter "printto"
In "Application used to perform action", enter the full pathname of the PRINTWIZ.EXE, followed by appropriate parameters:

C:\printwiz\printwiz.exe /p"%2"

The "printto" action is what Windows uses to print a particular file type on a specified printer. The printer name will be inserted in place of the "%2", and the file name to be printed will be appended. For diagnostic purposes, you might want to add a log file designation.

Recognizing a Marked-up Document

Print Wizard detects marked-up data as a file starting with any of (case insensitive):

<!DOCTYPE
<HTML
<PWML

Tag Basics

Print Wizard's tag structure, like HTML, consists of tags between less-than and greater-than, such as:

<PRE>

If you are in LEGACY mode (after a <LEGACY> tag), the less-than must be preceded with a "trigger" character, normally control-Z.Some tags have additional parameters, such as:

If the parameter value contains embedded spaces, the parameter must be in quotes as shown. If there are NO embedded spaces, the quotes are optional.The parameter value for some parameters must be numeric, implying there is a need for units of measure. These are described later.Some tags have a corresponding ending tag, such as "" to start bolding, and "" to end.

Tags are case insensitive, and can be continued from one line to another.

The Bare Minimum

Print Wizard will not actually start printing anything until it gets into the plain text part of the file. That is, it must encounter a <PRE>, <XMP>, <PLAINTEXT>, <LEGACY>, or <LISTING> tag. Since any of these should be inside the <BODY> section, a minimal set of tags (that does not alter Print Wizard's default behavior) is:

The differences between the four tags above involve a) what kind of tags are allowed after each, b) assumed width, and c) whether ampersand character entities (explained below) are allowed. After the PLAINTEXT tag, no other tag or character entity processing or is done.

LISTING implies 132 characters per line, and XMP implies 80 characters per line. No character entities are processed.

The only tag that is processed is the ending tag, "/LISTING" and "/XMP" respectively.

After PRE, any tag is recognized, and character entities are processed. There is no assumed number of characters per line, but that can be specified with the WIDTH attribute.

After LEGACY, any tag or character entity is allowed, but only if preceded by the trigger character, normally control-Z.

Units of Measure

Standard HTML is ambiguous about placement of text, images, etc. For instance, font size is indicated from "1" to "7", and bitmap widths use units of pixels. Print Wizard, however, is designed to allow precision, and pixel size varies from printer to printer.

For every numeric value entered in a tag, Print Wizard will assume a certain unit of measure. For instance, the tag

(which doesn't exist in standard HTML) assumes a unit of "point" (1/72 inch). Units can also be relative to the current setting. To make the pointsize 2 points larger, do

A minus sign ("-") also works. Changes can also be specified in percentages:

Finally, many measurements allow you to specify units exactly, with a two-character code immediately following the number, such as:

<PAGESIZE x=8.5in>

Allowable units are:

pt = points (72 points = 1 inch)
pc = pica (1 pc = 12 pt)
in = inches
mm = millimeters
cm = centimeters
li = lines (based on current linespacing)

For many measurements, we have tried to make the assumed units compatible with standard HTML, which deals in dots or pixels of the screen. When translating this to the printer, we have to make some assumptions. We have tried to maintain a certain amount of compatibility with existing browsers, as well as with earlier versions of Print Wizard.

Print Wizard takes the following approach. Each document starts off with an assumption of a virtual pixel density of 120 dots per inch (DPI). This is similar to the density used by various browsers when they print. Thus a horizontal rule (HR) that has a WIDTH of 300, will be printed as 300 DOTS wide, or 2.5 inches. Similarly an image (IMG) with a WIDTH of 480, will be printed as 480 IMG-DOTs wide, or 4 inches.

If Print Wizard encounters a <PAGESIZE>; tag, which is non-standard HTML, it then assumes a DPI of 720, and a density for images (IMG-DPI) of 300. Thus bitmaps that are scanned at 300 DPI will print in true size, regardless of the printer's capabilities. Finally, within either the <PAGESIZE> tag or the <BODY> tag, DPI can be set with a DOTSPERINCH attribute, and IMG-DPI can be set with an IMGDOTSPERINCH attribute.

Thus if DPI is 720, then a DOT unit is 1/720 of an inch. Likewise, IMG-DPI determines the size of an IMG-DOT. If a tag places a rectangle at X=360, and DPI is 720, then the rectangle is placed 1/2 inch in from the edge of the page. Print Wizard figures all placements from the top or left edge of the paper, NOT from where they normally start printing.

Colors

Print Wizard recognizes the following colors for fonts, font backgrounds, and horizontal rules:

#rrggbb hex RGB value
GRAYxx gray scale from GRAY00 to GRAY99
GREYxx
aqua
black
blue
fuchsia
green
lime
maroon
navy
olive
purple
red
silver
teal
yellow
cyan
magenta
white

Fonts

Print Wizard is generally designed to work with mono-spaced fonts, such as Courier New. Mono-spaced fonts are consistent with the focus on legacy print data, which generally relies on character spacing to align columns. Also, Courier New can contain many international characters. Print Wizard also works best with scalable fonts, i.e., TrueType fonts. These fonts can be scaled precisely to get the necessary height and width.

It is possible, with the FONT tag, to specify ANY available font, but your results may not be acceptable. If you are using a dot matrix printer, you may want to specify a font that is built in to the printer, for faster printing. These fonts can be identified by doing a font selection in a Windows program, and looking for a printer icon beside the font. Again, though, if they're not scalable then that limits Print Wizard's flexibility.

Some printer drivers may not handle international characters well. If you have trouble, open the printer's properties in Windows' control panel, and try different settings for font substitution and type of download. You might also try a different but similar printer driver, such as a LaserJet 4 driver for a LaserJet 5 printer.

Character Entities

In <PRE> mode, Print Wizard recognizes standard named values for character entities, such as "<" for less-than ("<"), "&" for ampersand ("&"), and also "€" for the Euro character ("€" -- might not show on your PC). It also recognizes characters coded numerically, such as "&#242" and "&#D242" (both decimal), and "&#H20AC" (hex). Numbers below 128 resolve to ASCII values. Numbers between 128 and 255 are in the ISO 8859-1 character set, which is essentially the same as Windows Latin-1. As in true HTML, numbers above 255 resolve to 16-bit Unicode characters.

Multi-Lingual Printing

The ability to render Unicode means that you can specify and intermix characters in many languages.

When Print Wizard has to print a character outside the ASCII range, it will test the currently selected font to see if it contains that character. If not, particularly for characters with diacritics, it will try several approaches to rendering the character, including printing character and diacritic separately, printing alternate forms of the diacritic, and using an internal bitmap for the diacritic.

Print Wizard does not yet deal explicitly with bidirectional languages Arabic and Hebrew.

Rectangles

HTML has a feature called "horizontal rule", as <HR>. By specifying SIZE (height), WIDTH, COLOR, and OUTLINE, you can create a solid, hollow, or color-filler rectangle of any size. The OUTLINE is always black.

Print Wizard extends this with absolute positioning (X and Y), so you can place the HR any place on the page. With clever use of these, you can create grids and other forms.

Placing an HR will change the current printing position, so you may want to use a GOTO tag to begin printing text in a particular spot.

It is possible to print rectangles over each other, text over rectangles, etc.

Graphics

Print Wizard is able to print bitmaps (pictures) from files that are in BMP, GIF, or JPG format, that are on the PC, a local area network, or a web or FTP server. Bitmaps are coded using the <IMG> tag. These can be sized with the HEIGHT and WIDTH attributes. A BORDER can be added (always in black).

If the filename (in the SRC parameter) does not contain a complete path, Print Wizard will look for it in a particular directory, generally the directory containing the data file. You can override this by using the BASE tag with the HREF parameter. You can also specify an assumed file extension, with the EXT parameter of the BASE tag. So, if early in the print job you specify

<base href=c:\mypix ext=".bmp">

then you can generate a picture with the tag

<img src=wally>

and Print Wizard will read the file "c:\mypix\wally.bmp".

With Print Wizard's additional attributes (X and Y), graphics can be placed any place on the page.

Printing a bitmap will change the current printing position, so you may want to use a GOTO tag to begin printing text in a particular spot.

It is possible to print text over graphics.

Bitmap Form Overlays

A special treatment of bitmaps allows creation of a form overlay. The OVERLAY attribute in the <PAGESIZE> tag specifies a bitmap file, in GIF, JPG, or BMP mode, that can exist on either the PC or an Internet server. This bitmap is always scaled to fit the page. So you can scan a full-page form (using other software), save it as a GIF, JPG, or BMP, and instruct Print Wizard to print it as background on every page of a print job.

The overlay does NOT affect the position at which Print Wizard will begin printing text on the page.

PCL Form Overlays

If you are using a laser (or other) printer that understands PCL (Printer Control Language), and has the macro capability (such as an HP LaserJet III or higher), you can instruct Print Wizard to load a PCL document as an overlay to be printed on every page. With this method, unlike with bitmap form overlays, the data is sent to the printer only once, and the printer does the job of adding it to each page.

If the document contains more than one page, each page will be loaded into a separate macro, and those will be cycled for each page of printout. So if you load a 2-page overlay, then proceed to print some text, your first page of text will print on the first page of the overlay, second on second, and then your third page of text will print on the first page of the overlay, and so forth.

You can create the form file using any Windows program that allows you to print to a disk file, such as Word, Adobe Acrobat Viewer, or Netscape. Select the page you want to use as your form. Configure the program to print using an HP LaserJet III printer driver (which you may need to install on your Windows platform), and to print to file. Print the page(s) you're interested in. When prompted for a filename make one up. Make sure the file ends up with a ".PCL" file extension (you may need to create it as ".PRN" and later rename it as ".PCL"). This completes creation of the overlay file.

To use the overlay file, simply reference it as an overlay. For instance:

<HTML><PAGESIZE OVERLAY="c:\mydir\myform.pcl"><body><pre>Text begins here...

Note that Print Wizard relies on the file extension to know how to process the file.

Barcodes

Print Wizard can internally generate a variety of barcodes, which can then be printed on nearly any printer, with a tag as simple as

<barcode src=1234>

Of course there are many kinds of barcode, and you'll want to specify style, size, position, etc. The Reference section below lists all the parameters. But here are some special notes.

Once the format of the barcode (STYLE, SIZE, etc.) has been established, it will remain in effect for the duration of the print job. It is sometimes easier to establish this format once, at the beginning of the print job, by including a BARCODE tag that has no SRC parameter (and will therefore not print anything).

Some barcode styles have particular requirements, such as numeric data only or a particular length. If you don't meet these requirements, Print Wizard may detect that and print a message on the page, in place of the barcode.

Print Wizard start off assuming that BARWIDTH, the width of the narrowest bar or space, is .012 inches. On a low resolution printer, this may produce unreadable barcodes. Therefore, you may need to specify a larger value.

Reference

The following table indicates all the tags and parameters that Print Wizard recognizes. Items marked with "+" are extensions to the HTML standard. Where units of measure are involved, the table shows what unit is assumed; see above for explanation. The table also indicates when relative or percentage changes are allowed, and where exact units can be specified.

<HTML> ... </HTML>

<PWML> ... </PWML>

<HEAD> ... </HEAD>
 (ignored)

<PAGESIZE> +
 DOTSPERINCH
 establishes DPI and DOT
 IMGDOTSPERINCH
 establishes IMG-DPI and IMG-DOT
 X=n
 in DOTs relative, %, units
 Y=n
 in DOTs relative, %, units
 PAPER=n
 1=letter
 3=tabloid
 5=legal
 8=A3
 20=#10 envelope
 BIN=n
 1=upper
 2=lower
 3=middle
 4=manual
 5=envelope
 6=envelope manual
 7=auto
 ORIENTATION=s
 1 or "landscape"
 0 or "portrait"
 LENGTH=n
 lines per page
 LINESPACING=n
 vertical, DOTs relative, %, units
 OVERLAY=filename
 always printed at full page size

<BASE>
 HREF=s
 base location for images
 EXT=s +
 assumed extension for IMG files

<BODY> ... </BODY>
 DOTSPERINCH +
 establishes DPI and DOT
 IMGDOTSPERINCH +
 establishes IMG-DPI and IMG-DOT
 TOPMARGIN=n
 in DOTs relative, %, units
 BOTTOMMARGIN=n
 in DOTs relative, %, units measured from top edge of paper
 LEFTMARGIN=n
 in DOTs relative, %, units
 RIGHTMARGIN=n
 in DOTs relative, %, units measured from left edge of paper

<LISTING> ... </LISTING>
 implies 132 characters per line, no embedded tags, no character entities

<XMP> ... </XMP>
 implies 80 characters per line, no embedded tags, no character entities

<PLAINTEXT>
 no tags can follow, not even </PLAINTEXT>
 no character entities

<PRE> ... </PRE>
 can contain tags
 can contain character entities
 WIDTH=n
 characters per line

<LEGACY> ... </LEGACY>
 can contain tags prefixed by trigger
 can contain character entities prefixed by trigger
 TRIGGER=n
 describes the trigger character in decimal


 FACE=s
 Windows font name
 SIZE=n
 1 through 7, arbitrarily assign to point sizes relative, %, units
 affects linespacing
 POINTSIZE=n +
 exact height in points relative, %, units
 affects linespacing
 PITCH=n +
 in DOTS relative, %, units
 forces horizontal spacing of characters
 COLOR=xxx +
 colors listed elsewhere
 BACKGROUND=xxx +
 colors listed elsewhere

 ... 
 Superscript

 ... 
 Subscript

<GOTO> +
 X=n
 in DOTs relative, %, units
 accounts for unprintable area
 specifies left side of character cell
 Y=n
 in DOTs relative, %, units
 accounts for unprintable area
 specifies top of character cell

 ... 
 bold on/off
 ... 
 underline on/off
 ... 
 italics on/off
 
 break line
<HR>
 horizontal rule or rectangle
 SIZE=n
 height in DOTs relative, %, units
 WIDTH=n
 in DOTs relative, %, units
 COLOR=xxx
 OUTLINE=n
 width of outline, in DOTs relative, %, units
 always black
 X=n +
 in DOTs relative, %, units
 accounts for unprintable area
 defaults to centered on page
 Y=n +
 in DOTs relative, %, units
 accounts for unprintable area
 defaults to next line

<IMG>
 SRC=s
 file name, with forward slashes
 can be URL
 affected by BASE .. HREF, EXT
 currently supports BMP, JPG, and GIF formats only
 ALIGN=s
 top
 top of image to top of text
 middle
 middle of image to baseline of text
 bottom
 bottom of image to baseline of text
 default
 BORDER=n
 DOTs
 relative, %, units
 HEIGHT=n
 in IMG-DOTs
 defaults to bitmap's height
 WIDTH=n
 in IMG-DOTs
 defaults to bitmap's width
 HSPACE=n
 horizontal space around image
 in DOTS relative, %, units
 X=n +
 in DOTs relative, %, units
 accounts for unprintable area
 defaults to right after last text
 Y=n +
 in DOTs relative, %, units
 accounts for unprintable area
 defaults to next line

<BARCODE> +
 STYLE=s
 UPCA
 UPCE
 EAN13
 EAN8
 2OF5
 CODABAR
 CODE11
 CODE39
 CODE93
 CODE128
 CODE128B
 FACE=s
 Windows font name for caption text
 does not affect normal text
 POINTSIZE=n
 in points
 relative, %, units
 SIZE=n
 in points
 relative, %, units
 X=n
 DOTs
 relative, %, units
 specifies left edge
 Y=n
 DOTs
 relative, %, units
 specifies top edge
 SRC=s
 String to be barcoded
 SUPPLEMENT=s
 String for barcode supplement
 BARWIDTH=n
 inches
 relative, %, units
 defaults to .012"
 BEARERBARS=b
 OFF or ON
 TALLGUARDBARS=b
 OFF or ON
 CAPTION=b
 OFF or ON
 SHOWGUARDCHARS=b
 OFF or ON
 ADDCHECKCHAR=b
 OFF or ON

Order Online