=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_media; $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_media> 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