[OPUS]

File_pstat_bb - A file name-based implementation of a Pstat_bb object.


Availability:

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

Pstat_bb

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

none


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

none

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

none


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

none

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;
  

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