Problem solve Get help with specific problems with your technologies, process and projects.

Controlling spool files with APIs

Use application programming interfaces, or APIs, to send spool files from your iSeries. Users can alter the source code in this tip to fit their needs.

Recently, Benito Abraham provided an interesting spool file tip, in which he discussed doing an XCOPY to a CSV...

(or comma separated value) file for emailing to whoever needs the information. While I like the XCOPY, there is one part I dislike very much. That is the F11 and writing down the attributes of the spool file that you need as parameters to the XCOPY command.

Well, never fear, IBM comes through for us iSeries folks with a number of application programming interfaces (APIs) for spool files. In this tip, I describe one possible way to use these APIs to minimize the drudgery of spool file attributes and parameter passing.

First, a disclaimer. Any similarity in the coding of these objects is purely coincidental to any other posted tip, article, or commercially available software. After doing this for 20 years, you do a lot of reading, research, testing, etc., and there is no way to prevent such similarities. So my thanks to all who have provided tips or articles that may have influenced the creation of this particular tip.

Here is a screen shot of the finished application:


It's not really the same as the system's WRKSPLF command, but that's the point. Using the spool file APIs, I retrieved the list of spool files for myself and presented a subfile of the results. A few of the applications' characteristics are designed for the needs of my users. Primarily, the move, email and fax routines are essentially snap-in/snap-out portions as needed. Obviously, you could make the option field two digits and have more flexibility to add routines. The code listed below will show the "move to another outq" logic, my email solution logic and a called routine for faxing. All these can be replaced with a different task, made service program procedures, external calls or whatever you need. You could even drive the selections available to the user from a database as well. It's a wide-open choice once you understand the APIs enough to get this far.

Option 1 is a simple Move It task, allowing multiple selections and defaulting to the outq listed in the header. That outq is an incoming parameter from a command just to make some users more comfortable, and is an input-capable field for changes on the fly. Likewise, Option 5 is just your garden variety display of the spool file.

The processing of a subfile is wonderful in its ability to select more than one item at a time. But for email or faxing, this presents two differing problems and solutions. Here is what the faxomg option shows to the user:


Faxing is a piecemeal process. So no matter how many items you select, you need to handle each one separately. Here, I do not have a database of typical fax locations/customers/etc. to work against, so I display the essential data needed to complete the transmission. The window is integral to the program, but the processing of the parameters is externalized to the CL program code below. Replace this with whatever logic fits your circumstances.

Here is the email processing display:


My email solution is not a very recent set of software. It's actually the IBM MMAIL set of applications. Here you see the required data. Some of this may be something you can fetch from other places, such as the from information. But remember that you can yank out my solution and add yours very easily.

The MMAIL software allows for multiple spool files to be sent at one time if needed, to one or more addresses. I selected two spool files and there is a subfile in the middle of the window for the addressing information. Fill it in, roll up and add as many as 50 to's, cc's or bcc's. I added some of the other parameters as well, like making up the body text of a message either from a known text file or a temporary one. I chose to force the spool files to be attached to an email as PDF objects, so those parameters are not here. A quirky thing with MMAIL is that it uses a complex qualified list in its command to pass the spool file parameters into the programming. A bunch of this code is devoted to handling this, but the saving grace was the command's validity checker. By running my strings through it, they come out ready for the regular program.

The heart of this process and the real focus of this tip is the APIs. These spool files are part of what's known as list APIs, which use a user space object to work in while building the information you request. If you have not worked with these before, here is a starting example.

First we set the parameters, some of which are already initialized with their variables, and we call the QUSCRTUS API to create our user space. Next, the QUSLSPL API will retrieve the spool file entries requested and place them in the user space. I choose to retrieve based on user ID, but you have other options, such as a specified output queue.

The challenging thing with user spaces is that there will be a header followed by details, all together. First you retrieve the header with some default parameters found in IBM's descriptions of the API. In this case, it gives us the number of spool file entries that were found and how to get to them with offsets/lengths. Once you know you have entries, execute the same API as the header but change the data structure to QUSF0100 for the spool file information. Then call one more QUSRSPLA to break out the individual attributes of that spool file, which are then placed on the screen. The data structures used by the APIs, found from the /INCLUDE directives at the start of the program, tell you a lot about the data you are mapping to, so check them out as well as the IBM definition of the API and its parameters.

There you have it. It looks like a monster, but it gives you all the possibilities of WRKSPLF with the flexibility of writing your own procedures to manipulate their processing. I hope you find this useful.


Dig Deeper on Imaging on iSeries

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.