<<

NAME

C4::Circulation - Koha circulation module

SYNOPSIS

use C4::Circulation;

DESCRIPTION

The functions in this module deal with circulation, issues, and returns, as well as general information about the library. Also deals with stocktaking.

FUNCTIONS

barcodedecode

  $str = &barcodedecode($barcode, [$filter]);

Generic filter function for barcode string. Called on every circ if the System Pref itemBarcodeInputFilter is set. Will do some manipulation of the barcode for systems that deliver a barcode to circulation.pl that differs from the barcode stored for the item. For proper functioning of this filter, calling the function on the correct barcode string (items.barcode) should return an unaltered barcode.

The optional $filter argument is to allow for testing or explicit behavior that ignores the System Pref. Valid values are the same as the System Pref options.

decode

  $str = &decode($chunk);

Decodes a segment of a string emitted by a CueCat barcode scanner and returns it.

FIXME: Should be replaced with Barcode::Cuecat from CPAN or Javascript based decoding on the client side.

transferbook

  ($dotransfer, $messages, $iteminformation) = &transferbook($newbranch, 
                                            $barcode, $ignore_reserves);

Transfers an item to a new branch. If the item is currently on loan, it is automatically returned before the actual transfer.

$newbranch is the code for the branch to which the item should be transferred.

$barcode is the barcode of the item to be transferred.

If $ignore_reserves is true, &transferbook ignores reserves. Otherwise, if an item is reserved, the transfer fails.

Returns three values:

$dotransfer

is true if the transfer was successful.

$messages

is a reference-to-hash which may have any of the following keys:

BadBarcode

There is no item in the catalog with the given barcode. The value is $barcode.

IsPermanent

The item's home branch is permanent. This doesn't prevent the item from being transferred, though. The value is the code of the item's home branch.

DestinationEqualsHolding

The item is already at the branch to which it is being transferred. The transfer is nonetheless considered to have failed. The value should be ignored.

WasReturned

The item was on loan, and &transferbook automatically returned it before transferring it. The value is the borrower number of the patron who had the item.

ResFound

The item was reserved. The value is a reference-to-hash whose keys are fields from the reserves table of the Koha database, and biblioitemnumber. It also has the key ResFound, whose value is either Waiting or Reserved.

WasTransferred

The item was eligible to be transferred. Barring problems communicating with the database, the transfer should indeed have succeeded. The value should be ignored.

itemissues

  @issues = &itemissues($biblioitemnumber, $biblio);

Looks up information about who has borrowed the book(s) with the given biblioitemnumber.

$biblio is ignored.

&itemissues returns an array of references-to-hash. The keys include the fields from the items table in the Koha database. Additional keys include:

date_due

If the item is currently on loan, this gives the due date.

If the item is not on loan, then this is either "Available" or "Cancelled", if the item has been withdrawn.

card

If the item is currently on loan, this gives the card number of the patron who currently has the item.

timestamp0, timestamp1, timestamp2

These give the timestamp for the last three times the item was borrowed.

card0, card1, card2

The card number of the last three patrons who borrowed this item.

borrower0, borrower1, borrower2

The borrower number of the last three patrons who borrowed this item.

CanBookBeIssued

  ( $issuingimpossible, $needsconfirmation ) =  CanBookBeIssued( $borrower, 
                      $barcode, $duedate, $inprocess, $ignore_reserves );

Check if a book can be issued.

$issuingimpossible and $needsconfirmation are some hashref.

$borrower hash with borrower informations (from GetMember or GetMemberDetails)
$barcode is the bar code of the book being issued.
$duedates is a DateTime object.
$inprocess boolean switch =item $ignore_reserves boolean switch

Returns :

$issuingimpossible a reference to a hash. It contains reasons why issuing is impossible. Possible values are :

INVALID_DATE

sticky due date is invalid

GNA

borrower gone with no address

CARD_LOST

borrower declared it's card lost

DEBARRED

borrower debarred

UNKNOWN_BARCODE

barcode unknown

NOT_FOR_LOAN

item is not for loan

WTHDRAWN

item withdrawn.

RESTRICTED

item is restricted (set by ??)

$needsconfirmation a reference to a hash. It contains reasons why the loan could be prevented, but ones that can be overriden by the operator.

Possible values are :

DEBT

borrower has debts.

RENEW_ISSUE

renewing, not issuing

ISSUED_TO_ANOTHER

issued to someone else.

RESERVED

reserved for someone else.

INVALID_DATE

sticky due date is invalid or due date in the past

TOO_MANY

if the borrower borrows to much things

CanBookBeReturned

  ($returnallowed, $message) = CanBookBeReturned($item, $branch)

Check whether the item can be returned to the provided branch

$item is a hash of item information as returned from GetItem
$branch is the branchcode where the return is taking place

Returns:

$returnallowed is 0 or 1, corresponding to whether the return is allowed (1) or not (0)
$message is the branchcode where the item SHOULD be returned, if the return is not allowed

CheckHighHolds

    used when syspref decreaseLoanHighHolds is active. Returns 1 or 0 to define whether the minimum value held in
    decreaseLoanHighHoldsValue is exceeded, the total number of outstanding holds, the number of days the loan
    has been decreased to (held in syspref decreaseLoanHighHoldsValue), and the new due date

AddIssue

  &AddIssue($borrower, $barcode, [$datedue], [$cancelreserve], [$issuedate])

Issue a book. Does no check, they are done in CanBookBeIssued. If we reach this sub, it means the user confirmed if needed.

$borrower is a hash with borrower informations (from GetMember or GetMemberDetails).
$barcode is the barcode of the item being issued.
$datedue is a DateTime object for the max date of return, i.e. the date due (optional). Calculated if empty.
$cancelreserve is 1 to override and cancel any pending reserves for the item (optional).
$issuedate is the date to issue the item in iso (YYYY-MM-DD) format (optional). Defaults to today. Unlike $datedue, NOT a DateTime object, unfortunately.

AddIssue does the following things :

  - step 01: check that there is a borrowernumber & a barcode provided
  - check for RENEWAL (book issued & being issued to the same patron)
      - renewal YES = Calculate Charge & renew
      - renewal NO  =
          * BOOK ACTUALLY ISSUED ? do a return if book is actually issued (but to someone else)
          * RESERVE PLACED ?
              - fill reserve if reserve to this patron
              - cancel reserve or not, otherwise
          * TRANSFERT PENDING ?
              - complete the transfert
          * ISSUE THE BOOK

GetLoanLength

  my $loanlength = &GetLoanLength($borrowertype,$itemtype,branchcode)

Get loan length for an itemtype, a borrower type and a branch

GetHardDueDate

  my ($hardduedate,$hardduedatecompare) = &GetHardDueDate($borrowertype,$itemtype,branchcode)

Get the Hard Due Date and it's comparison for an itemtype, a borrower type and a branch

GetIssuingRule

  my $irule = &GetIssuingRule($borrowertype,$itemtype,branchcode)

FIXME - This is a copy-paste of GetLoanLength as a stop-gap. Do not wish to change API for GetLoanLength this close to release.

Get the issuing rule for an itemtype, a borrower type and a branch Returns a hashref from the issuingrules table.

GetBranchBorrowerCircRule

  my $branch_cat_rule = GetBranchBorrowerCircRule($branchcode, $categorycode);

Retrieves circulation rule attributes that apply to the given branch and patron category, regardless of item type. The return value is a hashref containing the following key:

maxissueqty - maximum number of loans that a patron of the given category can have at the given branch. If the value is undef, no limit.

maxonsiteissueqty - maximum of on-site checkouts that a patron of the given category can have at the given branch. If the value is undef, no limit.

This will first check for a specific branch and category match from branch_borrower_circ_rules.

If no rule is found, it will then check default_branch_circ_rules (same branch, default category). If no rule is found, it will then check default_borrower_circ_rules (default branch, same category), then failing that, default_circ_rules (default branch, default category).

If no rule has been found in the database, it will default to the buillt in rule:

maxissueqty - undef maxonsiteissueqty - undef

$branchcode and $categorycode should contain the literal branch code and patron category code, respectively - no wildcards.

GetBranchItemRule

  my $branch_item_rule = GetBranchItemRule($branchcode, $itemtype);

Retrieves circulation rule attributes that apply to the given branch and item type, regardless of patron category.

The return value is a hashref containing the following keys:

holdallowed => Hold policy for this branch and itemtype. Possible values: 0: No holds allowed. 1: Holds allowed only by patrons that have the same homebranch as the item. 2: Holds allowed from any patron.

returnbranch => branch to which to return item. Possible values: noreturn: do not return, let item remain where checked in (floating collections) homebranch: return to item's home branch holdingbranch: return to issuer branch

This searches branchitemrules in the following order:

  * Same branchcode and itemtype
  * Same branchcode, itemtype '*'
  * branchcode '*', same itemtype
  * branchcode and itemtype '*'

Neither $branchcode nor $itemtype should be '*'.

AddReturn

  ($doreturn, $messages, $iteminformation, $borrower) =
      &AddReturn( $barcode, $branch [,$exemptfine] [,$dropbox] [,$returndate] );

Returns a book.

$barcode is the bar code of the book being returned.
$branch is the code of the branch where the book is being returned.
$exemptfine indicates that overdue charges for the item will be removed. Optional.
$dropbox indicates that the check-in date is assumed to be yesterday, or the last non-holiday as defined in C4::Calendar . If overdue charges are applied and $dropbox is true, the last charge will be removed. This assumes that the fines accrual script has run for _today_. Optional.
$return_date allows the default return date to be overridden by the given return date. Optional.

&AddReturn returns a list of four items:

$doreturn is true iff the return succeeded.

$messages is a reference-to-hash giving feedback on the operation. The keys of the hash are:

BadBarcode

No item with this barcode exists. The value is $barcode.

NotIssued

The book is not currently on loan. The value is $barcode.

IsPermanent

The book's home branch is a permanent collection. If you have borrowed this book, you are not allowed to return it. The value is the code for the book's home branch.

withdrawn

This book has been withdrawn/cancelled. The value should be ignored.

Wrongbranch

This book has was returned to the wrong branch. The value is a hashref so that $messages-{Wrongbranch}->{Wrongbranch}> and $messages-{Wrongbranch}->{Rightbranch}> contain the branchcode of the incorrect and correct return library, respectively.

ResFound

The item was reserved. The value is a reference-to-hash whose keys are fields from the reserves table of the Koha database, and biblioitemnumber. It also has the key ResFound, whose value is either Waiting, Reserved, or 0.

WasReturned

Value 1 if return is successful.

NeedsTransfer

If AutomaticItemReturn is disabled, return branch is given as value of NeedsTransfer.

$iteminformation is a reference-to-hash, giving information about the returned item from the issues table.

$borrower is a reference-to-hash, giving information about the patron who last borrowed the book.

MarkIssueReturned

  MarkIssueReturned($borrowernumber, $itemnumber, $dropbox_branch, $returndate, $privacy);

Unconditionally marks an issue as being returned by moving the issues row to old_issues and setting returndate to the current date, or the last non-holiday date of the branccode specified in dropbox_branch . Assumes you've already checked that it's safe to do this, i.e. last non-holiday > issuedate.

if $returndate is specified (in iso format), it is used as the date of the return. It is ignored when a dropbox_branch is passed in.

$privacy contains the privacy parameter. If the patron has set privacy to 2, the old_issue is immediately anonymised

Ideally, this function would be internal to C4::Circulation, not exported, but it is currently needed by one routine in C4::Accounts.

_debar_user_on_return

    _debar_user_on_return($borrower, $item, $datedue, today);

$borrower borrower hashref

$item item hashref

$datedue date due DateTime object

$today DateTime object representing the return time

Internal function, called only by AddReturn that calculates and updates the user fine days, and debars him if necessary.

Should only be called for overdue returns

_FixOverduesOnReturn

   &_FixOverduesOnReturn($brn,$itm, $exemptfine, $dropboxmode);

$brn borrowernumber

$itm itemnumber

$exemptfine BOOL -- remove overdue charge associated with this issue. $dropboxmode BOOL -- remove lastincrement on overdue charge associated with this issue.

Internal function, called only by AddReturn

_FixAccountForLostAndReturned

  &_FixAccountForLostAndReturned($itemnumber, [$borrowernumber, $barcode]);

Calculates the charge for a book lost and returned.

Internal function, not exported, called only by AddReturn.

FIXME: This function reflects how inscrutable fines logic is. Fix both. FIXME: Give a positive return value on success. It might be the $borrowernumber who received credit, or the amount forgiven.

_GetCircControlBranch

   my $circ_control_branch = _GetCircControlBranch($iteminfos, $borrower);

Internal function :

Return the library code to be used to determine which circulation policy applies to a transaction. Looks up the CircControl and HomeOrHoldingBranch system preferences.

$iteminfos is a hashref to iteminfo. Only {homebranch or holdingbranch} is used.

$borrower is a hashref to borrower. Only {branchcode} is used.

GetItemIssue

  $issue = &GetItemIssue($itemnumber);

Returns patron currently having a book, or undef if not checked out.

$itemnumber is the itemnumber.

$issue is a hashref of the row from the issues table.

GetOpenIssue

  $issue = GetOpenIssue( $itemnumber );

Returns the row from the issues table if the item is currently issued, undef if the item is not currently issued

$itemnumber is the item's itemnumber

Returns a hashref

GetIssues

    $issues = GetIssues({});    # return all issues!
    $issues = GetIssues({ borrowernumber => $borrowernumber, biblionumber => $biblionumber });

Returns all pending issues that match given criteria. Returns a arrayref or undef if an error occurs.

Allowed criteria are:

GetItemIssues

  $issues = &GetItemIssues($itemnumber, $history);

Returns patrons that have issued a book

$itemnumber is the itemnumber $history is false if you just want the current "issuer" (if any) and true if you want issues history from old_issues also.

Returns reference to an array of hashes

GetBiblioIssues

  $issues = GetBiblioIssues($biblionumber);

this function get all issues from a biblionumber.

Return: $issues is a reference to array which each value is ref-to-hash. This ref-to-hash containts all column from tables issues and the firstname,surname & cardnumber from borrowers.

GetUpcomingDueIssues

  my $upcoming_dues = GetUpcomingDueIssues( { days_in_advance => 4 } );

CanBookBeRenewed

  ($ok,$error) = &CanBookBeRenewed($borrowernumber, $itemnumber[, $override_limit]);

Find out whether a borrowed item may be renewed.

$borrowernumber is the borrower number of the patron who currently has the item on loan.

$itemnumber is the number of the item to renew.

$override_limit, if supplied with a true value, causes the limit on the number of times that the loan can be renewed (as controlled by the item type) to be ignored. Overriding also allows to renew sooner than "No renewal before" and to manually renew loans that are automatically renewed.

$CanBookBeRenewed returns a true value if the item may be renewed. The item must currently be on loan to the specified borrower; renewals must be allowed for the item's type; and the borrower must not have already renewed the loan. $error will contain the reason the renewal can not proceed

AddRenewal

  &AddRenewal($borrowernumber, $itemnumber, $branch, [$datedue], [$lastreneweddate]);

Renews a loan.

$borrowernumber is the borrower number of the patron who currently has the item.

$itemnumber is the number of the item to renew.

$branch is the library where the renewal took place (if any). The library that controls the circ policies for the renewal is retrieved from the issues record.

$datedue can be a DateTime object used to set the due date.

$lastreneweddate is an optional ISO-formatted date used to set issues.lastreneweddate. If this parameter is not supplied, lastreneweddate is set to the current date.

If $datedue is the empty string, &AddRenewal will calculate the due date automatically from the book's item type.

GetSoonestRenewDate

  $NoRenewalBeforeThisDate = &GetSoonestRenewDate($borrowernumber, $itemnumber);

Find out the soonest possible renew date of a borrowed item.

$borrowernumber is the borrower number of the patron who currently has the item on loan.

$itemnumber is the number of the item to renew.

$GetSoonestRenewDate returns the DateTime of the soonest possible renew date, based on the value "No renewal before" of the applicable issuing rule. Returns the current date if the item can already be renewed, and returns undefined if the borrower, loan, or item cannot be found.

GetIssuingCharges

  ($charge, $item_type) = &GetIssuingCharges($itemnumber, $borrowernumber);

Calculate how much it would cost for a given patron to borrow a given item, including any applicable discounts.

$itemnumber is the item number of item the patron wishes to borrow.

$borrowernumber is the patron's borrower number.

&GetIssuingCharges returns two values: $charge is the rental charge, and $item_type is the code for the item's item type (e.g., VID if it's a video).

AddIssuingCharge

  &AddIssuingCharge( $itemno, $borrowernumber, $charge )

GetTransfers

  GetTransfers($itemnumber);

GetTransfersFromTo

  @results = GetTransfersFromTo($frombranch,$tobranch);

Returns the list of pending transfers between $from and $to branch

DeleteTransfer

  &DeleteTransfer($itemnumber);

AnonymiseIssueHistory

  ($rows,$err_history_not_deleted) = AnonymiseIssueHistory($date,$borrowernumber)

This function write NULL instead of $borrowernumber given on input arg into the table issues. if $borrowernumber is not set, it will delete the issue history for all borrower older than $date.

If c<$borrowernumber> is set, it will delete issue history for only that borrower, regardless of their opac privacy setting (force delete).

return the number of affected rows and a value that evaluates to true if an error occurred deleting the history.

SendCirculationAlert

Send out a check-in or checkout alert using the messaging system.

Parameters:

type

Valid values for this parameter are: CHECKIN and CHECKOUT.

item

Hashref of information about the item being checked in or out.

borrower

Hashref of information about the borrower of the item.

branch

The branchcode from where the checkout or check-in took place.

Example:

    SendCirculationAlert({
        type     => 'CHECKOUT',
        item     => $item,
        borrower => $borrower,
        branch   => $branch,
    });

updateWrongTransfer

  $items = updateWrongTransfer($itemNumber,$borrowernumber,$waitingAtLibrary,$FromLibrary);

This function validate the line of brachtransfer but with the wrong destination (mistake from a librarian ...), and create a new line in branchtransfer from the actual library to the original library of reservation

UpdateHoldingbranch

  $items = UpdateHoldingbranch($branch,$itmenumber);

Simple methode for updating hodlingbranch in items BDD line

CalcDateDue

$newdatedue = CalcDateDue($startdate,$itemtype,$branchcode,$borrower);

this function calculates the due date given the start date and configured circulation rules, checking against the holidays calendar as per the 'useDaysMode' syspref. $startdate = DateTime object representing start date of loan period (assumed to be today) $itemtype = itemtype code of item in question $branch = location whose calendar to use $borrower = Borrower object $isrenewal = Boolean: is true if we want to calculate the date due for a renewal. Else is false.

IsBranchTransferAllowed

  $allowed = IsBranchTransferAllowed( $toBranch, $fromBranch, $code );

Code is either an itemtype or collection doe depending on the pref BranchTransferLimitsType

CreateBranchTransferLimit

  CreateBranchTransferLimit( $toBranch, $fromBranch, $code );

$code is either itemtype or collection code depending on what the pref BranchTransferLimitsType is set to.

DeleteBranchTransferLimits

    my $result = DeleteBranchTransferLimits($frombranch);

Deletes all the library transfer limits for one library. Returns the number of limits deleted, 0e0 if no limits were deleted, or undef if no arguments are supplied.

TransferSlip

  TransferSlip($user_branch, $itemnumber, $barcode, $to_branch)

  Returns letter hash ( see C4::Letters::GetPreparedLetter ) or undef

CheckIfIssuedToPatron

  CheckIfIssuedToPatron($borrowernumber, $biblionumber)

  Return 1 if any record item is issued to patron, otherwise return 0

IsItemIssued

  IsItemIssued( $itemnumber )

  Return 1 if the item is on loan, otherwise return 0

GetAgeRestriction

  my ($ageRestriction, $daysToAgeRestriction) = GetAgeRestriction($record_restrictions, $borrower);
  my ($ageRestriction, $daysToAgeRestriction) = GetAgeRestriction($record_restrictions);

  if($daysToAgeRestriction <= 0) { #Borrower is allowed to access this material, as he is older or as old as the agerestriction }
  if($daysToAgeRestriction > 0) { #Borrower is this many days from meeting the agerestriction }

@PARAM1 the koha.biblioitems.agerestriction value, like K18, PEGI 13, ... @PARAM2 a borrower-object with koha.borrowers.dateofbirth. (OPTIONAL) @RETURNS The age restriction age in years and the days to fulfill the age restriction for the given borrower. Negative days mean the borrower has gone past the age restriction age.

GetPendingOnSiteCheckouts

AUTHOR

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

<<