search_my_sets

General Purpose

This X-Service enables you to retrieve MetaLib system parameters and run time status of Metalib programs.

The search can be simple or advanced 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.

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
  • retrieve_my_sets – retrieves My Databases ID.
  • search_my_sets

Input Parameters

Mandatory
1. SESSION_ID – X(50)
2. MY_SET_ID – 9 (9).
3. FIND_REQUEST_COMMAND – X (256).

Optional
1. WAIT_FLAG – X (1)
2. CALLING_APPLICATION – X (100).

Explanation of the mandatory and optional parameters:

  • session_id – The session ID is the unique identifier of the login.
  • my_set_id – The requested My Databases. The My Databases’s ID is provided in the retrieve_my_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
    • NDefault – 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. 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.
  • 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>
  <search_by_my_set_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <my_sets_id>000000001</my_sets_id>
    <find_request_command>WRD=(search)</find_request_command>
    <wait_flag>Y</wait_flag>
  </search_by_my_set_request>
</x_server_request>

Input URL Syntax

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

MetalibPath:port/X?op=search_by_my_set_request&my_set_id=My Databases-sequence&find_request_command=search_command&wait_flag=wait_flag&session_id=session_id

Example URL Syntax

http://ram47:8334/X?op=search_by_my_set_request&my_set_id=000000001&find_request_command=WRD=(books)&wait_flag=Y&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

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

Example:

<x_server_response metalib_version="4.00 (20)">
  <find_response>
    <group_number>000000001</group_number>
    <base_info>
      <base_001>CKB00025</base_001>
      <set_number>000007</set_number>
      <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>
      <set_number>000008</set_number>
      <find_status>DONE</find_status>
      <no_of_documents>000000008</no_of_documents>
    </base_info>
    <base_info>
      <base_001>CKB00158</base_001>
      <set_number>000009</set_number>
      <find_status>DONE</find_status>
      <no_of_documents>000000197</no_of_documents>
    </base_info>
    <session_id new_session=N>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</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 this 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 My Databases does not exist:

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

5. If My Databases ID is missing:

<error_code>3102</error_code>
<error_text>Set ID is mandatory</error_text>

6. If the set contains resources that the user is no longer authorized to use or the resources are no longer available:

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

7. If a specific resource does not exist:

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

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

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

9. If the system is too busy:

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

10. If the search server is not running:

<error_code>6010</error_code>
<error_text>Failed to run SEARCH server</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 search syntax is invalid:

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

Possible Find Error Codes

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>