Next: A Pool Scan Example
Up: Scanning Pools in a Application
Previous: Introduction
An application scans a pool by creating a PoolScan object. PoolScan
objects are transient C++ objects, not persistent Shore objects. A PoolScan
object can be in one of two states: open or closed. A scan
must be opened inside a transaction, and can only be used inside the
transaction in which it was opened. Once a scan is opened, it stays open
until it is explicitly closed, or until the scan object is destroyed, or
the transaction terminates. In particular, the scan object
remains open even after the end of the scan has been reached or an
error has occurred.
The public interface to the PoolScan class is
class PoolScan {
public:
PoolScan();
PoolScan(const char *path);
PoolScan(const ref<Pool> pool);
shrc open(const char *path);
shrc open(const ref<Pool> pool);
shrc next(ref<any> &ref, bool fetch = false, LockMode mode = SH);
bool is_open();
shrc rc();
int operator==(shrc rc);
int operator!=(shrc rc);
shrc close();
~PoolScan();
};
- PoolScan()
- is the default constructor. The resulting PoolScan object is in the
closed state.
It may be opened by the open member function.
- PoolScan(const char *path)
- PoolScan(const ref<Pool> pool)
- These constructors invoke the corresponding versions of the open member
function.
The caller should whether the open operation was successful by calling
is_open() or by testing the return code with rc(),
operator==(), or operator!=().
- shrc open(const char *pool)
- shrc open(const ref<Pool> pool)
- The pool argument should be the pathname of a valid directory
in the Shore filesystem namespace or a reference to a Pool object,
and the PoolScan object should be in the closed state.
The caller must have (at least) read permission for the indicated pool
and must have a transaction open.
Upon successful completion, RCOK is returned. Any
other return value indicates an error condition.
- shrc next(ref<any> &ref, bool fetch = false,
LockMode mode = SH)
- returns a reference to the next object in the pool (if the scan has
just been opened, then it returns the first object in the pool).
Objects are returned in apparently random order, but each object is returned
exactly once by a scan.
If fetch is true, the object will be fetched into the
object cache, and a lock will be obtained on the object in the mode
indicated by mode, if such a lock is not already held by the
transaction.
If fetch is false (the default), mode is
ignored and the object is not fetched from the server.
The return value of next is RCOK if there was a next object in
the scan. If an attempt is made to go beyond the end of the scan (i.e., a
call to next is made after the last object in the scan has already
been returned), then the return code will be OC_EndOfScan. Any
other return code indicates an error condition.
- bool is_open()
- indicates whether the scan is open or closed.
Note that the scan remains open after retrieving the last entry.
- shrc rc()
- returns the return code generated by the last operation
(open or next).
- int operator==(shrc rc)
- int operator!=(shrc rc)
- These operators provide a convenient way to check the status of the scan.
For example, applications can say if (scan == RCOK) ....
- shrc close()
- closes the scan object. Closing a scan object releases any resources
associated with the scan in both the server and client processes (such as
the scan buffer). It also allows the scan object to be reused.
The scan is closed implicitly when the PoolScan object is
destroyed (either via operator delete or when the DirScan object goes out
of scope), or when the transaction in which the scan was opened terminates.
- ~PoolScan()
- The PoolScan destructor closes the scan object if it is open.
Next: A Pool Scan Example
Up: Scanning Pools in a Application
Previous: Introduction
This page was generated from LaTeX sources
10/27/1997