Debian Codegraph @

homepage/script-docs/stag-db.html

raw
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 &gt; 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 &gt; 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 &lt;person_set&gt;
89 &lt;person&gt;
90 &lt;id&gt;...&lt;/id&gt;
91 &lt;/person&gt;
92 &lt;person&gt;
93 &lt;id&gt;...&lt;/id&gt;
94 &lt;/person&gt;
95 ...
96 &lt;/person_set&gt;</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>