C4::Biblio - cataloging management functions
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:
In the 3.0 version of Koha, the authoritative record-level information is in biblio_metadata.metadata
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.
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:
The MARC record (in biblio_metadata.metadata) 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 :
( $biblionumber, $biblioitemnumber ) = AddBiblio( $record, $frameworkcode, $options );
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.
The $options
argument is a hashref with additional parameters:
disable_autolink
Unless disable_autolink
is passed AddBiblio will link record headings to authorities based on settings in the system preferences. This flag allows us to not link records when the authority linker is saving modifications.
ModBiblio($record, $biblionumber, $frameworkcode, $options);
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.
The $options
argument is a hashref with additional parameters:
overlay_context
This parameter is forwarded to "ApplyMarcOverlayRules" where it is used for selecting the current rule set if MARCOverlayRules is enabled. See "ApplyMarcOverlayRules" for more details.
disable_autolink
Unless disable_autolink
is passed ModBiblio will relink record headings to authorities based on settings in the system preferences. This flag allows us to not relink records when the authority linker is saving modifications.
skip_holds_queue
Unless skip_holds_queue
is passed, ModBiblio will trigger the BatchUpdateBiblioHoldsQueue task to rebuild the holds queue for the biblio if RealTimeHoldsQueue is enabled.
skip_record_index
Used when the indexing schedulling will be handled by the caller
record_source_id
Set as the record source when saving the record.
Returns 1 on success 0 on failure
_strip_item_fields($record, $frameworkcode)
Utility routine to remove item tags from a MARC bib.
my $error = &DelBiblio($biblionumber, $params);
Exported function (core API) for deleting a biblio in koha. Deletes biblio record from Zebra and Koha tables (biblio & biblioitems) Also backs it up to deleted* tables. Checks to make sure that the biblio has no items attached. return: $error
: undef unless an error occurs
$params is a hashref containing extra parameters. Valid keys are:
my $headings_linked = BiblioAutoLink($record, $frameworkcode)
Automatically links headings in a bib record to authorities.
Returns the number of headings changed
my $num_headings_changed, %results = LinkBibHeadingsToAuthorities($linker, $marc, $frameworkcode, [$allowrelink, $tagtolink, $verbose]);
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.
if ( _check_valid_auth_link($authid, $field) ) { ... }
Check whether the specified heading-auth link is valid without reference to Zebra. Ideally this code would be in C4::Heading, but that won't be possible until we have de-cycled C4::AuthoritiesMarc, so this is the safest place.
$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.
$isbd = &GetISBDView({ 'record' => $marc_record, 'template' => $interface, # opac/intranet 'framework' => $framework, });
Return the ISBD view which can be included in opac and intranet
my $tagslib = C4::Biblio::GetMarcStructure(); for my $tag ( sort keys %$tagslib ) { next unless $tag; for my $subfield ( sort keys %{ $tagslib->{$tag} } ) { next if IsMarcStructureInternal($tagslib->{$tag}{$subfield}); } # Process subfield }
GetMarcStructure creates keys (lib, tab, mandatory, repeatable, important) for a display purpose. These different values should not be processed as valid subfields.
$res = GetMarcStructure($forlibrarian, $frameworkcode, [ $params ]);
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 $params allows you to pass { unsafe => 1 } for better performance.
Note: If you call GetMarcStructure with unsafe => 1, do not modify or even autovivify its contents. It is a cached/shared data structure. Your changes c/would be passed around in subsequent calls.
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 contains a ref to a hash which each keys is the columns from marc_subfield_structure
$frameworkcode
is the framework code.
my $structure = GetMarcSubfieldStructure($frameworkcode, [$params]);
Returns a reference to hash representing MARC subfield structure for framework with framework code $frameworkcode
, $params
is optional and may contain additional options.
$frameworkcode
The framework code.
$params
An optional hash reference with additional options. The following options are supported:
Pass { unsafe => 1 } do disable cached object cloning, and instead get a shared reference, resulting in better performance (but care must be taken so that retured object is never modified).
Note: If you call GetMarcSubfieldStructure with unsafe => 1, do not modify or even autovivify its contents. It is a cached/shared data structure. Your changes would be passed around in subsequent calls.
my ( $field, $subfield ) = GetMarcFromKohaField($kohafield); my ( $f1, $sf1, $f2, $sf2 ) = GetMarcFromKohaField($kohafield); Returns list of MARC fields and subfields mapped to $kohafield. Since the Default framework is considered as authoritative for such mappings, the former frameworkcode parameter is obsoleted. NOTE: There may be multiple mappings! In the first example above you could miss the second mapping (although only a few of these will normally exist). Calling in scalar context has been deprecated as of 10/2023.
my $arrayref = GetMarcSubfieldStructureFromKohaField($kohafield); my $hashref = GetMarcSubfieldStructureFromKohaField($kohafield)->[0]; Returns marc subfield structure information for $kohafield. The Default framework is used, since it is authoritative for kohafield mappings. Since there MAY be multiple mappings (not that often), you receive an arrayref of all mappings found. In the second example above the first one is picked only. If there are no mappings, you get an empty arrayref (so in the call above $hashref will be undefined - without warnings).
my $marcxml = GetXmlBiblio($biblionumber);
Returns biblio_metadata.metadata/marcxml of the biblionumber passed in parameter. The XML should only contain biblio information (item information is no longer stored in marcxml field)
return the prices in accordance with the Marc format.
returns 0 if no price found returns undef if called without a marc record or with an unrecognized marc format
Return the best guess at what the actual price is from a price field.
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
returns 0 if no quantity found returns undef if called without a marc record or with an unrecognized marc format
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.
$marcisbnsarray = GetMarcISBN( $record, $marcflavour );
Get all ISBNs from the MARC record and returns them in an array. ISBNs stored in different fields depending on MARC flavour
$marcissnsarray = GetMarcISSN( $record, $marcflavour );
Get all valid ISSNs from the MARC record and returns them in an array. ISSNs are stored in different fields depending on MARC flavour
$marcsubjcts = GetMarcSubjects($record,$marcflavour);
Get all subjects from the MARC record and returns them in an array. The subjects are stored in different fields depending on MARC flavour
$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)
$marcseriesarray = GetMarcSeries($record,$marcflavour);
Get all series from the MARC record and returns them in an array. The series are stored in different fields depending on MARC flavour
my $record = C4::Biblio::UpsertMarcSubfield($MARC::Record, $fieldTag, $subfieldCode, $subfieldContent);
my $record = C4::Biblio::UpsertMarcControlField($MARC::Record, $fieldTag, $content);
$frameworkcode = GetFrameworkCode( $biblionumber )
$record = TransformKohaToMarc( $hash [, $params ] )
This function builds a (partial) MARC::Record from a hash. Hash entries can be from biblio, biblioitems or items. The params hash includes the parameter no_split used in C4::Items.
This function is called in acquisition module, to create a basic catalogue entry from user entry.
$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
$xml = TransformHtmlToXml( $tags, $subfields, $values, $indicator, $ind_tag, $auth_type )
$auth_type contains :
Passed what should be an indicator returns a space if its undefined or zero length
L<$record> = TransformHtmlToMarc(L<$cgi>) L<$cgi> is the CGI object which contains 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.
$result = TransformMarcToKoha({ record => $record, limit_table => $limit })
Extract data from a MARC bib record into a hashref representing Koha biblio, biblioitems, and items fields.
If passed an undefined record will log the error and return an empty hash_ref.
$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.
Helper routine for TransformMarcToKoha
my $count = CountItemsIssued( $biblionumber );
ModZebra( $record_number, $op, $server );
$record_number is the authid or biblionumber we want to index
$op is the operation: specialUpdate or recordDelete
$server is authorityserver or biblioserver
_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($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.
my ($biblionumber,$error) == _koha_modify_biblio($dbh,$biblio,$frameworkcode);
Internal function for updating the biblio table
my ($biblioitemnumber,$error) = _koha_modify_biblioitem_nonmarc( $dbh, $biblioitem );
$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
$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
$error = _koha_delete_biblio_metadata($biblionumber);
$biblionumber
- the biblionumber of the biblio metadata to be deleted
ModBiblioMarc( $newrec, $biblionumber, $options );
Add MARC XML data for a biblio to koha
Function exported, but should NOT be used, unless you really know what you're doing
The $options
argument is a hashref with additional parameters:
$marcfield = prepare_host_field( $hostbiblioitem, $marcflavour ); Generate the host item entry for an analytic child entry
UpdateTotalIssues($biblionumber, $increase, [$value])
Update the total issue count for a particular bib record.
$biblionumber
is the biblionumber of the bib to update$increase
is the amount to increase (or decrease) the total issues count by$value
is the absolute value that total issues count should be set to. If provided, $increase
is ignored.$skip_holds_queue
parameter to optionally skip updating the holds queue.&RemoveAllNsb($record);
Removes all nsb/nse chars from a record
my $record = ApplyMarcOverlayRules($params)
Applies marc merge rules to a record.
$params
is expected to be a hashref with below keys defined.
biblionumber
biblionumber of old recordrecord
Incoming record that will be merged with old recordoverlay_context
hashref containing at least one context module and filter value on the form {module => filter, ...}.Returns:
$record
Merged MARC record based with merge rules for context
applied. If no old record for biblionumber
can be found, record
is returned unchanged. Default action when no matching context is found to return record
unchanged. If no rules are found for a certain field tag the default is to overwrite with fields with this field tag from record
.
Helper method that takes care of calling all plugin hooks
Koha Development Team <http://koha-community.org/>
Paul POULAIN paul.poulain@free.fr
Joshua Ferraro jmf@liblime.com