Socloc stands for socket locate. Socloc provides a method of storing the information on all existing socket servers within an environment. Client applications can then look up this information using the socloc API.
Typically, when a client application wishes to connect to a socket server, the client application must know the TCP port number and either the host name or the IP address. When socloc is in use, the client application does not need to know this information as it can be obtained from the socloc server. Not having to know these details gives an enormous amount of freedom. Server applications may be moved around from machine to machine and the TCP port used may also easily be changed.
Multiple servers providing the same service can also be used just in case one or more servers fail.
There are two major components to socloc, the server and the API.
The socloc server is a TCP connection oriented iterative server that stores information about other socket servers in the environment. This server also responds to specific command requests for additions, deletions, and lookups. The socloc API is used by client applications.
The socloc server accepts requests in string form. Here is the basic syntax of a server request string:
send_command_code[ parms]
Each socloc request starts with a send command code. These codes are defined in socloc.h. After the command code, one or more parameters may present depending on the specific send command code. Each parameter is separated by one space. Any parameter containing spaces must be quoted.
A software developer using socloc does not really have to concern themselves with this level of detail as the socloc API handles all the details between client and server automatically.
Socloc uses the notion of a service name when storing information about socket servers. Multiple socket servers can be running on different hosts with the same service name. All port numbers are required to be unique across all socloc and socket servers.
On one or more machines, the socloc server is run. Many socloc servers may be running in an environment but only one socloc server may be running on any single host machine.
The result of using socloc is:
The socloc API is used by client applications (including other socket servers). The applications have different responsibilities.
Socket server applications are required to:
Socket client applications are required to:
A socloc server also is required to have a socloc startup file which must contain the host name, TCP port number and (optionally) the IP address of the socloc server.
Socloc servers maintain a common list between themselves. All additions and deletions are communicated to all known socloc servers using the server communications API.
There are two link lists that are used to maintain socloc information. The first list is the list of all known socket servers. This list is maintained by the socloc server. Each socloc server has a copy of this list. This list is synchronized by socloc servers communicating between themselves. The second list is the list of socloc servers. This list is stored in the configuration module of the socloc API. There is a copy of this list for each client application and socloc server. Throughout the socloc documentation, you will see this list referred to as the configuration list or config list.
When a socloc or socket server is added or deleted from either link list, the server communications API places an extra parameter right after the send command code. This parameter is a flag (either zero or one) indicating the origin of the request. When a addition or deletion is initiated by a client application, the flag will be one (1). When a socloc server receives the request and the flag is one, the socloc server will broadcast the addition or deletion to all other socloc servers by using the same command string but changing the flag from one to zero (0). This zero indicates that another socloc server has sent the request and not to broadcast this request.
A socloc client application can determine the details (host name, TCP port number and optionally the IP address) of a specific socket or socloc server by using one of the find functions in the main socloc API module. A socket server may be found by any or all of the service name, host name, port number or IP address. A socloc server may be found by the host name TCP port number or the IP address. The socloc server will attempt to verify the matched server by requesting the server status. If the server does not respond to the status request, the socloc server will delete the socket server entry and broadcast this deletion to all known socloc servers.
In addition to finding a single server entry, you may also find a list of entries by any criteria. For example, you may wish to find all socket servers with a specific service name or locate all socket servers that are running on a specific host machine.
When using the find list, get list or put list commands, the socloc server will return a list of matching socket server entries. Each element in the list is delimited by SL_LIST_DELIM as defined in socloc.h. The format of each socket server list entry is as follows:
sname hname port ip
Each parameter is separated by a space. A parameter that contains spaces will be quoted (using single quotes). The format of a socloc server entry is the same except there is no service name (sname).
The socloc server allows flexible finding by using a connect string. The general form of the connect string for socket servers is:
[service sname][ host hname][ port pnum][ ip ipad]
The connect string uses a parameter pair. The first word in each pair is the command word. The command word is one of service, host, port or ip. The second word is the value. Any value that contains spaces must be quoted. Each parameter is separated by at least one space.
The socloc find connect string is basically the same except there is no service name.
The main socloc API module takes the input parameters and builds a connect string which is sent to the socloc server. The server then parses this connect string and performs the find. The socloc API module sconnect.c provides the functions to build and parse a connect string.
Upon initialization of the socloc API, a startup file is read. The name of this file is socloc.ipc and it must reside in the current directory. This file describes or suggests a list of socloc servers. The format of this file is:
* comment line host_name port_num [ip]
A comment line starts with an asterisk in column one. A socloc server description line starts with the host name and adds the port that this socloc server listens to. This is followed by an optional IP address. One socloc server entry is expect per line.
A socket client and server uses the socloc startup file in the same way. When the client or server starts up, the startup file is read and an attempt to contact one of the listed socloc servers is made (in the order specified in the startup file). At least one socloc server on the list must respond or a fatal error will occur.
A socloc server uses the startup file in a different manner. When a socloc server starts up, the startup file is read and a search is made for a single entry matching the host name of the running machine. Upon a match, the TCP port number and IP address of the entry is used to identify the socloc server. The socloc server will fail to start if there is no entry in the startup file matching the host name of the machine involved.
Since all port numbers are required to be unique, a socloc server will fail to start if the port if found to already be in use. When a socket server registers itself, a fatal error will occur if the TCP port that it plans to use is already in use according to socloc.
Since the startup file is used only for suggestion purposes, it is recommended that a socket server and a socket client application retrieve the current list of all known socloc servers as soon as this communication is possible.