The C Socket equivalent is the getsockopt() function or a call to the ioctl program.
p3
UCX usage UCX item_list_3 type longword (unsigned) access read only mechanism by descriptor
The p3 argument contains the address of a UCX item_list_3 descriptor that specifies the buffer where the software returns the local socket name. The buffer contains the local socket address (family name, port number, and internet address). The parameter name for the descriptor is UCX$_C_SOCK_NAME, which is defined in the UCX$INET_DEF symbol definition file.The C Socket equivalent for this function is getsockname().
p4
UCX usage UCX item_list_3 type longword (unsigned) access read only mechanism by descriptor
The p4 argument contains the address of a UCX item_list_3 descriptor that specifies the buffer from which to return the remote peer socket name. The buffer contains the remote socket address (family name, port number, and internet address).The C Socket equivalent for this function is getpeername().
p6
UCX usage UCX item_list_2 or item_list_3 type longword (unsigned) access read only mechanism by descriptor
The p6 argument specifies the address of a descriptor that lists UCX item_list_2 or item_list_3 descriptors. The following are the parameter types for the UCX item_list to which the p6 argument points:
- UCX$C_SOCKOPT (communication socket option parameters)
- UCX$C_TCPOPT (TCP options)
- UCX$C_IPOPT (IP options)
- UCX$C_IOCTL (I/O control parameters)
The UCX item_list descriptor points to an integer (with the length set to the size of the integer). The integer contains zero to clear an option and nonzero to set an option.
The UCX$C_SOCKOPT parameter specifies the communication socket options. The descriptor that defines the list of socket options points to a list of item_list_3 descriptors, which contains one descriptor for each option. Table 4-9 describes the options for the UCX$C_SOCKOPT parameter type.
Unsupported socket options are ignored.
Table 4-10 describes the TCP/IP options for the UCX$C_TCPOPT parameter type.
Table 4-11 describes the options for the UCX$C_IPOPT parameter type.
Table 4-10 TCP/IP Options TCP/IP Option Description UCX$C_TCP_PROBE_IDLE TCP/IP protocol option. Specifies the time interval for the KEEPALIVE probe, as well as for the connection establishing the timeout. UCX$C_TCP_DROP_IDLE TCP/IP protocol option. Specifies the time interval after which the connection will be dropped if the remote host does not respond. The UCX$C_IOCTL parameter specifies the I/O control parameters. The parameters are specified through a UCX item_list_2 descriptor that points to a list of longword entries. The first longword entry contains the IOCTL command. The second longword contains the address of a buffer structure descriptor. The IOCTL commands are listed in Table 4-12.
Table 4-11 IP Options IP Option Description UCX$C_IP_TTL Time to live (TTL) for a datagram. UCX$C_IP_TOS Type of service (1-byte value).
Table 4-12 IOCTL Commands Parameter Structure IOCTL Command Description Integer SIOCATMARK Determines if you are at the OOB character mark. Integer FIONREAD Obtains the number of bytes that are queued in the socket receive queue. You can use one $QIO system service call with the IO$_SENSEMODE modifier for multiple operations. For example, a $QIO system service could specify a list of socket options or a list of IOCTL commands, combined with a local socket name or peer socket name.
When the software detects an error, the iosb argument contains the error and parameter address or value that was at fault.
The UCX software sequentially processes parameters in this order: p3, p4, p6.
You can specify multiple lists of socket options or IOCTL commands. If you duplicate a parameter or IOCTL command in one or more lists, the value returned is the last option or IOCTL command read.
SS$_ACCVIO Programming error. You attempted to access an invalid memory location or buffer. SS$_BADPARAM Programming error. You specified a $QIO function with an invalid parameter that resulted from one of the following:
- You attempted to execute the IO$_SENSEMODE function 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 while specifying a socket option.
SS$_DEVINACT INET management error. The driver was not started. Execute a UCX START COMMUNICATION command before issuing $QIO functions. SS$_DEVNOTMOUNT INET management error. You improperly executed the INET startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again. SS$_ILLCNTRFUNC Programming error. The operation is unsupported for one of the following reasons:
- You issued an invalid IO$_SENSEMODE function for the interface. The interface does not have an IOCTL routine.
- You issued a IO$_SENSEMODE function that requires a socket, 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 INET management or programming error. Do one of the following:
- Set a higher quota for the dynamic buffer space.
- Shut down the internet and restart with larger static buffer space.
SS$_IVBUFLEN Programming error. You set a socket option buffer with an invalid size. 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 Programming error.
- Stream socket --- You did not connect the socket.
- Datagram or raw IP --- You did not specify an INET port and address with an IO$_ACCESS system service call.
- You used the IO$_SENSEMODE system service call to request the name of a peer socket without first issuing calls to connect the socket or establish the peer socket.
SS$_NOOPER Programming error. You attempted to get ARP information without having OPER privileges. SS$_PROTOCOL Programming error. You attempted to set socket options on a closed socket. SS$_SHUT The network is being shut down. SS$_UNREACHABLE Programming error. Network is unreachable or the network address is invalid.
- You attempted to create a permanent ARP table with the network part of the INET address being zero.
- You attempted to create a route entry with the network part of the INET address being zero.
The Set Mode and Set Characteristics I/O functions perform mode, operational, and program/driver interface operations with the internet device socket. These two functions work in exactly the same manner. They take the following form:
- IO$_SETMODE
- IO$_SETCHAR
The protocol you use determines when you can change the mode or characteristics:
- Connectionless protocols (datagram or raw IP ) --- Can be changed any time.
- Connection-oriented protocols (TCP/IP) --- Can only be changed when the device socket is closed, such as before a connection is established (opened) or after the connection is closed. While a connection is open (active), only parameters that do not affect the connection characteristics may be changed.
The routine processes parameters sequentially. If it finds an error, the routine aborts. Any parameters correctly specified before the routine encounters an error are properly processed before the routine aborts.
The equivalent C Socket functions are socket(), bind(), listen(), setsockopt() or a call to the ioctl program.
p1
UCX usage socket definition (socket type, protocol, and INET domain) type longword (unsigned) access read only mechanism by reference
The p1 argument specifies the address of a buffer containing the socket characteristics. The C Socket equivalent for this is socket().The socket characteristics buffer is one longword. The first two bytes contain the protocol, the third byte contains the socket type (protocol type), and the fourth byte contains the domain name (the internet, by default).
Both the protocol and the socket type are contained in one longword value.
Table 4-13 lists the valid protocols.
Table 4-13 Valid Protocols for IO$_SETMODE and IO$_SETCHAR Protocol Description UCX$C_TCP TCP/IP UCX$C_UDP UDP/IP UCX$C_RAW_IP IP Table 4-14 lists the valid socket types.
Table 4-14 Valid Socket Types for IO$_SETMODE and IO$_SETCHAR Socket Type Description UCX$C_STREAM The communications protocol is a bidirectional, reliable, sequenced, and unduplicated data flow without record boundaries. UCX$C_DGRAM The communications protocol is a bidirectional data flow with record boundaries. There are no provisions for sequence, reliability, or duplication of messages. UCX$C_RAW Allows access to the lower layer (IP layer) of the internet communication protocol. It is used to develop new communication protocols that are to be layered on the IP layer. If the image that creates the socket runs in a process that has a privileged UIC or has SYSPRV, BYPASS, or OPER privileges, the socket is marked privileged.
Note
The p2 argument is not used with the IO$_SETMODE routine. It is used when you specify either the IO$M_OUTBAND, IO$M_READATTN, or IO$M_WRTATTN function modifiers. See the descriptions for IO$_SETMODE|IO$M_OUTBAND, IO$_SETMODE|IO$M_READATTN, and IO$_SETMODE|IO$M_WRTATTN for details.
p3
UCX usage local socket name type longword (unsigned) access read only mechanism by descriptor
The p3 argument specifies the address of a UCX item_list_2 descriptor of a buffer that specifies the local socket name (port and local host internet address). The parameter name for the descriptor is UCX$C_SOCK_NAME, which is defined in the UCX$INETDEF symbol definition file.The C Socket equivalent is bind().
p4
UCX usage number of connections to accept type byte (unsigned) access read only mechanism by value
The p4 argument specifies the number of connections that can be established simultaneously and held by the listener socket before the program accepts the connections on the socket associated with the UCX device (TCP/IP only). If more connections are received than have been specified, the the additional connections are rejected.The C Socket equivalent is listen().
p5
UCX usage UCX item_list_2 type longword (unsigned) access read only mechanism by descriptor
The p5 argument specifies the address of a descriptor that lists item_list_2 descriptors. The C Socket equivalent is setsockopt().Each UCX item_list_2 descriptor describes a group of parameters of a specific type.
The following are the parameter types for the UCX descriptor to which the p5 points:
- UCX$C_SOCKOPT (communication socket option parameter)
- UCX$C_TCPOPT (TCP options)
- UCX$C_IPOPT (IP options)
- UCX$C_IOCTL (I/O control parameter)
You can use one $QIO system call to set up several socket options at once. The UCX item_list_2 descriptor points to an integer (with the length set to the size of the integer). The integer contains zero to clear the option and nonzero to set the option.
The UCX$C_SOCKOPT parameter specifies the communication socket options. Table 4-15 describes the socket options you use with the UCX$C_SOCKOPT parameter type.
Unsupported socket options are ignored.
Table 4-16 describes the socket options you use with the UCX$C_TCPOPT parameter type.
Table 4-17 describes the options you use with the UCX$C_IPOPT parameter type.
Table 4-15 Communications Socket Options Socket Option Description UCX$C_KEEPALIVE Detects broken idle connections (connections in which the remote end point has dropped the connection) and keeps the connection alive for the specified maximum idle time (optional for TCP/IP). UCX$C_DONTROUTE Uses interface addresses only. UCX$C_BROADCAST Permits sending of broadcast messages. A broadcast internet address is the system number defined by using the connection control program. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege in order to be set. Optional for a connectionless datagram. UCX$C_LINGER Lingers on Close operation if data is present; that is, waits for all messages to be sent (optional for TCP/IP). UCX$C_OOBINLINE Leaves the received OOB data in line. UCX$C_RCVBUF Sets the socket receive quota. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege to be set. UCX$C_REUSEADDR Allows reuse of the local socket address. The local socket address is the 16-byte structure that contains the address family, port, and host IP address. The UCX$C_REUSEADDR option enables reuse of the local port number portion. It works only with connection-oriented protocols (in particular, TCP/IP), where a connection is characterized for its entire life by the local address, local port, remote host, and remote port.
The option can be used for a client that always binds to a known or well-defined port number. It allows several instances of the client image running on one host to connect to the same server on different hosts.
UCX$C_SNDBUF Sets the socket send quota. This option requires a system UIC, SYSPRV, BYPASS, or OPER privilege to be set. UCX$C_NO_RCV_CHECKSUM Disables checksum calculation for received data. UCX$C_NO_SND_CHECKSUM Disables checksum calculation for transmitted data. UCX$C_NO_CHECKSUM Disables checksum calculation altogether. UCX$C_SHARE Allows multiple processes to share the socket. UCX$C_FULL_DUPLEX_CLOSE When set before a close operation, both receive and transmit sides of the communications are closed.
Table 4-16 TCP Options TCP Option Description UCX$C_USELOOPBACK TCP/IP socket option. Shortcuts the data transfer when the transfer is local to the host. This improves the performance of the local TCP/IP transfer process and results in a lower load on the CPU when applications using local transfer are active. UCX$C_TCP_NODELAY TCP/IP option. Specifies that the send operation will not be delayed to coalesce packets. UCX$C_TCP_PROBE_IDLE TCP/IP option. Specifies the time interval for the KEEPALIVE probe, as well as for the connection establishing the timeout. UCX$C_TCP_DROP_IDLE TCP/IP option. Specifies the time interval after which the connection is dropped.
Table 4-17 IP Options IP Option Description UCX$C_IP_TTL Time to live (TTL) for a datagram. UCX$C_IP_TOS Type of service (1-byte value) The UCX$C_IOCTL parameter specifies the I/O control parameters. The list of the IOCTL parameters contains two entries of longwords: the IOCTL command (first longword) and the address of the required buffer structure (second longword).
To set UCX$C_IOCTL, you need a system UIC, SYSPRV, BYPASS, or OPER privileges.
You can specify multiple IO$_SETMODE parameters with one $QIO system service call. For example, one $QIO system service call could specify a list of socket options or a list of IOCTL commands, combined with a local socket name.
When an error is detected, the iosb argument specifies the error and parameter address or value that was at fault.
The UCX software processes parameter values for arguments in the following order: p1, p3, p4, and p5.
You can specify multiple lists of socket options or IOCTL commands. If a parameter, parameter list, or IOCTL command is duplicated by using the same return address, then the value returned is the last option or IOCTL command.
The IO$_SETMODE|IO$M_OUTBAND function/modifier combination requests that the asynchronous system trap (AST) for an out-of-band (OOB) character be delivered to the requesting process. This is to be done only when an OOB character is received on the socket and there is no waiting read request. The socket is a TCP/IP (stream) socket.
p1
UCX usage ast_procedure type procedure entry mask access call without stack unwinding mechanism by reference
To enable the AST, the p1 argument is the address of the OOB character AST routine. To disable the AST, p1 equals 0.p2
UCX usage user_arg type longword (unsigned) access read only mechanism by value
AST parameter to be delivered to the AST routine specified by the p1 argument.p3
UCX usage acmode type longword (unsigned) access read only mechanism by value
Access mode to deliver the AST.
The Enable OOB character AST function allows an Attention AST to be delivered to the requesting process only once. After the AST occurs, the function must explicitly reenable AST delivery before a new AST can be delivered. This function is subject to AST quotas.
SS$_ABORT Programming, INET management, or hardware error. The route entry already exists. You attempted to add a route entry with the IO$_SETMODE function and the operation failed. SS$_ACCVIO Programming error. You attempted to access an invalid memory location or buffer. SS$_BADPARAM Programming error. You specified a $QIO function with an invalid parameter that occurred for one of the following reasons:
- You attempted to execute an IO$_SETMODE function (all subfunctions, except socket creation) 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 new parameters are needed, 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 INET startup procedure. The driver was loaded, but the INET_ACP was not activated. Execute the INET startup procedure again. SS$_DUPLNAM Programming error. You are attempting to bind a port that is already in use. An attempt to bind the socket to an address and port failed. SS$_EXQUOTA Programming or INET management error that occurred because of one of the following reasons:
- You attempted to create a new socket with the IO$_SETMODE function but it failed because the maximum number of sockets was exceeded. Increase the maximum number of sockets (INET parameter).
- The number of sockets specified with the IO$_SETMODE (listen) exceeds the maximum number of sockets. Increase the maximum number of sockets (INET parameter) or reduce the listen parameter (the number of sockets that the listener socket can create).
SS$_FILALRACC Programming error. INET address is already in use. An attempt to bind the socket to an address and port failed. SS$_INSFMEM Programming or system management error: Not enough resources to allocate new socket. SS$_ILLCNTRFUNC Programming error. Operation is not supported because of one of the following reasons:
- You used an invalid IO$_SETMODE (IOCTL) function for the interface. The interface does not have an IOCTL routine.
- You attempted 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) for one of the following reasons:
- 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 an ARP table that was full failed.
- 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 for one of the following reasons:
- 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 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 due to one of the following reasons:
- 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 and therefore is an invalid type.
- The address family is not supported for one of the following reasons:
- 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 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.
The IO$_SETMODE|IO$M_READATTN function/modifier combination requests that an Attention AST be delivered to the requesting process when a data packet is received on the socket and there is no waiting read request.
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 Read Attention AST routine. To disable the AST, set p1 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.
The Enable Read Attention AST function enables an Attention AST to be delivered to the requesting process once only. 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.
Previous | Next | Contents