Retrieve Output Queue Information (QSPROUTQ) API


  Required Parameter Group:

1 Receiver variable Output Char(*)
2 Length of receiver variable Input Binary(4)
3 Format name Input Char(8)
4 Qualified output queue name Input Char(20)
5 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

The Retrieve Output Queue Information (QSPROUTQ) API returns information about the parameters used to create the queue, the current status of the queue, and the number of entries on the queue.


Authorities and Locks

Output Queue Library Authority
The caller needs *EXECUTE authority to the output queue library.
Output Queue Authority
The caller needs one of the following:
Output Queue Lock
This API needs an *EXCLRD lock on the output queue.

Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The variable that receives the information requested.


Length of receiver variable
INPUT; BINARY(4)

The length of the receiver variable provided by the receiver variable parameter. The amount of data returned is truncated if the receiver variable is too small. A length of less than 8 is not valid. If the length specified is greater than the actual length, the results may be unpredictable.

Format name
INPUT; CHAR(8)

The content and format of the queue information being returned.

You must specify one of the following:

OUTQ0100 Contains the basic information about the output queue and only one of the writers that is started to the queue.
OUTQ0200 Contains the basic information about the output queue and all of the writers that are started to the queue.

Qualified output queue name
INPUT; CHAR(20)

The name of the output queue for which information is returned. The first 10 characters contain the queue name and the second 10 characters contain the name of the library in which the queue resides.

The following special values are supported for the library name:

*LIBL The library list used to locate the queue.
*CURLIB The current library for the job is used to locate the queue.

Error code
I/O; CHAR(*)

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


OUTQ0100 Format

The following table shows the information returned for the OUTQ0100 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 CHAR(10) Output queue name
18 12 CHAR(10) Output queue library name
28 1C CHAR(10) Order of files on queue
38 26 CHAR(10) Display any file
48 30 BINARY(4) Job separators
52 34 CHAR(10) Operator controlled
62 3E CHAR(10) Data queue name
72 48 CHAR(10) Data queue library name
82 52 CHAR(10) Authority to check
92 5C BINARY(4) Number of files
96 60 CHAR(10) Output queue status
106 6A CHAR(10) Writer job name
116 74 CHAR(10) Writer job user name
126 7E CHAR(6) Writer job number
132 84 CHAR(10) Writer job status
142 8E CHAR(10) Printer device name
152 98 CHAR(50) Text description
202 CA CHAR(2) Reserved
204 CC BINARY(4) Number of spooled file pages specified
208 D0 BINARY(4) Number of writers started to queue
212 D4 BINARY(4) Writers to autostart
216 D8 CHAR(1) Remote system name type
217 D9 CHAR(255) Remote system name
472 1D8 CHAR(128) Remote printer queue
600 258 CHAR(10) Message queue name
610 262 CHAR(10) Message queue library name
620 26C BINARY(4) Connection type
624 270 BINARY(4) Destination type
628 274 CHAR(1) VM/MVS class
629 275 CHAR(8) Forms control buffer
637 27D CHAR(1) Host print transform
638 27E CHAR(17) Manufacturer type and model
655 28F CHAR(10) Workstation customizing object name
665 299 CHAR(10) Workstation customizing object library name
675 2A3 CHAR(1) Spooled file auxiliary storage pool attribute
676 2A4 BINARY(4) Offset to maximum spooled file page entries
680 2A8 BINARY(4) Number of page entries returned
684 2AC BINARY(4) Length of each size entry
688 2B0 CHAR(128) Destination options
816 330 CHAR(1) Writer type started to queue
817 331 CHAR(1) Print separator page
818 332 CHAR(255) Long remote printer queue
1073 431 CHAR(10) Image configuration
1083 43B CHAR(10) Image configuration library
1093 445 CHAR(1) Network directory publishing status
1094 446 CHAR(2) Reserved
1096 448 BINARY(4) Spooled file auxiliary storage pool ID
1100 44C CHAR(10) Spooled file auxiliary storage pool device name
    CHAR(*) Spooled file maximum page entries


OUTQ0200 Format

The following table shows the information returned for the OUTQ0200 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 CHAR(10) Output queue name
18 12 CHAR(10) Output queue library name
28 1C CHAR(10) Order of files on queue
38 26 CHAR(10) Display any file
48 30 BINARY(4) Job separators
52 34 CHAR(10) Operator controlled
62 3E CHAR(10) Data queue name
72 48 CHAR(10) Data queue library name
82 52 CHAR(10) Authority to check
92 5C BINARY(4) Number of files
96 60 CHAR(10) Output queue status
106 6A CHAR(50) Text description
156 9C BINARY(4) Number of spooled file pages specified
160 A0 BINARY(4) Number of writers started to queue
164 A4 BINARY(4) Writers to autostart
168 A8 CHAR(1) Remote system name type
169 A9 CHAR(255) Remote system name
424 1A8 CHAR(128) Remote printer queue
552 228 CHAR(10) Message queue name
562 232 CHAR(10) Message queue library name
572 23C BINARY(4) Connection type
576 240 BINARY(4) Destination type
580 244 CHAR(1) VM/MVS class
581 245 CHAR(8) Forms control buffer
589 24D CHAR(1) Host print transform
590 24E CHAR(17) Manufacturer type and model
607 25F CHAR(10) Workstation customizing object name
617 269 CHAR(10) Workstation customizing object library name
627 273 CHAR(1) Spooled file auxiliary storage pool attribute
628 274 BINARY(4) Offset to maximum spooled file page entries
632 278 BINARY(4) Number of page entries returned
636 27C BINARY(4) Length of each size entry
640 280 BINARY(4) Offset to writer entries
644 284 BINARY(4) Number of writer entries returned
648 288 BINARY(4) Length of each writer entry
652 28C CHAR(128) Destination options
780 30C CHAR(1) Writer type started to queue
781 30D CHAR(1) Print separator page
782 30E CHAR(255) Long remote printer queue
1037 40D CHAR(3) Reserved
1040 410 BINARY(4) Offset to user-defined options
1044 414 BINARY(4) Number of user-defined options returned
1048 418 BINARY(4) Length of each user-defined option entry
1052 41C BINARY(4) Offset to user-defined data
1056 420 BINARY(4) Bytes of user-defined data returned
1060 424 BINARY(4) Bytes of user-defined data available
1064 428 CHAR(10) User-defined object name
1074 432 CHAR(10) User-defined object library name
1084 43C CHAR(10) User object type
1094 446 CHAR(10) User driver program name
1104 450 CHAR(10) User driver program library name
1114 45A CHAR(10) Data transform program name
1124 464 CHAR(10) Data transform program library name
1134 46E CHAR(10) Image configuration
1144 478 CHAR(10) Image configuration library
1154 482 CHAR(1) Network directory publishing status
1155 483 CHAR(1) Reserved
1156 484 BINARY(4) Spooled file auxiliary storage pool ID
1160 488 CHAR(10) Spooled file auxiliary storage pool device name
    CHAR(*) Spooled file maximum page entries
    CHAR(*) Writer entries
    CHAR(*) User-defined option entries
    CHAR(*) User-defined data


Format of Spooled File Maximum Page Entry

Each spooled file size entry 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) Number of pages
4 4 CHAR(8) Starting time
12 C CHAR(8) Ending time


Format of Writer Entry

Each writer entry from format OUTQ0200 has the following structure. For more details about the fields in the following table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 CHAR(10) Writer job name
10 A CHAR(10) Writer job user name
20 14 CHAR(6) Writer job number
26 1A CHAR(10) Writer job status
36 24 CHAR(10) Printer device name


Format of User-Defined Option Entry

Each user-defined option entry has the following structure. For more details about the fields in the following table, see Field Descriptions.

Offset Type Field
Dec Hex
0 0 CHAR(10) User-defined option


Field Descriptions

Authority to check. Indicates what type of authorities to the output queue allow the user to control all the files on the queue.

The possible values are:

*OWNER Only the owner of the output queue can control all the output files on the queue.
*DTAAUT Any user with *READ, *ADD, or *DELETE authority to the output queue can control all output files on the queue.

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.

Bytes of user-defined data available. The number of bytes of user-defined data available to be returned. All available data is returned if enough space is provided.

Bytes of user-defined data returned. The number of bytes of user-defined data returned.

Connection type. The type of network connection to the remote system.

Values include:

0 The destination type is not specified when the remote system is *NONE.
1 The SNADS network is used as the connectivity to the remote system.
2 The TCP/IP network is used as the connectivity to the remote system.
3 The IPX network is used as the connectivity to the remote system. This value is no longer supported by ISeries 400.
4 Reserved.
5 A user-defined connectivity is used as the connectivity to the remote system.

Data queue library name. The name of the library that contains the data queue.

Data queue name. Name of the data queue associated with this output queue. Whenever a spooled file goes into ready status on the output queue, an entry is placed on the data queue.

*NONE No data queue is associated with this output queue.

Data transform program library name. The name of the library that contains the data transform program.

*LIBL The library list used to locate the data transform program.
*CURLIB The current library for the job is used to locate the data transform program.

Data transform program name. The name of the user-specified data transform program that is used by the driver program.

The following values are supported:

*NONE No data transform program is specified.
Data transform program name The name of the data transform program.

Destination options. Destination-dependent options that are specific to a particular implementation of an LPR Print Server.

The possible values are:

*NONE No destination-dependent options have been specified.
*NOWAIT The remote writer will not wait for confirmation that the destination system has finished processing the spooled file. This value is used only when the connection type is *IP and the destination type is *NDS or *SNA.
*USRDFNTXT Use the value for the user-defined text of the user profile when the spooled file was created.
destination options The destination-dependent options specified on the output queue.
blank This field is blank when the connection type is 0 (*NONE) or when the connection type is 1 (*SNA).

Destination type. The type of destination system that spooled files on this output queue are being sent to.

The possible values are:

0 The destination type is not specified when the remote system is *NONE.
1 The destination system is an iSeries server.
2 The destination system is an iSeries server running i5/OS (OS/400) version 2.
3 This destination system is a System/390 system.
4 The destination system is a PC using Print Services Facility/2.
5 Reserved.
6 The destination system is accessed with NETWARE3**. This value is no longer supported by ISeries 400.
7 The destination system is accessed with NETWARE4**.
-1 The destination system is not a system matching any of the other special values.

Display any file. Whether users who have authority to read this output queue can display the output data of any output file on this queue, or only the data in their own files.

*YES Any user having authority to read the queue can display, copy, or send the data of any file on the queue.
*NO Users authorized to use the queue can display, copy, or send the output data of their own files only, unless they have some special authority.
*OWNER Only the owner of a file or a user with *SPLCTL authority can display, copy, send, or move their own spooled files to another output queue.

Ending time. The ending time portion of the maximum spooled file page entry. It specifies the time of day that the maximum spooled file page is to end. The ending time is given in 24-hour format with a time separator (hh:mm:ss), where hh equals hours, mm equals minutes, and ss equals seconds.

Forms control buffer. The forms control buffer for files sent to a VM/MVS host system.

Note: This information is valid only when the connection type is 1 and the destination type is 3.

*NONE No FCB is used when sending spooled files.
*USRDTA The first 8 characters of the user data (USRDATA) spooled file attribute determine the name of the FCB. If the user data is blank, no FCB is used.
*PRTF The first 8 characters of the printer file used to spool the file determine the name of the FCB.
FCB-name The name of the FCB to be used.

Host print transform. Whether to use the host print transform function to transform a spooled file. This field was previously called transform SCS to ASCII.

Values are:

blank Used when the connection type is 1 (*SNA) and the user driver program is *NONE.
0 Do not transform data streams using host print transform.
1 Transform data streams using host print transform.

Image configuration. The transform services for a variety of image and print data-stream formats. (See the IMGCFG keyword in the Communications Configuration Link to PDF book.)

*NONE No image configuration is used when transforming the spooled file before sending.
Image-configuration-name The name of the image configuration.

Image configuration library. The library in which the image configuration is located. This field is always set to blanks.

Job separators. The number of job separators to be placed at the beginning of the output for each job having spooled file entries on this output queue.

0-9 The desired number of job separators.
-2 No job separators are used; instead a message is sent to the writer's message queue at the end of each job indicating that the output can be removed.

Length of each size entry. The length, in bytes, of each spooled file size entry.

Length of each user-defined option entry. The length, in bytes, of each user-defined option entry.

Length of each writer entry. The length, in bytes, of each writer entry.

Length of user-defined data. The length, in bytes, of the user-defined data.

Long remote printer queue. The name of the remote printer.

Possible values include:

*USER The user profile that creates the spooled file will determine the user ID on the remote system that it is sent to.
*SYSTEM The default system printer on the remote system will determine the printer queue.
printer queue name The name of the printer queue to which the remote writer will send files on the remote system.
blank The name of the printer queue will be blank for output queues that are not remote output queues.

Manufacturer type and model. The manufacturer, type, and model for a printer using the host print transform function.

*IBM42011 The IBM 4201-1 Proprinter printer is used.
*WSCST The workstation customizing object is used.
blank Used when the connection type is 1(*SNA), or when the connection type is 2(*IP) and the host print transform is 0.

Message queue library name. The library of the message queue.

Message queue name. The name of the message queue to which messages, created by the remote writer started to this output queue, are sent.

message queue name The message queue to which messages are to be sent.
blank The message queue is blank when the output queue is not a remote output queue.

Network directory publishing status. Whether the output queue is published in the network directory.

Possible values include:

0 Output queue is not published
1 Output queue is published

Number of files. The number of spooled files that exist on the output queue.

Number of pages. Only files with this number of pages or less will print between the starting and ending times.

Number of spooled file pages specified. In a spooled file, the maximum number of pages allowed on the output queue as determined by the output queue definition from the Create Output Queue (CRTOUTQ) command.

Number of page entries returned. The number of maximum spooled file page entries returned in this format. Only complete entries will be returned.

Number of user-defined options returned. The number of user-defined option entries returned in this format. Only complete entries are returned.

Number of writer entries returned. The number of writer entries returned in this format. Depending on the bytes available, this could be less than the number of writers started. Only complete entries will be returned.

Number of writers started to queue. The number of printer writers that have been started to this output queue.

Offset to maximum spooled file page entries. The offset to the maximum spooled file page entry. A maximum spooled file page entry specifies the requirements a spooled file must meet to be printed from the output queue. The maximum number of pages, the starting time, and the ending time define these requirements.

Offset to user-defined data. The offset to information about the user-defined data.

Offset to user-defined options. The offset to information about each user-defined option entry. Each entry contains the user-defined option.

Offset to writer entries. The offset to information about each writer that is started to the output queue. Each entry contains the writer job name, writer job user name, writer job number, writer job status, and printer device name.

Operator controlled. Whether users with job control authority are allowed to manage or control the files on this queue. Users have job control authority if SPCAUT(*JOBCTL) is specified in their user profile.

The possible values are:

*YES Users with job control authority can control the queue and make changes to the files on the queue.
*NO This queue and its entries cannot be controlled or changed by users with job control authority unless they also have some other special authority.

Order of files on queue. The order of the spooled files on the output queue.

The possible values are:

*FIFO The queue is first-in first-out for each file. That is, on the queue, new spooled files are placed after all other spooled files that have the same priority.
*JOBNBR The queue entries for the spooled files are sorted in priority sequence using the job number (the date and time that the job entered the system) of the job that created the spooled file.

Output queue library name. The name of the library that contains the output queue.

Output queue name. The name of the output queue.

Output queue status. The status of the output queue.

The status may be one of the following values:

RELEASED The queue is released.
HELD The queue is held.

Printer device name. The name of the printer device.

For format OUTQ0100 the following applies:

Print separator page. Whether to print a separator page when printing the spooled file on the remote system.

Possible values include:

blank The connection type is neither 2 (*IP) nor 5 (*USRDFN).
0 Do not print a separator page.
1 Print a separator page.

Remote printer queue. The name of the remote printer.

Possible values include:

*USER The user profile that creates the spooled file will determine the user ID on the remote system that it is sent to.
*SYSTEM The default system printer on the remote system will determine the printer queue.
printer queue name The name of the printer queue to which the remote writer will send files on the remote system.
blank The name of the printer queue will be blank for output queues that are not remote output queues. This field will also be blank if the name of the printer queue will not fit in 128 bytes.

Remote system name. The name of the remote system. The format of the name is dependent on the name type. When the remote system name type is 0 (*NONE) or 1 (*PASTHR), the remote system name is blank. When the name type is 2 (system name), the remote system name is up to 255 characters. When the name type is 3 (Internet address), the remote system name is a 15-character address in the form nnn.nnn.nnn.nnn, and the remaining characters are blank.

Remote system name type. The type of remote system name.

Valid values are:

0 There is no remote system name specified
1 The output is routed to the system from where the pass-through was issued (*PASTHR).
2 The name of the remote system.
3 Internet address

Reserved. An ignored field.

Spooled file auxiliary storage pool attribute. The auxiliary storage pool (ASP) where the spooled files are to reside.

The possible values are:

0 *SYSTEM: The spooled files reside in the system auxiliary storage pool.
1 *OUTQASP: The spooled files reside in the auxiliary storage pool in which the output queue resides.

Spooled file auxiliary storage pool device name. The name of the auxiliary storage pool (ASP) device where the spooled files reside.

The possible values are:

*SYSBAS The spooled files reside in the system ASP (ASP 1) or one of the defined basic user ASPs (ASPs 2-32).
auxiliary storage pool device name The name of the auxiliary storage pool device where the spooled files reside.

Spooled file auxiliary storage pool ID. The number of the auxiliary storage pool (ASP) where the spooled files reside.

The possible values are:

1 *SYSTEM: The spooled files reside in the system auxiliary storage pool.
2-255 The number of the auxiliary storage pool where the spooled files reside.

Spooled file maximum page entries. One maximum page entry is returned for each spooled file maximum page entry defined in the output queue. The number of entries may vary from one output queue to another. See Format of Spooled File Maximum Page Entry for the format of each entry.

Starting time. The starting time portion of the maximum spooled file page array. The starting time is given in 24-hour format with a time separator (hh:mm:ss), where hh equals hours, mm equals minutes, and ss equals seconds.

Text description. Text that briefly describes the output queue.

*BLANK There is no text description of the job queue.

User-defined data. Data defined by the user to be used by user applications or user-specified programs that process spooled files.

User-defined object library name. The name of the library that contains the user-defined object.

*LIBL The library list used to locate the user-defined object.
*CURLIB The current library for the job is used to locate the user-defined object.

User-defined object name. The name of the user-defined object that is used by user applications or user-specified programs that process spooled files.

The following values are supported:

*NONE No user-defined object is specified.
User-defined object name The name of the object defined by the user.

User-defined option. The option defined by the user to be used by user applications or user-specified programs that process spooled files. When the number of user-defined options returned is 0, there are no user-defined options.

User-defined option entries. One entry is returned for each user-defined option. The number of entries may vary from one output queue to another. See Format of User-Defined Option Entry for the format of each entry.

User driver program library name. The name of the library that contains the user driver program.

*LIBL The library list used to locate the user driver program.
*CURLIB The current library for the job is used to locate the user driver program.

User driver program name. The name of the user-specified driver program that is used to process the spooled files on the output queue.

The following values are supported:

*NONE No user driver program is specified.
User driver program name The name of the user-specified driver program.

User object type. The type of the user-defined object.

The following values are supported:

User object type The user object type can be data area (*DTAARA), data queue (*DTAQ), file (*FILE), PSF configuration object (*PSFCFG), user index (*USRIDX), user queue (*USRQ), and user space (*USRSPC).

Note: A blank value is returned when the name of the user-defined object is *NONE.

VM/MVS class. The VM/MVS SYSOUT class for distributions sent to a VM host system or to a MVS host system.

Possible values are:

A-Z, 0-9 The distribution class.
blank Used when the connection type is 1(*SNA).

Workstation customizing object library name. The library name for the workstation customizing object. This field is blank when the connection type is 1(*SNA) and the user driver program is *NONE.

Workstation customizing object name. The name of an object that consists of a table of attributes used to customize a given ASCII device.

Possible values are:

*NONE There is no workstation customizing object.
name The name of the workstation customizing object, which has been created by the Create Work Station Customizing Object (CRTWSCST) command.
blank Used when the connection type is 1(*SNA) and the user driver program is *NONE.

Writer entries. One writer entry is returned for each writer that is started to the output queue. The number of writer entries may vary from one output queue to another. See Format of Writer Entry for the format of each entry.

Writer job name. The name of the writer job.

The following applies:

Writer job number. The job number associated with the writer job.

The following applies:

Writer job status. The status of the writer job.

The following applies:

The status may be one of the following values.

STR The writer job is started to the output queue.
END The writer job is ended.
JOBQ The writer job is on the job queue
HLD The writer job is held.
MSGW The writer job is waiting for a message.

Writer job user name. The name of the user who started the writer job.

The following applies:

Writers to autostart. The number of remote printer writers to autostart to this output queue at system IPL.

Possible values are:

0 No writers are automatically started to this output queue.
number of writers The number of writers automatically started to this output queue.

Writer type started to queue. The type of writer started to this output queue.

Possible values are:

0 Printer writer
1 Diskette writer
2 Remote writer


Error Messages

Message ID Error Message Text
CPF2207 E Not authorized to use object &1 in library &3 type *&2.
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.
CPF3330 E Necessary resource not available.
CPF3357 E Output queue &1 in library &2 not found.
CPF8122 E &8 damage on library &4.
CPF9872 E Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V2R2
Top | Print APIs | APIs by category