17 July 1996 IT Solutions Pseudo Printer Driver Page 1 User's Manual for the IT Solutions Pseudo Printer Driver (ITSPPD) Version 2.0 by James Gray Walker "IT Solutions" GmbH 0. Table of Contents 0. Table of Contents . . . . . . . . . . . . . . . . . . . . . 1 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Components . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.1. ITSPPD.DRV . . . . . . . . . . . . . . . . . . . . . . 2 2.2. ITSEDIPP.INI Control File . . . . . . . . . . . . . . . 2 2.3. A Calling Application . . . . . . . . . . . . . . . . . 2 2.4. ITSCTRL Control Module . . . . . . . . . . . . . . . . 2 2.5. GAWKDLL Processing Module . . . . . . . . . . . . . . . 3 2.6. An E-Mail System . . . . . . . . . . . . . . . . . . . 3 3. ITSPPD Invocation and Execution . . . . . . . . . . . . . . 3 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 3 3.2. Printer Device Attributes . . . . . . . . . . . . . . . 3 3.3. Fonts and Text Rendering . . . . . . . . . . . . . . . 3 3.4. Printed Text Capture . . . . . . . . . . . . . . . . . 4 3.5. Further Processing via ITSCTRL . . . . . . . . . . . . 5 4. ITSEDIPP.INI Control File Structure . . . . . . . . . . . . 5 5. Installation . . . . . . . . . . . . . . . . . . . . . . . . 5 5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . 5 5.2. Unzipping the Distribution . . . . . . . . . . . . . . 6 5.3. Copying the ITSPPD Elements . . . . . . . . . . . . . . 6 5.4. Installing the ITSPPD Modules . . . . . . . . . . . . . 6 5.5. Installing the Printer Driver within Windows . . . . . 6 5.6. Examining the Sources . . . . . . . . . . . . . . . . . 7 5.7. Examining the Demos . . . . . . . . . . . . . . . . . . 7 6. Software and Hardware Requirements . . . . . . . . . . . . . 7 7. Licensing . . . . . . . . . . . . . . . . . . . . . . . . . 7 8. Support . . . . . . . . . . . . . . . . . . . . . . . . . . 8 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 Copyright 1996, ITS Information Technology Solutions GmbH. 17 July 1996 IT Solutions Pseudo Printer Driver Page 2 1. Overview As its name implies, the IT Solutions Pseudo Printer Driver is a false printer driver. To Windows, it looks like a normal printer driver, to which any application can print. Internally, ITSPPD captures what is printed to it, ignoring all but the text, writes the text to a file and passes the filename to the ITSCTRL module for further processing and e-mailing. Descriptions of the processing and e-mailing capabilities of the ITSCTRL module can be found in the documents "User's Manual for the IT Solutions Control DLL (ITSCTRL)" and "User's Manual for the IT Solutions GNU AWK DLL (GAWKDLL)". 2. Components 2.1. ITSPPD.DRV The ITSPPD.DRV module is the fixed component of the product. It is really a DLL file which has been renamed after having been built; that is what printer drivers are. It must reside in the Windows System directory. 2.2. ITSEDIPP.INI Control File The ITSEDIPP.INI control file serves two purposes. Firstly, it is the place where a few optional ITSPPD parameters can be specified. Secondly, but more importantly, it is the control INI file which ITSPPD passes in its call to ITSCTRL; in this respect, it controls the entire further processing of the captured input text. See the ITSCTRL document for more details. The ITSEDIPP.INI file must reside in the Windows directory. 2.3. A Calling Application While not actually part of the product, a calling application is an important component in the overall picture. ITSPPD captures the text part of a document which is printed to it, so some application must generate this printed data. Any Windows application which prints according to the standard Windows printing protocol, and that means just about all applications, can print to ITSPPD just as if it were another printer device driver. Of course, the application must have a document ready for printing which contains useful data for which ITSCTRL has been programmed to process. 2.4. ITSCTRL Control Module The ITSCTRL control module, delivered along with ITSPPD, is responsible for controlling the processing of the data which ITSPPD captures from the calling application. Details about ITSCTRL can be found in the document "User's Manual for the IT Solutions Control DLL (ITSCTRL)". 17 July 1996 IT Solutions Pseudo Printer Driver Page 3 2.5. GAWKDLL Processing Module The GAWKDLL processing module, also delivered with ITSPPD, is responsible for the actual detailed processing of the data which ITSPPD captures from the calling application. GAWKDLL is called as needed (as programmed) by ITSCTRL. More information about GAWKDLL can be found in the document "User's Manual for the IT Solutions GNU AWK DLL (GAWKDLL)". 2.6. An E-Mail System Also not part of the product, an e-mail system is a necessary component if the end result of the processing of the captured text is to be sent from the user's local machine out into the world. Compatibility with various e-mail systems is determined by the capabilities of the ITSCTRL module. So, more information can be found in the ITSCTRL documentation. Suffice it to say that the two leading groups of e-mail packages on the Windows market, those based on the Microsoft or Lotus standards, are supported. 3. ITSPPD Invocation and Execution 3.1. Overview As a printer driver conforming to the Windows printer device API, ITSPPD is invoked through a number of entry points on behalf on an application. See the Windows Device Driver Kit (DDK) for information on the printer device driver API. Broadly, there are two phases in the application-printer driver protocol. In the first phase, the application, via Windows as intermediary, queries the printer driver to discover its attributes and capabilities. In the second phase, the application, again via Windows, enables the driver to accept a print job, submits the print job and then signals that the job is completed. When signaled that the job is done, ITSPPD writes the captured input text to a file and calls ITSCTRL for all further processing. When ITSCTRL has finished, ITSPPD returns control to the application. 3.2. Printer Device Attributes As a printer driver, ITSPPD must simulate the responses of a real printer device driver when interacting with an application or Windows. ITSPPD reports that it is a text-only raster printer device with a 60x60 dots-per-inch resolution and which can only print single copies. The default page size is A4 (8.27" by 11.69") with portrait orientation. Additionally supported page sizes are Letter (8.5" by 11"), A3 (11.69" by 16.54") and Tabloid (11" by 17"). While landscape orientation can not be chosen in the printer setup dialog, it can be simulated by resetting the page dimensions. The application can explicitly specify any page size up to 1024 by 1024 pixels (17.06" by 17.06"). The entire "page surface" can be written to, that is, there is no minimum margin. 3.3. Fonts and Text Rendering When queried for available fonts, ITSPPD reports only one built-in font, a fixed-spaced "Roman" at 12 characters-per-inch and 17 July 1996 IT Solutions Pseudo Printer Driver Page 4 6 lines-per-inch. Due to earlier line- and field-wrapping problems resulting from a single, too-wide, fixed default size, the default characters-per-inch and lines-per-inch settings can be changed with the "FontCPI=" and "FontLPI=" assignments, respectively, in the "[Variables]" section of ITSEDIPP.INI. Note that these settings only make sense when given values which are integral factors of 60, because the pseudo device resolution is 60 dots-per-inch. The application may also request other fonts in other sizes. However, ITSPPD responds to all such requests with a fixed-spaced "Roman" font having the requested size and attributes, such as bold, italic, underline or struck-out. These attributes are not actually rendered when the job is "printed"; they just allow the application to approximate the original appearance better when displaying a document. This results in the document being displayed with fixed- spaced "Roman" fonts of various sizes and attributes when ITSPPD is chosen as the current printer. To see the document again with its original formatting, just change the current printer back to the printer driver normally used. 3.4. Printed Text Capture At some point the application will want to print the displayed document to ITSPPD. This usually happens as a direct result of a user "Print" command. The application then enables ITSPPD, submits the print job and signals ITSPPD that the job is finished. Internally, ITSPPD runs a state machine during this phase. When ITSPPD is enabled, the state machine associated with the print job is initialised. As the application proceeds to submitting text, signaling that the job is done or aborting the job, ITSPPD updates the state of the print job and, depending on the old and new states, carries out appropriate actions. In theory, several different kinds of objects can be submitted to a printer driver to be printed, for example, single pixels, bitmaps, lines, filled shapes and text. ITSPPD captures only the text and silently discards all other objects. The character set recognised by ITSPPD is ASCII printable only, that is, only characters between space (' ') and tilde ('~'). All other characters are replaced by underscore ('_') characters. White space before strings is filled with space characters, not tabs. Output lines are terminated by carriage return (CR, 0x0D) - line feed (LF, 0x0A) sequences. Windows generally submits print jobs a band at a time. A band is a horizontal strip of a page; the printer driver specifies how large a strip constitutes each band. ITSPPD dictates that each band comprises an entire single page. So, from a practical point of view, an application printing to ITSPPD submits an entire page of text at a time, which ITSPPD buffers and tentatively orders by page position. When the application signals that a page is finished and that the next page should be started, ITSPPD positions, orders and flushes the previous page's text to a sequential text buffer and prepares for the next page's text. After the last page has been finished and flushed to the sequential text buffer, the entire output text file is written to a temporary file for further processing by ITSCTRL. 17 July 1996 IT Solutions Pseudo Printer Driver Page 5 Because ITSPPD's output is text-only, font size is usually not meaningful. But, the one instance where the font sizes are meaningful to ITSPPD is when it has to decide whether two character strings are on the same line or on different lines. If a two strings have a vertical overlap (number of pixels at the ITSPPD resolution) equal to or greater than half the size of the smaller font, then the two strings are judged to be on the same line. This ensures that sub- and super-scripts do not break a single line into separate lines. Furthermore, the vertical extent of the larger font is saved for the next comparison so that lines with both sub- and super-scripts are handled reasonably. Finally, strings are sorted vertically for printing not by their top scan-line, but by their base-lines. This ensures that a slightly taller string in the middle of a line is not printed on a line by itself, followed by the remainder of the line on the next line. This set of string- positioning criteria is not perfect, but it generates a reasonable representation of just about any printed text document, and is certainly sufficient for the task at hand. 3.5. Further Processing via ITSCTRL After Windows gives notice that the print job is finished, the main printing control actions done by ITSPPD are to determine where to write the raw "printed" output text and to write the output. The location chosen is a temporary file, having the prefix "ITS", in the directory specified in the TEMP environment variable, as delivered by the Windows function GetTempFileName(). 4. ITSEDIPP.INI Control File Structure The ITSEDIPP.INI control file has the regular Windows INI file format with [sections], assignments, consisting of entries= and =values within the sections and ;comments. There is only one section needed by ITSPPD, named "[Variables]", which can hold a few variable assignments that modify the behavior of ITSPPD. Such an assignment has the form "=". Additional assignments in the "[Variables]" section and additional sections not used by ITSPPD may also be in the file and will be ignored. 5. Installation 5.1. Overview ITSPPD is distributed as part of ITSEDIPP and it does not make sense to try separate it from ITSEDIPP. However, it can be used independently if absolutely necessary. To install ITSPPD without ITSEDIPP requires that the distribution file on the ITSEDIPP installation diskette be unzipped, the ITSPPD, ITSCTRL and GAWKDLL elements copied from the ITSEDIPP directory and the ITSPPD.DRV, ITSCTRL.DLL, GAWK.DLL and AWKLIB.DLL object modules copied to the Windows System directory. Then, the ITSPPD printer driver must be registered with Windows to be accessible. At this point, the ITSEDIPP directory can be discarded, however, it is recommended that it be retained for a while, at least at first, for the examples in the demo directories. 17 July 1996 IT Solutions Pseudo Printer Driver Page 6 5.2. Unzipping the Distribution ITSP20A.EXE is the self-extracting .ZIP distribution file for ITSEDIPP. To get only ITSPPD, you should first install the ITSEDIPP directory by hand. Copy the file ITSP20A.EXE to the directory where you wish the ITSEDIPP directory to be installed. Then call it with the command "ITSP20A -e -d" and it will unzip itself. 5.3. Copying the ITSPPD Elements ITSPPD's driver file, ITSPPD.DRV, ITSCTRL's object file, ITSCTRL.DLL, and GAWKDLL's two object files, GAWK.DLL and AWKLIB.DLL, are unpacked to the ITSEDIPP\BIN directory by ITSP20A.EXE. Create a new directory for ITSPPD files and copy the four files there. ITSPPD's, ITSCTRL's and GAWKDLL's sources will be found in the directories ITSEDIPP\SRC\ITSPPD, ITSEDIPP\SRC\ITSCTRL, ITSEDIPP\SRC\AWKLIB and ITSEDIPP\SRC\GAWKDLL. Copy these four directories to your new ITSPPD directory. The documentation for ITSPPD, ITSCTRL and GAWKDLL are the files ITSPPD.*, ITSCTRL.* and GAWKDLL.*, respectively, in the directory ITSEDIPP\DOC. Copy them too to the new directory. 5.4. Installing the ITSPPD Modules Once you have the ITSPPD files segregated from ITSEDIPP, you can install them by copying ITSPPD.DRV, ITSCTRL.DLL, GAWK.DLL and AWKLIB.DLL to the Windows System directory, commonly \WINDOWS\SYSTEM. 5.5. Installing the Printer Driver within Windows The ITSPPD driver needs to be installed to the list of available printers within Windows, once the ITSPPD.DRV file is in the Windows system directory. This is done using the GAWK program and a couple of AWK scripts found in the ITSEDIPP\BIN directory. First, make a backup copy of WIN.INI in the Windows directory. Next, return to the DOS prompt by exiting Windows if you have Windows 3.x or restarting in DOS mode if you have Windows 95. Then, navigate to the ITSEDIPP\BIN directory and execute the command line "GAWK -f INILIB.AWK -f WININI.AWK". This modifies WIN.INI by inserting the line "PseudoPort=PseudoPort" into the "[ports]" section, the line "IT Solutions EDI Pseudo Printer=ITSPPD,PseudoPort,15,45" into the sorted "[PrinterPorts]" section and the line "IT Solutions EDI Pseudo Printer=ITSPPD,PseudoPort" into the sorted "[devices]" section. When Windows is restarted, the ITSPPD printer driver should be available for every Windows application when you select Print Setup, Choose Printer, Print, or however the application does it. It is not advisable to set or leave the ITSPPD driver as the default printer, although some applications do that when you print once to it. You will just have to switch the default printer back to the one you usually use in this case. 17 July 1996 IT Solutions Pseudo Printer Driver Page 7 5.6. Examining the Sources The source code is included in order to fulfil the provision of the GNU General Public License that you have free access to the source code to change as you wish. The source files are packed in ZIP files, for which you will need an unzip program, for example PKUNZIP, to unpack. If you believe you can make anything of the sources, then you will know where to get an unzip program on your own and probably already have one. 5.7. Examining the Demos The ITSEDIPP distribution contains six demos ranging from a very simple first demo to an overly complex fifth demo and an useable sixth demo. These demos can be found in the subdirectories of the ITSEDIPP\DEMO directory of the full ITSEDIPP distribution. 6. Software and Hardware Requirements The software requirements are Windows 3.xx or Windows 95 (ITSPPD has not been tested under Windows NT) and a Windows application which can print in the normal Windows fashion. Because ITSPPD calls ITSCTRL and ITSCTRL normally calls GAWKDLL, both ITSCTRL and GAWKDLL will be required. This is not a problem, as both are distributed along with ITSPPD. Provided ITSCTRL is configured to write to an e-mail system, then the corresponding system must be available. This can be either a MAPI-compatible e-mail system, such as WfW Mail or MS Mail, or a VIM-compatible e-mail system, such as cc:Mail or Lotus Notes Mail, or WinFax Pro 4.0. The hardware requirement is a machine which can run the chosen software configuration. ITSPPD itself imposes no special hardware requirements. 7. Licensing Following is the standard licensing statement for all GNU-"Free" software: ITSPPD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. ITSPPD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with ITSPPD; see the file COPYING. If not, write to the Free Software Foundation, Inc, 675 Mass Ave, Cambridge, MA 02139, USA. 17 July 1996 IT Solutions Pseudo Printer Driver Page 8 8. Support The author of ITSPPD, IT Solutions, will provide support at a fair price to users who need it. The contact information is: "IT Solutions" ITS Information Technology Solutions GmbH Untere Grasstr. 10 D - 81541 Munich Germany Phone: +49 (89) 69708525 E-Mail: walkerj at compuserve dot com 9. References User's Manual for the IT Solutions Control DLL (ITSCTRL), Version 2.0, James Gray Walker, ITS Information Technology Solutions GmbH, 1996. User's Manual for the IT Solutions GNU AWK DLL (GAWKDLL), Version 2.0, James Gray Walker, ITS Information Technology Solutions GmbH, 1996. Windows 3.1 Device Driver Kit, Device Driver Adaptation Guide, Chapter 4 - Printer Drivers, Microsoft Corporation, 1992. Windows 3.1 Device Driver Kit, Device Driver Adaptation Guide, Chapter 10 - Graphics Function Directory, Microsoft Corporation, 1992.