tcsCMD_HANDLER

NAME

SYNOPSIS

#include <tcsCMD_HANDLER.h>
tcsCMD_HANDLER cmdHandler(dbroot, cmdName, callback)

PARENT CLASS

tcsSTATE

DESCRIPTION

Class to handle user commands in an evhHANDLER application. It provides
the following features:
  - command call-back installation and de-installation
  - checking whether execution of command is allowed
  - state switching between IDLE and BUSY
  - storing the user message
  - sending replies (normal or error) to the originator
  - internal usage of the command function

To use the class for a specific command you can either overload the
Execute() method or provide an external callback for that purpose.

The constructor installs a generic call-back for the given command which
performs execution checking and calls the command executor function if
command execution is allowed. The destructor de-installs that call-back.

The checking for execution permit uses the following algorithm:
  - If the state is not an ONLINE sub-state, the command is rejected.
  - If the object is still active, i.e. the previous same command has not
    yet sent a last reply (or error reply), the new command is rejected.
  - If any other command is still active, the command is accepted.

If the command is accepted, the state is set to BUSY if not yet there.
On command completion the state is set to IDLE, if no other command is
still active. However, this is done only while in an ONLINE sub-state.

The object keeps track whether it is active, i.e. whether the execution of
a command is in progress. The according flag is set when a command is
received and unset when an error reply or last reply is sent.
THEREFORE IT IS IMPORTANT ALWAYS TO USE THE SendReply() METHOD OF THIS CLASS
FOR SENDING REPLIES, OTHERWISE THE OBJECT WOULDN'T KNOW THAT THE COMMAND
IS COMPLETED!

The class is also designed to allow usage of the command function not only
by the evhHandler but from inside the application (high-level commands use
the functionality of low-level commands). To do so, the application sends
the low-level command to itself.

When called from internally the SendReply() method hence sends replies to
the own process. Thus, using own commands internally is just like sending
a command to a sub-process.

PUBLIC METHODS

tcsCMD_HANDLER(const dbSYMADDRESS dRoot, const msgCMD cmdName,
                 const evhCALLBACK *cb = NULL);
    The constructor installs the generic command call-back. It takes
    the command name and the DB support point of the process as arguments.
    If the optional callback cb is given, it is replaces the built-in
    command execution function.

virtual ~tcsCMD_HANDLER();
    De-installs the command call-back and cleans everything.

virtual Init();
    Initializes the object.

virtual Reset();
    Aborts the command execution, if active and resets the object to
    inactive state.

const char *CmdName();
    Returns the associated command name.

vltLOGICAL IsActive();
    Returns ccsTRUE if a command execution is currently in progress.

evhCB_COMPL_STAT SendReply(const char *buffer, msgLENGTH size = 0,
                           vltLOGICAL last = ccsTRUE);
    Sends a normal reply to the originator and sets the command state to
    "not active" if flag <last> is set.

evhCB_COMPL_STAT SendReply(const ccsERROR &newErrmsg);
    Send an error reply back to the originator and sets the command state
    to "not active".

void MsgCaller(msgMESSAGE &msg);
    Set the original user command.

const char *MsgCallerName();
    Returns the name of the command originator process as @env:process.

vltLOGICAL InternalCall();
    Returns ccsTRUE if currently active due to an internal invokation.

PROTECTED METHODS

evhCB_COMPL_STAT CommandCB(msgMESSAGE &msg, void *udata);
    This is the generic callback which is installed at the event handler.
    It first checks if execution of the command is allowed in the current
    state and, if so, calls the overloaded execution function.

virtual evhCB_COMPL_STAT Execute(msgMESSAGE &msg, void *udata) = 0;
    Executes the connected command function. Gets the original message and
    udata from the CommandCB.

virtual vltLOGICAL ExecutionPermitted(msgMESSAGE &msg);
    Check if the new command can be executed in the current state and if it
    conflicts with a pending command.
    For the following commands execution is permitted in any state (for all others
    only in ONLINE): ONLINE,STANDBY,OFF,INIT,EXIT,STATUS,STATE,SIMULAT,STOP,STOPSIM,VERBOSE,VERSION
    + all commands that are sent by the process to itself.

virtual vltLOGICAL IsOwnProcess(msgMESSAGE &msg);
    Check if the new command is sent by the process itself.

void SetActive(vltLOGICAL flag=TRUE);
    Sets the object command state to "active" or "not active" as given in
    flag. Used internally when a command is received and accepted. When
    the state was IDLE it is set to BUSY on a command becoming active and
    vice versa.

msgMESSAGE &MsgCaller();
    Retrieves the message stored as the original user message.

PRIVATE DATA MEMBERS

msgCMD       command;         // name of command handled by this instance
msgMESSAGE   orgMsg;          // originator command message
evhCALLBACK *userCB;          // user's command callback
vltLOGICAL   cmdActive;       // flag if a command is active
static vltINT32 activeCount;  // number of commands active in parallel

FILES

None

ENVIRONMENT

None

COMMANDS

An object of this class can be connected to any command.

SEE ALSO

evhHANDLER, tcsSTATE

Index

NAME

SYNOPSIS

PARENT CLASS

DESCRIPTION

PUBLIC METHODS

PROTECTED METHODS

PRIVATE DATA MEMBERS

FILES

ENVIRONMENT

COMMANDS

SEE ALSO