Net::Z3950::RadioMARC - Perl extension for testing Z39.50 servers
use Net::Z3950::RadioMARC;
$t = new Net::Z3950::RadioMARC(); $t->set(host => 'z3950.loc.gov', port => '7090', db => 'voyager'); $t->set(delay => 3); $t->add("filename.marc"); $t->test('@attr 1=4 01245a01', { ok => '245$a is searchable as 1=4', notfound => 'This server is broken' }); # -- or -- set host => 'z3950.loc.gov', port => '7090', db => 'voyager'; set delay => 3; add "filename.marc"; test '@attr 1=4 01245a01', { ok => '245$a is searchable as 1=4', notfound => 'This server is broken' };
This module provides the harness in which test-scripts can be written
for detecting the presence of a ``radioactive MARC record'' in a
Z39.50-compliant database, and determining how that database indexes
the record. Its key provision is the test()
method, which runs a
search for some well-known term that is known to occur in a
``radioactive'' record, and generates different output dependent on
whether the record is found or not.
This module may be used in two different ways: the first approach is to use a rigorous object-oriented syntax in which a test-harness method is explicitly created, and methods are invoked on it. The other is a simpler syntax in which a test-harness object is transparently created behind the scenes when it's first needed, and subsequently referenced by function calls. These two styles are exemplified by the two code-fragments in the synopsis above.
For most purposes, the simple syntax will be preferable. The object-oriented synatx is useful primarily when it is necessary for a single script to run tests against two or more different databases.
set()
methodadd()
methoddumpindex()
methodtest()
method
new()
$testHarness = new Net::Z3950::RadioMARC();
Creates a new test-harness for checking the searchability of ``radioactive MARC records'' in a database available via Z39.50. There are no argument; the new object is returned.
Before the new test-harness can be used by the test()
method, at
least its
host
property must be set, and often its
port
,
db
and
format
as well. See the documentation for the <set()> method for details on
how this is done and what the argument mean.
It is not necessary to explicitly create a test-harness object in order to use this module. See the describe above of the ``simple syntax'' approach, in which a test-harness object is implicitly created.
set()
$t->set(host => 'z3950.loc.gov', port => '7090', db => 'voyager'); $t->set(delay => 3); # -- or -- set host => 'z3950.loc.gov', port => '7090', db => 'voyager'; set delay => 3;
Sets one or more properties of the specified test-harness, or of the implicit test-harness if none is specified (i.e. when the simple syntax is used instead of the object-oriented syntax).
Each pair of arguments is taken to be a pair consisting of a property name and the corresponding new value. It is an error to provide an odd number of argument.
The following properties are defined.
host
[no default]test()
method.
port
[default: 210
]db
[default: "Default"
]format
[default: "USMARC"
]delay
[default: 1
]messages
[default: an empty hash]The interpretation of message templates is described in the
documentation of the test()
method. Status values for which no
message template is provided (i.e. all status value initially) are not
reported at all, except for the status fail
which is reported using
a simple, explicit default format.
verbosity
[default: 1
]add()
method, or
matches more than one of these records (in which case the first one to
have been added is used).
Level 1 is the default, since these messages are arguably reporting configuration errors, whereas the higher levels generate chit-chit that is is probably only useful for debugging.
Messages indicating when the number of hits a query generates in the remote database is not one, as expected. Messages indicating how many hits each query generated in the remote database being tested, however many there are. Messages showing each query before it is tested.report
[default: 1
]($status, $errmsg, $addinfo) = test '@attr 1=4 fruit', { report => 0 };
which allows the test-script to explicitly check the status and make whatever choices it deems appropriate without side-effects.
identityField
[no default]It may take the form tag for control fields (for example 001
to
specify the local identifier) or tag$
subfield (for example
245$a
to specify the title field).
Multiple candidate identity fields may be specified, separated by
commas, like this: 100,035$a
. In this case, each such candidate
subfield is tried in turn, and the first one that exists in both
records being compared is used.
If no identity field is specified, then two records are considered to be the same only if they are byte-for-byte identical.
It is an error to try to set a property other than those described here.
add()
$t->add("filename.marc"); # -- or -- add "filename.marc";
Adds one or more MARC records to the set that are to be tested for. Records are loaded from the file whose name is specified. Any number of records may be added to the test-set, but using many such records may be self-defeating, since then the radioactive tokens to be searched for are less likely to be unique.
Behind the scenes, this module builds an inverted index of all the
words occurring in all the subfields of all the non-control fields in
all the records that are added. This is used when test()
is called
to identify which of the add()
ed records is the one that should be
retrieved from the server.
add()
returns a list of opaque tokens representing the newly added
records. These tokens may be passed as the record
parameter into
the test()
method to indicate explicitly which of the test-set
records a particular query is intended to find.
dumpindex()
$t->dumpindex();
Dumps to standard output the inverted index generated for the MARC
records have been added to the test-set by the add()
method.
Never call this method.
test()
$t->test('@attr 1=4 01245a01', { ok => '245$a is searchable as 1=4', notfound => 'This server is broken', record => $token }); $t->test('@attr 1=4 thrickbrutton'); # -- or -- test '@attr 1=4 01245a01', { ok => '245$a is searchable as 1=4', notfound => 'This server is broken', record => $token }; test '@attr 1=4 thrickbrutton';
Runs a single test against the server that has been nominated for the specified test-harness. The first argument is a query in PQF (Prefix Query Format) as described in the YAZ manual at http://indexdata.com/yaz/doc/tools.tkl#PQF and the second (optional) is a reference to hash of parameters, some of which are used for mapping status values to message templates.
The query is analysed to see which of the test-set records it should
find. For maximally indicative results, it should match exactly one
such record - no more, no less. If it matches more than one, the the
first one is used for the subsequent matching process: that is, the
one that occurred earliest in MARC file that first add()
ed to the
test-set. If the parameter record
is provided, then its value is
use as the opaque token of the test-set record to be used and the
query is not used for this purpose.
The query is submitted to the server, and returns some number of hit-set records. Again, the most significant test results are obtained when there is exactly one such record.
Each of the candidate hits is compared with the chosen test-set record to see whether there is match or not - that is, whether the search retrieved the nominated radioactive record.
The result of this process is that a status is generated, being one of the following short strings:
ok
notfound
fail
The test()
method returns a triple, ($status
, $errmsg
,
$addinfo
), with $errmsg
being the human-readable string
corresponding to the BIB-1 diagnostic code returned by the server in
the case of an error, and $addinfo
being any additional information
returned by the server along with such a diagnostic.
If the report
property of the test-harness is true (as it is by
default), then a report is emitted describing the outcome of the test.
Under some circumstances, it is useful to inhibit this behaviour by
setting report
false and testing the explicitly returned values
instead.
The reporting output is generated from a template. The template is
found by looking up the status of the test in the hash-reference
argument, if this is supplied. If it is not supplied, or if the
relevant element is missing, it is looked up in the hash that is the
value of the message
property. If the relevant element is not in
this hash either, a default template is used for notfound
and
fail
tests, but NO OUTPUT AT ALL is emitted for ok
test. This
makes it possible to write silent-on-success test scripts. If you
want commentary on successful tests, then, you must explicitly specify
an ok
message template, either in the message
property or in the
hash-reference passed into test()
.
Report-generating templates are strings which may contain the following escape sequences, which are substituted the the appropriate values:
The RadioMARC mailing list, at http://www.indexdata.dk/mailman/listinfo/radiomarc
### There ought to be an academic paper giving an overview of the whole ``Radioactive Record'' approach.
Creating Radioactive MARC Records and Z Queries Using the MARCdocs Database at http://www.unt.edu/zinterop/Zinterop2Drafts/MARCdocsExtensionForRadMARCQueries22Nov2004.pdf
### any other information UNT have published on the Web.
Mike Taylor, <mike@indexdata.com>
Copyright (C) 2004 by Index Data ApS.
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.3 or, at your option, any later version of Perl 5 you may have available.