hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP TCP/IP Services for OpenVMS

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming


Previous Contents Index

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

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.


Appendix A
Socket Options

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.

The following tables list:

Table A-1 lists the socket options that are set at the SOL_SOCKET level and their Sockets API and system service symbol names.

Table A-1 Socket Options
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.

Table A-2 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:

$ TCPIP sysconfig -q inet

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:

$ TCPIP sysconfig -q inet

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:

$ TCPIP sysconfig -q inet

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:

$ TCPIP sysconfig -q inet

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.


1The value of this option is stored internally as half-seconds. When setting or retrieving the value of the systemwide parameter, the value is expressed as half-seconds. When setting or retrieving the value of the socket option, the value is expressed as seconds.


Previous Next Contents Index