From b08d0270fef9210c27539b8290fcab3ce9de7e2b Mon Sep 17 00:00:00 2001 From: djfiander Date: Mon, 15 May 2006 00:16:42 +0000 Subject: [PATCH] Initial pass at documentation for ILS::Item --- ILS/Item.pod | 231 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 231 insertions(+) create mode 100644 ILS/Item.pod diff --git a/ILS/Item.pod b/ILS/Item.pod new file mode 100644 index 0000000..6420b57 --- /dev/null +++ b/ILS/Item.pod @@ -0,0 +1,231 @@ +=head1 NAME + +ILS::Item - Portable Item status object class for SIP + +=head1 SYNOPSIS + + use ILS; + use ILS::Item; + + # Look up item based on item_id + my $item = new ILS::Item $item_id; + + # Basic object access methods + $item_id = $item->id; + $title = $item->title_id; + $media_type = $item->sip_media_type; + $bool = $item->magnetic; + $locn = $item->permanent_location; + $locn = $item->current_location; + $props = $item->sip_item_props; + $owner = $item->owner; + $str = $item->sip_circulation_status; + $bool = $item->available; + @hold_queue = $item->hold_queue; + $pos = $item->hold_queue_position($patron_id); + $due = $item->due_date; + $pickup = $item->hold_pickup_date; + $recall = $item->recall_date; + $fee = $item->fee; + $currency = $item->fee_currency; + $type = $item->sip_fee_type; + $mark = $item->sip_security_marker; + $msg = $item->screen_msg; + $msg = $item->print_line; + + # Operations on items + $status = $item->status_update($item_props); + +=head1 DESCRIPTION + +An C object holds the information necessary to +circulate an item in the library's collection. It does not need +to be a complete bibliographic description of the item; merely +basic human-appropriate identifying information is necessary +(that is, not the barcode, but just a title, and maybe author). + +For the most part, Cs are not operated on directly, +but are passed to C methods as part of a transaction. That +is, rather than having an item check itself in: + + $item->checkin; + +the code tells the ILS that the item has returned: + + $ils->checkin($item_id); + +Similarly, patron's don't check things out (a la, +C<$patron-Echeckout($item)>), but the ILS checks items out to +patrons. This means that the methods that are defined for items +are, almost exclusively, methods to retrieve information about +the state of the item. + +=over + +=item C<$item_id = $item-Eid> + +Return the item ID, or barcode, of C<$item>. + +=item C<$title = $item-Etitle_id> + +Return the title, or some other human-relevant description, of +the item. + +=item C<$media_type = $item-Emedia_type> + +Return the SIP-defined media type of the item. The specification +provides the following definitions: + + 000 Other + 001 Book + 002 Magazine + 003 Bound journal + 004 Audio tape + 005 Video tape + 006 CD/CDROM + 007 Diskette + 008 Book with diskette + 009 Book with CD + 010 Book with audio tape + +The SIP server does not use the media type code to alter its +behavior at all; it merely passes it through to the self-service +terminal. In particular, it does not set indicators related to +whether an item is magnetic, or whether it should be +desensitized, based on this return type. The +C<$item-Emagnetic> method will be used for that purpose. + +=item C + +Is the item some form of magnetic media (eg, a video or a book +with an accompanying floppy)? This method will not be called +unless + + $ils->supports('magnetic media') + +returns C. + +If this method is defined, it is assumed to return either C +or C for every item. If the magnetic media indication is +not supported by the ILS, then the SIP server will indicate that +all items are 'Unknown'. + +=item C<$locn = $item-Epermanent_location> + +Where does this item normally reside? The protocol specification +is not clear on whether this is the item's "home branch", or a +location code within the branch, merely stating that it is, "The +location where an item is normally stored after being checked +in." + +=item C<$locn = $item-Ecurrent_location> + +According to the protocol, "[T]he current location of the item. +[A checkin terminal] could set this field to the ... system +terminal location on a Checkin message." + +=item C<$props = $item-Esip_item_props> + +Returns "item properties" associated with the item. This is an +(optional) opaque string that is passed between the self-service +terminals and the ILS. It can be set by the terminal, and should +be stored in the ILS if it is. + +=item C<$owner = $item-Eowner> + +The spec says, "This field might contain the name of the +institution or library that owns the item." + +=item C<$str = $item-Esip_circulation_status> + +Returns a two-character string describing the circulation status +of the item, as defined in the specification: + + 01 Other + 02 On order + 03 Available + 04 Charged + 05 Charged; not to be recalled until earliest recall date + 06 In process + 07 Recalled + 08 Waiting on hold shelf + 09 Waiting to be re-shelved + 10 In transit between library locations + 11 Claimed returned + 12 Lost + 13 Missing + +=item C<$bool = $item-Eavailable> + +Is the item available? That is, not checked out, and not on the +hold shelf? + +=item C<@hold_queue = $item-Ehold_queue> + +Returns a list of the C<$patron_id>s of the patrons that have +outstanding holds on the item. + +=item C<$pos = $item-Ehold_queue_position($patron_id)> + +Returns the location of C<$patron_id> in the hold queue for the +item, with '1' indicating the next person to receive the item. A +return status of '0' indicates that C<$patron_id> does not have a +hold on the item. + +=item C<$date = $item-Erecall_date> +=item C<$date = $item-Ehold_pickup_date> + +These functions all return the corresponding date as a standard +SIP-format timestamp: + + YYYYMMDDZZZZHHMMSS + +Where the C<'Z'> characters indicate spaces. + +=item C<$date = $item-Edue_date> + +Returns the date the item is due. The format for this timestamp +is not defined by the specification, but it should be something +simple for a human reader to understand. + +=item C<$fee = $item-Efee> + +The amount of the fee associated with borrowing this item. + +=item C<$currency = $item-Efee_currency> + +The currency in which the fee type above is denominated. This +field is the ISO standard 4217 three-character currency code. It +is highly unlikely that many systems will denominate fees in more +than one currency, however. + +=item C<$type = $item-Esip_fee_type> + +The type of fee being charged, as defined by the SIP protocol +specification: + + 01 Other/unknown + 02 Administrative + 03 Damage + 04 Overdue + 05 Processing + 06 Rental + 07 Replacement + 08 Computer access charge + 09 Hold fee + +=item C<$mark = $item-Esip_security_marker> + +The type of security system with which the item is tagged: + + 00 Other + 01 None + 02 3M Tattle-tape + 03 3M Whisper tape + +=item C<$msg = $item-Escreen_msg> +=item C<$msg = $item-Eprint_line> + +The usual suspects. + +=back -- 2.11.0