The following are miscellaneous REXXSOCK functions:

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.


SockASyncSelect

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


0 if success, or -1 if an error.

Notes

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

See Also


SockGetHandle


SockGetHandle

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


An RexxSock socket (which can be used with other REXXSOCK functions).


SockGetId

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


The ID number associated with the socket, or an empty string if there is no such socket.


SockGetSockOpt

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


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

Notes

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


SockIoctl

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


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

Notes

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


SockMaxPacketSize

Returns the maximum packet size that can be used with a socket of type "SOCK_DGRAM".

Synopsis

size = SockMaxPacketSize()

Returns


The maximum allowed size for a Datagram written with a single call to SockSend or SockSendTo. If 0, then there is no limit on the size.


SockSetSockOpt

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


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

Notes

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


SockSelect

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


count = SockSelect('reads.', 'writes.', 'excepts.', timeoutsecs, callback)

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


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 sockets 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 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).


SockVersion

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.