<<

NAME

C4::Biblio - cataloging management functions

DESCRIPTION

Biblio.pm contains functions for managing storage and editing of bibliographic data within Koha. Most of the functions in this module are used for cataloging records: adding, editing, or removing biblios, biblioitems, or items. Koha's stores bibliographic information in three places:

1. in the biblio,biblioitems,items, etc tables, which are limited to a one-to-one mapping to underlying MARC data
2. as raw MARC in the Zebra index and storage engine
3. as raw MARC the biblioitems.marc and biblioitems.marcxml

In the 3.0 version of Koha, the authoritative record-level information is in biblioitems.marcxml

Because the data isn't completely normalized there's a chance for information to get out of sync. The design choice to go with a un-normalized schema was driven by performance and stability concerns. However, if this occur, it can be considered as a bug : The API is (or should be) complete & the only entry point for all biblio/items managements.

1. Compared with MySQL, Zebra is slow to update an index for small data changes -- especially for proc-intensive operations like circulation
2. Zebra's index has been known to crash and a backup of the data is necessary to rebuild it in such cases

Because of this design choice, the process of managing storage and editing is a bit convoluted. Historically, Biblio.pm's grown to an unmanagable size and as a result we have several types of functions currently:

1. Add*/Mod*/Del*/ - high-level external functions suitable for being called from external scripts to manage the collection
2. _koha_* - low-level internal functions for managing the koha tables
3. Marc management function : as the MARC record is stored in biblioitems.marc(xml), some subs dedicated to it's management are in this package. They should be used only internally by Biblio.pm, the only official entry points being AddBiblio, AddItem, ModBiblio, ModItem.
4. Zebra functions used to update the Zebra index
5. internal helper functions such as char_decode, checkitems, etc. Some of these probably belong in Koha.pm

The MARC record (in biblioitems.marcxml) contains the complete marc record, including items. It also contains the biblionumber. That is the reason why it is not stored directly by AddBiblio, with all other fields . To save a biblio, we need to :

1. save datas in biblio and biblioitems table, that gives us a biblionumber and a biblioitemnumber
2. add the biblionumber and biblioitemnumber into the MARC records
3. save the marc record

When dealing with items, we must :

1. save the item in items table, that gives us an itemnumber
2. add the itemnumber to the item MARC field
3. overwrite the MARC record (with the added item) into biblioitems.marc(xml)

When modifying a biblio or an item, the behaviour is quite similar.

EXPORTED FUNCTIONS

AddBiblio

  ($biblionumber,$biblioitemnumber) = AddBiblio($record,$frameworkcode);

Exported function (core API) for adding a new biblio to koha.

The first argument is a MARC::Record object containing the bib to add, while the second argument is the desired MARC framework code.

This function also accepts a third, optional argument: a hashref to additional options. The only defined option is defer_marc_save, which if present and mapped to a true value, causes AddBiblio to omit the call to save the MARC in bibilioitems.marc and biblioitems.marcxml This option is provided only for the use of scripts such as bulkmarcimport.pl that may need to do some manipulation of the MARC record for item parsing before saving it and which cannot afford the performance hit of saving the MARC record twice. Consequently, do not use that option unless you can guarantee that ModBiblioMarc will be called.

ModBiblio

  ModBiblio( $record,$biblionumber,$frameworkcode);

Replace an existing bib record identified by $biblionumber with one supplied by the MARC::Record object $record. The embedded item, biblioitem, and biblionumber fields from the previous version of the bib record replace any such fields of those tags that are present in $record. Consequently, ModBiblio() is not to be used to try to modify item records.

$frameworkcode specifies the MARC framework to use when storing the modified bib record; among other things, this controls how MARC fields get mapped to display columns in the biblio and biblioitems tables, as well as which fields are used to store embedded item, biblioitem, and biblionumber data for indexing.

_strip_item_fields

  _strip_item_fields($record, $frameworkcode)

Utility routine to remove item tags from a MARC bib.

ModBiblioframework

   ModBiblioframework($biblionumber,$frameworkcode);

Exported function to modify a biblio framework

DelBiblio

  my $error = &DelBiblio($biblionumber);

Exported function (core API) for deleting a biblio in koha. Deletes biblio record from Zebra and Koha tables (biblio,biblioitems,items) Also backs it up to deleted* tables Checks to make sure there are not issues on any of the items return: $error : undef unless an error occurs

BiblioAutoLink

  my $headings_linked = BiblioAutoLink($record, $frameworkcode)

Automatically links headings in a bib record to authorities.

LinkBibHeadingsToAuthorities

  my $num_headings_changed, %results = LinkBibHeadingsToAuthorities($linker, $marc, $frameworkcode, [$allowrelink]);

Links bib headings to authority records by checking each authority-controlled field in the MARC::Record object $marc, looking for a matching authority record, and setting the linking subfield $9 to the ID of that authority record.

If $allowrelink is false, existing authids will never be replaced, regardless of the values of LinkerKeepStale and LinkerRelink.

Returns the number of heading links changed in the MARC record.

GetRecordValue

  my $values = GetRecordValue($field, $record, $frameworkcode);

Get MARC fields from a keyword defined in fieldmapping table.

SetFieldMapping

  SetFieldMapping($framework, $field, $fieldcode, $subfieldcode);

Set a Field to MARC mapping value, if it already exists we don't add a new one.

DeleteFieldMapping

  DeleteFieldMapping($id);

Delete a field mapping from an $id.

GetFieldMapping

  GetFieldMapping($frameworkcode);

Get all field mappings for a specified frameworkcode

GetBiblioData

  $data = &GetBiblioData($biblionumber);

Returns information about the book with the given biblionumber. &GetBiblioData returns a reference-to-hash. The keys are the fields in the biblio and biblioitems tables in the Koha database.

In addition, $data->{subject} is the list of the book's subjects, separated by " , " (space, comma, space). If there are multiple biblioitems with the given biblionumber, only the first one is considered.

&GetBiblioItemData

  $itemdata = &GetBiblioItemData($biblioitemnumber);

Looks up the biblioitem with the given biblioitemnumber. Returns a reference-to-hash. The keys are the fields from the biblio, biblioitems, and itemtypes tables in the Koha database, except that biblioitems.notes is given as $itemdata->{bnotes}.

GetBiblioItemByBiblioNumber

NOTE : This function has been copy/paste from C4/Biblio.pm from head before zebra integration.

GetBiblionumberFromItemnumber

GetBiblioFromItemNumber

  $item = &GetBiblioFromItemNumber($itemnumber,$barcode);

Looks up the item with the given itemnumber. if undef, try the barcode.

&itemnodata returns a reference-to-hash whose keys are the fields from the biblio, biblioitems, and items tables in the Koha database.

GetISBDView

  $isbd = &GetISBDView($biblionumber);

Return the ISBD view which can be included in opac and intranet

GetBiblio

  ( $count, @results ) = &GetBiblio($biblionumber);

GetBiblioItemInfosOf

  GetBiblioItemInfosOf(@biblioitemnumbers);

FUNCTIONS FOR HANDLING MARC MANAGEMENT

GetMarcStructure

  $res = GetMarcStructure($forlibrarian,$frameworkcode);

Returns a reference to a big hash of hash, with the Marc structure for the given frameworkcode $forlibrarian :if set to 1, the MARC descriptions are the librarians ones, otherwise it's the public (OPAC) ones $frameworkcode : the framework code to read

GetUsedMarcStructure

The same function as GetMarcStructure except it just takes field in tab 0-9. (used field)

  my $results = GetUsedMarcStructure($frameworkcode);

$results is a ref to an array which each case containts a ref to a hash which each keys is the columns from marc_subfield_structure

$frameworkcode is the framework code.

GetMarcFromKohaField

  ($MARCfield,$MARCsubfield)=GetMarcFromKohaField($kohafield,$frameworkcode);

Returns the MARC fields & subfields mapped to the koha field for the given frameworkcode

GetMarcBiblio

  my $record = GetMarcBiblio($biblionumber, [$embeditems]);

Returns MARC::Record representing bib identified by $biblionumber. If no bib exists, returns undef. $embeditems. If set to true, items data are included. The MARC record contains biblio data, and items data if $embeditems is set to true.

GetXmlBiblio

  my $marcxml = GetXmlBiblio($biblionumber);

Returns biblioitems.marcxml of the biblionumber passed in parameter. The XML contains both biblio & item datas

GetCOinSBiblio

  my $coins = GetCOinSBiblio($record);

Returns the COinS (a span) which can be included in a biblio record

GetMarcPrice

return the prices in accordance with the Marc format.

GetMarcQuantity

return the quantity of a book. Used in acquisition only, when importing a file an iso2709 from a bookseller Warning : this is not really in the marc standard. In Unimarc, Electre (the most widely used bookseller) use the 969$a

GetAuthorisedValueDesc

  my $subfieldvalue =get_authorised_value_desc(
    $tag, $subf[$i][0],$subf[$i][1], '', $taglib, $category, $opac);

Retrieve the complete description for a given authorised value.

Now takes $category and $value pair too.

  my $auth_value_desc =GetAuthorisedValueDesc(
    '','', 'DVD' ,'','','CCODE');

If the optional $opac parameter is set to a true value, displays OPAC descriptions rather than normal ones when they exist.

GetMarcControlnumber

  $marccontrolnumber = GetMarcControlnumber($record,$marcflavour);

Get the control number / record Identifier from the MARC record and return it.

GetMarcISBN

  $marcisbnsarray = GetMarcISBN( $record, $marcflavour );

Get all ISBNs from the MARC record and returns them in an array. ISBNs stored in differents places depending on MARC flavour

GetMarcNotes

  $marcnotesarray = GetMarcNotes( $record, $marcflavour );

Get all notes from the MARC record and returns them in an array. The note are stored in differents places depending on MARC flavour

GetMarcSubjects

  $marcsubjcts = GetMarcSubjects($record,$marcflavour);

Get all subjects from the MARC record and returns them in an array. The subjects are stored in differents places depending on MARC flavour

GetMarcAuthors

  authors = GetMarcAuthors($record,$marcflavour);

Get all authors from the MARC record and returns them in an array. The authors are stored in differents places depending on MARC flavour

GetMarcUrls

  $marcurls = GetMarcUrls($record,$marcflavour);

Returns arrayref of URLs from MARC data, suitable to pass to tmpl loop. Assumes web resources (not uncommon in MARC21 to omit resource type ind)

GetMarcSeries

  $marcseriesarray = GetMarcSeries($record,$marcflavour);

Get all series from the MARC record and returns them in an array. The series are stored in differents places depending on MARC flavour

GetMarcHosts

  $marchostsarray = GetMarcHosts($record,$marcflavour);

Get all host records (773s MARC21, 461 UNIMARC) from the MARC record and returns them in an array.

GetFrameworkCode

  $frameworkcode = GetFrameworkCode( $biblionumber )

TransformKohaToMarc

    $record = TransformKohaToMarc( $hash )

This function builds partial MARC::Record from a hash Hash entries can be from biblio or biblioitems.

This function is called in acquisition module, to create a basic catalogue entry from user entry

PrepHostMarcField

    $hostfield = PrepHostMarcField ( $hostbiblionumber,$hostitemnumber,$marcflavour )

This function returns a host field populated with data from the host record, the field can then be added to an analytical record

TransformHtmlToXml

  $xml = TransformHtmlToXml( $tags, $subfields, $values, $indicator, 
                             $ind_tag, $auth_type )

$auth_type contains :

- nothing : rebuild a biblio. In UNIMARC the encoding is in 100$a pos 26/27
- UNIMARCAUTH : rebuild an authority. In UNIMARC, the encoding is in 100$a pos 13/14
- ITEM : rebuild an item : in UNIMARC, 100$a, it's in the biblio ! (otherwise, we would get 2 100 fields !)

_default_ind_to_space

Passed what should be an indicator returns a space if its undefined or zero length

TransformHtmlToMarc

    L<$record> = TransformHtmlToMarc(L<$cgi>)
    L<$cgi> is the CGI object which containts the values for subfields
    {
        'tag_010_indicator1_531951' ,
        'tag_010_indicator2_531951' ,
        'tag_010_code_a_531951_145735' ,
        'tag_010_subfield_a_531951_145735' ,
        'tag_200_indicator1_873510' ,
        'tag_200_indicator2_873510' ,
        'tag_200_code_a_873510_673465' ,
        'tag_200_subfield_a_873510_673465' ,
        'tag_200_code_b_873510_704318' ,
        'tag_200_subfield_b_873510_704318' ,
        'tag_200_code_e_873510_280822' ,
        'tag_200_subfield_e_873510_280822' ,
        'tag_200_code_f_873510_110730' ,
        'tag_200_subfield_f_873510_110730' ,
    }
    L<$record> is the MARC::Record object.

TransformMarcToKoha

  $result = TransformMarcToKoha( $dbh, $record, $frameworkcode )

Extract data from a MARC bib record into a hashref representing Koha biblio, biblioitems, and items fields.

_disambiguate

  $newkey = _disambiguate($table, $field);

This is a temporary hack to distinguish between the following sets of columns when using TransformMarcToKoha.

  items.cn_source & biblioitems.cn_source
  items.cn_sort & biblioitems.cn_sort

Columns that are currently NOT distinguished (FIXME due to lack of time to fully test) are:

  biblio.notes and biblioitems.notes
  biblionumber
  timestamp
  biblioitemnumber

FIXME - this is necessary because prefixing each column name with the table name would require changing lots of code and templates, and exposing more of the DB structure than is good to the UI templates, particularly since biblio and bibloitems may well merge in a future version. In the future, it would also be good to separate DB access and UI presentation field names more.

get_koha_field_from_marc

  $result->{_disambiguate($table, $field)} = 
     get_koha_field_from_marc($table,$field,$record,$frameworkcode);

Internal function to map data from the MARC record to a specific non-MARC field. FIXME: this is meant to replace TransformMarcToKohaOneField after more testing.

TransformMarcToKohaOneField

  $result = TransformMarcToKohaOneField( $kohatable, $kohafield, $record, $result, $frameworkcode )

OTHER FUNCTIONS

PrepareItemrecordDisplay

  PrepareItemrecordDisplay($itemrecord,$bibnum,$itemumber,$frameworkcode);

Returns a hash with all the fields for Display a given item data in a template

The $frameworkcode returns the item for the given frameworkcode, ONLY if bibnum is not provided

ModZebra

  ModZebra( $biblionumber, $op, $server, $oldRecord, $newRecord );

$biblionumber is the biblionumber we want to index

$op is specialUpdate or delete, and is used to know what we want to do

$server is the server that we want to update

$oldRecord is the MARC::Record containing the previous version of the record. This is used only when NoZebra=1, as NoZebra indexing needs to know the previous version of a record in order to do an update.

$newRecord is the MARC::Record containing the new record. It is usefull only when NoZebra=1, and is used to know what to add to the nozebra database. (the record in mySQL being, if it exist, the previous record, the one just before the modif. We need both : the previous and the new one.

GetNoZebraIndexes

  %indexes = GetNoZebraIndexes;

return the data from NoZebraIndexes syspref.

EmbedItemsInMarcBiblio

    EmbedItemsInMarcBiblio($marc, $biblionumber);

Given a MARC::Record object containing a bib record, modify it to include the items attached to it as 9XX per the bib's MARC framework.

INTERNAL FUNCTIONS

_DelBiblioNoZebra($biblionumber,$record,$server);

function to delete a biblio in NoZebra indexes This function does NOT delete anything in database : it reads all the indexes entries that have to be deleted & delete them in the hash

The SQL part is done either : - after the Add if we are modifying a biblio (delete + add again) - immediatly after this sub if we are doing a true deletion.

$server can be 'biblioserver' or 'authorityserver' : it indexes biblios or authorities (in the same table, $server being part of the table itself

_AddBiblioNoZebra

  _AddBiblioNoZebra($biblionumber, $record, $server, %result);

function to add a biblio in NoZebra indexes

_find_value

  ($indicators, $value) = _find_value($tag, $subfield, $record,$encoding);

Find the given $subfield in the given $tag in the given MARC::Record $record. If the subfield is found, returns the (indicators, value) pair; otherwise, (undef, undef) is returned.

PROPOSITION : Such a function is used in addbiblio AND additem and serial-edit and maybe could be used in Authorities. I suggest we export it from this module.

_koha_marc_update_bib_ids

  _koha_marc_update_bib_ids($record, $frameworkcode, $biblionumber, $biblioitemnumber);

Internal function to add or update biblionumber and biblioitemnumber to the MARC XML.

_koha_marc_update_biblioitem_cn_sort

  _koha_marc_update_biblioitem_cn_sort($marc, $biblioitem, $frameworkcode);

Given a MARC bib record and the biblioitem hash, update the subfield that contains a copy of the value of biblioitems.cn_sort.

_koha_add_biblio

  my ($biblionumber,$error) = _koha_add_biblio($dbh,$biblioitem);

Internal function to add a biblio ($biblio is a hash with the values)

_koha_modify_biblio

  my ($biblionumber,$error) == _koha_modify_biblio($dbh,$biblio,$frameworkcode);

Internal function for updating the biblio table

_koha_modify_biblioitem_nonmarc

  my ($biblioitemnumber,$error) = _koha_modify_biblioitem_nonmarc( $dbh, $biblioitem );

Updates biblioitems row except for marc and marcxml, which should be changed via ModBiblioMarc

_koha_add_biblioitem

  my ($biblioitemnumber,$error) = _koha_add_biblioitem( $dbh, $biblioitem );

Internal function to add a biblioitem

_koha_delete_biblio

  $error = _koha_delete_biblio($dbh,$biblionumber);

Internal sub for deleting from biblio table -- also saves to deletedbiblio

$dbh - the database handle

$biblionumber - the biblionumber of the biblio to be deleted

_koha_delete_biblioitems

  $error = _koha_delete_biblioitems($dbh,$biblioitemnumber);

Internal sub for deleting from biblioitems table -- also saves to deletedbiblioitems

$dbh - the database handle $biblionumber - the biblioitemnumber of the biblioitem to be deleted

UNEXPORTED FUNCTIONS

ModBiblioMarc

  &ModBiblioMarc($newrec,$biblionumber,$frameworkcode);

Add MARC data for a biblio to koha

Function exported, but should NOT be used, unless you really know what you're doing

z3950_extended_services

  z3950_extended_services($serviceType,$serviceOptions,$record);

z3950_extended_services is used to handle all interactions with Zebra's extended serices package, which is employed to perform all management of the MARC data stored in Zebra.

$serviceType one of: itemorder,create,drop,commit,update,xmlupdate

$serviceOptions a has of key/value pairs. For instance, if service_type is 'update', $service_options should contain:

 action => update action, one of specialUpdate, recordInsert, recordReplace, recordDelete, elementUpdate.

and maybe

  recordidOpaque => Opaque Record ID (user supplied) or recordidNumber => Record ID number (system number).
  syntax => the record syntax (transfer syntax)
  databaseName = Database from connection object

To set serviceOptions, call set_service_options($serviceType)

$record the record, if one is needed for the service type

A record should be in XML. You can convert it to XML from MARC by running it through marc2xml().

set_service_options

  my $serviceOptions = set_service_options($serviceType);

$serviceType itemorder,create,drop,commit,update,xmlupdate

Currently, we only support 'create', 'commit', and 'update'. 'drop' support will be added as soon as Zebra supports it.

get_biblio_authorised_values

find the types and values for all authorised values assigned to this biblio.

parameters: biblionumber MARC::Record of the bib

returns: a hashref mapping the authorised value to the value set for this biblionumber

  $authorised_values = {
                       'Scent'     => 'flowery',
                       'Audience'  => 'Young Adult',
                       'itemtypes' => 'SER',
                        };

Notes: forlibrarian should probably be passed in, and called something different.

CountBiblioInOrders

This function return count of biblios in orders with $biblionumber

GetSubscriptionsId

This function return an array of subscriptionid with $biblionumber

GetHolds

This function return the count of holds with $biblionumber

AUTHOR

Koha Development Team <http://koha-community.org/>

Paul POULAIN paul.poulain@free.fr

Joshua Ferraro jmf@liblime.com

<<