dp2API之SearchItem

SearchItem() – 检索实体库

        LibraryServerResult SearchItem(
            string strItemDbName,
            string strQueryWord,
            int nPerMax,
            string strFrom,
            string strMatchStyle,
            string strLang,
            string strResultSetName,
            string strSearchStyle,
            string strOutputStyle);

用途：检索实体库。

参数表：

类型	参数名	说明
string	strItemDbName	实体库名列表
string	strQueryWord	检索词
int	nPerMax	最大命中数。-1表示不限制
string	strFrom	检索途径
string	strMatchStyle	匹配方式
string	strLang	语言代码
string	strResultSetName	结果集名
string	strSearchStyle	检索方式。如果包含子串”desc”表示命中结果按照降序排列；包含子串”asc”表示按照升序排列。缺省为升序排列。
string	strOutputStyle	输出方式

返回值：

成员	返回值	说明
LibraryServerResult.Value		
	-1	错误
	0	没有命中
	>=1	命中。返回值为命中的记录条数
LibraryServerResult.ErrorInfo		出错信息

权限

权限：需要searchitem权限。读者身份登录不允许使用本API。

strItemDbName

strItemDbName参数的值可以为空、或者“<全部>”、或者“”，均表示针对当前存在的全部实体库进行检索。也可以由若干实体库名连接以逗号，表示只针对这些特定的实体库进行检索。dp2Library在执行时会验证此参数中提供的实体库名，如果不是已经定义的实体库名会返回出错。

strItemDbName参数的值还可以为“<全部图书>”、或者“”，表示针对当前存在的全部图书(而非期刊)实体库进行检索。还可以为“<全部期刊>”、或者“”，表示针对当前存在的全部期刊(而非图书)实体库进行检索。

strFromStyle

strFromStyle参数指定了检索途径。实体库具体可以使用哪些检索途径，可以参考dp2Library数据目录下的templates/item/keys文件。

当针对检索途径“__id”进行检索时，可以在检索词中使用符号“-”，构成范围检索请求。例如，检索词为“1-200”，表示希望检索记录ID从1到200范围的实体记录。

strMatchStyle

strMatchStyle参数指定了检索词在检索中的匹配方式。为left/middle/right/exact之一，分别表示前方一致/中间一致/后方一致/精确一致。如果检索词为空，匹配方式为”exact”，表示希望检索相关检索途径中的空值，也就是不具备这个检索点的记录。如果要以检索词为空检索出数据库中的全部具有相关检索点的记录，则需要用”left”匹配方式(最多能命中的结果数量受nPerMax参数的限制)。

strLang

strLang参数指定了当前语言。

strResultSetName

strResultSetName参数指定了结果集名。此参数值可以为空，相当于”default”。如果希望某一次检索产生的结果集内容不要被后继的检索操作冲掉，可以为每次检索使用不同的结果集名。 结果集名的名字空间范围是一个通讯通道以内。不同的通讯通道之间即便是相同的结果集名也对应着完全不同的结果集对象。在通道存活期间，只要没有后继的检索操作冲掉一个结果集原先的内容，那这个结果集原先的内容就会一直存在。

strSearchStyle

strSearchStyle参数指定了检索方式。如果值中包含”desc”子串，表示命中结果按照降序排列；如果包含”asc”子串，表示按照升序排列。缺省为升序排列。

strOutputStyle

strOutputStyle参数指定了检索命中结果输出到结果集中的方式。如为”keycount”，表示返回命中的检索点和命中数，而不返回具体命中的记录路径；如为”keyid”，则表示返回命中的记录路径和命中的检索点。缺省为”keyid”；如为空，则表示返回命中记录路径。后两种情况下，在利用获取结果集信息的API获取结果集内的元素信息的时候，可以有选择地获得记录的浏览列和记录本身(XML格式数据)。

本API执行后，只返回命中的结果数量，而检索命中的记录结果本身被存储在dp2Library端(实际上是在dp2Kernel)的结果集之中了，需要前端调用GetSearchResult() API才能获取结果集中的信息。

---

2023/2/8备注：

把 SearchItem() API 的两个参数的注释 paste 在这里：

        //      strSearchStyle  检索风格。
        //                      desc 表示检索结果集中的记录按照 id 倒序排列。缺省为正序
        //                      最终是通过 XML 检索式中 item/order 元素文本值 "DESC" 来实现的
        //      strOutputStyle  输出风格。
        //                      desc 表示倒序。
        //                      keycount 
        //                      keycount，则输出归并统计后的key+count(把相同的 key 后面的 count 合并)；否则，或者缺省，为传统的输出记录id
        //                      keyid，输出 key 和 id
        //                      如果 keycount 和 keyid 都没有，则表示仅输出 id
        //                      特殊用法, 如果包含 __buildqueryxml，则在result.ErrorInfo中返回XML检索式，但不进行检索

简单说，strOutputStyle 参数的用途是，它在检索和创建结果集的时候，把结果集的一些特殊形态预先处理好，建立起来。也就是说，如果检索和创建结果集的时候不完成这个任务，等到后面获取结果集内容的时候，也就是 GetSearchResult() API 调用的时候，就晚了，因为结果集结构已经固定了，无法增补这些特殊形态的内容。

哪些特殊形态呢？一般来说，所谓普通形态就是，结果集里面存储了每条记录的路径(俗称 id)。当我们用 GetSearchResult() API 去获取结果集内容的时候，根据这些记录路径可以发生出各种东西，这些东西都是普通的东西，很容易发生出来，所以就没有包含在结果集中。这些东西包括 cols, id, xml, timestamp, metadata 等等

这种一般形态，结果集中只保存 id。而 dp2kernel 还提供了其他的检索方式，比如，每个命中的 id 都携带一个当时命中的 key，这在检索过程中很容易按照要求处理，得到 key，然后 key+id 一起一组一组保存到结果集中。不过，一旦结果集创建完成，再要想在里面加入 key 难如登天。也就是说，等到 GetSearchResult() 阶段，是没法无中生有弄出来每个命中的 key 的。所以，关键的记忆点：这种特性应该是在 Search()(SearchItem() ... 等)阶段解决好。

刚才说这个俗称 key+id。另外还有一种检索方式，俗称 key+count，它在结果集中存储一个 key 加上这个 key 命中的个数，一组一组地。注意，这时结果集中没有 id! 自然，等到 GetSearchResult() 阶段，也只能获得 key 和 count，虽然可能也是放在 .Cols 这个 string [] 中返回，但确实不是一般的浏览列，只是把 .Cols 成员挪用了而已

所以 cols,id 要求，一般是在 GetSearchResult() 阶段，不是 Search() 阶段。当然，记忆这些比较困难，很多时候也是要查一下代码注释才能明确和回忆起来