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.


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