Main Page | Data Structures | File List | Data Fields | Globals

commands.c File Reference

ISIS client application command interpreter functions. More...

#include "isisclient.h"
#include "client.h"
#include "commands.h"
#include "msutils.h"
#include <readline/readline.h>
#include <readline/history.h>

Functions

int cmd_quit (char *args, MsgType msgtype, char *reply)
 QUIT command.

int cmd_ping (char *args, MsgType msgtype, char *reply)
 PING command - communication handshaking request.

int cmd_pong (char *args, MsgType msgtype, char *reply)
 PONG command - communication handshaking acknowledgment.

int cmd_version (char *args, MsgType msgtype, char *reply)
 VERSION command - report application version and compilation info.

int cmd_verbose (char *args, MsgType msgtype, char *reply)
 VERBOSE command - toggle verbose console output on/off.

int cmd_debug (char *args, MsgType msgtype, char *reply)
 DEBUG command - toggle debugging (super-verbose) console output on/off.

int cmd_info (char *args, MsgType msgtype, char *reply)
 INFO command - report client application runtime information.

int cmd_help (char *args, MsgType msgtype, char *reply)
 HELP command - print a list of commands on the client console.

int cmd_history (char *args, MsgType msgtype, char *reply)
 HISTORY command - show the application's interactive command history.

int cmd_ports (char *args, MsgType msgtype, char *reply)
 PORTS command - report info about open barcode reader comm ports.

int cmd_status (char *args, MsgType msgtype, char *reply)
 STATUS command - report client status.

int cmd_send (char *args, MsgType msgtype, char *reply)
 SEND command - send a raw command to the barcode reader.

int cmd_query (char *args, MsgType msgtype, char *reply)
 QUERY command - send a raw device query to the barcode reader.

int cmd_read (char *args, MsgType msgtype, char *reply)
 READ command - read a barcode label.

int cmd_setto (char *args, MsgType msgtype, char *reply)
 TIMEOUT command - set/query the barcode reader communications timeout interval in seconds.

int cmd_reset (char *args, MsgType msgtype, char *reply)
 RESET command - reload the runtime config paramters and re-initialize the barcode reader.

void KeyboardCommand (char *line)
 Process a command from the client's console keyboard.

void SocketCommand (char *buf)
 Process a message/command from the client UDP socket.


Detailed Description

ISIS client application command interpreter functions.

This module contains the command "action" functions called to service specific client application commands. These consist of a suite of

The common client commands include the following:

These 3 commands are REQUIRED of all ISIS client apps:

These client commands are recommended for most apps: These are common commands relevant for the CLI, but generally not available to remote ISIS nodes (e.g., they test that the message type is EXEC:): These are then followed by cmd_xxx() action functions that implement the various client tasks.

At the end of this file are the template I/O handlers used by the command interpreter:

Author:
R. Pogge, OSU Astronomy Dept., pogge@astronomy.ohio-state.edu

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

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_ports char *  args,
MsgType  msgtype,
char *  reply
 

PORTS command - report info about open barcode reader 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 barcode reader comm ports connected to the client in IMPv2-compliant format. Shows their status as follows:
BCPort=/dev/ttyS0 Open BCTimeout=10

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

STATUS command - report client 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 various barcode readers for its current state and returns an IMPv2-conformal status message. This is a placeholder for future expansion.

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

SEND command - send a raw command to the barcode reader.

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 barcode reader. Raw commands generate no reply unless they are queries, so it sends the command and returns to the command prompt without waiting for a reply. To send a command that produces a reply from the controller, you need to send a "query" command (cmd_query()).

Raw means RAW: the user must type <> delimiters.

See also:
cmd_read(), cmd_query()

int cmd_query char *  args,
MsgType  msgtype,
char *  reply
 

QUERY command - send a raw device query to the barcode reader.

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 (Microscan "\<xxx?\>" syntax) generate a near-immediate reply from the barcode reader. The exception is an "\<X\>" command, which is what we use to command the reader to scan a barcode (supposedly) in its beam.

This routine sends a raw query and waits for a reply or timeout (e.g., if controller not there). The comm timeout is set by the mask.timeout member in global barcode struct.

To send a command that produces no reply from the controller, use the "send" command, cmd_send().

To read a barcode in the reader's beam, use the "read" command, cmd_read()

See also:
cmd_read(), cmd_send()

int cmd_read char *  args,
MsgType  msgtype,
char *  reply
 

READ command - read a barcode label.

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 the <X> command to the barcode scanner to tell it to read the barcode label supposedly in its beam. The barcode reader is configured to turn on its LEDs/laser and scan for a specified time. It either returns immediately with the decoded label text, or if its internal timeout expires returns "NOREAD" to indicate that it could not decode the barcode label (or that no label was in the beam).

As a failsafe, the cmd_read function waits for a specified communications timeout interval (defined by the mask.timeout member), so that we don't wait forever for a reply from a barcode scanner that is malfunctioning or just turned off.

On success, the reply string contains the text of the barcode label in IMPv2-compliant format as a keyword=value pair, the keyword text taken from the mask.Name string. For example, if mask.Name="MaskID", and the barcode label is read successfully as "MODS1-040231-Abell2203b" it will return

MaskID=(MODS1-040231-Abell2203b)
to be passed back to the calling process (either echoed on the command console if a keyboard "READ" command, or back to the calling remote client if received as an "REQ: READ" command request).

Raw reads, without IMPv2 reply formatting, can be accomplished by sending the "query \<X\>" command.

See also:
cmd_send(), cmd_query()

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

TIMEOUT command - set/query the barcode reader 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 barcode reader 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 (mask.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 at least as long as the barcode reader's internal no-decode timeout (usually 2 seconds), and typically is set to twice the no-decode timeout. Setting a shorter comm timeout could result in false no-read errors. Setting it to 0, while formally allowed, is just a bad idea.

int cmd_reset char *  args,
MsgType  msgtype,
char *  reply
 

RESET command - reload the runtime config paramters and re-initialize the barcode reader.

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 barcode reader is open it calls MSReset() to reset the barcode reader to its power-on state.

This provides the client application with a warm restart facility.

void KeyboardCommand char *  line  ) 
 

Process a command from the client's console keyboard.

Parameters:
line string with the keyboard command
This function is setup as a callback for readline(), the GNU command-line library that provides Emacs-like key bindings for command-line editing, rapid "arrow keys" command history browsing, and convenient command history commands (!, !!, etc.). This gives the client application's command-line interface a look-and-feel familiar to most users of Unix system command shells (e.g., the tcsh shell).

This function parses the interactive command line and calls the appropriate low-level cmd_xxx() command action functions for excuting most commands, as well as servicing ">XX msgtype: command" format raw IMPv2 message sending requests.

All keyboard commands are treated as EXEC: type IMPv2 messages. This makes the downstream cmd_xxx() action functions insensitive to whether or not the command came from the keyboard or from a remote ISIS server or client application.

See also:
SocketCommand()

void SocketCommand char *  buf  ) 
 

Process a message/command from the client UDP socket.

Parameters:
buf string with the IMPv2 message received from the remote application
This function parses a message received from a remote ISIS server or client application, and interprets the message. All EXEC: and implicit REQ: type messages are passed to the corresponding cmd_xxx() action functions for handling, while the remaining informational messages are simply echoed to the console screen.

More sophisticated handlers might pass such messages on to parsers/handlers of their own if the inputs were actually used for something other than "visual" information for the user of this application.

All messages received from an ISIS node are assumed to be in the proper IMPv2 messaging syntax.

Note that EXEC: is new to IMPv2. It allows remote nodes to transmit protected "executive" commands to clients, giving them access to commands that would otherwise only be available on the console keyboard (e.g., the "quit" command). Thus a remote EXEC: command means "act as if this was typed at the keyboard". It is the responsibility of the remote application to make sure that EXEC: is used with care, as you could do something stupid (though your client application should not allow actions that would be physically unsafe to personnel or equipment).

See also:
KeyboardCommand()


Generated on Thu Jul 22 20:10:48 2004 for Barcode Reader Agent by doxygen 1.3.7