--- /dev/null
+<chapter id="tutorial">
+ <!-- $Id: tutorial.xml,v 1.1 2008-02-01 13:54:39 marc Exp $ -->
+ <title>Tutorial</title>
+
+
+ <sect1 id="tutorial-oai">
+ <title>A first &acro.oai; indexing example</title>
+
+ <para>
+ In this section, we will test the system by indexing a small set of
+ sample &acro.oai; records that are included with the &zebra; distribution,
+ running a &zebra; server against the newly created database, and
+ searching the indexes with a client that connects to that server.
+ </para>
+ <para>
+ Go to the <literal>examples/oai-pmh</literal> subdirectory of the
+ distribution archive, or make a deep copy of the Debian installation
+ directory
+ <literal>/usr/share/idzebra-2.0.-examples/oai-pmh</literal>.
+ An XML file containing multiple &acro.oai;
+ records is located in the sub
+ directory <literal>examples/oai-pmh/data</literal>. To index these, type:
+ <screen>
+ zebraidx -c conf/zebra.cfg init
+ zebraidx -c conf/zebra.cfg update data/oai-caltech.xml
+ zebraidx -c conf/zebra.cfg commit
+ </screen>
+ In case you have not installed zebra yet but have compiled the
+ binaries from this tarball, use the following command form:
+ <screen>
+ ../../index/zebraidx -c conf/zebra.cfg this and that
+ </screen>
+ </para>
+
+ <para>
+ In this command, the word <literal>update</literal> is followed
+ by the name of a directory: <literal>zebraidx</literal> updates all
+ files in the hierarchy rooted at that directory. The command option
+ <literal>-c conf/zebra.cfg</literal> points to the proper
+ configuration file.
+ </para>
+
+ <para>
+ You might ask yourself how &acro.xml; content is indexed using &acro.xslt;
+ stylesheets: to satisfy your curiosity, you might want to run the
+ indexing transformation on an example debugging &acro.oai; record.
+ <screen>
+ xsltproc conf/oai2index.xsl data/debug-record.xml
+ </screen>
+ Here you see the &acro.oai; record transformed into the indexing
+ &acro.xml; format. &zebra; is creating several inverted indexes,
+ and their name and type are clearly visible in the indexing
+ &acro.xml; format.
+ </para>
+
+ <para>
+ If your indexing command was successful, you are now ready to
+ fire up a server. To start a server on port 9999, type:
+ <screen>
+ zebrasrv -c conf/zebra.cfg @:9999
+ </screen>
+ </para>
+
+ <para>
+ The &zebra; index that you have just created has a single database
+ named <literal>Default</literal>.
+ The database contains several &acro.oai; records, and the server will
+ return records in the &acro.xml; format only. The indexing machine
+ di the splitting into individual records just behind the scenes.
+ </para>
+
+ <para>
+ To test the server, you can use any &acro.z3950; client.
+ For instance, you can use the demo command-line client that comes
+ with &yaz;; we start the SRU/SRW/Z39.50 server in PQF mode only:
+ </para>
+ <para>
+ <screen>
+ yaz-client localhost:9999
+ </screen>
+ </para>
+
+ <para>
+ When the client has connected, you can type:
+ </para>
+
+ <para>
+ <screen>
+ Z> format xml
+ Z> elements oai
+ Z> find the
+ Z> show 1+1
+ </screen>
+ </para>
+
+<!--
+
+Z39.50 presents using presentation stylesheets:
+
+ Z> elements dc
+ Z> show 2+1
+
+ Z> elements zebra
+ Z> show 3+1
+
+
+Z39.50 buildin Zebra presents (in this configuration only if
+ started without yaz-frontendserver):
+
+ Z> elements zebra::meta
+ Z> show 4+1
+
+ Z> elements zebra::meta::sysno
+ Z> show 5+1
+
+ Z> format sutrs
+ Z> show 5+1
+ Z> format xml
+
+ Z> elements zebra::index
+ Z> show 6+1
+
+ Z> elements zebra::snippet
+ Z> show 7+1
+
+ Z> elements zebra::facet::any:w
+ Z> show 8+1
+
+ Z> elements zebra::facet::any:w,dc_title:w
+ Z> show 9+1
+
+
+
+Z39.50 searches targeted at specific indexes
+
+ Z> elements zebra
+ Z> find @attr 1=oai_identifier @attr 4=3 oai:caltechcstr.library.caltech.edu:4
+ Z> show 1+1
+
+ Z> find @attr 1=oai_datestamp @attr 4=3 2001-04-20
+ Z> show 1+1
+
+ Z> find @attr 1=oai_setspec @attr 4=3 7374617475733D756E707562
+ Z> show 1+1
+
+ Z> find @attr 1=dc_title communication
+ Z> show 1+1
+
+ Z> find @attr 1=dc_identifier @attr 4=3
+ http://resolver.caltech.edu/CaltechCSTR:1986.5228-tr-86
+ Z> show 1+1
+
+ etc, etc.
+
+ Notice that all indexes defined by 'type="0"' in the
+ indexing style sheet must be searched using the '@attr 4=3'
+ structure attribute instruction.
+
+ Notice also that searching and scan on indexes
+ 'dc_contributor', 'dc_language', 'dc_rights', and 'dc_source'
+ fails, simply because none of the records in this example set
+ have these fields set, and consequently, these indexes are
+ _not_ created.
+
+
+XXXXXXXX
+
+
+Z39.50 scan:
+
+ yaz-client localhost:9999
+ Z> format xml
+ Z> querytype prefix
+ Z> scan @attr 1=oai_identifier @attr 4=3 oai
+ Z> scan @attr 1=oai_datestamp @attr 4=3 1
+ Z> scan @attr 1=oai_setspec @attr 4=3 2000
+ Z>
+ Z> scan @attr 1=dc_title communication
+ Z> scan @attr 1=dc_identifier @attr 4=3 a
+
+ etc, etc,
+
+
+Z39.50 search using server-side CQL conversion:
+
+ Z> format xml
+ Z> querytype cql
+ Z> elements dc
+ Z>
+ Z> find harry
+ Z>
+ Z> find creator = the
+ Z> find dc.creator = the
+ Z> find title = the
+ Z>
+ Z> find description < the
+ Z> find title le some
+ Z> find title ge some
+ Z> find title > some
+ Z>
+ Z> find identifier eq
+ "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
+ Z> find relation eq something
+
+
+ etc, etc. Notice that all indexes defined by 'type="0"' in the
+ indexing style sheet must be searched using the 'eq'
+ relation.
+
+ Z> find title <> and
+
+ fails as well. ???
+
+
+Z39.50 scan using server side CQL conversion:
+
+ Unfortunately, this will _never_ work as it is not supported by the
+ Z39.50 standard.
+ If you want to use scan using server side CQL conversion, you need to
+ make an SRW connection using yaz-client, or a
+ SRU connection using REST Web Services - any browser will do.
+
+
+SRU Explain ZeeRex response:
+
+ http://localhost:9999/
+ http://localhost:9999/?version=1.1&operation=explain
+
+
+SRU Search Retrieve records:
+
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &query=creator=adam
+
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &query=date=1978-01-01
+ &startRecord=1&maximumRecords=1&recordSchema=dc
+
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &query=dc.title=the
+
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &query=description=the
+
+
+ relation tests:
+
+ http://localhost:9999/?version=1.1&operation=searchRetrieve
+ &query=title%3Cthe
+
+
+SRU scan:
+
+ http://localhost:9999/?version=1.1&operation=scan&scanClause=title=a
+ http://localhost:9999/?version=1.1&operation=scan
+ &scanClause=identifier%20eq%20a
+
+ Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
+
+
+
+SRW explain with CQL index points:
+
+ Z> open http://localhost:9999
+ Z> explain
+
+ Notice: when opening a connection using the 'http.//' prefix, yaz-client
+ uses SRW SOAP connections, and 'form xml' and 'querytype cql' are
+ implicitely set.
+
+
+SRW search using implicit server side CQL:
+
+ Z> open http://localhost:9999
+ Z> find identifier eq
+ "http://resolver.caltech.edu/CaltechCSTR:1978.2276-tr-78"
+ Z> find description < the
+
+
+ In SRW connection mode, the follwing fails due to problem in yaz-client:
+ Z> elements dc
+ Z> s 1+1
+
+
+SRW scan using implicit server side CQL:
+
+ yaz-client http://localhost:9999
+ Z> scan title = communication
+ Z> scan identifier eq a
+
+ Notice: you need to use the 'eq' relation for all @attr 4=3 indexes
+
+
+
+
+-->
+
+
+<!--
+
+ <para>
+ The default retrieval syntax for the client is &acro.usmarc;, and the
+ default element set is <literal>F</literal> (``full record''). To
+ try other formats and element sets for the same record, try:
+ </para>
+ <para>
+ <screen>
+ Z>format sutrs
+ Z>show 1
+ Z>format grs-1
+ Z>show 1
+ Z>format xml
+ Z>show 1
+ Z>elements B
+ Z>show 1
+ </screen>
+ </para>
+
+ <note>
+ <para>You may notice that more fields are returned when your
+ client requests &acro.sutrs;, &acro.grs1; or &acro.xml; records.
+ This is normal - not all of the GILS data elements have mappings in
+ the &acro.usmarc; record format.
+ </para>
+ </note>
+
+ <para>
+ If you've made it this far, you know that your installation is
+ working, but there's a certain amount of voodoo going on - for
+ example, the mysterious incantations in the
+ <literal>zebra.cfg</literal> file. In order to help us understand
+ these fully, the next chapter will work through a series of
+ increasingly complex example configurations.
+ </para>
+
+
+-->
+
+ </sect1>
+
+ <sect1 id="tutorial-oai-zebra">
+ <title>Requesting &acro.oai; records in &zebra; specific formats</title>
+
+
+ </sect1>
+
+
+</chapter>
+
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ sgml-parent-document: "zebra.xml"
+ sgml-local-catalogs: nil
+ sgml-namecase-general:t
+ End:
+ -->
projects / idzebra-moved-to-github.git / commitdiff