&). 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:
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
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
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
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
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
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
Example
string label("FOO_COMMAND");
Command* com = new Command(label);
cout << "The command label is: " << com->str() << endl;
delete com;
OPUS API index ·
STScI Home Page ·
Search ·
Topics ·
Index
Copyright © 1997-2000 The Association of Universities for
Research in Astronomy, Inc. All Rights Reserved.
For more information, contact
opushelp@stsci.edu
Last modified:
25 April 2000
![[OPUS]](opus.gif)