# DIGITAL TCP/IP Services for OpenVMS
System Services and C Socket Programming

Previous | Contents

Consider the following when using IO$M_READATTN:

- There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For example, for each enabled AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when an event occurs.
- If an out-of-band (OOB) Attention AST is enabled, the OOB AST is delivered, regardless of the following:
  - A Read Attention AST enabled
  - The UCX$C_OOBINLINE socket option
  - A READ $QIO waiting for completion on the socket

If the UCX$C_OOBINLINE option is set, then a waiting READ $QIO is completed and the OOB character is returned in the data stream.

- If both an OOB AST and a Read Attention AST are enabled, only the OOB AST is delivered when an OOB character is received.
- If a Read Attention AST is enabled and the UCX$C_OOBINLINE socket option is set, a waiting READ $QIO completes and the OOB character is returned in the data stream.
- If a Read Attention AST is enabled and the UCX$C_OOBINLINE socket option is not set (clear), the Read Attention AST is delivered when an OOB character is received, regardless of whether a READ $QIO is waiting for completion. In this case, the OOB character is not returned in the data stream. Therefore, if the OOB character is the only character received, the READ $QIO does not complete.

## Condition Values Returned

> SS$_ABORT | Programming, INET management, or hardware error. The route entry already exists, so your attempt to add a route entry using the IO$_SETMODE function failed.
> SS$_ACCVIO | Programming error. You attempted to access an invalid memory location or buffer.
> SS$_BADPARAM | Programming error. The parameter you specified for a $QIO function was invalid for one of the following reasons: You attempted to execute the IO$_SETMODE subfunctions without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. You made an error specifying a socket option.
> SS$_DEVACTIVE | INET management error. You attempted to change the static INET parameters. If you need new parameters, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command.
> SS$_DEVINACT | INET management error. The driver was not started. Issue a UCX START COMMUNICATION command before issuing $QIO functions.
> SS$_DEVNOTMOUNT | INET management error. You improperly executed the startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again.
> SS$_DUPLNAM | Programming error. You attempted to bind a port already in use so the operation to bind the socket to the address and port failed.
> SS$_EXQUOTA | Programming or INET management error. The quota for the valid number of sockets caused an error for one of the following reasons: You attempted to exceed the maximum number of sockets by creating new socket with the IO$_SETMODE function. Increase the maximum number of allowable sockets (INET parameter) before creating more sockets. You specified a number of sockets with the IO$_SETMODE function that exceeds the maximum number of sockets allowed. Increase the maximum number of sockets (INET parameter) or reduce the number of sockets that the listener socket can create (listen parameter).
> SS$_FILALRACC | Programming error. You attempted to bind the socket to an address that is already in use and the operation failed.
> SS$_INSFMEM | Programming or system management error. Your system does not have enough resources to allocate new socket.
> SS$_ILLCNTRFUNC | Programming error. Operation is not supported. Invalid IO$_SETMODE (IOCTL) function was used for the interface. The interface does not have an IOCTL routine. An attempt was made to perform an IO$_SETMODE (IOCTL) function that required a socket, but the device did not have one. Create a socket and issue the IOCTL function.
> SS$_IVADDR | Programming error. The specified INET address is not in the system, and an invalid port number or an invalid INET address combination was specified with an IO$_SETMODE function (a bind). An attempt to bind the address failed because the INET address is not in the system, port zero and INET address zero are not allowed, or port zero is not allowed when using an IO$_ACCESS or IO$_WRITEVBLK function. An attempt to make a permanent entry in the ARP table failed because of lack of space. Too many permanent entries. An attempt was made to bind an IP socket (raw IP) when there are no interfaces defined in the system. An attempt was made to bind an IP socket (raw IP) to a null INET address.
> SS$_IVBUFLEN | Programming error. The socket option buffer has an invalid size.
> SS$_NOLICENSE | Programming or system management error. UCX license not present.
> SS$_NOOPER | Programming or INET management error. An attempt was made to execute an I/O function that needs the OPER privilege.
> SS$_NOPRIV | Programming or INET management error. Not enough privileges for the attempted operation. Broadcasting an IP datagram was denied because the process does not have a system UIC, SYSPRV, BYPASS, or OPER privileges. An attempt was made to use a reserved port number lower than 1024. An operation accesses only processes that have a system UIC, SYSPRV, or BYPASS privilege. Raw IP protocol can be used only on privileged sockets. The process must have a SYSPRV or BYPASS privilege.
> SS$_NOSUCHDEV | Programming error or INET management error. An INET address is not in the ARP table. An attempt to show or delete an ARP table entry failed.
> SS$_NOSUCHNODE | Programming error or INET management error. An attempt to delete a route from the routing table failed because a route entry was not found.
> SS$_PROTOCOL | Programming error. The protocol type specified at socket creation is not valid. The protocol is not supported. The protocol type specified is not found in the internal tables. It is an invalid type. The address family is not supported: The address family specified with an IO$_SETMODE function (IOCTL subfunction) is not supported. The address family should be the UCX$C_AF_INET or UCX$C_UNSPEC address family. The address family of the remote INET address specified with an IO$_ACCESS or IO$_WRITEVBLK function is not supported (UDP/IP or TCP/IP). The address family should be the UCX$C_AF_INET address family. The address family of the local INET address specified with an IO$_SETMODE (bind) function is not supported. The address family should be the UCX$C_AF_INET address family. The address family of the INET address that is specified in a request to the routing module is not supported. The address family should be the UCX$C_AF_INET address family.
> SS$_SHUT | The network is being shut down.

# IO$_SETMODE|IO$M_WRTATTN

> The IO$_SETMODE|IO$M_WRTATTN function/modifier combination (IO$M_WRTATTN is Enable Write Attention AST (asynchronous system trap)) requests that an Attention AST be delivered to the requesting process when a data packet can be queued to the socket. For TCP sockets, this occurs when the TCP transmit queue is available.

## ARGUMENTS

> ### p1

> UCX usage | procedure entry mask
> type | call without stack unwinding
> access | by reference
> mechanism | 0

> To enable the AST, the p1 argument is the address of the Write Attention AST routine. To disable the AST, p1 is set to 0.

> ### p2

> UCX usage | user_arg
> type | longword (unsigned)
> access | read only
> mechanism | by value

> AST parameter to be delivered to the AST routine.

> ### p3

> UCX usage | acmode
> type | longword (unsigned)
> access | read only
> mechanism | by value

> Access mode to deliver the AST.

## DESCRIPTION

> The Enable Write Attention AST function enables an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly re-enable AST delivery before the AST can occur again. The function is subject to AST quotas.

> There is a one-to-one correspondence between the number of times you enable an Attention AST and the number of times the AST is delivered. For example, for each enable AST, one AST is delivered. If you enable an Attention AST several times, several ASTs are delivered for one event when the event occurs.

> You can use the UCX command SHOW DEVICE_SOCKET to display information on the socket's characteristics, options, and state.

## Condition Values Returned

> SS$_ABORT | Programming error, INET management error, or hardware error. The route you specified with the IO$_SETMODE function already exists. Therefore, the operation failed.
> SS$_ACCVIO | Programming error. You attempted to access an invalid memory location or buffer.
> SS$_BADPARAM | Programming error. The parameter you specified for the $QIO I/O function was invalid for one of the following reasons: You attempted to execute the IO$_SETMODE functions without specifying a device socket. Instead, create a device socket by issuing a $QIO with the IO$_SETMODE function and the proper parameters. You made an error when specifying a socket option.
> SS$_DEVACTIVE | INET management error. You attempted to change the static INET parameters. If you need new parameters, shut down the internet, reset the static parameters, and issue the START COMMUNICATION command.
> SS$_DEVINACT | INET management error. The driver is not started. Issue a UCX START COMMUNICATION command before issuing $QIO functions.
> SS$_DEVNOTMOUNT | INET management error. The INET startup procedure was improperly executed. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again.
> SS$_DUPLNAM | Programming error. Port that is being bound is already in use. An attempt to bind the socket to an address and port failed.
> SS$_EXQUOTA | Programming or INET management error. You attempted to create a new socket with the IO$_SETMODE function and it failed because the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter) and then create a new socket. The number of sockets you specified with the IO$_SETMODE function exceeds the allowable maximum number of sockets. Increase the maximum number of sockets (INET parameter) or reduce the number of sockets that the listener socket can create (listen parameter).
> SS$_FILALRACC | Programming error. Because the INET address is already in use, your attempt to bind the socket to an address and port failed.
> SS$_INSFMEM | Programming or system management error. There are not enough resources to allocate new socket.
> SS$_ILLCNTRFUNC | Programming error. You specified an operation that is unsupported for one of the following reasons: You used an invalid IO$_SETMODE function for the interface. The interface does not have an IOCTL routine. You attempted to execute an IO$_SETMODE function that required a socket, but the device did not have one. Instead, create a socket and issue the function.
> SS$_IVADDR | Programming error. You specified an invalid port number and INET address combination with the IO$_SETMODE bind function. This caused the operation to fail for one of the following reasons: You specified an illegal combination of port zero and INET address zero. You specified port zero when using an IO$_ACCESS or IO$_WRITEVBLK function. When you attempted to make a permanent entry in the ARP table, the operation failed because of lack of space. There are too many permanent entries. You attempted to bind a raw IP socket when there were no interfaces defined in the system. You attempted to bind a raw IP socket to a null INET address.
> SS$_IVBUFLEN | Programming error. You specified an invalid size for the socket option buffer.
> SS$_NOLICENSE | Programming or system management error. There is no DIGITAL TCP/IP Services for OpenVMS license present.
> SS$_NOOPER | Programming or INET management error. You attempted to execute an I/O function that needs the OPER privilege.
> SS$_NOPRIV | Programming or INET management error. You attempted to execute an operation that failed for one of the following reasons: You cannot broadcast an IP datagram for a process if you do not have system UIC, SYSPRV, BYPASS, or OPER privileges. You attempted to use a reserved port number lower than 1024. You attempted to access a process when you do not have system UIC, SYSPRV, or BYPASS privileges. You attempted to use raw IP on a socket that is not a privileged sockets. To do this, the process must have SYSPRV or BYPASS privilege.
> SS$_NOSUCHDEV | Programming error or INET management error. You attempted to show or delete an entry in the ARP table. However, because the INET address was not in the ARP table, the operation failed.
> SS$_NOSUCHNODE | Programming error or INET management error. You attempted to delete a route from the routing information table (RIT). However, because the route was not found in the RIT, the operation failed.
> SS$_PROTOCOL | Programming error. You specified an invalid protocol type when you created the socket. You specified an unsupported protocol. You specified a protocol type that is invalid because it is not found in the internal tables. You specified an address family that is not supported for one of the following reasons: You specified an address family with an IO$_SETMODE subfunction. Instead, specify the UCX$C_AF_INET or UCX$C_UNSPEC address family. You specified an address family of the remote INET address for a datagram or stream socket with an IO$_ACCESS or IO$_WRITEVBLK function. Instead, specify the UCX$C_AF_INET address family. You specified an address family of the local INET address with an IO$_SETMODE bind function. Instead, specify the UCX$C_AF_INET address family. You made a request to the routing module by specifying the address family of the INET address. Instead, specify the UCX$C_AF_INET address family.
> SS$_SHUT | The network is being shut down.

# IO$_WRITEVBLK

> Write I/O functions provide direct transfer of data from the virtual address space of the user's process to an internet host or port. The DIGITAL TCP/IP Services for OpenVMS product provides the WRITE I/O function code IO$_WRITEVBLK, which writes a user buffer for stream sockets, datagrams, or raw IP.

> If you specify multiple buffers, the system sends data from buffers in the order specified by the p5 list. For UDP and raw IP, the TCP/IP software sends the data in one datagram. The data to be sent is buffered by TCP/IP before being transmitted to the remote host.

> For a TCP socket, if the socket transmit queue is full, the Write I/O operation will be blocked until the transmit queue has enough room for the user data.

> For UDP and raw IP sockets, if the user data is greater than the transmit (send) socket quota, an error code is returned (SS$_TOOMUCHDATA).

> The equivalent C Socket functions are recv*, send*(), sendto() and write().

> Programming examples for the IO$_WRITEVBLK routine follow this command description. Example 4-12 uses the MACRO-32 programming language and Example 4-13 uses the C programming language to read a vectored buffer. Example 4-14 uses the C programming language to read from an INET driver.

## ARGUMENTS

> ### p1

> UCX usage | buffer
> type | longword (unsigned)
> access | read only
> mechanism | by reference

> The p1 argument specifies the starting virtual address of the buffer containing the data to be transmitted.

> ### p2

> UCX usage | buffer length
> type | longword (unsigned)
> access | read only
> mechanism | by value

> The p2 argument specifies the size (in bytes) of the buffer containing the data to be transmitted.

> ### p3

> UCX usage | remote socket name (message source)
> type | longword (unsigned)
> access | read only
> mechanism | by descriptor

> The p3 argument specifies the address of a UCX item_list_2 descriptor. This descriptor points to a buffer that contains the remote port and remote host internet address (socket name) of the message destination.

> ### p4

> UCX usage | flags
> type | longword (unsigned)
> access | read only
> mechanism | by value

> The p4 argument specifies the flags for the Write operation. Table 4-18 describes the valid flags for this argument.

> Table 4-18 Valid Write Flags for the p4 Argument
> Flag | Description
> --- | ---
> UCX$C_MSG_OOB | Writes an out-of-band (OOB) byte.
> UCX$C_MSG_DONTROUTE | Sends the message directly without routing.
> UCX$C_MSG_NBIO | Completes the I/O operation and returns an error if a condition that would cause the I/O operation to be blocked. Similar to using IO$M_NOWAIT.

> ### p5

> UCX usage | UCX item_list_2
> type | longword (unsigned)
> access | read only
> mechanism | by descriptor

> The p5 argument specifies the address for the descriptor of an input parameter list. The maximum number of buffers you can specify with the p5 argument is 16.

> The p1 and p2 arguments and the p5 argument are mutually exclusive. You either use p1 and p2 or you use p5. The software first checks to see if the p1 argument is being used. If p1 is not used, it checks to see if the p5 argument is being used. If neither the p1 nor the p5 argument is being used, an error code is produced.

> The resulting transfer-length value of the I/O status block is the sum of the bytes transferred in the multiple buffers.

## Function Modifiers

> IO$M_INTERRUPT | Sends an out-of-band byte to a target process. At the remote process, the byte is delivered to the user through the data receive mechanism.
> IO$M_NOWAIT | Regardless of a $QIO or $QIOW, if the system detects a condition that would cause the I/O operation to be blocked, the system completes the I/O operation and returns the error code SS$_SUSPENDED. When using this function modifier, always check the message length in the IOSB to ensure that all data is transferred. If only 1 byte of data is transferred, the function returns a success status even if data is not completely transferred.

## Condition Values Returned

> SS$_ABORT | Programming error, INET management error, or hardware error. The execution of the I/O was aborted.
> SS$_ACCVIO | Programming error. An attempt was made to access an invalid memory location or buffer.
> SS$_BADPARAM | Programming error. A $QIO I/O function was specified using an invalid parameter. An attempt was made to execute an IO$_WRITEVBLK function without specifying a device socket. First create a device socket by issuing an IO$_SETMODE function and the proper arguments. An attempt was made to issue an IO$_READVBLK or IO$_WRITEVBLK function that does not specify a correct buffer address ( p1, p5, or p6 is null). An attempt was made to issue an IO$_READVBLK or IO$_WRITEVBLK that specifies an invalid vectored buffer ( p5 or p6 specifies an invalid address descriptor).
> SS$_CANCEL | Warning code. The I/O operation was canceled by issuing a $CANCEL system service.
> SS$_DEVINACT | INET management error. The driver was not started. A UCX START COMMUNICATION command must be executed before issuing any $QIO function.
> SS$_DEVNOTMOUNT | INET management error. The INET startup procedure was executed improperly. The driver was loaded, but the INET_ACP was not activated.
> SS$_EXQUOTA | Returned when process resource mode wait is disabled. There is no internet request packet (IRP) available for completing the request. Increase the buffered I/O quota.
> SS$_FILALRACC | Programming error. INET address is already in use. An attempt was made to bind the socket to an address but the port failed. IP protocol (raw socket). An attempt was made to specify a remote INET socket address with an IO$_WRITEVBLK function, while an INET address was already specified with an IO$_ACCESS function. UDP/IP protocol. An attempt was made to specify a remote INET socket address with an IO$_WRITEVBLK function, while an INET address was already specified with the IO$_ACCESS function.
> SS$_ILLCNTRFUNC | Programming error. Unsupported operation on the protocol (IP, UDP/IP, TCP/IP).
> SS$_INSFMEM | INET management or programming error returned when process resource mode wait is disabled. Not enough system space for buffering user data. A higher quota for socket buffer space needs to be set, or the internet needs more dynamic buffer space (number of dynamic clusters should be increased).
> SS$_IVADDR | Programming error. The specified INET address is not in the system, and an invalid port number or an INET address combination was specified with an IO$_WRITEVBLK operation. An attempt to bind the socket failed because the INET address is not in the system, port number zero and INET address zero are not allowed, or port zero is not allowed with an IO$_ACCESS or IO$_WRITEVBLK function. An attempt to get an interface INET address, broadcast mask, or network mask failed. A send request was made on a datagram-oriented protocol, but the destination address is unknown or not specified.
> SS$_IVBUFLEN | Programming error. The size of the buffer for an I/O function is insufficient. An attempt was made to issue an IO$_WRITEVBLK function that specifies a correct buffer address ( p1 valid), but does not specify a buffer length ( p2 is null).
> SS$_LINKDISCON | Notification. Connection completion return code. The virtual circuit (TCP/IP) was closed at the initiative of the peer. The application must stop sending data and shutdown or close the socket.
> SS$_PROTOCOL | Programming error. The address family of the remote INET address specified with an IO$_WRITEVBLK function is not supported (UDP/IP or TCP/IP). The address family should be the UCX$C_AF_INET address family.
> SS$_NOLINKS | Programming error. The socket was not connected (TCP/IP) or an INET port and address were not specified with an IO$_ACCESS (UDP/IP or IP). An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (raw IP). An IO$_WRITEVBLK with no remote INET socket address was issued on a socket that was not the object of an IO$_ACCESS function (UDP/IP). An attempt was made to disconnect a socket that is not connected, or an attempt was made to issue an IO$_WRITEVBLK or IO$_READVBLK function on an unconnected socket (TCP/IP).
> SS$_SHUT | The network is being shut down.
> SS$_SUSPENDED | The operation was blocked. A send operation requires system buffer space that is not available. The socket is marked as performing nonblocking operations.
> SS$_TIMEOUT | Programming error, INET management error, or hardware error. A TCP/IP connection timed out after several unsuccessful retransmissions. On a TCP socket where KEEPALIVE is set, the connection was idle for longer than the timeout interval (10 minutes by default).
> SS$_TOOMUCHDATA | Programming or INET management error. The message size was too large. An IP packet that is broadcast cannot be fragmented. The Not Fragment IP flag was set and the IP datagram was too large to be sent without being fragmented. Internal error. The length of the Ethernet datagram does not allow enough space for the minimum IP header. The message to be sent on a UDP/IP or raw IP socket is larger than the socket buffer high water allows. An attempt was made to send or receive more than 16 buffers specified with the p5 argument.
> SS$_UNREACHABLE | Programming error. Either the network address is invalid or the network is unreachable. Hardware error. The data link adapter detected an error and shut itself off. The UCX software is waiting for the adapter to come back on line.

Previous | Next | Contents