 |   | ||
| HomePrev | Chapter 25. SIP Server | Next | |
|---|---|---|---|
SIP generally communicates over a TCP connection (either raw sockets or over telnet), but can also
communicate via serial connections and other methods. In Evergreen, the most common deployment is a RAW socket
connection on port 6001.
SIP communication consists of strings of messages, each message request and response begin with a 2-digit
“command” - Requests usually being an odd number and responses usually increased by 1 to be an even number. The
combination numbers for the request command and response is often referred to as a Message Pair (for example,
a 23 command is a request for patron status, a 24 response is a patron status, and the message pair 23/24 is patron
status message pair). The table in the next section shows the message pairs and a description of them.
For clarification, the “Request” is from the device (selfcheck or otherwise) to the ILS/ACS. The response is… the response to the request ;).
Within each request and response, a number of fields (either a fixed width or separated with a | [pipe symbol] and preceeded with a 2-character field identifier) are used. The fields vary between message pairs.
Pair | Name | Supported? | Details |
01 | Block Patron | Yes | 01/Block_Patron - ACS responds with 24 Patron Status Response |
09-10 | Checkin | Yes (with extensions) | |
11-12 | Checkout | Yes (no renewals) | |
15-16 | Hold | Partially supported | |
17-18 | Item Information | Yes (no extensions) | |
19-20 | Item Status Update | No | 19/20_Item_Status_Update - Returns Patron Enable response, but doesn’t make any changes in EG |
23-24 | Patron Status | Yes | 23/24_Patron_Status - 63/64 “Patron Information” preferred |
25-26 | Patron Enable | No | 25/26_Patron_Enable - Used during system testing and validation |
29-30 | Renew | Yes | |
35-36 | End Session | Yes | |
37-38 | Fee Paid | Yes | |
63-64 | Patron Information | Yes (no extensions) | |
65-66 | Renew All | Yes | |
93-94 | Login | Yes | 93/94_Login - Must be first command to Evergreen ACS (via socket) or |
97-96 | Resend last message | Yes | |
99-98 | SC-ACS Status | Yes |
A selfcheck will issue a Block Patron command if a patron leaves their card in a selfcheck machine or if the selfcheck detects tampering (such as attempts to disable multiple items during a single item checkout, multiple failed pin entries, etc).
In Evergreen, this command does the following:
The request looks like:
01<card retained><date>[fields AO, AL, AA, AC]
Card Retained: A single character field of Y or N - tells the ACS whether the SC has retained the card (ex: left in the machine) or not.
Date: An 18 character field for the date/time when the block occurred.
Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, “Z” (3 blanks and a Z) represents UTC(GMT/Zulu)
Fields: See Fields for more details.
The response is a 24 “Patron Status Response” with the following:
~The request looks like:
09<No block (Offline)><xact date><return date>[Fields AP,AO,AB,AC,CH,BI]
No Block (Offline): A single character field of Y or N - Offline transactions are not currently supported so send N.
xact date: an 18 character field for the date/time when the checkin occurred. Format: YYYYMMDDZZZZHHMMSS (ZZZZ being zone - 4 blanks when local time, “Z” (3 blanks and a Z) represents UTC(GMT/Zulu)
Fields: See Fields for more details.
The response is a 10 “Checkin Response” with the following:
10<resensitize><magnetic media><alert><xact date>[Fields AO,AB,AQ,AJ,CL,AA,CK,CH,CR,CS,CT,CV,CY,DA,AF,AG]
Example (with a remote hold):
09N20100507 16593720100507 165937APCheckin Bin 5|AOBR1|AB1565921879|ACsip_01|
101YNY20100623 165731AOBR1|AB1565921879|AQBR1|AJPerl 5 desktop reference|CK001|CSQA76.73.P33V76 1996 |CTBR3|CY373827|DANicholas Richard Woodard|CV02|
Here you can see a hold alert for patron CY 373827, named DA Nicholas Richard Woodard, to be picked up at CT “BR3”. Since the transaction is happening at AO “BR1”, the alert type CV is 02 for hold at remote library. The possible values for CV are:
The logic for Evergreen to determine whether the content is magnetic_media comes from either legacy circ scripts or search_config_circ_modifier. The default is non-magnetic. The same is true for media_type (default 001). Evergreen does not populate the collection_code because it does not really have any, but it will provide the call_number where available.
Unlike the item_id (barcode), the title_id is actually a title string, unless the configuration forces the
return of the bib ID.
Don’t be confused by the different branches that can show up in the same response line.
Evergreen supports the Hold message for the purpose of canceling holds. It does not currently support creating hold requests via SIP2.
The request looks like:
17<xact_date>[fields: AO,AB,AC]
The request is very terse. AC is optional.
The following response structure is for SIP2. (Version 1 of the protocol had only 6 total fields.)
18<circulation_status><security_marker><fee_type><xact_date> [fields: CF,AH,CJ,CM,AB,AJ,BG,BH,BV,CK,AQ,AP,CH,AF,AG,+CT,+CS]
Example:
1720060110 215612AOBR1|ABno_such_barcode|
1801010120100609 162510ABno_such_barcode|AJ|
1720060110 215612AOBR1|AB1565921879|
1810020120100623 171415AB1565921879|AJPerl 5 desktop reference|CK001|AQBR1|APBR1|BGBR1 |CTBR3|CSQA76.73.P33V76 1996|
The first case is with a bogus barcode. The latter shows an item with a circulation_status of 10 for in transit between
libraries. The known values of circulation_status are enumerated in the spec.
EXTENSIONS: The CT field for destination location and CS call number are used by Automated Material Handling systems.
Example:
2300120060101 084235AOUWOLS|AAbad_barcode|ACsip_01|ADbad_password|
24YYYY 00120100507 013934AE|AAbad_barcode|BLN|AOUWOLS|
2300120060101 084235AOCONS|AA999999|ACsip_01|ADbad_password|
24 Y 00120100507 022318AEDoug Fiander|AA999999|BLY|CQN|BHUSD|BV0.00|AFOK|AOCONS|
2300120060101 084235AOCONS|AA999999|ACsip_01|ADuserpassword|LY|CQN|BHUSD|BV0.00|AFOK|AOCONS|
24 Y 00120100507 022803AEDoug Fiander|AA999999|BLY|CQY|BHUSD|BV0.00|AFOK|AOCONS|
SIP2, optional) is valid patron, so the N value means bad_barcode doesn’t match a patron, the
Y value means 999999 does.
SIP2, optional) is valid password, so the N value means bad_password doesn’t match 999999’s
password, the Y means userpassword does.
So if you were building the most basic SIP2 authentication client, you would check for |CQY| in the response to
know the user’s barcode and password are correct (|CQY| implies |BLY|, since you cannot check the password
unless the barcode exists). However, in practice, depending on the application, there are other factors to consider in
authentication, like whether the user is blocked from checkout, owes excessive fines, reported their card lost, etc.
These limitations are reflected in the 14-character patron status string immediately following the 24 code. See the
field definitions in your copy of the spec.
3520100505 115901AOBR1|AA999999|
36Y20100507 161213AOCONS|AA999999|AFThank you!|
The Y/N code immediately after the 36 indicates success/failure. Failure is not particularly meaningful or important in this context, and for evergreen it is hardcoded Y.
Attempting to retrieve patron info with a bad barcode:
6300020060329 201700 AOBR1|AAbad_barcode|
64YYYY 00020100623 141130000000000000000000000000AE|AAbad_barcode|BLN|AOBR1|
Attempting to retrieve patron info with a good barcode (but bad patron password):
6300020060329 201700 AOBR1|AA999999|ADbadpwd|
64 Y 00020100623 141130000000000000000000000000AA999999|AEDavid J. Fiander|BHUSD|BV0.00 |BD2 Meadowvale Dr. St Thomas, ON Canada
90210|BEdjfiander@somemail.com|BF(519) 555 1234|AQBR1|BLY|CQN|PB19640925|PCPatrons |PIUnfiltered|AFOK|AOBR1|
See 23/24 Patron Status for info on BL and CQ fields.
Example:
9300CNsip_01|CObad_value|CPBR1|
[Connection closed by foreign host.] ...
9300CNsip_01|COsip_01|CPBR1|
941
941 means successful terminal login. 940 or getting dropped means failure.
99<status code><max print width><protocol version>
All 3 fields are required:
protocol version - 4 characters - x.xx
98<on-line status><checkin ok><checkout ok><ACS renewal policy> <status update ok><offline ok><timeout period>
<retries allowed><date/time sync><protocol version><institution id> <library name><supported messages><terminal
location><screen message><print line>
Example:
9910302.00
98YYYYNN60000320100510 1717202.00AOCONS|BXYYYYYYYYYNYNNNYN|
The Supported Messages field BX appears only in SIP2, and specifies whether 16 different SIP commands are
supported by the ACS or not.
All fixed-length fields in a communication will appear before the first variable-length field. This allows for simple parsing. Variable-length fields are by definition delimited, though there will not necessarily be an initial delimiter between the last fixed-length field and the first variable-length one. It would be unnecessary, since you should know the exact position where that field begins already.