|
HP OpenVMS Systems Documentation |
|
HP TCP/IP Services for OpenVMS
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Previous | Contents | Index |
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 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.
This appendix describes the socket options that you can set with the Sockets API setsockopt() function and the $QIO system service IO$_SETMODE and IO$_SETCHAR I/O function codes. You can query the value of these socket options using the Sockets API getstockopt() function or the $QIO system service IO$_SENSEMODE or IO$_SENSECHAR I/O function code.
Table A-1 lists the socket options that are set at the SOL_SOCKET level and their Sockets API and system service symbol names.
| Sockets API Symbol | System Service Symbol | Description |
|---|---|---|
| SO_BROADCAST | TCPIP$C_BROADCAST |
Permits the sending of broadcast messages. Requires an integer
parameter and SYSPRV, BYPASS, or OPER privilege. Optional for a
connectionless datagram.
If the inet subsystem attribute ovms_nobroadcastcheck is not zero, any nonprivileged application can send broadcast messages. |
| SO_DONTROUTE | TCPIP$C_DONTROUTE | Indicates that outgoing messages should bypass the standard routing facilities. Instead, the messages are directed to the appropriate network interface according to the network portion of the destination address. |
| SO_ERROR | TCPIP$C_ERROR | Obtains the socket error status and clears the error on the socket. |
| SO_FULL_DUPLEX_CLOSE | TCPIP$C_FULL_DUPLEX_CLOSE | When set, if the remote application closes the connection, the next transmit operation will return an error. |
| SO_KEEPALIVE | TCPIP$C_KEEPALIVE |
Keeps connections active. Enables the periodic transmission of
keepalive probes to the remote system. If the remote system fails to
respond to the keepalive probes, the connection is broken.
If the SO_KEEPALIVE option is enabled, the values of TCP_KEEPCNT, TCP_KEEPINTVL and TCP_KEEPIDLE affect TCP behavior on the socket. |
| SO_LINGER | TCPIP$C_LINGER |
Lingers on a
close()
function if data is present. Controls the action taken when unsent
messages queue on a socket and a
close()
function is performed. Uses a
linger
structure parameter defined in SOCKET.H to specify the state of the
option and the linger interval.
If SO_LINGER is specified, the system blocks the process during the close() function until it can transmit the data or until the time expires. If the option is not specified and a close() function is issued, the system allows the process to resume as soon as possible. |
| SO_OOBINLINE | TCPIP$C_OOBINLINE | When this option is set, out-of-band data is placed in the normal input queue. When SO_OOBINLINE is set, the MSG_OOB flag to the receive functions cannot be used to read the out-of-band data. A value of 0 disables the option, and a nonzero value enables the option. |
| SO_RCVBUF | TCPIP$C_RCVBUF | Sets the receive buffer size, in bytes. Requires an integer parameter and SYSPRV, BYPASS, or OPER privileges. |
| SO_RCVTIMEO | TCPIP$C_RCVTIMEO | For HP use only. Sets the timeout value for a recv() operation. The argument is a pointer to a timeval structure containing an integer value specified in seconds. |
| SO_REUSEADDR | TCPIP$C_REUSEADDR | Specifies that the rules used in validating addresses supplied by a bind() function should allow reuse of local addresses. A value of 0 disables the option, and a non-zero value enables the option. The SO_REUSEPORT option is automatically set when an application sets SO_REUSEADDR. |
| SO_REUSEPORT | TCPIP$C_REUSEPORT | Allows more than one process to receive UDP datagrams destined for the same port. The bind() call that binds a process to the port must be preceded by a setsockopt() call specifying this option. SO_REUSEPORT is automatically set when an application sets the SO_REUSEADDR option. |
| SO_SHARE | TCPIP$C_SHARE | Allows multiple processes to share the socket. |
| SO_SNDBUF | TCPIP$C_SNDBUF | Sets the send buffer size in bytes. Takes an integer parameter and requires SYSPRV, BYPASS, or OPER privileges. Optional for a connectionless datagram. |
| SO_SNDLOWAT | TCPIP$C_SNDLOWAT | Sets the low-water mark for a send() operation. The send low-water mark is the amount of space that must exist in the socket send buffer for select() to return writeable. Takes an integer value specified in bytes. |
| SO_SNDTIMEO | TCPIP$C_SNDTIMEO | For HP use only. Sets the timeout value for a send() operation. The argument is a pointer to a timeval structure containing an integer value specified in seconds. |
| SO_TYPE | TCPIP$C_TYPE | Obtains the socket type. |
| SO_USELOOPBACK | TCPIP$C_USELOOPBACK | For HP use only. This option applies only to sockets in the routing domain (AF_ROUTE), When you enable this option, the socket receives a copy of everything sent on the socket. |
Table A-2 lists the TCP protocol options that are set at the IPPROTO_TCP level and their Sockets API and system service symbol names. You must use the TCP.H header file to specify the TCP protocol options.
| Sockets API Symbol | System Service Symbol | Description |
|---|---|---|
| TCP_KEEPCNT | TCPIP$C_TCP_KEEPCNT |
When the SO_KEEPALIVE option is enabled, TCP sends probes to the remote
system of a connection that has been idle for a period of time. The
TCP_KEEPCNT option specifies the maximum number of keepalive probes to
be sent.
To display the values of the
inet
subsystem attributes, enter the following command at the system prompt:
The default value for TCP_KEEPCNT is 8. |
| TCP_KEEPIDLE | TCPIP$C_TCP_KEEPIDLE |
When the SO_KEEPALIVE option is enabled, TCP sends probes to the remote
system of a connection that has been idle for a period of time.
TCP_KEEPIDLE specifies the number of seconds before TCP will send the
initial keepalive probe.
To display the values of the
inet
subsystem attributes, enter the following command at the system prompt:
The default value for TCP_KEEPIDLE is 75 seconds 1. |
| TCP_KEEPINIT | TCPIP$C_TCP_KEEPINIT |
If a TCP connection cannot be established within a period of time, TCP
will time out the connection attempt. The default timeout value for
this initial connection establishment is 75 seconds. The TCP_KEEPINIT
option specifies the number of seconds to wait before the connection
attempt times out. For passive connections, the TCP_KEEPINIT option
value is inherited from the listening socket.
To display the values of the
inet
subsystem attributes, enter the following command at the system prompt:
The default value for TCP_KEEPINIT is 75 seconds 1. TCP_KEEPINIT option does not require the SO_KEEPALIVE option to be enabled. |
| TCP_KEEPINTVL | TCPIP$C_TCP_KEEPINTVL |
When the SO_KEEPALIVE option is enabled, TCP sends probes to the remote
system on a connection that has been idle for a period of time. The
TCP_KEEPINTVL option specifies the number of seconds to wait before
retransmitting a keepalive probe. The default value for this retransmit
interval is 75 seconds
1.
To display the values of the
inet
subsystem attributes, enter the following command at the system prompt:
|
| TCP_NODELAY | TCPIP$C_TCP_NODELAY |
Specifies that the
send()
operation not be delayed to merge packets.
Under most circumstances, TCP sends data when it is presented. When outstanding data has not yet been acknowledged, TCP gathers small amounts of the data into a single packet and sends it when an acknowledgment is received. This functionality can cause significant delays for some clients that do not expect replies (such as windowing systems that send a stream of events from the mouse). The TCP_NODELAY option disables the Nagle algorithm, which reduces the number of small packets on a wide area network. |
| TCP_MAXSEG | TCPIP$C_TCP_MAXSEG |
Sets the maximum transmission unit (MTU) of a TCP segment to a
specified integer value from 1 to 65535. The default is 576 bytes. Can
only be set before a
listen()
or
connect()
operation on the socket. For passive connections, the value is obtained
from the listening socket.
Note that TCP does not use an MTU value that is less than 32 or greater than the local network's MTU. Setting the option to zero results in the default behavior. |
| TCP_NODELACK | TCPIP$C_TCP_NODELACK | When specified, disables the algorithm that gathers outstanding data that has not been acknowledged and sends it in a single packet when acknowledgment is received. Takes an integer value. |
| TCP_PAWS | TCPIP$C_TCP_PAWS | When specified, the receiver rejects any old duplicate segments it receives. This option is used on synchronized TCP connections only, and requires that the TCP_TSOPTENA option be enabled also. |
| TCP_SACKENA | TCPIP$C_TCP_SACKENA | When specified, the receiver can inform the sender about all segments that arrive successfully. This allows the sender to retransmit only those segments that have actually been lost. This option is useful in cases where multiple segments are dropped. |
| TCP_TSOPTENA | TCPIP$C_TSOPTENA | When specified, the sender places a timestamp in each data segment. The receiver, if configured to accept them, sends these times back in the acknowledgement (ACK) segments. This allows the sender to measure the round-trip communication time. |
| TCP protocol options that are obsolete but provided for backward compatibility | ||
| TCP_DROP_IDLE | TCPIP$C_TCP_DROP_IDLE |
When the TCP_KEEPALIVE option is enabled, the TCP_DROP_IDLE option
specifies the time interval after which a connection is dropped. The
value of TCP_DROP_IDLE is an integer specified in seconds.
When the TCP_DROP_IDLE option is set, the value of the TCP_KEEPCNT option is calculated as the value of TCP_DROP_IDLE divided by the value of TCP_KEEPINTVL. A call to getsockopt() function specifying the TCP_DROP_IDLE option returns the result of multiplying the values of TCP_KEEPCNT and TCP_KEEPINTVL. |
| TCP_PROBE_IDLE | TCPIP$C_TCP_PROBE_IDLE |
When the TCP_KEEPALIVE option is enabled, the TCP_PROBE_IDLE option
specifies the time interval between the keepalive probes and for the
connections establishing the timeout. The value of TCP_PROBE_IDLE is an
integer specified in seconds.
When this option is set, TCP_KEEPINTVL, TCP_KEEPIDLE and TCP_KEEPINIT are set to the value specified for TCP_PROBE_IDLE. A call to the getsockopt() function specifying the TCP_PROBE_IDLE option returns the value of TCP_KEEPINTVL. |
| Previous | Next | Contents | Index |