Set Writer Status (QSPSETWI) API

Required Parameter Group:

1	Status changes	Input	Char(*)
2	Length of status changes	Input	Binary(4)
3	Format name	Input	Char(8)
4	Writer handle	Input	Char(16)
5	Spooled file handle	Input	Char(10)
6	Error code	I/O	Char(*)

Default Public Authority: *USE

Threadsafe: No

The Set Writer Status (QSPSETWI) API is used by a driver exit program to update information about a spooled file that a writer is processing. This information is used on certain spooled file displays. For example, the Work with Spooled File (WRKSPLF) command displays the correct status, current page, and total copies information.

Authorities and Locks

Output queue lock: *EXCLRD
The lock is on the output queue on which the spooled file resides.

Required Parameter Group

Status changes

INPUT; CHAR(*)

The variable that contains the status information to be updated.

Length of status changes

INPUT; BINARY(4)

The length of the status information provided by the status changes parameter. The amount of data specified can be smaller than the information in the format. However, all the status information may not be set appropriately.

Format name

INPUT; CHAR(8)

The format of the file status changes.

SETW0100

Contains the information about the writer and the spooled file status information to be changed.

Writer handle

INPUT; CHAR(16)

The handle to the writer job. This handle is provided to the driver program on a writer call to the driver exit program during initialization.

Spooled file handle

INPUT; CHAR(10)

The spooled file handle of the current file for which the information is being set. This handle is provided to the driver program on a writer call to the driver exit program (using the process file option).

Error code

I/O; CHAR(*)

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

SETW0100 Format

The following table shows the information specified in the SETW0100 format. For more details about the fields in the following table, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(1)	Change status
1	1	CHAR(1)	Change current page
2	2	CHAR(1)	Change convert page
3	3	CHAR(1)	Change copies
4	4	CHAR(1)	Change accounting pages
5	5	CHAR(1)	Change accounting lines
6	6	CHAR(1)	Change accounting bytes
7	7	CHAR(5)	Reserved
12	C	BINARY(4)	Status
16	10	BINARY(4)	Current page
20	14	BINARY(4)	Convert page
24	18	BINARY(4)	Copies
28	1C	BINARY(4)	Number of pages for accounting
32	20	BINARY(4)	Number of lines for accounting
26	24	PACKED (15,0)	Number of bytes for accounting

Field Descriptions

Change accounting bytes. Change the number of bytes that have been processed for accounting purposes.

Possible values are:

0	Do not change the accounting bytes.
1	Change the number of bytes that have been processed for accounting to the value specified in the number of bytes for accounting field.

Change accounting lines. Change the number of lines that have been processed for accounting purposes.

Possible values are:

0	Do not change the accounting lines.
1	Change the number of lines that have been processed for accounting to the value specified in the number of lines for accounting field.

Change accounting pages. Change the number of pages that have been processed for accounting purposes.

Possible values are:

0	Do not change the accounting pages.
1	Change the number of pages that have been processed for accounting to the value specified in the number of pages for accounting field.

Change convert page. Change the number of pages that have been converted.

Possible values are:

0	Do not change the number of pages that have been converted.
1	Change the number of pages that have been converted to the value specified in the convert page field.

Change copies. Change the number of copies currently printing.

Possible values are:

0	Do not change the number of the copies being printed.
1	Change the number of the copies being printed to the value specified in the copies field.

Change current page. Change the current page that has just printed.

Possible values are:

0	Do not change the current page that has just printed.
1	Change the current page that has just printed to the value specified in the current page field.

Change status. Change the status of the spooled file being processed by the writer.

Possible values are:

0	Do not change the status of the spooled file.
1	Change the status of the spooled file to the value specified in the status field.

Copies. The current number of copies of the spooled file that have been processed by the driver program. The driver program should call this API with the current number of copies processed after the processing of each copy of the spooled file.

Convert page. The number of the pages that have been converted.

Current page. The number of the page that is being printed.

Number of bytes for accounting. The cumulative number of bytes to be logged for accounting.

Number of lines for accounting. The cumulative number of lines to be logged for accounting.

Number of pages for accounting. The cumulative number of pages to be logged for accounting.

Reserved. Field must be set to blank.

Status. The new status of the spooled file.

Possible values are:

1 (pending)	The spooled file is being converted.
2 (writing)	The spooled file is being selected by the writer.
3 (sending)	The spooled file is being sent to a remote system.
4 (printing)	The spooled file is being printed.
5 (separator)	The writer is printing separator pages.
6 (suspend)	The driver is still processing the file.
7 (interrupt)	The driver is done processing the file.
8 (ready)	The spooled file is ready for processing.
9 (held)	The spooled file has been held by the driver.
10 (sent)	The spooled file has been sent to a remote system.
11 (finished)	The driver is finished with the spooled file.

Notes:

The driver program should use 6 (suspend) when a Hold Writer (HLDWTR) command with option *PAGEEND or *CNTRLD has occurred, and the driver program wishes to continue processing the spooled file when the writer is released (RLSWTR).
The driver program should use 7 (interrupt) when an interruption of the driver program has occurred during the process file option (20) of the printer driver exit, and the driver program wishes to no longer continue processing the spooled file.

An example scenario using the suspend status:

The writer calls driver program with the process file (20) process option.
While the driver program is processing the file, a Hold Writer (HLDWTR) command is issued with option *PAGEEND or *CNTRLD. The driver program can periodically check for the holding of the writer using the Extract Writer Information (QSPEXTWI) API.
The driver program finishes processing the spooled file to the next end of page for the *PAGEEND option of the Hold Writer (HLDWTR) command, and finishes processing the current copy of the spooled file for the *CNTRLD option of the Hold Writer (HLDWTR) command.
The driver program then returns to the writer with the error code field of the option specific output information of the print driver exit set to 10.
The writer then calls the driver program with the hold writer (40) process option.
The driver program at this time uses the Set Writer Information (QSPSETWI) API to set the status of the spooled file to suspend. This indicates to the writer that the driver program wishes to continue processing the spooled file when the Release Writer (RLSWTR) command has been issued.
If a Release Writer (RLSWTR) command is issued, the writer will call the driver program with the reprocess file (21) process option.
The driver program can use the Extract Writer Information (QSPEXTWI) API to determine where to continue processing of the spooled file. At this time the driver program would update the status of the spooled file from suspended to whatever is appropriate.
Processing would continue as normal.

An example scenario using the interrupt status follows:

The writer calls the driver program with the initialize (10) process option.
The driver program performs whatever initialization and setup is needed before processing of spooled files begins. At this time the driver program decides to allow interrupts to occur while it is processing a spooled file. The driver program does this by setting the allow interrupt field in the option specific output information of the print driver exit interface to 1 before returning to the writer.
The writer then will call the driver program with the process file (20) process option when a spooled file becomes eligible for processing.
While the driver program is processing a spooled file, that spooled file is deleted using the Delete Spooled File (DLTSPLF) command, held using the Hold Spooled File (HLDSPLF) command, or a restart page is specified using the Change Spooled File Attributes (CHGSPLFA) command. Since the driver program allowed interrupts, the driver program loses control to the writer immediately.
The writer calls the driver program with the reprocess file (21) process option.
The driver program uses the Extract Writer Information (QSPEXTWI) API to determine whether a delete, hold, or restart page change has been executed.
The driver program, upon detecting that a hold or delete operation has occurred, then uses the Set Writer Information (QSPSETWI) API to set the status of the spooled file to interrupt and returns control back to the writer.
Processing would continue as normal.

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error while addressing parameter list.
CPF3CF1 E	Error code parameter not valid.
CPF3C1D E	Length specified in parameter &1 not valid.
CPF3C19 E	Error occurred with receiver variable specified.
CPF3C21 E	Format name &1 is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF33CC E	No writer found for specified handle &1.
CPF33CD E	No file found for specified handle &1.
CPF34CB E	Value not valid for field &1.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V3R7

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