commands.h File Reference

Client application command tree header file. More...

Go to the source code of this file.

Data Structures
struct	Commands
	Application command action-function data structure. More...
Defines
#define	CMD_OK   0
	Command executed OK, return completion status.
#define	CMD_ERR   -1
	Command execution resulted in an error.
#define	CMD_NOOP   1
	Command execution requires no further action (no-op).
Functions
int	cmd_quit (char *, MsgType, char *)
	QUIT command.
int	cmd_ping (char *, MsgType, char *)
	PING command - communication handshaking request.
int	cmd_pong (char *, MsgType, char *)
	PONG command - communication handshaking acknowledgment.
int	cmd_info (char *, MsgType, char *)
	INFO command - report client application runtime information.
int	cmd_version (char *, MsgType, char *)
	VERSION command - report application version and compilation info.
int	cmd_verbose (char *, MsgType, char *)
	VERBOSE command - toggle verbose console output on/off.
int	cmd_debug (char *, MsgType, char *)
	DEBUG command - toggle debugging (super-verbose) console output on/off.
int	cmd_help (char *, MsgType, char *)
	HELP command - print a list of commands on the client console.
int	cmd_history (char *, MsgType, char *)
	HISTORY command - show the application's interactive command history.
int	cmd_status (char *, MsgType, char *)
	STATUS command - report application status.
int	cmd_filter (char *, MsgType, char *)
	FILTER command - set/query the filter position.
int	cmd_home (char *, MsgType, char *)
	HOME command - return the filter wheel to position 1.
int	cmd_send (char *, MsgType, char *)
	SEND command - send a raw command to the IFW.
int	cmd_ports (char *, MsgType, char *)
	PORTS command - report info about open IFW comm ports.
int	cmd_setto (char *, MsgType, char *)
	TIMEOUT command - set/query the IFW communications timeout interval in seconds.
int	cmd_init (char *, MsgType, char *)
	RESET command - reload the runtime config paramters and re-initialize the IFW.
Variables
Commands	cmdtab []
	Application command action-function data structure.
int	NumCommands = sizeof(cmdtab)/sizeof(struct Commands)
	number of commands defined

---

Detailed Description

Client application command tree header file.

To add a command, you need to

1. Add a command action function prototype to the code below
2. Add the command verb and its function call to the cmdtab struct

See commands.c for the full implementation details.

---

Define Documentation

#define CMD_OK   0

Command executed OK, return completion status.

#define CMD_ERR   -1

Command execution resulted in an error.

#define CMD_NOOP   1

Command execution requires no further action (no-op).

---

Function Documentation

int cmd_quit (  char *  args, MsgType  msgtype, char *  reply )

QUIT command. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK if command executed without errors, CMD_ERR if an error occurred. On errors reply contains the error message. Executes the application QUIT command. Only works if msgtype=EXEC, indicating that it is an IMPv2 executive command. This prevents remote applications from prematurely terminating this application by sending a QUIT command unqualified by the EXEC: directive.

int cmd_ping (  char *  args, MsgType  msgtype, char *  reply )

PING command - communication handshaking request. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK if command executed without errors, CMD_ERR if an error occurred. On errors reply contains the error message. This function is invoked when the client application receives a PING from a remote host requesting a communications handshaking reply. PINGs are actually handled separately in the SocketCommand() handler (nothing is done by the KeyboardCommand() handler) because the PONG sent back acknowledging the comm handshaking request is, in effect, a pseudo-command (implicit REQ:), not a "DONE:" response to a command request. This exception to the general messaging syntax has to be handled carefully to prevent problems, especially to ensure backwards compatibility with older IMPv applications. See also: cmd_pong

int cmd_pong (  char *  args, MsgType  msgtype, char *  reply )

PONG command - communication handshaking acknowledgment. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_NOOP since PONG is a no-op pseudo command. For historical reasons, a "PONG" sent in acknowledgment of a software handshaking "PING" looks like an implicit REQ:, and hence like a "command request" sent to the recipient, even though it isn't. It is, however, an exception to the strict messaging protocol, which is why it needs a separate handler. cmd_pong doesn't do anything except return a CMD_NOOP (since this "command" must NOT result in a reply back to the sender). In more sophisticated apps, we might actually use receipt of a pong to do something useful (e.g., help build up a node table), so at the very least this module works as a placeholder for future expansion. See also: cmd_ping

int cmd_info (  char *  args, MsgType  msgtype, char *  reply )

INFO command - report client application runtime information. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on successful creation of the info report, CMD_ERR if errors encountered. cmd_info creates a summary report of the current client application's runtime configuration as an IMPv2-compliant message string in which the runtime parameters are reported as keyword=value pairs. The format of cmd_info should be tailored specifically for the particular client application. If a client controls specific instrument or interface functions, the state of those functions should be reported in the info string, making it an omnibus "what is your status" command.

int cmd_version (  char *  args, MsgType  msgtype, char *  reply )

VERSION command - report application version and compilation info. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK Loads an IMPv2 message into the reply string with the version number and any relevant compilation information (e.g., date and time of compilation). VERSION allows a way for users or remote apps to verify the runtime version of the current application.

int cmd_verbose (  char *  args, MsgType  msgtype, char *  reply )

VERBOSE command - toggle verbose console output on/off. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK Sets the client isVerbose flag to 1 (enabled) if currently 0 (disabled) and vis-versa. Verbose output mode is used for basic client debugging information by printing extra information on the application console screen. Disabling throttles verbose console output. VERBOSE mode is normally disabled during normal operations. In general "Verbose" output refers only to client application level output (i.e., echoing socket message traffic, printing status update info, etc.). An more chatty DEBUG mode is provided that prints more engineering-level info for detailed low-level system debugging. See also: cmd_debug

int cmd_debug (  char *  args, MsgType  msgtype, char *  reply )

DEBUG command - toggle debugging (super-verbose) console output on/off. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK Sets the client Debug flag to 1 (enabled) if currently 0 (disabled) and vis-versa. May also set mechanism-level debug flags as well. DEBUG mode is a super-verbose mode that spews lots of I/O chatter onto the application console, useful during client debugging or for troubleshooting. For example, in client applications that control stepper motors, the full motor control chatter is echoed to the console during DEBUG mode to enable the user to follow the steps the system is (or is not) taking, watch encoder and limit switches assert (or not), etc. DEBUG is normally disabled during normal user operations. See also: cmd_verbose

int cmd_help (  char *  args, MsgType  msgtype, char *  reply )

HELP command - print a list of commands on the client console. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_NOOP on success, CMD_ERR if help executed as a non-EXEC: command Usage: help <cmd> cmd_help is usually invoked by the HELP or ? commands. It prints a list of all interactive commands on the client application's console screen. It is only meant to be executed as an EXEC: message type. If the command is not qualifed as EXEC:, it returns an error. If an argument is given, it tries to find that string in the command list, and if successful, prints a brief description and usage message. Help is meant to be simple. It can give help on particular commands (really a reminder of the command's function and syntax), or a list of all commands.

int cmd_history (  char *  args, MsgType  msgtype, char *  reply )

HISTORY command - show the application's interactive command history. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_NOOP on success, CMD_ERR if history executed as a non-EXEC: command Report the application's interactive command history on the console. The KeyboardCommand() function uses the GNU readline and history system to record all commands entered. This prints a list of the most recent commands. See also: KeyboardCommand()

int cmd_status (  char *  args, MsgType  msgtype, char *  reply )

STATUS command - report application status. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Queries the IFW for its current state and returns an IMPv2-conformal status message. This is a placeholder for future expansion.

int cmd_filter (  char *  args, MsgType  msgtype, char *  reply )

FILTER command - set/query the filter position. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Move the named filter into the beam, or query for the filter currently in the beam if FILTER is given without command arguments.

int cmd_home (  char *  args, MsgType  msgtype, char *  reply )

HOME command - return the filter wheel to position 1. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Move the filter wheel to the home position. Postition 1 is the hardware zero-reference position for the filter wheel.

int cmd_send (  char *  args, MsgType  msgtype, char *  reply )

SEND command - send a raw command to the IFW. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Sends a raw command to the IFW and waits for a reply. The IFW always tries to send something back.

int cmd_ports (  char *  args, MsgType  msgtype, char *  reply )

PORTS command - report info about open IFW comm ports. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Report information about the IFW comm ports connected to the client in IMPv2-compliant format. Shows their status as follows: IFWPort=/dev/ttyS0 Open IFWTimeout=10

int cmd_setto (  char *  args, MsgType  msgtype, char *  reply )

TIMEOUT command - set/query the IFW communications timeout interval in seconds. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Implements the TIMEOUT command to set/query the IFW communications timeout, overriding any value given by the TIMEOUT keyword in the runtime configuration file for the duration of the client session. When the client is quit and restarted (or warm restarted via the RESET command), the default timeout given in the runtime configuration file will be restored. If TIMEOUT was given without arguments, it returns the current communications timeout interval as an IMPv2-compliant keyword=value pair. If a number is given on the command line (e.g., TIMEOUT 5) it validates the number (converts to an integer) and sets the communications timeout (ifw.timeout member), returning the new timeout value as an IMPv2-compliant keyword=value pair. If an invalid timeout interval is given, it returns an error message. The communications timeout interval should be long enough to allow the IFW to complete the longest move. For the IFW, the manual says that this is the WHOME command, which can take up to 20 seconds to complete. Setting a shorter comm timeout could result in false timeout errors. Setting it to 0, while formally allowed, is just a bad idea.

int cmd_init (  char *  args, MsgType  msgtype, char *  reply )

RESET command - reload the runtime config paramters and re-initialize the IFW. Parameters: args  string with the command-line arguments msgtype  message type if the command was sent as an IMPv2 message reply  string to contain the command return reply Returns: CMD_OK on success, CMD_ERR if errors occurred, reply contains an error message. Calls loadconfig() to re-read the runtime config file, restoring all initial client parameters, then re-opens the serial port (if any - better be). Once the comm port to the IFW is open it executes IFWInit() to put the IFW into its serial communications loop. This provides the ifwtool application with a warm restart facility.

---

Variable Documentation

struct Commands cmdtab[]

Application command action-function data structure.

int NumCommands = sizeof(cmdtab)/sizeof(struct Commands)

number of commands defined

---