Host Server Jobs and Spooled File Identities

By:

When I need to obtain the qualified job name within which a spooled file was created, I generally use the Retrieve Job Attributes (RTVJOBA) command:

RTVJOBA  JOB(&JOB) USER(&USER) NBR(&JOBNBR)

With that information, I can easily manipulate the spooled file. For instance, I can use the Copy Spooled File (CPYSPLF) command to transform it to a flat file:

CPYSPLF FILE(MYSPLF) TOFILE(QTEMP/TEMPFILE) +   
   JOB(&JOBNBR/&USER/&JOB) SPLNBR(*LAST) CTLCHAR(*PRTCTL)

That's just one example of when identifying the last spooled file generated in the job is useful. Another example would be to run a command, for example from an ISV, that converts my spooled file into a PDF.

I widely use this technique in my programs, and it works well for interactive and batch jobs but not for server jobs. Server programs typically swap from one user profile to another for security reasons. When that happens, the spooled file is created with a different job ID. In that scenario, you need the help of the Retrieve Identity of Last Spooled File Created (QSPRILSP) API to identify the last spooled file created, even though it was created in the same job.

Host Servers, such as Database Server (QZDASOINIT) and Remote Command and Program Call Server (QZRCSRVR), enable n-tier, client/server architecture. QZRCSRVR server listens for and accepts TCP/IP connection requests from several clients. On the server side, these jobs run with the QUSER user profile in the QUSRWRK subsystem. If I use the RTVJOBA command to get the fully qualified name of a host server job as in the preceding example, I would obtain something like this:

  <job number>/QUSER/QZRCSRVR

Unfortunately with this technique, it is impossible to uniquely identify the spooled files generated from this host server job, because

the owner of the spooled files is not the user profile currently running (QUSER), but rather the current user, that is, the client user who launched the job into the system
the job name of the spooled files is not the name of the host server job, but rather the special job name QPRTJOB.
the job number of the spooled files is not the number of the host server job, but rather the number of the QPRTJOB job.

So we must use some tool specifically designed to identify the last spooled file created by the current job or thread. The QSPRILSP API is adequate.

The QSPRILSP API

According to the i5/OS Information Center, "The Retrieve Identity of Last Spooled File Created (QSPRILSP) API returns the complete spooled file identity of the last spooled file created for the current job or thread."

The API expects two input parameters -- the length of the receiver variable and the format name -- and returns in an output parameter the identity of the last spooled file created. In the API's lingo, output parameters are called receiver variables. A receiver variable is a program variable used as an output field to contain information returned from an API. A fourth I/O error-code parameter is also required.

Although the QSPRILSP API is so simple that it can be called from a CL program, this article explains how to use it from a Cobol program. The prototypes for the receiver variable and the error-code parameters are provided by IBM in the separate include members QSYSINC/QCBLLESRC(QSPRILSP) and QSYSINC/QCBLLESRC(QUSEC), letting you call this API without the tedious task of translating and coding the prototypes.

The only valid format name is SPRL0100.

Bear in mind that this article includes only the subprocedure that calls the API. In some place, the main procedure calls this subprocedure, and then it makes something with the returned information:

       ID  DIVISION.
       PROGRAM-ID.    "Retrieve_Last_Spooled_File_ID".
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  length-of-receiver      PIC 9(9) BINARY.
       01  format-name             PIC x(8).
       01  spool-file-identity.
           03 splf-name            PIC X(10).
           03 job-name             PIC X(10).
           03 usr-name             PIC X(10).
           03 job-number           PIC X(06).
       COPY qsprilsp OF qsysinc-qcbllesrc.
       COPY qusec OF qsysinc-qcbllesrc.

       PROCEDURE DIVISION RETURNING spool-file-identity.

       main SECTION.
      *----------------
       main-paragraph.
      *----------------
           MOVE LENGTH OF qsp-sprl0100 to length-of-receiver.
           MOVE "SPRL0100" TO format-name.
           MOVE LENGTH OF qus-ec TO bytes-provided OF qus-ec.
           CALL QSPRILSP USING qsp-sprl0100,
                               length-of-receiver,
                               format-name,
                               qus-ec
           END-CALL.
           IF bytes-available OF qus-ec > 0
              DISPLAY exception-id OF qus-ec
           END-IF.
           MOVE CORR qsp-sprl0100 TO spool-file-identity.
      *----------------
       goodbye.
      *----------------
           GOBACK.
       END PROGRAM "Retrieve_Last_Spooled_File_ID".

You can test this program example by running it in interactive or batch mode but more interesting would be to test it in the context of a server job. You can get it by launching the program from the Remote System Explorer (RSE) perspective of WDSc in a multi-threaded mode.

More Information:

Information about the QSPRILSP API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/apis/QSPRILSP.htm [2]

An IBM Software technical document explaining different techniques to retrieve spooled files generated in server jobs:
http://www-912.ibm.com/s_dir/slkbase.NSF/00e42b791a3dab7b862565c9004ec1af/ae40ce0ecaadc1c6862569ff0056a4f6?OpenDocument [3]