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

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.

decode

$str = &decode($chunk);

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

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:

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

CanBookBeIssued

Check if a book can be issued.

my ($issuingimpossible,$needsconfirmation) = CanBookBeIssued($borrower,$barcode,$year,$month,$day);

$borrower hash with borrower informations (from GetMemberDetails)
$barcode is the bar code of the book being issued.
$year $month $day contains the date of the return (in case it's forced by "stickyduedate".

Returns :

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

RESTRICTED

item is restricted (set by ??)

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

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.

( $issuingimpossible, $needsconfirmation ) = CanBookBeIssued( $borrower, $barcode, $duedatespec, $inprocess ); $duedatespec is a C4::Dates object. $issuingimpossible and $needsconfirmation are some hashref.

AddIssue

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

&AddIssue($borrower,$barcode,$date)

$borrower hash with borrower informations (from GetMemberDetails)
$barcode is the bar code of the book being issued.
$date contains the max date of return. calculated if empty.: 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

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

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

GetIssuingRule

FIXME - This is a copy-paste of GetLoanLength as a stop-gap. Do not wish to change API for GetLoanLength this close to release, however, Overdues::GetIssuingRules is broken.

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

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

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.

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

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

AddReturn

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

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. $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_.

&AddReturn returns a list of four items:

$doreturn is true iff the return succeeded.

$messages is a reference-to-hash giving the reason for failure:

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.
wthdrawn: This book has been withdrawn/cancelled. The value should be ignored.
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.

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

MarkIssueReturned

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

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 . Assumes you've already checked that it's safe to do this, i.e. last non-holiday > issuedate.

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

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($iteminfo,$borrower);

Calculates the charge for a book lost and returned (Not exported & used only once)

$iteminfo is a hashref to iteminfo. Only {itemnumber} is used.

$borrower is a hashref to borrower. Only {borrowernumber is used.

Internal function, called by AddReturn

GetItemIssue

$issues = &GetItemIssue($itemnumber);

Returns patrons currently having a book. nothing if item is not issued atm

$itemnumber is the itemnumber

Returns an array of hashes

GetItemIssues

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

Returns patrons that have issued a book

$itemnumber is the itemnumber $history is 0 if you want actuel "issuer" (if it exist) and 1 if you want issues history

Returns 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);

Find out whether a borrowed item may be renewed.

$dbh is a DBI handle to the Koha database.

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

$itemnumber is the number of the item to renew.

$CanBookBeRenewed returns a true value iff 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]);

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 branch. Defaults to the homebranch of the ITEM.

$datedue can be a C4::Dates object used to set the due date.

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

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 = AnonymiseIssueHistory($borrowernumber,$date)

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.

return the number of affected rows.

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,$loanlength,$branchcode); this function calculates the due date given the loan length , checking against the holidays calendar as per the 'useDaysMode' syspref. $startdate = C4::Dates object representing start date of loan period (assumed to be today) $branch = location whose calendar to use $loanlength = loan length prior to adjustment

CheckValidDatedue This function does not account for holiday exceptions nor does it handle the 'useDaysMode' syspref . To be replaced by CalcDateDue() once C4::Calendar use is tested.

$newdatedue = CheckValidDatedue($date_due,$itemnumber,$branchcode); this function validates the loan length against the holidays calendar, and adjusts the due date as per the 'useDaysMode' syspref. $date_due = returndate calculate with no day check $itemnumber = itemnumber $branchcode = location of issue (affected by 'CircControl' syspref) $loanlength = loan length prior to adjustment

CheckRepeatableHolidays

$countrepeatable = CheckRepeatableHoliday($itemnumber,$week_day,$branchcode); this function checks if the date due is a repeatable holiday $date_due = returndate calculate with no day check $itemnumber = itemnumber $branchcode = localisation of issue

CheckSpecialHolidays

$countspecial = CheckSpecialHolidays($years,$month,$day,$itemnumber,$branchcode); this function check if the date is a special holiday $years = the years of datedue $month = the month of datedue $day = the day of datedue $itemnumber = itemnumber $branchcode = localisation of issue

CheckRepeatableSpecialHolidays

$countspecial = CheckRepeatableSpecialHolidays($month,$day,$itemnumber,$branchcode); this function check if the date is a repeatble special holidays $month = the month of datedue $day = the day of datedue $itemnumber = itemnumber $branchcode = localisation of issue

AUTHOR

Koha Developement team <info@koha.org>