# Sockary

> [HTML Version](sockary.htm)

_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\]](https://bitbucket.org/microsabio/soslib/src/master/907010/fntcpxary.bsi) 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\]](https://bitbucket.org/microsabio/soslib/src/master/907010/fntcpxary.bsi) 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.