{{{ #!html
eCups is complete printing framework which is designed to allow the support of modern printers which lack ‘native’ OS/2 print drivers.
eCups includes the following components:
Although the terms are sometimes used interchangeably, there is a distinction between eCups and CUPS. eCups is basically a framework of related products and tools for integrating the CUPS product into OS/2 and eComStation.
CUPS stands for Common Unix Printing System. As the name implies, it was originally designed to be a generic framework for printer support under various UNIX systems. Since then, it has been adopted as the main printing engine under Linux and MacOS X as well.
It is important to keep in mind that CUPS is not a printer driver. At its most fundamental level, CUPS is essentially a print spooler plus a collection of data conversion modules.
The actual printer ‘drivers’ are located in addon packages like Gutenprint. CUPS itself does have a few built-in generic drivers, but generally you need at least one driver package installed in addition to CUPS itself.
Yes, it does... but the OS/2 spooler is only capable of receiving print jobs sent by various applications, converting them with a native OS/2 printer driver, and then sending them straight to the printer port (plus logic for managing the job queue, of course).
The CUPS spooler, by contrast, is able to perform a number of vital additional tasks during the process of sending a job to the printer. These tasks are what allow CUPS to support such a vast range of printers.
First of all, CUPS makes extensive use of PostScript, which is an open and widely-used standard for data formatting. A basic understanding of how PostScript normally works with regards to printing is needed in order to properly explain how CUPS works. Refer to the box below for a brief summary, or just skip past it if you already know this.
PostScript and Printing
Different printers require the data they receive for printing to be in a particular format or printer ‘language’. Naturally, printers from any given manufacturer typically use that manufacturer's own proprietary printer language. But even different printers from the same manufacturer often use slightly (or occasionally even radically) different variations of these languages. This is, of course, why we need specific drivers for our printers in the first place.
Some printers, however, (especially higher-end laser printers) are PostScript printers, meaning that they use PostScript as their printer language. (Often, it must be said, in addition to the manufacturer's proprietary language.) Because PostScript is an open, mature, and fully standardized language, this generally means that any printer driver which outputs generic PostScript data can print to any PostScript printer.
In this case, the individual capabilities of the printer (such as paper size, DPI, number and type of trays, duplexing, etc.) are provided by the manufacturer in standardized format via an ASCII file called a PostScript Printer Description (PPD).
The standard OS/2 PostScript printer driver includes a utility called PIN which allows these PPDs to be imported, thereby adding printer-specific support for the model in question without the need for new drivers.
Of course, since PostScript is a standardized language, it should also be possible to print to any PostScript printer using only generic settings (the PostScript driver includes a definition called "Generic PostScript Printer" for this purpose). As you would expect, however, using a generic printer definition does not let you take advantage of printer-specific features.
Given the above, there is rarely a problem with using any model of PostScript printer under OS/2, as long as a PPD for that printer is available. Where we need something like CUPS is for non-PostScript printers (of which, regrettably, there are many).
Basically, what CUPS does is add a PostScript emulation layer on top of all printers. That is to say, from the perspective of the operating system and applications, CUPS turns every printer into a PostScript printer. It accomplishes this emulation through a complex system of conversion utilities.
Because CUPS presents all printers as PostScript, it expects to receive incoming printer jobs in PostScript format. Generally, this is the responsibility of whatever passes the print job to CUPS in the first place, although CUPS is capable of converting a few specific file formats into PostScript on its own (such as plain text, PDF, or certain image formats).
CUPS takes each printer job it receives through the following steps:
(Some types of image file can be converted directly to CUPS-Raster format (see step C) when printing to a non-PostScript printer; in this case, CUPS skips step B and the first part of step C.)
If printing to a genuine PostScript printer, this data is then sent directly to the backend for printing (step D). Otherwise, it proceeds to step C.
The first filter, in most configurations, is "pstoraster", which uses GhostScript to convert the PostScript data into an intermediate format called "CUPS-Raster". (This format is supported by GhostScript as one of its available output formats.)
The CUPS-Raster data is then passed to another program which knows how to convert it into printer-specific data. (This latter program can thus, in a sense, be considered the actual printer ‘driver’.) CUPS has a few built- in programs for some common printer languages (generic support only), but more commonly an external driver package will be used. The largest such driver package is called "Gutenprint" (formerly called "gimp-print", as it was originally developed for The GIMP), which provides support for a large number of (mostly inkjet) printers. Other packages include HPLIP and Splix.
As it happens, GhostScript itself includes a number of printer drivers which aren't available in other packages like Gutenprint. In this case, the PostScript data can be converted directly to printer-specific format, rather than going through the process of CUPS-Raster --> external driver package. In cases like this, an alternative filter called "foomatic-rip" (or simply "Foomatic") gets called instead of pstoraster. Using instructions in the PPD file, Foomatic calls GhostScript in order to convert the PostScript data — not into CUPS-Raster format, but directly into the printer's native format instead. The usual second step of calling an external driver package is thus omitted. (Note that printers which use Foomatic for their drivers require a special PPD file with the required instructions.)
Whatever filters are called, at the end of this phase, CUPS should have a printer data file which is now in the printer's own native format, ready for actual printing.
A flowchart showing the various steps in more detail can be seen here.
See below for a more simplified flowchart which shows how these steps fit into the eCups framework under OS/2.
All CUPS printers are managed by the CUPS daemon, which is responsible for the whole process between receiving the initial job (in PostScript format), through all the filters and converters, to the backend whence it is passed off to the actual printer.
Once a printer is configured in CUPS, it is possible to print test pages from the CUPS administration GUI, as well as send files (or at least those in one of the supported formats) directly to the CUPS printer from a command line using the cupslpr utility.
To print from OS/2 applications, however, it is necessary to create a normal OS/2 printer object.
Wait! you ask. If we can already print files to the CUPS printer, why is it necessary to create an OS/2 printer as well?
Well, we can print using CUPS's own internal tools. The OS/2 printer object will be needed for the more general case. Basically, normal OS/2 (Presentation Manager) applications only know how to print to an OS/2 printer queue. They know nothing about any CUPS printers. So all our programs will be printing to our standard OS/2 printer object, and that gets sent on to CUPS.
How does that work? Well, we can redirect the jobs that get sent to an OS/2 printer so they end up going through CUPS. The OS/2 printing subsystem actually provides a mechanism for doing this, via a custom port driver. Instead of configuring the printer for LPTx or COMx, eCups includes a port driver, CUPS.PDR, which passes all jobs on to the CUPS daemon.
There's more; remember that CUPS needs the print jobs it receives to be in PostScript format before it can process them. CUPS does know how to convert a few specific file types into PostScript on its own, but it's not designed to handle the GPI format generated by most OS/2 applications. Happily, the OS/2 printer drivers are specifically designed to handle GPI data... and the PostScript printer driver in particular generates — naturally — a PostScript file, which then gets handed off to the printer. So, we just pass that file along to CUPS.
It's possible (at least theoretically; in practice there are sometimes various problems) to use the standard OS/2 PostScript driver for this. However, the eCups team has provided an updated PostScript driver called ECUPS.DRV; this is actually based on the standard PostScript driver, but with various fixes and other improvements to make it work with CUPS more smoothly.
The general flow of operation thus looks something like the following (greatly simplified, of course):
+-------------+ | Application | +-------------+ | | (OS/2-GPI printer format) | *======|=================== OS/2 PRINTER OBJECT =============================* # | # # v # # +---------------------------------------+ # # | PostScript printer driver (ECUPS.DRV) | # # +---------------------------------------+ # # | # # | (PostScript data) # # v # # +-----------------------------+ # # | CUPS port driver (CUPS.PDR) | # # +-----------------------------+ # # | # *====================================|=======================================* | *======================= CUPS =======|=======================================* # | # # | (Incoming PostScript data) (A) # # v # # +---------------+ # # | 'pstops' (B) | # # +---------------+ # # | # # | (Printer-specific PostScript data) # # | # # | # # PostScript printer? | Built in GhostScript driver? # # +------------------------< >---------------------+ # # | | | # # | CUPS or 3rd-party | driver module? | # # | | v # # | v +--------------------+ # # | +------------------+ | 'foomatic-rip' (C) | # # | | 'pstoraster' (C) | +--------------------+ # # | +------------------+ | # # | | | # # | | (CUPS-Raster format) | # # | v | # # | +-----------------------------+ | # # | | Printer-specific driver (C) | | # # | +-----------------------------+ | # # | | | # # | (PostScript) | <-(Printer-native format)-> | # # | | | # # v v v # # +------------------------------------------------------------------+ # # | CUPS backend (parallel/serial/USB/IPP/LPD/SMB/AppSocket/etc. (D) | # # +------------------------------------------------------------------+ # # | # *====================================|=======================================* | V +-------------+ | PRINTER (E) | +-------------+
The box labelled "CUPS" indicates components which are part of the cross-platform CUPS system. The whole diagram, with the exception of the application at the top and the printer at the bottom, comprises the eCups framework.
There are several. Some of the more prominent ones:
Until a proper fix can be developed, you can usually avoid the problem by "cleaning up" the PPD file before running PIN on it. The InstPDR utility (available on the eComStation BetaZone) does this automatically; there is also a script called CleanPPD (available separately) which does the same thing.
If all else fails, you should be able to use the Generic PostScript Printer driver (and configuring all printer-specific settings through the CUPS administration GUI); see question 2.5 for details.
This problem is currently under investigation. In the meantime, a couple of workarounds are available. First, it does not seem to occur when printing files which are already in PDF format, so if your application (like OpenOffice or some recent Mozilla builds) supports exporting to PDF, you can do that and then print the PDF manually using cupslpr or Lucide.
Alternatively, you can bypass CUPS (and Foomatic) entirely, and print using GhostScript as an inline print processor. This has the advantage of allowing basically seamless printing, at a cost of being rather awkward to configure properly. There are somewhat generalized instructions here.
Check out the eCups HOWTO, which provides detailed instructions, including screenshots.
When you go to add a new printer in the CUPS web interface, you will see a list of supported printer models, arranged by manufacturer. CUPS gets this list from all the driver packages which you have installed (like Gutenprint), plus the small number of generic drivers which CUPS includes natively.
Of course, some printers may be supported by driver packages which you don't currently have installed, in which case you won't see it in CUPS (until you install the required software). A good way to check for support for a particular printer model is to check the OpenPrinting Database. Keep in mind, though, that not all of the CUPS driver packages out there have been ported to OS/2 (and not all of them are open source in any case.)
First, you need to find out if a CUPS driver for your printer (or a compatible model) actually exists. The best place to find out is by looking through the printer list on the OpenPrinting web site.
If you've determined that your printer is supported, you will need make sure that the driver package required is installed. Currently, the following driver packages are available for eCups:
Go to the CupsPort page to download them.
You may also need to download the appropriate CUPS PPD file, if the support hasn't been included in the driver package already. The OpenPrinting site (see link above) is your place to go for these.
Finally, you have to install the support for your printer in CUPS and OS/2. In general terms, you need to do the following:
The eCups HOWTO describes these steps in more detail.
Browse the printer list on the OpenPrinting web site.
One may occasionally encounter a PPD file which can be imported into CUPS without problems, but which the OS/2 printer driver (ECUPS.DRV) chokes on.
If this happens to you, you can simply use the "Generic PostScript Printer" driver for the OS/2 printer object. Since CUPS is designed to operate on generic PostScript files, this should work just fine, as long as CUPS itself is properly configured to support your printer.
The main disadvantage of doing it this way is that you will be unable to set any printer-specific options in the OS/2 printer object or from the standard OS/2 job properties dialog. If you need to change the printer options, you will have to do so from the CUPS administration GUI.
CUPS supports several different types of network connection to a printer. Basically, you should choose whichever one your printer (or the print server it's connected to) supports best.
If your printer is being shared by a Windows, OS/2 Peer, LAN Server, or Samba file/print server, then you will probably need to use SMB (see question 2.11). Otherwise, choose whichever of the TCP/IP-based protocols your printer (or its print server) supports best.
Of course, it's quite likely that more than one of them is supported. In this case, you may want to consult the documentation that came with your printer/server (or ask your network administrator) to see if any of them is recommended specifically.
In general, IPP supports the most features, AppSocket/JetDirect has the best performance, and LPD is the most widely available.
Gutenprint provides many of its printer drivers (through its included PPD files) in both normal and "Simplified" versions.
The Gutenprint user's manual explains the difference:
The "simplified" PPD files offer a basic set of options only, for selecting printer options, standard paper sizes, and basic quality settings. The PPD files that are not "simplified" offer a much broader set of controls, giving the user extensive control over quality and color adjustment.
— Gutenprint 5.x user's manual
The Simplified drivers should be adequate for most peoples' needs.
OS/2 Presentation Manager programs only know how to print to an OS/2 printer object (or rather, to an OS/2 print queue, which is what the printer object defines). They know nothing about CUPS printers.
(Obviously, you can print directly to the CUPS printer using CUPS-specific tools like cupslpr or the CUPS web interface. But that doesn't help us with the general case.)
Creating an OS/2 printer object gives applications somewhere to send their print jobs. What we do in this case is configure that printer object to redirect all its jobs to CUPS. This is done by setting the printer output port to a CUPSx port, which you must configure with the name of the corresponding printer defined in CUPS.
To put it more simply: OS/2 printer objects know how to receive print jobs from applications. CUPS knows how to send that data to the actual printer. So they have to work together in tandem in order for printing to work.
In an ideal world, a corresponding OS/2 printer object would be created for you automatically whenever you created a new printer in CUPS. Unfortunately, there is no way to do this just at the moment, so you have to create them both separately yourself.
It may also strike you as confusing that you can't simply add support for your printer by importing the PPD into the ECUPS or PSCRIPT driver (as you can with non-CUPS printers). After all, the driver now lists your printer as supported, just as it does for native printers... so what's the problem?
The thing is, what the driver lists as supported isn't the true printer — it's the PostScript-emulated version of that printer presented by CUPS. It depends on going through CUPS in order to translate it into the printer's actualy format. If you were to select a CUPS-based printer driver and then try printing directly to the printer (instead of going through the eCups port driver), the printer wouldn't understand the job and would either reject it or start spewing out garbage. (Unless, of course, it really is a PostScript printer.)
In principle, you can set your preferred printer settings in either the OS/2 printer object or in CUPS itself.
When you configure options in the OS/2 printer object, the resulting PostScript file which gets sent on to CUPS will have those settings defined. In this case, CUPS should respect them.
The settings in CUPS itself (which you can configure through the web administration GUI) can be thought of as fall-back defaults. Any options which you set in the OS/2 printer object (or in the job properties dialog which most applications will offer you before printing) should take priority. Options which were not set in the printer object (and which are thus not defined in the PostScript file which CUPS receives) will fall back to the CUPS-configured defaults.
Just to avoid confusion, it's a good idea to keep both the printer object defaults and the internal CUPS defaults synchronized with each other.
It depends on which specific component you are upgrading:
Generally, you can just unzip the new cups-*.zip (or install the latest cups-*.wpi using WarpIN) over your previous installation. You should back up the existing \cups directory tree first, though.
If you'd rather install cleanly (while preserving your setup), do the following:
After upgrading (either way), check the file \cups\lib\cups\filter\pstoraster and make sure the "prefix=" line points to your correct GhostScript path.
Finally, start the CUPS Daemon (cupsd.exe), then go into the web administration GUI and double-check that your printers and settings are correct.
(If everything works properly, you can delete any backed-up/renamed previous versions of CUPS. It's a good idea to run with the new version for a while before doing this, however.)
After unzipping the new version, edit the file (in your CUPS installation) \cups\lib\cups\filter\pstoraster, and change the "prefix=" line to point to the new GhostScript path.
If you have GSView installed, and want to make it use the new version of GhostScript (recommended), run GSView and go into "Options" --> "Advanced Configure". Make sure the "GhostScript include path" is updated to point to the new GhostScript directory. (See the file readme.os2 included with GhostScript for what this path should look like in general.)
Once you have everything changed over to use the new GhostScript, and you've verified that it all works properly, you can delete the old GhostScript subdirectory.
To set up a printer using the SMB/CIFS (i.e. Peer/Samba/Windows network) protocol, an extra step is required.
Specifically, you need to obtain the file smbspool.exe from the OS/2 Samba client port. Rename this file to smb.exe and place it in the /cups/lib/cups/backend directory. The next time you go into the "Add printer" page in the CUPS Adminstration GUI, you should see a new option for "Windows or SAMBA" printer listed.
Enter the URI in the form:
smb://username:password@hostname/queue
First of all, go into the CUPS web GUI by pointing your browser at http://localhost:631.
The best place to go first is probably the Printers page. Each defined printer will show its current status; if a printer error was received by CUPS, that printer will show the error message under the status column.
For more detailed information, go to the Administration page. There's a button on that page called "View Error Log", which will show you all errors and warnings that were recently logged by CUPS.
For even more detailed diagnostics, you can enable the checkbox labelled "Save debugging information for troubleshooting". (Changing this setting requires the CUPS daemon to be restarted.) Of course, this setting is only useful if it was enabled before the error occurred... so if you decide to activate it, you'll presumably want to resubmit whatever job caused the error you're trying to diagnose.
Reading the error log (with or without debug information enabled) can be a bit intimidating to the uninitiated. It's not all that hard to work out with a bit of practice, however.
This problem happens if the desktop is unable to load the driver information for some reason. This can be caused by a number of things; the most common reasons are listed below.
To fix this, manually copy the updated AUXPRINT.PAK over from the directory where PIN output the imported files.
If this happens, you will probably have to replace the file with a fresh copy from the original install package, then re-import any PPDs which you previously imported.
The fix in this case is to open an INI editor (such as the built-in "registry editor" REGEDIT2.EXE) and make sure that the application PM_DEVICE_DRIVERS contains the key ECUPS (no extension), whose value is the fully-qualified filename of ECUPS.PDR. This should become effective immediately. (If the problem occurs with a different driver, such as PSCRIPT or ECUPS-HP, substitute the appropriate driver name in both the key name and the value.)
Unfortunately this error can be caused by a number of things. However, it usually means that CUPS encountered an error when trying to run Ghostscript.
The most common cause of this error message is that the script \cups\lib\cups\filter\pstoraster does not specify the correct path to your Ghostscript installation. Edit the pstoraster script and locate the prefix= definition (usually the first non-comment line in the file). Make sure that the correct path to Ghostscript, relative to the CUPS directory, is specified after the "=" (using forward slashes instead of backslashes).
Also note that Ghostscript must be installed on the same drive as CUPS.
First of all, obviously, make certain that it's not a physical problem with the printer. Also ensure that you are using the correct driver, and that the OS/2 printer object is printing to the proper CUPS port (and not directly to the printer port).
If you're certain that the problem lies with OS/2 and CUPS, check your version of Ghostscript. Problems of this nature are reported to occur sometimes with recent versions (9.0 and above) of Ghostscript. The cause is under investigation; in the meantime, try using Ghostscript version 8.71 (or earlier) and see if that works.
All-black or corrupted printouts have also been reported to occur sometimes when printing the second and subsequent jobs since the printer was turned on, even though the first job printed perfectly. This problem may have been resolved with recent releases of CUPS. If it still occurs after upgrading to the latest CUPS, try turning the printer off and on, then try printing the job again. }}}