Added November 2017
xcall TCPX, opcode, status, buffer, sockidx, flags, timer, hostname, sockary(1)
The optional parameter sockary is used to manage an array of sockets. When it is used, argument 4 (normally sockport) is now interpreted as the index into the sockary, rather than the socket itself. As in the normal case, the TCPOP_ACCEPT calls expects the 4th argument to be the port to listen on.
The sockary() parameter should be an array of up to 1025 ST_SOCKARY structures, defined by fntcpxary.bsi in SOSLIB[907,10] as:
defstruct ST_SOCKARY
map2 socket,b,3 ! socket value
map2 ready,b,1 ! TCPOP_CHECK sets this to 255 if ready
endstruct
The last element of this array must be zero; this is how TCPX identifies the end of the array. In most cases an application would have no need to access this array directly. If you do want to access it directly, you should. Instead, use the utility functions in use the utility functions in fntcpxary.bsi in SOSLIB[907,10] to provide isolation from possible changes in the structure.
The main advantage of using the sockary method is that it by setting the sockidx parameter to 0, TCPX will perform certain operations (mainly TCPOP_CHECK and TCPOP_CLOSE) on the entire set of open sockets in the array, rather than just one socket at a time.
For TCPOP_CHECK, if sockidx is zero, TCPX will wait on all of open sockets until one of them is ready to read from, subject to the time limit set by the timer parameter. If there is a socket ready, it will return sockidx set to the index into the array for that socket, so that a subsequent TCPOP_READ will read from that socket. If multiple sockets are ready to read from, TCPX will use a round-robin scheme so as to not unduly favor those sockets near the start of the array. It will also return the status parameter set to the number of sockets that are ready, allowing the application (optionally) to read from them all by scanning sockary() for those with the ready flag set. This may or may not be preferable to just calling TCPOP_CHECK again and relying on it to return the sockidx of the next ready socket.
For TCPOP_CLOSE, if sockidx is zero, TCPX will close all of the open sockets, and return status set to the number that were closed.
For TCPOP_READ, if sockidx is zero, it will read from whichever socket is available, although this is probably not useful except in very particular cases.
