| 1 | REXX OS/2 PRINTER UTILITIES
|
|---|
| 2 |
|
|---|
| 3 | ==============================================================================
|
|---|
| 4 | FUNCTION SUMMARY
|
|---|
| 5 |
|
|---|
| 6 | RPUDeviceDelete - Delete a local print device which lacks a printer queue.
|
|---|
| 7 | RPUDropFuncs - Deregister all RXPRTUTL functions.
|
|---|
| 8 | RPUEnumDrivers - List printerpak drivers which are currently installed.
|
|---|
| 9 | RPUEnumModels - List specific printers supported by a printerpak driver.
|
|---|
| 10 | RPUEnumPorts - List all printer ports currently defined on the system.
|
|---|
| 11 | RPUEnumPrinters - List all printers currently defined on the system.
|
|---|
| 12 | RPULoadFuncs - Register all other RXPRTUTL functions.
|
|---|
| 13 | RPUOpenView - Open the WPS object corresponding to a print queue.
|
|---|
| 14 | RPUPortDelete - Delete a printer port.
|
|---|
| 15 | RPUPortDialog - Open a printer port's configuration dialog.
|
|---|
| 16 | RPUPortInfo - Get basic information about a local printer port.
|
|---|
| 17 | RPUPortInstall - Create a new printer port.
|
|---|
| 18 | RPUPortQuery - Get the configuration settings of a printer port.
|
|---|
| 19 | RPUPortSet - Set the configuration settings of a printer port.
|
|---|
| 20 | RPUPrinterCreate - Create a new local printer.
|
|---|
| 21 | RPUPrinterDelete - Delete a local printer and its associated data.
|
|---|
| 22 | RPUPrinterQuery - Get information about a printer.
|
|---|
| 23 | RPUQueueDefault - Set the system default printer.
|
|---|
| 24 | RPUQueueHold - Hold or release a printer queue.
|
|---|
| 25 | RPUVersion - Return the current RXPRTUTL library version.
|
|---|
| 26 |
|
|---|
| 27 |
|
|---|
| 28 | ==============================================================================
|
|---|
| 29 | FUNCTION DETAILS
|
|---|
| 30 |
|
|---|
| 31 | ------------------------------------------------------------------------------
|
|---|
| 32 | RPUDeviceDelete
|
|---|
| 33 |
|
|---|
| 34 | Deletes a local print device which lacks a printer queue. Can be useful
|
|---|
| 35 | for cleaning up bad or corrupted printer definitions.
|
|---|
| 36 |
|
|---|
| 37 | REXX ARGUMENTS:
|
|---|
| 38 | 1. The name of the print device to be deleted. (REQUIRED)
|
|---|
| 39 |
|
|---|
| 40 | REXX RETURN VALUE:
|
|---|
| 41 | 1 on success, or 0 if an error occurred.
|
|---|
| 42 |
|
|---|
| 43 |
|
|---|
| 44 | ------------------------------------------------------------------------------
|
|---|
| 45 | RPUDropFuncs
|
|---|
| 46 |
|
|---|
| 47 | Deregister all RPU* REXX functions, including this one.
|
|---|
| 48 |
|
|---|
| 49 | REXX ARGUMENTS: None
|
|---|
| 50 | REXX RETURN VALUE: ""
|
|---|
| 51 |
|
|---|
| 52 |
|
|---|
| 53 | ------------------------------------------------------------------------------
|
|---|
| 54 | RPUEnumDrivers
|
|---|
| 55 |
|
|---|
| 56 | Gets a list of the printer drivers currently installed on the system.
|
|---|
| 57 | Returns a REXX array (stem) with each item being a driver name string.
|
|---|
| 58 |
|
|---|
| 59 | REXX ARGUMENTS:
|
|---|
| 60 | 1. The name of the stem in which to return the results. (REQUIRED)
|
|---|
| 61 |
|
|---|
| 62 | REXX RETURN VALUE:
|
|---|
| 63 | 1 on success, or 0 if an error occurred.
|
|---|
| 64 |
|
|---|
| 65 |
|
|---|
| 66 | ------------------------------------------------------------------------------
|
|---|
| 67 | RPUEnumModels
|
|---|
| 68 |
|
|---|
| 69 | Gets a list of the printer models supported by the specified print
|
|---|
| 70 | driver.
|
|---|
| 71 |
|
|---|
| 72 | REXX ARGUMENTS:
|
|---|
| 73 | 1. Filespec of the printer driver to query. (REQUIRED)
|
|---|
| 74 | 2. The name of the stem in which to return the results. (REQUIRED)
|
|---|
| 75 |
|
|---|
| 76 | REXX RETURN VALUE:
|
|---|
| 77 | 1 on success, or 0 if an error occurred.
|
|---|
| 78 |
|
|---|
| 79 |
|
|---|
| 80 | ------------------------------------------------------------------------------
|
|---|
| 81 | RPUEnumPorts
|
|---|
| 82 |
|
|---|
| 83 | Gets a list of the printer ports currently defined on the system. Returns
|
|---|
| 84 | a REXX array (stem) consisting of one string per port, of the form:
|
|---|
| 85 | <port> <driver> <driver path>
|
|---|
| 86 |
|
|---|
| 87 | REXX ARGUMENTS:
|
|---|
| 88 | 1. The name of the stem in which to return the results. (REQUIRED)
|
|---|
| 89 |
|
|---|
| 90 | REXX RETURN VALUE:
|
|---|
| 91 | 1 on success, or 0 if an error occurred.
|
|---|
| 92 |
|
|---|
| 93 |
|
|---|
| 94 | ------------------------------------------------------------------------------
|
|---|
| 95 | RPUEnumPrinters
|
|---|
| 96 |
|
|---|
| 97 | Gets a list of the printers currently defined on the system. Returns a
|
|---|
| 98 | compound (stem) variable with the following format:
|
|---|
| 99 |
|
|---|
| 100 | (stem).0 Number of printers
|
|---|
| 101 | (stem).i.!name Printer device (a.k.a. physical) name
|
|---|
| 102 | (stem).i.!queue Printer queue name ('' for direct printers)
|
|---|
| 103 | (stem).i.!host Name of LAN host where printer queue is located
|
|---|
| 104 | ('' for non-LAN printers)
|
|---|
| 105 | (stem).i.!description Printer description (name of WPS object)
|
|---|
| 106 | (stem).i.!handle Printer's object handle ('' for direct printers)
|
|---|
| 107 | (stem).i.!flags Zero or more of the following flags (any order):
|
|---|
| 108 | D This is the default printer queue
|
|---|
| 109 | P Printer queue is paused (held)
|
|---|
| 110 |
|
|---|
| 111 | This function does not indicate drivers or ports used by the printer; to
|
|---|
| 112 | obtain that information for a printer, call RPUPrinterQuery on the printer
|
|---|
| 113 | device name.
|
|---|
| 114 |
|
|---|
| 115 | REXX ARGUMENTS:
|
|---|
| 116 | 1. The name of the stem in which to return the results. (REQUIRED)
|
|---|
| 117 |
|
|---|
| 118 | REXX RETURN VALUE:
|
|---|
| 119 | 1 on success, or 0 if an error occurred.
|
|---|
| 120 |
|
|---|
| 121 |
|
|---|
| 122 | ------------------------------------------------------------------------------
|
|---|
| 123 | RPULoadFuncs
|
|---|
| 124 |
|
|---|
| 125 | Register all RPU* REXX functions except this one.
|
|---|
| 126 |
|
|---|
| 127 | REXX ARGUMENTS: None
|
|---|
| 128 | REXX RETURN VALUE: ""
|
|---|
| 129 |
|
|---|
| 130 |
|
|---|
| 131 | ------------------------------------------------------------------------------
|
|---|
| 132 | RPUOpenView
|
|---|
| 133 |
|
|---|
| 134 | Opens the requested view of the WPS object corresponding to the specified
|
|---|
| 135 | print queue. (Note that WPS printer objects are associated with a queue
|
|---|
| 136 | rather than a printer device, so it is the queue name that must be passed
|
|---|
| 137 | to this function.)
|
|---|
| 138 |
|
|---|
| 139 | REXX ARGUMENTS:
|
|---|
| 140 | 1. The name of the printer queue for the object to open. (REQUIRED)
|
|---|
| 141 | 2. Optional view flag, one of:
|
|---|
| 142 | O Object's default view (DEFAULT)
|
|---|
| 143 | D Details view
|
|---|
| 144 | I Icon view
|
|---|
| 145 | S Settings
|
|---|
| 146 |
|
|---|
| 147 | REXX RETURN VALUE:
|
|---|
| 148 | 1 on success, or 0 if an error occurred.
|
|---|
| 149 |
|
|---|
| 150 |
|
|---|
| 151 | ------------------------------------------------------------------------------
|
|---|
| 152 | RPUPortDelete
|
|---|
| 153 |
|
|---|
| 154 | Deletes a printer port.
|
|---|
| 155 |
|
|---|
| 156 | REXX ARGUMENTS:
|
|---|
| 157 | 1. The name of the port to be deleted. (REQUIRED)
|
|---|
| 158 |
|
|---|
| 159 | REXX RETURN VALUE:
|
|---|
| 160 | 1 on success, or 0 if an error occurred.
|
|---|
| 161 |
|
|---|
| 162 |
|
|---|
| 163 | ------------------------------------------------------------------------------
|
|---|
| 164 | RPUPortDialog
|
|---|
| 165 |
|
|---|
| 166 | Brings up the specified port's configuration dialog. This function can
|
|---|
| 167 | only be used from a PM process.
|
|---|
| 168 |
|
|---|
| 169 | REXX ARGUMENTS:
|
|---|
| 170 | 1. The name of the port driver without any extension. This must be
|
|---|
| 171 | installed and registered in OS2.INI already. (REQUIRED)
|
|---|
| 172 | 2. The name of the port to be configured. (REQUIRED)
|
|---|
| 173 |
|
|---|
| 174 | REXX RETURN VALUE:
|
|---|
| 175 | 1 if the user modified the port configuration.
|
|---|
| 176 | 0 if no changes were made, or if an error occurred.
|
|---|
| 177 |
|
|---|
| 178 |
|
|---|
| 179 | ------------------------------------------------------------------------------
|
|---|
| 180 | RPUPortInfo
|
|---|
| 181 |
|
|---|
| 182 | Queries basic information about a local port. This is different from
|
|---|
| 183 | RPUPortQuery() in that the latter returns port configuration information
|
|---|
| 184 | from the port driver itself, whereas this function only returns what the
|
|---|
| 185 | spooler itself knows about the port.
|
|---|
| 186 |
|
|---|
| 187 | REXX ARGUMENTS:
|
|---|
| 188 | 1. The name of the port. (REQUIRED)
|
|---|
| 189 | 2. The name of the stem in which to return the results: (REQUIRED)
|
|---|
| 190 | (stem).!name The name of the port
|
|---|
| 191 | (stem).!driver The name of the port driver
|
|---|
| 192 | (stem).!converter The name of the protocol converter used
|
|---|
| 193 |
|
|---|
| 194 | REXX RETURN VALUE:
|
|---|
| 195 | 1 on success, or 0 if an error occurred.
|
|---|
| 196 |
|
|---|
| 197 |
|
|---|
| 198 | ------------------------------------------------------------------------------
|
|---|
| 199 | RPUPortInstall
|
|---|
| 200 |
|
|---|
| 201 | Creates a new printer port.
|
|---|
| 202 |
|
|---|
| 203 | REXX ARGUMENTS:
|
|---|
| 204 | 1. The name of the port driver without any extension. This must be
|
|---|
| 205 | installed and registered in OS2.INI already. (REQUIRED)
|
|---|
| 206 | 2. The name of the new port to be created. If not specified, the port
|
|---|
| 207 | driver will be responsible for using a default name. This should
|
|---|
| 208 | generally be specified, as the driver is not guaranteed to support
|
|---|
| 209 | omitting it. (DEFAULT: none)
|
|---|
| 210 |
|
|---|
| 211 | REXX RETURN VALUE:
|
|---|
| 212 | 1 on success, or 0 if an error occurred.
|
|---|
| 213 |
|
|---|
| 214 |
|
|---|
| 215 | ------------------------------------------------------------------------------
|
|---|
| 216 | RPUPortQuery
|
|---|
| 217 |
|
|---|
| 218 | Queries the specified port's configuration settings. IMPORTANT: not all
|
|---|
| 219 | port drivers support this; the standard OS/2 serial and parallel port
|
|---|
| 220 | drivers do NOT. When this API is not supported, the return value should
|
|---|
| 221 | be ''. Otherwise, the format of the returned configuration data is a
|
|---|
| 222 | string of binary data in port driver-specific format (the caller assumes
|
|---|
| 223 | responsibility for knowing how to interpret it).
|
|---|
| 224 |
|
|---|
| 225 | See the file 'NOTES' for format information about some particular port
|
|---|
| 226 | drivers.
|
|---|
| 227 |
|
|---|
| 228 | REXX ARGUMENTS:
|
|---|
| 229 | 1. The name of the port driver without any extension. This must be
|
|---|
| 230 | installed and registered in OS2.INI already. (REQUIRED)
|
|---|
| 231 | 2. The name of the port to be queried. (REQUIRED)
|
|---|
| 232 |
|
|---|
| 233 | REXX RETURN VALUE:
|
|---|
| 234 | Binary data representing the port configuration, in whatever format is
|
|---|
| 235 | returned by the driver's SplPdQuery->BIDI_Q_PORTDRV routine. This
|
|---|
| 236 | depends on the particular port driver; consult its API documentation.
|
|---|
| 237 | '' will be returned if an error occurred.
|
|---|
| 238 |
|
|---|
| 239 |
|
|---|
| 240 | ------------------------------------------------------------------------------
|
|---|
| 241 | RPUPortSet
|
|---|
| 242 |
|
|---|
| 243 | Sets the specified port's configuration settings. IMPORTANT: not all
|
|---|
| 244 | port drivers support this; the standard OS/2 serial and parallel port
|
|---|
| 245 | drivers do NOT. Depending on the port driver, there are two possible
|
|---|
| 246 | outcomes when this API is not supported:
|
|---|
| 247 | A. Port driver does not have an entrypoint for SplPdSet. This is the
|
|---|
| 248 | case for any port driver using pre-Warp conventions. RPUPortSet will
|
|---|
| 249 | return 0 and RPUERROR will be "1: DosQueryProcAddr".
|
|---|
| 250 | B. Port driver supports SplPdSet but does not (correctly) implement the
|
|---|
| 251 | BIDI_SET_PORTDRV command. This is the case for some third-party port
|
|---|
| 252 | drivers. In this case, whether or not RPUPortSet returns a success
|
|---|
| 253 | code entirely depends on how conscientiously the port driver itself
|
|---|
| 254 | is written, but the "INITIALIZATION" key (and possibly others) in
|
|---|
| 255 | the port's entry in OS2SYS.INI will not be updated. The application
|
|---|
| 256 | should always check for this after calling RPUPortSet!
|
|---|
| 257 | If the application determines that either of these failure conditions has
|
|---|
| 258 | occurred, it is advisable to call RPUPortDialog as a fallback measure.
|
|---|
| 259 |
|
|---|
| 260 | Because of the above, use of this function is not generally encouraged
|
|---|
| 261 | except when absolutely necessary.
|
|---|
| 262 |
|
|---|
| 263 | See the file 'NOTES' for format information about some particular port
|
|---|
| 264 | drivers.
|
|---|
| 265 |
|
|---|
| 266 | REXX ARGUMENTS:
|
|---|
| 267 | 1. The name of the port driver without any extension. This must be
|
|---|
| 268 | installed and registered in OS2.INI already. (REQUIRED)
|
|---|
| 269 | 2. The name of the port to be configured. (REQUIRED)
|
|---|
| 270 | 3. Byte sequence representing the new port configuration. The format
|
|---|
| 271 | depends on the port driver (and it is up to the caller to know what
|
|---|
| 272 | it is). (REQUIRED)
|
|---|
| 273 |
|
|---|
| 274 | REXX RETURN VALUE:
|
|---|
| 275 | 1 on success, or 0 if an error occurred.
|
|---|
| 276 |
|
|---|
| 277 |
|
|---|
| 278 | ------------------------------------------------------------------------------
|
|---|
| 279 | RPUPrinterCreate
|
|---|
| 280 |
|
|---|
| 281 | Creates a new local printer object. The associated print queue and
|
|---|
| 282 | device are created automatically. However, the specified output port
|
|---|
| 283 | must exist, and the specified printer driver/model must have been
|
|---|
| 284 | installed already.
|
|---|
| 285 |
|
|---|
| 286 | The WPS object is created with default settings, and will be assigned an
|
|---|
| 287 | object-ID automatically by the WPS.
|
|---|
| 288 |
|
|---|
| 289 | NOTE: This function will NOT create a remote (LAN) printer object.
|
|---|
| 290 |
|
|---|
| 291 | REXX ARGUMENTS:
|
|---|
| 292 | 1. The printer description, used as the WPS object title. (REQUIRED)
|
|---|
| 293 | 2. The name of the underlying print queue. Must be a legal
|
|---|
| 294 | queue name according to OS/2 (but what is that...?) (REQUIRED)
|
|---|
| 295 | 3. The name of the printer port, which must exist already. (REQUIRED)
|
|---|
| 296 | 4. The default printer driver.model to be associated with
|
|---|
| 297 | the device. If specified, this must be installed in the
|
|---|
| 298 | system already. If not specified, IBMNULL is assumed. (OPTIONAL)
|
|---|
| 299 |
|
|---|
| 300 | REXX RETURN VALUE:
|
|---|
| 301 | 1 on success, or 0 if an error occurred.
|
|---|
| 302 |
|
|---|
| 303 |
|
|---|
| 304 | ------------------------------------------------------------------------------
|
|---|
| 305 | RPUPrinterDelete
|
|---|
| 306 |
|
|---|
| 307 | Deletes a local printer queue and its associated print device definition.
|
|---|
| 308 |
|
|---|
| 309 | REXX ARGUMENTS:
|
|---|
| 310 | 1. The name of the printer queue to be deleted. (REQUIRED)
|
|---|
| 311 |
|
|---|
| 312 | REXX RETURN VALUE:
|
|---|
| 313 | 1 on success, or 0 if an error occurred. (1 will be returned even if
|
|---|
| 314 | the WPS printer object could not be deleted, so long as the queue and
|
|---|
| 315 | device were destroyed successfully.)
|
|---|
| 316 |
|
|---|
| 317 |
|
|---|
| 318 | ------------------------------------------------------------------------------
|
|---|
| 319 | RPUPrinterQuery
|
|---|
| 320 |
|
|---|
| 321 | Gets information about the specified printer device.
|
|---|
| 322 |
|
|---|
| 323 | (stem).!description Printer description (name of WPS object)
|
|---|
| 324 | (stem).!port Name of the port the printer is using
|
|---|
| 325 | (stem).!drivers List of the drivers used by this printer
|
|---|
| 326 | (stem).!jobflags Zero or more of the following flags (any order):
|
|---|
| 327 | E A printer error has occurred
|
|---|
| 328 | H Printer destination is paused (held)
|
|---|
| 329 | I Intervention required
|
|---|
| 330 | N Printer has raised a notification alert
|
|---|
| 331 | O Printer is offline
|
|---|
| 332 | P Printer is out of paper
|
|---|
| 333 |
|
|---|
| 334 | REXX ARGUMENTS:
|
|---|
| 335 | 1. The name of the printer device being queried. (REQUIRED)
|
|---|
| 336 | 2. The name of the stem in which to return the results. (REQUIRED)
|
|---|
| 337 |
|
|---|
| 338 | REXX RETURN VALUE:
|
|---|
| 339 | 1 on success, or 0 if an error occurred.
|
|---|
| 340 |
|
|---|
| 341 |
|
|---|
| 342 | ------------------------------------------------------------------------------
|
|---|
| 343 | RPUQueueDefault
|
|---|
| 344 |
|
|---|
| 345 | Sets the requested printer queue as the system default printer.
|
|---|
| 346 |
|
|---|
| 347 | REXX ARGUMENTS:
|
|---|
| 348 | 1. The name of the printer queue to set as default. (REQUIRED)
|
|---|
| 349 |
|
|---|
| 350 | REXX RETURN VALUE:
|
|---|
| 351 | 1 on success, or 0 if an error occurred.
|
|---|
| 352 |
|
|---|
| 353 |
|
|---|
| 354 | ------------------------------------------------------------------------------
|
|---|
| 355 | RPUQueueHold
|
|---|
| 356 |
|
|---|
| 357 | Holds or releases the specified print queue.
|
|---|
| 358 |
|
|---|
| 359 | REXX ARGUMENTS:
|
|---|
| 360 | 1. The name of the printer queue to hold or release. (REQUIRED)
|
|---|
| 361 | 2. Action flag, one of:
|
|---|
| 362 | Y Hold printer (DEFAULT)
|
|---|
| 363 | N Release printer
|
|---|
| 364 |
|
|---|
| 365 | REXX RETURN VALUE:
|
|---|
| 366 | 1 on success, or 0 if an error occurred.
|
|---|
| 367 |
|
|---|
| 368 |
|
|---|
| 369 | ------------------------------------------------------------------------------
|
|---|
| 370 | RPUVersion
|
|---|
| 371 |
|
|---|
| 372 | Returns the current library version.
|
|---|
| 373 |
|
|---|
| 374 | REXX ARGUMENTS: None
|
|---|
| 375 | REXX RETURN VALUE: Current version in the form "major.minor.refresh"
|
|---|
| 376 |
|
|---|
| 377 |
|
|---|
| 378 | ==============================================================================
|
|---|
| 379 | NOTICES
|
|---|
| 380 |
|
|---|
| 381 | REXX OS/2 Printer Utility API (RXPRTUTL.DLL)
|
|---|
| 382 | (C) 2011,2016 Alex Taylor
|
|---|
| 383 |
|
|---|
| 384 | LICENSE:
|
|---|
| 385 |
|
|---|
| 386 | Redistribution and use in source and binary forms, with or without
|
|---|
| 387 | modification, are permitted provided that the following conditions are
|
|---|
| 388 | met:
|
|---|
| 389 |
|
|---|
| 390 | 1. Redistributions of source code must retain the above copyright
|
|---|
| 391 | notice, this list of conditions and the following disclaimer.
|
|---|
| 392 |
|
|---|
| 393 | 2. Redistributions in binary form must reproduce the above copyright
|
|---|
| 394 | notice, this list of conditions and the following disclaimer in the
|
|---|
| 395 | documentation and/or other materials provided with the distribution.
|
|---|
| 396 |
|
|---|
| 397 | 3. The name of the author may not be used to endorse or promote products
|
|---|
| 398 | derived from this software without specific prior written permission.
|
|---|
| 399 |
|
|---|
| 400 | THIS SOFTWARE IS PROVIDED BY THE AUTHOR ''AS IS'' AND ANY EXPRESS OR
|
|---|
| 401 | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|---|
| 402 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|---|
| 403 | DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
|
|---|
| 404 | INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|---|
| 405 | (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|---|
| 406 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|---|
| 407 | HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|---|
| 408 | STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
|---|
| 409 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|---|
| 410 | POSSIBILITY OF SUCH DAMAGE.
|
|---|
| 411 |
|
|---|
