| 1 | Spooled file handle | Input | Binary(4) |
| 2 | Qualified user space name | Input | Char(20) |
| 3 | Format name | Input | Char(8) |
| 4 | Ordinal number of buffer to be read | Input | Binary(4) |
| 5 | End of open spooled file | Input | Char(10) |
| 6 | Error code | I/O | Char(*) |
The Get Spooled File Data (QSPGETSP) API gets data from an existing spooled file. The existing spooled file must have been opened previously by the Open Spooled File (QSPOPNSP) API. Data is retrieved from the existing spooled file by buffers (one or more) and stored in a user space. The data in the user space is used as source to the Put Spooled File Data (QSPPUTSP) API. The number of buffers returned in the user space is no greater than the value specified on the number of buffers to get parameter on the Open Spooled File (QSPOPNSP) API.
Depending on the data format requested, the actual number of bytes returned for each buffer may vary from the size of the buffer. Format SPFR0300 may return fewer bytes for each buffer than the actual buffer size. Format SPFR0200 may return more bytes because additional sections, such as the buffer information, general information, and page data section are included. The buffer size is in relation to the print data, not the other information sections.
When creating the user space for the spooled file data, an initial user space size that is calculated by adding the size of the generic header section to the product of the buffer size (currently 4079 or 512) and the number of buffers to get provides adequate space for format SPFR0300. However, this may be too small for format SPFR0200. For format SPFR0200, the size of the user space needed is variable based on the number of pages per buffer. Normally, a good estimate for the user space size needed for SPFR0200 would be the number of buffers multiplied by the buffer size plus 500 bytes. The user space is automatically extended, if necessary, to allow all buffers requested to be stored in the user space.
User spaces can be created using the Create User Space (QUSCRTUS) API. The time it takes to create a user space is decreased if you specify to initialize the space to hexadecimal zeros.
The maximum size of a user space is 16,776,704 bytes. If the data requested exceeds this maximum size, message CPF3CAA is issued. The user space contains accurate information for the number of buffers returned. To continue processing, create another user space and call the QSPGETSP API again with the new user space. Another alternative would be to return fewer buffers on each call to the QSPGETSP API.
Note: The size of the buffer (currently 512 or 4079 bytes) is determined by the buffer size of the existing spooled file being worked with. The spooled file buffer size is an attribute of the spooled file that can be returned using format SPLA0200 with the QUSRSPLA API.
The handle returned by the Open Spooled File (QSPOPNSP) API
The name of the user space that is to receive the buffer of spooled information. The first 10 characters contain the user space name and the second 10 characters contain the name of the library in which the user space is located. The special values allowed for the library name are *LIBL and *CURLIB. Both user space name and library name are left-justified. If no library is specified as the current library of the job, QGPL is used.
The format and the content of the information retrieved from each
buffer.
The possible values are:
| SPFR0100 | Information about the print data stored in the buffer. |
| SPFR0200 | Information about the print data stored in the buffer and the print data. |
| SPFR0300 | Print data for the buffer or multiple buffers. |
The buffer of the spooled file that is read first (or next).
Any number greater than zero is valid. When a specific buffer is requested, only that buffer is returned.
The following special value is supported for this parameter:
| -1 | Reads the next buffer in the spooled file. |
To read sequentially, starting at a specific buffer, the first API call should specify the specific buffer, with subsequent calls of the API specifying the special value -1 (read next). The first API call returns only the specific buffer requested. The subsequent read operations, with -1 specified for the next buffer, return the number of buffers specified on the open operation. When reading an entire spooled file, the special value -1 should be used.
Performance degradation could happen if a specific buffer is always used.
How to handle the situation where the spooled file has not been closed (by this job or another job) and the requested data has not yet been written by the application program.
The values supported for this parameter are:
| *WAIT | The API waits until the requested data is available or until the spooled file is closed. If the spooled file is closed without the requested data becoming available, the action defined by *ERROR is done. |
| *ERROR | The API returns either an error code or an error message based on what was specified for the error code parameter. |
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
The organization of the user space is dependent on the format (SPFR0100, SPFR0200, or SPFR0300) used.
Formats SPFR0100 and SPFR0200 shows the general structure of the user space for formats SPFR0100 and SPFR0200. If SPFR0100 is used, no print data is returned.
Format SPFR0300 shows the structure for format SPFR0300. If SPFR0300 is used, only the print data is returned, and print data for the buffers requested is returned in one print data section.
Offset values are calculated from the beginning of the user space.
The following table shows the generic header information returned for the SPFR0100, SPFR0200, and SPFR0300 formats.
For more details about the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(64) | Generic user area |
| 64 | 40 | BINARY(4) | Size of header |
| 68 | 44 | CHAR(4) | Structure level |
| 72 | 48 | CHAR(6) | Spooled file level |
| 78 | 4E | CHAR(8) | Format of the information returned |
| 86 | 56 | CHAR(1) | Information complete indicator |
| 87 | 57 | CHAR(1) | Reserved |
| 88 | 58 | BINARY(4) | Size of user space used |
| 92 | 5C | BINARY(4) | Offset to first buffer |
| 96 | 60 | BINARY(4) | Number of buffers requested |
| 100 | 64 | BINARY(4) | Number of buffers returned |
| 104 | 68 | BINARY(4) | Size of print data |
| 108 | 6C | BINARY(4) | Number of complete pages |
| 112 | 70 | BINARY(4) | Number of first page |
| 116 | 74 | BINARY(4) | Offset to first page |
| 120 | 78 | CHAR(8) | Reserved |
Format of the information returned. The SPFR0100, SPFR0200, or SPFR0300 format of the data present.
For input to the QSPPUTSP API, this field should contain SPFR0200.
Generic user area. Provided for the user's application program.
Information complete indicator. Used to indicate if all information requested has been supplied.
| I | Incomplete information. An interruption causes the user space to contain incomplete information about a buffer or buffers. The information for the last buffer is incomplete. |
| P | Partial and accurate information. Partial information is returned when the maximum user space was used and not all of the buffers requested were read. Information is complete for the number of buffers returned. |
| C | Complete and accurate information. All the buffers requested are read and returned. Complete also applies to the case where the end of file was reached on a closed spooled file, but the number of buffers requested was not reached. |
For input to the QSPPUTSP API, this field should contain a value of C or P.
Number of buffers requested. The number of buffer entries requested for each read operation.
This is the number specified on the open operation. However, if a specific buffer is requested by the read operation, this value is only one buffer.
Number of buffers returned. The number of buffer entries present in the user space.
As output from the QSPGETSP API, this number may be equal to or less than the number of buffers requested. The number may be less because the end of a closed spooled file is reached or the maximum user space has been used before the requested buffer count has been processed.
As input to the QSPPUTSP API, this is the number of buffer entries present in the user space. If this data is built by the user, rather than returned by the QSPGETSP API, the user should specify the proper number of buffer entries being provided to the QSPPUTSP API.
Number of complete pages. The number of complete pages contained in the print data.
This field is applicable to format SPFR0300 only.
Number of first page. The number of the first page in the print data section of format SPFR0300. The field is zero when no page is starting in the print data returned or when the format is SPFR0100 and SPFR0200.
Offset to first buffer. The location of the data for the first buffer returned. The offset value is from the beginning of the user space. For formats SPFR0100 and SPFR0200, this is the offset to the first buffer information section. For format SPFR0300, this is the offset to the print data section.
Offset to first page. The location of the data for the beginning of the first page in the print data section of format SPFR0300. This field is zero if the number of first page field is zero or the format is SPFR0100 or SPFR0200.
Reserved. Used to align a 4-byte boundary.
Size of header. The size of the header section, excluding the generic user area, of format SPFR0100, SPFR0200, or SPFR0300 in bytes.
Size of print data. The size of the print data of format SPFR0300 in bytes. This is zero for formats SPFR0100 and SPFR0200.
Size of user space used. The number of bytes used (returned) in the user space. This includes the generic header section, all buffer information sections, all general information sections, all page data sections, and all print data sections that are present in the user space.
Spooled file level. The level of the spooled file in Version, Release, Modification level format.
Structure level. The level of the structure of the user space. This should always be 0200.
The following buffer information is returned by the QSPGETSP API. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of all buffer information |
| 4 | 4 | BINARY(4) | Ordinal number of the buffer |
| 8 | 8 | BINARY(4) | Offset to general information section |
| 12 | C | BINARY(4) | Size of general information section |
| 16 | 10 | BINARY(4) | Offset to page data section |
| 20 | 14 | BINARY(4) | Size of page data section |
| 24 | 18 | BINARY(4) | Number of page entries |
| 28 | 1C | BINARY(4) | Size of page entry |
| 32 | 20 | BINARY(4) | Offset to print data section |
| 36 | 24 | BINARY(4) | Size of print data section |
Length of all buffer information. The size of all information pertaining to this buffer. This includes the sizes of the buffer information section, general information section, page data section, and print data section.
Number of page entries. The number of page entries in the page data section.
Offset to general information section. The location of the general information section. The offset value is from the beginning of the user space.
Offset to page data section. The location of the page data information section. The offset value is from the beginning of the user space.
Offset to print data section. The location of the print data section. The offset value is from the beginning of the user space.
Ordinal number of the buffer. The ordinal number of the buffer returned.
Size of general information section. The size of the general information section in bytes.
Size of page data section. The size of the page data section in bytes.
Size of page entry. The size of each page entry.
Size of print data section. The size of the print data section in bytes. This is zero (0) for format SPFR0100 because this format does not return this information. For data not previously spooled (creating as opposed to copying) the print data buffer section cannot exceed the size of the spooled file buffer minus the sum of the sizes of the following:
The general information section of formats SPFR0100 and SPFR0200 has the following structure.
For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Nonblank lines in buffer |
| 4 | 4 | BINARY(4) | Nonblank lines in first page |
| 8 | 8 | BINARY(4) | Buffer number of error information |
| 12 | C | BINARY(4) | Offset to error recovery information |
| 16 | 10 | BINARY(4) | Size of print data |
| 20 | 14 | CHAR(10) | State |
| 30 | 1E | CHAR(1) | Last page continues |
| 31 | 1F | CHAR(1) | Advanced print function file |
| 32 | 20 | CHAR(1) | LAC command array in buffer |
| 33 | 21 | CHAR(1) | Any buffer had LAC |
| 34 | 22 | CHAR(1) | Error recovery information contains LAC |
| 35 | 23 | CHAR(1) | Error recovery information |
| 36 | 24 | CHAR(1) | Zero pages |
| 37 | 25 | CHAR(1) | Load font |
| 38 | 26 | CHAR(1) | IPDS data |
| 39 | 27 | CHAR(5) | Reserved |
Format SPFR0200 is the format required by the Put Spooled File Data (QSPPUTSP) API. When a spooled file is being copied, the information is retrieved with the QSPGETSP API. When the spooled file is created by a user application, all information in the format must be accurately provided.
Advanced print function file. Whether this spooled file was created by the AFP Utilities for iSeries licensed program. The value is N if the device type is *SCS.
Any buffer had LAC. Whether any buffer had an SCS Load Alternate Characters (LAC) command since last error recovery information was saved. Specify Y for yes and N for no. This should be set to N for all spooled files with a DEVTYPE other than *SCS.
Buffer number of error information. The number of the buffer containing the error recovery information. This should be zero when there is no buffer containing error recovery information or for all spooled files with a device type other than SCS.
Error recovery information. Whether there is error recovery information in this buffer for SCS commands. This error recovery information allows a file to be repositioned and print only some pages of a file, making sure the characters print using the proper code point. Information on the proper code points is stored in LAC commands in the error recovery information. This information is stored for each page that contains SCS commands that can cause characters to print differently based on the code point specified. Specify Y for yes and N for no. This should be set to N for all spooled files with a device type other than SCS.
Error recovery information contains LAC. Error recovery information for SCS commands at the end of this page includes the LAC command found later in the buffer. Specify Y for yes and N for no. This should be set to N for all spooled files with a DEVTYPE other than SCS.
IPDS data. Whether the buffer contains IPDS data. Specify Y for yes and N for no. Buffers of IPDS data may exist in SCS spooled files.
LAC command array in buffer. An LAC command exists in this buffer. Specify Y for yes and N for no. This should be set to N for all spooled files with a DEVTYPE other than SCS.
Last page continues. The last page in this buffer continues in the next buffer when the value is Y.
Load font. Indicates whether a new load font equivalence entry was added to the table for this buffer. Specify Y for yes and N for no. This should be set to N for all spooled files with a device type other than IPDS.
Nonblank lines in buffer. The number of nonblank lines in the buffer.
Nonblank lines in first page. The number of nonblank lines in the first page ending in the buffer.
Offset to error recovery information. Offset to the error recovery information in this buffer. This field is 0 for all spooled files with a DEVTYPE other than SCS.
Reserved. Reserved for byte alignment.
Size of print data. The number of bytes of print data.
State. The state the buffer ends in if the data is IPDS.
| *HOME | Home state |
| *PAGE | Page state |
| *GRAPHICS | Graphics |
| *PAGETRANS | Page transparency |
| *HOMETRANS | Home transparency |
| blank | All non-IPDS files |
Zero pages. Whether there are zero (0) pages in the spooled file. Specify Y for yes and N for no.
Each entry of the page data section of format SPFR0100 and SPFR0200 has the following structure. For more details about the fields in the following table, see Field Descriptions.
Note: One page data section entry is returned for each page that starts in a returned buffer. The number of pages within a buffer may vary depending on their sizes. Therefore, the number of page data section entries may also vary from buffer to buffer.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Text data start |
| 4 | 4 | BINARY(4) | Any data start |
| 8 | 8 | BINARY(4) | Page offset |
Any data start. The number of the first line where user data can start on this page. This count includes all data to be printed.
Page offset. The location of the start of this page. The offset value is from the beginning of the print data.
Text data start. Number of the first line where user data can start on this page. This count includes text only.
The print data section of format SPFR0200 and SPFR0300 has the following structure. For more details about the fields in the following tables, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(*) | Print data |
Print data for format SPFR0300 contains all the print data for all of the buffers returned.
The format of the print text data is dependent on the printer device type.
For printer device types of *AFPDS, *AFPDSLINE, and *LINE, the data for a given format may span buffers. The first buffer returned will have one of the following formats:
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | Record format | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | CC | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | CC | Record format | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | TRC | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | CC | TRC | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | 5A | AFPDS data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | AFPDS data |
| 5A | AFPDS data |
| AFPDS data |
*AFPDSLINE spooled files must have control characters and lengths.
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | CC | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | 5A | AFPDS data |
*AFPDSLINE spooled files must have control characters and lengths.
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | CC | TRC | Line data |
| Original length | Trimmed length | Line number | DBCS flag | RSRVD | 5A | AFPDS data | |
For a printer device type of *IPDS, the buffer has the following format:
| IPDS data |
For information on the buffer format of printer device type SCS, as well as other device types, see the Printing topic.
AFPDS data. CHAR(*): A variable length field describing the
structured fields that reside in the data stream. See the
Data Stream and Object Architectures: Mixed Object Document Content Architecture Reference (MO:DCA Reference)
for a description of these structured fields. When the
length fields are present, only one structured field can be contained in the
AFPDS data.
CC. CHAR(1): Carriage control.
All codes are in hexadecimal notation. The carriage control characters control writing, spacing, and skipping operations as the data is being formatted. It may or may not precede the line data. See the Printing topic for further information on the valid carriage control codes.
When control characters exist, they can be one of two types: American National Standard printer control characters or machine control characters.
DBCS flag. CHAR(1): For DBCS files, whether this page starts in IGC mode. This is determined by the leftmost bit of this field. This should be zero for all lines except the first one on the page.
IPDS data. CHAR(*): A variable length field describing the
structured fields that reside in the data stream. See the
IPDS Reference for a description of these structures.
Line data. CHAR(*): A variable length character field composed of the actual characters to print.
Line number. BINARY(2): The line number this page starts on. This should be zero for all lines except the first one on the page.
Original length. BINARY(2): The original length of the record before trailing blanks were trimmed. This length does not include the first 8 bytes of the record.
Record format. CHAR(10): The name of the record format found in the page definition specified on the spooled file's page definition attribute that describes how the record of line data is to be formatted.
RSRVD. CHAR(1): Reserved field.
TRC. CHAR(1): A table-reference character.
All codes are in hexadecimal notation. A table-reference character selects a font to be used when printing the line. See the Printing topic for further information on the valid table reference codes and how they relate to the CHARS attributes and page definitions. If both CC and TRC are present, CC will be first and the TRC character will be second. The absence or presence of these characters is determined by the control character attribute and TRC attribute.
Trimmed length. BINARY(2): The actual or trimmed length of the record. This length does not include the first 8 bytes of the record.
5A. CHAR(1): A special hexadecimal constant used to indicate that a structured field follows.
Some restrictions apply as to where these record formats can appear in the buffer.
For other data types the print text format corresponds to the architecture for that data stream.
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CAA E | List is too large for user space &1. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF33DF E | Internal data area for opened spooled files destroyed. |
| CPF33D2 E | Spooled file handle not valid. |
| CPF33D3 E | Value &1 not valid for buffer to read parameter. |
| CPF33D4 E | Value &1 not valid for end of open file parameter. |
| CPF33D5 E | Spooled file not opened for operation requested. |
| CPF33D6 E | Buffer &1 not available. |
| CPF33D7 E | Requested number of buffers not returned. |
| CPF3330 E | Necessary resource not available. |
| CPF811A E | User space &4 in &9 damaged. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9846 E | Error while processing file &1 in library &2. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| Top | Print APIs | APIs by category |