tcsMAIN_HANDLER

NAME

SYNOPSIS

#include "tcsMAIN_HANDLER.h"

tcsMAIN_HANDLER<tcsBASE_CLASS> myHandler.

PARENT CLASS

public eccsERROR_CLASS
public tcsBASE

DESCRIPTION

The purpose of this template is to implement a standard way for all tcs processes
to handle the main() function, and in particular:

  - CCS initializzation
  - CCS termination
  - Handling of command line arguments
  - Handling of the EVH main loop and error recovery

One instance of the class must be defined in the main() function of the process,
giving as a template type the type of the main object in the application itself
(that must be a subclass of evhTASK).

Then the Init() method must be called, passing as arguments the main's argc and
argv parameters. This method takes care of parsing the command line arguments
and initialyzing CCS in the proper way.

The optional command line argument [-r dbRoot] is the root point of the TCS
paket DB branch. If omitted it is defaulted to value of the TCS_DBPOINT
environment variable or, if even this not defined, hard-coded to
":Appl_data:TCS".
This is implemented by using the serveces provided by the tcsBASE(4) class.

The optional argument [-n processName] is the name under which the process'
instance registers with the CCS and hence the destination process name
for commands to it. If omitted, the instance registers with CCS with
its UNIX process name, as passed by the shell in argv[0] (and removing any
pathname component).

After that the application objects can be created.

The following step is to call the RunMainLoop() method.
This enters the EVH main loop and takes care of handling recovery trials in case
of a severe error.
In order to handle this, it is necessary to provide two parameters: a pointer
to the main application object and a pointer to the method of the object itself
used for error recovery. If the parameters are set to NULL no error recovery
is done.

When the application exits in the normal way through the main(), the instance
is automatically deleted and the destructor takes care of properly closing CCS.

Look in the examples section for a complete example.
Other examples are in the test directory of the module and in the true TCS
modules, like auto guiding.

PUBLIC METHODS

  tcsMAIN_HANDLER()  Constructor. There can be only one instance
                     of the class in the application. It is created
                     in the main() and automatically destroyed when
                     exiting from the main.

  ~tcsMAIN_HANDLER() Destructor. If the object was initialized
                     it also closes CCS

  ccsCOMPL_STAT Init(int argCount, char *arg[])
                     Parses the command line arguments, initialyze CCS and
                     checks that the basic TCS database branch root point
                     is accessible.
                     Command line parsing is done calling EvaluateArgs().
                     The parsed command line options are used to define the
                     database branch root point and the process name that
                     will be used in ccsInit().
                     If returns FAILURE the Init() has not been successfully
                     completed and the application should exit with a failure
                     code.

  ccsCOMPL_STAT RunMainLoop(T *obj, ccsCOMPL_STAT(T::* recover)())
                     Enters the EVH main loop to wait for events and command.
                     If a callback returns with an error and the parameters obj
                     and recover are != NULL, it calls the recover method
                     obj->recover(). If it returns TRUE, the application
                     continues re-entering the main loop, otherwise the function
                     returns with an error. This causes the application to exit.
                     If returns FAILURE the a callback is failed AND no error
                     recovery has been possible; the application should exit
                     with a failure code. Look in the error stack for exact
                     error condition.
                     It returns SUCCESS a callback has requested explicitly a
                     return; the application should exit with a success code.

PROTECTED METHODS

  virtual ccsCOMPL_STAT EvaluateArgs(int argCount, char *arg[], ccsPROCNAME pname)
                     This is the method used for argument's parsing.
                     In this implementation it parses the standard TCS -r and -n
                     arguments. It must be overloaded in a subclass if it is
                     necessary to implement handling for other command line
                     arguments.
                     The last parameter contains on return the parsed process
                     name to be used to call ccsInit().

ENVIRONMENT

  TCS_DBPOINT specifies the root point of the TCS database branch

ERROR CONDITIONS

  tcsERR_CCS_INIT          Init() has not been able to execute ccsInit()
  tcsERR_ACCESS_DATABASE   Init() has not been able to access the TCS database
                           branch root point
  tcsERR_RECOVER           RunMainLoop() has tried an error recovery, but it
                           has failed.
  other error conditions are returned by RunMainLoop() when a callback fails
  and no recovery handler is installed

EXAMPLES

  #include "tcsMAIN_HANDLER.h"

  // * Application main class
  class tcsTEST_CLASS: public evhTASK
  {
    public:
      ccsCOMPL_STAT  Recover() { .... try to recover .....};
  };

  int main (int argc, char *argv[])
  {
      ccsCOMPL_STAT stat;

      // Creates the instance of the template class
      tcsMAIN_HANDLER<tcsTEST_CLASS> mainHandler;

      // Init the object to parse arguments
      stat = mainHandler.Init(argc, argv);
      if( stat == FAILURE)
          {
          exit(EXIT_FAILURE);
          }

      // Created the application object
      tcsTEST_CLASS    obj;

      // Enters the main loop
      stat = mainHandler.RunMainLoop(&obj, &tcsTEST_CLASS::Recover);
      if(stat == FAILURE)
          {
          exit(EXIT_FAILURE);
          }

      return(EXIT_SUCCESS);
  }

SEE ALSO

tcsBASE(4)

Index

NAME

SYNOPSIS

PARENT CLASS

DESCRIPTION

PUBLIC METHODS

PROTECTED METHODS

ENVIRONMENT

ERROR CONDITIONS

EXAMPLES

SEE ALSO