Put Spooled File Data (QSPPUTSP) API

Required Parameter Group:

1	Spooled file handle	Input	Binary(4)
2	Qualified user space name	Input	Char(20)
3	Error code	I/O	Char(*)

Default Public Authority: *USE

Threadsafe: No

The Put Spooled File Data (QSPPUTSP) API puts data into a spooled file, which was created using the Create Spooled File (QSPCRTSP) API. The data put in the spooled file is taken from a user space. The data in the user space can be created using the Get Spooled File Data (QSPGETSP) API or can be created by a user application.

Before a buffer is put in a spooled file, a limited validity check is performed on the information in the user space for that buffer. The possible errors that result from the values of the fields in the user space can be classified as follows:

The value with an error can be substituted by the default value. A CPIxxxx message is issued informing the user of the substitution.
The value with an error causes a CPFxxxx message to be issued. The message is not issued until the validation of the information is complete or a severe error is encountered and validation cannot continue. This provides the caller with all informational messages as well as the first CPFxxxx message encountered.
The value with an error causes a CPFxxxx message to be issued immediately.

The buffers must be in the format returned by the Get Spooled File Data (QSPGETSP) API and be in format SPFR0200.

Authorities and Locks

User Space Authority: *CHANGE
Library Authority: *EXECUTE
User Space Lock: *EXCLRD

Required Parameter Group

Spooled file handle

INPUT; BINARY(4)

The handle returned by the QSPCRTSP API.

Qualified user space name

INPUT; CHAR(20)

The name of the user space that contains the buffer of spooled information. The first 10 characters contain the user space name, and the second 10 characters contains 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 entries are left-justified. If no library is specified as the current library of the job, QGPL is used. The format of the user space is the same as that returned by QSPGETSP API. The format specified must be SPFR0200.

To see the format of the user space and how the offset values are calculated, see Format of the User Space.

Error code

I/O; CHAR(*)

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

Considerations When Changing or Creating a User Space

When creating your own spooled files or altering the buffers returned by the QSPGETSP API, incorrect data can be put with the QSPPUTSP API. Although errors are caught by the QSPPUTSP API, not all errors are detected.

If the order of the pages, the number of pages, or the number of lines is incorrect, problems can occur when repositioning the spooled file to print it. Repositioning means trying to start printing at a specific page other than page 1. The problems can be caused by:

Using the restart printing function
Changing the starting and ending print pages
Working with an inquiry error message that allows a user to specify what page of the spooled file to restart printing

There are fields in the buffer section of the user space that, if they contain incorrect values, could cause other functions, such as displaying or copying of spooled files, to work incorrectly. These fields are in the general information section and in the page data section.

Fields in the General Information Section

If the state and IPDS™ data fields contain incorrect or changed values, the Display Spooled File (DSPSPLF) and Copy Spooled File (CPYSPLF) commands can be affected in the following ways:

State field
When this field is set to *HOMETRANS or *PAGETRANS, it indicates that the spooled file contains only IPDS transparent data. This field only affects spooled files with a device type of *IPDS.

A changed or incorrect state field value causes the DSPSPLF and CPYSPLF commands to work the following way:
- DSPSPLF command
  IPDS transparent data cannot be displayed by the DSPSPLF command. As a result, when the created spooled file is displayed, the data in the buffer with the state field set to *HOMETRANS or *PAGETRANS is not displayed. Furthermore, message CPI3438 (Intelligent Printer Data Stream™ (IPDS) data not displayed) appears. If the spooled file is made up entirely of buffers with the state field set to *HOMETRANS or *PAGETRANS, the spooled file is not displayed. Message CPF3429 (File cannot be displayed or copied) is displayed.
- CPYSPLF command
  IPDS transparent data cannot be copied by the CPYSPLF command. If some buffers of a spooled file have a state field set to *HOMETRANS or *PAGETRANS, those buffers are not copied to the database member. If the spooled file is made up entirely of buffers with the state field set to *HOMETRANS or *PAGETRANS, the spooled file is not copied. Message CPF3429 (File cannot be displayed or copied) is displayed.
IPDS data field
When this field is set to Y, it indicates that the buffer contains only IPDS data. This field only affects spooled files with a device type of *SCS.

A changed or incorrect IPDS data field value causes the DSPSPLF and CPYSPLF commands to work the following way:
- DSPSPLF command
  IPDS data cannot be displayed using the DSPSPLF command. As a result, when a created spooled file is displayed, the data in the buffer with the IPDS data field set to Y is not displayed. Furthermore, message CPI3437 (Intelligent printer data stream (IPDS) data not displayed) appears at the bottom of the last screen of the DSPSPLF command. If the spooled file is made up entirely of buffers with the IPDS field set to Y, the spooled file is not displayed. Message CPF3429 (File cannot be displayed or copied) is displayed.
- CPYSPLF command
  IPDS data cannot be copied by using the CPYSPLF command. As a result, when a spooled file is copied into the database member, the data in the buffer with the IPDS data field set to Y is not copied. If the spooled file is made up entirely of buffers with the IPDS field set to Y, the spooled file is not copied. Message CPF3429 (File cannot be displayed or copied) is displayed.

Fields in the Page Data Section

If the text data start and page offset fields contain incorrect or changed values, the Display Spooled File (DSPSPLF) command can be affected in the following ways:

Text data start
The number of the first line where user data can start on the page. This count includes text only. The text data start field can have an incorrect value when the buffers of the original spooled file are put in the created spooled file in an order other than the original spooled file. This field can also have an incorrect value by simply changing its value to another value higher or lower than was returned when the data was retrieved using the QSPGETSP API. This field affects all device types of spooled files.

A changed or incorrect value for the text data start field causes the DSPSPLF command to work the following way:
- DSPSPLF command
  When the text data start field contains an incorrect value, DSPSPLF may issue message CPF33F9 (Error occurred while displaying file X number Y) when attempting to find a particular string in the displayed spooled file. Also, the user is able to see only part of the spooled file. The amount of data the user sees depends on the order the buffers were put. For example, if the first buffer of the original spooled file is the last buffer in the created spooled file, the user only sees the pages in the first buffer of the created spooled file. If the second buffer of the original spooled file was the last buffer in the created spooled file, the user sees the pages in the first and second buffer of the created spooled file. The other buffers are there but not displayed.
Page offset
The location of the start of this page. The offset value is from the beginning of the print data. This field affects all device types of spooled files.

A changed or incorrect value for the page offset field causes the DSPSPLF command to work the following way:
- DSPSPLF command
  When the page offset field contains an incorrect value, DSPSPLF may issue informational message CPI3431 (Line number adjusted). The page information of the individual pages overlaps. The user sees only part of the spooled file because some pages overlap.

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error while addressing parameter list.
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.
CPF33D5 E	Spooled file not opened for operation requested.
CPF33F2 E	New page expected at beginning of buffer &1.
CPF33F3 E	Data in buffer &1 exceeds spooled file buffer size.
CPF33F4 E	Beyond end of user space &1 in library &2.
CPF33F6 E	Value in generic header of user space &4 in library &5 not valid.
CPF33F7 E	Value in buffer &6 of user space &4 in library &5 not valid.
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.

API introduced: V2R1

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