SockASyncSelect | Determines which messages are passed to your window for activity upon a given socket. |
SockGetHandle | Gets an RexxSock socket for a berkeley library socket. |
SockGetId | Gets an ID number associated with a socket. Also enumerates all of the currently connected sockets. |
SockGetSockOpt | Gets the current value of a particular option of a socket. |
SockIoctl | Controls the mode of a socket, or gets some information about a socket. |
SockMaxPacketSize | Returns the maximum packet size that can be used with a socket of type "SOCK_DGRAM". |
SockSetSockOpt | Sets a particular socket option to a specific value. |
SockSelect | Determines the status of one or more sockets, waiting if necessary. |
SockVersion | Gets the version of the sockets library that REXXSOCK requires. Also returns the version of REXXSOCK. |
Determines which messages are passed to your window for activity upon a given socket.
This is supported only under the Windows operating system.
Synopsis
err = SockASyncSelect(socket, window, message, activities)
Args
socket is the socket returned by SockSocket or SockAccept.
window is the handle to some window that your script has created.
message is the message number you wish to be sent when any activity happens upon this socket.
activities are the events for which you wish a message sent for this socket. It must be a string containing any or all of the following, each separated by a space:
READ | You want to receive notification when you can SockRecv or SockRecvFrom without blocking. |
WRITE | You want to receive notification when you can SockSend or SockSendTo without blocking. |
CONNECT | You want to receive notification when you SockConnect has succeeded upon a non-blocking socket. |
CLOSE | You want to receive notification when the socket is closed. |
OOB | You want to receive notification of the arrival of out-of-band data. |
ACCEPT | You want to receive notification when a new client is attempting to connect to your server socket, and you should call SockAccept. |
Returns
Notes
The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.
See Also
Gets an RexxSock socket for a berkeley library socket.
This is mostly intended to be used with messages that your window receives as a result of SockASyncSelect.
Synopsis
rxsockSocket = SockGetHandle(BerkeleySocket)
Args
BerkeleySocket is the socket returned by some berkeley library function or a message passed to your window via SockASyncSelect.
Returns
Gets an ID number associated with a socket (when the socket is gotten from SockSocket, SockConnect, or SockAccept). Also enumerates all of the currently connected sockets.
Synopsis
id = SockGetId(rxsock, enumerate, startId)
Args
enumerate is which socket's ID you wish retrieved where 1 is the first socket, 2 is the second socket, etc.
startId indicates the lowest ID retrieved. Any socket with a lower ID will not be enumerated. (This is mostly used to skip enumerating server sockets, which typically will be created before client sockets, and therefore have lower ID numbers than client sockets).
rxsock is the name of the REXX variable where SockGetId will return the REXXSOCK socket associated with the returned ID. If omitted, then SockGetId returns only the ID. If enumerate and startId are omitted, then rxSock is instead the REXXSOCK socket for which the ID is returned.
Returns
Gets the current value of a particular option of a socket.
Calls the sockets library's getsockopt() function.
Synopsis
err = SockGetSockOpt(socket, level, optVar, 'optVal')
Args
socket is the socket returned by SockSocket or SockAccept.
level must be the string "SOL_SOCKET". If omitted, defaults to "SQL_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
Notes
The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.
Controls the mode of a socket, or gets some information about 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, regardless of the protocol.
Calls the sockets library's ioctlsocket() function.
Synopsis
err = SockIoctl(socket, ioctlCmd, ioctlData)
Args
socket is the socket returned by SockSocket or SockAccept.
ioctlCmd is one of the following strings:
FIONBIO | Enable or disable blocking mode on the socket. You must pass a 1 for ioctlData if you desire nonblocking mode, or a 0 if you wish blocking mode. When a socket is created, it operates in blocking mode. |
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 is used only with a socket of type SOCK_STREAM whose SO_OOBINLINE option is enabled (ie, the socket has been configured for in-line reception of any out-of-band data). ioctlData is the name of a REXX variable where SockIoctl returns information. 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). |
If omitted, ioctlCmd defaults to "FIONREAD".
Returns
Notes
The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.
Returns the maximum packet size that can be used with a socket of type "SOCK_DGRAM".
Synopsis
size = SockMaxPacketSize()
Returns
Sets a particular socket option to a specific value.
Calls the sockets library's setsockopt() function.
Synopsis
err = SockSetSockOpt(socket, level, optVar, optVal)
Args
socket is the socket returned by SockSocket or SockAccept.
level must be the string "SOL_SOCKET". If omitted, defaults to "SQL_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, SO_RCVTIMEO and SO_SNDTIMEO, and SO_ERROR (whose value is either a number or one of the Symbolic error names for ErrNo).
Returns
Notes
The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.
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.
Synopsis
Args
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 sockets. reads.1 contains the first socket. reads.2 contains the second socket. Etc. If a socket is currently listening (ie, that socket 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 (via 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 sockets. writes.1 contains the first socket. writes..2 contains the second socket. 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 sockets. excepts.1 contains the first socket. excepts..2 contains the second socket. 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. tail pertaining to that socket.
timeoutsecs is the timeout period (in seconds) to wait for the check to complete before aborting. If omitted, then SockSelect will not return until one of the sockets you supplied meets the required condition.
callback is the name of a subroutine in your script that SockSelect calls in lieu of using the reads., writes., and excepts. variables. (ie, You can omit those variables if supplying a callback).
Returns
Notes
The specific error name can be retrieved via ErrNo, and any error message retrieved via SockErrMsg.
reads., writes., and/or excepts. may be omitted, or set to empty string (ie, ""), if there are no sockets to be checked for readability, writeability, or errors/out of band data, respectively, or if you pass the callback arg.
The maximum number of reads., writes., or excepts. sockets you can specify is 64 for each. (ie, Upto 64 sockets can be checked for readability, 64 for writeability, and 64 for errors/out of band data). If you specify too many sockets to check, this raises a SYNTAX condition. (If using the callback feature, it instead sets ERRNO to "EMFILE" and returns -1).
Returns the current version of the sockets library that REXXSOCK is using (or requires).
Synopsis
version_revision = SockVersion()
Returns
A string containing the version and revision numbers, separated by a dot, for example "1.0".
Notes
This may not query the actual version number of the underlying sockets library, but rather, what (minimum) version number REXXSOCK requires.