[Koha] API for circulation interfaces

[Tonnesen Steve]

Here is a proposed list of functions necessary to generate arbitrary
circulation interfaces.  Comments requested.

Is this an appropriate forum for programming discussion?



Program API for circulation interfaces:

====================
getpatroninformation
====================
Subroutine returns a hash reference with all patron information.  Can be called
with either borrowernumber or cardnumber.

($env, $patroninformation) = getpatroninformation($env,$borrowernumber,$cardnumber)


=============
currentissues
=============

Returns a hash reference (itemnumber => duedate)

($env, $currentissues) = currentissues($env, $borrowernumber);


==================
getiteminformation
==================

Subroutine returns a hash reference with all item information.  Can be called
with either itemnumber or barcode.

($env, $iteminformation) = getiteminformation($env,$itemnumber,$barcode)


============
findborrower
============

Subroutine returns an array reference containing a list of borrowernumbers that match $key.  $key could be a cardnumber or a partial last name.

($env, $borrowernumber) = findborrower($env, $key)


=========
issuebook
=========

This subroutine may or may not generate additional questions that must be answered.

($env, $itemnumber, $rejected, $question, $questionnumber, $defaultanswer, $responses) =
    issuebook($env,$borrowernumber,$barcode)

Subroutine must handle errors, some that block issuing, some that must be
approved before issuing.

If $rejected is not null, it will contain a message detailing the reason for
rejection.  Possible responses are listed below, prepended with 'Error:'.
Alternatively, $rejected may just be '-1' in which case the issue should be
rejected with no message displayed to the user.  This might happen if the
answer to a question resulted in a rejection.

Error: Invalid barcode _____
Error: Invalid borrowernumber ____
Error: Item is restricted  [$item->{'notforloan'}==1]
Error: Item withdrawn [$item->{'withdrawn'}==1]
Error: Restricted Item (and borrower not allowed to check out)
    [$item->{'restricted'}==1]
Error: Reference item not for loan [$item->{'itemtype'} eq 'REF']
    [Circulation::Renewals::renewstatus]
Error: Issued to this patron, no renewals. 


If $question is not null, it will contain a YesNo question that should be
asked.  $defaultanswer will contain 'Y' or 'N'.  $questionnumber will contain a
unique integer for each question that might be asked.  Interface code will
generate a hash reference ($responses) with the responsees to each question
asked and then recall issuebook() until the issue is accepted or rejected.

Question: Already issued to this patron and reserved to ___, renew?  default N
Question: Already issued to this patron, renew?
    [$newdate=C4::Circulation::Renewals::renewbook()]
Question: Already issued to patron ___, mark as returned?
    [returnrecord()]

calculate any charges   [calc_charges()] and [createcharge()]



==========
returnbook
==========

Subroutine for returning a book.  $message may contain an arbitrary message to display to the user (maybe should be an array reference for multiple messages?).

($env, $itemnumber, $borrowernumber, $message, $overduefees) = returnbook($env,$barcode)

Message: Reserved for collection at branch _______
Calculate any overdue fees (not in current Circulation code)

[UpdateStats]