Remote Print Installation Command-Line Interface Document Version 1.02 Document formatted: 8/22/97 for print or view 2.5 Related Documentation Terms: RMPI - Remote Multiple Printer Installation; ITSC - International Technical Support Center ITSO - International Technical Support Organization ITSO Redbook SG24-4295-01, OS/2 Installation Techniques: Chapter 7 discusses Remote Printer Install Redbooks Home Page on the World Wide Web http://www.redbooks.ibm.com/redbooks (use Search Redbooks button [SG24-4295-01]) 3. Introduction Administrators want to remotely install and configure print objects on clients and servers. Administrators do not want their users involved in this process. The Remote Multiple Printer Installation (RMPI) program shipped by the IBM International Technical Support Centre(ITSC) provides this function and is used by many customers today. The following customer requirements were taken into consideration when generating this feature: 1. Remotely install and configure local and network printer objects on OS/2 clients. 2. Remotely install and configure printer objects on OS/2 servers. 3. Provide a simple association of a printer object with a printer driver and properties (e.g. do not require the administrator to associate hard-to-remember printer driver numbers with printer objects as is currently the case in RMPI). 4. Define job and printer properties using standard keyword-value pairs. i.e. do not require the administrator to create printer objects for combinations of job and printer properties as is the case currently with RMPI. 5. Remotely install, modify and delete all types of ports supported by OS/2. 6. Allow a printer object, printer and/or port to be defined once and then reference this definition in the response file (i.e. avoid duplicate definitions) and/or reference this definition with specific exceptions for a given object. 7. Configure a printer and its properties. 8. Allow groups of clients and/or servers to use the same configuration (i.e. response file). 9. Update configured systems (i.e. add, modify or delete objects). For example, reassign an existing printer object to another port, update a printer configuration and properties on a configured system, or update a port definition on a configured system. 10. Uninstall configured systems. 11. Specify automatic synchronization of printer drivers, port drivers and protocol converters in the response file. This should be under administrator control and will most likely be used to maintain servers. 4. Design Overview This feature is built on the existing program Remote Multiple Printer Installation (RMPI) provided by the International Technical Support Center (ITSC). The current operation of this program is described in ITSO Redbook SG24-4295-01, OS/2 Installation Techniques: Chapter 7 and will not be described in this section. This section focuses on the changes to this program that deliver a viable product for our customer. The summary of changes to RMPI are as follows: * There are no limits on the number of local Printer Objects, Network Printer Objects, ports and printers that can be defined on a system. * Additional types of ports can now be defined and associated with printer objects: - Infrared - Network (802.2 and TCP/IP transports plus token ring and ethernet networks) * Download a port driver. * All properties for a local Printer Object and a Network Printer Object can be configured such as setting the default view. * Define the configuration and properties of intelligent (i.e. bidi) printers. * Legacy printer driver compression utilities are removed from the product. The subcomponents of RMPI are as follows: * RMPI Configuration Program (RINSTPRN.EXE) * RMPI Save Printer and Job Properties Program (BACKPRN.EXE) * RMPI Restore Printer and Job Properties Program (RESTPRN.EXE) * RMPI Change Queue Status Program (CHGQUE.EXE) Please note that these program will only update printer related items and will not update CONFIG.SYS, PROTOCOL.INI, or other system files. RMPI Response File Keywords: the new keywords supported by the updated remote multiple printer installation program are described below: ADDPORT Keyword: The RMPI Configuration Program allows the ADDPORT keyword to define the port configuration on the configured system. After a system is configured, the new port appears in the list of available ports on the configured system. ex: ADDPORT NAME=NETPORT1 PORTDRIVER=NETDRV DESCRIPTION=This is a test port NETADDR=123.123.123.123 CFGFILE=C:\os2\install\test.cfg CFGNAME=NetPortX ENDPORT Configuration files(CFGFILE) are system INI files that contain the configuration of an already installed port and can be used to duplicate a port configuration. The files do not need to have a file exentsion of .INI because the PrfQueryProfileData APIs can handle INI files that have extensions othere than .INI. You can have a print server already connected to a network-attached printer and use this print server's OS2SYS.INI file as the CFGFILE to create a printer port on another server that prints to the same network-attached printer. These config files will be processed first so any information retrieved from them can be overwritten by the keywords in the ADDPORT section of the response file. If the configuration name is specified( CFGNAME=PortName), then RINSTPRN will look in the configuation file for the settings for the given portname( in this example NetPortX ). If a configuration file is given but no CFGNAME is given, then RINSTPRN will look in the configuration file for the settings for the new portname( in this example NETPORT1 ), and if not found, it will use the first application name in the configuration file. ADDPORT keywords: NAME, DESCRIPTION, PORTDRIVER, NETADDR, NETADAPTER, HOSTNAME, ATTACHINTERFACE, CFGFILE, CFGNAME, PNLFILE, and REFERENCE. ADDPORT NAME= (Name of port to install...FILE is reserved and cannot be used) DESCRIPTION= (Any text to use as a port description) PORTDRIVER= (Name of port driver to use with the port) NETADDR= (String containing network address of the printer to attach to the port) (Could be DLC or TCP/IP) NETADAPTER= (Network adapter to use for the port i.e. LAN0, etc) HOSTNAME= (Name of the printer on the network) ATTACHINTERFACE= (Interface on remote adapter to which the printer is connected) CFGFILE= (Full path to file on client where configuration file is located) CFGNAME= (Port name in CFGFILE which contains values for port) PNLFILE= (Full path to file on client containing default information for printer) (Control panel for printer must support this file) REFERENCE= (Must be a previously defined port) ENDPORT ADDPORTDRIVER Keyword: Installs/updates a port driver on the system Keyword ADDPORTDRIVER gives the name of the port driver and the path to the port driver. ex: ADDPORTDRIVER NAME=PARALLEL ( Name of port driver to install...will find driver PARALLEL.PDR or .PD_) SRCPATH=X:\DRIVERS ( Path to the .PDR or .PD_ file with X: being any accessible drive) ( will try to find the driver in .\ or .\OS2DRV ) ENDPORTDRIVER Some port drivers may have ini keys to enable features. This program will not update/set any of those ini keys. ADDPORTDRIVER keywords: NAME and SRCPATH ADDPRINTDRIVER keyword: Installs /updates a printdriver on the system i.e. PSCRIPT valid keywords: NAME, SRCPATH,ENDPRINTDRIVER ADDPRINTDRIVER NAME= ( will be truncated to 8 chars if longer ) [REQUIRED] ( Name of print driver to install...will find driver *.DRV or DR_) SRCPATH= ( must be a valid path on the client system ) ( will try to find the driver in .\, .\OS2DRV, or .\PMDD_x ) ( if not defined, will use the cmd line argument - default A: ) ENDPRINTDRIVER ADDPRINTDEVICE keyword: Installs a new print device on the system i.e. PSCRIPT.Generic PostScript Printer valid keywords: NAME, DRIVER, ENDPRINTDEVICE ADDPRINTDEVICE NAME= ( can contain blanks ) [not required in drivers like IBMNULL] ( Name of the print device...must be same case as defined by the driver ) ( i.e. "NAME=Generic PostScript Printer" ) DRIVER= ( must be the same as NAME in ADDPRINTDRIVER ) [REQUIRED] ( i.e. PSCRIPT, IBMNULL, etc ) ENDPRINTDEVICE ADDDEVICE keyword: Installs/updates a device(printer) on the system valid keywords: NAME, LOGADDRESS, DRIVERS, COMMENT, DESCRIPTION, REFERENCE, ENDDEVICE ADDDEVICE NAME= ( can contain blanks ) [REQUIRED] ( Name of the device[printer] ) LOGADDRESS= ( can be LPT1-32, COM1-4, FILE, a port defined by ADDPORT, or not defined ) DRIVERS= ( DRIVER.device If not installed, a new driver[ADDPRINTDRIVER] and device[ADDPRINTDEVICE] will be created ) [REQUIRED] ( i.e. PSCRIPT.Generic PostScript Printer ) COMMENT= ( any text to use as comment ) DESCRIPTION= ( another way to specify COMMENT ) REFERENCE= ( must be a previously defined device ) ENDDEVICE ADDQUEUE keyword: Installs/updates a local queue on the system valid keywords: NAME, DESCRIPTION, COMMENT, SEPFILE, PRIORITY, STARTTIME, STOPTIME, HOLD, APPDEFAULT, PRINTERSPECIFIC, PRINTWHILESPOOL, PRINTPROCESSOR, PARAMETERS, DRIVERNAME, PRINTERS, PORT, REFERENCE, DEFINEQUEUEPROPS, ADDQUEUE, SETUP, ENDQUEUE ADDQUEUE NAME= ( will be truncated to 8 chars if longer ) [REQUIRED] ( Name of the queue) COMMENT= ( any text to use as comment - will be title of the print object ) DESCRIPTION= ( another way to specify COMMENT ) SEPFILE= ( Must exist on client ) ( specifies the separator file to place between print jobs ) PRIORITY= ( must be between 1 and 9 inclusive ) ( changes the queue's priority and the default print job priority ) STARTTIME= ( minutes after midnight ) ( time when queue begins to process print jobs ) STOPTIME= ( minutes after midnight ) ( time when queue stops processing print jobs ) HOLD=Y/N ( default = N , will only check first char of word ) ( Hold the queue, yes or no ) APPDEFAULT=Y/N ( default = N, will only check first char of word ) ( Use the queue as default for applications, yes or no ) ( Last one specified will be the default ) PRINTERSPECIFIC=Y/N ( default = N, will only check first char of word ) ( format print job for printer when spooled, yes or no ) PRINTWHILESPOOL=Y/N ( default = Y, will only check first char of word ) ( print printer-specific jobs before entire job is spooled, yes or no ) PRINTPROCESSOR= ( default=PMPRINT ) ( processor to use when printing a spooled print job ) DRIVERNAME= ( driver.device: If not installed, a new driver[ADDPRINTDRIVER] and device[ADDPRINTDEVICE] will be created ) [REQUIRED] ( i.e. PSCRIPT.Generic PostScript Printer) PRINTERS= ( must be an installed device ) PORT= ( can be LPT1-32, COM1-4, a port defined by ADDPORT, or not defined ) ( if the PORT is FILE, it will be output to file ) REFERENCE= ( must be a previously defined queue ) DEFINEQUEUEPROPS ( start of queue properties definition .. see below) ... ENDQUEUEPROPS ( end of queue properties definition ) OUTPUTTOFILE=Y/N ( default = N, will only check first char of word ) ( send the print output to a file not a printer, yes or no ) ADDWINOS2=Y/N ( default = N, will try to install WinOS2 printer configuration ) SETUP= ( The workplace shell setup string for the print object. ) ( This will allow overriding the default settings ) ( applied to a print object. ) ( The format is "KEYNAME1=Key Value1;KEYNAME2=Key Value2;" ) :SETUP is only supported on Warp 3-Fixpack 33 and above & Warp 4-Fixpack 5 and above ENDQUEUE DEFINEQUEUEPROPS keyword: Defines the default job properties for a queue only valid in ADDQUEUE ADDNETQUEUE defines. valid keywords: ORIENTATION, COLOR, PRINTQUALITY, DUPLEX, COLLATE, FEED, COPIES, SCALING, FORMFEEDCONTROL, NUP, RESOLUTION, FORMNAME, TRAYNAME, MEDIANAME, ENDQUEUEPROPS DEFINEQUEUEPROPS ORIENTATION=Portrait, Landscape, Rev_Portrait, Rev_Landscape COLOR=Monochrome, Color PRINTQUALITY=Draft, Low, Medium, High DUPLEX=Off, Book, Flip COLLATE=Off, On FEED=Manual, Automatic FORMFEEDCONTROL=None, Conditional, Compulsory COPIES= SCALING= NUP= RESOLUTION=[,] ( if only one value is specified, both x and y resolution will be the same ) ( X-Res Y-Res ) FORMNAME=None, Letter, Legal, Wide, Csheet, Dsheet, Esheet, LetterSmall, Tabloid, Ledger, Statement, Executive, A0, A1, A2, A3, A4, A4_Small, A5, B4, B5, Folio, Quatro, 10x14, 11x17, Note, Env_9, Env_10, Env_11, Env_12, Env_14, Env_dl, Env_a2, Env_c3, Env_c4, Env_c5, Env_c6, Env_c65, Env_c9, Env_c10, Env_b4, Env_b5, Env_b6, Env_Italy, Env_Monarch, Env_Personal, Fanfold_us, Fanfold_Std_German, Fanfold_Lgl_German, Architect_Bsheet, Architect_Csheet, Architect_Dsheet, Architect_Esheet, Card_A6, Card_4x6, Card_5x8, Card_Hagaki, Label_Standard, Label_Shipping, Label_Disk, Label_Euro TRAYNAME=None, Upper, Lower, Middle, Manual, Envmanual, Auto, Tractor, Smallfmt, Largefmt, LargeCapacity, Cassette MEDIANAME=None, Plain, Transparency, Glossy, Special, Coated, Backprint, Cloth, Thick, Stationary, Envelope, Continuous_Long, Continuous_Short, Tab_Stock, Multi_Part_Form, Labels ENDQUEUEPROPS Note: Print Driver has to support DJP's(Dynamic Job Properties) and may not support all options. Individual devices in each driver may support different options. DJP's are supported on Warp 4.0 and Warp 3.0 (fixpak 16 and greater). Only Job Properties can be changed, Printer Properties can not. ADDNETQUEUE keyword: Installs/updates a network queue on the system valid keywords: [all of ADDQUEUE] + REMOTECOMPUTER, REMOTEQUEUE, SYNCPRINTERPROPS, SYNCJOBPROPS, ENDNETQUEUE the following are accepted as valid but have no effect on Network Queues: SEPFILE,PRIORITY,STARTTIME,STOPTIME,HOLD,PRINTWHILESPOOL,PRINTPROCESSOR,PORT,OUTPUTTOFILE,ADDWINOS2 ADDNETQUEUE REMOTECOMPUTER= (must be of the form LS:\\computer ) [REQUIRED] REMOTEQUEUE= [REQUIRED] (print resource name on remote computer) SYNCPRINTERPROPS=Y/N ( default = Y, will only check first char of word ) ( synchronize printer properties from the server, yes or no ) SYNCJOBPROPS=Y/N ( default = N, will only check first char of word ) ( synchronize job properties from the server, yes or no ) ENDNETQUEUE DELETEPORT keyword: Deletes a port from the system valid keywords: NAME, ENDPORT DELETEPORT NAME= ( must be defined on the system ) [REQUIRED] ( FILE is reserved and will not be deleted ) ENDPORT DELETEDEVICE keyword: Deletes a device(printer) from the system valid keywords: NAME, ENDDEVICE DELETEDEVICE NAME= ( must be defined on the system ) [REQUIRED] ENDDEVICE DELETEQUEUE keyword: Deletes a queue (local or network) from the system valid keywords: NAME, ENDQUEUE DELETEQUEUE NAME= ( must be defined on the system ) [REQUIRED] ENDQUEUE 4.1 Concepts We have updated the existing RMPI Configuration Program to handle new response file keywords and to still support response files written for the original RMPI program. The print object(WPPRINT.DLL) and spooler(PMSPL.DLL) also changed to allow passing print object(local or remote) setup strings through the response file. The RMPI Configuration program uses existing 32-bit spooler APIs to modify the print system setup along with PrfWriteProfile calls to update those parts of the system INI file that cannot be updated with spooler APIs. 4.4 Flows The RMPI Configuration Program is an executable that can be run from a .cmd file, from the command line or from a user exit in a system response file. It will alter the print subsystem according to the response file information given to it 5.4 Command Support New Command Line Switches for RINSTPRN: The WinOS2 print driver diskette names changed between OS/2 Warp 3 and Warp 4. In order to allow a Warp 3 system to install using the shared directory structure for WinOS2 print drivers from Warp 4 (and Warp 4 systems to use Warp 3 directory structure), we are supplying the following command line switch for the RMPI Configuration Program: /VER:version version = 3 or 4 ( 3 is for Warp 3.0 fullpack and 4 is for Warp 4.0 ) default is the current version of the operating system ex: RINSTPRN /VER:3 - specifies Warp 3.0 fullpack configuration files are used. (control.inf, drvmap.lst, prdesc.lst, etc ) Note: Previous command line switches are in the reference section at the end of the document. 5.7 Dependencies In order to make use of the new port settings keywords, the customer has to install the latest network port drivers for OS/2. These port drivers will be available from the print manufacturer websites and are needed to make use of setting the network address for the network-attached printers being configured. See the readme file that comes with the network port driver to determine if any additional port configuration keynames are required. The Warp 4 level print drivers are also required in order to allow setting the DJP(Dynamic Job Properties) for print queues using the DEFINEQUEUEPROPS keyword. Operating System Support: * OS/2 Warp Version 3.0 * OS/2 Warp Version 4.0 * OS/2 Warp Server Version 4 (Entry or Advanced) REFERENCES Remote Printer Installation Program original command line switches. The program to be called has the name RINSTPRN. The following keywords can be used on the command line: /DSC /DRV /L1 /R /S /T /WPR /WDR /WT Each keyword is optional. Keywords can be used in any order. If the same keyword appears twice on the command line, the value of the last occurrence is used. The keywords are followed immediately by a ":" and a value. Blanks are not allowed between keyword, colon and value. Keywords are separated by one or more blanks. Misspelled keywords are logged into the log file and simply ignored (the processing will continue). If one of the keywords is not defined in the command line, a default value will be used. ° /DSC: This keyword defines the name of the printer description list. A partially or fully qualified OS/2 path name including a drive letter can be used. Note: If the drive letters "A:" or "B:" are used, make sure the driver diskette # 1 is in the specified drive before starting the program. The PRDESC.LST file changes with every release. A proper printer install can only take place if the PRDESC.LST matches the driver install diskettes. The current version of PRDESC.LST resides on diskette # 1 of the driver diskettes. Default: PRDESC.LST in the working directory. For example: RINSTPRN /DSC:X:\IMG\OS2V21\PMDD_1\PRDESC.LST Note: A PRDESC.LST file must be found or program will terminate. ° /DRV: This keyword defines the name of the printer driver list. A partially or fully qualified OS/2 path name, including a drive letter, can be used. Note: If the drive letters "A:" or "B:" are used, make sure the driver diskette # 1 is in the specified drive before starting the program. The PRDRV.LST changes with every release. A proper printer install can only take place if the PRDRV.LST matches the driver install diskettes. The current version of PRDRV.LST resides on diskette # 1 of the driver diskettes. Default: PRDRV.LST in the working directory. For example: RINSTPRN /DRV:X:\IMG\OS2V21\PMDD_1\PRDRV.LST Note: A PRDRV.LST file must be found or program will terminate. ° /L1: This keyword defines the location of the log file into which the RINSTPRN program logs its response file analysis, activities and execution results. A partially or fully qualified OS/2 path name, including a drive letter can be used. Default: RINSTPRN.LOG in the working directory. For example: RINSTPRN /L1:C:\RINSTPRN.LOG ° /R: This keyword defines the location of the printer install response file. A partially or fully qualified valid OS/2 path name, including a drive letter, can be used. Note: If the drive letters "A:" or "B:" are used, make sure the proper diskette is in the specified drive before starting the program. Please be aware of the fact, that when the keywords /DSC and /DRV point to the same drive, all three files have to be on this same diskette. Default: PRINTER.RSP in the working directory. For example: RINSTPRN /R:X:\RSP\OS2V21\PRINTER.RSP ° /S: This keyword defines the source drive and directory where the drivers and fonts to be installed are located. A fully qualified path name with a drive letter can be used. If the drive is A or B, the program asks for the printer driver diskettes on A: or B:. On any other drive (C to Z) the program looks for subdirectories called PMDD_1 to PMDD_n (depending on how many disks are mentioned in column two of the PRDRV.LST) in the specified directory. This drive can also be a redirected drive. Default: A:. For example: RINSTPRN /S:A: ° /T: This keyword defines the target drive where the OS/2 system is installed. Either just the drive letter or the drive letter with a colon can be specified. Use this keyword if OS/2 has been installed to a logical partition, rather than a primary partition. Default: C. For example: RINSTPRN /T:D ° /WPR: This keyword defines the name of the WIN-OS/2 printer setup file. A partially or fully qualified OS/2 path name, including a drive letter, can be used. Note: If the drive letters "A:" or "B:" are used, make sure a diskette, containing the specified file, is inserted in the drive before starting the program. ___ Important ______________________________________________________ | | | This keyword is OS/2 version dependent. | | Specify CONTROL.INF for installation on OS/2 V2.1 and OS/2 Warp | V3 and V4 | | | |__________________________________________________________________| The default value for this parameter is CONTROL.INF. This file resides in the \OS2\MDOS\WINOS2\SYSTEM subdirectory, after an installation of OS/2 and may change with every release. This parameter is only used if an installation of WIN-OS/2 printers is requested in the response file. Default: CONTROL.INF in the working directory. For example: RINSTPRN /WPR:X:\EXE\CONTROL.INF ° /WDR: This keyword defines the name of the map file between OS/2 and WIN-OS/2 device drivers. A partially or fully qualified OS/2 path name, including a drive letter, can be used. Note: If the drive letters "A:" or "B:" are used, make sure a diskette, containing the specified file, is inserted in the drive before starting the program. The default value for this parameter is DRVMAP.INF. This file resides in the \OS2\MDOS\WINOS2\SYSTEM subdirectory, after an installation of OS/2 and may change with every release. This parameter is only used if the WIN-OS/2 printer installation to an OS/2 printer is requested in the response file. Default: DRVMAP.INF in the working directory. For example: RINSTPRN /WDR:X:\EXE\DRVMAP.INF ° /WT: This keyword defines the target drive where WIN-OS/2 is installed. Either just the drive letter or the drive letter with a colon can be specified. Use this keyword if WIN-OS/2 has been installed to a logical partition, rather than a primary partition. Default: C. For example: RINSTPRN /WT:D The following complete example looks for a printer response file on redirected drive "Z:" with the name PRINTER.RSP. The PRDRV.LST is located on redirected drive "Z:" in the root subdirectory \PMDD_1. The PRDESC.LST is located on redirected drive "Z:" in the root subdirectory \PMDD_1. The WIN-OS/2 printer setup file is located in the "Z:" directory and has the name CONTROL.INF". The WIN-OS/2 driver map file is located in the "Z:" directory and has the name DRVMAP.INF. The USERnnnn.LOG file will be written to the redirected drive "Z:" thereby gathering the install information on the server. OS/2 and WIN-OS/2 are installed on drive D. The following example is valid for installation on OS/2 V2.1 and OS/2 Warp V3 and V4 since we specify the CONTROL.INF file for /WPR keyword. RINSTPRN /R:Z:\PRINTER.RSP /DRV:Z:\PMDD_1\PRDRV.LST /DSC:Z:\PMDD_1\PRDESC.LST /L1:Z:\USERnnnn.LOG /S:Z: /T:D /WPR:Z:\CONTROL.INF /WDR:Z:\DRVMAP.INF /WT:D