# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

Previous | Contents | Index

# 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 internet 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 internet address of the new connection is written.

> Use the IO$_ACCESS function with the IO$M_EXTEND modifier to specify a BSD Version 4.4 formatted socket address structure.

> ### 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.
> 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 Compaq 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 its socket quota or some other process quota.
> SS$_FILALRACC | The specified socket name is already in use by one of the following: On a raw socket, the remote internet address was already specified on a previous IO$_ACCESS call. On a datagram, the remote internet 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 internet address was not found, or an invalid port number and internet 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 internet address from the host database.
> INETACP_FUNC$C_GETHOSTBYNAME | Get the internet address of the specified host from the host database.
> INETACP_FUNC$C_GETNETBYADDR | Get the network name of the specified internet address from the network database.
> INETACP_FUNC$C_GETNETBYNAME | Get the internet 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 internet 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 host database for the host's name. If a matching host name is not found in the local host 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 internet address, host name, network internet address, or network name. The p2 argument is the address of a string descriptor pointing to the input string.

> All internet 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 one of the following: host internet address, host name, network internet address, or network name. All internet 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.
> - Internet addresses returned by IO$_ACPCONTROL with a call code of INETACP$C_TRANS are 32-bit value and 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 a GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
> SS$_BUFFEROVF | Programming error. There was not enough space for returning all alias names in a GET{HOST,NET}BY{NAME,ADDRESS} ACP call.
> SS$_ENDOFFILE | The information requested is not in the database.
> SS$_ILLCNTRFUNC | Illegal function.
> SS$_NOPRIV | No privilege 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.

# IO$_DEACCESS

> The IO$_DEACCESS function closes a connection and deletes a socket. Any pending messages queued for transmission are sent before tearing down the connection.

> When used with the IO$M_SHUTDOWN function modifier, the IO$_DEACCESS function shuts down all or part of a bidirectional connection on a socket. Use the p4 argument to specify the disposition of pending I/O operations on the socket.

> You can specify a wait time or time-to-linger socket parameter (TCPIP$C_LINGER option) for transmission completion before disconnecting the connection. Use the IO$_SETMODE or IO$_SETCHAR function to set and clear the TCPIP$C_LINGER option.

> If you set the TCPIP$C_LINGER option, a $QIO call that uses the IO$_DEACCESS function allows data queued to the socket to arrive at the destination. The system is blocked until data arrives at the remote socket. The socket data structure remains open for the duration of the TCP idle time interval.

> If you do not set the TCPIP$C_LINGER option (option is set to 0), a $QIO call that uses the IO$_DEACCESS function discards any data queued to the socket and deallocates the socket data structure.

> Note For compatibility with Compaq Tru64 UNIX, the TCP/IP Services forces a time to linger of 2 minutes on TCP stream sockets.

> Related Functions

> The equivalent Sockets API functions are `close()` and `shutdown()` .

## Arguments

> ### p4

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Longword of shutdown flags to specify the disposition of pending I/O operations on the socket. The p4 argument is used only with the IO$M_SHUTDOWN function modifier. The following table lists available shutdown flags.

> Shutdown Flag | Description
> --- | ---
> TCPIP$C_DSC_RCV | Discards messages from the receive queue and disallows further receiving. Pending messages in the receive queue for this connection are discarded.
> TCPIP$C_DSC_SND | Discards messages from the send queue and disallows sending new messages. Pending messages in the transmit queue for this connection are discarded.
> TCPIP$C_DSC_ALL | Discards all messages and disallows both sending and receiving. All pending messages are discarded. Specifying this flag has the same effect as issuing a $CANCEL QIO followed by an IO$_DEACCESS QIO without specifying any flags.

## Function Modifiers

> IO$M_SHUTDOWN | Causes all or part of a full-duplex connection on a socket to be shut down.
> 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 | The IO$_DEACCESS operation failed to specify a socket.
> 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$_NOLINKS | The specified socket was not connected.
> 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.

# IO$_READVBLK

> The IO$_READVBLK function transfers data received from an internet host to the specified user buffers. Use both p1 and p2 arguments to specify a single user buffer. Use the p6 argument to specify multiple buffers.

> For connection-oriented protocols, such as TCP, data is buffered in system space as a stream of bytes. The IO$_READVBLK function completes (1) when there is no more data buffered in system space for this socket, or (2) when there is no more available space in the user buffer. Data that is buffered in system space but did not fit in the user buffer is available to the user in subsequent $QIOs.

> For connectionless protocols, datagram and raw socket data is buffered in system space as a chain of records. The user buffer specified with a IO$_READVBLK function is filled with data that is buffered in one record. Each IO$_READVBLK reads data from one record. The IO$_READVBLK function completes (1) when all data from a record is transferred to the user buffer, or (2) when there is no more available space in the user buffer. Any data remaining in the current record that did not fit in the user buffer is discarded. A subsequent $QIO reads data from the next record buffered in system space.

> Use the management command SHOW DEVICE_SOCKET/FULL to display counters related to read operations.

> Related Functions

> The equivalent Sockets API functions are `read()` , `recv()` , `recvfrom()` , and `recvmsg()` .

## Arguments

> ### p1

> OpenVMS usage: | buffer
> type: | vector byte (unsigned)
> access: | read only
> mechanism: | by 32- or 64-bit reference (Alpha)

> The 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of the buffer to receive the incoming data. The length of this buffer is specified by the p2 argument.

> ### p2

> OpenVMS usage: | buffer_length
> type: | quadword unsigned (Alpha); longword unsigned (VAX)
> access: | read only
> mechanism: | by 64-bit value (Alpha)

> The length (in bytes) of the buffer available to hold the incoming data. The address of this buffer is specified by the p1 argument.

> ### p3

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

> The remote port number and internet address of the source of the datagram or raw IP message (not TCP). 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 internet address of the message source is written.

> Use the IO$_READVBLK function with the IO$M_EXTEND modifier to specify a BSD Version 4.4 formatted socket address structure. If the IO$M_EXTEND modifier is not specified, the IO$_READVBLK function returns a BSD Version 4.3 formatted socket address structure.

> ### p4

> OpenVMS usage: | mask_longword
> type: | longword (unsigned)
> access: | read only
> mechanism: | by value

> Longword of flags to specify attributes for the read operations. Table 6-5 lists the available read flags.

> Table 6-5 Read Flags
> Read Flag | Description
> --- | ---
> TCPIP$C_MSG_OOB | Reads an out-of-band byte.
> TCPIP$C_MSG_PEEK | Reads a message but leaves the message in the queue.
> TCPIP$C_MSG_NBIO | Does not block the I/O operation if the receive queue is empty (similar to using IO$M_NOWAIT).
> TCPIP$C_MSG_PURGE | Flushes data from the queue (similar to using IO$M_PURGE).
> TCPIP$C_MSG_BLOCKALL | Blocks the completion of the operation until the buffer is filled completely or until the connection is closed (similar to using IO$M_LOCKBUF).

> ### p6

> OpenVMS usage: | buffer_list
> type: | vector byte (unsigned)
> access: | read only
> mechanism: | by 32- or 64-bit descriptor-fixed-length descriptor (Alpha)

> Output buffer list describing one or more buffers to hold the incoming data. The p6 argument is the 32- or 64-bit address (on Alpha systems) or the 32-bit address (on VAX systems) of a descriptor that points to a output buffer list. Buffers are filled in the order specified by the output buffer list. The transfer-length value returned in the I/O status block is the total number of bytes transferred to all buffers.

> If you use the p1 and p2 arguments, do not use the p6 argument; they are mutually exclusive.

## Function Modifiers

> IO$M_EXTEND | Specifies the format of the socket address structure to return when used with the p3 argument. When specified, a BSD Version 4.4 formatted socket address structure is returned that identifies the source of the received UDP datagram or raw IP message.
> IO$M_INTERRUPT | Reads an out-of-band (OOB) message. This has the same effect as specifying the TCPIP$C_MSG_OOB flag in the p4 argument. On receiving a TCP/IP OOB character, TCP/IP stores the pointer in the received stream with the character that precedes the OOB character. A read operation with a user-buffer size larger than the size of the received stream up to the OOB character completes and returns to the user the received stream up to, but not including, the OOB character. To determine whether the socket must issue more read $QIOs before getting all the characters from the stream preceding an OOB character, poll the socket. To do this, issue a $QIO with the $IO_SENSEMODE function, and the TCPIP$C_IOCTL subfunction that specifies the SIOCATMARK command. The SIOCATMARK values are as follows: 0 = Issue more read QIOs to read more data before reading the OOB. 1 = The next read QIO will return the OOB. Polling a socket is particularly useful when the OOBINLINE socket option is set. When the OOBINLINE is set, TCP/IP reads the OOB character with the characters in the stream (IO$_READVBLK), but not before reading the preceding characters. Use this polling mechanism to determine whether the first character in the user buffer on the next read is an OOB character. On a socket without the OOBINLINE option set, a received OOB will always be read by issuing a $QIO with either the IO$_READVBLK|IO$M_INTERRUPT or IO$_READVBLK and the TCPIP$C_MSG_OOB flag set. This can occur regardless of how many preceding characters in the stream have been returned to the user.
> IO$M_LOCKBUF | Blocks the completion of the I/O operation until the user buffer is completely filled or until the connection is closed. This is particularly useful when you want to minimize the number of $QIO service calls issued to read a data stream of a set size. This function modifier supports only stream protocols.
> IO$M_NOWAIT | 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.
> IO$M_PURGE | Flushes data from the socket receive queue (discards data). If the user buffer is larger than the amount of data in the queue, all data is flushed.

## Condition Values Returned

> SS$_NORMAL | The service completed successfully.
> SS$_ABORT | Programming error, `INET` management error, or hardware error. The execution of the I/O was aborted.
> SS$_ACCVIO | Access to an invalid memory location or buffer occurred.
> SS$_BADPARAM | One of the following methods was used to specify a $QIO function with an invalid parameter: An I/O function executed without specifying a device socket. First issue a $QIO with the IO$_SETMODE function and the proper parameters to create the device socket. An IO$_READVBLK function that does not specify a correct buffer address ( p1 or p6 is null). An IO$_READVBLK function specified an invalid vectored buffer ( p6 is an invalid descriptor). The socket has the OOBINLINE option set, or there is no OOB character in the socket's OOB queue because the character was either already read or never received. This condition happens only if you use the IO$M_INTERRUPT modifier or set the TCPIP$C_MSG_OOB flag with IO$_READVBLK.
> 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$_INSFMEM | INET management or programming error. There is not enough buffer space for allocation. The INET software needs more buffer space. You should set a higher quota for the dynamic buffer space, or shut down and restart your internet with a larger static buffer space.
> SS$_IVBUFLEN | Programming error occurred for one of the following reasons: The size of the buffer for an I/O function is insufficient. An IO$_READVBLK specified a correct buffer address ( p1 valid), but does not specify a buffer length ( p2 is null).
> SS$_LINKDISCON | A virtual circuit (TCP/IP) was closed at the initiative of the peer.
> SS$_NOLINKS | Programming error. Read attempt on unconnected TCP socket.
> SS$_SHUT | The network is being shut down.
> SS$_SUSPENDED | The operation is blocked for one of the following reasons: No messages were received, so the receive operation cannot complete. The socket is marked as nonblocking. The socket has the OOBINLINE option clear, and the OOB character has already been read.
> SS$_TIMEOUT | This applies to a socket that has KEEPALIVE set. The connection was idle for longer than the timeout interval (10 minutes is the default).
> SS$_UNREACHABLE | Communication status. The remote host or network is unreachable.

Previous | Next | Contents | Index