Sockc stands for socket client. This name is a bit misleading since this application also runs under the QNX 4.x OS which does not use TCP sockets as the IPC method. Note that any mention of QNX in this document refers to the QNX 4.x OS. This GPL application will connect and send/receive data from/to just about any socket or QNX message passing server. The application also uses the socloc APIs to interface to the socloc server. Only the TCP socket version makes use of socloc.
Sockc is a command line text application. All socloc commands and all common socket codes for servers have been implemented by command keywords. Since each server usually defines its own command protocol, no attempt has been made to create sockc command keywords for servers (other than the common socket codes). You can communicate with a server in raw form by sending the server a command string. The sockc application will display the server reply also in raw form.
The sockc application can be used without the socloc interface. Program command line syntax is:
sockc [-s] [-l log_file]
Where the s command line switch will execute the application without initializing the socloc interface. The initial client log file name can be given using the l (el) switch.
Since the QNX 4.x version does not use TCP sockets or socloc, the s command line switch and all commands that refer to socloc do not exist in the QNX version.
When sockc is executed without the s switch, the application will initialize the socloc interface and attempt to connect to a socloc server.
Since the sockc program uses the socloc APIs, you first must create the socloc startup file which should contain a list of suggested socloc servers. The list may be incomplete but at least one entry must describe at least one active socloc server. The socloc startup file must be located in the current directory when you execute the sockc program.
When sockc is executed (without the s command line switch), it will attempt to connect to a socloc server listed in the socloc startup file. Once a proper connection has been established, the current socloc config list will be obtained from the socloc server. This list will be used to replace the socloc config list loaded from the socloc startup file.
The sockc program can maintain two current connections at the same time. One connection is for the socloc server and the other is a connection to another server. When commands are issued they could apply to the socloc server or the other server. Any server you wish to communicate with must already be running and registered with the socloc server. The program works by presenting a status line followed by a command prompt. The user then enters a command followed by enter or return. There are two forms of the status line:
When the socloc interface is enabled, the status line will consist of two parts: the socloc server description and the server description.
sockc:ch,cp/ks,kh,kp
The first part is the socloc server description. This consists of the host name (ch) and TCP port number (cp) of the socloc server you are currently connected to. Each detail of the server is separated by a comma. The first part of the status line is separated from the second part by a forward slash. The second part is the server description. This consists of the service name (ks), host name (kh) and TCP port number (kp). Each detail of the server is also separated by a comma. If there is no current server connection (which is allowed and this is the way that sockc starts up), a question mark will appear in place of the server description. Here are some status line examples:
sockc:node4,7928/?
The above status line indicates that the current socloc server is on host node4 and TCP port 7928. There is no current server connection.
sockc:node4,7928/dumsocks,node4,10001
The above status line indicates that the current socloc server is once again host node4 and TCP port 7928. This time, there is a current server connection to the service dumsocks also on host node4 using TCP port number 10001.
When the socloc interface is disabled, the status line will be displayed like this:
sockc:x/ks,kh,kp
The same two parts are present separated by a forward slash but the first part normally representing the currently connected socloc server is always an x. The second part represents the currently connected server and will be presented the same as when the socloc interface is enabled.
Here is a list of all sockc commands:
The sockc application can be compiled on all stated platforms except DOS where there is no TCP IPC method. Under the Linux/Unix/QNX operating systems, the sockc application can be compiled using the mksockc script.
Here are all of the sockc commands in the order that they are presented in the source module define table:
Syntax : term passwd
Used With : server
IPC : all
Parameters :
Name : passwd
Description: termination password
This command will attempt to send a termination request to the current server. The passwd must exactly match the server termination password (including case). Upon success, this command will cause a server to terminate. In order for this command to function properly, the server must be able to interpret the common socket code SOCKET_SEND_TERM.
Syntax : status Used With : server IPC : all
This command will send a status request to the current server. In order for this command to function properly, the server must be able to interpret the common socket code SOCKET_SEND_STATUS.
Syntax : client.log.off Used With : sockc client IPC : all
This command will turn sockc client logging off. A check will be made to make sure that client logging is not already off.
Syntax : client.log.on [lfname]
Used With : sockc client
IPC : all
Parameters :
Name : lfname
Description: client log destination (file name or sys_log)
This command will turn sockc client logging on. The optional log destination (lfname) can be used to specify a file name for local logging or sys_log for the system log server. If lfname is not present, the default log file (SOCKC_LOG_FILE as defined in sockc.c) will be used. A check will be made to make sure that client logging is not already on. If client logging is on and you wish to change the log file, you must stop the log first by using the client.log.off command.
Syntax : client.log.status Used With : sockc client IPC : all
This command will obtain the current client log status (on or off).
Syntax : server.log.off Used With : server IPC : all
This command will turn logging off on the current server. A check will be made to make sure that server logging is not already off. In order for this command to function properly, the server must be able to interpret the common socket code SOCKET_SEND_LOG_OFF.
Syntax : server.log.on [lfname]
Used With : server
IPC : all
Parameters :
Name : lfname
Description: server log destination
This command will turn server logging on. The optional log destination (lfname) can be used to specify a file name for local logging or sys_log for the system log server (if supported). Remember that the server log file is maintained by the server and must be specified in accordance with the server platform. If lfname is not present, the default log file for that server will be used. A check will be made to make sure that server logging is not already on. If server logging is on and you wish to change the log file, you must stop the log first by using the server.log.off command.
Syntax : server.log.status Used With : server IPC : all
This command will obtain the current server log status (on or off).
TCP Syntax : connect sconnect
QNX Syntax : connect nameloc_name
Used With : server
IPC : all
Parameters :
Name : sconnect
Description: connect string
Name : nameloc_name
Description: service name registered with the QNX nameloc facility
This command will establish a connection to a server overriding any current server connection. When the socloc interface is active, all keywords of the connect string are allowed and the specified server connection will be verified by the socloc server. When the socloc interface is not active, the service keyword in the connect string will not be allowed, both host and port keywords and their respective values must be present and the socket server connection will not be verified (because the socket server might not know how to respond to the common socket send code SOCKET_SEND_STATUS).
Syntax : socloc.list Used With : socloc server IPC : TCP
This command will obtain the current socloc server socket server list. The list will be displayed on the sockc client screen.
Syntax : socloc.config.list Used With : socloc server IPC : TCP
This command will obtain the current socloc server config list. The list will be displayed on the sockc client screen.
Syntax : socloc.get Used With : socloc server IPC : TCP
This command will obtain the current socloc server details including the host name, TCP port number and optionally the IP address. These details are obtained from the main socloc API module.
Syntax : socloc.log.on [lfname]
Used With : socloc server
IPC : TCP
Parameters :
Name : lfname
Description: server log file name
This command will turn socloc server logging on. The optional log file name (lfname) can be used to specify a file name. Remember that the server log file is maintained by the socloc server and must be specified in accordance with the server platform. If lfname is not present, the default log file for that server will be used. A check will be made to make sure that server logging is not already on. If server logging is on and you wish to change the log file, you must stop the log first by using the socloc.log.off command. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_LOG_ON. Note that you may not set the socloc server log to the system log server.
Syntax : socloc.log.off Used With : socloc server IPC : TCP
This command will turn logging off on the current socloc server. A check will be made to make sure that server logging is not already off. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_LOG_OFF.
Syntax : socloc.log.status Used With : socloc server IPC : TCP
This command will obtain the current socloc server log status (on or off). In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_LOG_STATUS.
Syntax : socloc.connect sconnect
Used With : socloc server
IPC : TCP
Parameters :
Name : sconnect
Description: connect string
This command will establish a connection to a socloc server overriding any current socloc server connection.
Syntax : socloc.find sconnect
Used With : socloc server
IPC : TCP
Parameters :
Name : sconnect
Description: connect string
This command will find and display all detail information for the found socket servers based on the sconnect.
Syntax : socloc.service.name Used With : socloc server IPC : TCP
This command will obtain the current socloc server service name. This command is kind of silly since the response will always be socloc. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_SERVICE_NAME.
Syntax : service.name Used With : server IPC : all
This command will obtain the current socket server service name. In order for this command to function properly, the socket server must be able to interpret the common socket code SOCKET_SEND_SERVICE_NAME.
Syntax : socloc.version Used With : socloc server IPC : TCP
This command will obtain the current socloc server version string. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_VERSION.
Syntax : version Used With : server IPC : all
This command will obtain the current server version string. In order for this command to function properly, the server must be able to interpret the common socket code SOCKET_SEND_VERSION.
Syntax : socloc.config.find sconnect
Used With : socloc server
IPC : TCP
Parameters :
Name : sconnect
Description: connect string
This command will find and display all detail information for the found socloc server based on sconnect. Since no more than one socloc server can be run on any one host machine and all TCP port numbers are required to be unique, this command will never return more than one socloc server detail.
Syntax : socloc.status Used With : socloc server IPC : TCP
This command will send a status request to the current socloc server. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_STATUS.
Syntax : socloc.client.list Used With : sockc client IPC : TCP
This command will obtain and display all socloc servers in the sockc local application config link list.
Syntax : socloc.client.update Used With : socloc and sockc client IPC : TCP
This command will obtain the current config link list from the current socloc server and update the sockc client with this new list replacing the old config link list.
Syntax : socloc.client.update.file Used With : socloc and sockc client IPC : TCP
This command will obtain the current config link list from the current socloc server and update the sockc client with this new list replacing the old config link list. The command will then write the new config link list to the socloc startup file replacing the old socloc startup file.
Syntax : send typ [parm]
Used With : server
IPC : all
Parameters :
Name : typ
Description: command type code
Name : parm
Description: command parameter(s)
This command will attempt to send a raw command to the current server. The typ parameter must be a valid command code for the specific server. If the command requires parameters, parm must also be specified. The server reply will also be displayed in raw form.
Syntax : socloc.add service host port[ ip]
Used With : socloc server
IPC : TCP
Parameters :
Name : service
Description: service name
Name : host
Description: machine host name
Name : port
Description: TCP port number
Name : ip
Description: IP address
This command will attempt to add a socket server entry to the current socloc server. The port must be unique. All parameters are required except for ip. The socloc server will not check to see if the socket server being added is responding (this is done when a connection is attempted).
Syntax : socloc.config.add host port[ ip]
Used With : socloc server
IPC : TCP
Parameters :
Name : host
Description: machine host name
Name : port
Description: TCP port number
Name : ip
Description: TCP address
This command will attempt to add a socloc server entry to the current socloc server. The port must be unique and their cannot be more than one socloc server running on a single host. All parameters are required except for ip. The socloc server will not check to see if the socloc server being added is responding (this is done when a socloc connection is attempted).
Syntax : socloc.delete port
Used With : socloc server
IPC : TCP
Parameters :
Name : port
Description: TCP port number
This command will attempt to delete a socket server entry from the current socloc server. All parameters are required. The matching socket server entry must already exist.
Syntax : socloc.config.delete port
Used With : socloc server
IPC : TCP
Parameters :
Name : port
Description: TCP port number
This command will attempt to delete a socloc server entry from the current socloc server. All parameters are required. The matching socloc server entry must already exist.
Syntax : socloc.dump Used With : socloc server IPC : TCP
This command will request that the socloc server display or dump its current socket server list. The list will be displayed on the socloc server console.
Syntax : socloc.config.dump Used With : socloc server IPC : TCP
This command will request that the socloc server display or dump its current socloc server list. The list will be displayed on the socloc server console.
Syntax : socloc.term passwd
Used With : socloc server
IPC : TCP
Parameters :
Name : passwd
Description: termination password
This command will attempt to send a termination request to the current socloc server. The passwd must exactly match the server termination password (including case). Upon success, this command will cause a socloc server to terminate. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_TERM.
Syntax : client.version Used With : sockc client IPC : all
This command will request that the sockc client application identify its version.
Syntax : off Used With : sockc client IPC : all
This command will request that the sockc client application terminate.
Syntax : socloc.on Used With : socloc server IPC : TCP
This command will turn the socloc interface on by calling the sloc_initialize function which will read the socloc startup file, obtain the current configuration list from the socloc server and use this to update the client configuration list. It is an error to use this command when the socloc interface is already active.
Syntax : socloc.off Used With : socloc server IPC : TCP
This command will turn the socloc interface off by calling the function sl_config_delete_all which will delete the entire client configuration list. It is an error to use this command when the socloc interface is already inactive.
Syntax : socloc.trans.num Used With : socloc server IPC : TCP
This command will fetch and display the transaction count of the current socloc server. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_TRANS_NUM.
Syntax : socloc.connect.num Used With : socloc server IPC : TCP
This command will fetch and display the connection count of the current socloc server. In order for this command to function properly, the socloc server must be able to interpret the common socket code SOCKET_SEND_CONNECT_NUM.
Syntax : trans.num Used With : server IPC : all
This command will fetch and display the transaction count of the current server. In order for this command to function properly, the server must be able to interpret the common socket code SOCKET_SEND_TRANS_NUM.
Syntax : connect.num Used With : server IPC : TCP
This command will fetch and display the connection count of the current server. In order for this command to function properly, the server must be able to interpret the common socket code SOCKET_SEND_CONNECT_NUM.