The Set Mode and Set Characteristics I/O functions perform mode, operational, and program/driver interface operations with the internet device socket. These two functions work in exactly the same manner. They take the following form:

• IO$_SETMODE
• IO$_SETCHAR

The protocol you use determines when you can change the mode or characteristics:

• Connectionless protocols (datagram or raw IP ) --- Can be changed any time.
• Connection-oriented protocols (TCP/IP) --- Can only be changed when the device socket is closed, such as before a connection is established (opened) or after the connection is closed. While a connection is open (active), only parameters that do not affect the connection characteristics may be changed.
  The routine processes parameters sequentially. If it finds an error, the routine aborts. Any parameters correctly specified before the routine encounters an error are properly processed before the routine aborts.
  The equivalent C Socket functions are socket(), bind(), listen(), setsockopt() or ioctl().

Arguments

p1

usage	socket definition (socket type, protocol, and INET domain)
type	longword (unsigned)
access	read only
mechanism	by reference

The p1 argument specifies the address of a buffer containing the socket characteristics. The C Socket equivalent for this is socket().

The socket characteristics buffer is one longword. The first two bytes contain the protocol, the third byte contains the socket type (protocol type), and the fourth byte contains the domain name (the internet, by default).

Both the protocol and the socket type are contained in one longword value.

Table 4-13 lists the valid protocols.

Table 4-13 Valid Protocols for IO$_SETMODE and IO$_SETCHAR

Protocol	Description
TCPIP$C_TCP	TCP/IP
TCPIP$C_UDP	UDP/IP
TCPIP$C_RAW_IP	IP

Table 4-14 lists the valid socket types.

Table 4-14 Valid Socket Types for IO$_SETMODE and IO$_SETCHAR

Socket Type	Description
TCPIP$C_STREAM	The communications protocol is a bidirectional, reliable, sequenced, and unduplicated data flow without record boundaries.
TCPIP$C_DGRAM	The communications protocol is a bidirectional data flow with record boundaries. There are no provisions for sequence, reliability, or duplication of messages.
TCPIP$C_RAW	Allows access to the lower layer (IP layer) of the internet communication protocol. It is used to develop new communication protocols that are to be layered on the IP layer.

If the image that creates the socket runs in a process that has a privileged UIC or has SYSPRV, BYPASS, or OPER privileges, the socket is marked privileged.

Note The p2 argument is not used with the IO$_SETMODE routine. It is used when you specify either the IO$M_OUTBAND, IO$M_READATTN, or IO$M_WRTATTN function modifiers. See the descriptions for IO$_SETMODE|IO$M_OUTBAND, IO$_SETMODE|IO$M_READATTN, and IO$_SETMODE|IO$M_WRTATTN for details.

p3

usage	local socket name
type	longword (unsigned)
access	read only
mechanism	by descriptor

The p3 argument specifies the address of an item_list_2 descriptor of a buffer that specifies the local socket name (port and local host internet address). The parameter name for the descriptor is TCPIP$C_SOCK_NAME, which is defined in the TCPIP$INETDEF symbol definition file.

The C Socket equivalent is bind().

p4

usage	number of connections to accept
type	byte (unsigned)
access	read only
mechanism	by value

The p4 argument specifies the number of connections that can be established simultaneously and held by the listener socket before the program accepts the connections on the socket associated with the device (TCP/IP only). If more connections are received than have been specified, the additional connections are ignored so that TCP retries can succeed.

The C Socket equivalent is listen().

p5

usage	item_list_2
type	longword (unsigned)
access	read only
mechanism	by descriptor

The p5 argument specifies the address of a descriptor that lists item_list_2 descriptors. The C Socket equivalent is setsockopt().

Each item_list_2 descriptor describes a group of parameters of a specific type.

The following are the parameter types for the DIGITAL TCP/IP Services for OpenVMS descriptor to which the p5 points:

• TCPIP$C_SOCKOPT (communication socket option parameter)
• TCPIP$C_TCPOPT (TCP options)
• TCPIP$C_IPOPT (IP options)
• TCPIP$C_IOCTL (I/O control parameter)

You can use one $QIO system call to set up several socket options at once. The item_list_2 descriptor points to an integer (with the length set to the size of the integer). The integer contains zero to clear the option and nonzero to set the option.

The TCPIP$C_SOCKOPT parameter specifies the communication socket options. Table 4-15 describes the socket options you use with the TCPIP$C_SOCKOPT parameter type.

Unsupported socket options are ignored.

Table 4-16 describes the socket options you use with the TCPIP$C_TCPOPT parameter type.

Table 4-17 describes the options you use with the TCPIP$C_IPOPT parameter type.

Table 4-15 Communications Socket Options

Socket Option	Description
TCPIP$C_BROADCAST	Permits the sending of broadcast messages. Takes an integer parameter and requires a system user identification code (UIC) or SYSPRV, BYPASS, or OPER privilege. Optional for connectionless datagram.
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.
TCPIP$C_FULL_DUPLEX_CLOSE	When set before a close operation, both receive and transmit sides of the communications are closed.
TCPIP$C_KEEPALIVE	Keeps connections active. Enables the periodic transmission of messages on a connected socket. If the connected socket fails to respond to the messages, the connection is broken.
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. Takes a linger structure parameter as defined in <socket.h>to specify the state of the option and linger interval. If TCPIP$C_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 continue as quickly as possible.
TCPIP$C_OOBINLINE	Leaves the received out-of-band (OOB) data (data marked urgent) in line. Takes an integer parameter.
TCPIP$C_RCVBUF	Sets the receive buffer size. Takes an integer value and requires a system UIC or SYSPRV, BYPASS, or OPER privilege.
TCPIP$C_RCVTIMEO	For Compaq use only. Sets the timeout value for a recv() operation.
TCPIP$C_REUSEADDR	Specifies that the rules used in validating addresses supplied by a bind() function should allow reuse of local addresses. Takes an integer parameter.
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.
TCPIP$C_SHARE	Allows multiple processes to share the socket.
TCPIP$C_SNDBUF	Sets the send buffer size. Takes an integer parameter and requires a system UIC or SYSPRV, BYPASS, or OPER privilege. Optional for a connectionless datagram.
TCPIP$_SNDLOWAT	Sets the low-water mark for a send() operation. Takes an integer parameter.
TCPIP$_SNDTIMEO	For Compaq use only. Sets the timeout value for a send() operation.

Table 4-16 TCP/IP Options

TCP/IP Option	Description
TCPIP$C_TCP_DROP_IDLE	When the TCPIP$C_KEEPALIVE option is enabled, specifies the time interval after which a connection is dropped. Default: 2 hours. Takes an integer value in the range of 1 to n, where n is TCPIP$C_TCP_DROP_IDLE divided by PR_SLOWHZ.
TCPIP$C_TCP_KEEPCNT	When the TCPIP$C_KEEPALIVE option is enabled, specifies the maximum number of keepalive probes to be sent. Default: 8. Takes an integer value, with a range of 1 to TCP_KEEPCNT.
TCPIP$C_TCP_KEEPINIT	Specifies the number of seconds to wait before the connect attempt times out. Default: 75 seconds. For passive connections, the value is inherited from the listening socket. Takes an integer value in the range of 1 to n, where n is TCPIP$C_TCP_KEEPINIT divided by PR_SLOWHZ.
TCPIP$C_TCP_NODELAY	Specifies that the send() operation will not be delayed to merge packets.
TCPIP$C_TCP_MAXSEG	Sets the maximum transmission unit (MTU) of a TCP segment to a specified integer value from 1 to 65,535. Default: 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.
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 acknowledgement is received. Takes an integer value. 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 acknowledgement is received. This functionality can cause significant delays for some clients (such as windowing systems that send a stream of events from the mouse that do not expect replies).
TCPIP$C_TCP_PROBE_IDLE	When the TCPIP$C_KEEPALIVE option is enabled, specifies the time interval for the keepalive probe and for the connections establishing the timeout. Default: 75 seconds. Takes an integer value in the range of 1 to n, where n is TCPIP$C_TCP_PROBE_IDLE value divided by PR_SLOWHZ.
TCPIP$C_USELOOPBACK	For Compaq use only. Valid for routing sockets. Determines if a sending socket receives a copy of its own message. Used when a set on another socket type is ignored.

Table 4-17 IP Options

IP Option	Description
TCPIP$C_IP_ADD_MEMBERSHIP	Adds the host to the membership of a multicast group. A host must become a member of a multicast group before it can receive datagrams sent to the group. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. Up to IP_MAX_MEMBERSHIPS (currently 20) memberships may be added on a single socket.
TCPIP$C_IP_DROP_MEMBERSHIP	Removes the host from the membership of a multicast group.
TCPIP$C_IP_HDRINCL	If specified, the IP header is not prepended to the outgoing packet.
TCPIP$C_IP_MULTICAST_IF	For hosts with multiple interfaces. When specified, each multicast transmission is sent from the primary network interface. Overrides the default for subsequent transmissions from a given socket.
TCPIP$C_IP_MULTICAST_LOOP	Disables loopback of local delivery. If a multicast datagram is sent to a group of which the sending host is a member, a copy of the datagram is looped back by the IP layer for local delivery (default). To disable the loopback delivery, specify the value 0.
TCPIP$C_IP_MULTICAST_TTL	Specifies the time-to-live (TTL) value for outgoing multicast datagrams. Takes an integer value between 0 and 255: Value Action 0 Restricts distribution to applications running on the local host. 1 Forwards the multicast datagram to hosts on the local subnet. 1-255 With a multicast router attached to the sending host's network, forwards multicast datagrams beyond the local subnet. Multicast routers forward the datagram to known networks that have hosts belonging to the specified multicast group. The TTL value is decremented by each multicast router in the path. When the TTL value is decremented to 0, the datagram is no longer forwarded.
TCPIP$C_IP_OPTIONS	Provides IP options to be transmitted in the IP header of each outgoing packet.
TCPIP$C_IP_RECVDSTADDR	Enables a SOCK_DGRAM socket to receive the destination IP address for a UDP datagram.
TCPIP$C_IP_RECVOPTS	Enables a SOCK_DGRAM socket to receive IP options.
TCPIP$C_IP_TTL	Time to live (TTL) for a datagram.
TCPIP$C_IP_TOS	Type of service (1-byte value).

The TCPIP$C_IOCTL parameter specifies the I/O control parameters. The list of the IOCTL parameters contains two entries of longwords: the IOCTL command (first longword) and the address of the required buffer structure (second longword).

To set TCPIP$C_IOCTL, you need a system UIC, SYSPRV, BYPASS, or OPER privileges.

You can specify multiple IO$_SETMODE parameters with one $QIO system service call. For example, one $QIO system service call could specify a list of socket options or a list of IOCTL commands, combined with a local socket name.

When an error is detected, the iosb argument specifies the error and parameter address or value that was at fault.

The TCP/IP Services software processes parameter values for arguments in the following order: p1, p3, p4, and p5.

You can specify multiple lists of socket options or IOCTL commands. If a parameter, parameter list, or IOCTL command is duplicated by using the same return address, then the value returned is the last option or IOCTL command.

Condition Values Returned

SS$_ABORT	Programming error, INET management error, or hardware error. The route entry already exists. An attempt to add a route entry with IO$_SETMODE (IOCTL) system service call failed.
SS$_ACCVIO	Programming error. You tried to access an invalid memory location or buffer.
SS$_BADPARAM	Programming error. You specified a $QIO function with an invalid parameter that was a result of one of the following: You tried to execute IO$_SETMODE function (all subfunctions, except socket creation) without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. You made an error specifying a socket option.
SS$_DEVACTIVE	INET management error. You attempted to change the static INET parameters. If new parameters are needed, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command.
SS$_DEVINACT	INET management error. The driver is not started. Issue a START COMMUNICATION command before issuing $QIO functions.
SS$_DEVNOTMOUNT	INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again.
SS$_DUPLNAM	Programming error. The port being bound is already in use. You attempted to bind the socket to an address and port and the operation failed.
SS$_EXQUOTA	Programming or INET management error occurred for one of the following reasons: You tried to create a new socket with the IO$_SETMODE function, but the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter). The number of sockets specified with the IO$_SETMODE (listen) exceeds the maximum number of sockets. Increase the maximum number of sockets (INET parameter) or reduce the listen parameter (the number of sockets the listener socket can create).
SS$_FILALRACC	Programming error. The INET address is already in use. You attempted to bind the socket to an address and port and the operation failed.
SS$_INSFMEM	Programming or system management error. There are not enough resources to allocate a new socket.
SS$_ILLCNTRFUNC	Programming error. The operation is not supported for one of the following reasons: You used an invalid IO$_SETMODE function for the interface that does not have an IOCTL routine. You tried to perform an IO$_SETMODE function that required a socket, but the device did not have one. Create a socket before issuing the function.
SS$_IVADDR	Programming error. The INET address you specified using the IO$_SETMODE function was not placed into the system. This resulted in an invalid port number or INET address combination. The INET address was invalid for one of the following reasons: Port zero and INET address zero are not allowed or port zero is not allowed when using an IO$_ACCESS or IO$_WRITEVBLK function. You attempted to exceed the limit of allowable permanent entries in the ARP table. You attempted to bind a raw IP socket when there are no interfaces defined in the system. You attempted to bind a raw IP socket to a null INET address.
SS$_IVBUFLEN	Programming error. The socket option buffer has an invalid size.
SS$_NOLICENSE	Programming or system management error. A DIGITAL TCP/IP Services for OpenVMS license is not present.
SS$_NOOPER	Programming or INET management error. You attempted to execute an I/O function that needs the OPER privilege.
SS$_NOPRIV	Programming or INET management error. There are not enough privileges for the attempted operation for one of the following reasons: You attempted to broadcast an IP datagram on a process without system UIC, SYSPRV, BYPASS, or OPER privileges. You attempted to use a reserved port number lower than 1024. You attempted to access a process that requires system UIC, SYSPRV, or BYPASS privileges. You attempted to use raw IP on a privileged socket that requires the SYSPRV or BYPASS privileges.
SS$_NOSUCHDEV	Programming error or INET management error. Your attempt to show or delete an ARP table entry failed because the INET address is not found.
SS$_NOSUCHNODE	Programming error or INET management error. Your attempt to delete a route from the routing table failed because the entry was not found.
SS$_PROTOCOL	Programming error. You specified a protocol or address family that caused an error for one of the following reasons: You specified an invalid protocol type at socket creation. You specified an unsupported protocol. You specified a protocol type that was not found in the internal tables. The address family is unsupported for one of the following reasons: You specified an unsupported address family with the IO$_SETMODE subfunction. Instead, specify the TCPIP$C_AF_INET or TCPIP$C_UNSPEC address family. You specified an unsupported address family for a remote INET address with the IO$_ACCESS or IO$_WRITEVBLK function. Instead, specify the TCPIP$C_AF_INET address family. You specified an unsupported address family for the local INET address with the IO$_SETMODE function. Instead, specify the TCPIP$C_AF_INET address family. You specified an unsupported address family for the INET address of the routing module. Instead, specify the TCPIP$C_AF_INET address family.
SS$_SHUT	The network is being shut down.