General Purpose

This X-Service allows you to perform a search in a specified QuickSet.

The search can be a simple search or an advanced search and can include Boolean logic. The number of hits per resource is returned in the response.
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. The XML response output format will contain the number of hits from each resource.
  • Asynchronic: When the wait flag is set to N, X-Server sends the group identifier numbers of the result sets. The calling application should save the group identifiers and use them in order to retrieve a report on the status of the search process. This is done using the find_group_info X-Service.


  • 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
  • bor_info
  • retrieve_quick_sets – retrieves QuickSet’s ID
  • search_quick_sets

Input Parameters

1. SESSION_ID – X(50)
2. QUICK_SET_ID – 9(9)

1. WAIT_FLAG – X(1)

  • 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)


Explanation of the mandatory and optional parameters:

  • session_id – The session ID is the unique identifier of the login.
  • quick_set_id – The requested QuickSet. The QuickSet’s ID is provided in the retrieve_quick_sets X-Service.
  • 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.

More complex Search Syntax examples of find_request_command:

Supported Search CommandsNormalized Command
WRD=(aspirin) OR WRD=(tylenol)WRD=(aspirin) OR WRD=(tylenol)
(WRD=aspirin OR WRD=tylenol)WRD = (aspirin) OR WRD = (tylenol)
WRD=(aspirin OR tylenol)WRD = (aspirin AND tylenol)
(WRD=aspirin) OR (WRD=tylenol)WRD = (aspirin) OR WRD = (tylenol)
WRD=aspirin OR WRD=tylenolWRD = (aspirin) OR WRD = (tylenol)
WRD=(“aspirin tylenol”) AND WTI=(medicine) OR WSU = (magical power)WRD=(“aspirin tylenol”) AND WTI=(medicine) OR WSU=(magical AND power)

Unsupported find_request_command:

WRD=(aspirin OR WRD=tylenol
WRD=(aspirin) OR (tylenol)
  • wait_flag
    • N – Default – the service returns the group numbers and continues processing the search in the background. You can retrieve results by running the find_group_info service to query the group identifier.
    • 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.
  • filter_ird_authorization – 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


<?xml version = "1.0" encoding = "UTF-8"?>

Input URL Syntax

In order to search QuickSets, the input parameters must be embedded within the appropriate URL syntax:


Example URL Syntax


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 – Resource number.
  • 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.


<x_server_response metalib_version="4.00 (20)">
      <find_error_text>Search failed</find_error_text>
    </base_info><session_id new_session=N>

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_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 this X-Service was activated after the session had timed out:

<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_text>The number of the resources is greater than the search limit parameter</error_text>

4. If the set does not exist:

<error_text>Set $1 does not exist</error_text>

5. If the set ID is missing:

<error_text>Set ID is mandatory</error_text>

6. If authorized resources are missing:

<error_text>Can't find any authorized resources for searching.</error_text>

7. If a specific resource does not exist:

<error_text>Resource $1 does not exist.</error_text>

8. If Find request can’t be parsed for a specific resource:

<error_text>Find request can't be parsed per resource $1.</error_text>

9. If the system is too busy:

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

10. If the search server is not running:

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

11. If the institution does not exist:

<error_text>Institution does not exist</error_text>

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

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

13. If the Z39.50 gate is down:

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

14. If the format of the pds_handle is incorrect:

<error_text>Invalid pds_handle format</error_text>

15.If the pds_handle is not valid:

<error_text>Invalid pds_handle</error_text>

16.If the search syntax is invalid:

<error_text>Search request not supported</error_text

If 14 or 15 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>


If you wait for the results (wait_flag=”Y”), the resulting group info does not have full_name elements for the resources so you have to make an extra find_group_info_request; find_request with wait flag does return full info. (version 4.5.3 (804))