| 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(*) |
| 10 | Open operation information | Input | Char(10) |
| 11 | Session initiation information | Input | Char(*) |
| 12 | Open feedback information | I/O | Char(*) |
| 13 | Length of open feedback information | Input | Binary(4) |
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.
A reference code created by the operating system to identify this open virtual terminal path in later calls to other virtual terminal APIs.
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.
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.
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.
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.
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 |
The key value to use for the data queue.
The length of the key value. Valid values are 0 through 256. If you specify 0, no key is used for data queue entries.
The structure in which to return error information. For the format of the structure, see Error code parameter.
Information about the open operation. The characters and their meanings are:
| 1 | Whether the PC text-assist function is supported.
Valid values are:
|
||||||
| 2-10 | Reserved. These characters must be blank. |
Information about the initiation of the virtual terminal session. The information must be in the following format:
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.
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.
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.
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.
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 |
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:
| CHAR(1) | The number of bytes of network address actually used. All 20 bytes allocated for the network address may not actually be used. |
| 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.' |
| 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:
| CHAR(1) | The number of bytes of network address actually used. All 28 bytes allocated for the network address may not actually be used. |
| 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.' |
| 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.
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 |
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.
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 |
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 |
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.
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. | |
| 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. |