Extract Writer Status (QSPEXTWI) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | 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 Extract Writer Status (QSPEXTWI) API is used by a driver program to access information about the writer, the spooled file the writer is processing, and to determine if the information for the spooled file has been changed. A call to this API should be made by a driver program after each buffer is sent to the printer.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Format name
- INPUT; CHAR(8)
The content and format of the writer information being returned.
You must specify one of the following:
EXTW0100 Contains the information about the writer and the spooled file it is processing.
- 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 at initialization time (the initialize option).
- Spooled file handle
- INPUT; CHAR(10)
The spooled file handle to the current file which is being processed by the writer. 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.
EXTW0100 Format
The following table shows the information returned for the EXTW0100 format. For more details about the fields in the following table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of additional copies |
| 12 | C | BINARY(4) | Reposition page number |
| 16 | 10 | CHAR(1) | Stop processing at page end |
| 17 | 11 | CHAR(1) | Stop processing at end of copy |
| 18 | 12 | CHAR(1) | Stop processing at page end, allow restart |
| 19 | 13 | CHAR(1) | Stop processing at end of copy, allow restart |
| 20 | 14 | CHAR(1) | Stop processing at page end, file was restarted |
| 21 | 15 | CHAR(1) | File held or deleted |
Field Descriptions
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned.
File held or deleted. The file has been held or deleted. This could have been the result of a user executing a Hold Spooled File (HLDSPLF) or Delete Spooled File (DLTSPLF) command while the file was active to the writer. This could also be the result of a user executing a Hold Writer (HLDWTR) command followed by executing a Release Writer (RLSWTR) command with the *BYPASS option, while the file was active to the writer.
Possible values are:
| 0 | The file has not been held or deleted. |
| 1 | The file has been held or deleted. |
Number of additional copies. The number of copies requested to be printed. It is possible that the user could change the number of copies to be printed using the Change Spooled File Attributes (CHGSPLFA) command. Therefore the driver program must check the current number of copies. This field has a range of values from 1 to 255. A special value of zero (0) is returned if the number of copies has not changed.
Reposition page number. The page where the writer is to reposition the file. This field is set when the writer is restarted and is used with the various stop processing flags.
Stop processing at end of copy. Stop processing the file at the end of the current copy. This can be set with an End Writer (ENDWTR) command with the controlled option (*CNTRLD) specified.
Possible values are:
| 0 | The writer has not been ended with the controlled option. |
| 1 | The writer has been ended with the controlled option. When this API is used within a print driver exit or writer transform exit program, the exit program should finish the current copy of the file and return. |
Stop processing at end of copy, allow restart. Stop processing the file at the end of the current copy. Allow printing to restart. This is set with the Hold Writer (HLDWTR) command with the controlled option (*CNTRLD) specified.
Possible values are:
| 0 | The writer has not been held with the controlled option. |
| 1 | The writer has been held with the controlled option. When this API is used within a print driver exit or writer transform exit program, the exit program should finish the current copy of the file and return. |
Stop processing at page end. Stop processing the file at the end of the current page. This can be set with an End Writer (ENDWTR) command with the page end option (*PAGEEND) specified.
Possible values are:
| 0 | The writer has not been ended with the page end option. |
| 1 | The writer has been ended with the page end option. When this API is used within a print driver exit or writer transform exit program, the exit program should finish the current page of the file and return. |
Stop processing at page end, allow restart. Stop processing the file at the end of the current page. Allow printing to restart. This is set with the Hold Writer (HLDWTR) command with the page end option (*PAGEEND) specified.
Possible values are:
| 0 | The writer has not been held with the page end option. |
| 1 | The writer has been held with the page end option. When this API is used within a print driver exit or writer transform exit program, the exit program should finish the current page of the file and return. |
Stop processing at page end, file was restarted. The file has restarted printing. It is possible that the user could restart printing the file (CHGSPLFA). Therefore, the print driver program must check the Reposition page number to determine where to restart printing.
Possible values are:
| 0 | The file has not restarted printing. |
| 1 | The file has started printing again. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable 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. |
| 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 ]