Admin Alert: Avoiding Restoration Problems with Remote Output Queues
November 5, 2008 Joe Hertvik
i5/OS remote output queues are used to send spooled files to printers attached to remote systems. They are commonly created with two objects: the remote output queue itself; and a virtual printer device that allows the queue to function as a locally attached printer device. However, this configuration has some issues when it is restored from backup media, but those problems are easily fixed if you know the right tricks.
Anatomy of a Remote Output Queue
Remote output queues (remote OUTQ) are a special type of i5/OS writer that communicates with and sends spooled file output to a printer located on a remote system. A remote OUTQ is fairly easy to create, and I published setup instructions in an earlier Admin Alert column, see Remote OUTQs and Auto-Answer Messages.
Unlike a printer device, a remote OUTQ is created without an associated writer. You start the remote writer by executing the Start Remote Writer command (STRRMTWTR), using the remote OUTQ name and library as the command’s parameters. A typical STRRMTWTR command would look like this.
The only thing that differentiates a remote OUTQ from a standard i5/OS writer is that by default, a remote OUTQ doesn’t have a printer device name. This causes problems whenever the system is using a program or command that does not support direct printing to an output queue. These functions–which include Query/400’s Work with Queries command (WRKQRY) and some third-party application–can only send spooled file output to a printer device. To allow these programs, commands, and applications to print to a remote OUTQ, you need to create a virtual printer device that redirects output toward a target remote OUTQ.
A virtual printer device allows every program, command, and application on your system (including WRKQRY) to print directly to its corresponding remote OUTQ, making remote OUTQ writers the functional equivalent of a normal locally attached printer device. Note that some publications (including some IBM documentation) may refer to a virtual printer device as a “dummy device description”.
For more information on how to create a virtual printer device that redirects spooled file output to a remote OUTQ, see my article Making a Remote Output Queue Look Like a Printer Device.
Once you set up the remote output queue and its companion virtual printer device, the configuration will run fine, until you need to restore it.
The Need To Restore Remote OUTQs/Virtual Printer Devices
The problem with virtual printer devices and their associated remote output queues occurs when you try to restore them to the source system or when you try to restore them to another system. You may need to restore a virtual printer device/remote OUTQ pair in the following situations:
In each of these instances, the virtual printer device/remote OUTQ must be set up exactly the same way that it was set up on the original source partition. The problem with duplicating this setup deals with the way that IBM uses the Restore Configuration (RSTCFG) command to restore printer device descriptions to the system.
The Trouble With RSTCFG and Virtual Printer Devices
I can best illustrate this problem through an example. Let’s say that I set up a remote OUTQ/virtual printer device pair where both of the objects are named JOETEST. These objects exist in the following places:
The traditional way to move these pairs is to perform the following steps. Note: For restoring the TESTJOE objects back to their source system, I would first delete the TESTJOE device description and the TESTJOE remote output queue before I restore the objects.
1. I would use the Save Configuration (SAVCFG) command to save my configuration data to media or a save file.
SAVCFG saves all the configuration and resource management objects from my source system. These objects include all my line, controller and device descriptions (including the TESTJOE device), as well as all of my output queue configurations.
2. Once the configuration is saved, I would transfer the backup media to my target system and run the following Restore Configuration (RSTCFG) command to restore TESTJOE to that system.
RSTCFG OBJ(TESTJOE) DEV(device_name) OBJTYPE(*ALL)
The second step is where the problem occurs. According to IBM, this RSTCFG command will restore the TESTJOE virtual printer device back to the QSYS library. However, because the system thinks the TESTJOE device is just a local printer device, it will create and restore a new normal output queue called TESTJOE in library QUSRSYS. RSTCFG does this because it is trying to configure the TESTJOE device the way that it thinks it should be configured. The net result is that because there will already be a normal output queue called TESTJOE on the system, RSTCFG will not restore the TESTJOE remote output queue to the system.
And this problem will occur whether I am trying to restore one remote output queue/virtual printer device pair or 100 of them.
Fortunately, there is an easy way to correctly restore these pairs without too much trouble. Here’s how you do it.
The Right Way To Restore Remote Output Queues To a System
The proper technique only adds three more steps to the procedure listed above, but those extra steps make all the difference. Here is the updated technique for restoring my TESTJOE remote output queue and virtual printer device.
1. On the source system, all my remote output queues should reside in the QUSRSYS library. This technique will not work if the OUTQs are in another library, because the RSTCFG command will always create a corresponding output queue in QUSRSYS for my restored virtual printer device. If I needed to move the JOETEST remote output queue to QUSRSYS, I would use the Move Object (MOVOBJ) command, like this:
MOVOBJ OBJ(lib_name/TESTJOE) OBJTYPE(*OUTQ) TOLIB(QUSRSYS)
2. Backup the source system’s QUSRSYS library by using the following Save Library (SAVLIB) command:
SAVLIB LIB(QUSRSYS) DEV(device_name) SAVACT(*SYNCLIB) SAVACTMSGQ(QSYS/QSYSOPR)
Notice that I am performing a save while active save on QUSRSYS, so that I backup all the objects in QUSRSYS, even if they are in use.
3. Backup the source system’s configuration data to media or to a save file by using SAVCFG.
4. On the target system, restore the remote output queue to the QUSRSYS library by using the backup media created in point 2 and the Restore Object (RSTOBJ) command.
RSTOBJ OBJ(TESTJOE) SAVLIB(QUSRSYS) DEV(device_name)
This will put the TESTJOE remote output queue back in the QUSRSYS library on the target system.
5. Again on the target system, restore the virtual printer device from the media configuration save file created in point 3.
RSTCFG OBJ(TESTJOE) DEV(device_name)
At this point, my remote output queue and its corresponding virtual printer device have been restored from my source system to my target system. Once started, the remote OUTQ will be able to send spooled files to its companion printer output queue on the remote system, and the virtual printer device that I restored to the target system will allow any command, program, or application to send spooled file output to its companion remote output queue.
And that’s how to quickly and easily move or restore a remote output queue and its companion virtual printer device from one system to another.