Retrieve Output Information (QWSRTVOI) 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 job name | Input | Char(26) |
5 | Internal job identifier | Input | Char(16) |
6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
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
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Bytes returned |
4 | 4 | BINARY(4) | Bytes available |
8 | 8 | CHAR(10) | Display file name |
18 | 12 | CHAR(10) | Display file library name |
28 | 1C | CHAR(10) | Display file record format name |
OINF0200 Format
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | BINARY(4) | Bytes returned |
4 | 4 | BINARY(4) | Bytes available |
8 | 8 | BINARY(4) | Offset to the list of active record formats |
12 | C | BINARY(4) | Number of active record formats |
16 | 10 | BINARY(4) | Size of an active record format entry |
20 | 14 | CHAR(10) | Display file name |
30 | 1E | CHAR(10) | Display file library name |
These fields repeat in the order listed for the number of active record formats | CHAR(10) | Active record format name | |
CHAR(10) | Record format type | ||
BINARY(4) | Start row | ||
BINARY(4) | End row | ||
BINARY(4) | Window start column | ||
BINARY(4) | Window end column |
Field Descriptions
Active record format name. The name of an active record format for the active file on the requester device for the specified interactive job. An active record format is a record format that is currently displayed on the requester device.The following internal record names may be returned:
*ERRSFL | The name for an internal sub-file created when the ERRSFL keyword is used at the file level in the DDS. The start and end row values both indicate the message line. If the MSGLOC keyword is used in the DDS, the values indicate that line. Otherwise, they indicate the default message line. |
*ERRCTL | The name of an internal sub-file control record created for the ERRSFL keyword. |
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:
*SFL | Subfile record |
*SFLCTL | Subfile control record |
*SFLMSGRCD | Subfile message record |
*MNUBAR | Menubar record |
*PULLDOWN | Pulldown record |
*USRDFN | The record is a user defined data stream. |
*WINDOW | Window definition record. |
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
Message ID | Error Message Text |
---|---|
CPF2207 E | Not authorized to requester device or display file. |
CPF24B4 E | Severe error while addressing parameter list. |
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. |
CPF3C51 E | Internal job identifier not valid. |
CPF3C52 E | Internal job identifier no longer valid. |
CPF3C53 E | Job &3/&2/&1 not found. |
CPF3C55 E | Job &3/&2/&1 does not exist. |
CPF3C57 E | Not authorized to retrieve job information. |
CPF3C58 E | Job name specified is not valid. |
CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
CPF3C90 E | Literal value cannot be changed. |
CPF3CF1 E | Error code parameter not valid. |
CPF919F E | Job is not interactive. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R6
[ Back to top | Workstation Support APIs | APIs by category ]