doc/zoom.xml

   1 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.4//EN"
   2     "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
   3  <!ENTITY copyright SYSTEM "copyright.xml">
   4  <!ENTITY % idcommon SYSTEM "common/common.ent">
   5      %idcommon;
   6 ]>
   7 <refentry id="ref-zoom">
   8  <refentryinfo>
   9   <productname>Metaproxy</productname>
  10   <info><orgname>Index Data</orgname></info>
  11  </refentryinfo>
  12
  13  <refmeta>
  14   <refentrytitle>zoom</refentrytitle>
  15   <manvolnum>3mp</manvolnum>
  16   <refmiscinfo class="manual">Metaproxy Module</refmiscinfo>
  17  </refmeta>
  18
  19  <refnamediv>
  20   <refname>zoom</refname>
  21   <refpurpose>Metaproxy ZOOM Module</refpurpose>
  22  </refnamediv>
  23
  24  <refsect1>
  25   <title>DESCRIPTION</title>
  26   <para>
  27    This filter implements a generic client based on
  28    <ulink url="&url.yaz.zoom;">ZOOM</ulink> of YAZ.
  29    The client implements the protocols that ZOOM C does: Z39.50, SRU
  30    (GET, POST, SOAP) and SOLR .
  31   </para>
  32
  33   <para>
  34    This filter only deals with Z39.50 on input. The following services
  35    are supported: init, search, present and close. The backend target
  36    is selected based on the database as part search and
  37    <emphasis>not</emphasis> as part of init.
  38   </para>
  39
  40   <para>
  41    This filter is an alternative to the z3950_client filter but also
  42    shares properties of the virt_db - in that the target is selected
  43    for a specific database
  44   </para>
  45
  46   <para>
  47    The ZOOM filter relies on a target profile description, which is
  48    XML based. It picks the profile for a given database from a web service
  49    or it may be locally given for each unique database (AKA virtual database
  50    in virt_db). Target profiles are directly and indrectly given as part
  51    of the <literal>torus</literal> element in the configuration.
  52   </para>
  53
  54  </refsect1>
  55
  56  <refsect1>
  57   <title>CONFIGURATION</title>
  58   <para>
  59    The configuration consists of six parts: <literal>torus</literal>,
  60    <literal>fieldmap</literal>, <literal>cclmap</literal>,
  61    <literal>contentProxy</literal>, <literal>log</literal>
  62    and <literal>zoom</literal>.
  63   </para>
  64   <refsect2>
  65    <title>torus</title>
  66    <para>
  67     The <literal>torus</literal> element specifies target profiles
  68     and takes the following content:
  69    </para>
  70    <variablelist>
  71     <varlistentry>
  72      <term>attribute <literal>url</literal></term>
  73      <listitem>
  74       <para>
  75        URL of Web service to be used when fetch target profiles from
  76        a remote service (Torus normally).
  77       </para>
  78       <para>
  79        The sequence <literal>%query</literal> is replaced with a CQL
  80        query for the Torus search.
  81       </para>
  82       <para>
  83        The special sequence <literal>%realm</literal> is replaced by value
  84        of attribute <literal>realm</literal> or by realm DATABASE argument.
  85       </para>
  86       <para>
  87        The special sequence <literal>%db</literal> is replaced with
  88        a single database while searching. Note that this sequence
  89        is no longer needed, because the <literal>%query</literal> can already
  90        query for a single database by using CQL query
  91        <literal>udb==...</literal>.
  92       </para>
  93      </listitem>
  94     </varlistentry>
  95     <varlistentry>
  96      <term>attribute <literal>content_url</literal></term>
  97      <listitem>
  98       <para>
  99        URL of Web service to be used to fetch target profile
 100        for a given database (udb) of type content. Semantics otherwise like
 101        <literal>url</literal> attribute above.
 102       </para>
 103      </listitem>
 104     </varlistentry>
 105     <varlistentry id="auth_url">
 106      <term>attribute <literal>auth_url</literal></term>
 107      <listitem>
 108       <para>
 109        URL of Web service to be used to for auth/IP lookup. If this
 110        defined, all access is granted or denied as part of Z39.50 Init
 111        by the ZOOM module and the use of database parameters realm and
 112        torus_url is not allowed. If this setting is not defined,
 113        all access is allowed and realm and/or torus_url may be used.
 114       </para>
 115      </listitem>
 116     </varlistentry>
 117     <varlistentry>
 118       <term>attribute <literal>realm</literal></term>
 119       <listitem>
 120         <para>
 121          The default realm value. Used for %realm in URL, unless
 122          specified in DATABASE parameter.
 123         </para>
 124       </listitem>
 125     </varlistentry>
 126     <varlistentry>
 127      <term>attribute <literal>proxy</literal></term>
 128      <listitem>
 129       <para>
 130        HTTP proxy to bse used for fetching target profiles.
 131       </para>
 132      </listitem>
 133     </varlistentry>
 134     <varlistentry>
 135      <term>attribute <literal>xsldir</literal></term>
 136      <listitem>
 137       <para>
 138        Directory that is searched for XSL stylesheets. Stylesheets
 139        are specified in the target profile by the
 140        <literal>transform</literal> element.
 141       </para>
 142      </listitem>
 143     </varlistentry>
 144     <varlistentry>
 145      <term>attribute <literal>element_transform</literal></term>
 146      <listitem>
 147       <para>
 148        Specifies the element that triggers retrieval and transform using
 149        the parameters elementSet, recordEncoding, requestSyntax, transform
 150        from the target profile. Default value
 151        is "pz2", due to the fact that for historical reasons the
 152        common format is that used in Pazpar2.
 153       </para>
 154      </listitem>
 155     </varlistentry>
 156     <varlistentry>
 157      <term>attribute <literal>element_raw</literal></term>
 158      <listitem>
 159       <para>
 160        Specifies an element that triggers retrieval using the
 161        parameters elementSet, recordEncoding, requestSyntax from the
 162        target profile. Same actions as for element_transform, but without
 163        the XSL transform. Useful for debugging.
 164        The default value is "raw".
 165       </para>
 166      </listitem>
 167     </varlistentry>
 168     <varlistentry>
 169      <term>attribute <literal>explain_xsl</literal></term>
 170      <listitem>
 171       <para>
 172        Specifies a stylesheet that converts one or more Torus records
 173        to ZeeExplain records. The content of recordData is assumed to be
 174        holding each Explain record.
 175       </para>
 176      </listitem>
 177     </varlistentry>
 178     <varlistentry>
 179      <term>attribute <literal>record_xsl</literal></term>
 180      <listitem>
 181       <para>
 182        Specifies a stylesheet that converts retrieval records after
 183        transform/literal operations.
 184       </para>
 185       <para>
 186        When Metaproxy creates a content proxy session, the XSL parameter
 187        <literal>cproxyhost</literal> is passed to the transform.
 188       </para>
 189      </listitem>
 190     </varlistentry>
 191     <varlistentry>
 192      <term>element <literal>records</literal></term>
 193      <listitem>
 194       <para>
 195        Local target profiles. This element may includes zero or
 196        more <literal>record</literal> elements (one per target
 197        profile). See section TARGET PROFILE.
 198       </para>
 199      </listitem>
 200     </varlistentry>
 201    </variablelist>
 202   </refsect2>
 203   <refsect2 id="fieldmap">
 204    <title>fieldmap</title>
 205    <para>
 206     The <literal>fieldmap</literal> may be specified zero or more times and
 207     specifies the map from CQL fields to CCL fields and takes the
 208     following content:
 209    </para>
 210    <variablelist>
 211     <varlistentry>
 212      <term>attribute <literal>cql</literal></term>
 213      <listitem>
 214       <para>
 215        CQL field that we are mapping "from".
 216       </para>
 217      </listitem>
 218     </varlistentry>
 219     <varlistentry>
 220      <term>attribute <literal>ccl</literal></term>
 221      <listitem>
 222       <para>
 223        CCL field that we are mapping "to".
 224       </para>
 225      </listitem>
 226     </varlistentry>
 227    </variablelist>
 228   </refsect2>
 229   <refsect2 id="cclmap_base">
 230    <title>cclmap</title>
 231    <para>
 232     The third part of the configuration consists of zero or more
 233     <literal>cclmap</literal> elements that specifies
 234     <emphasis>base</emphasis> CCL profile to be used for all targets.
 235     This configuration, thus, will be combined with cclmap-definitions
 236     from the target profile.
 237    </para>
 238   </refsect2>
 239   <refsect2>
 240    <title>contentProxy</title>
 241    <para>
 242     The <literal>contentProxy</literal> element controls content proxy'in.
 243     This section
 244     is optional and must only be defined if content proxy'ing is enabled.
 245    </para>
 246    <variablelist>
 247     <varlistentry>
 248      <term>attribute <literal>config_file</literal></term>
 249      <listitem>
 250       <para>
 251        Specifies the file that configures the cf-proxy system. Metaproxy
 252        uses setting <literal>sessiondir</literal> and
 253        <literal>proxyhostname</literal> from that file to configure
 254        name of proxy host and directory of parameter files for the cf-proxy.
 255       </para>
 256      </listitem>
 257     </varlistentry>
 258     <varlistentry>
 259      <term>attribute <literal>server</literal></term>
 260      <listitem>
 261       <para>
 262        Specifies the content proxy host. The host is of the form
 263        host[:port]. That is without a method (such as HTTP) and optional
 264        port number.
 265       </para>
 266       <note>
 267        <para>
 268         This setting is deprecated. Use the config_file (above)
 269         to inform about the proxy server.
 270        </para>
 271       </note>
 272      </listitem>
 273     </varlistentry>
 274     <varlistentry>
 275      <term>attribute <literal>tmp_file</literal></term>
 276      <listitem>
 277       <para>
 278        Specifies a filename of a session file for content proxy'ing. The
 279        file should be an absolute filename that includes
 280        <literal>XXXXXX</literal> which is replaced by a unique filename
 281        using the mkstemp(3) system call. The default value of this
 282        setting is <literal>/tmp/cf.XXXXXX.p</literal>.
 283       </para>
 284       <note>
 285        <para>
 286         This setting is deprecated. Use the config_file (above)
 287         to inform about the session file area.
 288        </para>
 289       </note>
 290      </listitem>
 291     </varlistentry>
 292    </variablelist>
 293   </refsect2>
 294   <refsect2>
 295    <title>log</title>
 296    <para>
 297     The <literal>log</literal> element controls logging for the
 298     ZOOM filter.
 299    </para>
 300    <variablelist>
 301     <varlistentry>
 302      <term>attribute <literal>apdu</literal></term>
 303      <listitem>
 304       <para>
 305        If the value of apdu is "true", then protocol packages
 306        (APDUs and HTTP packages) from the ZOOM filter will be
 307        logged to the yaz_log system. A value of "false" will
 308        not perform logging of protocol packages (the default
 309        behavior).
 310       </para>
 311      </listitem>
 312     </varlistentry>
 313    </variablelist>
 314   </refsect2>
 315
 316   <refsect2>
 317    <title>zoom</title>
 318    <para>
 319     The <literal>zoom</literal> element controls settings for the
 320     ZOOM.
 321    </para>
 322    <variablelist>
 323     <varlistentry>
 324      <term>attribute <literal>timeout</literal></term>
 325      <listitem>
 326       <para>
 327        Is an integer that specifies, in seconds, how long an operation
 328        may take before ZOOM gives up. Default value is 40.
 329       </para>
 330      </listitem>
 331     </varlistentry>
 332     <varlistentry>
 333      <term>attribute <literal>proxy_timeout</literal></term>
 334      <listitem>
 335       <para>
 336        Is an integer that specifies, in seconds, how long an operation
 337        a proxy check will wait before giving up. Default value is 1.
 338       </para>
 339      </listitem>
 340     </varlistentry>
 341    </variablelist>
 342   </refsect2>
 343
 344  </refsect1>
 345  <refsect1>
 346   <title>QUERY HANDLING</title>
 347   <para>
 348    The ZOOM filter accepts three query types: RPN(Type-1), CCL and
 349    CQL.
 350   </para>
 351   <para>
 352    Queries are converted in two separate steps. In the first step
 353    the input query is converted to RPN/Type-1. This is always
 354    the common internal format between step 1 and step 2.
 355    In step 2 the query is converted to the native query type of the target.
 356   </para>
 357   <para>
 358    Step 1: for RPN, the query is passed un-modified to the target.
 359   </para>
 360   <para>
 361    Step 1: for CCL, the query is converted to RPN via
 362    <link linkend="cclmap"><literal>cclmap</literal></link> elements part of
 363    the target profile as well as
 364    <link linkend="cclmap_base">base CCL maps</link>.
 365   </para>
 366   <para>
 367    Step 1: For CQL, the query is converted to CCL. The mappings of
 368    CQL fields to CCL fields are handled by
 369    <link linkend="fieldmap"><literal>fieldmap</literal></link>
 370    elements as part of the target profile. The resulting query, CCL,
 371    is the converted to RPN using the schema mentioned earlier (via
 372    <literal>cclmap</literal>).
 373   </para>
 374   <para>
 375    Step 2: If the target is Z39.50-based, it is passed verbatim (RPN).
 376    If the target is SRU-based, the RPN will be converted to CQL.
 377    If the target is SOLR-based, the RPN will be converted to SOLR's query
 378    type.
 379   </para>
 380  </refsect1>
 381
 382  <refsect1>
 383   <title>SORTING</title>
 384   <para>
 385    The ZOOM module actively handle CQL sorting - using the SORTBY parameter
 386    which was introduced in SRU version 1.2. The conversion from SORTBY clause
 387    to native sort for some target is driven by the two parameters:
 388    <link linkend="sortStrategy"><literal>sortStrategy</literal></link>
 389    and <link linkend="sortmap"><literal>sortmap_</literal><replaceable>field</replaceable></link>.
 390   </para>
 391   <para>
 392    If a sort field that does not have an equivalent
 393    <literal>sortmap_</literal>-mapping is passed un-modified through the
 394    conversion. It doesn't throw a diagnostic.
 395   </para>
 396  </refsect1>
 397
 398  <refsect1>
 399   <title>TARGET PROFILE</title>
 400   <para>
 401    The ZOOM module is driven by a number of settings that specifies how
 402    to handle each target.
 403    Note that unknown elements are silently <emphasis>ignored</emphasis>.
 404   </para>
 405   <para>
 406    The elements, in alphabetical order, are:
 407   </para>
 408   <variablelist>
 409    <varlistentry>
 410     <term id="zoom-torus-authentication">authentication</term><listitem>
 411     <para>
 412      Authentication parameters to be sent to the target. For
 413      Z39.50 targets, this will be sent as part of the
 414      Init Request. Authentication consists of two components: username
 415      and password, separated by a slash.
 416     </para>
 417     <para>
 418      If this value is omitted or empty no authentication information is sent.
 419     </para>
 420    </listitem>
 421    </varlistentry>
 422
 423    <varlistentry id="cclmap">
 424     <term>cclmap_<replaceable>field</replaceable></term><listitem>
 425     <para>
 426      This value specifies CCL field (qualifier) definition for some
 427      field. For Z39.50 targets this most likely will specify the
 428      mapping to a numeric use attribute + a structure attribute.
 429      For SRU targets, the use attribute should be string based, in
 430      order to make the RPN to CQL conversion work properly (step 2).
 431     </para>
 432    </listitem>
 433    </varlistentry>
 434
 435    <varlistentry>
 436     <term>cfAuth</term><listitem>
 437     <para>
 438      When cfAuth is defined, its value will be used as authentication
 439      to backend target and authentication setting will be specified
 440      as part of a database. This is like a "proxy" for authentication and
 441      is used for Connector Framework based targets.
 442     </para>
 443    </listitem>
 444    </varlistentry>
 445
 446    <varlistentry>
 447     <term id="zoom-torus-cfproxy">cfProxy</term><listitem>
 448     <para>
 449      Specifies HTTP proxy for the target in the form
 450      <replaceable>host</replaceable>:<replaceable>port</replaceable>.
 451     </para>
 452    </listitem>
 453    </varlistentry>
 454
 455    <varlistentry>
 456     <term>cfSubDB</term><listitem>
 457     <para>
 458      Specifies sub database for a Connector Framework based target.
 459     </para>
 460    </listitem>
 461    </varlistentry>
 462
 463    <varlistentry id="zoom-torus-contentConnector">
 464     <term>contentConnector</term><listitem>
 465     <para>
 466      Specifies a database for content-based proxy'ing.
 467     </para>
 468    </listitem>
 469    </varlistentry>
 470
 471    <varlistentry>
 472     <term>elementSet</term><listitem>
 473     <para>
 474      Specifies the elementSet to be sent to the target if record
 475      transform is enabled (not to be confused' with the record_transform
 476      module). The record transform is enabled only if the client uses
 477      record syntax = XML and a element set determined by
 478      the <literal>element_transform</literal> /
 479      <literal>element_raw</literal> from the configuration.
 480      By default that is the element sets <literal>pz2</literal>
 481      and <literal>raw</literal>.
 482      If record transform is not enabled, this setting is
 483      not used and the element set specified by the client
 484      is passed verbatim.
 485     </para>
 486    </listitem>
 487    </varlistentry>
 488
 489    <varlistentry>
 490     <term>literalTransform</term><listitem>
 491     <para>
 492      Specifies a XSL stylesheet to be used if record
 493      transform is anabled; see description of elementSet.
 494      The XSL transform is only used if the element set is set to the
 495      value of <literal>element_transform</literal> in the configuration.
 496     </para>
 497     <para>
 498      The value of literalTransform is the XSL - string encoded.
 499     </para>
 500    </listitem>
 501    </varlistentry>
 502
 503    <varlistentry>
 504     <term>piggyback</term><listitem>
 505     <para>
 506      A value of 1/true is a hint to the ZOOM module that this Z39.50
 507      target supports piggyback searches, ie Search Response with
 508      records. Any other value (false) will prevent the ZOOM module
 509      to make use of piggyback (all records part of Present Response).
 510     </para>
 511    </listitem>
 512    </varlistentry>
 513
 514    <varlistentry>
 515     <term>queryEncoding</term><listitem>
 516     <para>
 517      If this value is defined, all queries will be converted
 518      to this encoding. This should be used for all Z39.50 targets that
 519      do not use UTF-8 for query terms.
 520     </para>
 521    </listitem>
 522    </varlistentry>
 523
 524    <varlistentry>
 525     <term>recordEncoding</term><listitem>
 526     <para>
 527      Specifies the character encoding of records that are returned
 528      by the target. This is primarily used for targets were records
 529      are not UTF-8 encoded already. This setting is only used
 530      if the record transform is enabled (see description of elementSet).
 531     </para>
 532    </listitem>
 533    </varlistentry>
 534
 535    <varlistentry>
 536     <term>requestSyntax</term><listitem>
 537     <para>
 538      Specifies the record syntax to be specified for the target
 539      if record transform is enabled; see description of elementSet.
 540      If record transform is not enabled, the record syntax of the
 541      client is passed verbatim to the target.
 542     </para>
 543    </listitem>
 544    </varlistentry>
 545
 546    <varlistentry id="sortmap">
 547     <term>sortmap_<replaceable>field</replaceable></term><listitem>
 548     <para>
 549      This value the native field for a target. The form of the value is
 550      given by <link linkend="sortStrategy">sortStrategy</link>.
 551     </para>
 552    </listitem>
 553    </varlistentry>
 554
 555    <varlistentry id="sortStrategy">
 556     <term>sortStrategy</term><listitem>
 557     <para>
 558      Specifies sort strategy for a target. One of:
 559      <literal>z3950</literal>, <literal>type7</literal>,
 560      <literal>cql</literal>, <literal>sru11</literal> or
 561      <literal>embed</literal>. The <literal>embed</literal> chooses type-7
 562      or CQL sortby depending on whether Type-1 or CQL is
 563      actually sent to the target.
 564     </para>
 565    </listitem>
 566    </varlistentry>
 567
 568    <varlistentry>
 569     <term>sru</term><listitem>
 570     <para>
 571      If this setting is set, it specifies that the target is web service
 572      based and must be one of : <literal>get</literal>,
 573      <literal>post</literal>, <literal>soap</literal>
 574      or <literal>solr</literal>.
 575     </para>
 576    </listitem>
 577    </varlistentry>
 578
 579    <varlistentry>
 580     <term>sruVersion</term><listitem>
 581     <para>
 582      Specifies the SRU version to use. It unset, version 1.2 will be
 583      used. Some servers do not support this version, in which case
 584      version 1.1 or even 1.0 could be set it.
 585     </para>
 586    </listitem>
 587    </varlistentry>
 588
 589    <varlistentry>
 590     <term>transform</term><listitem>
 591     <para>
 592      Specifies a XSL stylesheet filename to be used if record
 593      transform is anabled; see description of elementSet.
 594      The XSL transform is only used if the element set is set to the
 595      value of <literal>element_transform</literal> in the configuration.
 596     </para>
 597    </listitem>
 598    </varlistentry>
 599
 600    <varlistentry>
 601     <term>udb</term><listitem>
 602     <para>
 603      This value is required and specifies the unique database for
 604      this profile . All target profiles should hold a unique database.
 605     </para>
 606    </listitem>
 607    </varlistentry>
 608
 609    <varlistentry id="urlRecipe">
 610     <term>urlRecipe</term><listitem>
 611     <para>
 612      The value of this field is a string that generates a dynamic link
 613      based on record content. If the resulting string is non-zero in length
 614      a new field, <literal>metadata</literal> with attribute
 615      <literal>type="generated-url"</literal> is generated.
 616      The contents of this field is the result of the URL recipe conversion.
 617      The urlRecipe value may refer to an existing metadata element by
 618      ${field[pattern/result/flags]}, which will take content
 619      of field and perform a regular expression conversion using the pattern
 620      given. For example: <literal>${md-title[\s+/+/g]}</literal> takes
 621      metadata element <literal>title</literal> and converts one or more
 622      spaces to a plus character.
 623     </para>
 624    </listitem>
 625    </varlistentry>
 626
 627    <varlistentry>
 628     <term>zurl</term><listitem>
 629     <para>
 630      This is setting is mandatory and specifies the ZURL of the
 631      target in the form of host/database. The HTTP method should
 632      not be provided as this is guessed from the "sru" attribute value.
 633     </para>
 634    </listitem>
 635    </varlistentry>
 636   </variablelist>
 637  </refsect1>
 638  <refsect1>
 639   <title>DATABASE parameters</title>
 640   <para>
 641    Extra information may be carried in the Z39.50 Database or SRU path,
 642    such as authentication to be passed to backend etc. Some of
 643    the parameters override TARGET profile values. The format is
 644   </para>
 645   <para>
 646    udb,parm1=value1&amp;parm2=value2&amp;...
 647   </para>
 648   <para>
 649    Where udb is the unique database recognised by the backend and parm1,
 650    value1, .. are parameters to be passed. The following describes the
 651    supported parameters. Like form values in HTTP the parameters and
 652    values are URL encoded. The separator, though, between udb and parameters
 653    is a comma rather than a question mark. What follows question mark are
 654    HTTP arguments (in this case SRU arguments).
 655   </para>
 656   <variablelist>
 657    <varlistentry>
 658     <term>content-password</term>
 659     <listitem>
 660      <para>
 661       The password to be used for content proxy session. If this parameter
 662       is not given, value of parameter <literal>password</literal> is passed
 663       to content proxy session.
 664      </para>
 665     </listitem>
 666    </varlistentry>
 667    <varlistentry>
 668     <term>content-proxy</term>
 669     <listitem>
 670      <para>
 671       Specifies proxy to be used for content proxy session. If this parameter
 672       is not given, value of parameter <literal>proxy</literal> is passed
 673       to content proxy session.
 674      </para>
 675     </listitem>
 676    </varlistentry>
 677    <varlistentry>
 678     <term>content-user</term>
 679     <listitem>
 680      <para>
 681       The user to be used for content proxy session. If this parameter
 682       is not given, value of parameter <literal>user</literal> is passed
 683       to content proxy session.
 684      </para>
 685     </listitem>
 686    </varlistentry>
 687    <varlistentry>
 688     <term>cproxysession</term>
 689     <listitem>
 690      <para>
 691       Specifies the session ID for content proxy. This parameter is, generally,
 692       not used by anything but the content proxy itself when invoking
 693       Metaproxy via SRU.
 694      </para>
 695     </listitem>
 696    </varlistentry>
 697    <varlistentry>
 698     <term>nocproxy</term>
 699     <listitem>
 700      <para>
 701       If this parameter is specified, content-proxying is disabled
 702       for the search.
 703      </para>
 704     </listitem>
 705    </varlistentry>
 706    <varlistentry>
 707     <term>password</term>
 708     <listitem>
 709      <para>
 710       Specifies password to be passed to backend. It is also passed
 711       to content proxy session unless overriden by content-password.
 712       If this parameter is omitted, the password will be taken from
 713       TARGET profile setting
 714       <link linkend="zoom-torus-authentication">
 715        <literal>authentication</literal>
 716       </link>
 717       .
 718      </para>
 719     </listitem>
 720    </varlistentry>
 721    <varlistentry>
 722     <term>proxy</term>
 723     <listitem>
 724      <para>
 725       Specifies one or more proxies for backend. If this parameter is
 726       omitted, the proxy will be taken from TARGET profile setting
 727       <link linkend="zoom-torus-cfproxy">
 728        <literal>cfProxy</literal></link>.
 729        The parameter is a list of  comma-separated  host:port entries.
 730        Bost host and port must be given for each proxy.
 731      </para>
 732     </listitem>
 733    </varlistentry>
 734    <varlistentry>
 735     <term>realm</term>
 736     <listitem>
 737      <para>
 738       Session realm to be used for this target, changed the resulting
 739       URL to be used for getting a target profile, by changing the
 740       value that gets substituted for the %realm string. This parameter
 741       is not allowed if access is controlled by
 742       <link linkend="auth_url">auth_url</link>
 743       in configuration.
 744      </para>
 745     </listitem>
 746    </varlistentry>
 747
 748    <varlistentry>
 749     <term>torus_url</term>
 750     <listitem>
 751      <para>
 752       Sets the URL to be used for Torus records fetch - overriding value
 753       of <literal>url</literal> attribute of element <literal>torus</literal>
 754       in zoom configuration. This parameter is not allowed if access is
 755       controlled by
 756       <link linkend="auth_url">auth_url</link> in configuration.
 757      </para>
 758     </listitem>
 759    </varlistentry>
 760
 761    <varlistentry>
 762     <term>user</term>
 763     <listitem>
 764      <para>
 765       Specifies user to be passed to backend. It is also passed
 766       to content proxy session unless overriden by content-user.
 767       If this parameter is omitted, the user will be taken from TARGET
 768       profile setting
 769       <link linkend="zoom-torus-authentication">
 770        <literal>authentication</literal>
 771       </link>
 772       .
 773      </para>
 774     </listitem>
 775    </varlistentry>
 776    <varlistentry>
 777     <term>x-parm</term>
 778     <listitem>
 779      <para>
 780       All parameters that has prefix x, dash are passed verbatim
 781       to the backend.
 782      </para>
 783     </listitem>
 784    </varlistentry>
 785   </variablelist>
 786  </refsect1>
 787  <refsect1>
 788   <title>SCHEMA</title>
 789   <literallayout><xi:include
 790   xi:href="../xml/schema/filter_zoom.rnc"
 791   xi:parse="text"
 792   xmlns:xi="http://www.w3.org/2001/XInclude" />
 793   </literallayout>
 794  </refsect1>
 795
 796  <refsect1>
 797   <title>EXAMPLES</title>
 798   <para>
 799    In example below Target definitions (Torus records) are fetched
 800    from a web service via a proxy. A CQL profile is configured which
 801    maps to a set of CCL fields ("no field", au, tu and su). Presumably
 802    the target definitions fetched maps the CCL to their native RPN.
 803    A CCL "ocn" is mapped for all targets. Logging of APDUs are enabled,
 804    and a timeout is given.
 805    <screen><![CDATA[
 806     <filter type="zoom">
 807       <torus
 808          url="http://torus.indexdata.com/src/records/?query=%query"
 809          proxy="localhost:3128"
 810          />
 811       <fieldmap cql="cql.anywhere"/>
 812       <fieldmap cql="cql.serverChoice"/>
 813       <fieldmap cql="dc.creator" ccl="au"/>
 814       <fieldmap cql="dc.title" ccl="ti"/>
 815       <fieldmap cql="dc.subject" ccl="su"/>
 816
 817       <cclmap>
 818         <qual name="ocn">
 819           <attr type="u" value="12"/>
 820           <attr type="s" value="107"/>
 821         </qual>
 822       </cclmap>
 823       <log apdu="true"/>
 824       <zoom timeout="40"/>
 825     </filter>
 826 ]]>
 827    </screen>
 828   </para>
 829
 830   <para>
 831    Here is another example with two locally defined targets: A
 832    Solr target and a Z39.50 target.
 833    <screen><![CDATA[
 834       </filter>
 835       <filter type="zoom">
 836         <torus>
 837           <records>
 838             <record>
 839               <udb>ocs-test</udb>
 840               <cclmap_term>t=z</cclmap_term>
 841               <cclmap_ti>u=title t=z</cclmap_ti>
 842               <sru>solr</sru>
 843               <zurl>ocs-test.indexdata.com/solr/select</zurl>
 844             </record>
 845             <record>
 846               <udb>loc</udb>
 847               <cclmap_term>t=l,r</cclmap_term>
 848               <cclmap_ti>u=4 t=l,r</cclmap_ti>
 849               <zurl>z3950.loc.gov:7090/voyager</zurl>
 850             </record>
 851           </records>
 852         </torus>
 853         <fieldmap cql="cql.serverChoice"/>
 854         <fieldmap cql="dc.title" ccl="ti"/>
 855       </filter>
 856 ]]>
 857    </screen>
 858   </para>
 859  </refsect1>
 860
 861  <refsect1>
 862   <title>SEE ALSO</title>
 863   <para>
 864    <citerefentry>
 865     <refentrytitle>metaproxy</refentrytitle>
 866     <manvolnum>1</manvolnum>
 867    </citerefentry>
 868   </para>
 869   <para>
 870    <citerefentry>
 871     <refentrytitle>virt_db</refentrytitle>
 872     <manvolnum>3mp</manvolnum>
 873    </citerefentry>
 874   </para>
 875  </refsect1>
 876
 877  &copyright;
 878 </refentry>
 879
 880 <!-- Keep this comment at the end of the file
 881 Local variables:
 882 mode: nxml
 883 nxml-child-indent: 1
 884 End:
 885 -->