<HTML>
<HEAD>
<TITLE>stag-db</TITLE>
<LINK REV="made" HREF="mailto:feedback@suse.de">
</HEAD>
<BODY>
<A NAME="__index__"></A>
<!-- INDEX BEGIN -->
<UL>
<LI><A HREF="#name">NAME</A></LI>
<LI><A HREF="#synopsis">SYNOPSIS</A></LI>
<LI><A HREF="#description">DESCRIPTION</A></LI>
<UL>
<LI><A HREF="#arguments">ARGUMENTS</A></LI>
<UL>
<LI><A HREF="#i indexfile">-i INDEXFILE</A></LI>
<LI><A HREF="#r relationname">-r RELATION-NAME</A></LI>
<LI><A HREF="#k uniquekey">-k UNIQUE-KEY</A></LI>
<LI><A HREF="#u uniquekey">-u UNIQUE-KEY</A></LI>
<LI><A HREF="#p parser">-p PARSER</A></LI>
<LI><A HREF="#q queryid">-q QUERY-ID</A></LI>
<LI><A HREF="#top nodename">-top NODE-NAME</A></LI>
<LI><A HREF="#qf queryfile">-qf QUERY-FILE</A></LI>
<LI><A HREF="#keys">-keys</A></LI>
<LI><A HREF="#w writer">-w WRITER</A></LI>
</UL>
</UL>
<LI><A HREF="#see also">SEE ALSO</A></LI>
</UL>
<!-- INDEX END -->
<HR>
<P>
<H1><A NAME="name">NAME</A></H1>
<P>stag-db.pl - persistent storage and retrieval for stag data (xml, sxpr, itext)</P>
<P>
<HR>
<H1><A NAME="synopsis">SYNOPSIS</A></H1>
<PRE>
stag-db.pl -r person -k social_security_no -i ./person-idx myrecords.xml
stag-db.pl -i ./person-idx -q 999-9999-9999 -q 888-8888-8888</PRE>
<P>
<HR>
<H1><A NAME="description">DESCRIPTION</A></H1>
<P>Builds a simple file-based database for persistent storage and
retrieval of nodes from a stag compatible document.</P>
<P>Imagine you have a very large file of data, in a stag compatible
format such as XML. You want to index all the elements of type
<STRONG>person</STRONG>; each person can be uniquely identified by
<STRONG>social_security_no</STRONG>, which is a direct subnode of <STRONG>person</STRONG></P>
<P>The first thing to do is to build an index file, which will be stored
in your current directory:</P>
<PRE>
stag-db.pl -r person -k social_security_no -i ./person-idx myrecords.xml</PRE>
<P>You can then use the index ``person-idx'' to retrieve <STRONG>person</STRONG> nodes by
their social security number</P>
<PRE>
stag-db.pl -i ./person-idx -q 999-9999-9999 > some-person.xml</PRE>
<P>You can export using different stag formats</P>
<PRE>
stag-db.pl -i ./person-idx -q 999-9999-9999 -w sxpr > some-person.xml</PRE>
<P>You can retrieve multiple nodes (although these need to be rooted to
make a valid file)</P>
<PRE>
stag-db.pl -i ./person-idx -q 999-9999-9999 -q 888-8888-8888 -top personset</PRE>
<P>Or you can use a list of IDs from a file (newline delimited)</P>
<PRE>
stag-db.pl -i ./person-idx -qf my_ss_nmbrs.txt -top personset</PRE>
<P>
<H2><A NAME="arguments">ARGUMENTS</A></H2>
<P>
<H3><A NAME="i indexfile">-i INDEXFILE</A></H3>
<P>This file will be used as the persistent index for storage/retrieval</P>
<P>
<H3><A NAME="r relationname">-r RELATION-NAME</A></H3>
<P>This is the name of the stag node (XML element) that will be stored in
the index; for example, with the XML below you may want to use the
node name <STRONG>person</STRONG> and the unique key <STRONG>id</STRONG></P>
<PRE>
<person_set>
<person>
<id>...</id>
</person>
<person>
<id>...</id>
</person>
...
</person_set></PRE>
<P>This flag should only be used when you want to store data</P>
<P>
<H3><A NAME="k uniquekey">-k UNIQUE-KEY</A></H3>
<P>This node will be used as the unique/primary key for the data</P>
<P>This node should be nested directly below the node that is being
stored in the index - if it is more that one below, specify a path</P>
<P>This flag should only be used when you want to store data</P>
<P>
<H3><A NAME="u uniquekey">-u UNIQUE-KEY</A></H3>
<P>Synonym for <STRONG>-k</STRONG></P>
<P>
<H3><A NAME="p parser">-p PARSER</A></H3>
<P>This can be the name of a stag supported format (xml, sxpr, itext) -
XML is assumed by default</P>
<P>It can also be a module name - this module is used to parse the input
file into a stag stream; see <A HREF="./Data/Stag/BaseGenerator.html">the Data::Stag::BaseGenerator manpage</A> for details
on writing your own parsers/event generators</P>
<P>This flag should only be used when you want to store data</P>
<P>
<H3><A NAME="q queryid">-q QUERY-ID</A></H3>
<P>Fetches the relation/node with unique key value equal to query-id</P>
<P>Multiple arguments can be passed by specifying -q multple times</P>
<P>This flag should only be used when you want to query data</P>
<P>
<H3><A NAME="top nodename">-top NODE-NAME</A></H3>
<P>If this is specified in conjunction with <STRONG>-q</STRONG> or <STRONG>-qf</STRONG> then all the
query result nodes will be nested inside a node with this name (ie
this provides a root for the resulting document tree)</P>
<P>
<H3><A NAME="qf queryfile">-qf QUERY-FILE</A></H3>
<P>This is a file of newline-seperated IDs; this is useful for querying
the index in batch</P>
<P>
<H3><A NAME="keys">-keys</A></H3>
<P>This will write a list of all primary keys in the index</P>
<P>
<H3><A NAME="w writer">-w WRITER</A></H3>
<P>This format will be used to write the data; can be any stag format
(xml, sxpr, itext) - default XML.</P>
<P>Can also be a module that catches the incoming stag event stream and
does something with it (for example, this could be a module you write
yourself that transforms the stag events into HTML)</P>
<P>
<HR>
<H1><A NAME="see also">SEE ALSO</A></H1>
<P><A HREF="./Data/Stag.html">the Data::Stag manpage</A></P>
<P>For more complex stag to database mapping, see <A HREF="./DBIx/DBStag.html">the DBIx::DBStag manpage</A> and the
scripts</P>
<P><EM>stag-storenode.pl</EM></P>
<P><EM>selectall_xml</EM></P>
</BODY>
</HTML>