Open Spooled File (QSPOPNSP) API

The Open Spooled File (QSPOPNSP) API opens an existing spooled file. After the existing spooled file is opened, the Get Spooled File Data (QSPGETSP) API can then get the data from the file.

Authorities and Locks

Spooled File Authorities

The requester is authorized to the spooled file if one or more of the following conditions are met.

• The requester is the owner of the spooled file.
• The requester has *READ authority to the queue on which the spooled file resides, and the queue is specified as DSPDTA(*YES).
• The requester has *SPLCTL authority.
• The requester has *JOBCTL authority, and the queue on which the spooled file resides is specified as OPRCTL(*YES).
• The requester has ownership of the queue on which the spooled file resides, and the queue is specified as AUTCHK(*OWNER).
• The requester has read, add, and delete authorities to the queue on which the spooled file resides, and the queue is specified as AUTCHK(*DTAAUT).

Spooled File Lock

*LSRD

Required Parameter Group

Spooled file handle returned

OUTPUT; BINARY(4)

The handle used on subsequent get (QSPGETSP API) and close (QSPCLOSP API) operations to identify the spooled file.

Qualified job name

INPUT; CHAR(26)

The job that owns the spooled file. The qualified job name has three parts:

job name	CHAR(10). A specific job name, or one of the following special values: * Only the job that this program is running. The rest of the job name parameter must be blank. *INT The internal job identifier used to locate the spooled file. The user name and job number must be set to blank.
user name	CHAR(10) A specific user profile name, or blanks when the job name is * or *INT.
job number	CHAR(6). A specific job number, or blanks when the job name is * or *INT.

Internal job identifier

INPUT; CHAR(16)

The internal job identifier for the job that owns the spooled file. Use the Retrieve Spooled File Attributes (QUSRSPLA) API or one of these APIs to make the identifier available: List Spooled Files (QUSLSPL) API

Internal spooled file identifier

INPUT; CHAR(16)

The internal spooled file identifier for the spooled file. To make the identifier available, use the Retrieve Spooled File Attributes (QUSRSPLA) API or see List Spooled Files (QUSLSPL) API.

Spooled file name

INPUT; CHAR(10)

The name of the spooled file to be opened. You can use this special value for the name:

*INT	The internal spooled file identifier is used to locate the spooled file.

Spooled file number

INPUT; BINARY(4)

The unique number of the spooled file. The valid range is 1 through 999999.

The following special values are supported for this parameter:

0	Only one spooled file from the job has the specified file name, so the number of the spooled file is not necessary.
-1	This uses the highest-numbered spooled file with the specified file name.
-2	The spooled file number is not used to determine which spooled file to process. Use this value when you want the Job system name parameter or the Spooled file create date and Spooled file create time parameters to take precedence over the spooled file number when selecting a spooled file.

Number of buffers to get

INPUT;BINARY(4)

How many buffers to get on each call to the QSPGETSP API. Valid numbers include 1 through 8, 16, 24, and 32. Any values greater than 32 must be a multiple of 32. A value greater than 1 should show some performance improvement. A value of 8 may give the best performance when using the QSPGETSP API.

The following special value is supported for this parameter:

-1	Reads the entire spooled file.

If the user space cannot accommodate all buffers requested, as many complete buffers as possible will be returned in the available space. The information complete indicator in the header section of the data returned is then set to P.

If the end of an open spooled file is encountered before the buffer count is reached, the end of open spooled file parameter on the Get Spooled File Data (QSPGETSP) API determines the action taken.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Optional Parameter Group

Job system name

INPUT; CHAR(8)

The name of the system where the job that created the spooled file ran or blank when the spooled file name is *INT. This parameter is considered after the job name, user name, job number, spooled file name, and spooled file number parameter requirements have been met.

The following special values are supported for this parameter:

*ONLY	There is one job with the specified job name, user name, job number, spooled file name, spooled file number, spooled file creation date, and spooled file creation time.
*CURRENT	The job on the current system with the specified job name, user name, job number, spooled file create date, and spooled file create time is used.
*ANY	The job system name is not considered when selecting a spooled file. Use this value when you want the Spooled file create date and Spooled file create time parameters to take precedence over the job system name when selecting a spooled file.

If this parameter is omitted, the API assumes blanks when the spooled file name is *INT. When spooled file name is not *INT, the API assumes *ONLY.

Spooled file create date

INPUT; CHAR(7)

The date the spooled file was created on the system or blank when the spooled file name is *INT. This parameter is considered after the job name, user name, job number, spooled file name, spooled file number, and job system name parameter requirements have been met. The date must be in the CYYMMDD format or one of the following special values:

*ONLY	There is only one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, and job system name.
*LAST	The spooled file with the latest date and time which also has the specified job name, user name, job number, spooled file name, spooled file number, and job system name is used.

The date format CYYMMDD is defined as follows:

C	Century, where 0 indicates years 19xx and 1 indicates years 20xx.
YY	Year
MM	Month
DD	Day

If this parameter is omitted, the API assumes blanks when the spooled file name is *INT. When spooled file name is not *INT, the API assumes *ONLY.

Spooled file create time

INPUT; CHAR(6)

The time the spooled file was created on the system or blank when the spooled file name is *INT. This parameter must be set to blanks when special values *LAST or *ONLY are used for parameter Spooled file create date. This parameter must have a value set if a date is specified for parameter Spooled file create date. This parameter is considered after the job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file create date parameter requirements have been met. The time must be in the HHMMSS format or one of the following special values:

*ONLY	There is only one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, job system name, and create date.
*LAST	The spooled file with the latest time which also has the specified job name, user name, job number, spooled file name, spooled file number, job system name, and create date is used.

The time format HHMMSS is defined as follows:

HH	Hour
MM	Minutes
SS	Seconds

If this parameter is omitted, the API assumes blanks.

How to Select a Spooled File to Be Opened

This table illustrates the valid parameter combinations of qualified job name, internal job identifier, internal spooled file identifier, spooled file name, job system name, spooled file create date, and spooled file create time. The combinations of these parameters identify the spooled file to be opened. For example, when the qualified job name parameter value is *, the internal job identifier must be blank, the internal spooled file identifier must be blank, and the actual name and number of the spooled file must be given.

Notes: This parameter combination is not valid when a job has been detached from its spooled files or for a spooled file on an independent disk pool. Use of this combination will result in message CPF3C43.

Error Messages