| Previous | Contents | Index |
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() .
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.
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.
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.
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() .
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.
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.
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() .
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.
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.
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.
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() .
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.
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 |