Get Spooled File Data (QSPGETSP) API


  Required Parameter Group:


  Default Public Authority: *USE

  Threadsafe: No

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.


Authorities and Locks

User Space Authority
*CHANGE
Library Authority
*EXECUTE
Output Queue Authority
*USE
User Space Lock
*EXCLRD

Required Parameter Group

Spooled file handle
INPUT; BINARY(4)

The handle returned by the Open Spooled File (QSPOPNSP) API

Qualified user space name
INPUT; CHAR(20)

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.

Format name
INPUT; CHAR(8)

The format and the content of the information retrieved from each buffer.
The possible values are:


Ordinal number of buffer to be read
INPUT; BINARY(4)

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:


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.

End of open spooled file
INPUT; CHAR(10)

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:


Error code
I/O; CHAR(*)

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


Format of the User Space

The organization of the user space is dependent on the format (SPFR0100, SPFR0200, or SPFR0300) used.

Formats SPFR0100 and SPFR0200 show 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.

Formats SPFR0100 and SPFR0200

Format SPFR0300

Format SPFR0300


Generic Header Section

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.



Field Descriptions

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.


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.


Buffer Information Section

The following buffer information is returned by the QSPGETSP API. For more details about the fields in the following table, see Field Descriptions.



Field Descriptions

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:


General Information Section

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.



Field Descriptions

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 IBM® Advanced Function Printing™ Utilities 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 about 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.


Zero pages. Whether there are zero (0) pages in the spooled file. Specify Y for yes and N for no.


Page Data Section

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.



Field Descriptions

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.


Print Data Section

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.

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:

For a printer device type of *IPDS, the buffer has the following format:

For information about the buffer format of printer device type SCS, as well as other device types, see the Printing topic collections.


Field Descriptions

AFPDS data. CHAR(*): A variable length field describing the structured fields that reside in the data stream. See the Data Stream and Object Architectures: MO:DCA™ Reference manual, SC31-6802, for a description of these structured fields. This manual is available from the IBM Publications CenterLink outside information center. 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 collections for further information about 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 manual, S544-3417, for a description of these structures. This manual is available from the IBM Publications CenterLink outside information center.

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 collections for further information about 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.


Restrictions for Print Data Section

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.


Error Messages



API introduced: V2R1

[ Back to top | >Print APIs | APIs by category ]