Windows LPR Spooler Version 4.0a A Network Printer Spooler for Microsoft Windows 3.1 July 6, 1994 This document was created with Microsoft Word for Windows 2.0 DISCLAIMER: THE SOFTWARE IS PROVIDED AS-IS. THE AUTHOR DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. NO LIABILITY IS ASSUMED FOR DAMAGES, DIRECT OR CONSEQUENTIAL, WHICH MAY RESULT FROM THE USE OF THIS SOFTWARE. (C) Copyright 1992-94 by Thomas Heil. All trademarks appearing in this document are the property of their respective owners. Table of Contents Table of Contents 3 Introduction 5 New Features 5 Requirements 5 Package Contents 6 Installation 6 If you upgrade ... 7 How Does the Spooler Work? 8 First Start 8 Adding/Changing Network Printer Definitions 9 Adjusting WLPRSPL Operating Parameters 10 WLPRSPL Running ... 11 WLPRSPL Menu Options 12 Usage Notes 14 Troubleshooting 14 Change Log 14 Licensing and Registration 16 Registration Fee 16 One Final Word ... 17 Registration Form 19 Introduction Windows LPR Spooler, in the following text abbreviated as WLPRSPL, is a program which allows transparent printing from Microsoft Windows 3.1 applications to network printers. WLPRSPL allows you to define a large number of remote printers which may be addressed through different Protocol DLLs. Included with the program is WLPR2.DLL which implements the Line Printer Daemon (LPD, RFC1179) protocol that is widely used on UNIX hosts. DLL's that support other network printing protocols will be developped over time. (For details on which Protocol DLLs currently exist, please contact the author. Note: Protocol DLLs other than those included in the shareware version will be available to registered users only.) New Features Version 4.0a offers the following new features: Support of the new WLPR2.DLL API which allows WLPRSPL to use different Protocol DLLs for different remote printer queues (like the included WLPR2.DLL that implements the LPR/LPD protocol). The spooler can run in a so-called "unattended mode". In this mode the spooler automatically retries failed print file transfers after a user-definable amount of time. The user is not interactively notified of such failures. Spool failures are displayed in the relevant queue line of the spooler window. Requirements The following components are required to run WLPRSPL: Microsoft Windows 3.1 WLPR2.DLL or compatible Protocol DLL(s). If the spooler is used together with the included WLPR2.DLL, the following additional components are required: TCP/IP networking software for the PC that offers a WinSock 1.1 compliant WINSOCK.DLL. WSOCKAID.DLL Version 1.0 or later. Users that run a TCP/IP stack other than FTP Software's should note the comment in the "Installation" section below. Package Contents This package contains the spooler (WLPRSPL.EXE) and the supporting libraries WLPR2.DLL Version 2.0a, WSOCKAID.DLL Version 2.0, and CTL3D.DLL Version 2.05, as well as this documentation in form of a PostScript file and a plain ASCII version. The following files are included in the standard distribution: WLPRSPL.EXE The main program. WLPRSPL.PS/.ASC Program documentation. WLPR2.DLL The Protocol DLL which supports the LPR/LPD protocol. WLPR2.PS/.ASC The documentation for WLPR2.DLL. WSOCKAID.DLL A supporting DLL that contains functions missing in WINSOCK.DLL. WSOCKAID.PS/.ASC The documentation for WSOCKAID.DLL. WSAIDCNF.CPL A Control Panel extension that allows the setting of the username for WSOCKAID.DLL. CTL3D.DLL A DLL that allows dialog boxes to have a 3D look. CTRLD10B.ZIP An archive that contains a small utility with which one can enable/disable the generation of a leading Ctrld-D for any installed PostScript printer driver. Installation Choose a directory where you want to install WLPRSPL and create it. Move the archive WLPRSnnn.ZIP to this directory and unzip it with PKUNZIP 2.04g or a compatible uncompression program. Move all W*.DLL files to the Windows directory or to another directory that is in your PATH, or include the directory where you installed WLPRSPL into your PATH. Copy CTL3D.DLL to your WINDOWS/SYSTEM directory after checking that there is not already a newer version. Then either create a new Program Manager group or open an existing one, and install WLPRSPL.EXE there (please refer to your Windows documentation on how to do this). After that you can start the program for the first time. For your convenience you should install the spooler also in your AUTOSTART group so that it gets launched automatically when you start Windows. A note about WSOCKAID.DLL: This is a network software vendor specific DLL containing a few functions that WINSOCK.DLL does not offer. Currently you will not get this DLL from your vendor. The version in this pack was written by us explicitly for FTP Software's PC/TCP stack. The function that WLPRSPL (or better WLPR2.DLL) uses is retrieving the user's login name. If you have FTP Software's PC/TCP 2.1 or higher, this DLL will take the needed information from the PCTCP.INI file (or whatever your PCTCP environment variable is set to). If you use a different stack, you may copy WSAIDCNF.CPL to your WINDOWS/SYSTEM directory. This small applet then allows you to set the username in the Control Panel. Note that the username is the only thing which WLPR2.DLL retrieves from WSOCKAID.DLL. All other information that WSOCKAID.DLL can give (as described in WSOCKAID.ASC or .PS) is ignored. The local PC hostname for example is retrieved from the networking software directly (through WINSOCK.DLL), which means that you have to have a PC hostname configured in your networking software. Protocol DLLs other than WLPR2.DLL may behave differently. Refer to the corresponding DLL documentation. If you use a TCP/IP stack that offers a real Windows network driver, then WSOCKAID.DLL tries to inquire the username through this driver instead of returning the INI file entry. You can verify if your TCP/IP software uses such a driver by looking at SYSTEM.INI section [boot]. If a non-empty entry "network.drv=" exists, then your networking software has such a driver. For further details concerning the included DLLs please take a look at the corresponding .ASC or .PS files. If you upgrade ... If you upgrade from Version 3.x to 4.0a, WLPRSPL will recognize this the first time you start the new version. You will be prompted if the settings of the old version shall be retained. If you accept this, you will further be prompted if the old Queue Definition File shall be converted to the new format (which now is in standard Windows .INI format). The old Queue Definition File must be writable when you choose to update it automatically. So if you have a shared QDF on a network drive you should start the new version on a PC with write access to this file first. It then gets converted, and on all other PCs you can skip the conversion when WLPRSPL 4.0a is started for the first time there. You can later load 3.x style QDFs with the Setup/Queues/Load queue definitions... menu option. The program automatically determines that the file is not a 4.0 QDF and asks if the file shall be read as 3.x QDF. After the file is read you can save it as 4.0 file. Note that the spooler settings are no longer kept in WIN.INI but in WLPRSPL.INI in the Windows directory. How Does the Spooler Work? Every printer used within Windows is connected to a so- called "port." Examples are LPT1, LPT2, COM1, COM2 etc. But those ports can also be normal disk files. When you add the line C:\SPOOL\DRUCKER.DAT= to the [ports] section of WIN.INI you may later connect a printer driver to this "port." Every print job sent to this port is written to the specified file. This is what WLPRSPL relies on. WLPRSPL uses a dedicated directory on the PCs hard disk for spooling (i.e. C:\SPOOL). This directory has to be specified the first time you start the program. For each network printer you want to print to you have to define a unique file name (i.e. HP.PCL for a HP LaserJet in PCL mode). This file name together with the chosen spool directory forms the port (in this case C:\SPOOL\HP.PCL) to which an appropriate Windows printer driver can be connected. The filename without path represents the local queue. A remote printer is defined by the local queue name as described above, the remote printer name, the host name of the computer that acts as printer server, and the name of the Protocol DLL to be used for connecting to the remote printer. The definitions of all remote printers are kept in a Queue Definition File (which will be abbreviated as QDF from now on). When starting the spooler for the first time, you have to specifiy the location of this file. It may either be located on a local drive, but it could also be on a shared network drive where it is maintained by some network printer administrator. You define remote printers by filling in the information described above into the queue setup dialog. WLPRSPL automatically creates the needed port in WIN.INI so that you later can install an appropriate printer driver for this remote queue. When you print to such a network driver from a windows application, the printer data is written to the corresponding spool file. WLPRSPL then puts the file into its own queueing system and sends the data to the remote printer. First Start When you start WLPRSPL for the first time you have to specify the spool directory you want to use. In the dialog that appears you can also create new subdirectories. Once you have selected the spool directory, you have to define the place where the QDF shall be located. It is possible to use a shared QDF that resides on a network drive and which is maintained centrally. The file that you specify does not have to exist at this time. It will be created as soon as you define the first queue in WLPRSPL. After this first time configuration you may define local queues for all remote printers you want to utilize. This is described in the next section. Then you should install appropriate Windows printer drivers for your network printers and connect them to the corresponding port. Adding/Changing Network Printer Definitions In order to define network printers in WLPRSPL start the program if not yet running, restore the program window if the program is iconized, and select the menu option Setup/Queues/Define new queue... or press Alt-Insert. A dialog pops up where you can enter a new queue definition. The fields in this dialog have the following meaning: Local Spool File: Name of the spool file (without path) that shall be used for the local queue. Remote Queue Name: Name of the queue on the remote print server. Remote Host Name: Internet host name or address of the remote print server. DLL to be used: Specifies the Protocol DLL to be used for this remote printer. It may be either the name only (which lets WLPRSPL search for it in the standard search order) or a fully qualified path name. WLPR2.DLL is the default for new queues. After filling in all fields you can review/change the options that are in effect for this queue by pressing the Queue properties... button. The options in the dialog popping up depend on the specified Protocol DLL. For the meaning of those options please refer to the DLL's documentation. When you press OK in the "Edit queue data" dialog, a new port is created if needed. Now you can go to the Control Panel/Printer Setup, install a printer driver that matches the remote printer, and connect it to the corresponding port. Take care that all printer characteristics you define match the remote printer. Normally a datastream from a Windows printer driver overrides settings of the remote printer defaults. If you select settings that the remote printer does not support it may hang. If you want to change the definition of a remote printer, select it in the main window listbox and click the menu option Setup/Queues/Edit queue data... or press Alt-Enter. You get the queue setup dialog box with the currently valid values filled in, ready to be altered. Changes to queues are not automatically saved. This has to be done either through Setup/Queues/Save queue definitions, or by accepting the automatic saving when WLPRSPL (or Windows) is terminated. After installing the printer driver you may print to the remote queue from any Windows application. Adjusting WLPRSPL Operating Parameters Through the menu (Setup/Preferences...) you can get to a dialog box where you can change the following operating parameters of WLPRSPL. Timer ticks in sec. This entry defines the time steps used by WLPRSPL to periodically check for possible spool files. It can be 0 which means that this feature is disabled. With this feature enabled it is possible to create spool files in DOS sessions and have them automatically entered into the WLPRSPL queueing system (see Usage Notes). Default is 0. Spool timeout in sec. Time in seconds during which a print job should be completed. If it takes longer the user is notified and may cancel the transfer. Default is 60. Warn if suspended When this check box is activated (default), you get a warning every time you print to a remote network printer if the spooler is currently suspended. Default is on. Unattended mode When this check box is activated, the spooler is in "Unattended Mode". This means that the user is not notified of spooling errors. Instead the faulty queue is temporarily disabled, and is re-enabled after the number of seconds specified. Default is on. Automatically re-enable queue after ... sec. If unattended mode is on, this entry specifies after how long a failed print file transfer is retried. Default is 300 seconds. Normally you can leave the default values as they are. If you notice a performance degradation on slow PCs due to the spool file polling set the Timer Ticks to a higher value, or set it to 0 if this feature is not needed. If you often print large documents or you only have a slow link to your print server you may want to set the Spool timeout... to a higher value. WLPRSPL Running ... When WLPRSPL is active you normally don't notice anything of its existance because the spooling is done in the background. The WLPRSPL main window always shows you what is currently going on. You see the following information being displayed: the time the spooler was started the mode in which Windows is running (Standard or Enhanced) the current state of the spooler (suspended or active) the current run mode of the spooler ("unattended" or "interactive") the currently used spool directory the currently used Queue Definition File a listbox displaying the states of all local queues (more detailed description below) the Windows printer driver used for the currently selected (and therefore highlighted) queue The individual columns in the listbox have the following meaning: Symbol If blank the local queue is currently not connected to a printer driver, if ">" it is connected, if "*" it is connected and is currently selected as default printer. Red "E" If present, it indicates that there was some spool error. You can check this error with the Queues/Show last error... menu option and remove the flag with the Queues/Clear error flag menu option. Loc. Queue Name of the local queue (and of the spool file). Rem. Queue Name of the queue on remote print server. Host Name of remote print server. Spool tries unsucc./succ. Number of print jobs sent over this queue since WLPRSPL was started or since the queue statistics were reset, and number of times the current spool file in a queue failed to be sent. Files queued Number of unsent print jobs. Permanently disabled queues (that means "disabled by user") are shown with red text. A temporarily disabled queue (disabled because of spool error in unattended mode) is shown with yellow text. A queue that is active sending a print job is shown in green, and the statistics are replaced with a progress message. WLPRSPL Menu Options Following is a list with all available menu options. On the right hand side the keyboard short cut is shown. Files Delete next spool file (Delete) Delete next spool file in selected local queue. Delete all spool files in queue (Ctrl-Delete) Delete all spool files in selected local queue. Delete all spool files (Shift-Ctrl-Delete) Delete all spool files in all local queues. Cancel spooling (Ctrl-C) A currently running transfer is cancelled. Suspend/Resume spooler (Ctrl-S) The spooler is suspended, or its operation is resumed, depending on the current state of the spooler. When the spooler is suspended, no print jobs are transferred to remote printers. Control Panel Call the control panel. Exit (Ctrl-X or Alt-F4) Exit WLPRSPL. Queues Show remote queue status (Ctrl-Q) Shows the state of the remote queue that corresponds to the selected local queue by executing an LPQ request. The dialog box showing the remote queue status then allows refreshing the display and cancelling one or more remote print jobs. Show jobs in local queue (Ctrl-L) Opens a dialog box that shows all jobs which are still in the currently selected local queue. In this dialog box you have the possiblity of removing jobs individually. Enable/Disable queue (Doubleclick on queue in listbox) The selected local queue is enabled/disabled. Scan queues immediately(Click right mouse button on WLPR SPL symbol) The spool directory is scanned for new spool files immediately. Retry to spool now If the queue is in retry timeout state (yellow text) because an error occured when trying to send the active spool file, the spooler retries immediately to send the file instead of waiting for the time to expire. Show last error... (Ctrl-E) A message describing the last spool error is displayed. Clear error flag (Ctrl-F) A message describing the last spool error is displayed. Reset selected queue (Ctrl-R) The statistics of the selected local queue are reset. Reset all queues (Shift-Ctrl-R) The statistics of all local queues are reset. Setup Preferences... Activates the dialog described in "Adjusting WLPRSPL Operating Parameters" Spool-Directory... Activates the dialog for selection of the spool directory described in "First Start". Queues > Define new queue (Alt-Insert) Activates the dialog for defining a new queue described in "Adding/Changing Network Printer Definitions". Edit queue data (Alt-Enter) Activates the dialog for editing queue data described in "Adding/Changing Network Printer Definitions". The dialog is filled with the data of the currently selected local queue. Delete queue (Alt-Delete) Deletes the currently selected local queue. Reload queue definitions Reloads the queue definitions from the currently active QDF. Load queue definitions... Activates the dialog for selecting a QDF described in "First Start". Save queue definitions Saves changes made to a queue definition in the currently active QDF. Save queue definitions as... Saves the current queue definitions to a QDF which must first be selected. If wanted, this new QDF can be made the currently active QDF, which will then be used the next time WLPRSPL starts. Register Program... Activates the program registration dialog. If you have a pre-registered version of the program, this menu option is grayed. Usage Notes When the spool directory is changed after the first installation, new ports are automatically generated for all local queues in the [ports] section of WIN.INI. The user then has to manually connect all printer drivers to those new ports. This is currently not done automatically. If you have a DOS application that can print to a file in addition to printing to a real LPTx or COMx, you can use WLPRSPL to spool those files. Just let the application print to the file that defines the port for the desired network printer (i.e. C:\SPOOL\HP.PCL). Then there are two possibilities to initiate the transfer: Either you have set the Timer Ticks to a non- zero value. In this case you only have to wait for the specified number of seconds, and WLPRSPL puts the file into its queueing system. If you have disabled this feature you can also switch back to WLPRSPL with Alt- Tab and select Queues/Scan queues immediately from the menu or click on the WLPRSPL icon with the right mouse button. The state of all queues (enabled/disabled, number and names of spool files) is saved in the spool directory as file filename.SPL, where filename corresponds to the name of the QDF. When, for example, the name of the QDF is WLPRSPL.QS, then the name of the queue state file is WLPRSPL.SPL. This file should not be deleted because it is needed to determine to which local queue any unsent spool files belong. When you print to a remote queue that automatically detects PostScript files and you get the PostScript text printed, this usually happens due to the fact that the Windows PostScript driver prepends the PS datastream with a Ctrl-D (0x04). This character normally causes a locally attached PS printer to reset, but it also makes it impossible for network queues to recognize the print data as PS file. Included in this package is a ZIP archive called CTRLD10B.ZIP which contains a small Windows utility that allows you to selectively enable or disable the Ctrl-D generation for all installed PS printers. Troubleshooting If you have problems with the spooler that can't be resolved through this document please take a look at the documentation of the supporting DLLs. There are given some troubleshooting tips which are specific to those DLLs. If this fails, too, please feel free to contact us. But do not forget to provide us with info about the program version, your operating system, and your networking software, as well as info about what printer and printer server you use (model, operating system etc.) Change Log Version 4.0a: Package includes WLPR2.DLL Version 2.0a. The logic when saving the state of a queue (enabled, disabled, retry timeout) was changed. Now, if a queue is permanently disabled, it will stay in this state when you close down the spooler and later restart it. Previously, a disabled queue went into "Retry timeout" state when the spooler was restarted. In the "Edit Queue Data" dialog the "Local Spool File" name now is limited to 12 characters. Long queue and host names extended into the data right of it in the main window list box. They are now truncated in the display. In unattended mode, the error code of a failed spool attempt is now kept and can be displayed with the Queues/Show last error... menu option. If an error occured, this is also indicated with a red "E" at the beginning of the relevant line in the spooler's main window listbox. Licensing and Registration This software is not free. It is shareware. You are granted the right to test this software for a period of 30 days. After this you have to register the product (see registration form at the end of this document) and, if this applies to you, pay the required registration fee. The unregistered shareware version displays a message box at the program start reminding you that the program has not yet been registered. When you register the program, you get a serial number and a corresponding key. Start the spooler, select the Setup/Register Program... menu option, and type your user information together with serial number and key into the dialog box. Then press the OK button. You may redistribute this program to other persons as long as you keep the package complete with all the files that are listed in the "Contents" section at the beginning of this document. Registration Fee Members of educational/non-profit institutions belong to Category I, all others belong to Category II. Please refer to the following table for pricing according to the number of licenses. Licenses Cat. I Price per License Cat. II Price per License 1-9 30 DM 60 DM 10 or more 25 DM 50 DM 20 or more 20 DM 40 DM 50 or more 15 DM 30 DM 100 or more 10 DM 20 DM For Site/Company Licenses and upgrades please contact us. If you want to pay in currency other than DM please contact us. If you want to wire the amount please assure that all fees are handled on your side. One Final Word ... Tell us everything you like or dislike about this program in order to let us make it better. Tell us about functions that you would like to see added. Tell us about problems you have encountered. You can reach us under the following E-mail addresses (first in the list preferred): th.heil@kfa-juelich.de ich211@zam001.zam.kfa-juelich.de ich211@djukfa11.bitnet ich211@ich210.ich.kfa-juelich.de or by ordinary mail as Software-Vertrieb Susanne Heil Hindenburgstr. 50 41352 Korschenbroich Germany or by fax under +49 (0)2161 644337 Registration Form (Please register WLPRSPL 4.0a when you decide to use it beyond the trial period of 30 days.) Name: Institution: Department: Street: City/Town and ZIP/Post Code: State: Country: Phone number: FAX number: E-Mail address: Customer Numberfrom a previous registration I would like to register _______ Windows LPR Spooler 4.0a licenses for an educational/no-profit institution.Total price: DM a commercial/for-profit institution. Total price: DM Payment: Remittance to:Bank: Stadtsparkasse Korschenbroich, Germany Bank Routing Code: 310 512 40 Account: 473017 included Cheque (in German currency) Date/Signature Please mail this form (with a possible fee included) to Software-Vertrieb Susanne Heil Hindenburgstr. 50 41352 Korschenbroich Germany