| Previous | Contents | Index |
6.3 TELNET Port Driver I/O Function Codes
The TELNET port driver (TNDRIVER) provides terminal session support for
TCP stream connections using the RAW, NVT, RLOGIN, and TELNET
protocols. Either a remote device or an application can be present at
the remote endpoint of the connection.
A user program can manage a TELNET connection with the standard OpenVMS
$QIO system service by using the IO$_TTY_PORT and IO$_TTY_PORT_BUFIO
I/O function codes. This section describes these I/O function codes and
their associated arguments.
6.3.1 Interface Definition
The following definitions are used by the interface. The symbols are
defined in SYS$LIBRARY:TNIODEF.H.
6.3.1.1 Item List Codes
Table 6-7 describes the symbols used with the p5 parameter.
| Item Code | Maximum Size | Description |
|---|---|---|
| TN$_ACCPORNAM | 64 | Access port name string. When written, the string's length is determined by the item_length field. The value of item_length should not be more than 63 bytes. When read, the string is returned in ASCIC format (the first byte contains the string's length), so a size of 64 is appropriate. |
| TN$_CHARACTERISTICS | 4 | Characteristics mask. This longword contains a bit mask of the device's characteristics read or to be written. (See Table 6-8.) |
| TN$_CONNECTION_ATTEMPTS | 4 | Reconnection attempts. This item is the number of unsuccessful reconnection attempts which have been made on a reconnectable device. The value will be reinitialized when a successful connection is made. This item is read only. |
| TN$_CONNECTION_INTERVAL | 4 | Minimum time (in seconds) before reconnection attempts. |
| TN$_CONNECTION_TIMEOUT | 4 | Current time (in seconds) since the last reconnection attempt. This item is read only. |
| TN$_DATA_HIGH | 4 | Maximum amount of output data (in bytes) buffered at the network port. This number does not affect the amount of data buffered within the socket. |
| TN$_DEVICE_UNIT | 4 | Terminal device unit number. When written, this value must be between 1 and 9999. |
| TN$_IDLE_INTERVAL | 4 | Maximum idle time (in seconds) allowed before a connection is to be broken. Connections are not broken if the device is stalled. |
| TN$_IDLE_TIMEOUT | 4 | Current time (in seconds) since last output on the terminal. This item is read only. |
| TN$_LOCAL_ADDRESS | 32 | Local sockaddr of the active connection. When written, the value of item_length determines the size of the sockaddr . Note that the sockaddr is in BSD Version 4.4 format, which includes a sockaddr size field. (C programs should be compiled with the _SOCKADDR_LEN symbol defined.) This item is read only. |
| TN$_NETWORK_DEVICE_NAME | 64 | Name of the network pseudodevice currently bound to the terminal. When read, the data is returned in ASCIC format (the first byte contains the string's length). This item is read only. |
| TN$_PROTOCOL | 4 | Session protocol. (See Table 6-9.) |
| TN$_REMOTE_ADDRESS | 32 | Remote peer's sockaddr of the active connection. Note that the sockaddr is in BSD Version 4.4 format, which includes a sockaddr size field. The size of the sockaddr should be determined from this field. This item is read only. |
| TN$_SERVICE_TYPE | 4 | Class of terminal service. (See Table 6-10.) |
| TN$_STATUS | 4 | Current device and session status. This item is read only. |
6.3.1.2 Characteristic Mask Bits
Table 6-8 describes the characteristic mask bits used with the
p5 parameter.
| Characteristic | Description |
|---|---|
| TN$M_AUTOCONNECT | The device supports automatic connect/reconnect. |
| TN$M_LOGIN_ON_DASSGN | Initiate a login when the TELNET device is deassigned. This characteristic requires the BYPASS or SYSNAM privilege or executive or kernel mode calls. |
| TN$M_LOGIN_TIMER | Used in conjunction with TN$M_LOGIN_ON_DASSGN, this bit indicates that the login completion timer applies. If the TN device fails to login within 60 seconds, the connection will be broken and the device deallocated. This characteristic requires the BYPASS or SYSNAM privileges or executive or kernel mode calls. |
| TN$M_PERMANENT_UCB | The TELNET device is to remain until explicitly deleted. |
| TN$M_RETAIN_ON_DASSGN | The TELNET device is not to be deleted upon the deassignment of the last channel to this device. This condition is cleared on this last deassignment, so that a subsequent assign and deassign will result in the device being deleted. |
| TN$M_VIRTUAL_TERMINAL | When logging in under this device, a virtual terminal is to be created by TTDRIVER. |
Table 6-9 describes the protocol types used with the p5 parameter.
| Protocol Type | Description |
|---|---|
| TN$K_PROTOCOL_UNDEFINED | There is no explicit protocol for this session. Data is transmitted and received on the socket without any interpretation. This is a raw connection. |
| TN$K_PROTOCOL_NVT | Network Virtual Terminal (NVT) protocol. The protocol understands basic session control but does not include the options negotiation present in the TELNET protocol. |
| TN$K_PROTOCOL_RLOGIN | BSD Remote Login protocol. This simple protocol provides some special control character support but lacks the architecture independence of the NVT and TELNET protocols. |
| TN$K_PROTOCOL_TELNET | TELNET protocol. Including the basic NVT protocol, TELNET adds support for options negotiation. This can provide an enhanced terminal session depending upon the client and server involved. |
Table 6-10 describes the service type codes used with the p5 parameter.
| Service Type | Description |
|---|---|
| TN$K_SERVICE_NONE | The service type is not currently known. |
| TN$K_SERVICE_INCOMING | The service is an incoming connection. |
| TN$K_SERVICE_OUTGOING | The service is an outgoing connection. |
The IO$_TTY_PORT function is used to pass $QIO parameters through the terminal driver to the TELNET port driver. The actual subfunction is encoded as an option mask and may be:
Bind socket to a TELNET terminal.This subfunction will bind a created (connected) socket to a TELNET terminal device.
p1
OpenVMS usage: channel type: word (unsigned) access: read only mechanism: by value
The p1 argument contains the channel number of the socket over which the TELNET session is to be established.p2
OpenVMS usage: protocol_number type: longword (unsigned) access: read only mechanism: by value
The p2 argument contains the protocol selection.p3
OpenVMS usage: characteristics_mask type: longword (unsigned) access: read only mechanism: by value
The p3 argument specifies a mask of characteristics to apply against the connection. See Table 6-8 for possible values.
The IO$M_TN_STARTUP subfunction allows the application to communicate over a socket using the terminal driver QIO interface. Note that incoming and outgoing data is processed by the terminal driver, and that the terminal's characteristics may affect the format of the data. Be aware that by default, the terminal will echo incoming data back to the sender.Once the subfunction completes, the application is free to perform all terminal QIO functions on the connection. While the socket is bound to a terminal device, it will process neither the IO$_READxBLK nor the IO$_WRITExBLK function, and will return the error SS$_DEVINUSE.
SS$_IVCHAN Programming error. The specified channel is not valid. SS$_IVMODE Programming error. The access mode of the channel is more privileged than the access mode of the terminal's channel. SS$_NOPRIV Programming error. The TN$M_LOGIN_ON_DASSGN characteristic was specified in a characteristics mask from a QIO in USER or SUPERVISOR mode without either the BYPASS or SYSPRV privilege. SS$_NOTNETDEV Programming error. The specified channel is an assignment to a non-BG device. SS$_PROTOCOL Programming error. The specified protocol number is not valid, or the internet network is not available.
Unbind socket from a TELNET terminal.This subfunction will unbind a previously bound socket-terminal connection.
p1
OpenVMS usage: channel type: word (unsigned) access: read only mechanism: by value
The p1 argument contains the channel number of the socket to establish the TELNET session.
The IO$M_TN_SHUTDOWN subfunction allows the application to break a previously bound socket-terminal connection (created with IO$M_TN_STARTUP). The channel must be from an assignment to the same network pseudodevice in the socket-terminal connection.Upon completion, the application retains the assignments to the connection and the TELNET terminal, but they are no longer related. Any subsequent IO$_READxBLK or IO$_WRITExBLK function on the socket channel will no longer return the error SS$_DEVINUSE.
SS$_IVCHAN Programming error. The specified channel is not valid. SS$_IVMODE Programming error. The access mode of the channel is more privileged than the access mode of the terminal's channel. SS$_NOTNETDEV Programming error. The specified channel is an assignment to a non-BG device. SS$_DEVREQERR Programming error. The device on the channel does not match the device in the socket-terminal connection.
6.3.3 Buffered Reading and Writing of Item Lists
The IO$_TTY_PORT_BUFIO function is used to pass $QIO parameters through
the terminal driver to the TELNET port driver. IO$_TTY_PORT_BUFIO
differs from IO$_TTY_PORT in that certain subfunctions accept buffered
item lists for reading or writing parameters to the terminal device.
The subfunctions of IO$_TTY_PORT_BUFIO accept an item list for input or output. Figure 6-1 shows the format of this item list.
Figure 6-1 Subfunction Item List
The item list is terminated with an item_code and item_length, both of which are zero.
The subfunctions of IO$_TTY_PORT_BUFIO can be combined into a single QIO. For example, the IO$M_TN_SETMODE and IO$M_TN_CONNECT can be combined to set the device's parameters and then to attempt to make a connection.
The subfunctions are performed in the following order:
Certain items are read only (IO$M_TN_SENSEMODE) and cannot be written (IO$M_TN_SETMODE). Normally, attempting to write such items would result in the error SS$_BADATTRIB. However, if a combination operation (IO$M_TN_SENSEMODE|IO$M_TN_SETMODE) is being performed, these items will not result in an error. Rather, the items will be ignored in the IO$M_TN_SETMODE processing, and the QIO will continue with IO$M_TN_SENSEMODE processing, returning the information that the item specifies. |
Read device parameters.
p5
OpenVMS usage: item_list_2 type: vector byte (unsigned) access: read only mechanism: by reference
The p5 argument is the address of an item list that contains a summary of information to be read from the device.
The IO$M_TN_SENSEMODE subfunction of IO$_TTY_PORT_BUFIO is used to read the parameters associated with a device.
SS$_BADATTRIB Programming error. The item code within the list is not valid. This could be because of its code, an attempt to write a read-only parameter, or inappropriate size. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_IVBUFLEN Programming error. The length of the specified item is not acceptable. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_NOPRIV Programming error. An item that requires a privilege which the requestor does not have is present in the item list. The address of the item's buffer is returned in the second longword of the I/O status block.
Write device parameters.
p5
OpenVMS usage: item_list_2 type: vector (byte unsigned) access: read only mechanism: by reference
The p5 argument is the address of an item list that contains a summary of information to be written to the device.
The IO$M_TN_SETMODE subfunction of IO$_TTY_PORT_BUFIO is used to write the parameters associated with a device.
SS$_BADATTRIB Programming error. The item code within the list is not valid. This could be because of its code, an attempt to write a read-only parameter, or inappropriate size. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_DUPLNAM Programming error. An attempt to set the device's unit number via the TN$_DEVICE_UNIT item has failed because that specified unit number was already present. SS$_IVBUFLEN Programming error. The length of the specified item is not acceptable. The address of the item's buffer is returned in the second longword of the I/O status block. SS$_NOPRIV Programming error. An item that requires a privilege which the requester does not have is present in the item list. The address of the item's buffer is returned in the second longword of the I/O status block.
| Previous | Next | Contents | Index |