Open Virtual Terminal Path (QTVOPNVT) API
Required Parameter Group:
| 1 | Virtual terminal handle | Output | Char(16) |
| 2 | Keyboard language type | Input | Char(3) |
| 3 | Character set | Input | Binary(4) |
| 4 | Code page | Input | Binary(4) |
| 5 | Workstation type | Input | Binary(4) |
| 6 | Qualified data queue name | Input | Char(20) |
| 7 | Key value | Input | Char(*) |
| 8 | Length of key value | Input | Binary(4) |
| 9 | Error code | I/O | Char(*) |
Optional Parameter Group: 1
| 10 | Open operation information | Input | Char(10) |
Optional Parameter Group: 2
| 11 | Session initiation information | Input | Char(*) |
Optional Parameter Group: 3
| 12 | Open feedback information | I/O | Char(*) |
| 13 | Length of open feedback information | Input | Binary(4) |
Default Public Authority: *USE
Threadsafe: No
The Open Virtual Terminal Path (QTVOPNVT) API opens a path to a virtual terminal, allowing a server program to interact with an IBM® i application. The virtual terminal path remains open until it is explicitly closed or the job is ended.
When you call the QTVOPNVT API, the operating system selects or automatically configures a virtual terminal for you and indicates that the device is logically turned on. The operating system sends a message to the specified data queue to signal the server program that data is available.
Authorities and Locks
- Library Authority
- *USE
- User Queue Authority
- *CHANGE
- User Queue Lock
- *EXCLRD
Required Parameter Group
- Virtual terminal handle
- OUTPUT; CHAR(16)
A reference code created by the operating system to identify this open virtual terminal path in later calls to other virtual terminal APIs.
- Keyboard language type
- INPUT; CHAR(3)
The keyboard language type for the virtual terminal. To use the system value, specify blanks for this parameter. For a list of other valid values, see the Create Device Description (Display) (CRTDEVDSP) command. For details about supported languages, see the i5/OS globalization topic collection.
- Character set
- INPUT; BINARY(4)
The graphic character set for the virtual terminal. Valid values are a specific graphic character set number and these special values:
0 The graphic character set system value is used. -1 The keyboard language type is used to select the appropriate character set. For details about the graphic character sets you can specify, see i5/OS globalization.
Note: The graphic character set system value is obtained from the default graphic character set and code page (QCHRID) system value.
- Code page
- INPUT; BINARY(4)
The code page for the virtual terminal. For details about the code pages you can specify, see i5/OS globalization. If you specified 0 or -1 for the character set parameter, you do not have to specify this parameter. When you use 0 for the character set parameter, the system value is used for this parameter. When you use -1 for the character set parameter, the code page value is derived from the keyboard language type parameter.
Note: The code page system value is obtained from the default graphic character set and code page (QCHRID) system value.
- Workstation type
- INPUT; BINARY(4)
The type of workstation to use. Valid values are 1 through 15. See Supported Workstation Types and Models for an explanation of the values.
Other workstation types and models are supported. You can specify these by determining their equivalents in Workstation Types and Models.
If a virtual terminal description does not yet exist for the workstation type specified, the operating system attempts to configure the workstation automatically. Automatic configuration is controlled by the Automatic virtual device configuration (QAUTOVRT) system value, which specifies the number of virtual terminals that the operating system can configure automatically. See for more information about the QAUTOVRT value.
- Qualified data queue name
- INPUT; CHAR(20)
The name and library of the data queue used by your application program to receive data from the operating system asynchronously. The first 10 bytes are for the data queue name; the second 10 bytes are for the library name. Allowable special values are:
*CURLIB The jobs current library *LIBL The library list
- Key value
- INPUT; CHAR(*)
The key value to use for the data queue.
- Length of key value
- INPUT; BINARY(4)
The length of the key value. Valid values are 0 through 256. If you specify 0, no key is used for data queue entries.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group 1
- Open operation information
- INPUT; CHAR(10)
Information about the open operation. The characters and their meanings are:
1 Whether the PC text-assist function is supported. Valid values are: Blank The PC text-assist function is supported. 0 The PC text-assist function is supported. 1 The PC text-assist function is not supported. The adapted word processing function is used automatically. 2-10 Reserved. These characters must be blank.
Optional Parameter Group 2
- Session initiation information
- INPUT; CHAR(*)
Information about the initiation of the virtual terminal session. The information must be in the following format:
- Number of variable length records
- The total number of all of the variable length records.
- Variable length records
- The attributes of the session initiation that are to be performed or changed. For the specific format of the variable length record, see Format for Variable Length Record.
Optional Parameter Group 3
- Open feedback information
- I/O; CHAR(*)
A pointer to information about the device assigned to this virtual terminal session or the reason code when an automatic sign-on request fails. The layout of this information is described in Format for Open Feedback Information.
- Length of open feedback information
- INPUT; BINARY(4)
The size of the open feedback output area being supplied by the caller. The Open Feedback Information returned will be restricted such that it always returns a total number of bytes equal to or less than this parameter.
Format for Variable Length Record
The following table defines the format for the variable length records.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Key |
| 4 | 4 | BINARY(4) | Length of data |
| 8 | 8 | CHAR(*) | Data |
If the length of the data is longer than the key fields data length, the data will be truncated at the right. No message will be issued.
If the length of the data is smaller than the key field s data length, the data will be padded with blanks at the right. No message will be issued.
It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.
Field Descriptions
Data. The data used to control the session initiation.
Key. An attribute of the session initiation. See Keys for the list of valid keys.
Length of data. The length of the data used to control the initiation.
Keys
The following table shows the valid keys for the key field area of the variable length record.
| Key | Type | Field |
|---|---|---|
| 1 | CHAR(10) | User profile |
| 2 | CHAR(10) | User password |
| 3 | CHAR(10) | Initial program |
| 4 | CHAR(10) | Initial menu |
| 5 | CHAR(10) | Current library |
| 6 | CHAR(10) | Virtual device name |
| 7 | CHAR(20) | IPv4 Network address |
| 8 | CHAR(*) | Automatic sign-on (see Automatic Sign-on Key) |
| 9 | CHAR(32) | Profile Token |
| 10 | CHAR(28) | IPv6 Network address |
Field Descriptions
Automatic sign-on. The values needed to have a user automatically signed on once a terminal session has been established. If key 8 is not specified, automatic sign-on will not occur for this virtual terminal session; keys 3, 4, and 5 will be ignored. The automatic sign-on must be used in place of key 1 and 2 whenever the system value QPWDLVL is set to 2 or 3. When the system value QPWDLVL is set to 0 or 1, either keys 1 and 2 or key 8 may be used for automatic sign-on.
Current library. The current library to be used when using automatic sign-on. The special value *USRPRF can be used to indicate that the current library found in the user profile specified with key 1 should be used. If key 5 is not specified, *USRPRF is the default. This value is supported for both key 1 and key 8.
Initial menu. The initial menu to be used when using automatic sign-on. The special value *USRPRF can be used to indicate that the initial menu found in the user profile specified with key 1 should be used. This value is supported for both key 1 and key 8. If key 4 is not specified, *USRPRF is the default.
Initial program. The initial program to be used when using automatic sign-on. The special value *USRPRF can be used to indicate that the initial program found in the user profile specified with key 1 should be used. If key 3 is not specified, *USRPRF is the default. This value is supported for both key 1 and key 8.
IPv4 Network address. An address that is uniquely assigned to each terminal session and is used in all communications with the session. This address is associated with the virtual terminal device by the applicaion and can be accessed by any other application using the Retrieve Device Description (QDCRDEVD) API. The following format defines the layout of the network address:
- Size of network address
CHAR(1) The number of bytes of network address actually used. All 20 bytes allocated for the network address may not actually be used.
- Family or protocol
CHAR(1) The family or protocol that is being used (only IPv4 is supported). The family or protocol defines the layout used for the remainder of the network address. Internet Protocol version 4 value is X'02.'
- Internet Protocol (IP)
CHAR(2) TCP port number CHAR(4) internet address
IPv6 Network address. An address that is uniquely assigned to each terminal session and is used in all communications with the session. This address is associated with the virtual terminal device by the applicaion and can be accessed by any other application using the Retrieve Device Description (QDCRDEVD) API. The following format defines the layout of the network address:
- Size of network address
CHAR(1) The number of bytes of network address actually used. All 28 bytes allocated for the network address may not actually be used.
- Family or protocol
CHAR(1) The family or protocol that is being used (only IPv6 is supported). The family or protocol defines the layout used for the remainder of the network address. Internet Protocol version 6 value is X'18.'
- Internet Protocol (IP)
CHAR(2) TCP port number CHAR(4) Flow Info - optional: Must be set to X'00000000' if not used. CHAR(16) internet address up to 16 hex chars of address, right adjusted, unused leading chars must be set to x'00' CHAR(4) Scope ID - optional: Must be set to X'00000000' if not used.
Profile Token. A 32-byte Profile Token which may be used as an alternative to using key 8, or keys 1 and 2 for Automatic sign-on purposes. When key 9 is used for Automatic sign-on, keys 3, 4 and 5 will also be honored if specified. Also, if Optional parameter group 3 is specified, the Automatic sign-on response code can be used to determine the result of the Automatic sign-on request when using key 9. Profile tokens may be used for all values of the system value QPWDLVL.
User password. The user password specified for initiating this virtual terminal session in conjunction with the specified profile. If the user profile is *CURRENT, you can use the special value *NONE for the user password. If you specify a user profile other than *CURRENT or blank and do not specify a user password, an error message is returned. This value works in association with key 1 (but not with key 8). This key is supported only when system value QPWDLVL is set to 0 or 1. Note that the Automatic sign-on Reason Code value from Optional Parameter Group 3 is undefined when using keys 1 and 2 for Automatic sign-on.
User profile. The user profile specified for initiating this virtual terminal session. You can use the special value *CURRENT for the user profile. If the user profile is *CURRENT, you can use the special value *NONE for the password. This value is used in association with key 2 (but not with key 8). If key 1 is not specified, automatic sign-on will not occur for this virtual terminal session; keys 2, 3, 4, and 5 will be ignored. This key is supported only when system value QPWDLVL is set to 0 or 1. Note that the Automatitic sign-on Reason Code value from Optional Parameter Group 3 is undefined when using keys 1 and 2 for Automatic sign-on.
Virtual device name. The specific virtual device to be associated with the terminal session.
The device is created by the system, if it does not exist, when the QAUTOVRT system value allows for this.
If no value is supplied by the caller, the virtual terminal API defaults to using the virtual device selection methods.
The device description name must be a valid *VRT and must adhere to standard IBM i naming conventions.
Automatic Sign-on Key
The following table defines the format for the automatic sign-on key.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Sign-on length |
| 4 | 4 | BINARY(4) | Passphrase CCSID |
| 8 | 8 | BINARY(4) | Passphrase offset |
| 12 | C | BINARY(4) | Passphrase length |
| 16 | F | CHAR(8) | Client seed |
| 24 | 18 | CHAR(8) | Server seed |
| 32 | 20 | CHAR(10) | Bypass user profile |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | CHAR(*) | Passphrase |
Field Descriptions
Bypass user profile. The user profile to be automatically signed on. This profile is not interchangeable with the user profile from key 1. If key 8 is used, then the profile must be part of the automatic sign-on information.
Client seed. A randomly-generated seed that was used to encrypt the password or passphrase using the encryption level (either DES-7 or SHA-1) on the system. If a zero-length seed is provided, it is assumed that a clear-text unencrypted password or passphrase is being provided.
Passphrase CCSID. The CCSID of the password or passphrase being provided for automatic sign-on.
Passphrase offset. The offset in this structure of the actual password or passphrase being provided for automatic sign-on.
Passphrase length. The number of bytes in the password or passphrase being provided.
Passphrase. The password or passphrase associated with the user profile to be automatically signed on. This field can range from 1 to 128 bytes. If your system is pre-V5R1, or has system value QPWDLVL set to 0 or 1, then the maximum size of this field is 10 bytes.
Reserved. Reserved for future use.
Server seed. A randomly-generated seed that was used to encrypt the password or passphrase using the encryption level (either DES-7 or SHA-1) on the system. If a zero-length seed is provided, it is assumed that a clear-text unencrypted password or passphrase is being provided.
Sign-on length. The total number of bytes of the automatic sign-on data provided.
Format for Open Feedback Information
The following table defines the format for the open feedback information.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of bytes available |
| 4 | 4 | BINARY(4) | Number of bytes returned |
| 8 | 8 | BINARY(4) | Reason code (see Automatic Sign-on Reason Codes) |
| 12 | C | CHAR(10) | Device name |
| 22 | 16 | CHAR(4) | Reserved |
Automatic Sign-on Reason Codes
The following table shows the reason codes that may be returned for automatic sign-on failure. The reason code field is undefined when using keys 1 and 2 for Automatic sign-on.
| Reason Code |
Failure Description |
|---|---|
| 1 | System error (unknown error) |
| 2 | User profile unknown |
| 3 | User profile disabled |
| 4 | Password or passphrase not valid |
| 5 | Password or passphrase is expired |
| 6 | Pre-V2R2 password |
| 8 | Next password or passphrase that is not valid will revoke user profile |
| 9 | Profile Token invalid or expired |
Field Descriptions
Device Name. The device name that has actually been assigned to this terminal session.
Number of bytes available. The total number of bytes of feedback information available for return. This space is provided by the caller.
Number of bytes returned. The total number of bytes of feedback information actually returned to the caller.
Reason code. Reason an automatic sign-on request has failed. For possible reason code values, see Automatic Sign-on Reason Codes.
Reserved. Reserved for future use.
Supported Workstation Types and Models
The following table details the values you can specify for the QTVOPNVT APIs workstation type parameter.
| Workstation Types and Models | |||
|---|---|---|---|
| Value | Workstation Type and Model | Equivalent Type and Model | Description |
| 1 | 5251-11 | 24 x 80 monochrome display. | |
| 2 | 5291-1 | 5291-2 | 24 x 80 monochrome display. |
| 3 | 5292-2 | 24 x 80 color graphics display. This type is also emulated by a graphics workstation feature. | |
| 4 | 5555-B01 | 5555-E01 | 24 x 80 or 27 x 132 monochrome double-byte character set (DBCS) display. This type is emulated by a monochrome workstation feature that supports a DBCS display. |
| 5 | 3196-A1 | 3196-A2 3196-B1 3196-B2 3476-EA |
24 x 80 monochrome display. This type is emulated by a monochrome workstation feature. This is what the ASCII devices emulate. |
| 6 | 3179-2 | 3197-C1 3197-C2 3476-EC 5292-1 |
24 x 80 color display. This type is emulated by a color workstation feature. |
| 7 | 3180-2 | 3197-D1 3197-D2 3197-W1 3197-W2 |
27 x 132 monochrome display. |
| 8 | 3477-FC | 27 x 132 wide-screen color display. | |
| 9 | 3477-FG | 3477-FA 3477-FD 3477-FE 3477-FW |
27 x 132 wide-screen monochrome display. |
| 10 | 5555-C01 | 5555-F01 | 24 x 80 or 27 x 132 color double-byte character set (DBCS) display. This type is emulated by a color workstation feature that supports a DBCS display. |
| 11 | 5555-G01 | 24 x 80 or 27 x 132 double-byte character set (DBCS) monochrome graphics display. This type is emulated by a monochrome workstation feature that supports a DBCS display. | |
| 12 | 5555-G02 | 24 x 80 or 27 x 132 color double-byte character set (DBCS) graphics display. This type is emulated by a color graphics workstation feature that supports a DBCS display. | |
| 13 | 3486-BA | 24 x 80 monochrome display. | |
| 14 | 3487-HA | 3487-HG 3487-HW |
24 x 80 or 27 x 132 monochrome display. |
| 15 | 3487-HC | 24 x 80 or 27 x 132 color display. | |
Usage Notes
- All 5250 workstations, except 5555 Model B01, can operate as 5251 Model 11
workstations.
- Selecting double-byte character set (DBCS) workstations requires the IBM i primary language to be one of the DBCS national language versions (NLVs).
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1842 E | Cannot access system value &1. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C84 E | Key &1 required with value specified for key &2. |
| CPF3C86 E | Required key &1 not specified. |
| CPF3C88 E | Number of variable length records &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF87D7 E | Cannot automatically select virtual device. |
| CPF87FA E | Character identifier not valid. |
| CPF87FB E | Cannot exceed maximum number of active Virtual Terminal sessions. |
| CPF87F0 E | Virtual terminal type value &1 not valid. |
| CPF87F1 E | Queue key length &1 not valid. |
| CPF87F2 E | Virtual terminal handle &1 not valid. |
| CPF87F7 E | Parameter value &1 not valid. |
| CPF87F8 E | Unexpected internal system error occurred in program &1. |
| CPF87F9 E | Keyboard language type &1 not valid. |
| CPF9E18 E | Attempt made to exceed usage limit for product &1. User not added. |
| CPF9E71 E | Grace period expired. Requesting user not added. |
| CPF9E73 E | Expiration date &4 was reached. |
| CPF9E78 E | The license key for product &1, license term &2, feature &3 is no longer valid. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1