Retrieve Output Information (QWSRTVOI) API

The Retrieve Output Information (QWSRTVOI) API gives the caller information on either the last active record format involved in an output operation to the requester device for the specified job or all the active record formats currently displayed on the requester device for the specified job.

Authorities and Locks

Job Authority

*JOBCTL if the job for which information is retrieved has a different user profile from that of the job that calls the QWSRTVOI API.

Device Authority

*READ authority to the display device that the interactive job is using as the *REQUESTER device.

File Authority

*READ authority to the display file that is active currently.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable 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. If this value is larger than the actual size of the receiver variable, the result may not be predictable. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The content and format of the information returned for the job. The following format names can be specified:

OINF0100	Display file and last record format name involved in an output operation.
OINF0200	Display file and a list of active records currently on the display.

For more information, see OINF0100 Format or OINF0200 Format.

Qualified job name

INPUT; CHAR(26)

The name of the job for which information is to be returned. The qualified job name has three parts:

Job name	CHAR(10). A specific job name or one of the following special values: * The job in which this program is running. The rest of the qualified job name parameter must be blank. *INT The internal job identifier locates the job. The user name and job number must be blank.
User name	CHAR(10). A specific user profile name, or blanks when the job name is a special value or *INT.
Job number	CHAR(6). A specific job number, or blanks when the job name specified is a special value or *INT.

Internal job identifier

INPUT; CHAR(16)

The internal identifier for the job. The List Job (QUSLJOB) API creates this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.

Error code

I/O; CHAR(*)

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

OINF0100 Format

OINF0200 Format

Field Descriptions

The following internal record names may be returned:

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.

Display file library name. The name of the library that contains the display file.

Display file name. The name of the display file. The user interface manager (UIM) panel groups generate a user-defined data stream through a display file. The name of the display file (such as QDUI80 or QDUI132) is returned, not the panel group. If format OINF0200 is being used, the record format type for a UIM panel is *USRDFN.

Display file record format name. The name of the record format used from the display file.

End row. Ending row of the record format.

Number of active record formats. The number of currently active record formats for the given file. This number is used to determine the size of the list of active record formats array. The maximum number of active records is 25.

Offset to the list of active record formats. An offset from the beginning of format OINF0200 to the list of active record formats.

Record format type. The type of the record format. Blanks are returned in this field if the record format has no special type. Otherwise, one of the following is returned:

If a window is active on the display, any previously written records are inactive. The window definition record is active, as are any records written "in" the window. Non-window definition records active in the window are records with the WINDOW keyword with a parameter that names the window definition record format; these are window reference records. Reported for an active window are:

• An entry that names the window definition record and for which the the start row, end row, start column and end column define the positions of the window's borders on the display. This is the only entry which has a format type of "*WINDOW".
  
  
• Another entry with the same record name, if the window definition record contains fields. Only the start row and end row are non-zero in this entry. The start row and end row are the actual rows on the display that the record's fields occupy.
  
  
• Any additional records that are active in the window, with their actual start row and end row positions.

If a window is active, the sub-file for the ERRSFL keyword (if present in the DDS) is not active.

Size of an active record format entry. The size of one of the repeating entries in the active records format information.

Start row. Starting row of the record format.

Window end column. If the record format type is *WINDOW, this is the ending column of the window record. For all other record format types, this field is zero.

Window start column. If the record format type is *WINDOW, this is the starting column of the window record. For all other record format types, this field is zero.

Error Messages