Net::Z3950::AsyncZ::Report.pm - Perl extension for the Net::AsyncZ module

- NAME
- SYNOPSIS
- DESCRIPTION
- Constructor and Methods

- Constructor
- Object Method
- Class Methods

- Record Data

- Record Format Types
- Format Methods
- MARC Bibliographic Format

- The MARC Fields Hashes
- References to MARC Hashes
- Changing %MARC_FIELDS
- The `_params` Options
- MARC fields priority sequence:
- MARC Examples
- Some Useful MARC web links:

- AUTHOR
- COPYRIGHT AND LICENSE

# NAME

Net::Z3950::AsyncZ::Report.pm - Perl extension for the Net::AsyncZ module

# SYNOPSIS

             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

# DESCRIPTION

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.

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.

# Constructor and Methods

## Constructor

Net::Z3950::AsyncZ::Report::new

         $rpt = Net::Z3950::AsyncZ::Report->new( $rs, $options);

params:
  $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.

Or see the HTML Options documentation: Options.html

## Object Method

Net::Z3950::AsyncZ::reportResult
  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()`,

  [3] fetch the records array through the result field of the report object.

## Class Methods

get_MARC_pat
get_GRS1_pat
get_RAW_pat
get_DEFAULT_pat

              $pat = get_TYPE_pat();

returns
  `$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.

  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()

get_pats

              $pat = get_pats();

returns
  `$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.

# Record Data

`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.

## Record Format Types

  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`.

  [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:

MARC
  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:

              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

For HTML format, see Format Callback in AsyncZ.html.

GRS-1
  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.

RAW
  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.

DEFAULT
  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.

## Format Methods

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.

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.

For the full discussion in HTML format, see Format Callback in AsyncZ.html.

The Methods

HTML
  See MARC for a brief sample of the output and furtherlinks.

Plain Text
  See MARC for a brief sample of the output and further links.

User Defined Formatting
  See MARC and the ``Format Callback'' section of AsyncZ.pod.
For the discussion in HTML format, see Format Callback in AsyncZ.html.

## MARC Bibliographic Format

`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.

### The MARC Fields Hashes

%MARC_FIELDS_STD

               %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

              %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`.

These three hashes are not themselves in visible scope. They are instead made available to the programmer by means of three references.

### References to MARC Hashes

The references are as follows:

$std = `\%MARC_FIELDS_STD`
$xtra = `\%MARC_FIELDS_XTRA`
$all = `\%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.

### Changing %MARC_FIELDS

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:

                    "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.

### The `_params` Options

marc_fields
  `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_subst
  `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_userdef
  `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_xcl
  `marc_xcl=>undef` reference to hash of MARC fields to exclude when formatting records.

### MARC fields priority sequence:

marc_userdef -> marc_fields -> marc_xcl -> marc_subst

           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

### MARC Examples

Example 1:
  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.

Example 2:
  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`.

            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:

              $Net::Z3950::AsyncZ::Report::all

  to access:

              %Net::Z3950::AsyncZ::Report::MARC_FIELDS_ALL

### Some Useful MARC web links:

     Library of Congress Tutorial:  http://lcweb.loc.gov/marc/umb/
     Library of Congress MARC Specification:  http://www.loc.gov/marc/bibliographic/ecbdhome.html

# AUTHOR

Myron Turner <turnermm@shaw.ca> or <mturner@ms.umanitoba.ca>

# COPYRIGHT AND LICENSE

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.