HP OpenVMS systems documentation

For TCP/IP Services, $QIO uses the following system resources:

• The process's AST limit (ASTLM) quota, if an AST service routine is specified.
• System dynamic memory, which is required to queue the I/O request. System dynamic memory requirements are protocol specific.
• Additional memory, on a device-dependent basis.

For $QIO, completion can be synchronized as follows:

• By specifying the astadr argument to have an AST routine execute when the I/O is completed.
• By calling the $SYNCH synchronize service to await completion of the I/O operation. (If you want your I/O operation to complete synchronously, use the $QIOW system service instead.)

Condition Values Returned

Each function used with $QIO has its own error codes. See the error codes listed under the individual descriptions of the I/O function code in the remainder of this chapter.

6.2 Network Pseudodevice Driver I/O Functions

Table 6-2 Network Pseudodevice Driver I/O Functions

Function Code and Arguments	Function Modifier	Description
IO$_ACCESS p3,p4	IO$M_ACCEPT IO$M_EXTEND IO$M_NOW	Opens a connection.
IO$_ACPCONTROL p1, p2, p3, p4		Performs an ACP (ancillary control process) operation.
IO$_DEACCESS p4	IO$M_NOW IO$M_SHUTDOWN	Aborts or closes a connection.
IO$_READVBLK p1,p2,p3,p4,p6	IO$M_EXTEND IO$M_INTERRUPT	Reads a virtual block.
	IO$M_LOCKBUF IO$M_PURGE	Controls the buffer operations.
IO$_SENSEMODE p2, p3,p4,p6		Reads the network pseudodevice characteristics.
IO$_SENSECHAR p2, p3,p4,p6		Reads the network pseudodevice characteristics.
IO$_SETMODE p1, p2, p3,p4,p5	IO$M_OUTBAND IO$M_READATTN IO$M_WRTATTN	Sets the network pseudodevice characteristics for subsequent operations.
IO$_SETCHAR p1, p2, p3,p4,p5	IO$M_OUTBAND IO$M_READATTN IO$M_WRTEATTN	Sets the network pseudodevice characteristics for subsequent operations.
IO$_WRITEVBLK p1,p2,p3,p4,p5	IO$M_INTERRUPT	Writes a virtual block.

Table 5-2 lists the file names of the symbol definition files. These files specify $QIO arguments (p1,p2,...p6) for applications written in the corresponding programming languages. You must invoke the symbol definition by using the appropriate statement in your application.

When using a connection-oriented protocol, such as TCP, the IO$_ACCESS function initiates a connection and specifies a remote port number and IP address. When using a connectionless protocol, such as UDP, the IO$_ACCESS function sets the remote port number and IP address.

For TCP, a connection request times out at a specified interval (75 seconds is the default). This interval can be changed by setting the inet subsystem parameter tcp_keepinit . The program can also set a specific timeout interval for a socket that it has created, as described in Table A-2.

If a connection fails, you must deallocate the socket and then create a new socket before trying to reconnect.

Related Functions

The equivalent Sockets API function is connect() .

Arguments

p3

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

The remote port number and IP address of the host to connect. The p3 argument is the address of an item_list_2 descriptor that points to the socket address structure containing the remote port number and IP address.

Function Modifiers

IO$M_NOW

Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	Programming error that occurred for one of the following reasons: $QIO system service was specified without a socket. An IO$_ACCESS function was specified without the address of a remote socket name ( p3 was null).
SS$_BUGCHECK	Inconsistent state. Report the problem to your HP support representative.
SS$_CANCEL	The I/O operation was canceled by a $CANCEL system service.
SS$_CONNECFAIL	The connection to a network object timed out or failed.
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	A network configuration error. No ports were available for new connections.
SS$_EXQUOTA	The process has exceeded a process quota.
SS$_FILALRACC	The specified socket name is already in use by one of the following: On a raw socket, the remote IP address was already specified on a previous IO$_ACCESS call. On a datagram, the remote IP address was already specified on a previous IO$_ACCESS call. On a stream socket, the IO$_ACCESS function targeted a stream socket that was already connected.
SS$_ILLCNTRFUNC	Illegal function.
SS$_INSFMEM	Insufficient system dynamic memory to complete the service.
SS$_IVADDR	The specified IP address was not found, or an invalid port number and IP address combination was specified with the IO$_ACCESS function. Port 0 is not allowed with the IO$_ACCESS function.
SS$_IVBUFLEN	The size of the socket name structure specified with the IO$_ACCESS function was invalid.
SS$_LINKABORT	The remote socket closed the connection.
SS$_NOLICENSE	The TCP/IP Services license is not present.
SS$_PROTOCOL	A network protocol error occurred. The address family specified in the socket address structure is not supported.
SS$_REJECT	The network connection is rejected for one of the following reasons: An attempt was made to connect to a remote socket that is already connected. An error was encountered while establishing the connection The peer socket refused the connection request or is closing the connection.
SS$_SHUT	The local or remote node is no longer accepting connections.
SS$_SUSPENDED	The system detected a condition that might cause the operation to block.
SS$_TIMEOUT	A TCP connection timed out before the connection could be established.
SS$_UNREACHABLE	The remote node is currently unreachable.

This function is used with a connection-based protocol, such as TCP, to accept a new connection on a passive socket.

This function completes the first connection on the queue of pending connections.

Related Functions

The equivalent Sockets API function is accept() .

Arguments

p3

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

The remote port number and IP address of a new connection. The p3 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the remote port number and IP address of the new connection is written.

p4

OpenVMS usage:	channel
type:	word (unsigned)
access:	write only
mechanism:	by reference

The I/O channel number assigned to a new connection. The p4 argument is the address of a word into which the new connection's channel number is written.

Function Modifiers

IO$M_EXTEND	Allows the usage of BSD Version 4.4 formatted socket address structures. Use this modifier to operate in the IPv6 environment.
IO$M_NOW	Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the operation to block, the system completes the I/O operation and returns the SS$_SUSPENDED status code.

Condition Values Returned

SS$_NORMAL	The service completed successfully.
SS$_BADPARAM	Programming error that occurred for one of the following reasons: $QIO system service was specified without a socket. A IO$_ACCESS|IO$M_ACCEPT function was specified without the address of the channel for the new connection ( p4 was null or invalid).
SS$_BUGCHECK	Inconsistent state. Report the problem to your HP support representative.
SS$_CANCEL	The I/O operation was canceled by a $CANCEL system service.
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$_EXQUOTA	The process has exceeded a process quota.
SS$_FILALRACC	The specified socket name is already in use by one of the following: On a raw socket, the remote IP address was already specified on a previous IO$_ACCESS call. On a datagram, the remote IP address was already specified on a previous IO$_ACCESS call. On a stream socket, the IO$_ACCESS function targeted a stream socket that was already connected.
SS$_ILLCNTRFUNC	Illegal function.
SS$_INSFMEM	Insufficient system dynamic memory to complete the service.
SS$_IVADDR	The specified IP address was not found, or an invalid port number and IP address combination was specified with the IO$_ACCESS function. Port 0 is not allowed with the IO$_ACCESS function.
SS$_IVBUFLEN	The size of the socket name structure specified with the IO$_ACCESS function was invalid.
SS$_LINKABORT	The remote socket closed the connection.
SS$_NOLICENSE	The TCP/IP Services license is not present.
SS$_PROTOCOL	A network protocol error occurred. The address family specified in the socket address structure is not supported.
SS$_REJECT	The network connection is rejected for one of the following reasons: An attempt was made to connect to a remote socket that is already connected. An error was encountered while establishing the connection The peer socket refused the connection request or is closing the connection.
SS$_SHUT	The local or remote node is no longer accepting connections.
SS$_SUSPENDED	The system detected a condition that might cause the operation to block.
SS$_TIMEOUT	A TCP connection timed out before the connection could be established.
SS$_UNREACHABLE	The remote node is currently unreachable.

The IO$_ACPCONTROL function accesses the network ACP to retrieve information from the host and the network database files.

Related Functions

The equivalent Sockets API functions are gethostbyaddr() , gethostbyname() , getnetbyaddr() , and getnetbyname() .

Arguments

p1

OpenVMS usage:	subfunction_code
type:	longword (unsigned)
access:	read only
mechanism:	by descriptor-fixed-length descriptor

A longword identifying the network ACP operation to perform. The p1 argument is the address of a descriptor pointing to this longword.

To specify the network ACP operation to perform, select a subfunction code from Table 6-3 and a call code from Table 6-4.

Table 6-3 defines subfunction codes for network ACP operations.

.

Table 6-3 Subfunction Codes

Subfunction Code	Description
INETACP_FUNC$C_GETHOSTBYADDR	Get the host name of the specified IP address from the hosts database. 1
INETACP_FUNC$C_GETHOSTBYNAME	Get the IP address of the specified host from the hosts database. 1
INETACP_FUNC$C_GETNETBYADDR	Get the network name of the specified IP address from the network database.
INETACP_FUNC$C_GETNETBYNAME	Get the IP address of the specified network from the network database.

Table 6-4 defines call codes for network ACP operations.

Table 6-4 Call Codes

Call Code	Description
INETACP$C_ALIASES	Returns the list of alias names associated with the specified host or network from the internet hosts or network database.
INETACP$C_TRANS	Returns the IP address associated with the specified host or network as a 32-bit value in network byte order.
INETACPC$C_HOSTENT_OFFSET	Returns full host information in a modified hostent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure.
INETACP$C_NETENT_OFFSET	Returns full network information in a modified netent structure. In the modified structure, pointers are replaced with offsets from the beginning of the structure.

IO$_ACPCONTROL searches the local hosts database for the host's name. If a matching host name is not found in the local hosts database, IO$_ACPCONTROL then searches the BIND database if the BIND resolver is enabled.

p2

All IP addresses are specified in dotted-decimal notation.

p3

p4

The format of the data returned in the output buffer is dictated by the call code specified by the p1 argument.

• Strings returned by IO$_ACPCONTROL with a call code of INETACP$C_ALIASES consist of one of the following: host IP address, host name, network IP address, or network name. All IP addresses are formatted using dotted-decimal notation. Alias names are separated by a null character (0). The length of the returned string includes all null characters that separate alias names.
• IP addresses returned by IO$_ACPCONTROL with a call code of INETACP$C_TRANS are 32-bit values in network byte order.
• All hostent and netent structures returned by IO$_ACPCONTROL with a call code of INETACP$C_HOSTENT_OFFSET or INETACP$C_NETENT_OFFSET are modified; pointers are replaced with offsets from the beginning of the structure.

Condition Values Returned

SS$_NORMAL	The service completed successfully
SS$_ABORT	An error was detected while performing an ACP function.
SS$_BADPARAM	Programming or internal error. A bad parameter (name or address) was specified in the call.
SS$_BUFFEROVF	Programming error. There was not enough space for returning all alias names in the call.
SS$_ENDOFFILE	The information requested is not in the database.
SS$_ILLCNTRFUNC	Illegal function.
SS$_NOPRIV	The privilege level was insufficient for the execution of an ACP function.
SS$_RESULTOVF	The ACP overflowed the buffer in returning a parameter.
SS$_SHUT	The local or remote node is no longer accepting connections.