DigitalPlatform / dp2

Integrated Library System / 图书馆集成系统
http://digitalplatform.github.io/dp2
Apache License 2.0
106 stars 54 forks source link

SIP2消息说明 #756

Open renyh opened 3 years ago

renyh commented 3 years ago

接口目录

SC to the ACS - ACS to the SC -
Login 93 Login Response 94
Item Information 17 Item Information Response 18
Item Status Update 19 Item Status Update Response 20
Checkout 11 Checkout Response 12
Checkin 09 Checkin Response 10
Patron Information 63 Patron Information Response 64
End Patron Session 35 End Session Response 36
Fee Paid 37 Fee Paid Response 38
Patron Enable 25 Patron Enable Response 26
Hold 15 Hold Response 16
Renew 29 Renew Response 30
Renew All 65 Renew All Response 66
Patron Status Request 23 Patron Status Responese 24
Block Patron 01 Patron Status Responese 24
SC Status 99 ACS Status 98
Request ACS Resend 97 Request SC Resend 96

字段标识清单

ID 名称 ID 名称 ID 名称
AA patron identifier BA   CA 2.00 overdue items limit
AB item identifier BB   CB 2.00 charged items limit
AC terminal password BC   CC 2.00 fee limit
AD patron password BD 2.00 home address CD 2.00 unavailable hold items
AE personal name BE 2.00 e-mail address CE  
AF screen message BF 2.00 home phone number CF 2.00 hold queue length
AG print line BG 2.00 owner CG 2.00 fee identifier
AH due date BH 2.00 currency type CH 2.00 item properties
AI   BI 2.00 cancel CI 2.00 security inhibit
AJ title identifier BJ   CJ 2.00 recall date
AK   BK 2.00 transaction id CK 2.00 media type
AL blocked card msg BL 2.00 valid patron CL 2.00 sort bin
AM library name BM 2.00 renewed items CM 2.00 hold pickup date
AN terminal location BN 2.00 unrenewed items CN 2.00 login user id
AO institution id BO 2.00 fee acknowledged CO 2.00 login password
AP current location BP 2.00 start item CP 2.00 location code
AQ permanent location BQ 2.00 end item CQ 2.00 valid patron password
AR   BR 2.00 queue position    
AS 2.00 hold items BS 2.00 pickup location    
AT 2.00 overdue items BT 2.00 payment type    
AU 2.00 charged items BU 2.00 recall items    
AV 2.00 fine items BV 2.00 fee amount    
AW   BW 2.00 expiration date    
AX   BX 2.00 supported messages    
AY sequence number BY 2.00 hold type    
AZ checksum BZ 2.00 hold items limit    
renyh commented 3 years ago

登录 93/94

Login 93

设备端登录图书馆系统。

结构

93<UID algorithm><PWD algorithm><login user id><login password><location code>
93  1-char  1-char  CN  CO  CP

字段说明

字段名称 ID 格式 描述
UID algorithm   1-char,必需 user id加密的算法。 0表示user id不加密。
PWD algorithm   1-char, 必需 login password加密算法。 0表示login password不加密。
login user id CN 必需 设备端登录图书馆系统的帐号。
login password CO 必需 设备端登录图书馆系统的的密码。
location code CP 可选 设备终端代码

样例

9300CNusername |CO1234567|CP工作台号|AY1AZEAE5

Login Response 94

结构

94<ok>
94 1-char

字段说明

字段名称 ID 格式 描述
ok   1-char, 必需 1表示登录成功,0表示登录失败。

样例

941|AY4AZFF62
renyh commented 3 years ago

获取图书信息 17/18

Item Information 17

结构

17<transaction date><institution id><item identifier><terminal password>
17  18-char AO  AB  AC

字段说明

字段名称 ID 格式 描述
transaction date   18-char, 必需 请求时间,格式为YYYYMMDDZZZZHHMMSS,例如:20170623    151645。
institution id AO 必需 图书馆的机构ID。
item identifier AB 必需 册条码号。
terminal password AC 可选 设备登录图书馆系统密码。

样例

1720170623    151645AOCN-110108-1-XXXX|AB700635|

Item Information Response 18

结构

18<circulation status><security marker><fee type><transaction date><hold queue length><due date><recall date><hold pickup date><item identifier>
18  2-char  2-char  2-char  18-char CF  AH  CJ  CM  AB
<title identifier><owner><currency type><fee amount><media type><item properties>
AJ  BG  BH  BV  CK  CH  
<permanent location><current location><permanent shelf no><current shelf no><call no>
AQ  AP  KQ  KP  KC
<screen message><print line>
AF  AG

字段说明

字段名称 ID 格式 描述
circulation status   2-char, 必需,值范围 (00~99) 流通状态。dp2根据该图书实际状态,返回相应值 ,外借图书是04。
security marker   2-char, 必需,值范围 (00~99) 安全标记类型。dp2返回的00。
fee type   2-char, 必需,值范围 (01~99) 收费类型。dp2返回的01。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
hold queue length CF 可选 预约排队人数。dp2系统如果该书没有预约,返回0。
due date AH 可选 还书日期。dp2返回的还书日期格式为YYYY-MM-DD,例如AH2019-01-25。
recall date CJ 18-char, 可选 召回的日期,格式为YYYYMMDDZZZZHHMMSS。dp2系统未传该字段。
hold pickup date CM 18-char, 可选 保留到期的日期,格式为YYYYMMDDZZZZHHMMSS。dp2系统,如果该书没有被预约,不传该字段。
item identifier AB 必需 册条码号,不能为空。
title identifier AJ 必需 图书的题名。
owner BG 可选 图书所属机构名称。dp2系统未返回该字段。
currency type BH 3-char,定长,可选 货币类型。dp2系统如果图书未涉及欠费,不返回该字段。
fee amount BV 可选 欠费金额。dp2系统如果图书未涉及欠费,不返回该字段。
media type CK 3-char,定长,可选 煤体类型。dp2返回001,表示图书。
item properties CH 可选 图书一些属性信息,例如尺寸、价格等。注dp2以前版本返回是索取号。
screen message AF 可选 提示信息。
print line AG 可选 打印消息。
permanent location AQ 可选 图书永久馆藏地。
current location AP 可选 图书当前馆藏地。
permanent shelf no KQ 可选 永久架位号,dp2扩展字段。
current shelf no KP 可选 当前架位号,dp2扩展字段。
call no KC 可选 索取号,dp2扩展字段。

样例

1804000120181225    100159CF0|AH2019-01-25|CM20181225    100139|ABDPB000001|AJ金庸随想录|CK001
|AQ实验学校/一楼阅览室|AP实验学校/一楼阅览室|KQ0101|KP0102|KCI267.1/H317

盘点设备对接注意事项

  1. 关于位置的4个字段,详细说明和数据示例如下: 1)permanent location (AQ) 表示图书永久馆藏地,举例:单独图书馆情况,馆藏地形态为“一楼阅览室”;总分馆模式,分馆馆藏地形态为“海淀分馆/一楼阅览室”。 2)current location (AP) 表示图书当前馆藏地,举例:单独图书馆情况,馆藏地形态为“二楼阅览室”;总分馆模式,分馆馆藏地形态为“海淀分馆/二楼阅览室”。。 3)permanent shelf no(KQ) 表示图书永久架位,例如“0101”。 4)current shelf no(KP) 表示图书当前架位,例如“0102”。

  2. 本来在dp2系统可以在permanent location (AQ)图书永久位置 和current location (AP)图书当前位置这两个字段,返回详细的位置信息,字段值同时包括馆藏地和架位,格式为“馆藏地:架位号”。 但为了第三方使用的简便性,特别扩展了KQ永久架位和KP当前架位字段,接口原有的AQ和AP仅返回馆藏地,这样第三方使用时就不需要拆分字符串。

  3. 如果盘点定位设备端首次获取图书数据时,没有得到图书的当前位置信息,可以在盘点设备进行图书盘点时,调19接口更新图书位置信息。以后再获取图书数据时,就会有图书位置信息了。

关于图书流通状态

3M SIP2协议规定18消息前2字符表示流通状态,这是原文和翻译的值 The circulation status of an item. The following statuses are defined: 该册图书的流通状态,状态如下: Value Status 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 声明丢失

针对SIP2的Item Information Response 18消息返回的状态,有2种情况需要确认一下: 一是我们图书馆服务器如果出现了严重错误,比如SIP2服务器通着,但底层的模块断开了。那么18中的状态该 返回什么值? 二是如果前端调Item Information17接口,传过来一个图书馆系统完全不存在的图书条码,那18消息的状态该返回什么值?

renyh commented 3 years ago

更新图书信息 19/20

Item Status Update 19

结构

19<transaction date><institution id><item identifier><terminal password><item properties>
19  18-char AO  AB  AC  CH
<permanent location><current location><permanent shelf no><current shelf no><holding state>
AQ  AP  KQ  KP  HS

注意:暂时还不支持HS修改状态的功能

字段说明

字段名称 ID 格式 描述
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
institution id AO 必需 图书馆的机构ID。
item identifier AB 必需 册条码号,不能为空。
terminal password AC 可选 设备登录图书馆系统密码。
item properties CH 必需 图书一些属性信息,例如尺寸、价格等。
permanent location AQ 可选 图书永久馆藏地,dp2扩展字段。
current location AP 可选 图书当前馆藏地,dp2扩展字段。
permanent shelf no KQ 可选 永久架位号,dp2扩展字段。
current shelf no KP 可选 当前架位号,dp2扩展字段。
batch no KB 可选 盘点批次号,dp2扩展字段。

注意:发送请求时CH字段是必需有的,但CH字段值可以为空。

20220523补充

等号左侧是dp2library册记录中的元素,右侧是sip字段中的概念,其中currentLocation的形态是由当前馆藏地+当前架位组成的。两者是结合在一起的,不会单独分开。就是说前端每次发出去的请求中都有这两个信息。

location=AQ(永久馆藏地)<location>阅览室</location> shelfNo=KQ(永久架位)<shelfNo>阅览室</shelfNo> currentLocation=AP(当前馆藏地)+KP(当前架位)<currentLocation>阅览室:0102</currentLocation>

样例

1920170623    151645AOCN-110108-1-XXXXAB000001AQ一楼阅览室|AP一楼阅览室|KQ0101|KP0102

盘点设备对接注意事项

  1. 关于位置的4个字段,详细说明和数据示例如下: 1)permanent location (AQ) 表示图书永久馆藏地,例如“一楼阅览室”。 2)current location (AP) 表示图书当前馆藏地,例如“二楼阅览室”。 3)permanent shelf no(KQ) 表示图书永久架位,例如“0101”。 4)current shelf no(KP) 表示图书当前架位,例如“0102”。

  2. 如果请求消息中完全不传上述某个字段,表示不修改对应信息。例如发送的请求为:1920170623 151645AOCN-110108-1-XXXXAB000001|KP0102,表示仅修改册000001的当前架位这0102,其它信息不变。

  3. 如果请求消息中完全传了上述某个字段,但值为空。例如发送的请求为:1920170623 151645AOCN-110108-1-XXXXAB000001|AP|KP,表示将册000001的当前馆藏地设为空,当前架位设为空,其它信息不变。

  4. 特别注意:盘点设备端对图书进行盘点定位后,要及时调此接口更新图书的当前位置,这样用户才能在图书馆后台系统以及OPAC和微信公众号看到图书的当前位置,方便用户根据显示的当前位置信息找到实物图书。


Item Status Update Response 20

结构

20<item properties ok><transaction date><item identifier><title identifier><item properties>
20  1-char  18-char AB  AJ  CH
<screen message><print line>
AF  AG
字段名称 ID 格式 描述
item properties ok 1-char, 必需 更新成功返回1,失败返回0。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
item identifier AB 必需 册条码号。
title identifier AJ 必需 题名。
item properties CH 可选 图书一些属性信息,例如尺寸、价格等。
screen message AF 可选 提示信息。
print line AG 可选 打印消息。

样例

20120170623    151645AB000001AJ小王子|CH|AF图书信息更新成功|AG图书信息更新成功|AY0AZC05B
renyh commented 3 years ago

借书 11/12

Checkout 11

结构

结构:
11<SC renewal policy><no block><transaction date><nb due date><institution id>
11  1-char  1-char  18-char 18-char AO
<patron identifier><item identifier><terminal password>
AA  AB  AC
<patron password><item properties><fee acknowledged><cancel>
AD  CH  BO  BI

字段说明

字段名称 ID 格式 描述
SC renewal policy   1-char, Y or N,必需 Y表示支持续借,N表示不可以续借。
no block   1-char, Y or N,必需 前端是否可以离线借还。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
nb due date   18-char, 必需 与离线借还有关,参见下方详细说明。格式为YYYYMMDDZZZZHHMMSS。一般传18个空格。
institution id AO 必需 图书馆的机构ID。
patron identifier AA 必需 读者证条码号。
item identifier AB 必需 册条码号,不能为空。
terminal password AC 必需 设备登录图书馆系统密码。
patron password AD 可选 读者密码。
item properties CH 可选 图书一些属性信息,例如尺寸、价格等。
fee acknowledged BO 1-char,Y or N,可选 与费用有关,一般传N。参见下方详细说明
cancel BI 1-char, Y or N,可选 传Y时与取消操作有关,一般传N。参见下方详细说明

部分字段详细说明:

nb due date

This is the no block due date that articles were given during off-line (store and forward) operation.,

fee acknowledged

If this field is N in a Checkout message and there is a fee associated with checking out the item, the ACS should tell the SC in the Checkout Response that there is a fee, and refuse to check out the item. If the SC and the patron then interact and the patron agrees to pay the fee, this field will be set to Y on a second Checkout message, indicating to the ACS that the patron has acknowledged the fee and checkout of the item should not be refused just because there is a fee associated with the item.

cance

This field should be set to Y for a Checkout command being used to cancel a failed Checkin command, or for a Checkin command being used to cancel a failed Checkout command. It should be set to N for all other Checkout or Checkin commands. Checkout此参数传Y,则取消前一个失败的Checkin Checkin此参数传Y,则取消前一个失败的Checkout 所有其他Checkout或Checkin命令都应设置为N。

样例

11YN20170630    141135                  AOCN-110108-1-XXXX|AAL905071|AB510105|AC|BON|BIN|

字段说明


Checkout Response 12

结构

12<ok><renewal ok><magnetic media><desensitize><transaction date><institution id>
12  1-char  1-char  1-char  1-char  18-char AO
<patron identifier><item identifier><title identifier><due date>
AA  AB  AJ  AH
<fee type><security inhibit><currency type><fee amount><media type><item properties>
BT  CI  BH  BV  CK  CH
<transaction id><screen message><print line>
BK  AF  AG

字段说明

字段名称 ID 格式 描述
ok   1-char, 0 or 1,必需 1表示操作成功,0表示操作失败。
renewal ok   1-char, Y or N,必需 首次借阅返回N,续借返回Y。参见下方详细说明。
magnetic media   1-char, Y or N or U,必需 “Y”表示该物品是磁性媒体,“N”表示该物品不是磁性介质。 'U'表示不确定。参见下方详细说明。一般传N。
desensitize   1-char, Y or N or U,必需 一般返回Y,表示需要自助设备端消磁。参见下方详细说明。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。ZZZZ部分传的4个空格例如:20170623    151645。交易时间。
institution id AO 必需 图书馆的机构ID。
patron identifier AA 必需 读者证条码号。
item identifier AB 必需 册条码号,不能为空。
title identifier AJ 必需 题名
due date AH 必需 还书日期。目前dp2返回的还书日期格式为YYYY-MM-DD,如AH2017-10-28。
fee type BT 2-char, (01 thru 99),可选 费用类型。参见下方详细说明。
security inhibit CI 1-char, Y or N,可选 Y表示通知SC忽略该物品的安全状态。目前dp2未使用这个字段。
currency type BH 3-char, 可选 货币类型。参见下方详细说明。如没有相关费用,dp2不返回这个字段。
fee amount BV 可选 费用金额。参见下方详细说明。如没有相关费用,dp2不返回这个字段。
media type CK 3-char,可选 煤体类型。参见下方详细说明。
item properties CH 可选 图书一些属性信息,例如尺寸、价格等。
transaction id BK 可选 当借书时涉及费用时,由ACS或支付系统分配的交易id。以用于跟踪现金流的审计。
screen message AF 可选 提示信息。
print line AG 可选 打印消息。

部分字段详细说明:

renewal ok

Renewal OK should be set to Y if the patron requesting to check out the item already has the item checked out,should be set to N if the item is not already checked out to the requesting patron. 翻译:如果请求借出图书的读者已经借出了该图书,则Renewal OK应设置为Y,如果该图书尚未借出给请求的读者,应将其设置为N. This field is needed to inform the SC that the material is already checked out. A ‘Y’ value means that the item was checked out to the same patron, so it is actually being renewed. An ‘N’ value means that the patron did not already have the item checked out. 翻译:该字段需要通知SC该图书已经被借出。 “Y” 值意味着该书是被同一个顾客借出的,所以此次实际上是续借。 “N”值意味着该读者还没有借过该书。

magnetic media

A 'Y' in this field indicates that this article is magnetic media and the SC will then handle the security discharge accordingly. A 'N' in this field indicates that the article is not magnetic media. A 'U' indicates that the ACS does not identify magnetic media articles. ACS vendors are encouraged to store and provide article magnetic media identification.

desensitize

A Y in this field indicates that the SC unit should desensitize the article. An N in this field indicates that the article will not be desensitized, i.e. some non-circulation books are allowed to be checked out, but not removed from the library.  A U indicates that the ACS does not know if the item should or should not be desensitized, and will be treated by the SC the same as an N.
翻译:Y表示SC需要对该物品脱敏,N表示不需要脱敏。例如一些不参与流通的图书可以被借阅,但不能移出图书馆。U表示ACS不清楚是否需要脱敏,SC将U与N同样处理。

Desensitize should be set to Y if the SC should desensitize the article. should be set to N if the SC should not desensitize the article (for example, a closed reserve book, or the checkout was refused).
翻译:如果SC应该使物品脱敏,则Desensitize应设为Y。 如果SC不应该使物品脱敏(例如封闭的储备书,或借出被拒绝),应设为N。 dp2目前返回Y,表示 需要消磁。

fee type

The type of fee associated with checking out this item. 费用类型 Enumerated type of fee, from the following table: Value Fee Type
01 other/unknown 其它或未知 02 administrative 行政 03 damage 损坏 04 overdue 超期 05 processing 加工费 06 rental 租金 07 replacement 更新 08 computer access charge 电脑访问费 09 hold fee 预约费

currency type

货币类型 The value for currency type follows ISO Standard 4217:1995, using the 3-character alphabetic code part of the standard. A portion of the standard is provided here as examples: 货币类型遵循ISO标准4217:1995,使用标准的3个字符的字母代码部分。 Value Definition USD US Dollar 美元 CAD Canadian Dollar 加元 GBP Pound Sterling 英镑 FRF French Franc 法郎 DEM Deutsche Mark 德意志马克 ITL Italian Lira 意大利里拉 ESP Spanish Peseta 西班牙语 JPY Yen 日元

fee amount

The amount of the fee associated with checking out this item. 费用金额 Fee Amount should be set to the value of the fee associated with checking out the item,should be set to 0 if there is no fee associated with checking out the item. 费用金额应设置为与借出物品相关的费用的金额,如果没有与借出物品相关的费用,应将其设置为0。 This contains a money amount in whatever currency type is specified by the currency type field of the same message. For example, “115.57” could specify $115.57 if the currency type was USD (US Dollars). 同一消息的currency type字段指定的货币类型的货币金额。 例如,如果currency type是USD,“115.57”表示$ 115.57。、

media type

煤体类型 enumerated media type, from the following table: Value Media Type
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

样例

121NNY20170630    141540AOCN-110108-1-XXXX|AAL905071|AB549096|AJ川味家常菜|AH2017-10-28
|AF图书【川味家常菜】借阅成功!应还日期:2017-10-28
|AG读者【L905071】借书 川味家常菜【川味家常菜】成功,应还日期:2017-10-28|AY4AZF331

120NNY20170630    141137AOCN-110108-1-XXXX|AAL905071|AB510105|AF图书【510105】借阅失败!
|AG读者【L905071】借书【510105】失败!借阅 操作被拒绝,原因: 借阅证的状态为 '待启用'。
|AY4AZB9CD
renyh commented 3 years ago

还书 09/10

Checkin 09

结构

09<no block><transaction date><return date><current location><institution id>
09  1-char  18-char 18-char AP  AO
<item identifier><terminal password><item properties><cancel>
AB  AC  CH  BI

样例

09N20170630    14163020170630    141630AP|AOdp2Library|AB510102|AC|BIN|

字段说明

字段名称 ID 格式 描述
no block   1-char, Y or N,必需 前端是否可以离线借还。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
return date   18-char, 必需 图书还回到图书馆的时间。格式为YYYYMMDDZZZZHHMMSS。
current location AP 必需 图书还回的当前位置,一般传馆藏地,
institution id AO 必需 图书馆的机构ID。
item identifier AB 必需 册条码号,不能为空。
terminal password AC 必需 设备端密码。必需要有字段名,可以传空值。
item properties CH 可选 图书一些属性信息,例如尺寸、价格等。
cancel BI 1-char, Y or N,可选 传Y时与取消操作有关,一般传N。

Checkin Response 10

结构

10<ok><resensitize><magnetic media><alert><transaction date><institution id><item identifier>
10  1-char  1-char  1-char  1-char  18-char AO  AB
<permanent location><title identifier><sort bin><patron identifier><media type>
AQ  AJ  CL  AA  CK
<item properties><screen message><print line>
CH  AF  AG

样例

101YNN20170630    141632AOCN-110108-1-XXXX|AB510102|AQ综合图书库|AJ《奔放西班牙餐》|AAL905071|AF图书《奔放西班牙餐》还回处理成功!2017-06-30|AG图书《奔放西班牙餐》-- 510102已于2017-06-30归还!|AY4AZ4E37

字段说明

字段名称 ID 格式 描述
ok   1-char, 0 or 1,必需 1表示操作成功,0表示操作失败。
resensitize   1-char, Y or N,必需 返回Y。
magnetic media   1-char, Y or N or U,必需 “Y”表示该物品是磁性媒体,“N”表示该物品不是磁性介质。 'U'表示不确定。一般传N。
alert   1-char, Y or N or U,必需 是否有警告,例如是否被预约了。普通情况返回N。见最下方解释。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。ZZZZ部分传的4个空格例如:20170623    151645。交易时间。
institution id AO 必需 图书馆的机构ID。
item identifier AB 必需 册条码号,不能为空。
permanent location AQ 必需 永久馆藏地。
title identifier AJ 可选 题名
sort bin CL 可选 目前dp2未返回。
patron identifier AA 可选 读者证条码号。
media type CK 3-char,可选 煤体类型。参见12消息下方详细说明。
item properties CH 可选 图书一些属性信息,例如尺寸、价格等。
screen message AF 可选 提示信息。
print line AG 可选 打印消息。

resensitize含义: Resensitize should be set to Y if the SC should resensitize the article. should be set to N if the SC should not resensitize the article (for example, a closed reserve book, or the checkin was refused).

alert含义 A Y in the alert field will generate an audible sound at the SC. The alert will indicate conditions like articles on hold, articles belonging to another library branch, or other alert conditions as determined by the ACS. The alert signal will alert the library staff to special article handling conditions during discharging operations.

renyh commented 3 years ago

获取读者信息 63/64

Patron Information 63

结构

63<language><transaction date><summary><institution id><patron identifier><terminal password><patron password><start item><end item>
63  3-char  18-char 10-char AO  AA  AC  AD  BP  BQ

字段说明

字段名称 ID 格式 描述
language   3-char, 必需 指定显示和打印消息的语言。000 Unknown (default) ,001 English ,002 French ,003 German,……019 Chinese 中文。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
summary   10-char, 必需 该字段指定前端请求部分信息的详细信信,一般请求只获取在借信息,值为Y,详细说明参见下方。
institution id AO 必需 图书馆的机构ID。
patron identifier AA 必需 读者证条码号。
terminal password AC 可选 设备登录图书馆系统密码。
patron password AD 可选 读者密码。
start item BP 可选 用于分批获取summary指定事项的开始编号,一般不使用这个字段,详细说明参见下方。
end item BQ 可选 用于分批获取summary指定事项的结束编号,一般不使用这个字段,详细说明参见下方。

部分字段详细说明:

summary

This allows the SC to request partial information only. This field usage is similar to the NISO defined PATRON STATUS field. A Y in any position indicates that detailed as well as summary information about the corresponding category of items can be sent in the response. A blank (code $20) in this position means that only summary information should be sent about the corresponding category of items. Only one category of items should be requested at a time, i.e. it would take 6 of these messages, each with a different position set to Y, to get all the detailed information about a patron’s items. All of the 6 responses, however, would contain the summary information Position Definition
0 hold items 预约事项 (预约的图书,每个预约项一个字段。AS) 1 overdue items 超期事项 (超期的图书,每个超期图书一个字段。AT) 2 charged items 在借事项 (在借的图书,每个在借图书一个字段。AU) 3 fine items 罚款事项,一般是超期罚款 (需要交费事项,每个交费事项一个字段。AV) 4 recall items 召回事项 (召回的图书,每个召回图书一个字段。BU) 5 unavailable holds 无法提供的预约事项 (预约未满足的图书,每个事项一个字段。CD) ~6 fee items 费用事项~ 2022/9/21备注:在1998年的2.10版本有一项,但检查64回复消息中无对应的items字段。查看SIP2协议2006年更新的2.12版本去掉了这个字段。在2.12版PDF文档中的版本历史里有记录 2.12 removed incorrect summary field value

start item

The number of the first item to be returned. The Patron Information message allows the SC to request the ACS to send a list of items that a patron has checked out, or that are overdue, etc. This field specifies the number in that list of the first item to be sent to the SC. For instance, if the SC had requested via the summary, start item, and end item fields of the Patron Information message - to have the fifth through tenth items in the list of the patron’s overdue items sent in the Patron Information response, this field would have the value “5”. A numbering system that starts with 1 is assumed. This allows the requester to have control over how much data is returned at a time, and also to get the whole list in sequential or some other order using successive messages/responses.

end item

The number of the last item to be returned. The Patron Information message allows the SC to request the ACS to send a list of items that a patron has checked out, or that are overdue, etc. This field specifies the number in that list of the last item to be sent to the SC. For instance, if the SC had requested - via the summary, start item, and end item fields of the Patron Information message - to have the seventh through twelfth items in the list of the patron’s overdue items sent in the Patron Information response, this field would have the value “12”. A numbering system that starts with 1 is assumed. This allows the requester to have control over how much data is returned at a time, and also to get the whole list in sequential or some other order using successive messages/responses.

样例

6301920170630    090808  Y       AOCN-110108-1-XXXX|AAP005312|

Patron Information Response 64

结构

64<patron status><language><transaction date><hold items count><overdue items count><charged items count><fine items count>
64  14-char 3-char  18-char 4-char  4-char  4-char  4-char
<recall items count><unavailable holds count><institution id><patron identifier><personal name><hold items limit><overdue items limit>
4-char  4-char  AO  AA  AE  BZ  CA
<charged items limit><valid patron><valid patron password><currency type><fee amount><fee limit>
CB  BL  CQ  BH  BV  CC
<hold items><overdue items><charged items><fine items><recall items><unavailable hold items>
AS  AT  AU  AV  BU  CD
<home address><e-mail address><home phone number><screen message><print line>
BD  BE  BF  AF  AG

样例

64              01920181225    100158000000000001000000000000AOCN-110108-1-XXXX|AA123456|AE测试|BZ0009|CB10|BLY|CQN|
AF您在本馆最多可借【10】册,还可以再借【9】册。|AG您在本馆最多可借【10】册,还可以再借【9】册。|
AUE01D20F581D69CC8|AY4AZDF75

字段说明

字段名称 ID 格式 描述
patron status   14-char, 必需 读者状态。详细说明参见下方。
language   3-char, 必需 指定显示和打印消息的语言。000 Unknown (default) ,001 English ,002 French ,003 German,……019 Chinese 中文。
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
hold items count   4-char, 必需 该字段表示读者预约图书的数量,值从0000至9999。如果没有预约事项或者不支持预约,则值应为4个空格。
overdue items count   4-char, 必需 该字段表示读者超期图书的数量,值从0000至9999。如果没有超期事项,则值应为4个空格。
charged items count   4-char, 必需 该字段表示读者在借图书的数量,值从0000至9999。如果没有在借事项,则值应为4个空格。
fine items count   4-char, 必需 该字段表示读者罚款事项的数量,值从0000至9999。如果没有罚款事项,则值应为4个空格。
recall items count   4-char, 必需 该字段表示读者在借中需要召回的图书数量,值从0000至9999。如果没有可用事项,则值应为4个空格。
unavailable holds count   4-char, 必需 该字段表示该未满足预约的图书数量,值从0000至9999。如果没有事项则值应为4个空格。
institution id AO 必需 图书馆的机构ID。
patron identifier AA 必需 读者证条码号。
personal name AE 必需 读者姓名。
hold items limit BZ 定长4-char,可选 该字段表示读者预约图书的最大数量限制,从0000至99999。
overdue items limit CA 定长4-char,可选 该字段表示读者超期图书的最大数量限制,从0000至99999。
charged items limit CB 定长4-char,可选 该字段表示读者可借图书的最大数量限制,从0000至99999。
valid patron BL 1-char, Y or N,可选 Y表示读者证条码有效,N表示读者无效。
valid patron password CQ 1-char, Y or N,可选 Y表示读者密码有效,N表示读者密码无效。
currency type BH 定长3-char, 可选 货币类型。参见详细说明。
fee amount BV 可选 针对读者收费金额。
fee limit CC 可选 该字段表示读者被允许的罚款和收费的累计限制
hold items AS 可选 预约的图书,每个预约项一个字段。对应summary“0”
overdue items AT 可选 超期的图书,每个超期图书一个字段。对应summary“1”
charged items AU 可选 在借的图书,每个在借图书一个字段。对应summary“2”
fine items AV 可选 需要交费事项,每个交费事项一个字段。对应summary“3”
recall items BU 可选 召回的图书,每个召回图书一个字段。对应summary“4”
unavailable hold items CD 可选 预约未满足的图书,每个事项一个字段。对应summary“5”
home address BD 可选 家庭地址。
e-mail address BE 可选 读者email地址。
home phone number BF 可选 读者电话
screen message AF 可选 提示信息。
print line AG 可选 打印消息。

BH

3-char, fixed-length field. The value for currency type follows ISO Standard 4217:1995, using the 3-character alphabetic code part of the standard. A portion of the standard is provided here as examples: Value Definition USD US Dollar CAD Canadian Dollar GBP Pound Sterling FRF French Franc DEM Deutsche Mark ITL Italian Lira ESP Spanish Peseta JPY Yen

patron status

This field is described in the preliminary NISO standard Z39.70199x. A Y in any position indicates that the condition is true. A blank (code $20) in this position means that this condition is not true. For example, the first position of this field corresponds to "charge privileges denied" and must therefore contain a code $20 if this patron’s privileges are authorized. 对应位置值为Y表示满足。 此位置的空格(代码$ 20)表示此条件不满足。 例如,该字段的第一个位置对应于“借还权限被拒绝”,如果读者拥有借还权限,则此位置为空格。 Position Definition
0 charge privileges denied 借还权限被拒绝 1 renewal privileges denied 没有续借权限 2 recall privileges denied 没有召回权限 3 hold privileges denied 没有预约权限 4 card reported lost 卡挂失 5 too many items charged 太多的在借事项 6 too many items overdue 太多的超期事项 7 too many renewals 太多的续借 8 too many claims of items returned 太多的归还时需赔偿事项 9 too many items lost 太多的丢失事项 10 excessive outstanding fines 罚款未及时交 11 excessive outstanding fees 交费未及时交 12 recall overdue 召回超期 13 too many items billed 太多的事项有帐单

renyh commented 2 years ago

查看SIP2通道(数字平台扩展接口)

SIP2的通道是指SIP2前端与SIP2服务器的之间的TCP连接通道,虽然SIP2服务器会间接访问dp2library服务器,但SIP2通道与dp2library的通道是两回事。dp2library通道是由dp2library服务器端的通道应用池机制管理的,有可能有两个SIP2前端与SIP2服务器连接,是两根SIP2通道。但SIP2服务器去访问dp2library服务器时,dp2library根据自己的通道应用池机制,用一根dp2library通道就应对了,在内务观察到的通道是指dp2library的通道。 所以我们需要扩展一组查看SIP2通道的接口,方便SIP2前端查看当前SIP2服务器有多少根通道。

针对成千上万的数据量,如何做检索接口?

各种数据检索接口都是类似的。本次扩展好针对SIP2通道的检索接口后,后面其它接口也是类似的。

请求消息: 1)请求偏移量 2)请求最大数量:-1表示不限 3)检索词,不输表示获取全部通道,输入一个帐户名表示获取该帐户的所有通道 4)格式类型,xml,json

响应消息: 1)总数量 2)内容占一个字段 3)出错信息还使用通用的AF,AG

出错如何表示?是否需要固定长度的标志位,还是和总数量使用同一个参数。参考一下17/18,63/64消息。

服务器端如何实现?

服务器还是需要保存结果集,如果每次当前端请求时进行检索,再按请求的偏移量和数量返回数据。则前端分几次请求拿到的数据不一定是同批的,会混乱,因为服务器的数据是动态变化的,每次检索出来的数据可能不一定。 为了让前端请求简单,本次前端请求接口设计上就不用像dp2的检索接口分两个:即先检索得到结果集,再从结果集分批取数据。就设计一个检索接口,结果集的由服务器端保存和销毁。服务器端是结果哪个前端请求的,对应哪个结果集的。

服务器端什么时候销毁结果集?

一种方案是当前端请求完最后一拨数据后,服务器清除结果集。但这有一个问题,就是类似前面下载文件时暴露的md5不匹配的问题。有可以服务器的传输给前端的过程中出现问题,导致前端没有收到最后一拨数据,再前端再请求时,服务器已经没有结果集了。 所以服务器的结果集需要多留一会,留到何时呢?留到下一次前端检索请求从0获取数据,这次服务器一看是新一次检索的了,再清除上一次的结果集。这样的话,前端如果最后一批数据未收到,再获取最后一批数据时,发请求要只获取最后一批,如果从头获取,则是新的结果集了。

在SIP2前端增加的查看通道信息功能,如何显示?

SIP2前端先发起请求消息,服务器返回响应消息。 最简单的做法,是把返回的通道信息直接显示在右侧面板。更好一些的做法,可以提供一个通道管理的界面,用列表显示,即可以刷新查看,也可以中断,类似内务的通道管理窗。

renyh commented 2 years ago

获取通道信息 41/42

Channel Information 41

结构

41<transaction date><search word><start item><max count><format>
41  18-char ZW      BP  ZC  ZF

字段说明

字段名称 ID 格式 描述
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
search word ZW 必需 检索词,不输表示获取全部通道。
start item BP 必需 开始序号,从0开始。
max count ZC 必需 前端本次请求的最大数量,但服务不一定返回请求的数量,服务器根据服务器端的考量决定返回多少。-1表示不限。
format ZF 必需 需返回的数据格式,值为xml或json。

样例

4120181225    100150ZW|BP0|ZC10|ZFxml

注: 1)获取读者信息63使用的BQ指定一个结束的序号,本消息使用max count,表示前端请求的最大个数,但服务不一定返回请求的数量,服务器根据服务器端的考量决定返回多少。 2)是否需要机构代码?不涉及到读者和册,应该不需要。


Channel Information Response 42

结构

42<status><transaction date><total count><return count><channel value><screen message><print line>
1-char      18-char     ZT      ZR  ZV      AF      AG

字段说明

字段名称 ID 格式 描述
status   1-char, 必需 Y成功,N失败
transaction date   18-char, 必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20170623    151645。
total count ZT 必需 通道总数量。
return count ZR 必需 本次返回通道数量。
channel value ZV 必需 通道信息,xml或json格式。
screen message AF 可选 提示信息。
print line AG 可选 打印消息。

样例

42Y20181225    100158ZT10|ZR2|ZV<root>XXX</root>|AF共10根通道,本次返回2根通道。|AG共10根通道,本次返回2根通道。
SZCND commented 2 years ago

获取服务器状态98/99

SC Status 99

结构

99<status code><max print width><protocol version>
99  1-char  3-char  4-char

字段说明

字段名称 ID 格式 描述
status code 1-char,必须 0or1or2 状态代码,0表示正常,1表示SC打印机缺纸,2表示SC即将关机,通常参数值为0
max print width 3-char,必须 最大可打印的长度,通常传的值为030
protocol version 4-char,必须 当前使用的SIP协议版本,格式为x.xx,目前参数值为2.00

样例

send:9900302.00

注:2022/3/31 status code传9,表示前端与dp2服务器约定的一个状态。


ACS Status 98

结构

98<on-line status><checkin ok><checkout ok><ACS renewal policy><status update ok><off-line ok><timeout period><retries allowed>
98  1-char  1-char  1-char  1-char  1-char  1-char  3-char  3-char
<date/time sync><protocol version><institution id><library name><supported messages ><terminal location><screen message><print line>
18-char 4-char  AO  AM  BX  AN  AF  AG

字段说明

字段名称 ID 格式 描述
on-line status 1-char,必须Y or N 该字段表示系统在线还是离线,Y在线,N离线
checkin ok 1-char,必须Y or N Y表示允许SC还书
checkout ok 1-char, 必须 Y or N Y表示允许SC借出书
ACS renewal policy 1-char, 必须 Y or N Y表示ACS允许SC执行读者续借请求
status update ok 1-char, 必须 Y or N Y表示允许SC端更新读者状态
off-line ok 1-char, 必须 Y or N 是否支持离线操作。Y表示允许,N表示不允许,注:目前dp2传N
timeout period 3-char,必须 This timeout period until a transaction is aborted should be a number expressed in tenths of a second. 000 indicates that the ACS is not on-line. 999 indicates that the time-out is unknown.
retries allowed 3-char,必须 允许重试,999表示重试次数未知。注:目前dp2返回003
date / time sync 18-char,必须,格式为YYYYMMDDZZZZHHMMSS 注:目前dp2返回当前时间,例如20220330 191349
protocol version 4-char,必须,格式为x.xx 当前使用的SIP协议版本,格式为x.xx,目前值为2.00
institution id AO 必须 图书馆的机构代码,注:目前dp2返回机构代码
library name AM 可选 图书馆名称,注:目前dp2返回馆名称
supported messages BX 必须 支持的消息。Y表示支持相关的消息/响应。 N表示不支持消息/响应。注:目前dp2返回的值为XYYYYYYYYYYYYYYYY
terminal location AN 可选 终端位置,注:目前dp2未返回这个字段
screen message AF 可选 提示信息,注:dp2返回信息为空
print line AG 可选 打印信息,注:目前dp2未返回这个字段

样例

recv:98YYYYNN01000320220330    1913492.00AO|AM用户权限|BXYYYYYYYYYYYYYYYY|AF|AY4AZ1A2F
SZCND commented 2 years ago

交费37/38

Fee Paid 37

结构

37<transaction date><fee type><payment type><currency type><fee amount><institution id><patron identifier>
37      18-char       2-char    2-char         3-char         BV           AO             AA
<terminal password><patron password><fee identifier><transaction id>
AC                   AD               CG                  BK

字段说明

字段名称 ID 格式 描述
transaction date 18-char,必需 交易时间,格式为YYYYMMDDZZZZHHMMSS。例如:20180118 1309170100
fee type 2-char,必需 付款的费用类型,注:01 其它或未知,02 行政,03 损坏,04 超期,05 加工费,06 租金,07 更新,08 电脑访问费,09 预约费
payment type 2-char,必需 支付类型,注:00 表示现金
currency type 3-char,必需 货币类型,注:USD 美元、CNY 人民币
fee amount BV 必需 支付的费用金额
institution id AO 必需 图书馆的机构代码
patron identifier AA 必需 读者证条码号
terminal password AC 可选 SC端密码
patron password AD 可选 读者密码
fee identifier CG 可选 交费事项ID,对应64接口读者记录的一个fine item 例如:637895274065447889-2
transaction id BK 可选 付款设备分配的交易记录id

样例

send:3720180118    1309170100USDBV0.1|AOj163-z1|AAL120100000000000002|AY3AZEFFC

Fee Paid Response 38

结构

38<payment accepted><transaction date><institution id><patron identifier><transaction id><screen message><print line>
38  1-char  18-char  AO  AA  BK  AF   AG

字段说明

字段名称 ID 格式 描述
payment accepted 1-char,必需,Y or N 注:接受付款返回1,不接受返回0
transaction date 18-char,必需 交易时间,格式为YYYYMMDDZZZZHHMMSS 例如:20220607 142620
institution id AO 必需 图书馆机构代码 注:目前dp2返回机构代码
patron identifier AA 必需 读者证条码号
transaction id BK 可选 注:目前由图书馆系统分配的交易ID,承认接受了付款。
screen message AF 可选 屏幕消息内容
print line AG 可选 打印消息内容

样例

recv:38Y20220607    145053AOCN-123456-1-ZG|AA|BK|AF交费成功|AG交费成功|AY4AZD322