1 <?xml version="1.0" standalone="no"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
5 <!ENTITY % local SYSTEM "local.ent">
7 <!ENTITY manref SYSTEM "manref.xml">
8 <!ENTITY gpl2 SYSTEM "gpl-2.0.xml">
9 <!ENTITY % idcommon SYSTEM "common/common.ent">
14 <title>MP-XQuery - User's Guide and Reference</title>
17 <firstname>Adam</firstname><surname>Dickmeiss</surname>
20 <releaseinfo>&version;</releaseinfo>
22 <year>2014-2015</year>
23 <holder>Index Data</holder>
27 This manual is part of MP-XQuery version &version;.
30 MP-XQuery is a Metaproxy module that allows record conversion
31 using W3C's XQuery language.
34 MP-XQuery is covered by the GNU General Public License version 2.
39 <imagedata fileref="common/id.png" format="PNG"/>
42 <imagedata fileref="common/id.eps" format="EPS"/>
48 <chapter id="introduction">
49 <title>Introduction</title>
51 MP-XQuery is a <ulink url="&url.metaproxy;">Metaproxy</ulink> module
52 that allows record conversion using
53 <ulink url="http://www.w3.org/TR/xquery/">W3C XML XQuery</ulink>.
54 The initial motivations for the module was to be able to
55 <ulink url="http://bibframe.org">BIBFRAME</ulink> records
56 via SRU/Z39.50. By using the
58 url="https://github.com/lcnetdev/marc2bibframe">
60 </ulink> utilities, this module can convert existing
61 MARCXML records to BIBFRAME records - on the fly - as part of retrieval.
64 <chapter id="installation">
65 <title>Installation</title>
67 MP-XQuery is available as packages for CentOS/RHEL 6 and most recent
68 Ubuntu/Debian versions. For other systems, the module must be build
71 <sect1 id="installation.packages">
72 <title>Installing packages</title>
74 You need to enable the relevant software repositories.
75 For setting up refer to one of:
77 url="http://ftp.indexdata.dk/pub/mp-xquery/redhat/centos/6/README">CentOS 6</ulink>
80 url="http://ftp.indexdata.dk/pub/mp-xquery/redhat/centos/7/README">CentOS 7</ulink>
83 url="http://ftp.indexdata.dk/pub/mp-xquery/ubuntu/README">Ubuntu</ulink>
86 url="http://ftp.indexdata.dk/pub/mp-xquery/debian/README">Debian</ulink>
89 The package is called <literal>mp-xquery</literal> on RHEL/Debian systems.
90 Install that package and you are ready to use filter "xquery" in your
94 <sect1 id="installation.source">
95 <title>Installing from source</title>
97 To build from source, you need zorba and metaproxy development
98 packages. <ulink url="http://www.zorba.io">Zorba</ulink>
99 might be installed in <filename>/opt/zorba</filename> as follows:
101 tar zxf zorba-3.0.tar.gz
106 -D CMAKE_INSTALL_PREFIX=/opt/zorba \
107 -D ZORBA_SUPPRESS_SWIG:BOOL=ON \
111 Consult the Zorba documentation for more information.
114 Some parts of Zorba require C++ 11 features. If the local C++
115 compiler does not offer this by default, you might have to add:
117 -D CMAKE_CXX_FLAGS=-std=c++11
119 to the cmake invokation. This is the case on MAC OS X with MacPorts.
122 Metaproxy can be installed as follows:
128 But consult the Metaproxy documentation for requirements and
132 We are now ready to build the MP-XQuery module with:
135 make ZORBA=/opt/zorba MP_CONFIG=/usr/local/bin/mp-config
137 Adjust <literal>ZORBA</literal> and <literal>MP_CONFIG</literal> values
138 above for the correct location of installed
139 Zorba and Metaproxy's mp-config respectively. MP_CONFIG can be omitted
140 if Metaproxy was installed in the system PATH.
143 You can now install the <filename>metaproxy_filter_xquery.so</filename>
144 in a directory searched by Metaproxy daemon.
145 Specifically, that's the directories
146 given by the <literal>dlpath</literal> configuration.
149 If dlpath includes <filename>/usr/lib/metaproxy6/modules</filename>,
150 the module can be installed with:
152 cp src/metaproxy_filter_xquery.so /usr/lib/metaproxy6/modules
157 For RHEL/CentOS systems on 64-bit architectures, the correct paths is:
158 <filename>/usr/lib64/metaproxy6/modules</filename>.
163 <title>BIBFRAME</title>
165 The MARC to BIBFRAME was the primary purpose of the XQuery
166 module for Metaproxy, but generally the module is a just an alternative
167 to record_transform filter of Metaproxy which primarily performs XSLT.
170 The <filename>bibframe directory</filename> of the source tar
171 contains sample file for performing MARC to BIBFRAME conversions.
172 Upon <literal>make install</literal> these are installed to directory
173 <filename>/usr/share/mp-xquery/bibframe</filename> and they are also
174 part of the package <literal>mp-xquery</literal>.
177 <literal>config.xml</literal> is a complete Metaproxy configuration file.
178 It includes a standalone configuration that makes Metaproxy offe
179 Z39.50 and SRU support on port 9070. The modules in use are http_file
180 (to serve XSL files), sru_z3950 (SRU service), cql_rpn (CQL to RPN
181 conversion), xquery (to convert MARCXML to BIBFRAME), record_transform
182 (to convert MARC21 to MARCXML), virt_db (for database rewrite), log
183 (to perform backend logging) and, finally, z3950_client to interface
187 It is important that the XQuery module comes before the
188 "record_transform" so that the XQuery module sees XML
189 <emphasis>only</emphasis> and not ISO2709-records.
190 If it does, they will be ignored (passed through) by the XQuery module.
193 The XQuery module script name points to the full path of
194 <filename>zorba3-0.xqy</filename> part
195 of marc2bibframe . Do not move <filename>zorba3-0.xqy</filename>
196 from its place within the
197 marc2bibframe directory as other files are referred to and their relative
198 location must be preserved.
201 File <filename>cql2pqf.txt</filename> contains a simple DC/CQL profile
202 for driving a CQL to RPN conversion.
203 It is referred to from the cql_rpn filter in config.xml .
206 File <filename>explain.xml</filename> is SRU explain configuration.
207 It is referred to from the sru_z3950 filter in config.xml .
210 Directory <filename>xsl/..</filename> is client side XSL for brief -
211 and full display. These must be located so that the http_file filter
212 can fetch them. For example, if these files are located in
213 <filename>/usr/share/mp-xquery/bibframe/xsl</filename> , then
216 <filter type="http_file">
218 <documentroot>/usr/share/mp-xquery/bibframe/xsl</documentroot>
220 <passthru>true</passthru>
228 Do not modify the files below <filename>/usr/share/mp-xquery</filename>.
229 They will be overwritten by a package update and if
230 <literal>make install</literal> is executed.
231 Use them if they can be used as-is but copy them away if you want to
232 modify them (such as <filename>config.xml</filename>).
237 <reference id="reference">
238 <title>Reference</title>
239 <partintro id="reference-introduction">
241 The material in this chapter is drawn directly from the individual
248 <appendix id="license">
249 <title>License</title>
251 Copyright (C) 2014-2015 Index Data
255 Metaproxy is free software; you can redistribute it and/or modify it under
256 the terms of the GNU General Public License as published by the Free
257 Software Foundation; either version 2, or (at your option) any later
262 Metaproxy is distributed in the hope that it will be useful, but WITHOUT ANY
263 WARRANTY; without even the implied warranty of MERCHANTABILITY or
264 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
269 You should have received a copy of the GNU General Public License
270 along with Metaproxy; see the file LICENSE. If not, write to the
271 Free Software Foundation,
272 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
280 <!-- Keep this comment at the end of the file