This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here

Constructors:

Command( )
~Command( )

Methods:

clone( )	returns a copy of this object
add_arg( )	adds a new calling argument to the vector of arguments for the function
get_args( )	gets a copy of the calling arguments for the function
execute( )	calls the function with any calling arguments stored in this object calls the function with any calling arguments stored in this object plus those in the supplied vector
str( )	overrides the base class to return only the Com_label value

Data Members:

 static const int COM_ARG_IDENT;       // unique field ID's

 static const int COM_LABEL_IDENT;

Description

These objects are used as entries on the command blackboard, and are a collection of information needed to call some function. They store a pointer to a function foo with signature and return type: bool foo(const vector&). As can be seen, all functions associated with Command objects take a reference to a vector of strings as a calling argument. The Command object stores each of the strings that are to be placed in the vector calling argument, when the function is called, in individual Com_arg objects (the order in which the Com_arg fields are added to the Command object determines the order in which they are placed in the vector calling argument).

In addition to Com_arg field objects, Command entry objects also contain an identifying Com_label field object which is used by the command blackboard to uniquely identify its entries.

Derived from

Entry

Example

  
    #include <vector>
    #include <string>
    #include <iostream>
    #include "command.h"
    #include "command_bb.h"
  
    using namespace std;
  
    // The following function demonstrates a global function to be
    // placed on the Command Blackboard by an OAPI client. This simple
    // example dumps its arguments to cout, then returns true.
    bool foo(vector<string>& args)
    {
       for (int i = 0; i < args.size(); i++) cout << args[i] << endl;
       return(true);
    }
  
    // The following driver posts a command on the Command Blackboard,
    // then does a search for it which results in its execution.
    int main(int argc, char* argv[])
    {
       string     label("Foo Command"); // give the command a name
       string     arg("/tmp");          // a command argument
       Command*   com;
  
       com = new Command(label, foo);   // create new Command that points
                                        // to foo()
       com->add_arg(arg);               // add a single calling argument
  
       Command_bb com_bb;
       com_bb.post(com);                // post Command on blackboard
       delete com;                      // no longer needed
  
       com = new Command(label);        // create Command for search
       vector<string> results;          // results vector
  
                                        // search returns size of results
                                        // vector
       if (com_bb.search(com, results)) {
           cout << "Command execution returns true." << endl;
           delete results[0];           // delete search result
       } else {
           cout << "Command not found or returned false." << endl;
       }
  
  
       delete com;                      // no longer needed
       return(0);
    }
  

See Also:

• Entry
• Command_bb
• Com_label
• Com_arg
• "OPUS API Blackboard and Support Classes Design Document"

Command::Command - The Command constructor.

Synopsis

Command::Command(
                 const string& l,                       // I - Com_label
                                                        //     label
                 bool (*fp)(const vector<string>&))     // I - pointer to
                                                        //     the function
                                                        //     associated
                                                        //     with this
                                                        //     object

Command::Command(
                 const Command& cmd) // I - object to initialize from

Description

This method constructs a new Command object and a new Com_label field object using the string argument as the label. The function pointer, if provided, is associated with the new Command object.

Exceptions Thrown

none

Example

  
    bool foo(vector<string>&);       // an external function
    string     label("Foo Command"); // give the command a name
    Command*   com;
    com = new Command(label, foo);   // create new Command that points
                                     // to foo()

Command::~Command - The Command destructor.

Synopsis

Command::~Command()

Description

This method destroys the object.

Exceptions Thrown

none

Command::clone - Create a copy of the Command object.

Synopsis

Entry* Command::clone() const

Description

A new Command object is allocated off the heap and is initialized using this object. A pointer to the new object is returned to the caller. The client should delete the returned object when it is no longer needed.

Returns

    A pointer to the new Command object initialized by this object.

Exceptions Thrown

none

Example

  
    string label("FOO_COMMAND");
    Command* com = new Command(label);      // create new command
  
    Entry* new_com = com->clone();          // clone it
  

Command::add_arg - Add a calling argument to the list of calling arguments for the associated function.

Synopsis

void Command::add_arg(
                      const string& s) // I - calling argument to add

Description

A new Com_arg field object is created using the supplied string argument, and is added to this object. Arguments should be added to the Command entry object in the same order expected by the associated function in its vector of strings calling argument.

Exceptions Thrown

none

Example

  
    string label("FOO_COMMAND");
    bool foo(const vector<string>&);        // the function to
                                            // associate with command
  
    Command* com = new Command(label, foo); // create new command
  
    string arg("/tmp/");
    com->add_arg(arg);                      // add calling argument
  

Command::get_args - Retrieve the current list of calling arguments.

Synopsis

int Command::get_args(
                      vector<string>& args) // O - vector to hold arguments
                      const

Description

Any calling arguments added to the Command object are pushed onto the vector argument in the same order they would be sent to the associated function if the execute method were called.

Returns

    the number of calling arguments stored in this object.

Exceptions Thrown

none

Example

  
    string label("FOO_COMMAND");
    bool foo(const vector<string>&);        // the function to
                                            // associate with command
  
    Command* com = new Command(label, foo); // create new command
  
    string arg("/tmp/");
    com->add_arg(arg);                      // add calling argument
  
    vector<string> cargs;
    com->get_args(cargs);                   // retrieve calling argument
  

Command::execute - Call the associated function together with its arguments plus any additional arguments passed to this method and return the result.

Synopsis

bool Command::execute()

bool Command::execute(
                      const vector<string>& addl_args) // I - additional
                                                       //     calling
                                                       //     arguments

Description

Each Com_arg value string is placed into a vector of strings with which the function is called. If this method is called with a vector of strings, that vector is appended to the vector formed above prior to calling the function.

Returns

    The return value of the called function.

Exceptions Thrown

[any exceptions thrown by the called function]

Not_ready<void*>

- if this object was not initialized with a function pointer; Not_ready.arg contains 0 always.

Example

  
    bool foo(vector<string>&); 
    string     label("Foo Command"); // give the command a name
    string     arg("/tmp");          // a command argument
    Command*   com;
  
    com = new Command(label, foo);   // create new Command that points
                                     // to foo()
    com->add_arg(arg);               // add a single calling argument
  
    Command_bb com_bb;
    com_bb.post(com);                // post Command on blackboard
    delete com;                      // no longer needed
  
    com = new Command(label);        // create Command for search
    vector<string> results;          // results vector
  
                                     // search returns size of results
                                     // vector
    if (com_bb.search(com, results)) {
        cout << "Command execution returns true." << endl;
        delete results[0];           // delete search result
    } else {
        cout << "Command not found or returned false." << endl;
    }
    delete com;
  

Command::str - Get the object's string label.

Synopsis

string Command::str() const

Description

This method overrides the base class implementation, and returns only the unpadded Com_label string.

Returns

    the string label for this object.

Exceptions Thrown

none

Example

  
    string label("FOO_COMMAND");
    Command* com = new Command(label);
    cout << "The command label is: " << com->str() << endl;
    delete com;
  

For more information, contact opushelp@stsci.edu

Last modified: 25 April 2000