Read from Virtual Terminal (QTVRDVT) API
Required Parameter Group:
| 1 | Virtual terminal handle | Input | Char(16) |
| 2 | Read information | Output | Char(10) |
| 3 | Data buffer | Output | Char(*) |
| 4 | Number of bytes to read | Input | Binary(4) |
| 5 | Data received | Output | Binary(4) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Read from Virtual Terminal (QTVRDVT) API reads data from the virtual terminal into the server program's data buffer. Your application should read data only if it has received an asynchronous notification message on the data queue, or if the more data flag was set on a previous read operation. The data received is in 5250 data stream format.
Only one full-screen display of data can be received at a time. If the data buffer is too small, partial displays are received and the more data flag for the QTVRDVT API's read information parameter is set to 1.
Before working with 5250 data streams, be sure to see the
IBM® 5494 Functions Reference manual, SC30-3533. This manual can be viewed online
through the
IBM
Publications Center
.
Authorities and Locks
None.
Required Parameter Group
- Virtual terminal handle
- INPUT; CHAR(16)
The reference code for the open virtual terminal path, created by the operating system with the Open Virtual Terminal Path (QTVOPNVT) API.
- Read information
- OUTPUT; CHAR(10)
Information about the read operation. The characters and their meanings are:
1 The operation code, which gives the server program additional information about IBM i status and what is expected of the server program. Valid values for this parameter are: 1 Invite 2 Output only 3 Put/get 4 Save display 5 Restore display 6 Read immediate 8 Read display A Cancel invite B Turn on message light C Turn off message light For detailed descriptions of these codes, see Read Operation Codes.
2 More data flag. Valid values for this parameter are: 0 There is no more data. 1 More data is available. Issue the read operation again to receive the additional data. This flag is set if the buffer specified on input is not large enough to hold all of the data received from the virtual terminal. 3 Key flag. Valid character values for this parameter are: 0 The Enter key was pressed. 1 The System Request key was pressed. 4-10 Reserved. These characters must be blank.
- Data buffer
- OUTPUT; CHAR(*)
The server program's buffer for receiving data from the virtual terminal. The data is a 5250 data stream.
The QTVRDVT API does not lock the data buffer. Thus, other applications should not use the buffer while the API is using it.
The data buffer should be large enough to hold the largest display of data expected. If it is not large enough for all the data to fit, the more data flag of the read information parameter is set to 1. Additional read requests must be performed, until all the remaining data is received and the more data flag is set back to 0.
- Number of bytes to read
- INPUT; BINARY(4)
The number of bytes to read from the data buffer. This number must be smaller than or equal to the size of the data buffer.
- Data received
- OUTPUT; BINARY(4)
The amount of data received from the virtual terminal in bytes. If no data is received from the virtual terminal, 0 is returned. Some read operations do not return any data.
For graphic work stations, a maximum of 24 576 (24KB) bytes of data can be returned.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Read Operation Codes
The following table describes the operation codes that can be returned on a
read request.
| Read Operation Codes | ||
|---|---|---|
| Value | Response Name | Description |
| 1 | Invite | The operating system and the application are ready to receive data. The server program is expected to follow this with a write operation when data becomes available from the client program. |
| 2 | Output only | This read request returned some data. The server program should send the data to the client program. However, the operating system is not ready to receive data from the server program. The server program should not request any data from the client program yet. This response usually occurs because an application is performing several put operations to the virtual terminal device. After the last put operation by the application, a put/get operation code is usually returned on the read operation. |
| 3 | Put/get | Data is returned from this read request and should be sent by the server program to the client program. The operating system is ready to receive data from the server program. The server program should wait for data from the client program. |
| 4 | Save display | The operating system expects the server program to obtain the data from the current display and write the data to the virtual terminal. The operating system saves the display for later use, such as returning the display to the server program. The server program must indicate a save-display response on the write operation and send the saved display as data (that is, the saved display must be in the data buffer). |
| 5 | Restore display | The data returned is a previously saved display. The server program should send the data to the client program. |
| 6 | Read immediate | No data is returned from this read request. The operating system expects the server program to write data to the virtual terminal. Only data from input fields should be written. |
| 8 | Read display | No data is returned from this read request. The operating system expects the server program to write data to the virtual terminal. The current display should be written. |
| A | Cancel invite | No data is returned from this read request. The operating system expects the server program to signal the client program to cancel the outstanding invite operation. When it is canceled, the server program must perform a write operation to the virtual terminal and indicate a cancel invite response. Because the response has no data associated with it, the number of bytes to write must be set to 0 for the write operation. |
| B | Turn on message light | No data is returned from this read request. A message has been received, and the user should be notified. The server program should signal the client program to turn on a display message indicator light or some other indicator. |
| C | Turn off message light | No data is returned from this read request. The display message light or some other indicator should be set off. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C90 E | Literal value cannot be changed. |
| CPF87F2 E | Virtual terminal handle &1 not valid. |
| CPF87F3 E | Data buffer length &1 not valid. |
| CPF87F7 E | Parameter value &1 not valid. |
| CPF87F8 E | Unexpected internal system error occurred in program &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1