REXX OS/2 PRINTER UTILITIES

==============================================================================
FUNCTION SUMMARY

RPUDeviceDelete  - Delete a local print device which lacks a printer queue.
RPUDropFuncs     - Deregister all RXPRTUTL functions.
RPUEnumDrivers   - List printerpak drivers which are currently installed.
RPUEnumModels    - List specific printers supported by a printerpak driver.
RPUEnumPorts     - List all printer ports currently defined on the system.
RPUEnumPrinters  - List all printers currently defined on the system.
RPULoadFuncs     - Register all other RXPRTUTL functions.
RPUOpenView      - Open the WPS object corresponding to a print queue.
RPUPortDelete    - Delete a printer port.
RPUPortDialog    - Open a printer port's configuration dialog.
RPUPortInfo      - Get basic information about a local printer port.
RPUPortInstall   - Create a new printer port.
RPUPortQuery     - Get the configuration settings of a printer port.
RPUPortSet       - Set the configuration settings of a printer port.
RPUPrinterCreate - Create a new local printer.
RPUPrinterDelete - Delete a local printer and its associated data.
RPUPrinterQuery  - Get information about a printer.
RPUQueueDefault  - Set the system default printer.
RPUQueueHold     - Hold or release a printer queue.
RPUVersion       - Return the current RXPRTUTL library version.


==============================================================================
FUNCTION DETAILS

------------------------------------------------------------------------------
RPUDeviceDelete

Deletes a local print device which lacks a printer queue.  Can be useful
for cleaning up bad or corrupted printer definitions.

REXX ARGUMENTS:
  1. The name of the print device to be deleted.               (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUDropFuncs

Deregister all RPU* REXX functions, including this one.

REXX ARGUMENTS:    None
REXX RETURN VALUE: ""


------------------------------------------------------------------------------
RPUEnumDrivers

Gets a list of the printer drivers currently installed on the system.
Returns a REXX array (stem) with each item being a driver name string.

REXX ARGUMENTS:
  1. The name of the stem in which to return the results.      (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUEnumModels

Gets a list of the printer models supported by the specified print
driver.

REXX ARGUMENTS:
  1. Filespec of the printer driver to query.                  (REQUIRED)
  2. The name of the stem in which to return the results.      (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUEnumPorts

Gets a list of the printer ports currently defined on the system. Returns
a REXX array (stem) consisting of one string per port, of the form:
  <port> <driver> <driver path>

REXX ARGUMENTS:
  1. The name of the stem in which to return the results.      (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUEnumPrinters

Gets a list of the printers currently defined on the system.  Returns a
compound (stem) variable with the following format:

  (stem).0               Number of printers
  (stem).i.!name         Printer device (a.k.a. physical) name
  (stem).i.!queue        Printer queue name ('' for direct printers)
  (stem).i.!host         Name of LAN host where printer queue is located
                         ('' for non-LAN printers)
  (stem).i.!description  Printer description (name of WPS object)
  (stem).i.!handle       Printer's object handle ('' for direct printers)
  (stem).i.!flags        Zero or more of the following flags (any order):
                           D  This is the default printer queue
                           P  Printer queue is paused (held)

REXX ARGUMENTS:
  1. The name of the stem in which to return the results.      (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPULoadFuncs

Register all RPU* REXX functions except this one.

REXX ARGUMENTS:    None
REXX RETURN VALUE: ""


------------------------------------------------------------------------------
RPUOpenView

Opens the requested view of the WPS object corresponding to the specified
print queue.  (Note that WPS printer objects are associated with a queue
rather than a printer device, so it is the queue name that must be passed
to this function.)

REXX ARGUMENTS:
  1. The name of the printer queue for the object to open.  (REQUIRED)
  2. Optional view flag, one of:
       O  Object's default view  (DEFAULT)
       D  Details view
       I  Icon view
       S  Settings

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUPortDelete

Deletes a printer port.

REXX ARGUMENTS:
  1. The name of the port to be deleted.                       (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUPortDialog

Brings up the specified port's configuration dialog.  This function can
only be used from a PM process.

REXX ARGUMENTS:
  1. The name of the port driver without any extension.  This must be
     installed and registered in OS2.INI already.              (REQUIRED)
  2. The name of the port to be configured.                    (REQUIRED)

REXX RETURN VALUE:
  1 if the user modified the port configuration.
  0 if no changes were made, or if an error occurred.


------------------------------------------------------------------------------
RPUPortInfo

Queries basic information about a local port.  This is different from
RPUPortQuery() in that the latter returns port configuration information
from the port driver itself, whereas this function only returns what the
spooler itself knows about the port.

REXX ARGUMENTS:
  1. The name of the port.                                     (REQUIRED)
  2. The name of the stem in which to return the results:      (REQUIRED)
     (stem).!name       The name of the port
     (stem).!driver     The name of the port driver
     (stem).!converter  The name of the protocol converter used
  TODO
     (stem).!printer    The device name of the printer(s) using this
                        port, if any ('' if not in use)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUPortInstall

Creates a new printer port.

REXX ARGUMENTS:
  1. The name of the port driver without any extension.  This must be
     installed and registered in OS2.INI already.         (REQUIRED)
  2. The name of the new port to be created.  If not specified, the port
     driver will be responsible for using a default name.  This should
     generally be specified, as the driver is not guaranteed to support
     omitting it.                                         (DEFAULT: none)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUPortQuery

Queries the specified port's configuration settings.  IMPORTANT: not all
port drivers support this; the standard OS/2 serial and parallel port
drivers do NOT.  When this API is not supported, the return value should
be ''.  Otherwise, the format of the returned configuration data is a
string of binary data in port driver-specific format (the caller assumes
responsibility for knowing how to interpret it).

See the file 'NOTES' for format information about some particular port
drivers.

REXX ARGUMENTS:
  1. The name of the port driver without any extension.  This must be
     installed and registered in OS2.INI already.              (REQUIRED)
  2. The name of the port to be queried.                       (REQUIRED)

REXX RETURN VALUE:
  Binary data representing the port configuration, in whatever format is
  returned by the driver's SplPdQuery->BIDI_Q_PORTDRV routine.  This
  depends on the particular port driver; consult its API documentation.
  '' will be returned if an error occurred.


------------------------------------------------------------------------------
RPUPortSet

Sets the specified port's configuration settings.  IMPORTANT: not all
port drivers support this; the standard OS/2 serial and parallel port
drivers do NOT.  Depending on the port driver, there are two possible
outcomes when this API is not supported:
  A. Port driver does not have an entrypoint for SplPdSet. This is the
     case for any port driver using pre-Warp conventions. RPUPortSet will
     return 0 and RPUERROR will be "1: DosQueryProcAddr".
  B. Port driver supports SplPdSet but does not (correctly) implement the
     BIDI_SET_PORTDRV command. This is the case for some third-party port
     drivers. In this case, whether or not RPUPortSet returns a success
     code entirely depends on how conscientiously the port driver itself
     is written, but the "INITIALIZATION" key (and possibly others) in
     the port's entry in OS2SYS.INI will not be updated. The application
     should always check for this after calling RPUPortSet!
If the application determines that either of these failure conditions has
occurred, it is advisable to call RPUPortDialog as a fallback measure.

Because of the above, use of this function is not generally encouraged
except when absolutely necessary.

See the file 'NOTES' for format information about some particular port
drivers.

REXX ARGUMENTS:
  1. The name of the port driver without any extension.  This must be
     installed and registered in OS2.INI already.              (REQUIRED)
  2. The name of the port to be configured.                    (REQUIRED)
  3. Byte sequence representing the new port configuration.  The format
     depends on the port driver (and it is up to the caller to know what
     it is).                                                   (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUPrinterCreate

Creates a new local printer object.  The associated print queue and
device are created automatically.  However, the specified output port
must exist, and the specified printer driver/model must have been
installed already.

The WPS object is created with default settings, and will be assigned an
object-ID automatically by the WPS.

NOTE: This function will NOT create a remote (LAN) printer object.

REXX ARGUMENTS:
  1. The printer description, used as the WPS object title.    (REQUIRED)
  2. The name of the underlying print queue. Must be a legal
     queue name according to OS/2 (but what is that...?)       (REQUIRED)
  3. The name of the printer port, which must exist already.   (REQUIRED)
  4. The default printer driver.model to be associated with
     the device. If specified, this must be installed in the
     system already. If not specified, IBMNULL is assumed.    (OPTIONAL)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUPrinterDelete

Deletes a local printer queue and its associated print device definition.

REXX ARGUMENTS:
  1. The name of the printer queue to be deleted.              (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.  (1 will be returned even if
  the WPS printer object could not be deleted, so long as the queue and
  device were destroyed successfully.)


------------------------------------------------------------------------------
RPUPrinterQuery

Gets information about the specified printer device.

  (stem).!description  Printer description (name of WPS object)
  (stem).!port         Name of the port the printer is using
  (stem).!driver2      List of the drivers used by this printer
  (stem).!jobflags     Zero or more of the following flags (any order):
                           E  A printer error has occurred
                           H  Printer destination is paused (held)
                           I  Intervention required
                           N  Printer has raised a notification alert
                           O  Printer is offline
                           P  Printer is out of paper

REXX ARGUMENTS:
  1. The name of the printer device being queried.             (REQUIRED)
  2. The name of the stem in which to return the results.      (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUQueueDefault

Sets the requested printer queue as the system default printer.

REXX ARGUMENTS:
  1. The name of the printer queue to set as default. (REQUIRED)

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUQueueHold

Holds or releases the specified print queue.

REXX ARGUMENTS:
  1. The name of the printer queue to hold or release. (REQUIRED)
  2. Action flag, one of:
       Y  Hold printer (DEFAULT)
       N  Release printer

REXX RETURN VALUE:
  1 on success, or 0 if an error occurred.


------------------------------------------------------------------------------
RPUVersion

Returns the current library version.

REXX ARGUMENTS:    None
REXX RETURN VALUE: Current version in the form "major.minor.refresh"


==============================================================================
NOTICES

REXX OS/2 Printer Utility API (RXPRTUTL.DLL)
(C) 2011,2016 Alex Taylor

LICENSE:

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:

  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.

  3. The name of the author may not be used to endorse or promote products
     derived from this software without specific prior written permission.

  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ''AS IS'' AND ANY EXPRESS OR
  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  POSSIBILITY OF SUCH DAMAGE.

