Open Spooled File (QSPOPNSP) API
Required Parameter Group:
| 1 | Spooled file handle returned | Output | Binary(4) |
| 2 | Qualified job name | Input | Char(26) |
| 3 | Internal job identifier | Input | Char(16) |
| 4 | Internal spooled file identifier | Input | Char(16) |
| 5 | Spooled file name | Input | Char(10) |
| 6 | Spooled file number | Input | Binary(4) |
| 7 | Number of buffers to get | Input | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 9 | Job system name | Input | Char(8) |
| 10 | Spooled file create date | Input | Char(7) |
| 11 | Spooled file create time | Input | Char(6) |
Default Public Authority: *USE
Threadsafe: No
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, based on local job time, that 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, in local job time, that 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.
| Qualified Job Name | Internal Job Identifier | Internal Spooled File Identifier | Spooled File Name | Spooled File Number | Job System Name | Spooled File Create Date | Spooled File Create Time | ||
|---|---|---|---|---|---|---|---|---|---|
| Job Name | User Name | Job Number | |||||||
| Name | Name | Number | Blanks | Blanks | Name | -2 through 999999 | Name, *ONLY, *CURRENT, or *ANY | Date, *ONLY, or *LAST | Time, blanks, *ONLY, or *LAST |
| Name | Name | Blanks | Blanks | Blanks | Name | -2 through 999999 | Name, *ONLY, *CURRENT, or *ANY | Date, *ONLY, or *LAST | Time, blanks, *ONLY, or *LAST |
| * | Blanks | Blanks | Blanks | Blanks | Name | -2 through 999999 | Name, *ONLY, *CURRENT or *ANY | Date, *ONLY or *LAST | Time, blanks, *ONLY or *LAST |
| *INT | Blanks | Blanks | Internal job identifier | Internal spooled file identifier | *INT | -2 through 999999 | Blanks | Blanks | Blanks |
| *INT | Blanks | Blanks | Internal job identifier | Blanks | Name | -2 through 999999 | Name, *ONLY, *CURRENT, or *ANY | Date, *ONLY, or *LAST | Time, blanks, *ONLY, or *LAST
See Notes for additional information. |
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
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C33 E | Spooled file number &1 is not valid. |
| CPF3C40 E | Spooled file &4 not found. |
| CPF3C41 E | More than one spooled file with same name. |
| CPF3C42 E | User name or job number is not blank. |
| CPF3C43 E | Internal job identifier is not valid. |
| CPF3C44 E | Internal spooled file identifier is not valid. |
| CPF3C58 E | Job name specified is not valid. |
| CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF33C9 E | Spooled file name parameter cannot be blank. |
| CPF33DA E | Value &1 not valid for number of buffers to read parameter. |
| CPF33DB E | Qualified job name parameter not valid with internal spooled file name. |
| CPF33DC E | Open or create not valid for diskette files. |
| CPF33DD E | Maximum number of open spooled files exceeded for this job. |
| CPF33DE E | Size of internal data for opened spooled file exceeds maximum. |
| CPF33DF E | Internal data area for opened spooled files destroyed. |
| CPF3309 E | No files named &1 are active. |
| CPF3330 E | Necessary resource not available. |
| CPF333B E | Job system name is not valid. |
| CPF333C E | Spooled file create date is not valid. |
| CPF333D E | Spooled file create time is not valid. |
| CPF333E E | Spooled file create time is not blank. |
| CPF333F E | Job system name is not blank. |
| CPF3342 E | Job &5/&4/&3 not found. |
| CPF3343 E | Duplicate job names found. |
| CPF3344 E | File &1 number &2 no longer in the system. |
| CPF335B E | Spooled file create date is not blank. |
| CPF3492 E | Not authorized to spooled file. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1
[ Back to top | Print APIs | APIs by category ]