This socloc API module is used by the socloc server to communicate with other socloc servers and other socket servers. This API has the file name slocsrv.c. Note that there is no DOS or QNX version of this API. Any mention of QNX in this documentation refers to the QNX 4.x OS.

Unlike our other socket API's, this one does not connect and then leave the socket open. The socloc server can communicate with any number of other socloc servers and socket servers so this API is one-shot based. The socket is opened, the request is sent, the reply received and then the socket is closed. The only possible consequence of this behavior (that I have seen) is that the socket descriptor pool can become exhausted after few million requests in some Unix's.

Here is a list of functions in this module:

Public Functions

• sloc_custom_status
• sloc_get_list
• sloc_config_get_list
• sloc_bcast_add
• sloc_bcast_delete
• sloc_bcast_config_add
• sloc_bcast_config_delete
• sloc_get_active_socloc
• sloc_find_first_active
• sloc_is_init

Private Functions

• sloc_ll_status
• sloc_sr_code
• sloc_sr_char
• sloc_client_connect

Module Global Data

This socloc API contains the following global data:

#ifdef OS_WIN32
SOCKET slclientSocket;        // client socket
SOCKADDR_IN slsockClientAddr; // client address structure
LPHOSTENT lpHostEnt;          // host info structure
#endif

#ifdef OS_UNIX
int slclientSocket;
struct sockaddr_in slsockClientAddr;
struct hostent *lpHostEnt;
#endif

char sloc_hostname[128];      // host name of 'socloc' server
int sloc_port = 0;            // port 'socloc' is using

The current socloc server details are stored in sloc_hostname and sloc_port. These connection specs are trusted. No failover protection is given by this API.

Note that the link list of socloc servers (the config list) is actually stored in the socloc API configuration module.

Module Dependencies

This module is part of the socloc API and needs to be linked with the following modules:

• fio.c
• parse.c
• logger.c
• ipcomm.c
• slconfig.c
• sliocode.c
• sconnect.c

In the Linux and Unix platform, this module is compiled along with the other socloc modules as part of the script csocloc. The socloc server uses this API and it is compiled using the mksocloc script.

Module Header Files

This module depends on the following header files:

• stdhead.h
• flsocket.h
• ipcomm.h
• sloc.h
• socloc.h
• slconfig.h
• sconnect.h
• sliocode.h

Module Functions

sloc_custom_status

Prototype   : int sloc_custom_status(char *hname, int port)
Parameters  :
      Name  : hname
Description : host name

      Name  : port
Description : TCP port number

Returns     : socloc code

This function will attempt to get the status of a socket or a socloc server. All parameters are required. The destination server is required to be able to interpret the common socket send code SOCKET_SEND_STATUS as defined in flsocket.h.

sloc_get_list

Prototype   : int sloc_get_list(char *list_out)
Parameters  :
      Name  : list_out
Description : returned
server list

Returns     : socloc code

This function will attempt to get the details of all socket servers known to socloc. The returned list uses SL_LIST_DELIM (as defined in socloc.h) to delimit each server entry. Each returned entry is in the following format:

   sname hname port [ip]

Any returned value that contains spaces will be quoted. The IP address will only be present if it was registered with the socloc server.

sloc_config_get_list

Prototype   : int sloc_config_get_list(char *list_out)
Parameters  :
      Name  : list_out
Description : returned socloc server list

Returns     : socloc code

This function will attempt to get the details of all socloc servers known. The returned list uses SL_LIST_DELIM (as defined in socloc.h) to delimit each server entry. Each returned entry is in the following format:

   hname port [ip]

Any returned value that contains spaces will be quoted. The IP address will only be present if it was registered with the socloc server.

sloc_bcast_add

Prototype   : int sloc_bcast_add(char *sn, char *hn, int port, char *ip)
Parameters  :
      Name  : sn
Description : service name

      Name  : hn
Description : host name

      Name  : port
Description : TCP port number

      Name  : ip
Description : IP address

Returns     : socloc code

This function will attempt broadcast a socket server add command to all known socloc servers. The function works by obtaining the details of each entry in the config list and sending a socket server add command to it. All parameters except ip are expected to be not null and contain a non-zero length string or positive integer. This function is used by socloc servers to broadcast changes and should not be called by client applications.

sloc_bcast_delete

Prototype   : int sloc_bcast_delete(int port)
Parameters  :
      Name  : port
Description : TCP port number

Returns     : socloc code

This function will attempt broadcast a socket server delete command to all known socloc servers. The function works by obtaining the details of each entry in the config list and sending a socket server delete command to it. Port is required to be a positive integer.

sloc_bcast_config_add

Prototype   : int sloc_bcast_config_add(char *hn, int port, char *ip)
Parameters  :
      Name  : hn
Description : host name

      Name  : port
Description : TCP port number

      Name  : ip
Description : IP address

Returns     : socloc code

This function will attempt broadcast a socloc server add command to all known socloc servers. The function works by obtaining the details of each entry in the config list and sending a socloc server add command to it. All parameters except ip are expected to be not null and contain a non-zero length string or positive integer.

sloc_bcast_config_delete

Prototype   : int sloc_bcast_config_delete(int port)
Parameters  :
      Name  : port
Description : TCP port number

Returns     : socloc code

This function will attempt broadcast a socloc server delete command to all known socloc servers. The function works by obtaining the details of each entry in the config list and sending a socloc server delete command to it. Port is required to be a positive integer.

sloc_get_active_socloc

Prototype   : void sloc_get_active_socloc(char *hname, int *port)
Parameters  :
      Name  : hname
Description : returned host name

      Name  : port
Description : returned TCP port number

This function will retrieve the host name (hname) and TCP port number (port) of the current socloc server. Both parameter pointers must not be null and the host name must already be allocated to sufficient size for the returned host name.

sloc_find_first_active

Prototype   : int sloc_find_first_active(void)

Returns     : socloc code

This function will traverse the socloc config link list from the top in an attempt to find the first responding socloc server. If an entry in the config list is found to be not responding, it will be deleted from the list and this deletion will be broadcasted to all known socloc servers. The first responding socloc server will become the current active socloc server.

sloc_is_init

Prototype   : int sloc_is_init(void)

Returns     : socloc code

This function will determine whether this API has been initialized. The API is considered initialized when there is an active host name in sloc_hostname and a positive port number in sloc_port. Function returns SL_OK if the API has been initialized, SL_NO_INIT otherwise.

sloc_ll_status

Prototype   : static int sloc_ll_status(void)

Returns     : socloc code

This private function will attempt to get the status of the socloc server. If the server is operational, the typical response is SL_OK as defined in socloc.h.

sloc_sr_code

Prototype   : static int sloc_sr_code(int typ, char *parm)
Parameters  :
      Name  : typ
Description : send command code

      Name  : parm
Description : command parameter(s)

Returns     : socloc code

This private function will attempt to send a request to the current active server that will return no other value except the socloc code. The parameter typ is required to be a valid send command code, parm may be a null pointer or an empty string if there are no command parameters.

sloc_sr_char

Prototype   : static int sloc_sr_char(int typ, char *parm, char *sval)
Parameters  :
      Name  : typ
Description : send command code

      Name  : parm
Description : command parameter(s)

      Name  : sval
Description : returned string value

Returns     : socloc code

This private function will attempt to send a request to the current active server that will return a string in addition to the socloc code. The parameter typ is required to be a valid send command code, parm may be a null pointer or an empty string if there are no command parameters. The returned string value must already be allocated to sufficient size by the caller. An active server must be found on entry.

sloc_client_connect

Prototype   : static int sloc_client_connect(void)

Returns     : socloc code

This private function attempt to connect to the current active server.

sloc_ll_client_connect

Prototype   : int sloc_ll_client_connect(void)

Returns     : socloc code

This private function will attempt to connect to the current active socloc server by opening a socket to the server. This function will not attempt a failover if the connection attempt fails.