# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

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.

Table 6-7 List Codes for the p5 Item
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.

Table 6-8 Characteristic Mask Bits
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.

### 6.3.1.3 Protocol Types

Table 6-9 describes the protocol types used with the p5 parameter.

Table 6-9 Protocol Type Codes
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.

### 6.3.1.4 Service Types

Table 6-10 describes the service type codes used with the p5 parameter.

Table 6-10 Service Type Codes
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.

## 6.3.2 Passing Parameters to the TELNET Port Driver

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:

- IO$M_TN_STARTUP --- Bind socket to a TELNET terminal.
- IO$M_TN_SHUTDOWN --- Unbind socket from a TELNET terminal.

# IO$_TTY_PORT|IO$M_TN_STARTUP

> Bind socket to a TELNET terminal.

> This subfunction will bind a created (connected) socket to a TELNET terminal device.

## Arguments

> ### 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.

## Description

> 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.

## Condition Values Returned

> 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.

# IO$_TTY_PORT|IO$M_TN_SHUTDOWN

> Unbind socket from a TELNET terminal.

> This subfunction will unbind a previously bound socket-terminal connection.

## Arguments

> ### 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.

## Description

> 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.

## Condition Values Returned

> 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.

- IO$M_TN_SENSEMODE --- Read device parameters.
- IO$M_TN_SETMODE --- Write device parameters.

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:

1. IO$M_TN_SETMODE
2. IO$M_TN_CONNECT
3. IO$M_TN_SENSEMODE
4. IO$M_TN_DISCON

Note 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.

# IO$_TTY_PORT_BUFIO|IO$M_TN_SENSEMODE

> Read device parameters.

## Arguments

> ### 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.

## Description

> The IO$M_TN_SENSEMODE subfunction of IO$_TTY_PORT_BUFIO is used to read the parameters associated with a device.

## Condition Values Returned

> 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.

# IO$_TTY_PORT_BUFIO|IO$M_TN_SETMODE

> Write device parameters.

## Arguments

> ### 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.

## Description

> The IO$M_TN_SETMODE subfunction of IO$_TTY_PORT_BUFIO is used to write the parameters associated with a device.

## Condition Values Returned

> 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