find

General Purpose

This X-Service submits a search request to a single resource or to a group of resources.
The resources are identified by their unique MetaLib ID. MetaLib limits the number of resources that can be searched within a single search request. This limit is one of MetaLib’s global parameters ( www_metalib_search_limit).

The search result sets are given a unique identifier, which is sent as part of the response (group_number).

There are two modes of retrieving the search results: synchronic and asynchronic:

  • Synchronic: When the wait flag is set to Y, X-Server sends the response only when the results from all of the searched resources are available. If time-out occurs before the service has finished fetching results from all available resources, this service will send a response containing the group identifier number as if the wait flag was sent without being set to On.
  • Asynchronic: If the request is sent without the wait_flag being set to On, the X-Server sends the group identifier numbers of the result sets. The calling application saves the group identifiers and uses them in order to retrieve a report on the status of the search process. This is done using the find_group_info X-Service.

Flow

  • login – Called once by the calling application with valid /X user name and password. The session-id retrieved should be passed to all other API calls
  • Authentication (either local or remote)
    • bor_auth – for local authentication of the user and to retrieve a valid borrower’s ID
    • PDS authentication – for remote authentication of the user and to obtain a pds handle
      or bor_info
  • retrieve_quick_sets – retrieves QuickSet’s ID
  • source_locate – Locating database(s) by criteria

Input Parameters

Mandatory
1. FIND_REQUEST_COMMAND – X(500).
2. FIND_BASE_001 – X(20).
3. SESSION_ID – X(50).

Optional
1. WAIT_FLAG – X(1)
2. FIND_FILTER:

  • Option 1
    • REQUESTER_IP – X(12)
    • INSTITUTE – X(30)
    • USER_GROUP – X(30)
  • Option 2
    • REQUESTER_IP – X(12)
    • INSTITUTE – X(30)
  • Option 3
    • REQUESTER_IP – X(12)
  • Option 4
    • INSTITUTE – X(30)
  • Option 5
    • INSTITUTE – X(30)
    • USER_GROUP – X(30)
  • Option 6
    • REQUESTER_IP – X(12)
    • PDS_HANDLE – X(50)
  • Option 7
    • PDS_HANDLE – X(50)

3. CALLING_APPLICATION – X(100)

Explanation of the mandatory and optional parameters:

    • find_request_command – Search criteria according to the syntax : WRD= any word, WTI= word from title, WAU= word from author, WSU= word from subject, WYR= year, ISSN= issn, ISBN= isbn.

More complex Search Syntax examples of find_request_command:

Supported Search CommandsNormalized Command
WRD=(baby) OR WRD=(infant)WRD=(baby) OR WRD=(infant)
(WRD=baby OR WRD=infant)WRD = (baby) OR WRD = (infant)
WRD=(baby OR infant)WRD = (baby AND infant)
(WRD=baby) OR (WRD=infant)WRD = (baby) OR WRD = (infant)
WRD=baby OR WRD=infantWRD = (baby) OR WRD = (infant)
WRD=(“baby boom”) AND WTI=(medicine) OR WSU = (magical power)WRD=(“baby boom”) AND WTI=(medicine) OR WSU=(magical AND power)

Unsupported find_request_command:

WRD=(baby OR WRD=infant)
WRD=(baby) OR (infant)
  • find_base_001 – Resource number. Unique number with institution prefix.
  • session_id – The session ID is the unique identifier of the login.
  • wait_flag – Valid Values
    • N – Default – the service returns the group numbers and continues processing the search in the background. Results can be retrieved by the find_group_info X-Service querying the group indentifier. The find_group_info X-Service indicates the fetching program (see find_group_info for more information.
    • Y – The service returns the result only after all resources have finished performing the search query. The result contains full information for each resource (hits, status, and so on). Note that a single search might take between 10 seconds up to the time-out limitation in MetaLib. The DONE status indicates that fetching is completed.
  • find_filter – wrapper of three input parameters (requester_ip, institute and user group) used for filtering of resources. If filter_ird_authorization is not provided, the requester_ip, institute and user_group are ignored.
  • requester_ip – user’s IP address, in case resource filtering is needed.
  • institute – user’s institution, in case resource filtering is needed.
  • user_group – user’s affiliation group, in case resource filtering is needed.
  • pds_handle – user’s unique token returned by the remote authentication system, in case resource filtering is needed.
  • calling_application – Name of the calling application. If not specified, default name is “X-SERVER”, and it will be stored in exact case.

Input XML Format

Example:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <find_request>
    <wait_flag>Y</wait_flag>
    <find_filter>
      <requester_ip>Requester IP</requester_ip>
      <institute>Institution</institute>
      <user_group></user_group>
    </find_filter>
    <find_request_command>WRD=("baby") AND WTI=(medicine) OR WSU = (magical power)</find_request_command>
    <find_base>
      <find_base_001>LOC00025</find_base_001>
    </find_base>
    <find_base>
      <find_base_001>LOC00230</find_base_001>
    </find_base>
    <find_base>
      <find_base_001>LOC00039</find_base_001>
    </find_base>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
  </find_request>
</x_server_request>

Input URL Syntax

In order for an affiliated user or guest to perform a search in a database, the Wait_flag, Request_ip, Institute, User_group, Find_request_command, Find_base_001 and Session_id attributes must be embedded within the URL syntax:

MetalibPath:port/X?op=find_request&wait_flag=N/Y&requester_ip=requester ip&institute=institution&user_group= group name&find_request_command=search string&find_base_001=Institute unique number&find_filter=requester_ip, institute and user_group&session_id=Login session

Example URL Syntax

http://ram47:8334/X?op=find_request&wait_flag=Y&find_request_command=WRD=(books)&find_base_001=CKB00009&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Explanation of the output values:

  • group_number – The group identifier of the result set (sequence number). Using this identifier, the calling application can receive a report on the status of the search process for each resource. This is done by using the find_group_info service.
  • base_001 – Unique number with institution prefix.
  • full_name – Resource name.
  • set_number – Sequence number for each resource per search.
  • find_status – Search status per resource. Valid Values: Done; Error
  • find_error_code – Error number which only appears if find_status = error. See below for list of possible values.
  • find_error_text – Error message, only if find_status = error.
  • no_of_documents – Number of results (documents) retrieved per resource.

Examples:
wait_flag set to N
If the wait_flag is set to N, the process will run in the background and the group number will be returned to the calling application. The results of the search are obtained by invoking the find_group_info X-Service:

<x_server_response metalib_version="4.00 (20)">
  <find_response>
    <group_number>000003</group_number>
    <session_id new_session="N">GYX6ML7HD7H4J7UTVV2M8F3C8GVLAIEGGBURF3L6IURDFV628G</session_id>
  </find_response>
</x_server_response>

wait_flag set to Y
If the wait_flag is set to Y, the calling application will receive full information about each resource (hits, status, and so on) when the process ends:

<x_server_response metalib_version="4.00 (20)">
  <find_response>
    <group_number>000004</group_number>
    <base_info>
      <base_001>CKB00025</base_001>
      <set_number>000007</set_number>
      <full_name>Boston College</full_name>
      <find_status>ERROR</find_status>
      <find_error_code>0114</find_error_code>
      <find_error_text>Search failed</find_error_text>
      <no_of_documents>000000000</no_of_documents>
    </base_info>
    <base_info>
      <base_001>CKB02319</base_001>
      <full_name>NTIS</full_name>
      <set_number>00000B</set_number>
      <find_status>DONE</find_status>
      <no_of_documents>000000000</no_of_documents>
    </base_info>
    <base_info>
      <base_001>CKB00158</base_001>
      <full_name>PubMed</full_name>
      <set_number>000009</set_number>
      <find_status>DONE</find_status>
      <no_of_documents>000000197</no_of_documents>
    </base_info>
    <session_id new_session="N">93YYYB56VY7LE57EM7G25BYBYJ21LBK35CPG41VI2Y8P4UUH9X</session_id>
  </find_response>
</x_server_response>

Possible Error Codes

1. If the session_id, provided as an input parameter, is not valid, the following error message appears in the XML output:

<error_code>0151</error_code>
<error_text>You are not authorized to use this function</error_text>

This can be caused by not using the session_id returned from the Login X-Service.

2. If the Find X-Service was activated after the session had timed out:

<error_code>2050</error_code>
<error_text>Session timeout</error_text>

3. If the number of resources in the search request is greater than the search limit parameter (www_metalib_search_limit):

<error_code>0200</error_code>
<error_text>The number of the resources is greater than the search limit parameter</error_text>

4. If one of the parameters is missing:

<error_code>2038</error_code>
<error_text>Missing element from XML request - " verification ".</error_text>

5. If there are no resources in the input:

<error_code>0204</error_code>
<error_text>Missing resource in the input parameters </error_text>

6. If the resource is not searchable:

<error_code>2041</error_code>
<error_text>Resource is not searchable</error_text>

7. If the resource does not exist:

<error_code>2039</error_code>
<error_text>Resource does not exist</error_text>

8. If the system is too busy:

<error_code>6009</error_code>
<error_text>System busy. Try again later</error_text>

9. If the search server is not running:

<error_code>6010</error_code>
<error_text>Failed to run SEARCH server</error_text>

10. If the institution does not exist:

<error_code>6025</error_code>
<error_text>Institution does not exist</error_text>

11. If time-out occurs before the service has finished fetching results from all available services:

<error_code>6026</error_code>
<error_text>Interactive search is still in process. Use "find group info" to determine the search status </error_text>

12. If the Z39.50 gate is down:

<error_code>6012</error_code>
<error_text>Z39.50 gate is not running</error_text>

13. If the format of the pds_handle is incorrect:

<error_code>6062</error_code>
<error_text>Invalid pds_handle format</error_text>

14.If the search syntax is invalid:

<error_code>2999</error_code>
<error_text>Search request not supported</error_text

Note:
If 13 or 14 above are returned, the request will not terminate in error. The onus is on the calling application as to how to proceed.

Possible Find Error Codes

When errors are encountered during the search process, the service returns both the find_error_code and find_error_text. Following is a list of possible errors returned if the target cannot process the search:

1. <find_error_code>0001</find_error_code>
<find_error_text>General communication error</find_error_text>2. <find_error_code>0002</find_error_code>
<find_error_text>Target server not responding</find_error_text>3. <find_error_code>0008</find_error_code>
<find_error_text>Failed to read reply from target</find_error_text>

4. <find_error_code>0009</find_error_code>
<find_error_text>Failed to update registration parameters.</find_error_text>

5. <find_error_code>0050</find_error_code>
<find_error_text>Z39.50 gate not running.</find_error_text>

6. <find_error_code>0051</find_error_code>
<find_error_text>Z39.50 target not defined on the Z39.50 gate.</find_error_text>

7. <find_error_code>0052</find_error_code>
<find_error_text>Z39.50 target definition is not correct on the Z39.50 gate.</find_error_text>

8. <find_error_code>0053</find_error_code>
<find_error_text>Connection refused by the Z39.50 target.</find_error_text>

9. <find_error_code>0054</find_error_code>
<find_error_text>Connection rejected by the Z39.50 database server.</find_error_text>

10. <find_error_code>0055</find_error_code>
<find_error_text>The Z39.50 gate could not map the CCL code to RPN form.</find_error_text>

11. <find_error_code>0056</find_error_code>
<find_error_text>Z39 target reported an error:</find_error_text>

12. <find_error_code>0057</find_error_code>
<find_error_text>The Z39 gate could not write result set.</find_error_text>

13. <find_error_code>0058</find_error_code>
<find_error_text>The Z39 gate could not recover result set.</find_error_text>

14. <find_error_code>0059</find_error_code>
<find_error_text>The requested document is not in the Z39’s set.</find_error_text>

15. <find_error_code>0060</find_error_code>
<find_error_text>Record not found on the Z39 server.</find_error_text>

16. <find_error_code>0061</find_error_code>
<find_error_text>Unspecified Z39 gate error.</find_error_text>

17. <find_error_code>0065</find_error_code>
<find_error_text>Target response timeout.</find_error_text>

18. <find_error_code>0114</find_error_code>
<find_error_text>Search failed</find_error_text>

19. <find_error_code>0204</find_error_code>
<find_error_text>MetaLib cannot retrieve the number of hits from the target</find_error_text>

20. <find_error_code>0219</find_error_code>
<find_error_text>Failed to establish connection.</find_error_text>

Notes

There shouldn’t be a problem to search up to 100 databases.