LPINST
------

For information regarding the LPRPORTD print director provided by
OS/2 TCP/IP, please see the TCP/IP Guide.

The LPINST utility provides configuration for LPRPORTD in two ways.
First, LPINST adds or deletes the \PIPE\LPD ports in the OS/2 print
subsystem.  These ports are used to direct print jobs to network print
servers.  If you open the settings notebook for a printer object,
these ports can be found on the "Output" page.  Second, LPINST can use
a plain-text file to configure the characteristics of any of the
\PIPE\LPD ports.  This eliminates the need to work interactively with
the printer object's settings notebook.  A site administrator can
easily configure a workstation in their network without physically
interacting with that workstation.

   NOTE: Since there is no OS/2 API to specify a printer object's
   output port, LPINST can not change a printer object's output
   port from "LPT1" to "\PIPE\LPD1".  Selecting which port receives
   the printer output still requires interaction with the printer's
   "Output" page.

Command Syntax
--------------

   >>---LPINST ---------------------------------------------------------------
                 |               | |        | |             | |              |
                  -- -# number --   -- -d --   -- -t path --   -- FileName --

       -# number
         the number of printer \PIPE\LPD ports you want on this machine

       -d
         enables LPINST debug mode, providing more information about
         LPINST's activity

       -t path 
         specifies the path to the TCP/IP product directory

       FileName
         the name of the file containing predefined \PIPE\LPD settings.

TCP/IP Product Path
-------------------

The LPINST utility relies on the LPRPDRVR.PDR in your TCP/IP DLL
directory to perform some of its work.  LPINST will attempt to
locate LPRPDRVR.PDR.  If LPINST can *not* locate LPRPDRVR.PDR,
LPINST terminates.  You can specify the path to your TCP/IP
product directories with the "-t" option to LPINST:

  LPINST -t <path>

For example, if your TCP/IP product is installed in "E:\TCPIP",
you would issue LPINST:

  LPINST -t e:\tcpip

Creating ports
--------------

Each printer object on the desktop needs a port to direct its output
to.  LPRPORTD supports up to 64 output ports for printer objects
directing their output to network print servers.  For example, if you
have 5 printer objects on your desktop and you want all 5 printers to
be directed through LPRPORTD to a network print server, you will need
5 ports, "\PIPE\LPD0" through "\PIPE\LPD4".  If you have 5 printer
objects on your desktop and you only want 2 printers to be directed
through LPRPORTD, you need 2 ports, "\PIPE\LPD0" and "\PIPE\LPD1".

Use the '#' option on the LPINST utility to create these ports:

   LPINST -# <number>

If you already have \PIPE\LPD output ports defined, the LPINST utility
will either create more ports to bring the total number of ports up to
the number specified or deactivate any ports above this number.  For
example, if you already have "\PIPE\LPD0" and "\PIPE\LPD1" and you
issue "LPINST -# 5", LPINST will only create ports "\PIPE\LPD2"
through "\PIPE\LPD4".  If you already have 5 ports and you issue
"LPINST -# 2", LPINST will simply deactivate ports "\PIPE\LPD2"
through "\PIPE\LPD4".

Defining the ports
------------------

Each port is mapped to a particular network printer.  In order to locate
this network printer, each port has characteristics which must be
defined, such as the remote server's hostname, the printer on the remote
server which will receive the output, the client machine's hostname, etc.

To configure these characteristics interactively, open the printer object's
settings notebook.  Select the "Output" page.  Select a LPRPORTD printer
port ("\PIPE\LPD1") by double-clicking on it.  Fill in the fields which
you require and press the "OK" button.  (The fields "LPD server" and
"LPD printer" provide the minimum information required for LPRPORTD.)

To configure the port characteristics with LPINST, you must write a
short plain-text file.  When issuing the LPINST command, you specify
the name of this file, and LPINST will configure the ports based on
the information you supplied in the plain-text file.

The plain-text file is line-oriented.  Each line of the file defines
either a port name or a characteristic of that port.  To define a port
name, enclose the port name in brackets.  All characteristics
following the port name are associated with this port, one
characteristic per line.  Here is an example of the plain-text file:

     [\PIPE\LPD0]
     Server = "jake.raleigh.ibm.com"
     Printer = "Printer"

     [\PIPE\LPD1]
     Server = "stinky"
     Printer = "Lexmark4"
     User = "jakec"
     Host = "jake.raleigh.ibm.com"
     MailTo = "jakec"
     Card = "f%jobfilename%"

Notice that the values of the characteristics are enclosed in quotation
marks.  If a value requires a quotation mark, the quotation mark can be
escaped with the '\'.  Since the slash character has this special meaning,
you must use two slashes to include a slash in the value.  Here are two
examples:

  Server = "Foolish\"Hostname"      value is Foolish"Hostname
  Printer = "postscript\\printer"   value is postscript\printer

Here is a complete list of the characteristics which can be defined in
the plain-text file: server, printer, host, user, spooler, queue,
network, settings, filter, mailto, class, and card.  Each
characteristic corresponds to an entry on the \PIPE\LPD settings page.
For information about these characteristics see the TCP/IP Guide.

You do not need to include all of the characteristics for each port.
Include only those characteristics which you are interested in
defining.

If LPINST encounters any errors in the definition of a port, that port
is ignored.  Any ports not explicitly defined in the plain-text file are
not configured.  In the example above, only the ports "\PIPE\LPD0" and
"\PIPE\LPD1" are configured.  All other ports are simply ignored.

If the plain-text file defining the ports shown above was named "zami",
you would issue LPINST:

  LPINST -# 2 zami

Notice that in the previous example, LPINST will perform two actions:
(1) it will create and/or enable 2 ports, (2) it will define the
characteristics for those ports.  You do *not* need to invoke LPINST
twice, once to create the ports and once to define them.

LPINST Return Codes
-------------------

Upon completion, the LPINST command returns a value specifying whether
the operation succeeded or failed.  A return code of zero indicates
that LPINST executed successfully.  A non-zero return code indicates
that LPINST ran with errors.  The return codes are:

   0         Success
  -1         Illegal arguments
  -2         Illegal number of ports specified
  -3         Can't find the TCP/IP product directory
  -4         Defining the number of ports failed
  -5         Defining LPRPDRVR.PDR failed
  -6         Unable to load LPRPDRVR.PDR
  -7         LPRPDRVR.PDR appears corrupted
  -8         Installation of a port failed
  -9         Can't open the plain-text definition file
  -10        An entry in the plain-text definition file is incorrect
  -11        An error occurred while defining a port
  -12        Out of memory
