Biblio::ILL::ISO::Request - Perl extension for handling ISO 10161 interlibrary loan ILL-Request messages

Biblio-ILL-ISO documentation  | view source Contained in the Biblio-ILL-ISO distribution.

Index

NAME

Top

Biblio::ILL::ISO::Request - Perl extension for handling ISO 10161 interlibrary loan ILL-Request messages

VERSION

Top

Version 0.01

DESCRIPTION

Top

Biblio::ILL::ISO::Request is a derivation of the abstract Biblio::ILL::ISO::ISO object, and handles the ILL-Request message type.

EXPORT

Top

None.

ERROR HANDLING

Top

Each of the set_() methods will croak on missing or invalid parameters.

FROM THE ASN DEFINITION

Top

 ILL-Request ::= [APPLICATION 1] EXPLICIT SEQUENCE {
    	protocol-version-num	[0]	IMPLICIT INTEGER, -- {
    				-- version-1 (1),
    				-- version-2 (2)
    				--},
    	transaction-id	[1]	IMPLICIT Transaction-Id,
    	service-date-time	[2]	IMPLICIT Service-Date-Time,
    	requester-id	[3]	IMPLICIT System-Id OPTIONAL,
    		-- mandatory when using store-and-forward communications
    		-- optional when using connection-oriented communications
    	responder-id	[4]	IMPLICIT System-Id OPTIONAL,
    		-- mandatory when using store-and-forward communications
    		-- optional when using connection-oriented communications
    	transaction-type	[5]	IMPLICIT Transaction-Type, --DEFAULT 1,
    	delivery-address	[6]	IMPLICIT Delivery-Address OPTIONAL, 
    	delivery-service		Delivery-Service OPTIONAL,
    	billing-address	[8]	IMPLICIT Delivery-Address OPTIONAL,
    	iLL-service-type	[9]	IMPLICIT SEQUENCE OF ILL-Service-Type, --  SIZE (1..5)
    		-- this sequence is a list, in order of preference
 -- DC - 'EXTERNAL' is not supported in Convert::ASN1
 --	responder-specific-service	[10]	EXTERNAL OPTIONAL,
 --		-- use direct reference style
    	requester-optional-messages	[11]	IMPLICIT Requester-Optional-Messages-Type,
    	search-type	[12]	IMPLICIT Search-Type OPTIONAL,
    	supply-medium-info-type 	[13]	IMPLICIT SEQUENCE OF Supply-Medium-Info-Type OPTIONAL, -- SIZE (1..7)
    		-- this sequence is a list, in order of preference,
    		-- with a maximum number of 7 entries
    	place-on-hold	[14]	IMPLICIT Place-On-Hold-Type, --DEFAULT 3,
    	client-id	[15]	IMPLICIT Client-Id OPTIONAL,     
    	item-id	[16]	IMPLICIT Item-Id,
 -- DC - 'EXTERNAL' definition (see Supplemental-Item-Description)
 --	supplemental-item-description	[17]	IMPLICIT Supplemental-Item-Description OPTIONAL,
    	cost-info-type	[18]	IMPLICIT Cost-Info-Type OPTIONAL,
    	copyright-compliance	[19]	ILL-String OPTIONAL,
    	third-party-info-type	[20]	IMPLICIT Third-Party-Info-Type OPTIONAL,
    		-- mandatory when initiating a FORWARD service or an
    		-- ILL-REQUEST service for a partitioned ILL sub-
    		-- transaction or when initiating an ILL-REQUEST service for
    		-- an ILL sub-transaction if the received ILL-REQUEST
    		-- included an "already-tried-list";optional otherwise
    	retry-flag	[21]	IMPLICIT BOOLEAN, -- DEFAULT FALSE,
    	forward-flag	[22]	IMPLICIT BOOLEAN, -- DEFAULT FALSE,
    	requester-note	[46]	ILL-String OPTIONAL,
    	forward-note	[47]	ILL-String OPTIONAL,
    	iLL-request-extensions 	[49]	IMPLICIT SEQUENCE OF Extension OPTIONAL
    	--iLL-request-extensions 	[49]	IMPLICIT SEQUENCE OF Extension
     	}

CONSTRUCTORS

Top

new()

Base constructor for the class. It just returns a completely empty message object, which you'll need to populate with the various set_() methods, or use the read() method to read an ILL-Request message from a file (followed by a call to from_asn() to turn the read's returned hash into a proper Request message.

The constructor also initializes the Convert::ASN1 if it hasn't been initialized.

METHODS

Top

For any example code, assume the following: my $msg = new Biblio::ILL::ISO::Request;

from_asn($href)

To read a message from a file, use the following:

    my $href = $msg->read("msg_01.request.ber");
    $msg = $msg->from_asn($href);

The from_asn() method turns the hash returned from read() into a proper message-type object.

set_protocol_version_num($pvn)

 Sets the protocol version number.
 Acceptable parameter values are the strings:
    version-1
    version-2

set_transaction_id($tid)

 Sets the message's transaction-id.  
 Expects a valid Biblio::ILL::ISO::TransactionId.

    my $tid = new Biblio::ILL::ISO::TransactionId("PLS","001","", 
					          new Biblio::ILL::ISO::SystemId("MWPL"));
    $msg->set_transaction_id($tid);

 This is a mandatory field.

set_service_date_time($sdt)

 Sets the message's service-date-time.  
 Expects a valid Biblio::ILL::ISO::ServiceDateTime.

    my $dt_this = new Biblio::ILL::ISO::DateTime("20030623","114400");
    my $dt_orig = new Biblio::ILL::ISO::DateTime("20030623","114015")
    my $sdt = new Biblio::ILL::ISO::ServiceDateTime( $dt_this, $dt_orig);
    $msg->set_service_date_time($sdt);

 This is a mandatory field.

set_requester_id($reqid)

 Sets the message's requester-id.  
 Expects a valid Biblio::ILL::ISO::SystemId.

    my $reqid = new Biblio::ILL::ISO::SystemId();
    $reqid->set_person_name("David A. Christensen");
    $msg->set_requester_id($reqid);

 This is a mandatory field.

set_responder_id($resid)

 Sets the message's responder-id.  
 Expects a valid Biblio::ILL::ISO::SystemId.

    my $resid = new Biblio::ILL::ISO::SystemId("MWPL");
    $msg->set_responder_id($resid);

 This is an optional field.

set_transaction_type($tt)

 Sets the message's transaction-type.  
 Expects a valid Biblio::ILL::ISO::TransactionType.

    my $tt = new Biblio::ILL::ISO::TransactionType("simple");
    $msg->set_transaction_type($tt);

 This is a mandatory field.

set_delivery_address($da)

 Sets the message's delivery-address.
 Expects a valid Biblio::ILL::ISO::DeliveryAddress.

    my $sa = new Biblio::ILL::ISO::SystemAddress("SMTP","DChristens\@gov.mb.ca")'
    my $pa = new Biblio::ILL::ISO::PostalAddress("Manitoba Public Library Services",
					         "",
					         "Unit 200",
					         "1525 First Street South",
					         "",
					         "Brandon",
					         "MB",
					         "CANADA",
					         "R7A 7A1"
					         )
    my $da = new Biblio::ILL::ISO::DeliveryAddress($sa,	$pa);
    $msg->set_delivery_address($da);

 This is an optional field.

set_delivery_service($ds)

 Sets the message's delivery-service.
 Expects a valid Biblio::ILL::ISO::DeliveryService.

    my $tm = new Biblio::ILL::ISO::TransportationMode("Canada Post")
    my $ds = new Biblio::ILL::ISO::DeliveryService( $tm );
    $msg->set_delivery_service($ds);

 This is an optional field.

set_billing_address($ba)

 Sets the message's billing-address.
 Expecs a valid Biblio::ILL::ISO::DeliveryAddress.

    my $sa = new Biblio::ILL::ISO::SystemAddress("SMTP","DChristens\@gov.mb.ca")'
    my $pa = new Biblio::ILL::ISO::PostalAddress("Manitoba Public Library Services",
					         "",
					         "Unit 200",
					         "1525 First Street South",
					         "",
					         "Brandon",
					         "MB",
					         "CANADA",
					         "R7A 7A1"
					         )
    my $ba = new Biblio::ILL::ISO::DeliveryAddress($sa,	$pa);
    $msg->set_delivery_address($ba);

 This is an optional field.

set_ILL_service_type_sequence($ists)

 Sets the message's iLL-service-type sequence.
 Expects a valid Biblio::ILL::ISO::ILLServiceTypeSequence.

    my $ist1 = new Biblio::ILL::ISO::ILLServiceType("loan");
    my $ist2 = new Biblio::ILL::ISO::ILLServiceType("copy-non-returnable");
    # You can pass an array of ILLServiceType(s)
    my $ists = new Biblio::ILL::ISO::ILLServiceTypeSequence( $ist1, $ist2 );

    #example of adding to a sequence_of
    $ists->add(new Biblio::ILL::ISO::ILLServiceType("locations"));

    $msg->set_ILL_service_type_sequence($ists);

 This is a mandatory field.

set_requester_optional_messages($rom)

 Sets the message's requester-optional-messages.
 Expects a valid Biblio::ILL::ISO::RequesterOptionalMessageType.

    my $rom = new Biblio::ILL::ISO::RequesterOptionalMessageType(1,
                                                                 1,
                                                                 "desires",
                                                                 "requires"
                                                                 );
    $msg->set_requester_optional_messages($rom);

 This is a mandatory field.

set_search_type($st)

 Sets the message's search-type.
 Expects a valid Biblio::ILL::ISO::SearchType.

    my $st = new Biblio::ILL::ISO::SearchType("need-Before-Date",
                                              "1",
                                              "20030720"
                                              );
    $msg->set_search_type($st);

 This is an optional field.

set_supply_medium_info_type_sequence($smits)

 Sets the message's supply-medium-info-type sequence.
 Expects a valid Biblio::ILL::ISO::SupplyMediumInfoTypeSequence.

    my $smit = new Biblio::ILL::ISO::SupplyMediumInfoType("photocopy","legal-size paper");
    # Just a sequence of one....
    my $smits = new Biblio::ILL::ISO::SupplyMediumInfoTypeSequence( $smit );
    $msg->set_supply_medium_info_type_sequence($smits);

 This is an optional field.

set_place_on_hold($poh)

 Sets the message's place-on-hold.
 Expects a valid Biblio::ILL::ISO::PlaceOnHoldType.

    my $poh = new Biblio::ILL::ISO::PlaceOnHoldType("no");
    $msg->set_place_on_hold($poh);

 This is a mandatory field.

set_client_id($cid)

 Sets the message's client-id.
 Expects a valid Biblio::ILL::ISO::ClientId.

    my $cid = new Biblio::ILL::ISO::ClientId("David Christensen",
                                             "Most excellent",
                                             "007"
                                             );
    $msg->set_client_id($cid)

 This is an optional field.

set_item_id($iid)

 Sets the message's item-id.
 Expects a valid Biblio::ILL::ISO::ItemId.

    my $iid = new Biblio::ILL::ISO::ItemId("My Book",
                                           "David Christensen",
                                           "CHR001.1"
                                           );
    $iid->set_item_type("monograph");
    $iid->set_medium_type("printed");
    $iid->set_pagination("456");
    $iid->set_publication_date("2003");
               :
               :

    $msg->set_item_id($iid);

 This is a mandatory field.

set_cost_info_type($cit)

 Sets the message's cost-info-type.
 Expects a valid Biblio::ILL::ISO::CostInfoType.

    my $cit = new Biblio::ILL::ISO::CostInfoType("","","","PLS001","\$40.00");
    $msg->set_cost_info_type($cit);

 This is an optional field.


 Sets the message's copyright-compliance.
 Expects a simple text string.

    msg->set_copyright_compliance("Statement of copyright compliance");

 This is an optional field.

set_third_party_info_type($tpit)

 Sets the message's third-party-info-type.
 Expects a valid Biblio::ILL::ISO::ThirdPartyInfoType.

    # The send-to-list-type sequence
    my $stlt = new Biblio::ILL::ISO::SendToListType( new Biblio::ILL::ISO::SystemId("MBOM") )
    my $stlts = new Biblio::ILL::ISO::SendToListTypeSequence( $stlt );
    $stlts->add(new Biblio::ILL::ISO::SendToListType( new Biblio::ILL::ISO::SystemId("MWPL"),
                                                      new Biblio::ILL::ISO::AccountNumber("PLS001"),
				                      new Biblio::ILL::ISO::SystemAddress("SMTP","pls\@gov.mb.ca")
				                    )
  	       );

    # The already-tried-list-type
    my $atlt = new Biblio::ILL::ISO::AlreadyTriedListType( new Biblio::ILL::ISO::SystemId("BVAS") );
    my $obj = new Biblio::ILL::ISO::SystemId();
    $obj->set_institution_name("Winnipeg Public Library");
    $atlt->add($obj);
    $obj = new Biblio::ILL::ISO::SystemId();
    $obj->set_person_name("Frank Emil Urwald");
    $atlt->add($obj);
    $atlt->add( new Biblio::ILL::ISO::SystemId("MBOM"));

    # And finally, the third-party-info-type
    my $sa = new Biblio::ILL::ISO::SystemAddress("SMTP","David_A_Christensen\@hotmail.com");
    my $tpit = new Biblio::ILL::ISO::ThirdPartyInfoType(1,1,1,1,
                                                        "ordered",
						        $sa,
						        $stlts,
						        $atlt
						       );
    msg->set_third_party_info_type($tpit);

 This is an optional field.

set_retry_flag($flag)

 Sets the message's retry-flag.
 Acceptable parameter values are the strings:
     true
     false

 This is a mandatory field.

set_forward_flag($flag)

 Sets the message's forward-flag.
 Acceptable parameter values are the strings:
     true
     false

 This is a mandatory field.

set_requester_note($note)

 Sets the message's requester-note.
 Expects a simple text string.

    $msg->set_requester_note("This is a requester note");

 This is an optional field.

set_forward_note($note)

 Sets the message's forward-note.
 Expects a simple text string.

    $msg->set_forward_note("This is a forward note");

 This is an optional field.

RELATED MODULES

Top

 Biblio::ILL::ISO::ISO
 Biblio::ILL::ISO::Request
 Biblio::ILL::ISO::ForwardNotification
 Biblio::ILL::ISO::Shipped
 Biblio::ILL::ISO::Answer
 Biblio::ILL::ISO::ConditionalReply
 Biblio::ILL::ISO::Cancel
 Biblio::ILL::ISO::CancelReply
 Biblio::ILL::ISO::Received
 Biblio::ILL::ISO::Recall
 Biblio::ILL::ISO::Returned
 Biblio::ILL::ISO::CheckedIn
 Biblio::ILL::ISO::Overdue
 Biblio::ILL::ISO::Renew
 Biblio::ILL::ISO::RenewAnswer
 Biblio::ILL::ISO::Lost
 Biblio::ILL::ISO::Damaged
 Biblio::ILL::ISO::Message
 Biblio::ILL::ISO::StatusQuery
 Biblio::ILL::ISO::StatusOrErrorReport
 Biblio::ILL::ISO::Expired

SEE ALSO

Top

See the README for system design notes.

For more information on Interlibrary Loan standards (ISO 10160/10161), a good place to start is:

http://www.nlc-bnc.ca/iso/ill/main.htm

AUTHOR

Top

David Christensen, <DChristensenSPAMLESS@westman.wave.ca>

COPYRIGHT AND LICENSE

Top

Copyright 2003 by David Christensen

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Biblio-ILL-ISO documentation  | view source Contained in the Biblio-ILL-ISO distribution.