Finding and Working with Spooled Files Generated under a QPRTJOB Job

If running V4R4M0 (R440) or V4R5M0 (R450) operating system, specific PTFs must be applied to use the QIBM_NOTIFY_CRTSPLF Environment Variable. If running V4R4M0 (R440) operating system, R440 PTF SF61082 or superseding PTF SF64657 should be applied. If running V4R5M0 (R450) operating system, then R450 PTF SF62350 or superseding PTF SF66903 should be applied. No PTFs are required to use the QIBM_NOTIFY_CRTSPLF Environment Variable in V5R1M0 (R510) operating system and above.

The QIBM_NOTIFY_CRTSPLF environment variable can be used to associate a data queue with a specific job. Once this is set up, the job is notified when a new spooled file has been created under that job. Then, the Receive Data Queue (QRCVDTAQ) API can be used to receive the Record type 02 data queue entry, which includes the Qualified job name, Spooled file name, Spooled file number, Qualified output queue name, Creating qualified job name, User data, Auxiliary Storage Pool, Thread ID, System name, Creation date, and Creation time.

Once a data queue entry is received, a user program can reference the spooled file by using the qualified job name, spooled file name, spooled file number, creation date, and creation time in several operating system commands including, but not limited to, the following:

• Change Spooled File Attributes (CHGSPLFA)
• Copy Spooled File (CPYSPLF)
• Delete Spooled File (DLTSPLF)
• Hold Spooled File (HLDSPLF)
• Release Spooled File (RLSSPLF)
• Send TCP/IP Spooled File (SNDTCPSPLF)

Environment Variable Data Queue Support

Using the Add Environment Variable (ADDENVVAR) or Change Environment Variable (CHGENVVAR) command, you can associate a data queue with a job or the system. As spooled files are created, the entries are logged in the data queue. Using the Receive Data Queue (QRCVDTAQ) API to receive information from the data queue, a user program can determine when a spooled file is created by the job or by the system. Use the environment variable data queue support to determine the identity of a spooled file that was stored under a QPRTJOB and was created by a job (such as a remote command system job).

Using the CL command ADDENVVAR and specifying a fully qualified data queue name for the environment variable QIBM_NOTIFY_CRTSPLF you can associate a data queue with a job or the system. The command used is as follows:

ADDENVVAR ENVVAR(QIBM_NOTIFY_CRTSPLF)
          VALUE('*DTAQ <library name>/<data queue name>')
          LEVEL(*JOB | *sys)

The data queue must be created with a record length of at least 144 bytes. The data queue must also have a public authority of *USE, or grant the QSPL user profile *USE private authority to the data queue. You must ensure that the containing library has a public authority of *EXECUTE, or grant the QSPL user profile *EXECUTE private authority to the library. The format of the CRTDTAQ command is:

CRTDTAQ DTAQ (<library name>/<data queue name>) MAXLEN(144) AUT(*USE)

Once a data queue is associated with a job or the system, any spooled file created by the job or system will automatically have an entry placed in the data queue. For this action to occur, the user or user profile QSPL must have authorization to the data queue.

Note: An environment variable that is specified at the job level takes precedence over the same environment variable specified at the system level.

The entry in the data queue has a format of record type 02. See Record type 02 data queue entry format for a description of the information contained in record type 02.

Record type 02 data queue entry format

The data queue entry placed in the data queue specified in the environment variable QIBM_NOTIFY_CRTSPLF has the following format:
 

Decimal Offset	Hex Offset	Type	Length	Description
0	0	CHAR	10	Function Identifies the function that created the data queue entry. The value for a spooled file is *SPOOL.
10	A	CHAR	2	Record type Identifies the record type within the function. Valid values are: 02 A Spooled file has been created and placed on an output queue.
12	C	CHAR	26	Qualified job name Identifies the qualified job name of the job that the spooled file is stored under. CHAR(10) Job name CHAR(10) User name CHAR(6) Job number
38	26	CHAR	10	Spooled file name Identifies the name of the spooled file placed on the output queue.
48	30	BINARY	4	Spooled file number Identifies the unique number of the spooled file placed on the output queue.
52	34	CHAR	20	Qualified output queue name Identifies the qualified name of the output queue on which the spooled file was placed. CHAR(10) Output queue name CHAR(10) Output queue library
72	48	CHAR	26	Creating qualified job name Identifies the qualified job name of the job that created the spooled file. CHAR(10) Job name CHAR(10) User name CHAR(6) Job number
98	62	CHAR	10	User data Identifies the user specified data for the spooled file that was created.
108	6C	BINARY	4	Auxiliary storage pool Identifies the auxiliary storage pool the spooled file resides on.
112	70	CHAR	8	Thread identifier Identifies the thread of the job that created the spooled file.
120	78	CHAR	10	Reserved
130	82	CHAR	7	Creation date Identifies the date on which the spooled file was created. The date is in format CYYMMDD.
137	89	CHAR	6	Creation time Identifies the time on which the spooled file was created. The time is in format HHMMSS.
143	BF	CHAR	1	Reserved

1. Use the Create Data Queue (CRTDTAQ) command to create a data queue to be updated whenever a spooled file has been created in the current job. For example:
   
   CRTDTAQ DTAQ (<library name>/<data queue name>) MAXLEN(144) AUT(*USE)
   
   Note: The data queue must be created with a record length of at least 144 bytes. The data queue must also have a public authority of *USE, or grant the QSPL user profile *USE private authority to the data queue. You must ensure that the containing library has a public authority of *EXECUTE, or grant the QSPL user profile *EXECUTE private authority to the library.
2. Use the Add Environment Variable (ADDENVVAR) command to assign the QIBM_NOTIFY_CRTSPLF environment variable to point to the data queue that was just created. For example:
   
   ADDENVVAR ENVVAR(QIBM_NOTIFY_CRTSPLF)
             VALUE('*DTAQ <library name>/<data queue name>')
             LEVEL(*JOB | *sys)
3. Swap to the other user profile.
4. Generate a spooled file.
5. Use the Receive Data Queue (QRCVDTAQ) API to determine the qualified job name, spooled file name, spooled file number, creation date and creation time for the spooled file created in Step 4.
6. Process the spooled file by using the qualified job name, spooled file name, spooled file number, creation date and creation time received from the data queue entry.
7. Repeat Steps 3 through 6 as necessary.

For More Information

For more information, refer to the following topics in the IBM i Information Center.

IBM i: Data Queue Support:  https://www.ibm.com/docs/en/i/7.5?topic=sfoq-data-queue-support
Record type 02 data queue entry format:  https://www.ibm.com/docs/en/i/7.5?topic=dqs-record-type-02-data-queue-entry-format
Receive Data Queue (QRCVDTAQ) API:  https://www.ibm.com/docs/api/v1/content/ssw_ibm_i_75/apis/qrcvdtaq.htm

If running V5R2M0 (R520) operating system or above, the Retrieve Identity of Last Spooled File Created (QSPRILSP) API can be used to retrieve information on the last spooled file created by the current job. The QSPRILSP API returns this information in the receiver variable using the SPRL0100 format, which includes the Bytes returned, Bytes available, Spooled file name, Job name, User name, Job number, Spooled file number, Job system name, Spooled file create date, and Spooled file create time.

Once the QSPRILSP API has retrieved information on the last spooled file created, a user program can reference the spooled file by using the spooled file name, job name, user name, job number, spooled file number, job system name, spooled file create date and spooled file create time in several operating system commands including, but not limited to, the following:

• Change Spooled File Attributes (CHGSPLFA)
• Copy Spooled File (CPYSPLF)
• Delete Spooled File (DLTSPLF)
• Hold Spooled File (HLDSPLF)
• Release Spooled File (RLSSPLF)
• Send TCP/IP Spooled File (SNDTCPSPLF)

Decimal Offset	Hex Offset	Type	Length	Description
0	0	BINARY	4	Bytes returned Identifies the function that created the data queue entry. The value for a spooled file is *SPOOL.
4	4	BINARY	4	Bytes available The number of bytes of data available to be returned. All available data is returned if enough space is provided.
8	8	CHAR	10	Spooled file name The name of the last spooled file created by the current job or thread.
18	12	CHAR	10	Job name The name of the job that owns the spooled file.
28	1C	CHAR	10	User name The name of the user who owns the last spooled file created by the current job or thread.
38	26	CHAR	6	Job number The number of the job that owns the spooled file.
44	2C	BINARY	4	Spooled file number The number of the last spooled file created by the current job or thread.
48	30	CHAR	8	Job system name The name of the system where the job that created the spooled file ran.
56	38	CHAR	7	Spooled file create date The date the spooled file was created on the system. The date is in the CYYMMDD format as follows: C Century, where 0 indicates years 19xx and 1 indicates years 20xx. YY Year MM Month DD Day
63	3F	CHAR	1	Reserved
64	40	CHAR	6	Spooled file create time The time the spooled file was created on the system. The time is in the HHMMSS format where: HH Hour MM Minutes SS Seconds

1. Swap to the other user profile.
2. Generate a spooled file.
3. Use the Retrieve Identity of Last Spooled File Created (QSPRILSP) API to determine the spooled file name, job name, user name, job number, spooled file number, job system name, spooled file create date, and spooled file create time for the spooled file created in Step 2.
4. Process the spooled file by using the spooled file name, job name, user name, job number, spooled file number, job system name, spooled file create date and spooled file create time retrieved by the QSPRILSP API
5. Repeat Steps 1 through 4, as necessary.

For More Information

For more information, refer to the following Rochester Support Center knowledgebase document:

641319: Retrieving Spooled Files Generated in a Host Server Job

and the following topic within the IBM i Information Center:

Retrieve Identity of Last Spooled File Created (QSPRILSP) API:  https://www.ibm.com/docs/en/i/7.5?topic=ssw_ibm_i_75/apis/QSPRILSP.html

• Work with User Jobs (WRKUSRJOB) command, select Option 5 (Work with) on the QPRTJOB job that is in the list. Then, select Option 4 (Work with spooled files) to work with the spooled files associated with that QPRTJOB job.
• Use the Work with Job (WRKJOB) command, specify "QPRTJOB" for the job name, and specify the job user name. Leave the job number blank, for example:
  
  WRKJOB JOB(user-profile/QPRTJOB)
  
  If there is more than one QPRTJOB job associated with the user profile, this command typically brings up the Select Job screen where the job can be selected using Option 1. Otherwise, this command will take you directly to the Work with Job screen for that specific job, so you can then select Option 4 (Work with spooled files) to work with the spooled files associated with that QPRTJOB job.
  
  Note: The Work with Job (WRKJOB) command can be used with the Option (OPTION) parameter set to *SPLF to take you directly to the Work with Job Spooled Files screen without having to first select Option 4 (Work with spooled files). For example:
  
  WRKJOB JOB(user-profile/QPRTJOB) OPTION(*SPLF)
• You can work with spooled files on the system using iSeries Navigator by going into Basic Operations > Printer Output. Pressing the F11 key, or selecting View > Customize this View > Include, brings up the "Printer Output - Include" dialog box, that will let you specify which printer output to display in the list. This dialog lets you specify the job name. Therefore, you can set the job name to "QPRTJOB" and specify the job user name. However, the job number must also be specified.
  
  Note: Pressing the F12 key, or selecting View > Customize this View > Columns brings up the "Printer Output - Columns" dialog box that lets you specify which columns of information you want to display in the list. If the Job Name column is added to the list, you can scan the list of spooled files looking for a job name of "QPRTJOB" to find the spooled file.