sockc GPL Application

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:

# Status Line When Socloc is Enabled

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.

# Status Line When Socloc is Disabled

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:

- term
- status
- client.log.off
- client.log.on
- client.log.status
- server.log.off
- server.log.on
- server.log.status
- connect
- socloc.list
- socloc.config.list
- socloc.get
- socloc.log.on
- socloc.log.off
- socloc.log.status
- socloc.connect
- socloc.find
- socloc.service.name
- service.name
- socloc.version
- version
- socloc.config.find
- socloc.status
- socloc.client.list
- socloc.client.update
- socloc.client.update.file
- send
- socloc.add
- socloc.config.add
- socloc.delete
- socloc.config.delete
- socloc.dump
- socloc.config.dump
- socloc.term
- client.version
- socloc.on
- socloc.off
- socloc.trans.num
- socloc.connect.num
- trans.num
- connect.num
- off

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.

# Sockc Commands

Here are all of the sockc commands in the order that they are presented in the source module define table:

## term

    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.

## status

    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.

## client.log.off

    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.

## client.log.on

    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.

## client.log.status

    Syntax     : client.log.status
    Used With  : sockc client
    IPC        : all

This command will obtain the current client log status (on or off).

## server.log.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.

## server.log.on

    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.

## server.log.status

    Syntax     : server.log.status
    Used With  : server
    IPC        : all

This command will obtain the current server log status (on or off).

## connect

    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).

## socloc.list

    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.

## socloc.config.list

    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.

## socloc.get

    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.

## socloc.log.on

    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.

## socloc.log.off

    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.

## socloc.log.status

    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.

## socloc.connect

    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.

## socloc.find

    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.

## socloc.service.name

    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.

## 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.

## socloc.version

    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.

## 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.

## socloc.config.find

    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.

## socloc.status

    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.

## socloc.client.list

    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.

## socloc.client.update

    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.

## socloc.client.update.file

    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.

## send

    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.

## socloc.add

    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).

## socloc.config.add

    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).

## socloc.delete

    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.

## socloc.config.delete

    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.

## socloc.dump

    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.

## socloc.config.dump

    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.

## socloc.term

    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.

## client.version

    Syntax     : client.version
    Used With  : sockc client
    IPC        : all

This command will request that the sockc client application identify its version.

## off

    Syntax     : off
    Used With  : sockc client
    IPC        : all

This command will request that the sockc client application terminate.

## socloc.on

    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.

## socloc.off

    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.

## socloc.trans.num

    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.

## socloc.connect.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.

## trans.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.

## connect.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.

Goto Top | Future Lab Home | Contact Webmaster | Feedback

Copyright © 2000-2006 Future Lab, Last Updated Jun 25, 2006