
                DBXML Getting Started Examples
                            Readme

This directory contains examples and sample data designed to illustrate
DBXML's basic capabilities. Generally, to run the examples you must first
compile the examples and then load the sample data using
loadExamplesData[.sh|.cmd] (depending on your platform).  This script uses the
exampleLoadContainer example program to load all the sample data contained in
the xmlData directory into the appropriate containers.

To run loadExamplesData, you must provide the directory where you want your
database environment to be placed and the directory where these examples are
stored. The database environment directory must exist before you run the
script.

For example:

     cd <examples directory>
     mkdir dbEnvironment
     loadExamplesData dbEnvironment .

This causes the sample data to be loaded into a database environment stored in
<examples directory>/dbEnvironment. The dot (.) tells the script that the
examples are contained in the current working directory. It needs this 
information in order to find the xmlData directory.

Once loaded, most of the examples found here can be run by simply identifying
the directory where you placed your database environment. For example:

    simpleQuery -h dbEnvironment


EXAMPLES DESCRIPTION

- simpleContainer.cpp

  Creates a container, closes it, and then quits. No database environment is
  used. You should edit this file and identify a real path to where you want
  your container placed before running this example.

- simpleContainerInEnv.cpp
  Creates a database environment, opens it, and then creates and opens three
  containers in that environment. Finally, the containers and environments are
  closed. You should edit this file and provide a path to an existing
  directory where you want the database environment placed before running this
  example.

- myDbEnv.hpp
  Declares and implements a class that creates/opens a database environment.
  All of the following examples rely on this class.

- myXmlContainer.hpp
  Declares and implements a class that creates/opens a container. The
  container can opened with or without a database environment. All of the
  following examples rely on this class.

- simpleAdd.cpp
  Creates a database environment and container, and then adds two very simple
  XML documents to the container. You identify the location where you want the
  database environment placed using the -h option. This example requires no
  other command line options.

- exampleLoadContainer.cpp
  Creates/opens the specified database environment, creates/opens the
  specified container in that environment, and then loads every XML document
  identified on the command line call into the identified container. As each
  document is loaded, a document name is set. Metadata is also set on each
  document that represents the day and time that the document was loaded into
  the container.

  All of the following examples assume that exampleLoadContainer has been run
  via loadExamplesData[.sh|.bat].

    exampleLoadContainer -h <dbenv> -c <containername> file1.xml file2.xml ...

- simpleQuery.cpp
  Executes several XPath queries and prints query results to the console.
  Use the -h option to identify the database environment location that you
  used when you ran loadExamplesData.

       simpleQuery -h <dbenv>

  Note that all of the following examples use the same command line option.

- queryWithContext.cpp
  Identical to simpleQuery, except that contexts are used to define
  namespaces and variables. 

- queryForDocumentValue.cpp
  Identical to queryWithContext, except that specific document data is
  retrieved from each document found in the query's result set.

- queryWithDocumentNames.cpp
  Identical to queryWithContext, except that the query is performed using the
  document name that was set when exampleLoadContainer placed the document
  into the container.

- queryForMetaData.cpp
  Identical to queryWithContext, except that the timestamp that was stored as
  metadata is retrieved and displayed. This timestamp was set on the document
  when exampleLoadContainer placed the document into the container.

- updateDocument.cpp
  Identical to queryWithContext, except that the document retrieved as the
  result of the query is updated in a trivial way and then stored back into
  the container.

- modifyDocument.cpp
  Similar to updateDocument, except that the document(s) retrieved as the
  result of the query are updated via XmlContainer::modifyDocument(), and
  optionally committed back to the container.

- deleteDocument.cpp
  Identical to queryWithContext, except that every document retrieved as the
  result of the query is deleted from the container.

- addIndex.cpp
  Adds indexes to a specific document node.

- replaceIndex.cpp
  Replaces the indexes on a specific document node with new indexes. Iterates
  through the indexes maintained for the container and shows what is being
  used. For best results, run addIndex before running this example.
  
- deleteIndex.cpp
  Deletes indexes from a specific document. Iterates through the indexes
  maintained for the container and shows what is being used. For best results,
  run addIndex before running this example.
  
- myDb.hpp
  Declares and implements a class that creates/opens a Berkeley db.
  The following two examples rely on this class.

- buildDB.cpp 
  Illustrates how a DBXML container can be used with a Berkeley DB database. A
  Berkeley DB database is created in the same environment as the container and
  data corresponding to documents in the container is loaded into the
  database. The DBXML query and database put are all wrapped in a common
  transaction.

- retrieveDB.cpp
  Illustrates how a DBXML container can be used with a Berkeley DB database.
  Documents are retrieved from the container and then data corresponding to
  each document is retrieved from the Berkeley DB database. Again, all queries
  are wrapped in a common transaction. For best results, run buildDB before
  running this example.
  


