zstream Documentation

Introduction

zstream provides C++ iostream like access to a Z39.50 result set. However, zstream is not stand-alone. You will need an implementation of the ZOOM C++ API. See http://zoom.z3950.org/ for details on ZOOM and its implementations. The Z39.50 Maintenance Agency, http://www.loc.gov/z3950/agency/, has the full Z39.50 specification.

Whilst the basic ZOOM API is easy to use, zstream takes the ease of use one step further by providing an interface that will be immediately familiar to C++ programmers who have used iostreams and istream_iterators.

I've put both the ZOOM::zstream and ZOOM::zstream_iterator classes into the ZOOM namespace, which is perhaps not the best idea. Suggestions for an alternative namespace name would be welcome.

Feedback

Please send all feedback to Ashley Sanders, a.sanders@manchester.ac.uk.

Download

zstream comes as a single C++ header file. No separate compilation is necessary.

• http://www.mimas.ac.uk/~zzaascs/zstream/zstream.hpp

Examples

In the following examples I create query objects of type simpleQuery. Depending on the implementation you have, the actual type of the query object may vary.

If you wanted to process every record in a result set, you might use code as follows:

ZOOM::connection conn ("localhost", 210);
ZOOM::zstream zs (conn, simpleQuery ("ti=\"pendon\""));
ZOOM::record r;
while (zs >> r)
  ProcessRecord (r);

You can use manipulators to change the record syntax and element set name for next record to be retrieved:

ZOOM::connection conn ("localhost", 210);
ZOOM::zstream zs (conn, simpleQuery ("ti=\"pendon\""));
ZOOM::record r;
// Ask for the first record as a full GRS-1 record.
zs >> grs1 >> esn("F") >> r;
// Ask for the next record as a brief MARC21 record.
zs >> marc21 >> esn("B") >> r;

The manipulators set the record syntax and element set name for all subsequent records retrieved. Should a Z39.50 server not be able to deliver a record in the requested syntax or element set name, then the stream will be put into a failed state, ie fail() will return true. You must clear() the failure before you can retrieve further records (and you'll probably want to reset the syntax or element set name as well.)

Using iterators

You can use zstream_iterators to interoperate with STL algorithms and containers. The following example pulls in every record from a result set into a vector of records:

ZOOM::connection conn ("localhost", 210);
ZOOM::zstream zs (conn, simpleQuery ("ti=\"pendon\""));
ZOOM::zstream_iterator zit (zs);
ZOOM::zstream_iterator eof;
std::vector<ZOOM::record> vec (zit, eof);

If you wanted a list of all the rendered records in a result set then an algorithm and a function object along with a zstream_iterator can be used as follows:

struct render {
  std::string operator() (const ZOOM::record &r) {
    return r.render ();
  }
};

ZOOM::connection conn ("localhost", 210);
ZOOM::zstream zs (conn, simpleQuery ("ti=\"pendon\""));
ZOOM::zstream_iterator zit (zs);
ZOOM::zstream_iterator eof;
std::list<std::string> lst;
std::transform (zit, eof, std::back_inserter (lst), render ());

Or perhaps you just want to blast the whole result set to standard out:

ZOOM::connection conn ("localhost", 210);
ZOOM::zstream zs (conn, simpleQuery ("ti=\"pendon\""));
std::transform (
    ZOOM::zstream_iterator (zs),
    ZOOM::zstream_iterator (),
    std::ostream_iterator<std::string> (std::cout, "\n"),
    std::mem_fun_ref (&ZOOM::record::render)
  );

To do

• zstream currently provides no way of finding out what error caused a stream to be put into a failed state.

---