Net::Z...:Config(3pm)

🦋 NAME 🦋

okay so this whole page is the manual for Net::Z3950::Simple2ZOOM::Config (it lives in the 3pm manual section, iykyk) — it's the configuration file for the Simple2ZOOM gateway. that's it. that's the name. periodt. 💅

---

✨ SYNOPSIS ✨

here's the whole vibe in one glance, bestie:

<client>
  <authentication>http://some.url/{user}/pwd={pass}<authentication>
  <database name="srubooks">
    <zurl>http://z3950.loc.gov:7090/voyager</zurl>
    <option name="sru">get</option>
    <charset>marc-8</charset>
    <search>
      <querytype>cql</querytype>
      <map use="4"><index>title</index></map>
      <map use="1003"><index>creator</index></map>
    </search>
  </database>
</client>

---

💖 DESCRIPTION 💖

so the universal Swiss Army Gateway simple2zoom is configured by one single file, you name it on the command-line, and it's written in XML. that's the whole thing.

this file is doing so much for you. it says which back-end databases are supported, how the back-ends get contacted, what character-sets they hand back records in, and how Z39.50 searches map over to CQL. it's giving project manager energy fr fr. 🌈

the structure? pretty simple ngl.

🌸 Top Level 🌸

💜 <client>

the top-level element is <client>. it holds:

• a single optional <authentication> element
• any number of <database> elements
• a single optional <search> element

the <database> ones say which databases exist and how to talk to them. the <search> one says how to interpret requests to search in the configured databases. and the <authentication> one — which is the second of these, obviously — provides query mapping specs for dynamically specified databases. 💅

🔐 <authentication>

this element contains a URL template, which is the address of an HTTP authentication server.

the template must include the special strings {user} and {pass} — those get substituted with the username and password supplied in the Init request, if any.

so what happens: the resulting URL gets actioned, and the result gets examined.

• any successful response (HTTP status 200) → the username/password combo is acceptable and the session can continue 🎉
• any other response (e.g. 401 Authorization Required) → the Init request gets refused with BIB-1 diagnostic 1014 (Init/AC: Authentication System error) 💀

if the <authentication> element is omitted from the config, then no authentication credentials are required, and any that are provided just get ignored. bye.

(also, a trivial example of an authentication server script ships in the Simple2ZOOM distribution, as etc/sru-auth — go look bestie 🫶)

🗂️ <database>

the <database> element carries a name attribute — that's the Z39.50 database name, the one clients know it by.

it contains several complex elements, and we're getting into all of them in more detail below. sit tight.

🔎 <search>

every <search> element — whether it's nested inside a specific <database> (see below 👇) or sitting at the top level — is made of:

1. a single mandatory <querytype> element
2. followed by any number of <map>s

the content of <querytype> tells you what type of query should be sent to the back-end server, and Simple2ZOOM is the one responsible for translating incoming queries into that format as needed.

right now, the only supported value is cql. that's the whole menu, no cap.

🗺️ <map>

each <map> element carries a use attribute — that's the numeric value of the BIB-1 use attribute to be supported. and optionally it contains a single <index> element, which in turn contains the name of the corresponding CQL index.

so: Type-1 searches against the specified BIB-1 access point get mapped to CQL searches against the specified index. slay. ✨

if the <index> is omitted inside a <map>, then the generated CQL query term has no index specified. that's actually useful for BIB-1 attributes like 1016 (any) and 1035 (anywhere). iconic.

🦋 Databases 🦋

the <database> element that describes each database contains the following elements in the specified order. order matters bestie, don't freestyle it.

so in general, <database> entries come in two flavors:

• ones connecting through to a Z39.50 database → no <search> element, because no query mapping is needed to translate an incoming Type-1 query
• ones connecting to an SRU or SRW database → they do have a <search> element with <querytype> set to cql, and it contains the info on how to map from specified BIB-1 use attributes to CQL indexes

🌐 <zurl>

contains the target address of the back-end database. examples, bestie: tcp:z3950.indexdata.com/gils or http://z3950.loc.gov:7090/voyager.

🔄 <resultsetid>

optional! if you provide it, it has to be one of these values. and if you omit it, then fallback is assumed.

• id — when queries come in that include references to existing result-sets, those get translated into result-set references using the cql.resultSetId index. it is an error if the server doesn't support this facility. 💀
• search — references to existing result-sets get rewritten as resubmissions of the query. this works on all servers, but it doesn't reliably give precisely correct results if the database is updated between searches. 🙈
• fallback — result-set references get used when supported, but resubmissions of prior queries get used when that facility is unavailable.

🚫 <nonamedresultsets>

this one's optional. if provided, it's empty, and it indicates that the back-end database does not support named result sets. that's it, that's the whole element. 💅

⚙️ <option>

there can be any number of these. each <option> element carries a name attribute and contains a corresponding value.

these are ZOOM options which get applied to the connection when it's first created. you can use them to control stuff like the desired elementSetName or schema of the records the back-end gives you.

one that's particularly important is sru — set it to get, post or soap to request vanilla SRU, SRU over POST and SRW respectively. 👑

🔤 <charset>

optional. contains the name of the character-set in which the back-end target supplies records (e.g. marc-8).

🔍 <search>

optional. gives you the specs for how to search the database, exactly like the top-level <search> element described above. same energy.

📋 <schema>

optional and repeatable — so you can stack these. each element indicates special handling for when records are requested in a particular schema. more below. ⬇️

📦 <sutrs-record>, <usmarc-record>, <grs1-record>

optional. these provide specs for how to construct records in the relevant syntaxes when clients request them.

the format is the same in all cases: the spec contains a list of <field> elements, and each one has an xpath attribute plus textual content.

so records get built by accessing the data addressed by the specified XPath expressions, and encoding each one as an element addressed as specified by the element content. the interpretation of that content is different depending on which record-syntax you're in:

SUTRS

the content is ignored. nothing to see here. 🎀

USMARC

the content indicates a MARC field via a string made of these parts, in order:

• a three-digit field number
• optionally a slash followed by the first indicator
• optionally another slash followed by the second indicator
• optionally a dollar sign followed by a subfield tag

in other words, MARC field specifications much match the regular expression /^\d\d\d(/w)?(/w?)(\$\w)?$/.

heads up: it is impossible to specify the second indicator without the first. but a subfield can be specified along with zero, one or two indicators. 💀

as usual, a few examples are worth any amount of explanation:

001
260$c
500$a
100/1$a
245/1/0$a

GRS-1

the content indicates an address within a GRS-1 record, in the form of one or more consecutive (type,value) pairs, each enclosed in parentheses.

for example, (1,14) would indicate an element of type 1 (tagSet-M) with value 14 (localControlNumber).

a longer path like (3,admin)(2,6) indicates an abstract field (tagSet-G element 6) within an admin sub-record. look at us go ✨

🎀 Schemas 🎀

each <schema> element is empty, but it carries the following attributes, which get used to provide records to Z39.50 clients in MARC formats.

• oid — Mandatory. this is the OID of a Z39.50 record-syntax which is to be handled by schema mapping. requests in this database for this record-syntax are handled as specified. example value: 1.2.840.10003.5.10
• sru — Mandatory. this is the URI of an SRU/W schema which is requested from the SRU or SRW back-end in order to fulfill the request. example value: info:srw/schema/1/marcxml-v1.1
• format — optional. indicates which of the MARC variants is in use, so the record can be formatted correctly. defaults to MARC21 if omitted. example values: MARC21, USMARC, UNIMARC
• encoding — optional. indicates which character-set to use for the formatted record. defaults to UTF-8 if omitted. example values: UTF-8, <MARC-8>

⚠️ NOTE that in its current form, this schema-mapping only works for the specific though common combination of Z39.50 front-end, SRU back-end and MARC record syntax. that's the deal bestie, don't come for me.

---

🧚 CONFIGURATION FILE SCHEMA 🧚

the Simple2ZOOM distribution includes, in the etc directory, an XML schema you can use to validate configuration files. it comes in four formats:

• simple2zoom.rnc — Relax-NG compact format: a simple, elegant, terse and wholly comprehensible XML constraint language that you don't even need to learn in order to understand. this is the master version — the others are automatically generated from it. 👑
• simple2zoom.rng — Relax-NG XML format: the world seems to have this zany fetish that everything must be specified in XML, so Relax-NG has an XML syntax that corresponds trivially with the much nicer compact syntax. the principle value of this is that xmllint understands it. 💅
• simple2zoom.dtd — an old-fashioned DTD (document type definition). vintage. 🎀
• simple2zoom.xsd — if you must. 🙈

use whichever you like. for example:

xmllint --relaxng simple2zoom.rng --noout test.xml
xmllint --dtdvalid simple2zoom.dtd --noout test.xml
xmllint --schema simple2zoom.xsd --noout test.xml

---

🌈 SEE ALSO 🌈

• the simple2zoom program.
• the Net::Z3950::Simple2ZOOM module.

---

💜 AUTHOR 💜

Mike Taylor <mike@indexdata.com> — the icon who wrote this. 🫶

---

🌈 COPYRIGHT AND LICENCE 🌈

okay bestie, legal era 💅 but like, the nice kind of legal, not the scary kind.

Copyright (C) 2007 by Index Data.

that's it, that's the whole vibe. Index Data was out here in 2007 making this whole thing happen and honestly? iconic of them. 👑

---

now the part that actually matters for you and your projects, so listen up:

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

fr fr, that's a real gift. 🎁 you can share it, you can remix it, you can pass it along to your friends, you just gotta keep the same energy (aka the same terms) that Perl itself rolls with. no cap.

lowkey read that again if you're planning on shipping something: same terms as Perl itself — and you get to pick whether that's Perl version 5.8.8 or literally any newer Perl 5 you've got lying around. your call, bestie. 🫶

---

🌸 a lil' vibe check before you go 🌸

• free software = you can redistribute it ✅
• free software = you can modify it ✅
• same terms as Perl itself = the rules you're following 📜
• Perl version 5.8.8 = the baseline ✨
• any later version of Perl 5 = also fine, if you want 💖

that's the whole license, no fine print lurking in the shadows, no gotchas. go build something cute with it. 🦋

---

and that's a wrap on this whole page, bestie!! 🎀 this documentation came to you courtesy of the perl v5.32.0 toolchain, dated 2021-01-06, for the page known and loved as Net::Z...:Config(3pm) under the User Contributed Perl Documentation banner. ⭐ ty for reading all the way to the bottom, that's genuinely main character behavior. mwah. 💜🌸✨