| 1 |
<HTML> |
| 2 |
<HEAD> |
| 3 |
<TITLE>stag-db</TITLE> |
| 4 |
<LINK REV="made" HREF="mailto:[email protected]"> |
| 5 |
</HEAD> |
| 6 |
|
| 7 |
<BODY> |
| 8 |
|
| 9 |
<A NAME="__index__"></A> |
| 10 |
<!-- INDEX BEGIN --> |
| 11 |
|
| 12 |
<UL> |
| 13 |
|
| 14 |
<LI><A HREF="#name">NAME</A></LI> |
| 15 |
<LI><A HREF="#synopsis">SYNOPSIS</A></LI> |
| 16 |
<LI><A HREF="#description">DESCRIPTION</A></LI> |
| 17 |
<UL> |
| 18 |
|
| 19 |
<LI><A HREF="#arguments">ARGUMENTS</A></LI> |
| 20 |
<UL> |
| 21 |
|
| 22 |
<LI><A HREF="#i indexfile">-i INDEXFILE</A></LI> |
| 23 |
<LI><A HREF="#r relationname">-r RELATION-NAME</A></LI> |
| 24 |
<LI><A HREF="#k uniquekey">-k UNIQUE-KEY</A></LI> |
| 25 |
<LI><A HREF="#u uniquekey">-u UNIQUE-KEY</A></LI> |
| 26 |
<LI><A HREF="#p parser">-p PARSER</A></LI> |
| 27 |
<LI><A HREF="#q queryid">-q QUERY-ID</A></LI> |
| 28 |
<LI><A HREF="#top nodename">-top NODE-NAME</A></LI> |
| 29 |
<LI><A HREF="#qf queryfile">-qf QUERY-FILE</A></LI> |
| 30 |
<LI><A HREF="#keys">-keys</A></LI> |
| 31 |
<LI><A HREF="#w writer">-w WRITER</A></LI> |
| 32 |
</UL> |
| 33 |
|
| 34 |
</UL> |
| 35 |
|
| 36 |
<LI><A HREF="#see also">SEE ALSO</A></LI> |
| 37 |
</UL> |
| 38 |
<!-- INDEX END --> |
| 39 |
|
| 40 |
<HR> |
| 41 |
<P> |
| 42 |
<H1><A NAME="name">NAME</A></H1> |
| 43 |
<P>stag-db.pl - persistent storage and retrieval for stag data (xml, sxpr, itext)</P> |
| 44 |
<P> |
| 45 |
<HR> |
| 46 |
<H1><A NAME="synopsis">SYNOPSIS</A></H1> |
| 47 |
<PRE> |
| 48 |
stag-db.pl -r person -k social_security_no -i ./person-idx myrecords.xml |
| 49 |
stag-db.pl -i ./person-idx -q 999-9999-9999 -q 888-8888-8888</PRE> |
| 50 |
<P> |
| 51 |
<HR> |
| 52 |
<H1><A NAME="description">DESCRIPTION</A></H1> |
| 53 |
<P>Builds a simple file-based database for persistent storage and |
| 54 |
retrieval of nodes from a stag compatible document.</P> |
| 55 |
<P>Imagine you have a very large file of data, in a stag compatible |
| 56 |
format such as XML. You want to index all the elements of type |
| 57 |
<STRONG>person</STRONG>; each person can be uniquely identified by |
| 58 |
<STRONG>social_security_no</STRONG>, which is a direct subnode of <STRONG>person</STRONG></P> |
| 59 |
<P>The first thing to do is to build an index file, which will be stored |
| 60 |
in your current directory:</P> |
| 61 |
<PRE> |
| 62 |
stag-db.pl -r person -k social_security_no -i ./person-idx myrecords.xml</PRE> |
| 63 |
<P>You can then use the index ``person-idx'' to retrieve <STRONG>person</STRONG> nodes by |
| 64 |
their social security number</P> |
| 65 |
<PRE> |
| 66 |
stag-db.pl -i ./person-idx -q 999-9999-9999 > some-person.xml</PRE> |
| 67 |
<P>You can export using different stag formats</P> |
| 68 |
<PRE> |
| 69 |
stag-db.pl -i ./person-idx -q 999-9999-9999 -w sxpr > some-person.xml</PRE> |
| 70 |
<P>You can retrieve multiple nodes (although these need to be rooted to |
| 71 |
make a valid file)</P> |
| 72 |
<PRE> |
| 73 |
stag-db.pl -i ./person-idx -q 999-9999-9999 -q 888-8888-8888 -top personset</PRE> |
| 74 |
<P>Or you can use a list of IDs from a file (newline delimited)</P> |
| 75 |
<PRE> |
| 76 |
stag-db.pl -i ./person-idx -qf my_ss_nmbrs.txt -top personset</PRE> |
| 77 |
<P> |
| 78 |
<H2><A NAME="arguments">ARGUMENTS</A></H2> |
| 79 |
<P> |
| 80 |
<H3><A NAME="i indexfile">-i INDEXFILE</A></H3> |
| 81 |
<P>This file will be used as the persistent index for storage/retrieval</P> |
| 82 |
<P> |
| 83 |
<H3><A NAME="r relationname">-r RELATION-NAME</A></H3> |
| 84 |
<P>This is the name of the stag node (XML element) that will be stored in |
| 85 |
the index; for example, with the XML below you may want to use the |
| 86 |
node name <STRONG>person</STRONG> and the unique key <STRONG>id</STRONG></P> |
| 87 |
<PRE> |
| 88 |
<person_set> |
| 89 |
<person> |
| 90 |
<id>...</id> |
| 91 |
</person> |
| 92 |
<person> |
| 93 |
<id>...</id> |
| 94 |
</person> |
| 95 |
... |
| 96 |
</person_set></PRE> |
| 97 |
<P>This flag should only be used when you want to store data</P> |
| 98 |
<P> |
| 99 |
<H3><A NAME="k uniquekey">-k UNIQUE-KEY</A></H3> |
| 100 |
<P>This node will be used as the unique/primary key for the data</P> |
| 101 |
<P>This node should be nested directly below the node that is being |
| 102 |
stored in the index - if it is more that one below, specify a path</P> |
| 103 |
<P>This flag should only be used when you want to store data</P> |
| 104 |
<P> |
| 105 |
<H3><A NAME="u uniquekey">-u UNIQUE-KEY</A></H3> |
| 106 |
<P>Synonym for <STRONG>-k</STRONG></P> |
| 107 |
<P> |
| 108 |
<H3><A NAME="p parser">-p PARSER</A></H3> |
| 109 |
<P>This can be the name of a stag supported format (xml, sxpr, itext) - |
| 110 |
XML is assumed by default</P> |
| 111 |
<P>It can also be a module name - this module is used to parse the input |
| 112 |
file into a stag stream; see <A HREF="./Data/Stag/BaseGenerator.html">the Data::Stag::BaseGenerator manpage</A> for details |
| 113 |
on writing your own parsers/event generators</P> |
| 114 |
<P>This flag should only be used when you want to store data</P> |
| 115 |
<P> |
| 116 |
<H3><A NAME="q queryid">-q QUERY-ID</A></H3> |
| 117 |
<P>Fetches the relation/node with unique key value equal to query-id</P> |
| 118 |
<P>Multiple arguments can be passed by specifying -q multple times</P> |
| 119 |
<P>This flag should only be used when you want to query data</P> |
| 120 |
<P> |
| 121 |
<H3><A NAME="top nodename">-top NODE-NAME</A></H3> |
| 122 |
<P>If this is specified in conjunction with <STRONG>-q</STRONG> or <STRONG>-qf</STRONG> then all the |
| 123 |
query result nodes will be nested inside a node with this name (ie |
| 124 |
this provides a root for the resulting document tree)</P> |
| 125 |
<P> |
| 126 |
<H3><A NAME="qf queryfile">-qf QUERY-FILE</A></H3> |
| 127 |
<P>This is a file of newline-seperated IDs; this is useful for querying |
| 128 |
the index in batch</P> |
| 129 |
<P> |
| 130 |
<H3><A NAME="keys">-keys</A></H3> |
| 131 |
<P>This will write a list of all primary keys in the index</P> |
| 132 |
<P> |
| 133 |
<H3><A NAME="w writer">-w WRITER</A></H3> |
| 134 |
<P>This format will be used to write the data; can be any stag format |
| 135 |
(xml, sxpr, itext) - default XML.</P> |
| 136 |
<P>Can also be a module that catches the incoming stag event stream and |
| 137 |
does something with it (for example, this could be a module you write |
| 138 |
yourself that transforms the stag events into HTML)</P> |
| 139 |
<P> |
| 140 |
<HR> |
| 141 |
<H1><A NAME="see also">SEE ALSO</A></H1> |
| 142 |
<P><A HREF="./Data/Stag.html">the Data::Stag manpage</A></P> |
| 143 |
<P>For more complex stag to database mapping, see <A HREF="./DBIx/DBStag.html">the DBIx::DBStag manpage</A> and the |
| 144 |
scripts</P> |
| 145 |
<P><EM>stag-storenode.pl</EM></P> |
| 146 |
<P><EM>selectall_xml</EM></P> |
| 147 |
|
| 148 |
</BODY> |
| 149 |
|
| 150 |
</HTML> |