Write to Virtual Terminal (QTVWRTVT) API


  Required Parameter Group:

1 Virtual terminal handle Input Char(16)
2 Write information Input Char(10)
3 Data buffer Input Input
4 Number of bytes to write Input Binary(4)
5 Error code I/O Char(*)

  Default Public Authority: *USE

  Threadsafe: No

The Write to Virtual Terminal (QTVWRTVT) API writes data from a server program's data buffer to a virtual terminal. You can send one display to the virtual terminal during each write operation. You cannot send partial or multiple displays.


Authorities and Locks

None.


Required Parameter Group

Virtual terminal handle
INPUT; CHAR(16)

The reference code for the open virtual terminal path, created with the Open Virtual Terminal Path (QTVOPNVT) API.

Write information
INPUT; CHAR(10)

Information about the write operation. The information given in each character is as follows:

1 Key flag. Valid values are:
0 The Enter key was pressed.
1 The System Request key was pressed. The next read operation returns the System Request menu.
2 The Attention key was pressed. In this case, the number of bytes to write must be 0.
3 The Test Request key was pressed.
4 The Help-in-Error key was pressed.
2 Operation code. This parameter describes the type of write operation to perform. Valid values and their meanings are:
blank Put/get
2 Output only
3 Put/get
4 Save display
A Cancel invite

For detailed descriptions of these codes, see Write Operation Codes.
3 Data stream output error. The negative response code, for example X'10030101', is sent as data in the data buffer.
blank 5250 data in data buffer
0 5250 data in data buffer
1 Data stream error; SNA response code data is in the data buffer.
4-10 Reserved. These characters must be blank.

Data buffer
INPUT; CHAR(*)

The server program's buffer containing the data to send to the virtual terminal.

The QTVWRTVT API does not lock the data buffer. Thus, other applications should not use the buffer while the API is using it.

Number of bytes to write
INPUT; BINARY(4)

The number of bytes to write. This number must be smaller than or equal to the size of the data buffer. Valid range of numbers is 0 through 24KB. This parameter must be 0 if character 1 of the write information parameter is 2.

Some write operations do not write data.

Error code
I/O; CHAR(*)

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


Write Operation Codes

The following table describes the operation codes that can be used for the write information parameter.

Write Operation Codes
Value Name Description
blank Put/get Data is being sent to the virtual terminal. The virtual terminal server program is ready for input.
2 Output only This write operation is in response to a read request that returned an output-only read operation code.
3 Put/get See the description above.
4 Save display This write operation is in response to a read request that returned a save display read operation code. No data is associated with this write operation; thus, the data buffer length must be set to 0.
A Cancel invite This write operation is in response to a read request that returned a cancel invite read operation code. No data is associated with this write operation; thus, the data buffer length must be set to 0.


Error Messages

Message ID Error Message Text
CPF3C90 E Literal value cannot be changed.
CPF3CF1 E Error code parameter not valid.
CPF87D4 E Data sent exceeded the corresponding I/O request.
CPF87F2 E Virtual terminal handle &1 not valid.
CPF87F3 E Data buffer length &1 not valid.
CPF87F4 E Key flag &1 not valid.
CPF87F5 E Operation code response &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

[ Back to top | Virtual Terminal APIs | APIs by category ]