═══ 1. What is RxSock? ═══ RxSock is a REXX function package providing access to the TCP/IP socket API's available for the C programming environment. Therefore, most of the functions described in this reference correspond to their like-named C functions available in the TCP/IP socket library. The function reference below is certainly not exhaustive. It is assumed you are already familiar with the basic socket APIs, and can reference the system specific ones. A widely available book with information on the basic socket APIs is "Internetworking with TCP/IP Volume I: Principals, Protocols, and Architecture" by Douglas Comer (ISBN 0-132-16987-8). This function package requires TCP/IP support to be active. ═══ 2. Installation and Removal ═══ The REXX function package RxSock is contained in the file rxsock.dll. This file is to be placed in a directory along your LIBPATH. To get access to the functions in the function package RxSock, execute the following REXX code: rc = RxFuncAdd("SockLoadFuncs","rxsock","SockLoadFuncs") rc = SockLoadFuncs() To unload the DLL, you should first call the SockDropFuncs() function, then exit all CMD.EXE shells. After exiting all the command shells, the DLL will be dropped by the system and can be deleted or replaced. ═══ 3. Parameters and Return Values ═══ Return values for most functions are the same as the C equivalents, unless otherwise noted. There are a number of standard parameter types referenced in the function reference. socket This is a socket value. It is an integral number. domain This is a domain value. The only currently supported domain is "AF_INET". address This is the 'stem' of a stemmed variable with the following values: address.family should always be "AF_INET" address.port a port number address.addr a dotted decimal address, or where appropriate, "INADDR_ANY" When this parameter is needed you should set it the name of a stem variable for the function to set (or that the function will read from). For example, if you passed the string "xxx.!" as a parameter, the variables "xxx.!family", "xxx.!port", and "xxx.!addr" will be set by the function, or queried by the function. A null address is an address with the family field being "AF_INET", the port field being 0, and the addr field being "0.0.0.0". dotAddress the standard dotted decimal address. For example, the string "9.23.19.63" is a valid address. host This is the 'stem' of a stemmed variable with the following values: host.name the standard name of the host host.alias.0 number of aliases for this host host.alias.1 First alias for this host host.alias.n n'th alias for this host host.addrtype should always be "AF_INET" host.addr a dotted decimal address (default address) host.addr.0 number of addresses for this host host.addr.1 First address for this host host.addr.n n'th address for this host When this parameter is needed you should set it the name of a stem variable for the function to set (or that the function will read from). For example, if you passed the string "xxx.!" as a parameter, the variables "xxx.!name", "xxx.!alias.0", "xxx.!alias.1" ... "xxx.!alias.n", "xxx.!addrtype", "xxx.!addr", "xxx.!addr.0", "xxx.!addr.1" ... "xxx.!addr.n" will be set by the function, or queried by the function. ═══ 4. Special Note on Stemmed Variables ═══ The address and host type of parameters are stemmed variable names. Traditionally, you would pass a string like "addr." as a parameter, and expect to have the variables addr.family, addr.port, and addr.addr set by the function. In the examples above though, using a stem like "addr.!" was shown. The exclamation point helps to distinguish the tail values, so they won't get mis-used as normal variables. For instance, look at the following code: port = 923 sNew = SockAccept(sOld,"addr.") say addr.port You might expect the say statement to write the port number of the accepted socket. Instead it writes the value of the variable addr.923, since the port variable is SET to a value. Since you probably don't normally use exclamation points in your variables, it's unlikely that you will be using the variable "!port" in your program. Also note, some folk prefer other characters, including "_", "0", and "1" (the digits are allowed to prefix tail values and are very secure against this kind of accidental misuse - don't use them because the characters are hard to distinguish from O, I, and l). ═══ 5. Special Variables ═══ There are two variables that are maintained by the system:  Variable errno  Variable h_errno ═══ 5.1. Variable errno ═══ The errno variable is set after every REXX Socket Library (RxSock) function call. It will have one of the following values (or a numeric value if the number isn't one of these values): "EWOULDBLOCK" "EINPROGRESS" "EALREADY" "ENOTSOCK" "EDESTADDRREQ" "EMSGSIZE" "EPROTOTYPE" "ENOPROTOOPT" "EPROTONOSUPPORT" "ESOCKTNOSUPPORT" "EOPNOTSUPP" "EPFNOSUPPORT" "EAFNOSUPPORT" "EADDRINUSE" "EADDRNOTAVAIL" "ENETDOWN" "ENETUNREACH" "ENETRESET" "ECONNABORTED" "ECONNRESET" "ENOBUFS" "EISCONN" "ENOTCONN" "ESHUTDOWN" "ETOOMANYREFS" "ETIMEDOUT" "ECONNREFUSED" "ELOOP" "ENAMETOOLONG" "EHOSTDOWN" "EHOSTUNREACH" "ENOTEMPTY" Note the value is set even if the function that was called does not neccessarily set the variable, in which case the value has no meaning. The value 0 indicates no error occurred. ═══ 5.2. Variable h_errno ═══ The h_errno variable is set after every REXX Socket Library (RxSock) function call. It will have one of the following values (or a numeric value if the number isn't one of these values): "HOST_NOT_FOUND" "TRY_AGAIN" "NO_RECOVERY" "NO_ADDRESS" Note the value is set even if the function that was called does not neccessarily set the variable, in which case the value has no meaning. The value 0 indicates no error occurred. ═══ 6. Function Reference ═══ The following chapters provide a description of how the individal functions contained in the REXX Socket Library RxSock are invoked from the REXX programming environment:  SockLoadFuncs  SockDropFuncs  SockVersion  SockAccept  SockBind  SockClose  SockConnect  SockGetHostByAddr  SockGetHostByName  SockGetHostId  SockGetPeerName  SockGetSockName  SockGetSockOpt  SockInit  SockIoctl  SockListen  SockPSock_Errno  SockRecv  SockRecvFrom  SockSelect  SockSend  SockSendTo  SockSetSockOpt  SockShutDown  SockSock_Errno  SockSocket  SockSoClose ═══ 6.1. SockLoadFuncs ═══ The SockLoadFuncs() call loads all the functions in the REXX Socket Library RxSock package. Syntax: SockLoadFuncs([parm]) Parameters: If any parameter parm is passed to this function, it will bypass the program/copyright information normally displayed. All parameters are ignored except to determine whether or not to bypass displaying the information. ═══ 6.2. SockDropFuncs ═══ The SockDropFuncs call drops all the functions in the REXX Socket Library RxSock package. Syntax: SockDropFuncs() To unload the dynamic load library (DLL), you should first call SockDropFuncs(), then exit all CMD.EXE shells. After exiting all command shells, the DLL will be dropped by the system and can be deleted or replaced. ═══ 6.3. SockVersion ═══ The SockVersion() call provides the version number of the REXX Socket Library RxSock. Syntax: vers = SockVersion() Return Values: The returned result consists of an integral version number followed by a dot followed by an integral subversion number. An example is "2.0". Prior to version 1.2, this function did not exist. To check if a previous version of RxSock is installed, use the following code, after loading the function package with SockLoadFuncs(). /* oldVersion will be '1' if a version of RxSock < 1.2 is loaded */ oldVersion = (1 = RxFuncQuery("SockVersion")) ═══ 6.4. SockAccept ═══ The SockAccept() call accepts a connection request from a remote host. Syntax: csocket = SockAccept(socket[, address]) Parameters: socket is the socket descriptor address is a REXX stem variable that contains the socket address of the connection client when the SockAccept() call returns. This parameter is optional. It can be omitted if the caller is not interested in the client address. Description: This call is used by a server acting in a connection-oriented mode to accept a connection request from a client. The call accepts the first connection on its queue of pending connection requests. The SockAccept() call creates a new socket descriptor with the same properties as socket and returns it to the caller. The new socket descriptor cannot be used to accept new connections. The original socket socket, remains available to accept more connection requests. If the queue has no pending connection requests, SockAccept() blocks the caller unless socket is in nonblocking mode. If no connection requests are queued and socket is in nonblocking mode, SockAccept() returns -1 and sets the return code to EWOULDBLOCK. The socket parameter must be a socket descriptor created with the SockSocket() call. It is usually bound to an address with the SockBind() call and must be made capable of accepting connections with the SockListen() call. The SockListen() call marks the socket as one that accepts connections and allocates a queue to hold pending connection requests. The SockListen() call allows the caller to place an upper boundary on the size of the queue. The address parameter is where the connection requester address is placed. It is optional. You cannot screen requesters without calling SockAccept(). The application cannot tell the system the requesters it will accept connections from. The caller can, however, choose to close a connection immediately after discovering the identity of the requester. The SockSelect() call can be used to check the socket for incoming connection requests. Return Values: A non-negative client socket descriptor csocket indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EINTR Interrupted system call. EINVAL SockListen() was not called for socket socket. EOPNOTSUPP The socket parameter is not connection-oriented. EWOULDBLOCK The socket parameter is in nonblocking mode and no connections are on the queue. ECONNABORTED The software caused a connection close. NOTE: SockAccept() interfaces to the C function accept(). ═══ 6.5. SockBind ═══ The SockBind() call binds a local name to the socket. Syntax: rc = SockBind(socket, address) Parameters: socket is the socket descriptor returned by a previous call to SockSocket() address is a REXX stem variable containing the address that is to be bound to socket Description: The SockBind() call binds a unique local name address to the socket with descriptor socket. After calling SockSocket(), a descriptor does not have a name associated with it. However, it does belong to a particular addressing family as specified when SockSocket() is called. Because socket was created in the AF_INET domain, the fields of the REXX stem variable address are expected to be as follows: The family field must be set to "AF_INET". The port field is set to the port to which the application must bind. If port is set to 0, the caller leaves it to the system to assign an available port. The application can call SockGetSockName() to discover the port number assigned. The addr field is set to the internet address. On hosts with more than one network interface (called multihomed hosts), a caller can select the interface with which it is to bind. Subsequently, only UDP packets and TCP connection requests from this interface (which match the bound name) are routed to the application. If addr is set to "INADDR_ANY", the caller is requesting that the socket be bound to all network interfaces on the host. Subsequently, UDP packets and TCP connections from all interfaces (which match the bound name) are routed to the application. This becomes important when a server offers a service to multiple networks. By leaving the address unspecified, the server can accept all UDP packets and TCP connection requests made for its port, regardless of the network interface on which the requests arrived. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: EADDRINUSE The address is already in use. See the SO_REUSEADDR option described under SockGetSockOpt() and the SO_REUSEADDR option described under SockSetSockOpt(). EADDRNOTAVAIL The address specified is not valid on this host. For example, the Internet address does not specify a valid network interface. EAFNOSUPPORT The address family is not supported. ENOTSOCK The socket parameter is not a valid socket descriptor. EINVAL The socket is already bound to an address. ENOBUFS No buffer space is available. NOTE: SockBind() interfaces to the C function bind(). ═══ 6.6. SockClose ═══ The SockClose() call shuts down a socket and frees resources allocated to the socket. Syntax: rc = SockClose(socket) Parameter: socket is the Socket descriptor of the socket to be closed. Description: This call shuts down the socket associated with the socket descriptor socket, and frees resources allocated to the socket. If socket refers to a connected socket, the connection is closed. If the SO_LINGER socket option is enabled (see SockSetSockOpt() for additional information), then the task will try to send any queued data. If the SO_LINGER socket option is disabled, then the task will flush any data queued to be sent. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). The error codes are: ENOTSOCK The socket parameter is not a valid socket descriptor. EALREADY The socket socket is marked nonblocking, and a previous connection attempt has not completed. The Function SockClose() is exactly the same as SockSoClose(). NOTE: SockClose() interfaces to the C function soclose() or in the Windows environments to closesocket(). ═══ 6.7. SockConnect ═══ The SockConnect() socket call requests a connection to a remote host. Syntax: rc = SockConnect(socket, address) Parameters: socket is the socket descriptor used to originate the connection request address is a REXX stem variable containing the address of the socket to which a connection will be attempted Description: The SockConnect() call performs two tasks when called for a stream socket: 1. Completes the binding if necessary for a socket 2. Attempts to create a connection between two sockets. This call is used by the client side of socket-based applications to establish a connection with a server. The remote server must have a passive open pending. This means the server must successfully call SockBind() and SockListen(); otherwise, SockConnect() returns -1 and the error value is set to ECONNREFUSED. In the Internet communication domain, a timeout occurs if a connection to the remote host is not successful within 75 seconds (1 minute and 15 seconds). If the socket is in blocking mode, the SockConnect() call blocks the caller until the connection is established or until an error is received. If the socket is in nonblocking mode, SockConnect() returns -1 and sets the error value to EINPROGRESS if the connection was successfully initiated. The caller can test the completion of the connection setup by calling:  SockSelect(), to test for the ability to write to the socket  SockGetsockOpt(), with option SO_ERROR, to test if the connection succeeded Stream sockets can call SockConnect() only once. Datagram or raw sockets: The SockConnect() call specifies the destination peer address when called for a datagram or raw socket. Normally, datagram and raw sockets use connectionless data transfer calls such as SockSendTo() and SockRecvFrom(). However, applications can call SockConnect() to specify and store the destination peer address for this socket. The system will then know which address to send data to on this socket. This method of communication allows datagram and raw sockets to be connected. However, data is still not guaranteed to be delivered. Thus the normal features of connectionless mode sockets are maintained. The address is remembered until another SockConnect() call is made. This permits the use of SockRecv() and SockSend(), which are usually reserved for connection-oriented sockets. The application can still use SockSendTo(), SockRecvFrom(). The advantage of calling SockConnect() and being connected is that the destination peer address does not have to be specified for all datagrams sent. Datagram and raw sockets can call SockConnect() multiple times. The application can reset their destination address by specifying a new address on the SockConnect() call. In addition, the socket can be returned to operate in a connectionless mode by calling SockConnect() with a null destination address. The null address is created by setting the REXX stem variable address as follows: The family field is set to "AF_INET", the port field is set to 0, and the addr field is set to "0.0.0.0". The call to SockConnect will return -1, indicating that the connection to the null address cannot be established. Calling SockSock_Errno() will return EADDRNOTAVAIL. For more information on connecting datagram sockets, see "Description" for SockSendTo(). Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: EADDRNOTAVAIL The calling host cannot reach the specified destination. EAFNOSUPPORT The address family is not supported. EALREADY The socket socket is marked nonblocking, and a previous connection attempt has not completed. ENOTSOCK The socket parameter is not a valid socket descriptor. ECONNREFUSED The connection request was rejected by the destination host. EINPROGRESS The socket socket is marked nonblocking, and the connection cannot be completed immediately. The EINPROGRESS value does not indicate an error condition. EINTR Interrupted system call. EISCONN The socket socket is already connected. ENETUNREACH The network cannot be reached from this host. ETIMEDOUT The connection establishment timed out before a connection was made. ENOBUFS No buffer space is available. EOPNOTSUPP The operation is not supported on socket socket. NOTE: SockConnect interfaces to the C function connect(). ═══ 6.8. SockGetHostByAddr ═══ The SockGetHostByAddr() call retrieves host information on a specified host on the network using its address. Syntax: rc = SockGetHostByAddr(dotAddress, host[, domain]) Parameters: dotAddress is the standard dotted decimal address of the host host is a REXX stem variable that is to receive the information on the host. domain is the domain value. The only supported domain is "AF_INET". This parameter is optional. The default value is "AF_INET". Description: This socket call retrieves information on the host identified by its dotAddress. Return Values: Returns 1 for success, 0 for error. NOTE: SockGetHostByAdress() interfaces to the C function gethostbyaddr(). ═══ 6.9. SockGetHostByName ═══ The SockGetHostByName() call retrieves host information on a specified host on the network using its name. Syntax: rc = SockGetHostByName(nameAddress, host) Parameters: nameAddress should be the textual name of a host, for example "www.ibm.com". host is the name of a REXX stem variable that is to receive the information on the host. Description: This socket call retrieves information on the host identified by its hostname or any alias of it. Return Values: Returns 1 for success, 0 for error. NOTE: SockGetHostByName() interfaces to the C function gethostbyname(). ═══ 6.10. SockGetHostId ═══ The SockGetHostId() call retrieves the dotAddress of the local host. Syntax: dotAddress = SockGetHostId() Description: This socket call retrieves the dotAddress of the local host. Return Value: The dotAddress of the local host. NOTE: SockGetHostId() interfaces to the C function gethostid(). ═══ 6.11. SockGetPeerName ═══ The SockGetPeerName() call gets the name of the peer connected to a socket. Syntax: rc = SockGetPeerName(socket, address) Parameter: socket is the socket descriptor address is a REXX stem variable that is to contain the address of the peer connected to socket socket is returned. Description: This call returns the address of the peer connected to socket socket. This call operates only on connected sockets. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. ENOTCONN The socket is not connected. ENOBUFS No buffer space is available. NOTE: SockGetPeerName() interfaces to the C function getpeername(). ═══ 6.12. SockGetSockName ═══ The SockGetSockName() call gets the local socket name. Syntax: rc = SockGetSockName(socket, address) Parameters: socket is the socket descriptor address is a REXX stem variable that is to receive the address of the socket being returned. Description: This call returns the address for the socket specified by the socket parameter in the REXX stem variable address. It returns the address to the socket that has been bound. If the socket is not bound to an address, the call returns a null address. The returned null address is a REXX stem variable with the family field set to "AF_INET", the port field set to 0, and the addr field set to "0.0.0.0". Sockets are explicitly assigned an address after a successful call to SockBind(). Stream sockets are implicitly assigned an address after a successful call to SockConnect() or SockAccept() if SockBind() was not called. The SockGetSockName() call is often used to discover the port assigned to a socket after the socket has been implicitly bound to a port. For example, an application can call SockConnect() without previously calling SockBind(). In this case, the SockConnect() call completes the binding necessary by assigning a port to the socket. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. ENOBUFS No buffer space available. NOTE: SockGetSockName() interfaces to the C function getsockname(). ═══ 6.13. SockGetSockOpt ═══ The SockGetSockOpt() call gets the socket options associated with a socket. Syntax: rc = SockGetSockOpt(socket, level, optName, optVal) Parameters: socket Socket descriptor level Specifies which option level is being queried for the specified optname optname Name of a specified socket option. Only one option can be specified on a call. optval is the variable to receive the option data requested Description: This call returns the value of a socket option at the socket level. It can be called for sockets of all domain types. Some options are supported only for specific socket types. You must specify the level of the option and the name of the option to retrieve option values. The only supported level is SOL_SOCKET. The optval parameter is a variable where the option values are returned. For socket options that are Boolean, the option is enabled if optval is nonzero and disabled if optval is 0. The following options are recognized for SOL_SOCKET: SO_BROADCAST (datagram sockets only) Retrieves the current ability of the socket to broadcast messages. If this option is enabled, it allows the application to send broadcast messages over socket, if the interface specified in the destination supports broadcasting of packets. SO_DEBUG Retrieves the current ability for recording debug information for a socket. SO_DONTROUTE Retrieves the current ability for the socket to bypass routing. When this option is enabled, it causes outgoing messages to bypass the standard routing algorithm and be directed to the appropriate network interface, according to the network portion of the destination address. When enabled, packets can be sent only to directly connected networks (networks this host has an interface for). SO_ERROR Returns any pending error on the socket and clears the error status. It can be used to check for asynchronous errors on connected datagram sockets or for other asynchronous errors (errors that are not returned explicitly by one of the socket calls). SO_KEEPALIVE (stream sockets only) Retrieves the current ability of the socket to send keepalive packets. TCP uses a timer called the keepalive timer. This timer is used to monitor idle connections that might have been disconnected because of a peer crash or timeout. If this option is set on, a keepalive packet is periodically sent to the peer. This is mainly used to allow servers to close connections that are no longer active as a result of clients going away without properly closing connections. SO_LINGER (stream sockets only) Retrieves the current ability of the socket to linger on close if data is present. When this option is enabled and there is unsent data present when SockSoClose() is called, the calling application is blocked during the SockSoClose() call until the data is transmitted or the connection has timed out. If this option is disabled, the SockSoClose() call returns without blocking the caller, and TCP waits to try to send the data. Although the data transfer is usually successful, it cannot be guaranteed, because TCP waits only a finite amount of time trying to send the data. SO_OOBINLINE (stream sockets only) Retrieves the current ability of the socket to receive out-of-band data. When this option is enabled, it causes out-of-band data to be placed in the normal data input queue as it is received, making it available to SockRecv(), and SockRecvFrom() without having to specify the MSG_OOB flag in those calls. When this option is disabled, it causes out-of-band data to be placed in the priority data input queue as it is received, making it available to SockRecv(), and SockRecvFrom(), only by specifying the MSG_OOB flag in those calls. SO_RCVBUF Retrieves buffer size for input. This value tailors the receive buffer size for specific application needs, such as increasing the buffer size for high-volume connections. SO_RCVLOWAT Retrieves receive low-water mark information. SO_RCVTIMEO Retrieves the timeout value for a receive operation. SO_REUSEADDR (stream and datagram sockets only) Retrieves the current ability of the socket to reuse local addresses. When enabled, this option allows local addresses that are already in use to be bound. This alters the normal algorithm used in the SockBind() call. At connect time, the system checks to be sure that no local address and port have the same foreign address and port. The error EADDRINUSE is returned if the association already exists. SO_SNDBUF Retrieves the size of the send buffer. This value tailors the send buffer size for specific application needs, such as increasing the buffer size for high-volume connections. SO_SNDLOWAT Retrieves send low-water mark information. This value is ignored for nonblocking calls. For the Internet domain, this value is not used. SO_SNDTIMEO Retrieves the timeout value for a send operation. SO_TYPE Returns the type of the socket. On return, the integer pointed to by optval is set to one of the following: "STREAM", "DGRAM", "RAW", or "UNKNOWN". SO_USELOOPBACK Bypasses hardware when possible. Most of the options' values are integral. The exception is "SO_LINGER" that contains two blank delimited integers: 1. the l_onoff value. The l_onoff field is set to zero if the SO_LINGER option is being disabled. A nonzero value enables the option. 2. the l_linger value. The l_linger field specifies the amount of time in seconds to linger on close. A value of zero will cause SockSoClose() to wait until the disconnect completes. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: EADDRINUSE The address is already in use. ENOTSOCK The socket parameter is not a valid socket descriptor. ENOPROTOOPT The optname parameter or level parameter is not recognized. NOTE: SockGetSockOpt() interfaces to the C function getsockopt(). ═══ 6.14. SockInit ═══ The SockInit() call initializes the socket data structures. Syntax: rc = SockInit() Description: This call initializes the socket data structures and checks whether the TCP/IP network is active. Therefore, SockInit() should be called at the beginning of each program that uses SockSocket(). SockInit() is not strictly required as initalization is done for each REXX Function Library (RxSock) function in case the initialization has not yet occurred. For this reason, the explicit initialization function is not available in all system environments. Return Values: The value 0 indicates success; the value 1 indicates an error. NOTE: SockInit() interfaces to the C function sock_init(). ═══ 6.15. SockIoctl ═══ The SockIoctl() call performs special operations on socket. Syntax: rc = SockIoctl(socket, ioctlCmd, ioctlData) Parameters: socket Socket descriptor ioctlCmd is the ioctl command to perform. ioctlData is the command specific value. Description: This call controls the operating characteristics of sockets. The ioctlData parameter is a variable containing data associated with the particular command, and its format depends on the command that is requested. Valid commands are: FIONBIO Sets or clears nonblocking input/output for a socket. When this option is set, input/output calls will not block until the call is completed. The data parameter is an integer. If the integer is 0, nonblocking input/output on the socket is cleared. Otherwise, the socket is set for nonblocking input/output. FIONREAD Gets the number of immediately readable bytes for the socket. The data parameter is an integer. Sets the value of the integer to the number of immediately readable characters for the socket. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EINVAL The request is not valid or not supported. EOPNOTSUPP The operation is not supported on the socket. NOTE: SockIoctl() interfaces to the C function ioctl() or in the Windows environments to ioctlsocket(). ═══ 6.16. SockListen ═══ The SockListen() call completes the binding necessary for a socket to accept connections and creates a connection request queue for incoming requests. Syntax: rc = SockListen(socket, backlog) Parameter: socket is the socket descriptor. backlog controls the maximum queue length for pending connections. Description: The SockListen() call performs two tasks: 1. Completes the binding necessary for a socket socket, if SockBind() has not been called for socket 2. Creates a connection request queue of length backlog, to queue incoming connection requests. When the queue is full, additional connection requests are ignored. The SockListen() call indicates a readiness to accept client connection requests. It transforms an active socket into a passive socket. After SockListen() is called, socket can never be used as an active socket to initiate connection requests. SockListen() is called after allocating a socket with SockSocket() and after binding a name to socket with SockBind(). SockListen() must be called before calling SockAccept(). SockListen() can only be called on connection-oriented sockets. If the backlog parameter is less than 0, then SockListen() interprets backlog as 0. If the backlog parameter is greater than the maximum value as defined by the network system then SockListen() interprets backlog as this maximum value. Return Values: The value 0 indicates success, the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EOPNOTSUPP The socket parameter is not a socket descriptor that supports the SockListen() call. NOTE: SockListen() interfaces to the C function listen(). ═══ 6.17. SockPSock_Errno ═══ The SockPSock_Errno() call writes a short error message to the standard error device. Syntax: SockPSock_Errno([error_string]) Parameter: error_string will be the error string that is printed to standard error describing the last error encountered. It is optional. Description: This call writes a short error message to the standard error display describing the last error encountered during a call to a socket library function. If error_string is specified and is not an empty string, the string is printed, followed by a colon, followed by a space, followed by the message. If error_string is omitted or is an empty string, only the message is printed. The error code is acquired by calling SockSock_Errno(). The error code is set when errors occur. Subsequent socket calls do not clear the error code. NOTE: SockPSock_Errno() interfaces to the C function psock_errno(). ═══ 6.18. SockRecv ═══ The SockRecv() call receives data on a connected socket. Syntax: rc = SockRecv(socket, var, len[, flags]) Parameters: socket is the socket descriptor var is the name of a REXX variable the data should be received into. len is the maximum amount of data to read. flags is a blank delimited list of options: MSG_OOB Reads any out-of-band data on the socket. MSG_PEEK Peeks at the data present on the socket; the data is returned but not consumed, so that a subsequent receive operation sees the same data. Description: This call receives data on a socket with descriptor socket and stores it in the REXX variable named var. The SockRecv() call applies only to connected sockets. For information on how to use SockRecv() with datagram and raw sockets, see "Datagram or raw sockets" in SockConnect(). The SockRecv() call returns the length of the incoming data. If a datagram is too long to fit in the buffer, the excess is discarded. No data is discarded for stream sockets. If data is not available at the socket with descriptor socket, the SockRecv() call waits for a message to arrive and blocks the caller, unless the socket is in nonblocking mode. See SockIoctl() for a description of how to set nonblocking mode. Return Values: If successful, the length in bytes of the data is returned. The value 0 indicates that the connection is closed. The value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EINTR Interrupted system call. EINVAL Invalid argument. EWOULDBLOCK The socket parameter is in nonblocking mode and no data is available to receive, or the SO_RCVTIMEO option has been set for socket socket and the timeout expired before any data arrived to receive. NOTE: SockRecv() interfaces to the C function recv(). ═══ 6.19. SockRecvFrom ═══ The SockRecvFrom() call receives data on a socket. Syntax: rc = SockRecvFrom(socket, var, len[, flags], address) Parameters: socket is the socket descriptor var is the name of a REXX variable the data should be received into. len is the maximum amount of data to read. flags is a blank delimited list of options: MSG_OOB Reads any out-of-band data on the socket. MSG_PEEK Peeks at the data present on the socket; the data is returned but not consumed, so that a subsequent receive operation sees the same data. address is a REXX stem variable specifying the address of the sender the data is received from. Description: The SockRecvFrom() call receives data on a socket with descriptor socket and stores it in a REXX variable named var. The SockRecvFrom() call applies to any socket type, whether connected or not. If address is not a null address, the address of the sender of the data is returned. The SockRecvFrom() call returns the length of the incoming message or data. If a datagram is too long to fit in the supplied buffer, the excess is discarded. No data is discarded for stream sockets. If data is not available at the socket with descriptor socket, the SockRecvFrom() call waits for a message to arrive and blocks the caller, unless the socket is in nonblocking mode. See SockIoctl() for a description of how to set nonblocking mode. Return Values: If successful, the length, in bytes, of the data is returned. The value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EINVAL Invalid argument. EWOULDBLOCK The socket parameter is in nonblocking mode and no data is available to receive, or the SO_RCVTIMEO option has been set for socket socket and the timeout expired before any data arrived to receive. NOTE: SockRecvFrom() interfaces to the C function recvfrom(). ═══ 6.20. SockSelect ═══ The SockSelect() call monitors the activity on a socket by specifying the number of sockets to be checked for readability, readiness for writing, and exception pending conditions. Syntax: rc = SockSelect(reads, writes, excepts [, timeout]) Parameters: reads A Number of sockets to be checked for readability. writes A Number of sockets to be checked for readiness for writing. excepts A Number of sockets to be checked for exceptional pending conditions. For Network Services sockets, the only exceptional pending condition is out-of-band data in the receive buffer. timeout Maximum interval, in seconds, to wait for the selection to complete. Description: This call monitors activity on a set of different sockets until a timeout expires, to see if any sockets are ready for reading or writing, or if any exceptional conditions are pending. Each parameter specifying a number of sockets is specified by a stem variable which is queried and set by this function. The stem variable has the following format: The stem.0 variable should contain the number of sockets, stem.1 the first socket, etc. Upon return, the stem variables will be reset to the sockets which are ready. If any of the stem variables are "", or no parameter is passed, no sockets for that type will be checked. If the timeout value is 0, SockSelect() does not wait before returning. If the timeout value is "", SockSelect() does not timeout, but returns when a socket becomes ready. If the timeout value is a number of seconds, SockSelect() waits for the specified interval before returning. The SockSelect() call checks all indicated sockets at the same time and returns when any of them is ready. If no timeout value is passed, "" is assumed. The timeout value must be integral (no fractional values). Non-numeric and negative numbers are considered 0. Return Values: The number of ready sockets is returned. The value 0 indicates an expired time limit. In this case, the stem variables are not modified. The value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EFAULT The address is not valid. EINVAL Invalid argument. EINTR Interrupted system call. Examples: r.0 = 2 /* specify 2 sockets for read in stem r. */ r.1 = 101 r.2 = 102 /* specify 1 socket for write in stem w. */ w.0 = 1 w.1 = 103 /* no sockets for exceptions in stem e. */ e.0 = 0 rc = SockSelect("r.","w.","e.") do i = 1 to r.0 /* display sockets being ready for read /* say "socket" r.i "is ready for reading." end The SockSelect() call above could as well have been invoked as either of: rc = SockSelect("r.","w.","") rc = SockSelect("r.","w.",) The function call SockSelect(, , , x) results in the program pausing for x seconds. NOTE: SockSelect() interfaces to the C function select(). ═══ 6.21. SockSend ═══ The SockSend() call sends data on a connected socket. Syntax: rc = SockSend(socket, data[, flags]) Parameters: socket is the socket descriptor data is the name of a REXX variable containing the data to transmit flags is a blank delimited list of options: MSG_OOB Sends out-of-band data on sockets that support SOCK_STREAM communication. MSG_DONTROUTE The SO_DONTROUTE option is turned on for the duration of the operation. This is usually used only by diagnostic or routing programs. Description: This call sends data on the socket with descriptor socket. The SockSend() call applies to connected sockets. For information on how to use SockSend() with datagram and raw sockets, see "Datagram or raw sockets" in SockConnect(). If buffer space is not available at the socket to hold the data to be sent, the SockSend() call normally blocks, unless the socket is placed in nonblocking mode. See SockIoctl() for a description of how to set nonblocking mode. Use the SockSelect() call to determine when it is possible to send more data. Return Values: If successful, the number of bytes of the socket with descriptor socket that is added to the send buffer is returned. This may be less than the number of bytes specified in the length parameter. Successful completion does not imply that the data has already been delivered to the receiver. The return value -1 indicates an error was detected on the sending side of the connection. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EINTR Interrupted system call. EINVAL Invalid argument. ENOBUFS No buffer space is available to send the message. EWOULDBLOCK The socket parameter is in nonblocking mode and the data cannot be sent without blocking, or the SO_SNDTIMEO option has been set for socket socket and the timeout expired before any data was sent. Note. SockSend() interfaces to the C function send(). ═══ 6.22. SockSendTo ═══ The SockSentTo() call sends data on a socket. Syntax: rc = SockSendTo(socket, data[, flags], address) Parameters: socket is the socket descriptor data is a string of data to transmit flags is a blank delimited list of options: MSG_OOB Sends out-of-band data on sockets that support SOCK_STREAM communication. MSG_DONTROUTE The SO_DONTROUTE option is turned on for the duration of the operation. This is usually used only by diagnostic or routing programs. address is a REXX stem variable containing the destination address. Description: This call sends data on the socket with descriptor socket. The SockSendTo() call applies to connected or unconnected sockets. For unconnected datagram and raw sockets, the SockSendTo() call sends data to the specified destination address. For stream sockets the destination address is ignored. Datagram sockets are connected by calling SockConnect(). This identifies the peer to send/receive the datagram. Once a datagram socket is connected to a peer, you may still use the SockSendTo() call but a destination address cannot be included. To change the peer address when using connected datagram sockets, issue a SockConnect() call with a null address. Specifying a null address on a connected datagram socket removes the peer address specification. You can then either issue a SockSendTo() call specifying a different destination address or issue a SockConnect() call to connect to a different peer. For more information on connecting datagram sockets and specifying null addresses, see "Datagram or raw sockets" in SockConnect(). Return Values: If successful, the number of bytes sent is returned. Successful completion does not guarantee delivery of the data to the receiver. The return value -1 indicates an error was detected on the sending side. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). ENOTSOCK The socket parameter is not a valid socket descriptor. EMSGSIZE The message data was too big to be sent as a single datagram. ENOBUFS No buffer space is available to send the message. EWOULDBLOCK The socket parameter is in nonblocking mode and the data cannot be sent without blocking, or the SO_SNDTIMEO option has been set for socket socket and the timeout expired before any data was sent. ENOTCONN The socket is not connected. EDESTADDRREQ Destination address required. Note. SockSendTo() interfaces to the C function sendto(). ═══ 6.23. SockSetSockOpt ═══ The SockSetSockOpt() call sets options associated with a socket. Syntax: rc = SockSetSockOpt(socket, level, optName, optVal) Parameters: socket Socket descriptor level Specifies which option level is being set optname Name of a specified socket option optval option data value Description: This call sets options associated with a socket such as enabling debugging at the socket or protocol level, control timeouts, or permit socket data broadcast. Options can exist at the socket or the protocol level; options are always present at the highest socket level. When setting socket options, the level of the option level and the name of the option optname must be specified. The only supported level is SOL_SOCKET. The optval parameter is used to pass data used by the particular set command. The optval parameter is a variable containing the data needed by the set command. The optval parameter is optional and if data is not needed by the command, it can be omitted. For socket options that are toggles, the option is enabled if optval is nonzero and disabled if optval is 0. The following options are recognized for SOL_SOCKET: SO_BROADCAST (datagram sockets only) Sets the ability to broadcast messages. If this option is enabled, it allows the application to send broadcast messages over socket, if the interface specified in the destination supports broadcasting of packets. SO_DEBUG Sets the ability to record debug information for a socket. SO_DONTROUTE Sets the ability for the socket to bypass the routing of outgoing messages. When this option is enabled, it causes outgoing messages to bypass the standard routing algorithm and be directed to the appropriate network interface according to the network portion of the destination address. When enabled, packets can be sent only to directly connected networks (networks for which this host has an interface). SO_KEEPALIVE (stream sockets only) Sets the ability of the socket to send keepalive packets that will keep the connection alive. TCP uses a timer called the keepalive timer. This timer is used to monitor idle connections that might have been disconnected because of a peer crash or timeout. If this option is set on, a keepalive packet is periodically sent to the peer. This is mainly used to allow servers to close connections that are no longer active as a result of clients going away without properly closing connections. SO_LINGER (stream sockets only) Sets the ability of the socket to linger on close if data is present. When this option is enabled and there is unsent data present when SockSoClose() is called, the calling application is blocked during the SockSoClose() call until the data is transmitted or the connection has timed out. If this option is disabled, the SockSoClose() call returns without blocking the caller, and TCP waits to try to send the data. Although the data transfer is usually successful, it cannot be guaranteed, because TCP waits only a finite amount of time trying to send the data. SO_OOBINLINE (stream sockets only) Sets the ability of the socket to receive out-of-band data. As stated in TCP/IP Illustrated, Volume 1: The Protocols, out-of-band data is "a logically separate data path using the same connection as the normal data path." When this option is enabled, it causes out-of-band data to be placed in the normal data input queue as it is received, making it available to SockRecv(), and SockRecvFrom(), without having to specify the MSG_OOB flag in those calls. When this option is disabled, it causes out-of-band data to be placed in the priority data input queue as it is received, making it available to SockRecv(), and SockRecvFrom(), only by specifying the MSG_OOB flag in those calls. SO_RCVBUF Sets buffer size for input. This option sets the size of the receive buffer to the value contained in the buffer pointed to by optval. This allows the buffer size to be tailored for specific application needs, such as increasing the buffer size for high-volume connections. SO_RCVLOWAT Sets receive low-water mark. SO_RCVTIMEO Sets the timeout value for a receive operation. SO_REUSEADDR (stream and datagram sockets only) Sets the ability of a socket to reuse a local address. When enabled, this option allows local addresses that are already in use to be bound. This alters the normal algorithm used in theSockBind() call. The system checks at connect time to be sure that no local address and port have the same foreign address and port. The error SOCEADDRINUSE is returned if the association already exists. Multicast applications must set this socket option if they want to join the same Class D IP address and port for sending and receiving multicast packets. SO_SNDBUF Sets buffer size for output. This option sets the size of the send buffer to the value contained in the buffer pointed to by optval. This allows the send buffer size to be tailored for specific application needs, such as increasing the buffer size for high-volume connections. SO_SNDLOWAT Sets send low-water mark. SO_SNDTIMEO Sets the timeout value for a send operation. SO_USELOOPBACK Bypasses hardware when possible. Most of the options' values are integral. The exception is "SO_LINGER" that expects two blank delimited integers: 1. the l_onoff value. The l_onoff field is set to zero if the SO_LINGER option is being disabled. A nonzero value enables the option. 2. the l_linger value. The l_linger field specifies the amount of time in seconds to linger on close. A value of zero will cause SockSoClose() to wait until the disconnect completes. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: EADDRINUSE The address is already in use. ENOTSOCK The socket parameter is not a valid socket descriptor. ENOPROTOOPT The optname parameter is unrecognized. EINVAL Invalid argument. ENOBUFS No buffer space is available. NOTE: SockSetSockOpt() interfaces to the C function setsockopt(). ═══ 6.24. SockShutDown ═══ The SockShutDown() call shuts down all or part of a full duplex connection. Syntax: rc = SockShutDown(socket, howto) Parameters: socket is the socket descriptor howto is the condition of the shutdown Description: This call shuts down all or part of a full duplex connection. Since data flows in one direction are independent of data flowing from the other direction, the shutdown call allows you to independently stop data flow in either direction or all data flows with one API call. For example, you may want to stop the sender(s) from sending data to you, but you still want to send data. Using the SockShutDown() call is optional. The howto parameter sets the condition for shutting down the connection to socket socket. It can be set to one of the following:  0 - no more data can be received on socket socket.  1 - no more output to be allowed on the socket socket.  2 - no more data can be sent or received on socket socket. Return Values: The value 0 indicates success; the value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: ENOTSOCK The socket parameter is not a valid socket descriptor. EINVAL The howto parameter was not set to one of the valid values. NOTE: SockShutDown() interfaces to the C function shutdown(). ═══ 6.25. SockSock_Errno ═══ The SockSock_Errno() call returns an error code set by a socket call. Syntax: errno = SockSock_Errno() Description: The SockSock_Errno() call returns the last error code set by a socket call. Subsequent socket API calls do not reset this error code. NOTE: SockSock_Errno() interfaces to the C function sock_errno(). ═══ 6.26. SockSocket ═══ The SockSocket() call creates an endpoint for communication and returns a socket descriptor representing the endpoint. Syntax: socket = SockSocket(domain, type, protocol) Parameters: domain is the communication domain requested type is the type of socket created protocol is the protocol requested domain must be "AF_INET", type may be one of "SOCK_STREAM", "SOCK_DGRAM", or "SOCK_RAW", and protocol may be one of "IPPROTO_UDP", "IPPROTO_TCP", or "0". Description: This call creates an endpoint for communication and returns a socket descriptor representing the endpoint. Each socket type provides a different communication service. Sockets are deallocated with the SockClose() call. The domain parameter specifies a communications domain where communication is to take place. This parameter specifies the protocol family which is used. AF_INET Use addresses in the Internet address format. The type parameter specifies the type of socket created. The type is analogous with the semantics of the communication requested. The types supported are: SOCK_STREAM Provides sequenced, two-way byte streams that are reliable and connection-oriented. It supports a mechanism for out-of-band data. Stream sockets are supported by the Internet (AF_INET) communication domain. SOCK_DGRAM Provides datagrams, which are connectionless messages of a fixed length whose reliability is not guaranteed. Datagrams can be received out of order, lost, or delivered multiple times. Datagram sockets are supported by the Internet (AF_INET) communication domain. SOCK_RAW Provides the interface to internal protocols (such as IP and ICMP). Raw sockets are supported by the Internet (AF_INET) communication domain. The protocol parameter specifies a particular protocol to be used with the socket. If the protocol field is set to 0 (default), the system selects the default protocol number for the domain and socket type requested. Return Values: A non-negative socket descriptor return value indicates success. The return value -1 indicates an error. You can get the specific error code by calling SockSock_Errno() or SockPSock_Errno(). These are: EMFILE The maximum number of sockets are currently in use. EPROTONOSUPPORT The protocol is not supported in the specified domain or the protocol is not supported for the specified socket type. EPFNOSUPPORT The protocol family is not supported. ESOCKTNOSUPPORT The socket type is not supported. NOTE: SockSocket() interfaces to the C function socket(). ═══ 6.27. SockSoClose ═══ The SockSoClose() call shuts down a socket and frees resources allocated to the socket. Syntax: rc = SockSoClose(socket) Parameter: socket is the socket descriptor of the socket to be closed. This function is identical to SockClose(). For a detailed description of SockSoClose(), please refer to SockClose().