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: 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) This function does not indicate drivers or ports used by the printer; to obtain that information for a printer, call RPUPrinterQuery on the printer device name. 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 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).!drivers 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.