|
HP OpenVMS Systems Documentation |
|
HP TCP/IP Services for OpenVMS
|
| Previous | Contents | Index |
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 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 UNIX, 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 when one of the following occurs:
- There is no more data buffered in system space for this socket.
- 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 when one of the following occurs:
- All data from a record is transferred to the user buffer.
- 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 TCP/IP 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: (Alpha and I64) by 32- or 64-bit reference (VAX) by 32-bit reference
The address 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: access: quadword unsigned (Alpha and I64); longword unsigned (VAX) mechanism: read only (Alpha and I64) by 64-bit value
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 IP 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 IP address of the message source is written.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: (Alpha and I64) by 32- or 64-bit descriptor-fixed-length descriptor (VAX) by 32-bit descriptor-fixed-length descriptor
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 and I64 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 TCP/IP Services 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). For more information, see Table A-2. SS$_UNREACHABLE Communication status. The remote host or network is unreachable.
The IO$_SENSEMODE and IO$_SENSECHAR functions return one or more parameters (characteristics) pertaining to the network driver.Socket names (local and remote peer) are returned by using IO$_SENSEMODE's p3 and p4 arguments. Other parameters such as socket and protocol options, are specified in an output parameter list using the IO$_SENSEMODE p6 argument.
IO$_SENSEMODE p3 and p4 arguments can be used with the p6 argument in a single $QIO system service to return socket names as well as socket and protocol options. IO$_SENSEMODE processes arguments in this order: p3, p4, p6. If IO$_SENSEMODE detects an error, the I/O status block (IOSB) contains the error and argument address or the value that was at fault.
Refer to individual argument descriptions for details about specifying the type and format of output parameters.
p3
OpenVMS usage: socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_3 descriptor
The port number and IP address of the local name associated with the socket. The p3 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the local name is written.The equivalent Sockets API function is getsockname() .
p4
OpenVMS usage: socket_name type: vector byte (unsigned) access: read only mechanism: by item_list_3 descriptor
The port number and IP address of the remote name associated with the socket's peer. The p4 argument is the address of an item_list_3 descriptor that points to the socket address structure into which the peer name is written.The equivalent Sockets API function is getpeername() .
p6
OpenVMS usage: output_parameter_list type: vector byte (unsigned) access: read only mechanism: by item_list_2 descriptor
Output parameter list describing one or more parameters to return. The p6 argument is the address of an item_list_2 descriptor that points to and identifies the type of output parameter list.The equivalent Sockets API functions are getsockopt() and ioctl() .
IO$M_EXTEND Specifies the format of the socket address structure to return when used with the p3 or p4 arguments. When specified, a BSD Version 4.4 formatted socket address structure is returned.
Specify the IO$M_EXTEND modifier to operate in an IPv6 environment.
SS$_NORMAL The service completed successfully. SS$_ACCVIO The service cannot access a buffer specified by one or more arguments. SS$_BADPARAM Programming error occurred for one of the following reasons:
- $QIO system service was specified without a socket.
- Error occurred processing a socket or protocol option.
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$_ILLCNTRFUNC Programming error. The operation is unsupported for one of the following reasons:
- An invalid IO$_SENSEMODE function for the interface was specified. The interface does not have an IOCTL routine.
- An IO$_SENSEMODE function that requires a socket was specified, but the device did not have one. Create a socket and then issue the function.
- An unsupported operation was performed on at least one of the following protocols: raw IP, datagram, or stream sockets.
SS$_INSFMEM Insufficient system dynamic memory to complete the service. SS$_IVBUFLEN The size of a socket option buffer specified with the IO$_SENSEMODE function was invalid. SS$_NOSUCHDEV Programming error or INET management error. An INET address is not in the Address Resolution Protocol (ARP) table. An attempt to show or delete an ARP table entry failed. SS$_NOLINKS The specified socket was not connected. SS$_NOOPER Programming error. An attempt to get ARP information occurred without OPER privilege. SS$_PROTOCOL A network protocol error occurred. The address family specified in the socket address structure is not supported. SS$_SHUT The local or remote node is no longer accepting connections. SS$_UNREACHABLE The remote node is currently unreachable.
| Previous | Next | Contents | Index |