![[OPUS]](opus.gif)
This class is available for the OPUS Blackboard API. The initial OPUS 2.0 release is described here
Constructors:
| File_pstat_bb( ) | construct given directory containing the PSTAT files |
| ~File_pstat_bb( ) |
Methods:
| post( ) | creates a Pstat file |
| erase( ) | deletes a Pstat file |
| replace( ) | renames a Pstat file |
| search( ) | searches for matching PSTAT files |
| lock_entry( ) | places a lock on a PSTAT file |
| str( ) | gets the blackboard name |
| get_bb_dir( ) | gets the directory in which the PSTAT files are stored |
| new_pstat( ) | creates a new File_pstat object |
| appl_pstat( ) | returns a copy of the application's PSTAT |
| test_driver( ) | runs the test driver |
Description
This implementation of a Pstat_bb object stores its entries, File_pstat objects, as files in the directory specified by the environment variable OPUS_OBSERVATIONS_DIR. The file name contains all of the information-- the files themselves are empty. In general, clients of the OAPI do not instantiate objects of this class directly.
Derived from
Example
#include <iostream>
#include "file_pstat_bb.h"
#include "file_pstat.h"
#include "pid.h"
#include "node.h"
#include "opus_lock.h"
using namespace std;
// The following example uses the File PSTAT Blackboard to find
// an application's PSTAT on disk, then delete it.
int main(int argc, char* argv[])
{
// constructor takes
// OPUS_HOME_DIR path
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
Pstat* fpstat = pbb->new_pstat(); // padded except for Pid &
// Node fields
Pid* pid = new Pid(123); // replace PID in PSTAT
fpstat->set_field(pid);
delete pid;
Node* node = new Node("foo"); // replace NODE in PSTAT
fpstat->set_field(node);
delete node;
fpstat->search_fill(); // place search characters in
// remaining fields
vector<Entry*> res;
if (pbb->search(fpstat, res)) { // search for PSTAT
Opus_lock* lck = 0;
try { // attempt lock on PSTAT
lck = pbb->lock_entry(res[0]);
pbb->erase(res[0]); // delete it
cout << "Deleted PSTAT: " << fpstat->str() << endl;
}
catch(...) {
cout << "Failed to delete PSTAT: " << res[0]->str()
<< endl;
}
delete lck; // release & delete
delete res[0];
} else {
cout << "Could not find PSTAT: " << fpstat->str() << endl;
}
delete fpstat;
delete pbb;
return(0);
}
See Also:
File_pstat_bb::File_pstat_bb - The File_pstat_bb constructor.
Synopsis
File_pstat_bb::File_pstat_bb(
const string& dir) // I - directory containing
// the PSTAT files
Description
The constructor verifies that the directory specified in the calling argument exists.
Exceptions Thrown
| Io_error<int> | - if indicated directory does not exist; Io_error.arg contains the value of errno |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
File_pstat_bb::~File_pstat_bb - The File_pstat_bb destructor.
Synopsis
File_pstat_bb::~File_pstat_bb()
Description
This method destroys the object.
Exceptions Thrown
File_pstat_bb::post - Create a PSTAT file.
Synopsis
void File_pstat_bb::post(
const Entry* ce) // I - File_pstat object to
// create file from
Description
This method creates a file based on the File_pstat object in the blackboard directory. If a PSTAT file with the same Node and Pid fields already exists, an exception is thrown.
Exceptions Thrown
| Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
| Type<Entry*> | - if argument is not of type File_osf; Type.arg points to the calling argument |
| Already<Entry*> | - if the OSF file already exists; Already.arg points to the calling argument |
| Io_error<int> | - if a file creation error occurs; Io_error.arg contains the value of errno |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
Pstat* fpstat = pbb->new_pstat(); // padded except for Pid &
// Node fields
Pid* pid = new Pid(123); // replace PID in PSTAT
fpstat->set_field(pid);
delete pid;
Node* node = new Node("foo"); // replace NODE in PSTAT
fpstat->set_field(node);
delete node;
try {
pbb->post(fpstat); // place PSTAT on file system
}
catch(Already<Entry*>) {
cout << "PSTAT already exists!" << endl;
}
delete fpstat;
delete pbb;
File_pstat_bb::erase - Delete a PSTAT file.
Synopsis
void File_pstat_bb::erase(
const Entry* ce) // I - File_pstat object to delete
Description
The PSTAT file named in the argument is deleted from the blackboard directory. If multiple matches to the PSTAT are found or no match exists, exceptions are thrown. No attempt is made to lock the object being deleted; the caller is responsible for obtaining a lock prior to making this call.
Exceptions Thrown
| Bad_val<Entry*> | - if the argument is null; Bad_val.arg points to the calling argument |
| Type<Entry*> | - if argument is not of type File_osf; Type.arg points to the calling argument |
| Bad_val<Entry*> | - if first argument is null; Bad_val.arg points to the first argument |
| Type<Entry*> | - if first argument is not of type File_pstat; Type.arg points to the first argument |
| Io_error<const char*> | - if the file search fails; Io_error.arg contains the error message |
| Ambiguous<vector<Entry*>*> | - if more than one PSTAT file is found on disk; Ambiguous.arg points to a vector allocated off the heap containing all matching entries, each allocated off the heap |
| Io_error<int> | - if the delete operation fails; Io_error.arg contains the value of errno |
| No_entry<Entry*> | - if no PSTAT file is found; No_entry.arg points to the calling argument |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
Pstat* fpstat = pbb->new_pstat(); // padded except for Pid &
// Node fields
Pid* pid = new Pid(123); // replace PID in PSTAT
fpstat->set_field(pid);
delete pid;
Node* node = new Node("foo"); // replace NODE in PSTAT
fpstat->set_field(node);
delete node;
fpstat->search_fill(); // place search characters in
// remaining fields
vector<Entry*> res;
if (pbb->search(fpstat, res)) { // search for PSTAT
Opus_lock* lck = 0;
try { // attempt lock on PSTAT
lck = pbb->lock_entry(res[0]);
pbb->erase(res[0]); // delete it
delete lck; // release & delete
cout << "Deleted PSTAT: " << fpstat->str() << endl;
}
catch(...) {
cout << "Failed to delete PSTAT: " << res[0]->str()
<< endl;
}
delete res[0];
} else {
cout << "Could not find PSTAT: " << fpstat->str() << endl;
}
delete fpstat;
delete pbb;
File_pstat_bb::replace - Rename a PSTAT file.
Synopsis
void File_pstat_bb::replace(
const Entry* old_ent, // I - PSTAT file to
// replace
const Entry* new_ent) // I - replacement PSTAT
// file
Description
This method replaces the PSTAT file named in the first argument with the PSTAT file named in the second argument. No attempt is made to lock the object being replaced; the caller is responsible for obtaining a lock prior to making this call.
Exceptions Thrown
| Bad_val<int> | - if either argument is null; Bad_val.arg indicates which arg is bad (0 or 1) |
| Type<const Entry*> | - if either argument is not of type File_pstat; Type.arg points to the bad argument |
| Io_error<const char*> | - if the file rename attempt fails; Io_error.arg contains the error message |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
Pstat* old_ap = pbb->appl_pstat(); // get application's PSTAT
// make a copy
Pstat* new_ap = dynamic_cast<Pstat*>(old_ap->clone());
// create HALT command
Proc_cmd* pc = new Proc_cmd(Proc_cmd::PSTAT_HALT_COMMAND);
new_ap->set_field(pc); // apply to new PSTAT
delete pc;
pbb->replace(old_ap, new_ap); // replace PSTAT
delete old_ap;
delete new_ap;
delete pbb;
File_pstat_bb::search - Search for a PSTAT file on the blackboard.
Synopsis
int File_pstat_bb::search(
const Entry* ce, // I - the PSTAT file to
// look for
vector<Entry*>& res) // I - results vector
const
Description
A search of the blackboard is made for the file named in the File_pstat object argument. Any matches are placed in new File_pstat entries which are pushed on the vector argument. The client should delete these entries when they are no longer needed as they are allocated off the heap.
Returns
The size of the vector argument after the search is made and matching
entries have been pushed on the vector argument.
Exceptions Thrown
| Bad_val<Entry*> | - if first argument is null; Bad_val.arg points to the first argument |
| Type<Entry*> | - if first argument is not of type File_pstat; Type.arg points to the first argument |
| Io_error<const char*> | - if the file search fails; Io_error.arg contains the error message |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
Pstat* fpstat = pbb->new_pstat(); // padded except for Pid &
// Node fields
Pid* pid = new Pid(123); // replace PID in PSTAT
fpstat->set_field(pid);
delete pid;
Node* node = new Node("foo"); // replace NODE in PSTAT
fpstat->set_field(node);
delete node;
fpstat->search_mask(); // place search characters in
// remaining fields
vector<Entry*> res;
if (pbb->search(fpstat, res)) { // search for PSTAT
cout << "Found PSTAT: " << res[0]->str() << endl;
delete res[0];
} else {
cout << "No match to PSTAT " << fpstat->str() << " found."
<< endl;
}
delete fpstat;
delete pbb;
File_pstat_bb::new_pstat - Create a new File_pstat object.
Synopsis
Pstat* File_pstat_bb::new_pstat() const
Pstat* File_pstat_bb::new_pstat(
const char* c_str) // I - PSTAT file
// name
const
Description
A new File_pstat object is constructed off the heap and returned to the caller. If an argument is provided, it should contain a valid PSTAT file name. If no argument is provided, the new object will be initialized with the application's PID and NODE in their respective fields; the other fields will contain padding. The client should delete the object when it is no longer needed.
Returns
A pointer to the new File_pstat object.
Exceptions Thrown
| Bad_val<string> | - if the file name fails to parse; Bad_val.arg contains a copy of the calling argument |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
Pstat* fps = pbb->new_pstat();
File_pstat_bb::appl_pstat - Get a copy of the application's PSTAT.
Synopsis
Pstat* File_pstat_bb::appl_pstat() const
Description
A new File_pstat object containing a copy of the applications's current PSTAT information is constructed off the heap and returned to the caller. The new object should be deleted by the client when it is no longer needed.
Returns
A pointer to the new File_pstat object containing the application's
PSTAT.
Exceptions Thrown
| Bad_val<Entry*> | - if first argument is null; Bad_val.arg points to the first argument |
| Type<Entry*> | - if first argument is not of type File_pstat; Type.arg points to the first argument |
| Io_error<const char*> | - if the file search fails; Io_error.arg contains the error message |
| Ambiguous<vector<string>*> | - if more than one PSTAT is found; Ambiguous.arg points to a vector allocated off the heap containing the list of matching PSTAT files |
| No_entry<void*> | - if no PSTAT file is found; No_entry.arg points to null |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstat");
Pstat* pst = pbb->appl_pstat();
File_pstat_bb::lock_entry - Create a lock file for the indicated PSTAT file.
Synopsis
Opus_lock* File_pstat_bb::lock_entry(
const Entry* ce) // I - PSTAT file to
// lock
Description
This method attempts to create a lock file for the indicated PSTAT file. If the PSTAT is locked already, an exception is thrown. If multiple matches to the PSTAT file are found or no match exists, exceptions are thrown. The returned Opus_lock object is allocated off the heap, and should be deleted by the client when it is no longer needed.
Returns
A new Opus_lock object for the PSTAT file.
Exceptions Thrown
| Bad_val<Entry*> | - if argument is null; Bad_val.arg points to the calling argument |
| Type<Entry*> | - if argument is not of type File_pstat; Type.arg points to the calling argument |
| Locked<string> | - if the target file is locked already; Locked.arg contains the target name |
| Io_error<int> | - if an IO error occurs during the lock attempt; Io_error.arg contains the value of errno |
| Bad_val<string> | - if the stretch cannot be resolved; Bad_val.arg contains the stretched file name |
| Bad_val<vector<string>> | - if the calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments |
| Io_error<int> | - if the disk space check fails; Io_error.arg contains the value of errno |
| Bad_val<vector<string>> | - if calling arguments are incorrect; Bad_val.arg is a vector containing the calling arguments |
| Exec<int> | - if the subprocess spawn attempt fails; Exec.arg contains the return status from the spawn attemp |
| Bad_val<string> | - if the string does not appear to be a directory specification or invalid characters are present; Bad_val.arg contains the calling argument |
| Io_error<int> | - if a problem occurs determining the current working directory; Io_error.arg contains the value of errno |
| Bad_val<string> | - if the string contains invalid characters; Bad_val.arg contains the calling argument |
| Bad_val<string> | - if the extension prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument |
| Bad_val<string> | - if dangle prefix is not present or invalid characters are present; Bad_val.arg contains the calling argument |
| Io_error<int> | - if an IO error occurs creation of the lock directory; Io_error.arg contains the value of errno |
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
Pstat* fpstat = pbb->new_pstat(); // padded except for Pid &
// Node fields
Pid* pid = new Pid(123); // replace PID in PSTAT
fpstat->set_field(pid);
delete pid;
Node* node = new Node("foo"); // replace NODE in PSTAT
fpstat->set_field(node);
delete node;
fpstat->search_fill(); // place search characters in
// remaining fields
vector<Entry*> res;
if (pbb->search(fpstat, res)) { // search for PSTAT
Opus_lock* lck = 0;
try { // attempt lock on PSTAT
lck = pbb->lock_entry(res[0]);
pbb->erase(res[0]); // delete it
delete lck; // release & delete
cout << "Deleted PSTAT: " << fpstat->str() << endl;
}
catch(...) {
cout << "Failed to delete PSTAT: " << res[0]->str()
<< endl;
}
delete res[0];
} else {
cout << "Could not find PSTAT: " << fpstat->str() << endl;
}
delete fpstat;
delete pbb;
File_pstat_bb::str - Get the blackboard name.
Synopsis
string File_pstat_bb::str() const
Description
This method returns a string describing the blackboard.
Returns
string containing the blackboard name, "File_pstat_bb".
Exceptions Thrown
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
cout << "PSTAT implementation in use is " << pbb->str() << endl;
File_pstat_bb::get_bb_dir - Get the blackboard location on the file system.
Synopsis
string File_pstat_bb::get_bb_dir() const
Description
This method returns the directory in which the blackboard is stored.
Returns
string containing the blackboard location
Exceptions Thrown
File_pstat_bb::test_driver - Test the blackboard implementation.
Synopsis
bool File_pstat_bb::test_driver()
Description
This method exercises the object's methods. Diagnostic output is sent to cerr. If all of the tests pass, this method returns true. Otherwise, it returns false. All exceptions generated during the test are caught and reported.
Returns
true - if all tests pass;
false - if one or more of the tests fail
Exceptions Thrown
Example
File_pstat_bb* pbb = new File_pstat_bb("/home/opus/pstats/");
cout << "Running the File PSTAT Blackboard test driver." << endl;
if (pbb.test_driver()) cout << "Pass." << endl;
else cout << "Fail." << endl;
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