The major difference is there is no SockErrMsg() function in the Debian RxSock. Instead the standard error indications are used:
SockSock_Errno(), SockPSock_Errno(), ERRNO are only valid after a failed socket function call, otherwise they are undefined. Each function call returns its own success/failure indicator, described below.
A full list of sockets errors can be found here - errno.h. (If this link is dead, it's /usr/include/asm/errno.h in the libc6-dev package.)
These OS/2 docs may also be useful.
Jeff has said that he is willing to help with porting his version to Linux as he is able, although he doesn't run Linux himself.
In the SYNTAX section for each function, when a parameter is enclosed in braces [ and ], then this means that the parameter is optional. (ie, Its value can be omitted). RXSOCK will then usually substitute some default value for that parameter, or perform some default action.
For some RXSOCK functions, they need to be passed the name of a REXX variable to operate upon.
In the PARAMS section for each function, when part of a REXX variable name is enclosed in parenthesis, then this means that the actual passed parameter is substituted. For example, let's assume that there is an RXSOCK function named SockSomething() that is passed the name of a REXX stem variable. Its SYNTAX is defined as so:
SYNTAX:
CALL SockSomething('stem.')
Also, under the PARAMS section of SockSomething() is the following text:
PARAMS:
SockSomething() sets the REXX compound variable "(stem.)FAMILY" to 1.
Now assume that the REXX script calls SockSomething() as so:
CALL SockSomething("myvar.")
Then for the expression "(stem.)FAMILY", SockSomething() would substitute what was actually passed and it would therefore set the REXX variable MYVAR.FAMILY to 1.
Note that normal REXX tail name substitution is performed by RXSOCK. For example, assume that the REXX script has the following statements:
FAMILY = 'this'
CALL SockSomething("myvar.")
Then the REXX variable that RXSOCK sets to 1 would actually be MYVAR.THIS. (ie, "FAMILY" gets substituted with its value). If you wish to avoid this behavior, one technique is to pass a stem name with an exclamation point appended to it, and use exclamation points only with your variable names passed to RXSOCK, as so:
CALL SockSomething("myvar.!")
This helps circumvent the problem with tail name substitution. Since you probably don't normally use exclamation points in variables used in other places in your script, it's unlikely that you will be using the variable "!FAMILY" elsewhere in your script, and therefore do not have to worry about it having some preceding value. So the REXX variable that RXSOCK sets to 1 would be MYVAR.!FAMILY. (ie, The exclamation point is included in the variable name).
In lieu of an exclamation point, you may prefer other characters, including "_", "0", and "1". (The digits 0 and 1 are allowed to prefix tail names and are very useful for preventing an unwanted tail name substitution by RXSOCK).
A dotted IP address is an internet "address" containing 4 numbers separated by 3 decimal points. For example, the string "9.23.19.63" is a valid dotted IP address.
For the majority of RXSOCK functions, they set the value of the REXX variable named "ERRNO". If an RXSOCK function succeeds, then ERRNO is set to 0. If an RXSOCK function fails, then ERRNO is set to some "symbolic error name". For example, if SockSend() fails because the connection to the external peer was reset by that peer, then ERRNO is set to the (string) value "ECONNRESET".
To retrieve an informative error message about that failure, you can use the RXSOCK function SockErrMsg().
So, here is an example of how a failure in some RXSOCK function would be handled, and how to display an appropriate error message:
CALL SockSomething("myvar.")
IF ERRNO \== 0 THEN SAY SockErrMsg()
ELSE SAY "SockSomething() performed successfully!"
A full list of sockets errors can be found here - errno.h. (If this link is dead, it's /usr/include/asm/errno.h in the libc6-dev package.)
Allows a REXX script running upon a server to begin accepting connections from clients. Calls the sockets library's accept() function.
SYNTAX:
err = SockAccept(socket [, 'addr.'])
PARAMS:
'socket' is the socket number returned by SockSocket().
'addr.' is the name of a stem variable that SockAccept() fills in with information about the client that has been "accepted". SockAccept() fills in the REXX compound variable "(addr.)FAMILY" with the client's Address Family, "(addr.)PORT" with the client's port number, and "(addr.)ADDR" with the client's dotted IP Address. If 'addr.' is omitted, no such information is returned.
RETURNS:
'err' is 0 if success, or -1 if bad parameters or accept() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Associates a local address with a socket. Calls the sockets library's bind() function.
SYNTAX:
err = SockBind(socket, address)
PARAMS:
'socket' is the socket number returned by SockSocket().
'address' is a dotted IP address.
RETURNS:
'err' is 0 if success, or -1 if bad parameters or association fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Closes the socket which was opened by SockSocket(), and frees resources associated with it. Calls the sockets library's closesocket() function.
SYNTAX:
err = SockClose(socket)
PARAMS:
'socket' is the socket number returned by SockSocket().
RETURNS:
'err' is 0 if success, or -1 if bad parameters or closesocket() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
SockShutdown() should be called first.
The behavior of SockClose() is affected by the socket option SO_LINGER as follows:
| Option | Type of close | Wait for close? |
| SO_LINGER is off | Graceful | No |
| SO_LINGER is on with 0 timeout | Hard | No |
| SO_LINGER is on with timeout | Graceful | Yes |
If SO_LINGER option is turned on with a zero timeout interval, then SockClose() is not blocked even if queued data has not yet been sent or acknowledged by the underlying sockets library. This is called a "hard" or "abortive" close, because the socket's virtual circuit is reset immediately, and any unsent data is lost. Any SockRecv() call on the remote side of the circuit will fail with ERRNO = "ECONNRESET".
If SO_LINGER option is turned on with a nonzero timeout interval, then SockClose() blocks until the remaining data has been sent or until the timeout expires. This is called a "graceful disconnect". Note that if the socket is set to nonblocking and SO_LINGER is set to a nonzero timeout, then SockClose() will fail with ERRNO = "EWOULDBLOCK".
If SO_LINGER option is turned off with a stream socket, then SockClose() will return immediately. However, any data queued for transmission will be sent if possible before the underlying socket is closed. This is also called a graceful disconnect. Note that in this case the WIN32 sockets implementation may not release the socket and other resources for an arbitrary period, which may affect applications that expect to use all available sockets.
Calls the sockets library's connect() function to connect to another computer (peer). This must be done once before calling any RXSOCK function to send or receive data from that peer.
SYNTAX:
err = SockConnect(socket, 'peer.')
PARAMS:
'socket' is the socket number returned by SockSocket().
'peer.' is a stem variable that should be filled in prior to the call to SockConnect(). "(peer.)FAMILY" is a string that represents the addressing family, usually "AF_INET" for internet style addressing. "(peer.)PORT" is the well known port number on the peer to connect to. "(peer.)ADDR is the peer's (ie, other computer's) dotted IP address (as may be returned by SockGetHostByName()).
RETURNS:
'err' is 0 if success, or -1 if bad parameters or connect() fails.
On a nonblocking socket, if the return value is -1, the script
should check the REXX variable 'ERRNO'. If ERRNO is "EWOULDBLOCK",
then your script can use SockSelect()
to determine the completion of the connection request by checking if the
socket is writeable.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
SockConnect() is used to create a connection to a particular peer. 'socket' specifies an unconnected datagram or stream socket. If the socket is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound. Note that if "(peer.)ADDR is all zeroes, SockConnect() will set ERRNO = "EADDRNOTAVAIL". For stream sockets (type SOCK_STREAM), an active connection is initiated to the foreign host using "(peer.)ADDR" and "(peer.)PORT". When SockConnect() completes successfully, the socket is ready to send and receive data. For a datagram socket (type SOCK_DGRAM), a default destination is set, which will be used on subsequent SockSend() and SockRecv() calls.
Drops all the RXSOCK functions, making them unavailable to Rexx. This is usually called only if the REXX script has previously called SockLoadFuncs().
SYNTAX:
CALL SockDropFuncs()
Returns an error message pertaining to the specified symbolic error name.
SYNTAX:
err_message = SockErrMsg(errno)
PARAMS:
'errno' is the symbolic error name (ie, what RXSOCK sets the REXX variable 'ERRNO'
to) for which the respective error message is returned.
A full list of sockets errors can be found here - errno.h. (If this link is dead, it's /usr/include/asm/errno.h in the libc6-dev package.)
RETURNS:
'err_message' is the error message that pertains to 'errno'.
NOTES:
The error messages that different socket libraries return may vary.
If passed an error name that it doesn't recognize, then SockErrMsg() simply returns that same error name as 'err_message'. For example, the following call: CALL SockErrMsg("CTRL-C") will return an error message of "CTRL-C".
Converts a dotted IP address to a TCP/IP alias. This is the complement to SockGetHostByName(). Calls sockets library's gethostbyaddr() function.
SYNTAX:
err = SockGetHostByAddr(address, 'host.' [, domain])
PARAMS:
'address' is the dotted IP address.
'host.' is the name of the stem variable whose tails "(host.)ADDRTYPE", "(host.)ADDR", and "(host.)NAME" will be set to the host's Address Family (ie, "AF_INET"), the host's dotted IP address, and the alias name, respectively. Furthermore, "(host.)ALIAS.0" is set to the number of alias names the host has. The variables "(host.)ALIAS.1" through "(host.)ALIAS.(host.ALIAS.0)" will be those alias names. "(host.)ADDR.0" is set to the number of alias addresss the host has. The variables "(host.)ADDR.1" through "(host.)ADDR.(host.ADDR.0)" will be those alias addresses.
'domain' must be the string "AF_INET". (ie, RXSOCK supports only internet domain connections).
RETURNS:
'err' is 1 if success, or 0 if bad parameters or gethostbyaddr()
fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Converts a TCP/IP alias to a dotted IP address. For example, passing an alias of "microsoft.com" will look up and return the dotted IP address for "microsoft.com". Calls the sockets library's gethostbyname() function.
SYNTAX:
err = SockGetHostByName(name, 'host.')
PARAMS:
'name' is the TCP/IP alias, such as "microsoft.com".
'host.' is the name of the stem variable whose tails "(host.)ADDRTYPE", "(host.)ADDR", and "(host.)NAME" will be set to the host's Address Family (ie, "AF_INET"), the host's dotted IP address, and the alias name, respectively. Furthermore, "(host.)ALIAS.0" is set to the number of alias names the host has. The variables "(host.)ALIAS.1" through "(host.)ALIAS.(host.ALIAS.0)" will be those alias names. "(host.)ADDR.0" is set to the number of alias addresss the host has. The variables "(host.)ADDR.1" through "(host.)ADDR.(host.ADDR.0)" will be those alias addresses.
RETURNS:
'err' is 1 if success, or 0 if bad parameters or gethostbyname()
fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Retrieves the local dotted IP address (ie, the address of the machine upon which this script is run). Calls the sockets library's gethostid() function.
SYNTAX:
address = SockGetHostId()
RETURNS:
'address' is the dotted IP address of the host if success, or a
nul string if an error.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Retrieves the dotted IP address of the computer (peer) to which the system running the REXX script is connected. Calls sockets library's getpeername() function.
SYNTAX:
err = SockGetPeerName(socket, 'addr.')
PARAMS:
'socket' is the socket number returned by SockSocket().
'addr.' is the name of the stem variable whose tails, "(addr.)FAMILY", "(addr.)PORT", and "(addr.)ADDR" are set to the Address Family, Port number, and dotted IP address of the peer.
RETURNS:
'err' is 0 if success, or -1 if bad parameters or getpeername() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Gets the local name for the specified socket. Calls the sockets library's getsockname() function.
SYNTAX:
err = SockGetSockName(socket, 'addr.')
PARAMS:
'socket' is the socket number returned by SockSocket().
'addr.' is the name of the stem variable whose tails, "(addr.)FAMILY", "(addr.)PORT", and "(addr.)ADDR" are set to the Address Family, Port number, and dotted IP address of the local socket.
RETURNS:
'err' is 0 if success, or -1 if bad parameters or getsockname() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
SockGetSockName() retrieves the current name for the specified socket. It is used on a bound or connected socket. The local association is returned. This call is especially useful when SockConnect() has been called without doing a SockBind() upon that socket first; SockGetSockName() provides the only means by which you can determine the local association set by the system.
If a socket was bound to INADDR_ANY, indicating that any of the host's IP addresses should be used for the socket, SockGetSockName() will not necessarily return information about the host IP address, unless the socket has been connected with SockConnect() or SockAccept(). A script must not assume that the IP address will be changed from INADDR_ANY unless the socket is connected. This is because for a multi-homed host, the IP address that will be used for the socket is unknown unless the socket is connected.
Retrieves the current value of a particular option of a socket. Calls the sockets library's getsockopt() function.
SYNTAX:
err = SockGetSockOpt(socket, level, optVar, 'optVal')
PARAMS:
'socket' is the socket number returned by SockSocket().
'level' must be the string "SOL_SOCKET".
'optVar' is the option whose value is retrieved. It can be one of the strings listed in SockSetSockOpt() (ie, to retrieve the value of that option).
'optVal' is the name of the REXX variable whose value is set to the current value of the requested option.
RETURNS:
'err' is 0 if success, or -1 if bad parameters or getsockopt() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Initializes the socket interface. It is not necessarily to call this. It is provided only for backward compatibility.
SYNTAX:
err = SockInit()
RETURNS:
'err' is 0 if success, or 1 if an error.
Controls the mode of a socket. SockIoctl() may be used on any socket in any state. It is used to get or set operating parameters associated with the socket, independent of the protocol and communications subsystem. Calls the sockets library's ioctlsocket() function.
SYNTAX:
err = SockIoctl(socket, ioctlCmd, ioctlData)
PARAMS:
'socket' is the socket number returned by SockSocket().
'ioctlCmd' is one of the following command strings:
| FIONBIO | Enable or disable nonblocking mode on the socket 'ioctlData' is nonzero if nonblocking mode is to be enabled and zero if it is to be disabled. When a socket is created, it operates in blocking mode (that is, nonblocking mode is disabled). |
| FIONREAD | Determine the amount of data that can be read atomically from the socket. 'ioctlData' is the name of a REXX variable where SockIoctl() returns information. If 'socket' is of type "SOCK_STREAM", then 'ioctlData' is set to the total amount of data that can be read in a single SockRecv(); this is normally the same as the total amount of data queued on the socket. If 'socket' is of type "SOCK_DGRAM", 'ioctlData' is set to the size of the first datagram queued on the socket. |
| SIOCATMARK | Determine whether all out-of-band data has been read. This applies only to a socket of type SOCK_STREAM that has been configured for in-line reception of any out-of-band data (SO_OOBINLINE). If no out-of-band data is waiting to be read, 'ioctlData' = 1. Otherwise, 'ioctlData' = 0, and the next SockRecv() or SockRecvFrom() performed on the socket will retrieve some or all of the data preceding the "mark"; the script should use "SIOCATMARK" to determine whether any data remains. If there is any normal data preceding the "urgent" (out-of-band) data, it will be received in order. (Note that a SockRecv() or SockRecvFrom() will never mix out-of-band and normal data in the same call). |
RETURNS:
'err' is 0 if success, or -1 if bad parameters or ioctlsocket() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Establishes a socket to listen for incoming connection. Calls sockets library's listen() function.
SYNTAX:
err = SockListen(socket, backlog)
PARAMS:
'socket' is the socket number returned by SockSocket().
'backlog' is a number indicating the maximum length to which the queue of pending connections may grow.
RETURNS:
'err' is 0 if success, or -1 if bad parameters or listen() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
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.
Makes all the RXSOCK functions available to Rexx.
SYNTAX:
err = SockLoadFuncs()
RETURNS:
'err' is a null string if success, or REXXSAA API error number for
RexxRegisterFunctionDll() if an error.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
If using Reginald's auto-load feature, you do not need to call SockLoadFuncs() to make the RXSOCK functions available to your script. (Nor do you need to call SockDropFuncs()).
Writes an error message to STDERR pertaining to the last sockets library error (not necessarily the last RXSOCK error -- use SockErrMsg() for that). Calls the sockets library function psock_errno().
SYNTAX:
CALL SockPSock_Errno([message])
PARAMS:
'message' is an optional string that is written out prior to the
error message. A colon followed by a space will be automatically
appended to 'message' before the error message is also appended.
NOTES:
SockPSock_Errno() is provided for backward compatibility. A
script should instead use SockErrMsg().
Receives a string from the connected peer. Calls the sockets library's recv() function.
SYNTAX:
count = SockRecv(socket, buf, maxBytes [, flags])
PARAMS:
'socket' is the socket number returned by SockSocket().
'buf' is the name of the REXX variable that is set to the string received.
'maxBytes' is number of bytes desired.
'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. |
RETURNS:
'count' is the number of chars actually read and returned in 'buf'
if success, or 0 if the connection has been closed, or -1 if bad
parameters or an error.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
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 has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data will be returned. The script may use the SockIoctl() "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 nonblocking. In this case a value of -1 is returned and ERRNO = "EWOULDBLOCK". 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".
Receives a string from the connected peer. Calls the sockets library's recvfrom() function.
SYNTAX:
count = SockRecvFrom(socket, 'buf', maxBytes [, flags], 'addr.')
PARAMS:
'socket' is the socket number returned by SockSocket().
'buf' is the name of the REXX variable that is set to the string received.
'maxBytes' is number of bytes desired.
'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. |
'addr.' is the name of the stem variable whose tails, "(addr.)FAMILY", "(addr.)PORT", and "(addr.)ADDR" are set to the Address Family, Port number, and dotted IP address of the peer from whom the bytes are received.
RETURNS:
'count' is the number of chars actually read and returned in 'buf'
if success, or 0 if the connection has been closed, or -1 if bad
parameters or an error.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
See the notes under SockRecv().
Determines the status of one or more sockets, waiting if necessary. SockSelect() is used to determine the status of one or more sockets. For each socket, the script may request information on read, write, or error status. The set of sockets for which a given status is requested is indicated by the "reads", "writes", and "excepts" REXX variables. Upon return, these variables are updated to reflect the subset of these sockets that meet the specified condition, and SockSelect() returns the number of sockets meeting the conditions. Calls the sockets library's select() function.
SYNTAX:
count = SockSelect(reads, writes, excepts [, timeoutsecs])
PARAMS:
'reads' is the name of the REXX variable whose tails are the set of
sockets to be checked for readability. "(reads).0" is a count of
how many tails contain socket numbers. "(reads).1" contains the first
socket number. "(reads).2" contains the second socket number. Etc. If
a socket is currently listening (ie, that socket number has been used
with a call to SockListen()), then it will be marked as readable if
an incoming connection request has been received. so that SockAccept()
is guaranteed to complete without blocking. For other sockets,
readability means that queued data is available for reading or, for
sockets of type SOCK_STREAM, that the virtual socket corresponding
to the socket has been closed, so that a SockRecv() or SockRecvFrom()
is guaranteed to complete without blocking. If the virtual circuit
was closed gracefully, then a SockRecv() will return immediately with
zero bytes read; if the virtual circuit was reset, then a SockRecv()
will complete immediately with 'ERRNO' set to ECONNRESET. The
presence of out-of-band data will be checked if the socket option
SO_OOBINLINE has been enabled (see SockSetSockOpt()).
'writes' is the name of the REXX variable whose tails are the set of sockets to be checked for writeability. "(writes).0" is a count of how many tails contain socket numbers. "(writes).1" contains the first socket number. "(writes).2" contains the second socket number. Etc. If a socket is not in the process of connecting, writability means that a SockSend() or SockSendTo() will complete without blocking. (It is not specified how long this guarantee can be assumed to be valid, particularly in a multithreaded environment).
'excepts' is the name of the REXX variable whose tails are the set of sockets to be checked for out-of-band data or any exceptional error conditions. "(excepts).0" is a count of how many tails contain socket numbers. "(excepts).1" contains the first socket number. "(excepts).2" contains the second socket number. Etc. Note that out-of-band data will only be reported in this way if the SO_OOBINLINE option is not enabled. For a socket of type SOCK_STREAM, the breaking of the connection by the peer or due to KEEPALIVE failure will be indicated as an exception. This specification does not define which other errors will be included. If a socket is connecting (nonblocking), failure of the connect attempt is indicated in the returned "(excepts).(socket_number)".
'timeoutsecs' is the timeout period (in seconds) to wait for the check to complete before aborting.
RETURNS:
'count' is the total number of sockets that are ready and contained
in REXX variables (reads), (writes), and [excepts] , or 0 if timeout,
or -1 if error. SockSelect() also updates "(reads).0" to indicate how
many sockets are set for readability, and then sets that many tails,
starting with "(reads).1" to those socket numbers that are set for
readability. SockSelect() does the same for (writes) and "excepts"
for sockets set for writeability, and errors/out of band data,
respectively.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
'reads', 'writes', and/or 'excepts' may be set to empty string (ie, "") if there are no sockets to be checked for readability, writeability, or errors/out of band data, respectively.
The maximum number of (reads), (writes), or (excepts) tails is 64 for each. (ie, Upto 64 sockets can be checked for readability, 64 for writeability, and 64 for errors/out of band data. SockSelect() may vary slightly from OS/2 RXSOCK's behavior in that, when you specify too many sockets to check, this simply returns error (-1). OS/2 RXSOCK's maximum number of sockets, and its behavior when that maximum is exceeded, is not documented, and so this version of RXSOCK therefore sets its own criteria.
Sends data to an already-connected peer. Calls the sockets library's send() function.
SYNTAX:
sent = SockSend(socket, data [, flags])
PARAMS:
'socket' is the socket number returned by SockSocket().
'data' is the data string to send.
'flags' is any (or none) of the following, separated by a space:
| MSG_DONTROUTE | The data should not be subject to routing. |
| MSG_OOB | Send out-of-band data. |
RETURNS:
'sent' is the number of chars (bytes) actually sent. Could be
0 if an error.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
SockSend() is used on connected datagram or stream sockets and is used to write outgoing data on a socket.
For datagram sockets, care must be taken not to exceed the maximum IP packet size of the underlying subnets, which is returned by SockMaxPacketSize(). If the data is too long to pass atomically through the underlying protocol, then ERRNO = "EMSGSIZE", and no data is transmitted.
The successful completion of SockSend() does not indicate that the data was successfully delivered.
SockSend() will likely block unless the socket has been placed in a nonblocking I/O mode. On nonblocking SOCK_STREAM sockets, the number of bytes written may be between 1 and the requested length, depending on buffer availability on both the local and foreign computers. SockSelect() may be used to determine when it is possible to send more data.
Sends a string of data to a specified peer. Calls the sockets library's sendto() function.
SYNTAX:
sent = SockSendTo(socket, data, [, flags] , 'addr.')
PARAMS:
'socket' is the socket number returned by SockSocket().
'data' is the data string to send.
'flags' is any (or none) of the following, separated by a space:
| MSG_DONTROUTE | The data should not be subject to routing. |
| MSG_OOB | Send out-of-band data. |
'addr.' is the name of the stem variable whose tails, "(addr.)FAMILY", "(addr.)PORT", and "(addr.)ADDR" are set to the Address Family, Port number, and dotted IP address of the peer to whom you wish to send the data string.
RETURNS:
'sent' is the number of chars (bytes) actually sent. Could be
0 if an error.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
See notes under SockSend().
To send a broadcast (on a socket of type "SOCK_DGRAM" only), (addr.)ADDR should be set to the special IP address "INADDR_BROADCAST", and (addr.)PORT should be set to the intended port number. It is generally inadvisable for a broadcast datagram to exceed the size at which fragmentation may occur, which implies that the data portion of the datagram (excluding headers) should not exceed 512 bytes.
Sets a particular socket option to a specific value. Calls the sockets library's setsockopt() function.
SYNTAX:
err = SockSetSockOpt(socket, level, optVar, optVal)
PARAMS:
'socket' is the socket number returned by SockSocket().
'level' must be the string "SOL_SOCKET".
'optVar' is the option whose value is to be set. It can be one of the following strings (ie, to set the value of that option):
| SO_ACCEPTCONN | Socket is listening. (Not supported in WIN32). |
| SO_BROADCAST | Allow transmission of broadcast messages on the socket. |
| SO_DEBUG | Record debugging information. |
| SO_DONTROUTE | Don't route: send directly to interface. |
| SO_ERROR | Get error status and clear. |
| SO_KEEPALIVE | Send keepalive messages. |
| SO_LINGER | Linger on close if unsent data is present. |
| SO_OOBINLINE | Receive out-of-band data in the normal data stream. |
| SO_RCVBUF | Specify buffer size for receives. |
| SO_RCVLOWAT | Receive low-water mark. (Not supported in WIN32). |
| SO_REUSEADDR | Allow the socket to be bound to an address that is already in use. (See SockBind()). |
| SO_SNDBUF | Specify buffer size for sends. |
| SO_SNDLOWAT | Send low-water mark. (Not supported in WIN32). |
| SO_SNDTIMEO | Send timeout. (Not supported in WIN32). |
| SO_TYPE | Type of the socket. (NOT supported in WIN32 for setting. Supported by SockGetSockOpt() only). |
| SO_USELOOPBACK | Bypass hardware when possible. (Not supported in WIN32). |
| TCP_NODELAY | Disables the Nagle algorithm for send coalescing. (WIN32 only). |
'optVal' is the new value for the option. This will be a numeric value that turns the option on or off (0 = OFF, or 1 = ON), except for SO_LINGER (whose value must be 2 numbers, separated by a space -- where the first number is "0" or "1" for OFF/ON, and the second number is the timeout amount), SO_RCVBUF (whose value is the desired size of the receive buffer), SO_SNDBUF (whose value is the desired size of the send buffer), and SO_TYPE (whose value is the type of the socket as per SockSocket()), SO_RCVLOWAT and SO_SNDLOWAT, and SO_RCVTIMEO and SO_SNDTIMEO.
RETURNS:
'err' is 0 if success, or -1 if bad parameters or setsockopt() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Shutdowns and cleanups a socket before closing it (via SockClose()). This is used on all types of sockets to disable reception, transmission, or both. Calls the sockets library's shutdown() function.
SYNTAX:
err = SockShutDown(socket, how)
PARAMS:
'socket' is the socket number returned by SockSocket().
'how' is a numeric value that indicates what types of operation will no longer be allowed. It is one of the following:
| 0 | Subsequent receives on the socket will be disallowed. This has no effect on the lower protocol layers. For TCP, the TCP window is not changed, and incoming data will be accepted (but not acknowledged) until the window is exhausted. For UDP, incoming datagrams are accepted and queued. In no case will an ICMP error packet be generated. |
| 1 | Subsequent sends are disallowed. For TCP sockets, a FIN will be sent. |
| 2 | Disables (disallows) both sends and receives as described above. |
RETURNS:
'err' is 0 if success, or -1 if bad parameters or shutdown() fails.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
SockShutDown() does not close the socket, and resources attached to the socket will not be freed until SockClose() is invoked.
SockShutDown() does not block, regardless of the SO_LINGER setting on the socket. A script should not rely on being able to reuse a socket after it has been shut down.
Returns the Berkeley error number of the last sockets library operation, per the OS/2 operating system's sockets library error numbers (since this function library is based upon OS/2's original RXSOCK).
SYNTAX:
number = SockSock_Errno()
RETURNS:
'number' is the Berkeley error number per the OS/2 implementation of
the sockets library.
NOTES:
Currently this does not adjust other operating systems to return
their Berkeley error numbers in accordance to OS/2's sockets library
numbers. (Different OS vendors sometimes add "offsets" to the berkeley
error numbers so that they don't conflict with the error numbers of
other system libraries). It therefore returns an OS-specific number.
This is provided for backward compatibility only. A REXX script should instead reference the REXX variable 'ERRNO' to query a symbolic error name rather than the actual Berkeley error number.
Calls the socket library's socket() function to create a socket (ie, prepare to be able to connect to another computer). This must be done once prior to actually connecting to, and sending data to, and receiving data from, that other computer.
SYNTAX:
socket = SockSocket(domain, type, protocol)
PARAMS:
'domain' must be the string "AF_INET" (ie, RXSOCK supports only
internet domain connections).
'type' is one of the strings: "SOCK_STREAM", "SOCK_DGRAM", or "SOCK_RAW". The first supports bi-directional (full duplex) communication between two partners, The latter two operate connectionless by sending only messages from the "server" (ie, sender) to the "client" (ie, recipient).
'protocol' is one of the strings: "IPPROTO_UDP", "IPPROTO_TCP" (ie, TCP/IP protocol), or "0" if you do not wish to specify a protocol (ie, the sockets library chooses a default protocol for you).
RETURNS:
'socket' is the returned socket number which will be passed to
many of the other RXSOCK functions you call.
NOTES:
The specific error name can be retrieved via 'ERRNO', and the
error message retrieved via SockErrMsg().
Equivalent to SockClose().
Returns the version/revision number of RXSOCK.DLL, for example "1.5".
SYNTAX:
version_revision = RxsockVersion()
RETURNS:
'version_revision' is a string containing the version and revision numbers,
separated by a dot.
Returns the current version of the sockets library that RXSOCK is using (or requires).
SYNTAX:
version = SockVersion()
RETURNS:
'version' is a string containing the version number.
NOTES:
This may not query the actual version number of the underlying sockets
library, but rather, what (minimum) version number RXSOCK requires.