HP OpenVMS Systems Documentation
Content starts here

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

Previous Contents Index

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

The network pseudodevice allows physical, logical, and virtual I/O functions. The physical and logical I/O functions are used only with the IP layer. Table 6-2 lists the basic I/O functions and their modifiers. The sections that follow describe in greater detail the operation of these 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.

IO$_ACCESS

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.

IO$_ACCESS|IO$M_ACCEPT

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.

IO$_ACPCONTROL

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.
1You can limit the maximum amount of time spent obtaining host names and addresses by entering the command TCPIP SET NAME_SERVICE/TIMEOUT=1/RETRY=1

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


OpenVMS usage: char_string
type: character-coded text string
access: read only
mechanism: by descriptor-fixed-length string descriptor

Input string for the network ACP operation containing one of the following: host IP address, host name, network IP address, or network name. The p2 argument is the address of a string descriptor pointing to the input string. The input string must be in an area of memory that is capable of being read and written to.

All IP addresses are specified in dotted-decimal notation.

p3


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

Length in bytes of the output buffer returned by IO$_ACPCONTROL. The p3 argument is the address of a word in which the length of the output buffer is written.

p4


OpenVMS usage: buffer
type: vector byte (unsigned)
access: write only
mechanism: by descriptor-fixed-length descriptor

Buffer into which IO$_ACPCONTROL writes its output data. The p4 argument is the address of a descriptor pointing to the output buffer.

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.

Previous Next Contents Index