17 July 1996 IT Solutions EDI Pseudo Printer Page 1 User's Manual for the IT Solutions EDI Pseudo Printer (ITSEDIPP) Version 2.0 by James Gray Walker "IT Solutions" GmbH 0. Table of Contents 0. Table of Contents . . . . . . . . . . . . . . . . . . . . . 1 1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Product Components . . . . . . . . . . . . . . . . . . . . . 2 2.1. IT Solutions Pseudo Printer Driver (ITSPPD) . . . . . . 2 2.2. IT Solutions Control DLL (ITSCTRL) . . . . . . . . . . 2 2.3. IT Solutions GNU AWK DLL (GAWKDLL) . . . . . . . . . . 2 2.4. The Control INI File . . . . . . . . . . . . . . . . . 2 2.5. AWK Script Files . . . . . . . . . . . . . . . . . . . 3 2.6. Other .INI and .DBF Data Files . . . . . . . . . . . . 3 2.7. A Calling Application . . . . . . . . . . . . . . . . . 3 2.8. An E-Mail System . . . . . . . . . . . . . . . . . . . 3 3. ITSEDIPP Invocation and Execution . . . . . . . . . . . . . 3 3.1. Printing Process . . . . . . . . . . . . . . . . . . . 3 3.2. Control Flow . . . . . . . . . . . . . . . . . . . . . 4 3.3. Data Transformation . . . . . . . . . . . . . . . . . . 4 3.4. E-Mailing . . . . . . . . . . . . . . . . . . . . . . . 4 4. Installation . . . . . . . . . . . . . . . . . . . . . . . . 4 4.1. The Installation Diskette . . . . . . . . . . . . . . . 4 4.2. Unzipping the Distribution . . . . . . . . . . . . . . 5 4.3. Installing the Object Modules . . . . . . . . . . . . . 5 4.4. Installing the Printer Driver within Windows . . . . . 5 4.5. Installing a Demo . . . . . . . . . . . . . . . . . . . 5 4.6. Installing the ITSEDIPP Windows Program Group . . . . . 5 4.7. Adding a Dummy Recipient to the Local Address Book . . 5 4.8. Examining the Sources . . . . . . . . . . . . . . . . . 6 5. Software and Hardware Requirements . . . . . . . . . . . . . 6 6. Licensing . . . . . . . . . . . . . . . . . . . . . . . . . 6 7. Support . . . . . . . . . . . . . . . . . . . . . . . . . . 7 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 Copyright 1996, ITS Information Technology Solutions GmbH. 17 July 1996 IT Solutions EDI Pseudo Printer Page 2 1. Overview The IT Solutions EDI Pseudo Printer is a false printer driver which generates EDI messages. To Windows, it looks like a normal printer driver to which any application can send a print job. Internally, ITSEDIPP captures the text printed to it, transforms it into an EDI message and e-mails the generated message. The transformation and e-mailing steps are fully configurable based upon configuration files, transformation scripts and the input text content. 2. Product Components 2.1. IT Solutions Pseudo Printer Driver (ITSPPD) The ITSPPD module implements the standard Windows printer driver interface. Any Windows application can print to it as if it were a printer or fax board. It captures the text part of the input printed to it, writes it to a file and submits the file to ITSCTRL. For more information, refer to the document "User's Manual for the IT Solutions Pseudo Printer Driver". 2.2. IT Solutions Control DLL (ITSCTRL) The ITSCTRL module executes a simple program, as specified in a control INI file. The program specifies the steps to carry out in order to a) transform the input text file from ITSPPD into the desired output EDI format and b) e-mail the resulting message to the local e-mail system. ITSCTRL calls GAWKDLL to perform the detailed and complex processing required to recognise the relevant elements from the ITSPPD input and transform them into an EDI message. ITSCTRL can write its e-mail output to systems conforming to Microsoft's Messaging API (MAPI), Lotus' Vendor Independent Messaging (VIM) API or Delrina's WinFax PRO. For more information, refer to the document "User's Manual for the IT Solutions Control DLL". 2.3. IT Solutions GNU AWK DLL (GAWKDLL) The GAWKDLL module is a DLL implementation of the Free Software Foundation's GNU version of the standard (originally Unix) AWK utility. It is responsible for the detailed processing and transformation of the data passed to it by ITSCTRL. For more information, refer to the document "User's Manual for the IT Solutions GNU AWK DLL". 2.4. The Control INI File The control INI file, ITSEDIPP.INI, contains parameters to control the text capture behavior of ITSPPD, but, most importantly, it contains the simple program which dictates what ITSCTRL is to do. It has the standard Windows INI file format. For more information, see the ITSPP and ITSCTRL documentation. 17 July 1996 IT Solutions EDI Pseudo Printer Page 3 2.5. AWK Script Files The AWK script files steer the data processing actions of GAWKDLL when it is called by ITSCTRL. Usually, ITSCTRL calls GAWKDLL multiple times within a single print job, so there are a number of different AWK script files. AWK has a simple, but very flexible, script language. It can be used for pattern matching, data selection, data validation and data transformation. Extensions have been made to GAWKDLL so that it can process Windows INI files and standard DBF database files. For more information, see the GAWKDLL documentation. 2.6. Other .INI and .DBF Data Files Depending on the implementation of the specific ITSEDIPP-based application, other data files using the .INI and .DBF formats can be accessed from within the AWK script files at runtime. Files with the .INI format are suitable for small databases, such as a trading partner list. Files with the .DBF format are suitable for larger data-validation databases. For more information, see the GAWKDLL documentation. 2.7. A Calling Application While not actually part of the product, a calling application is an important component in the overall picture. ITSEDIPP captures the text part of a printed document, so some application must generate these data. Any Windows application which prints according to the standard Windows printing protocol, and that means just about all applications, can print to ITSEDIPP. Of course, the application must have a document ready for printing which contains useful data for which ITSEDIPP has been configured to receive. 2.8. An E-Mail System Also not part of the product, an e-mail system is necessary if the generated EDI message is to be sent 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 here that the two leading groups of e-mail packages on the Windows market, those based on the Microsoft or Lotus standards, are supported. 3. ITSEDIPP Invocation and Execution 3.1. Printing Process ITSEDIPP is invoked (via Windows) by the user application. When ITSEDIPP (the ITSPPD driver) is chosen as the destination printer, the application learns of the "printer" attributes and capabilities by querying ITSPPD using the standard Windows printer driver API. The application can use this information to format the document contents for display on the screen before actually printing anything. At some point, the user will choose "Print" and the application will print the job. ITSPPD captures and buffers the printed text fragments as they are submitted. When a page is finished, ITSPPD arranges the fragments into their correct positions 17 July 1996 IT Solutions EDI Pseudo Printer Page 4 and order on the page and pushes the page into another buffer. When the whole job is finished, ITSPPD writes the completed text buffer contents into a temporary file and calls the ITSCTRL module for further processing. 3.2. Control Flow Once the print job has been finished by the application and written to the temporary file by ITSPPD, ITSCTRL takes over. First, ITSCTRL makes its own copy of the input file provided by ITSPPD. Then, it reads the simple program it is to carry out from the control INI file, ITSEDIPP.INI, and interprets and executes each step (stage) in turn. There are several types of stage which ITSCTRL can do, among them flow control and subroutines, file operations, complex data transformation by calling GAWKDLL and e-mailing by calling an e-mail API. See the ITSCTRL documentation for more details. 3.3. Data Transformation Transforming the printed input text into an EDI message can be a complex process and is usually divided into several steps. Each of these steps is accomplished by the GAWKDLL module, as called by ITSCTRL, and is driven by an AWK script. AWK scripts can be programmed to read data in, recognise and extract the relevant data, integrate data from other sources into the data, transform the data and write new output. See the GAWKDLL documentation. 3.4. E-Mailing At some point, all of the necessary data transformation will have been done and a file containing an EDI message will have been produced. ITSCTRL will then encounter a stage type which directs it to e-mail the EDI message to one of its known APIs. These APIs are Microsoft MAPI, Lotus VIM and WinFax PRO. The e-mail system on the receiving side of the API is expected to accept and then route the message to the specified destination. See the ITSCTRL documentation for more details. 4. Installation 4.1. The Installation Diskette The installation diskette contains six files: COPYING, DESCRIPT.TXT, INSTALL.BAT, ITSP20A.EXE, INSTALL.TXT and WHAT2DO.TXT. COPYING contains the GNU General Public License. DESCRIPT.TXT is a short description of the product. INSTALL.BAT is the installation batch file. INSTALL.TXT contains some advice about the product and its installation for those who do not have this manual. ITSP20A.EXE is a self-extracting .ZIP file; it is executed by INSTALL.BAT. WHAT2DO.TXT is a narrative of what you should do to become familiar with the product. If the defaults are acceptable to you (Windows directory is C:\WINDOWS and ITSEDIPP directory will be C:\ITSEDIPP), you can simply run the file INSTALL.BAT from the DOS prompt (without Windows running) and skip down to the section "Adding a Dummy Recipient..." 17 July 1996 IT Solutions EDI Pseudo Printer Page 5 below. This is strongly recommended because all of the demos are configured to have C:\ITSEDIPP as the base directory. 4.2. Unzipping the Distribution As commented above, ITSP20A.EXE is the self-extracting .ZIP distribution file. If you are installing the product by hand, you should copy this file to the location where you wish the ITSEDIPP directory to be installed. Then call it with the command "ITSP20A -e -d" and it will unpack itself. 4.3. Installing the Object Modules The package's four object modules, ITSPPD.DRV, ITSCTRL.DLL, GAWK.DLL and AWKLIB.DLL, are unpacked to the ITSEDIPP\BIN directory by ITSP20A.EXE. If your Windows directory is C:\WINDOWS, the file BIN_INST.BAT can be called to install the object files there. Otherwise, you need to manually copy them to the Windows system directory. See the file BIN.TXT for additional assistance. 4.4. Installing the Printer Driver within Windows The ITSEDIPP (ITSPPD) driver needs to be installed to the list of available printers within Windows. BIN_INST.BAT does this automatically by modifying the Windows WIN.INI file. You can do this manually by first making a backup copy of the WIN.INI file and then executing the command "gawk -f INILIB.AWK -f WININI.AWK" from the ITSEDIPP\BIN directory. See the ITSPPD documentation for more specifics on what is actually changed in WIN.INI. 4.5. Installing a Demo The product comes with six demos, ranging from a very simple first demo to an overly complex fifth demo, plus a practical, useable sixth demo. To install a demo manually, execute the file DMO_INST.BAT from the ITSEDIPP\DEMO directory. This script asks the user to choose which demo to install. By default, a zeroth (null) demo is installed. The sixth demo is recommended. Another demo can be chosen and installed later, but be careful; installing a new demo overwrites a previously installed demo, so any changes you may have made to the AWK scripts and INI files could be lost. 4.6. Installing the ITSEDIPP Windows Program Group Included in each demo is a prepared Windows program group file, ITSEDIPP.GRP, which gets copied to the Windows directory. DMO_INST.BAT installs, or reinstalls, this program group file to the Program Manager by modifying the Windows PROGMAN.INI file. You can do this manually by first making a backup copy of the PROGMAN.INI file and then executing the command "gawk -f INILIB.AWK -f PROGMAN.AWK" from the ITSEDIPP\BIN directory. 4.7. Adding a Dummy Recipient to the Local Address Book To test a demo with a local e-mail system, you will need to add the dummy recipient entry "editest" to your local mail address book. 17 July 1996 IT Solutions EDI Pseudo Printer Page 6 This is so that it will be a valid look-up name when ITSEDIPP (ITSCTRL), via the chosen e-mail API, tries to send e-mail to it. How to do this step depends on the mail program you are using on your system. Generally, you want to go into your mail program, open your local Address Book and add a new entry with name "editest" and a dummy mailbox address, or your own mailbox address. After this has been done, when ITSCTRL sends an e-mail message to alias "editest", the message will be accepted by the mail system and put into the dummy, or your, mailbox for verification. If you do not have an e-mail system or your e-mail system does not respond to the MAPI or VIM interfaces, you can still test ITSEDIPP. When you print to ITSEDIPP, all steps will be done up to the actual mailing and then an error will be reported when the mailing fails. However, the EDI message file and the intermediate files will still be there for your inspection. 4.8. Examining the Sources The source files are packed in six .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 already know where to get an unzip program on your own and probably already have one. Assuming your unzip program is, in fact, PKUNZIP, you can run the file SRC_INST.BAT from the ITSEDIPP\SRC directory to unpack the sources into the right places (in directories below SRC). To install the sources manually, you need to unzip each of the six *\*20S.ZIP files under the SRC directory. See SRC.TXT for more details. Even if you do not unpack the sources, you can still look at the CHANGES.TXT and PLAN.TXT files in each source directory to find out what has and what will happen with the various versions. 5. Software and Hardware Requirements The software requirements are Windows 3.xx or Windows 95 (ITSEDIPP has not been tested under Windows NT) and a Windows application which can print in the normal Windows fashion. Provided ITSEDIPP 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. ITSEDIPP itself imposes no special hardware requirements. 6. Licensing Following is the standard licensing statement for all GNU-"Free" software: 17 July 1996 IT Solutions EDI Pseudo Printer Page 7 ITSEDIPP 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. ITSEDIPP 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 ITSEDIPP; see the file COPYING. If not, write to the Free Software Foundation, Inc, 675 Mass Ave, Cambridge, MA 02139, USA. 7. Support The author of ITSEDIPP, 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 It is envisioned that two support activities will be most needed: talking through procedures on the telephone and script- and initialization-file setup, via telephone and e-mail. Customer visits can also be negotiated on a case-by-case basis. Additional work, such as porting, enhancements and customisation of the product or more concrete support contracts will gladly be taken on. 8. References User's Manual for the IT Solutions Pseudo Printer Driver (ITSPPD), Version 2.0, James Gray Walker, ITS Information Technology Solutions GmbH, 1996. 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.