Mysteries of Restoring Output Queues and Spooled Files

By Dan Riehl

Since version 5.4 of the IBM i operating system, IBM has included the capability to natively save and restore spooled files. Previously, when an output queue object was saved, only the output queue object itself was saved. The spooled files within the output queue weren't saved and therefore couldn't be restored. Even today, unless you specify that you want to save the spooled files in your saved output queues, the spooled files aren't saved.

Since 5.4, an output queue and its associated spooled files can be saved using standard save commands such as Save Library (SAVLIB) and Save Object (SAVOBJ).

In the following example, I save an output queue named ADMIN5P to a save file by using the SAVOBJ command. On the command, I specify the parameter SPLFDTA(*ALL). The SPLFDTA(*ALL) parameter is what causes the spooled files to be saved. Had I not specified SPLFDTA(*ALL), only the output queue object would be saved and not the associated spooled files.

SAVOBJ OBJ(ADMIN5P) LIB(ADMIN5) DEV(*SAVF)  +
       OBJTYPE(*OUTQ) SAVF(DANWORK/DANTEST1) SPLFDTA(*ALL)

I display the contents of the save file by using this command:

DSPSAVF FILE(DANWORK/DANTEST1)

I then see the resulting display showing the saved ADMIN5P output queue.

                             Display Saved Objects                              
                                                                                
 Library saved . . . . . . . :   ADMIN5                                         
                                                                                
 Type Options, press Enter.                                                     
   5=Display                                                                    
                                                                                
 Opt  Object      Type      Attribute   Owner          Size (K)  Data           
  5   ADMIN5P     *OUTQ                 DANRIEHL             96  YES            
     

Selecting option 5=Display aside the ADMIN5P output queue lets me see all the saved spooled files. Each spooled file is identified by the job name, job user, job number, and job spooled file number. These four pieces of information uniquely identify the spooled file to the system.

                          Display Saved Spooled Files                           
                                                                                
 Spooled     File                                     Creation  Creation         
 File        Number   Job         User        Number  Date      Time             
 DANSTART    000001   DANSTART    DANRIEHL    118125  03/29/13  15:31:52         
 QPJOBLOG    000001   DANTEST1    DANRIEHL    117677  03/29/13  16:24:44         
 QPSECUSR    000002   INSTRUCTA1  DANRIEHL    118089  03/29/13  10:59:08         

Restoring the Output Queue

Let's examine a few variations of restoring the output queue and spooled files. Both the Restore Library (RSTLIB) and the Restore Object (RSTOBJ) command specify a default value of SPLFDTA(*NEW), meaning that all *NEW spooled files are restored. A *NEW spooled file is defined as one that doesn't currently exist on the system.

When restoring an output queue with SPLFDTA(*NEW), the system looks for a spooled file with the same unique identifier as the one you're attempting to restore. To determine whether the spooled file already exists, it appears that it's using the spooled file's unique combination of job name, job user, job number, and spooled file number. If a match is found in any output queue on the system, the spooled file is not restored, because it's not *NEW. (Note: In the innards of the OS, there may be some hidden identifier within a spooled file that uniquely identifies it for the save and restore process, but that hidden identifier would need to be unique and most likely based upon the four spooled file attributes of job name, job user, job number, and spooled file number.)

Restoring the Output Queue to the Original Saved Output Queue

To restore the output queue and *NEW spooled files, you can specify the command:

RSTOBJ OBJ(*ALL) SAVLIB(ADMIN5) DEV(*SAVF) +
       SAVF(DANWORK/DANTEST1) SPLFDTA(*NEW)

If spooled files already exist in the queue, they're not disturbed. *NEW spooled files are restored with all their original spooled file attributes.

Restoring an Output Queue to a Different Library

Here's an example of the command to restore the output queue and *NEW spooled files to a different library from where it was originally saved:

RSTOBJ OBJ(*ALL) SAVLIB(ADMIN5) DEV(*SAVF) +
       SAVF(DANWORK/DANTEST1) RSTLIB(ADMIN6) SPLFDTA(*NEW)

The result is actually the same as the previous example. Only Spooled files that are *NEW to the system are restored. Existing spooled files in the queue aren't disrupted, and matching spooled files that already exist on the system aren't disturbed.

Because the *NEW spooled files are restored with their original spooled file attributes, including job name, job user, job number, and job spooled file number, you might reasonably expect to be able to access the spooled files in all methods used prior to the save and restore operation. But, as I discovered in my testing, this isn't the case.

Effect of the System Value QSPLFACN (Spooled File Action)

The QSPLFACT system value determines whether spooled files retain a connection to the jobs that generated the spooled files. The options for the system value are *KEEP (i.e., keep the connection; the job remains on the system until all attached spooled files are removed) and *DETACH (i.e., don't keep a connection; the job is removed from the system when it's completed).

The shipped default value of QSPLFACT is *KEEP. This results in completed jobs with attached spooled files having a job status of *OUTQ when the job is completed. If *DETACH is specified, jobs that have generated spooled files are removed from the system when they're completed.

I wondered—or better yet, I assumed that since the system value is set to *KEEP, when a spooled file was restored for a job no longer on the system, the OS would somehow regenerate an entry in the system job table and reattach the spooled file to a copy of the original job. That turned out to be an invalid assumption. No linkage between the spooled file and its original job is created if the job is no longer on the system.

The spooled files are restored to the output queue, but unless the job is still on the system, the spooled files are not accessible through any job interface such as Work with Job (WRKJOB), Work with User Jobs (WRKUSRJOB), or Work with Submitted Jobs (WRKSBMJOB). The linkage isn't restored for jobs that have been removed from the system. So the spooled files can be accessed only by using Work with Spooled Files (WRKSPLF) and Work with Output Queues (WRKOUTQ) type interfaces, but not through any job interface.

About the Author

Dan performs IBM i security assessments and provides security consulting, remediation, forensic evaluations, and other customized security services for his clients. He also provides training in all aspects of IBM i security and other technical areas through The 400 School, Inc.

Dan Riehl on LinkedIn