The following are functions that read from a socket or prepare for accepting incoming connections:

SockBind Associates a socket with a port.
SockListen Sets a server's socket to listen for incoming connections.
SockRecv Gets a string from the connected computer.
SockRecvFrom Gets a datagram (string), and identifies the computer that sent it.


SockBind

Associates a socket (created with SockSocket) to a port on the computer so that the socket can "listen" for a connection (from some other computer) to that port. This is called by a server script in preparation of receiving connections from clients.

Calls the sockets library's bind() function.

Synopsis

err = SockBind(socket, 'assoc.')

Args

socket is server's socket returned by SockSocket.

address is the local dotted IP address.

assoc. is a stem variable that should be filled in prior to the call to SockBind. assoc.FAMILY is a string that represents the addressing family, usually "AF_INET" for internet style addressing. assoc.PORT is the port number upon which to listen for connections. assoc.ADDR is the computer's dotted IP address (as may be returned by SockGetHostByName) or the computer's network name (as may be returned by SockGetHostByAddr or SockGetHostId) or the string "INADDR_ANY" to use the first defined IP address of the computer.

Returns


0 if success, or -1 if the association fails.

Notes

The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.

Note: The SockSocket function takes extra args which makes calling SockBind unnecessary.


SockListen

Sets a server's socket to listen for incoming connections.

Calls sockets library's listen() function.

Synopsis

err = SockListen(socket, backlog)

Args

socket is the server's socket returned by SockSocket. The socket must have been created with a type of "SOCK_STREAM".

backlog is a number indicating the maximum allowed number of pending connections from clients.

Returns


0 if success, or -1 if listen() fails.

Notes

The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.

To accept connections, a socket is first created with SockSocket, a backlog for incoming connections is specified with SockListen, and then the connections are accepted with SockAccept. SockListen applies only to sockets that support connections, in other words, those of type SOCK_STREAM. The socket passed to SockListen is put into "passive" mode where incoming connections are acknowledged and queued pending acceptance by the REXX script (using SockAccept). SockListen is typically used by servers that could have more than one connection request at a time: if a connection request arrives with the queue full, the client will receive an error with an indication of ECONNREFUSED. SockListen attempts to continue to function correctly when there are no available descriptors. It will accept connections until the queue is emptied. If descriptors become available, a later call to SockListen or SockAccept will refill the queue to the current or most recent "backlog," if possible, and resume listening for incoming connections.

Note: The SockSocket function takes extra args which makes calling SockListen unnecessary.


SockRecv

Gets a string from the connected computer.

Calls the sockets library's recv() function.

Synopsis

count = SockRecv(socket, 'buf', maxbytes, flags)

Args

socket is the socket returned by SockSocket or SockAccept.

'buf' is name of the REXX variable where you wish SockRecv to store the received string.

maxBytes is number of bytes you want to read.

flags is any (or none) of the following, separated by a space:

MSG_PEEK Peek at the incoming data. The data is returned but is not removed from the input queue.
MSG_OOB Process out-of-band data.

If omitted, defaults to none of the above.

Returns


The number of chars actually gotten and returned in 'buf' if success, or 0 if the connection has been closed, or -1 if an error.

Notes

The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.

For a socket of type SOCK_STREAM, as much information as is currently available up to maxBytes amount of characters is returned. If the socket's SO_OOBINLINE option has been enabled (ie, the socket has been configured for in-line reception of out-of-band data) and out-of-band data is waiting to be read, only out-of-band data will be returned. The script may use the SockIoctl's "SIOCATMARK" command to determine whether any more out-of-band data remains to be read.

For datagram sockets, data is extracted from the first enqueued datagram, up to maxBytes amount of characters. If the datagram is larger than maxBytes, then 'buf' is set to the first part of the datagram, the excess data is lost, and SockRecv sets ErrNo = "EMSGSIZE".

If no incoming data is available at the socket, SockRecv waits for data to arrive unless the socket is non-blocking. For non-blocking, a value of -1 is returned and ErrNo = "EWOULDBLOCK" if there is no data waiting to be read. SockSelect can be used to determine when more data arrives.

If the socket is of type "SOCK_STREAM" and the remote side has shut down the connection gracefully, a SockRecv will complete immediately with 0 bytes received. If the connection has been reset, a SockRecv will fail with ErrNo = "ECONNRESET".


SockRecvFrom

Gets a datagram (string), and identifies the computer that sent it.

Calls the sockets library's recvfrom() function.

Synopsis

count = SockRecvFrom(socket, 'buf', maxbytes, flags, 'peer.')

Args

socket is the socket returned by SockSocket.

'buf' is name of the REXX variable where you wish SockRecvFrom to store the received datagram string.

maxBytes is number of bytes you want to read of the datagram. (Any excess bytes of the datagram will be discarded).

flags is any (or none) of the following, separated by a space:

MSG_PEEK Peek at the incoming data. The data is returned but is not removed from the input queue.
MSG_OOB Process out-of-band data.

If omitted, defaults to none of the above.

peer. is the name of the stem variable whose tails, peer.FAMILY, peer.PORT, and peer.ADDR SockRecvFrom will set to the Address Family, Port number, and dotted IP address of the computer that sent the datagram.

Returns


The number of chars actually gotten and returned in 'buf' if successful, or 0 if the connection has been closed, or -1 if an error.

Notes

The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.

Although SockRecvFrom is primary to be used with sockets of type SOCK_DGRAM, it can also be used to read data from a socket of type SOCK_STREAM. But SockRecvFrom does not return accurate information about who sent data in the case of a SOCK_STREAM type socket.

See the notes under SockRecv.