lpr.txt
2000-06-03

User manual for Thomas' lpr remote printing clients and server package.


Introduction

Peter Rottengatter's STinG TCP/IP stack for Atari ST/TT/Falcon machines and
compatibles (denoted ST for short below) provides internet access but also
aims for a complete TCP/IP network solution. One useful feature of
networked computers is the ability to share printer hardware. This package
provides client and server software for STs to access remote printers on
STs or other machines. As the software is compliant with RFC1179
interoperability is ensured. Although the software resembles the BSD
printing system that is often used on other operating systems like Linux,
it uses the features of GEM-AES and STinG for easy installation and
operation under both single tasking TOS and multitasking OS.


Prerequisites

I assume that you have built a STinG TCP/IP network of one or more STs
and/or any other networked machines. This package is of no use for you if
you just use STinG to access the internet via a provider.
You MUST use STING.PRG version 1.25 or later.

It does not matter if the machines are networked via the serial port, midi
port, ethernet, what ever.

Your STs may run a single or multitasking OS. Additional support is
provided for MagiC. Additional support for MINT is in the works.

In order to print from an application running on an ST you must be able to
generate a file instead of sending the output directly to the printer. The
TRLPR package is currently known to be useful with the following
applications:

That's Write 3.11 PS
Papyrus 7.58a
Texel 2.00
Arabesque 2 V1.2
Xact 3.10h
Phoenix 5.0

In particular if you use NVDI (version >= 4) as GDOS, you win as the NVDI
printer drivers can print to a file. Thus *any* application that supports
printing via GDOS can print remotely.


Installation

Unpack the archive TRLPRxxx.LZH to any directory you like using LHARC or
similar.
The following installation steps depend on your configuration. The
instructions below cover typical usage examples. For reference information
about the individual TRLPR components see the files *-MAN.TXT.


Example 1)

Your ST is linked to a network with a Linux or other Unix server. This
server is reachable from the ST under the name "machine1". For that to work
you need to associate "machine1" with the server's IP address by manipulating
the resolvers CHACHE.DNS file (see STING.HYP). You may however use the
server's IP address instead of "machine1" in the examples below.

First make sure STinG is up and running on your ST and you can ping the
server.

You have to have an user account on the server, the username be e.g.
"thomas".

Edit the file /etc/hosts.lpd on the server. The host name of the ST must be
added to this file such that the ST is allowed to access the printer
server. In this example the ST shall have the name "machine2" associated to
the ST's IP address.


Edit the file DEFAULT.CFG the STinG installation uses on the ST with a text
editor.

Add the following lines to DEFAULT.CFG (USERNAME and HOSTNAME may already
be present but void):
#
USERNAME = thomas
HOSTNAME = machine2
#
LP1_QN = lp
LP1_RM = machine1
LP1_SD = C:\TMP
#

This assumes there exists a printer queue on machine1 with the name "lp".

machine1 is the hostname of the remote Linux server. STinG must be able to
resolve this to a valid IP address. Hence in this case machine1 needs to be
associated to the servers IP address using the STinG resolver module. You
may however use plain ip addresses for LP1_RM.

The entry LP1_SD must specify an existing directory on the ST where to put
temporary files.

Reboot the ST


Example 1a)

Everything else like above but you wanted to print to a different queue on
the Linux box e.g. with name "HP4" you would edit DEFAULT.CFG like this:
#
USERNAME = thomas
HOSTNAME = machine2
#
LP1_QN = lp
LP1_RP = HP4
LP1_RM = machine1
LP1_SD = C:\TMP
#


Example 2)

You have linked just two ST machines. You have physically connected a
printer to ST#2 on the parallel printer port. You run single TOS on ST#2.
ST#2 shall act as a printer server. You want to print from ST#1.

First make sure STinG runs well on both machines and you can ping in both
directions. Also alias names like machine1 and machine2 you gave to both
machines are resolved when you ping from both sides.

Configure ST#1 like the ST in example 1) above.

Edit the file DEFAULT.CFG you STinG installation uses on ST#2 with a text
editor.

Make sure you have the following lines in DEFAULT.CFG:
#
LP1_QN = lp
LP1_LP = PRN:
LP1_SD = C:\TMP
#

The last entry must specify an existing directory on ST#2 where to put
temporary files.

Copy lpd.prg to the root directory of the boot drive of ST#2 and rename it
lpd.acc.

Reboot ST#2

When ST#2 comes up again do not worry that lpd.acc does not show up as a
desk accessory in the menu. It need not as it has no user interface.

At ST#1 configure your desktop such that you may drop files on lpr.prg.


How to Print

When you have generated a file to be printed you simply drop this file on
lpr.prg. lpr.prg starts and takes the file as an argument. It sends the
file to the remote printer spooler daemon. If everything runs smoothly it
keeps quiet.
It shows a dialog box only in case of error to indicate the cause. Note
that this is not possible with the desktop of older single TOSes. Here you
could work around by giving the file a special extension and configure the
desktop such that lpr.prg is launched once the file is double clicked.


MagiC Support

If you run the MagiC TOS compatible operating system on an ST you may
want to also install the device driver lp.dev :

-       Copy lp.dev to the location indicated in you MagiC manual. E.g.
        C:\GEMSYS\MAGIC\XTENSION

-       Make sure you have added settings to the file DEFAULT.CFG
        like in example 1).

-       Reboot. You should see now a new device called  lp  in the
        directory u:\dev

-       Test the device driver by copying a small file to u:\dev\lp .
        Example using the Mupfel shell:
                cp anyfile u:\dev\lp

        Note that MagXDesk will not allow you to drop a file on u:\dev\lp
        to trigger a copy. So printing from the desktop MagXDesk still
        requires use of lpr.prg (see below).

-       Redirect GDOS/NVDI printing to the "file" u:\dev\lp . This can be
        effected by modifying the output file in the NVDI printer device
        CPX (NPRNCONF.CPX) as described in the NVDI manual.

-       Printing from an application that uses GDOS to print will now go
        right away over the network to the remote printer.


The Queue Concept

The lpr package centres around the concept of printer "queues".

There are queues defined on the server. When you add lines to DEFAULT.CFG
like in Example 2) to be used by the print server lpd.prg, you define a
queue and associate it with a physical printer.

Additional queues differ in the third character of the DEFAULT.CFG
variables:

LP1_QN = ...    first queue
LP1_LP = ...
LP1_SD = ...
#
LP2_QN = ...    second queue
LP2_LP = ...
LP2_SD = ...
#
LP3_QN = ...    third queue
LP3_LP = ...
LP3_SD = ...

Hence nine queues may be defined. Note that you can refer to the same
physical printer with more than one queue (with a different queue name
LPn_QN though).

Similarly you define printer queues on each client machine. These may also
be up to nine. For a client queue you also specify a mapping between local
queues and remote queues. Example DEFAULT.CFG:
#
LP1_QN = lp
LP1_RP = the_hp
LP1_RM = machine1
LP1_SD = C:\TMP #

The line LP1_RP = the_hp associates the *remote queue* the_hp on machine
machine1 with the local queue lp (as defined by LP1_QN = lp).
If LP1_RP is missing the name for the remote queue defaults to the name 
for the local queue.

This mechanism may seem complicated at first but provides some
flexibility.
E.g.: with this release lp.dev always looks for the local queue lp and you
thus need LPn_RP to address a remote queue with a name different from lp.
Similarly lpr.prg also looks for the local queue lp by default. Other
queues may be chosen by a command line option for lpr.prg however.

With a Linux remote server you can usually reach one and the same physical
printer by different queue names. Thus you achieve different processing
(filtering) on the data before they reach the printer. That is supported by
this package. The lpd.prg daemon for STs supplied with this package however
does not (yet) have such filtering capability.



Limitations


I developed and tested lpr with the following configuration:

-        STinG v 1.25 running SLIP via Modem1 or my own ethernet driver
         on a custom built NE2000 adapter on an 4MB 260ST under
	 MagiC 5.11 and TOS 1.04

-        Lpd running on a PC under OS/2 Warp 4 with built-in TCP/IP

-        Lpd running on a PC under SuSE Linux 5.3

-        HP Deskjet 690C connected to the PC

I welcome any notice on which platforms it does run.
I do not welcome any notice on which platforms it does not run ;-) .

lpr.prg and lp.dev comply with RFC1179. The main limitation is missing
input filtering.

lpd.prg supports a subset of RFC1179 enabling printing only. Queue queries
and other operations are not yet supported.


How to use MagXDesk's printer icon

If lpr is working well from the command line or by drag and drop, you may
want to replace print.ttp from MagiC's MagXDesk with lpr.prg in MagiC's
configuration:
Optionen, Einstellungen..., Dienstprogramme, Ausgabe: c:\bin\lpr.prg

Thus you can print files by drag and drop on MAGXDESK's printer icon.
Similar results can be obtained with other shells.


Choosing the correct NVDI printer device driver

When using NVDI or similar software you can easily redirect GDOS
printing to a file. If no filtering on the remote host is active you need
to "print" to a file using a GDOS printer driver for the *same printer 
model* that is attached as the remote printer.


Where to Complain About the Queue Model

The queue concept of this lpr package and the command line options of
lpr.prg are similar to the BSD lpr package in widespread use under e.g.
Linux.


Other Ways to Run lpd.prg

Copy lpd.prg to a directory where it gets automatically started at system
start. Example: for MagiC this is like C:\GEMSYS\MAGIC\START


Print Job Filtering on Linux Servers

If you do want a filtering happen, for example you send an ASCII file with
lpr and the remote host should convert to Postscript before print, you need
to configure the lp-daemon (lpd) at the remote host. A good description of
this can be found in the Linux documentation or the periodical c't 17/98
page 190.
lpd.prg for the ST however currently does not support filtering.


LPD and LPR on the same ST?

You may run lpr.prg/lp.dev and lpd.prg/lpd.acc on the same machine thus 
using the machine as an lpr server and client the same time.
Although this does look like overkill it may be useful for testing.

Say you have following lines in DEFAULT.CFG to operate lpd.prg:
#
LP1_QN = lp
LP1_LP = PRN:
LP1_SD = C:\TMP
#

If you run lpr.prg it will look for but not find an LP1_RM. However the
remote machine defaults to 127.0.0.1 and that is by convention the local
machine. And the remote queue defaults to the name of the local queue. Thus
you can still reach this printer from lpr.prg as the printer lp (which is
the default for lpr.prg as well).


History

Version              From              What
0.90B                1998-11-10        First release, beta

1.00B                1999-11-08        Fixed bug in lpr.ttp cFA file
                                       (added the 'd')
                                       Added lp.dev MagiC device driver

1.10B                1999-12-28        Added lpd.prg printer daemon
                                       Converted lpr.ttp to use GEM 
				       (lpr.prg)

1.10                 2000-07-17        Fixed bug preventing print of
                                       long files (lpr.prg)
				       Changed LPA...LPZ to LP1...LP9
				       


License & copyright

This lpr package is freeware. I allow you to use and distribute it freely
under the condition that you do not change the package in any way without
my explicit consent.
(c) Copyright Dr. Thomas Redelberger 1998, 1999, 2000.


Credits

I thank Dan Ackerman and especially Peter Rottengatter for initiating and
developing this great and free TCP/IP software for the ST and compatibles
and Ulf Ronald Andersson for valuable help and suggestions.


Disclaimer

This package is provided to you as is. I do not guarantee any features nor
do I take any responsibility for any damage or loss you may suffer when
using this software.


Contact Information

Suggestions, bug reports, flames are welcome

Dr. Thomas Redelberger
EMail:     redetho@gmx.de
Fax:       +49 6023 999410

