HP OpenVMS Systems Documentation

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

The IO$_SETMODE and IO$_SETCHAR functions set one or more parameters (characteristics) pertaining to the network driver.

Sockets are created using the IO$_SETMODE p1 argument. Names are assigned to sockets using the IO$_SETMODE p3 argument. Active sockets are converted to passive sockets using the IO$_SETMODE p4 argument. Other parameters, such as socket and protocol options, are specified in an input parameter list using the IO$_SETMODE p5 argument.

The IO$_SETMODE p1, p3, and p4 arguments can be used with the p5 argument in a single $QIO system service to set socket names as well as socket and protocol options. IO$_SETMODE processes arguments in this order: p1, p3, p4, p5. If IO$_SETMODE detects an error, the I/O status block (IOSB) contains the error and argument address or the value that was at fault.

Refer to individual argument descriptions for details about specifying the type and format of input parameters.

Arguments

p1

OpenVMS usage:	socket_characteristics
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Longword specifying the protocol, socket type, and address family of a new socket. The p1 argument is the address of the longword containing the socket characteristics.

The newly created socket is marked privileged if the image that creates a socket runs in a process that has BYPASS, OPER, or SYSPRV privilege.

The following table shows protocol codes:

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

Table 6-6 lists the socket types.

Table 6-6 Socket Types

Socket Type	Description
TCPIP$C_STREAM	Permits bidirectional, reliable, sequenced, and unduplicated data flow without record boundaries.
TCPIP$C_DGRAM	Permits bidirectional data flow with record boundaries. No provisions for sequencing, reliability, or unduplicated messages.
TCPIP$C_RAW	Permits access to the IP layer; used to develop new protocols that are layered upon the IP layer.

The following table shows address family codes:

Address Family	Description
TCPIP$C_AF_INET	IPv4 Internet domain (default).
TCPIP$C_AF_INET6	IPv6 Internet domain.
TCPIP$C_AUXS	Accept hand-off of a socket already created and initialized by the auxiliary server.

The equivalent Sockets API function is socket() .

p3

OpenVMS usage:	socket_name
type:	vector byte (unsigned)
access:	read only
mechanism:	by item_list_2 descriptor

The local name (that is, port number and IP address) to assign to the socket. The p3 argument is the address of an item_list_2 descriptor that points to the socket address structure containing the local name.

The equivalent Sockets API function is bind() .

p4

OpenVMS usage:	connection_backlog
type:	byte (unsigned)
access:	read only
mechanism:	by value

Maximum limit of outstanding connection requests for a socket that is connection oriented. If more connection requests are received than are specified, the additional requests are ignored so that TCP retries can succeed.

The equivalent Sockets API function is listen() .

p5

OpenVMS usage:	input_parameter_list
type:	vector byte (unsigned)
access:	read only
mechanism:	by item_list_2 descriptor

Input parameter list describing one or more parameters to set. The p5 argument is the address of an item_list_2 descriptor that points to and identifies the type of input parameter list.

The equivalent Sockets API functions are setsockopt() and ioctl() .

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	The service cannot access a buffer specified by one or more arguments.
SS$_BADPARAM	Programming error that occurred for one of the following reasons: $QIO system service was specified without a socket. Error occurred processing a socket or protocol option.
SS$_DEVINTACT	The network driver was not started.
SS$_DEVNOTMOUNT	The network driver is loaded, but the INETACP is not currently available for use.
SS$_DUPLNAM	Programming error. The port being bound is already in use. An attempt to bind the socket to an address and port failed.
SS$_FILALRACC	Programming error. The IP address is already in use. An attempt to bind the socket to an address and port failed.
SS$_ILLCNTRFUNC	Programming error. An attempt to perform an IO$_SETMODE function required a socket, but the device did not have one. Create a socket before issuing the function.
SS$_IVADDR	Programming error. The IP address you specified using the IO$_SETMODE function was not placed into the system. This resulted in an invalid port number or IP address combination. The IP address was invalid for one of the following reasons: An attempt was made to exceed the limit of allowable permanent entries in the ARP table. An attempt was made to bind a raw IP socket when there are no interfaces defined in the system. An attempt was made to bind a raw IP socket to a null Internet address.
SS$_INSFMEM	Insufficient system dynamic memory to complete the service.
SS$_IVBUFLEN	The size of a socket option buffer specified with the IO$_SETMODE function was invalid.
SS$_NOLICENSE	Programming or system management error. A TCP/IP Services license is not present.
SS$_NOOPER	Programming or INET management error. An attempt to was made 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: An attempt was made to broadcast an IP datagram on a process without SYSPRV, BYPASS, or OPER privilege. An attempt was made to use a reserved port number lower than 1024. An attempt was made to access a process that requires SYSPRV or BYPASS privilege. An attempt was made to use raw IP on a privileged socket that requires the SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV	Programming error or INET management error. An attempt was made to show or delete an ARP table entry failed because the IP address is not found.
SS$_NOSUCHNODE	Programming error or INET management error. An attempt was made to delete a route from the routing table failed because the entry was not found.
SS$_PROTOCOL	Programming error. A specified protocol or address family caused an error for one of the following reasons: An invalid protocol type was specified at socket creation. An unsupported protocol was specified. The address family is unsupported for one of the following reasons: An unsupported address family was specified. Instead, specify the address family (TCPIP$C_AF_INET, TCPIP$C_AF_INET6, or TCPIP$C_UNSPEC). An unsupported address family for the local IP address was specified. Instead, specify the address family (TCPIP$C_AF_INET or TCPIP$C_AF_INET6). An unsupported address family for the IP address of the routing module was specified. Instead, specify the address family (TCPIP$C_AF_INET or TCPIP$C_AF_INET6).
SS$_SHUT	The local or remote node is no longer accepting connections.

The IO$_SETMODE|IO$M_OUTBAND function/modifier combination requests that the asynchronous system trap (AST) for an out-of-band (OOB) character be delivered to the requesting process. This is to be done only when an OOB character is received on the socket and there is no waiting read request. The socket must be a TCP (stream) socket.

The Enable OOB character AST function allows an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before a new AST can be delivered. This function is subject to AST quotas.

Arguments

p1

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

To enable the AST, the p1 argument is the address of the OOB character AST routine. To disable the AST, p1 equals 0.

p2

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

AST parameter to be delivered to the AST routine specified by the p1 argument.

p3

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode to deliver the AST.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_ABORT	Programming, INET management, or hardware error.
SS$_ACCVIO	Programming error. An attempt to access an invalid memory location or buffer occurred.
SS$_BADPARAM	Programming error. A $QIO service with an invalid parameter occurred for one of the following reasons: An attempt was made to execute an IO$_SETMODE function (all functions except socket creation) without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and correct parameters. A socket option was specified incorrectly.
SS$_DEVACTIVE	INET management error. An attempt to change the static parameters occurred. If new parameters are needed, restart TCP/IP Services.
SS$_DEVINTACT	The network driver was not started.
SS$_DEVNOTMOUNT	The network driver is loaded but the INET_ACP is not currently available for use.
SS$_DUPLNAM	Programming error. An attempt to bind a port that is already in use occurred. An attempt to bind the socket to an address and port failed.
SS$_FILALRACC	Programming error. IP address is already in use. An attempt to bind the socket to an address and port failed.
SS$_INSFMEM	Programming or system management error: Not enough resources to allocate new socket.
SS$_ILLCNTRFUNC	Programming error. Operation is not supported because of one of the following reasons: Invalid IO$_SETMODE (IOCTL) function was used for the interface. The interface does not have an IOCTL routine. An attempt was made to perform an IO$_SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function.
SS$_IVADDR	The specified IP address was not found, or an invalid port number and IP address combination was specified. Port 0 is not allowed with this function.
SS$_IVBUFLEN	Programming error. The socket option buffer has an invalid size.
SS$_NOLICENSE	Programming or system management error. The TCP/IP Services license is not present.
SS$_NOOPER	Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege.
SS$_NOPRIV	Programming or INET management error. Not enough privileges for the attempted operation for one of the following reasons: Broadcasting an IP datagram was denied because the process does not have SYSPRV, BYPASS, or OPER privilege. An attempt was made to use a reserved port number lower than 1024. An operation accesses only processes that have SYSPRV or BYPASS privilege. Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV	Programming error or INET management error. An INET address is not in the ARP table. An attempt to show or delete an ARP table entry failed.
SS$_NOSUCHNODE	Programming or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found.
SS$_PROTOCOL	Programming error. The specified protocol type is not supported.
SS$_SHUT	The local or remote node is no longer accepting connections.

The IO$_SETMODE|IO$M_READATTN function/modifier combination requests that an Attention AST be delivered to the requesting process when a data packet is received on the socket and there is no waiting read request.

The Enable Read Attention AST function enables an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before the AST can occur again. The function is subject to AST quotas.

Consider the following when using IO$M_READATTN:

• There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For each enabled AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when an event occurs.
• If an out-of-band (OOB) Attention AST is enabled, the OOB AST is delivered, regardless of the following:
  • An enabled Read Attention AST
  • The TCPIP$C_OOBINLINE socket option
  • A READ $QIO waiting for completion on the socket

If the TCPIP$C_OOBINLINE option is set, then a waiting READ $QIO is completed and the OOB character is returned in the data stream.

• If both an OOB AST and a Read Attention AST are enabled, only the OOB AST is delivered when an OOB character is received.
• If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE socket option is set, a waiting READ $QIO completes and the OOB character is returned in the data stream.
• If a Read Attention AST is enabled and the TCPIP$C_OOBINLINE socket option is not set (clear), the Read Attention AST is delivered when an OOB character is received, regardless of whether a READ $QIO is waiting for completion. In this case, the OOB character is not returned in the data stream. Therefore, if the OOB character is the only character received, the READ $QIO does not complete.

Arguments

p1

OpenVMS usage:	ast_procedure
type:	procedure value
access:	call without stack unwinding
mechanism:	by reference

To enable the AST, the p1 argument is the address of the Read Attention AST routine. To disable the AST, set p1 to 0.

p2

OpenVMS usage:	user_arg
type:	longword (unsigned)
access:	read only
mechanism:	by value

AST parameter to be delivered to the AST routine.

p3

OpenVMS usage:	access_mode
type:	longword (unsigned)
access:	read only
mechanism:	by value

Access mode in which the AST is delivered.

Condition Values Returned

SS$_ABORT	Programming, INET management, or hardware error. The route entry already exists, so the attempt to add a route entry using the IO$_SETMODE function failed.
SS$_ACCVIO	Programming error. An attempt to access an invalid memory location or buffer occurred.
SS$_BADPARAM	Programming error. The parameter specified for a $QIO function was invalid for one of the following reasons: An attempt to execute the IO$_SETMODE functions without specifying a device socket occurred. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. A socket option was specified incorrectly.
SS$_DEVACTIVE	INET management error. An attempt to change a static parameter was unsuccessful. If you need new parameters, restart TCP/IP Services.
SS$_DEVINTACT	The network driver was not started.
SS$_DEVNOTMOUNT	The network driver is loaded but the INET_ACP is not currently available for use.
SS$_DUPLNAM	Programming error. An attempt to bind a port already in use occurred so the operation to bind the socket to the address and port failed.
SS$_FILALRACC	Programming error. An attempt to bind the socket to an address that is already in use occurred and the operation failed.
SS$_INSFMEM	Programming or system management error. The system does not have enough resources to allocate new socket.
SS$_ILLCNTRFUNC	Programming error. Operation is not supported. Invalid IO$_SETMODE (IOCTL) function was used for the interface. The interface does not have an IOCTL routine. An attempt was made to perform an IO$_SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function.
SS$_IVADDR	Programming error. The specified IP address is not in the system, and an invalid port number or an invalid IP address combination was specified with an IO$_SETMODE function (a bind). An attempt to bind the address failed because the IP address is not in the system, Port 0 and IP address 0 are not allowed, or Port 0 is not allowed when using an IO$_ACCESS function. An attempt was made to make a permanent entry in the ARP table failed because of lack of space. Too many permanent entries. An attempt was made to bind an IP socket (raw IP) when there are no interfaces defined in the system. An attempt was made to bind an IP socket (raw IP) to a null INET address.
SS$_IVBUFLEN	Programming error. The socket option buffer has an invalid size.
SS$_NOLICENSE	Programming or system management error. The TCP/IP Services license is not present.
SS$_NOOPER	Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege.
SS$_NOPRIV	Programming or INET management error. Not enough privileges for the attempted operation. Broadcasting an IP datagram was denied because the process does not have SYSPRV, BYPASS, or OPER privilege. An attempt was made to use a reserved port number lower than 1024. An operation accesses only processes that have SYSPRV or BYPASS privilege. Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege.
SS$_NOSUCHDEV	Programming error or INET management error. An Internet address is not in the ARP table. An attempt to show or delete an ARP table entry failed.
SS$_NOSUCHNODE	Programming error or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found.
SS$_PROTOCOL	Programming error. The specified protocol type is not supported.
SS$_SHUT	The local or remote node is no longer accepting connections.