Net::Z3950::AsyncZ::Report.pm - Perl extension for the Net::AsyncZ module
my $report = Net::Z3950::AsyncZ::Report->new($rs, $options); $report->reportResult(); $result = $report->{result}; $rs: Net::Z3950::ResultSet $options: Net::Z3950::AsyncZ::Options::_param $result: reference to array of record data
In the general case, Report.pm retrieves records from the server, formats them one line at a time and pushes the formatted lines onto an array. Each record is preceded by a set of headers, which mark the separation between records. It's this array which is returned to the callback function assigned in AsyncZ::new to the cb parameter. You can also supply your own formatting function, using the format parameter, to format the lines yourself.
Report.pm
AsyncZ::new
cb
format
If you choose to get the record back as Raw data, no formatting is done. In this case, you can do the formatting in the callback. You might choose to take this route in the case of GRS-1 Records or Record Formats which Net::Z3950::AsyncZ::Report is not equipped to handle.
Report.pm is integrated into the AsyncZ system, but it can be used independently as long as you pass it a Net::Z3950::AsyncZ::Options::_param object as the second parameter. It will return an array of record data formatted according to your specifications.
$rpt = Net::Z3950::AsyncZ::Report->new( $rs, $options);
$rs: Net::Z3950::ResultSet
$options: Net::Z3950::AsyncZ::Options::_param:
format => undef, # reference to a callback function that formats each row of a record raw => 0, # (boolean) if true the raw record data is returned unformatted start => 1, # number of the record with which to start report num_to_fetch => 5, # number of records to include in a report marc_fields => $std, # $std = \%MARC_FIELDS_STD marc_xcl => undef, # reference to hash of MARC fields to exclude from report marc_userdef => undef, # reference to user specified hash of MARC fields for report marc_subst => undef # reference to a hash which subtitutes field names for default names HTML =>0 # (boolean) if true use default HTML formatting, # if false format as plain text # if true each row will be formatted as follows: # "<tr><td>field name<td>field data\n" # if false each row will be formatted as follows: # "MARC_field_number field_name field_data\n"
For more detailed descriptions of these options see the Options documentation: Options.pod.
There is no return value and no parameters for this method. It is used as illustrated in the SYNOPSIS above:
my $report = Net::Z3950::AsyncZ::Report->new($rs, $options); $report->reportResult(); $result = $report->{result};
[1] create a Report object,
[2] implement the report with a call to reportResult(),
reportResult()
[3] fetch the records array through the result field of the report object.
$pat = get_TYPE_pat();
$pat: a regular expression that tests whether a header is of a particular type. With this you can test whether a line from the result array is a header and of what type.
$pat
For example, for the MARC record header it returns:
\[MARC\s\d+\]
You can test for the MARC header as follows:
$line =~ Net::Z3950::AsyncZ::Record::get_MARC_pat()
$pat = get_pats();
$pat: a regular expression that matches any of the above types:
$line =~ Net::Z3950::AsyncZ::Record::get_pats()
This will return true if the line matches one of the header types.
Net::Z3950::AsyncZ::Report defaults to the MARC record structure, and uses the MARC record structure in parsing and formatting record data. The GRS-1 structure is far more complex and difficult to deal with. In so far as a GRS-1 record implements the MARC record tags, I make an attempt to read and parse it. But if AsyncZ ever becomes useful to programmers who need GRS-1, they will have to build far better GRS-1 support into it.
Net::Z3950::AsyncZ::Report
When Net::Z3950::AsyncZ::Report gets back records from a server, it follows these steps:
[1] if raw is set to true, it does one of two things. If _params->{render} is set to true, which is the default, it returns an array derived from passing the raw data through Net::Z3950::Record::render(). If _params->{render} is set to false, it returns the raw record data unfiltered. To extract records from the unfiltered data, two methods are provided: Net::Z3950::AsyncZ::prep_Raw and Net::AsyncZ::get_ZRawRec. The default is render=>1.
raw
_params->{render}
Net::Z3950::AsyncZ::prep_Raw
Net::AsyncZ::get_ZRawRec
render=>1
[2] if raw is false, it checks to see whether the Record format is MARC or GRS-1 and, if it is one of these, processes it accordingly;
[3] if none of the above are true, it processes the Record using its Default method
Note: Each of the types described in this section has a corresponding Header.
The Types:
In dealing with MARC records, Net::Z3950::AsyncZ::Report passes the MARC tag and the record data to one of the "Format Methods". These check the tag against the %MARC_FIELDS hash and retrieve the descriptive identifier string for that field and produce rows consisting of tag, identifier, data. The plaintext, DEFAULT, output looks like this:
%MARC_FIELDS
100 author: James, Henry,1843-1916.Correspondence.Selections. 245 title: Dear munificent friends
If HTML were specified then these elements would be put into table format:
<TD>100<TD>author: <TD>James, Henry,1843-1916.Correspondence.Selections.
See the "Format Callback" section of AsyncZ.pod and the "MARC Bibliographic Format"
In the case of GRS-1 Records, the GRS-1 method attempts to locate MARC Record tags; if none are found it passes the formatting function an empty string for the tag. A data string still is passed into the function.See MARC and "Format Methods".
MARC
As stated in [1] above, the RAW method returns either an array derived from passing the raw data through Net::Z3950::Record::render() or entirely raw output-- which depends on the value of the render option. In neither case does it make an attempt to parse or format the Record, and in keeping with this, you cannot assign a format callback for use with RAW data. Presumably, you will read, parse, and format the record in the cb callback.
render
As in the case of GRS-1 Records, in the DEFAULT method an attempt is made to identify MARC tags; if none are found it passes the formatting function an empty string for the tag and passes in a data string. See MARC and GRS-1 above and "Format Methods" below.
GRS-1
Two default methods are provided for formatting lines of record data, Plain Text and HTML. If you set raw to true, no formatting will be done. You can also supply a method of your own to format record lines by assigning a callback function to the format parameter of the _params object.
Plain Text
HTML
_params
The formatting methods are passed two parameters in the form of a reference to a two element array:
$ref->[0]>: a MARC tag or the null string if there is no tag $ref->[1]>: the data string
See MARC and the "MARC Bibliographic Format".
A full discussion of the Format function will be found in the "Format Callback" section of AsyncZ.pod.
See MARC for a brief sample of the output and furtherlinks.
See MARC for a brief sample of the output and further links.
See MARC and the "Format Callback" section of AsyncZ.pod.
Net::Z3950::AsyncZ::Report defaults to the MARC Bibliographic Format for Bibliographic Data when parsing and formatting records. Net::Z3950::AsyncZ::Report uses a selection of the many fields in the MARC Format and divides this selection into three hashes.
%MARC_FIELDS_STD = ( "020"=>'ISBN', "050"=>"LC call number", 100=>'author', 245=>'title', 250=>'edition', 260=>'publication', 300=>'description', 440=>'series', 500=>'note', 520=>'annotation', 650=>'subject', 700=>'auth, illus, ed', );
%MARC_FIELDS_XTRA = ( "082"=>'Dewey decimal number', 240=>'Uniform title', 246=>'alternate title', 130=>'main entry', 306=>'playing time', 504=>'Bibliography', 508=>'creation/production credits', 510=>'citation/references', 511=>'participant or performer', 520=>'Summary,note', 521=>'target audience', 530=>'physical form', 586=>'awards' );
These hashes are futher identified as follows:
%MARC_FIELDS_ALL = (%MARC_FIELDS_STD, %MARC_FIELDS_XTRA); %MARC_FIELDS = %MARC_FIELDS_STD;
%MARC_FIELDS always points to the hash which is used in formatting records, and it defaults to %MARC_FIELDS_STD.
%MARC_FIELDS_STD
These three hashes are not themselves in visible scope. They are instead made available to the programmer by means of three references.
The references are as follows:
\%MARC_FIELDS_STD
\%MARC_FIELDS_XTRA
\%MARC_FIELDS_ALL
These references have the advantage of being brief. Since Net::Z3950::Report does not export any names, it is simpler to write $Net::Z3950::Report:std than %Net::Z3950::Report::MARC_FIELDS_STD. In addition, they conform to the general use of references in the setting of options.
Net::Z3950::Report
$Net::Z3950::Report:std
%Net::Z3950::Report::MARC_FIELDS_STD
The _params array provides a set of options which enables you to change the default entries of the %MARC_FIELDS hash. Each of these options takes a reference to another hash, the form of which must follow the structure of %MARC_FIELDS_STD and %MARC_FIELDS_XTRA. The hash keys are the MARC tags, and the values are the descriptive identifiers. The tags are always three digit numbers. If either one or both of the leading numbers is 0, then the tag must be quoted:
%MARC_FIELDS_XTRA
"020"=>'ISBN', "050"=>'LC call number'
There is great flexibility for handling the tags and the identifiers. For one--you can subtitute your own hash for the default hashes by setting marc_userdef to your own. Or, you can use one or both of the default hashes and tailor them to your own needs with marc_subst and marc_xcl. The marc_subst hash enables you to subsitute your own identifiers for the default, and marc_xcl enables you to exclude tag entries from the default hashes.
marc_userdef
marc_subst
marc_xcl
marc_fields=>\%Net::Z3950::AsyncZ::Report::STD other possibilties are \%Net::Z3950::AsyncZ::Report::ALL and \%Net::Z3950::AsyncZ::Report::XTRA, which you can set by using either set_marc_xtra() or set_marc_all().
marc_fields=>\%Net::Z3950::AsyncZ::Report::STD
\%Net::Z3950::AsyncZ::Report::ALL
\%Net::Z3950::AsyncZ::Report::XTRA
set_marc_xtra()
set_marc_all()
marc_subst=>undef reference to user-defined hash of MARC fields in which you substitute your own field identifier strings for those which are pre-defined in the MARC fields hashes
marc_subst=>undef
marc_userdef=>undef reference to user-defined hash of MARC fields to use in formatting records. If this hash is defined, it will take the place of the default hash.
marc_userdef=>undef
marc_xcl=>undef reference to hash of MARC fields to exclude when formatting records.
marc_xcl=>undef
This means that: 1. marc_userdef will replace marc_fields if marc_userdef exists 2. marc_xcl will be applied to the hash which results from operation 1 3. marc_subst will be applied to the hash resulting from 1 plus 2
This example assumes that you are using %MARC_FIELDS_STD as your base hash:
%MARC_FIELDS_STD = ( "020"=>'ISBN', "050"=>"LC call number", 100=>'author', 245=>'title', 250=>'edition', 260=>'publication', 300=>'description', 440=>'series', 500=>'note', 520=>'annotation', 650=>'subject', 700=>'auth, illus, ed', ); $xcl = { "020"=>undef,"050"=>'', 500=>undef, 520=>"" }; $subst = { 250=>'ed.',260=>'pub.',300=>'desc.'}; $_pararms->set_marc_xcl($xcl); $_pararms->set_marc_subst($subt);
The resulting hash would be:
%MARC_FIELDS_STD = ( 100=>'author', 245=>'title', 250=>'ed.', 260=>'pub.', 300=>'desc.', 440=>'series', 650=>'subject', 700=>'auth, illus, ed', );
A record using this hash and Plain Text formatting might look something like this:
100 author: Henry, James F.,1930- 245 title: The manager's guide to resolving legal disputes 250 ed. 1st ed. 260 pub.: New York :Harper & Row,c1985. 300 desc.: v, 162 p. ;22 cm. 650 subject: Dispute resolution (Law)United States. 650 subject: Negotiation. 700 auth, illus, ed: Lieberman, Jethro Koller.
This example assumes that you want to expand the number of fields available, beyond those which are specified in %MARC_FIELDS_ALL. You create a hash of additional fields and add them to %MARC_FIELDS_ALL.
%MARC_FIELDS_ALL
my %my_MARC_fields = ( 651 => "location", 654 => "terms", 655 => "genre", 656 => "occupation", 760 => "main series entry", 762 => "subseries entry", 765 => "original language entry", 767 => "translation entry", 770 => "supplement/special issue entry", 772 => "supplement parent entry", 773 => "host item entry", 774 => "constituent unit entry", 775 => "other edition entry", 776 => "additional physical form entry", 777 => "issued with entry", 780 => "preceding entry", 785 => "succeeding entry", 786 => "data source entry", 787 => "nonspecific relationship entry", 800 => "series added entry -- personal name", 810 => "series added entry--corporate name", 811 => "series added entry--meeting name", 830 => "series added entry--uniform title" ); my %my_MARC_hash = (%$Net::Z3950::AsyncZ::Report::all, %my_MARC_fields); $_pararms->marc_userdef(\%my_MARC_hash);
Note: we use the $all reference:
$all
$Net::Z3950::AsyncZ::Report::all
to access:
%Net::Z3950::AsyncZ::Report::MARC_FIELDS_ALL
Library of Congress Tutorial: http://lcweb.loc.gov/marc/umb/ Library of Congress MARC Specification: http://www.loc.gov/marc/bibliographic/ecbdhome.html
Myron Turner <turnermm@shaw.ca> or <mturner@ms.umanitoba.ca>
Copyright 2003 by Myron Turner
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
3 POD Errors
The following errors were encountered while parsing the POD:
Expected '=item *'
To install Net::Z3950::AsyncZ::ZSend, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Z3950::AsyncZ::ZSend
CPAN shell
perl -MCPAN -e shell install Net::Z3950::AsyncZ::ZSend
For more information on module installation, please visit the detailed CPAN module installation guide.