API Corner: List Spooled Files From an Application

August 3, 2005 Shannon O'Donnell

The code for this article is available for download. Please note: the code has been changed since this story first ran. [Modified 09/08/05]

In this article, I will show you how to use the QUSLSPL (List Spooled Files) Print API to display all the spooled files for the current user, from within an application. Why is this something you would want to do? The biggest reason I can think of is security. Most of the time, you would rather not have to grant your users access to a command line interface. However, to allow the users to view their spooled files, you had no other choice. Until now. By using the QUSLSPL API you can now give your users the ability to view their spooled files in the manner you deem most secure, from within their application. They will never need access to a command line again!

QUSLSPL API

The QUSLSPL API is part of the PRINT APIs, and more specifically, part of the Spooled File Print APIs. The QUSLPL API is very similar to the view you get when you use the WRKSPLF (Work with Spooled Files) command from the OS/400 command line. The biggest differences between this API and that command are:

• The user can view their spooled files without requiring access to a command line
• The amount of work you have to do to recreate all the functionality of the WRKSPLF command is not insignificant

Because there is a lot of work involved in recreating the most significant portions of the WRKSPLF command, by using the other Spooled File APIs, we are going to take a different approach. We’ll use the QUSLSPL API to list the user’s spooled files, but for viewing, changing, deleting and other functionality, we will use the OS/400 command designed for that function, via the QCMDEXC (Command Execute) API. My theory is that when it’s appropriate to build a door from scratch, you build a door from scratch. When it’s appropriate to buy a pre-built door, you buy a pre-built door. In other words, once we have the list of the user’s spooled files, retrieved via QUSLSPL, there’s no reason not to use the OS/400 commands that already exist to manipulate those spooled files.

Figure 1: The Program Output

In Figure 1, you can see what the output of this program will look like. The basic information I am returning in this sample program (code available for download with this article), is:

• The spooled file name
• The spooled file number
• The status of the spooled file
• The spooled file form type
• The name of the output queue associated with this spooled file
• The number of pages this spooled file has
• The number of copies this spooled file will print

The Mechanics

If you’ve been following along with the other articles in the series API Corner, then you will be familiar with most of the mechanics of how to use this API already. For those of you who have just turned in, allow me to review.

The first thing we want to do for any LIST API, such as the one we are using here, is to create a user space object to dump the returned list into. We do that using a two-step process. We first delete the user space, just in case it already exists, and then we create it. Alternatively you could have cleared the user space, but my preference is to delete it and start fresh.

The relevant code to accomplish these two steps looks like this:

 
      * Create the Qualified User Space Name
     C                   Eval      qUserNm   = 'SPLFLST   QGPL      '
     C                   Eval      qText         = 'Spooled Files List'
      *
      * Attempt to delete the user space first...
      * Just to clean it up
     C                   Call      'QUSDLTUS'                     50
     C                   Parm                              qUserNm
     C                   Parm                              dsEc
      *
     C                   Endsr

	
     C                   Call      'QUSCRTUS'                     50
     C                   Parm                                qUserNm
     C                   Parm      *Blanks             eXtAtr
     C                   Parm      5000                  iNzSize
     C                   Parm      *Blanks             iNVal
     C                   Parm      '*CHANGE'     pUbAut
     C                   Parm                               qText
     C                   Parm                               rEplace
     C                   Parm                               dsEc
      *

The next step is to execute the API to list the current user’s spooled files into the user space.

To use this API, we have to pass it several input parameters that tell it what information we want it to return. Those parameters are:

• User Space Name – The qualified user space name we created in the previous step.
• API Format – This is the format, as identified by the API documentation, that we want the API to return our data in. For most APIs, you have a choice of a variety of formats. For our example, we will tell the API to use format SPLF0300. We’ll take a look at the layout of that format in just a moment.
• The User ID – This is the user profile of the user who’s spooled files you want to return. You have two choices for this parameter: *ALL, which returns spooled files for all users on the system, or *CURRENT, which returns spooled files for only the user running this program. NOTE: There is also a way to return spooled files for specific jobs, user profiles, etc. beyond what you’ve seen so far. However, that method is beyond the scope of this article.
• The Output Queue – This input parameter will contain the name of the output queue you want to retrieve the list of spooled files from. The possible values are: *ALL, or a named output queue. In our example, we will look in *ALL output queues for this user profile.
• Form Type – This input parameter can be used to subset the returned list by a specific form type. The possible values are *ALL or *STD.
• User Data – If you want to return a list based on the text that appears in the User Data field of the spooled file, you can do so by specifying that user data text here. Otherwise, enter *ALL for all user data values.
• Standard Error Data Structure.

The code we use to execute this API looks like this:

 
     C                   Call      'QUSLSPL'                     50
     C                   Parm                                qUserNm
     C                   Parm      'SPLF0300'        Format
     C                   Parm      '*CURRENT'    IUser
     C                   Parm      '*ALL'               IOutq
     C                   Parm      '*ALL'               IFrmTyp
     C                   Parm      '*ALL'               IUsrDta
     C                   Parm                               dsEc

Once we have retrieved the list of spooled files into the user space, we then need to peek into the standard header section of the list to see how many entries were returned, and where the list data begins. We need to obtain this information first so that we know where to start parsing the user space data.

The standard API header section and the code used to retrieve it and process it is the same for every list API, can be found in the sample code. I will not include it here as I have already included this list in other articles in this series and to include it now would border on painful redundancy for the reader.

The same holds true for the code used to process the list API. If you are not familiar with list APIs, I strongly encourage you to go back and read the earlier articles in the API Corner series. All of the information is included in those articles and what you learn there is immediately applicable to this API as well.

The rest of the sample program is pretty straightforward. We simply iterate through the list API data and build a subfile, line by line, from the returned information. When we have exhausted our list, the subfile is complete and it is displayed. I have also added a function on there to allow the user to refresh the list, just in case their spooled files increase or decrease while they have the list open.

Extending the API

There are a lot of additional pieces of information available with the SPLF0300 format for this API including:

• Date spooled file was opened
• Time spooled file was opened
• Size of spooled file
• ASP spooled file lives in
• Priority of spooled file
• More . . .

You can tweak this sample program to allow the users extended “views” of their spooled file data by adding a couple of function keys and then rebuilding the subfile based on the information they request to see.

In addition to the SPLF0300 format, there are two other formats you can use with this API: SPLF0100 and SPLF0200. Both of these formats offer considerably more information which will be returned in the list. However, to use these formats, the amount of information you have to pass to the API as input parameters also increases. If you are interested in learning more about this API, I encourage you to visit the IBM Information Center online at http://publib.boulder.ibm.com/infocenter/iseries/v5r3/ic2924/index.htm and check out the section under PROGRAMMING on APIs. The documentation for the QUSLSPL API can be found in the PRINT/Spooled File API Section.

Using Existing OS/400 Spooled File Commands

As you will see when you download the code for this article, I’ve also recreated all the normal WRKSPLF command functionality including viewing, deleting, changing, and sending spooled files. Each of these functions has been recreated by using the appropriate OS/400 command designed for that spooled file function.

You can use this program, as is, to give your users the same functionality they have with the WRKSPLF command, without compromising your security by exposing the OS/400 command line.