find_group_info

NAVIGATE CONTENT
Ex Libris Developer Network MetaLib Documentation MetaLib APIs X-Services find_group_info

General Purpose

This X-Service enables you to receive a report on the status of the search process for each resource by using the search identifier (= group_number).

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
  • source_locate– Locating database(s) by criteria
  • find – Performs a search request on a single resource or on group of resources.
  • find_group_info

Input Parameters

Mandatory
1. SESSION_ID – X(50)
2. GROUP_NUMBER – X(6)

Explanation of the mandatory and optional parameters:session_id – The session ID is the unique identifier of the login.
group_number – Group identifier of the result sets (sequence number). Retrieved by the find X-Service

Input XML Format

Example:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <find_group_info_request>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
    <group_number>000181</group_number>
  </find_group_info_request>
</x_server_request>

Input URL Syntax

In order to retrieve a result(s) report, the session_id and group_number attributes must be embedded within the URL syntax:

MetalibPath:port/X?op=find_group_info_request&group_number=group number&session_id=Login session

Example URL Syntax

Example: 

http://10.1.235.47:8335/X?op=find_group_info_request&group_number=000181&session_id=PB3AK5YHFB3AIN2T12FXX267SPABSADKJ8SYEN3CYJMR6A5TLL

Output XML Format

  • FORK – Before search
  • FIND – Search
  • FETCH – Start the first fetch process
  • DONE1 – 10 records fetched
  • DONE2 – 20 records fetched
  • DONE3 – 30 records fetched
Up to MetaLib configuration: NO_FETCHED_RESULT
  • DONE – All records fetched
  • STOP – Time out occured
  • ERROR – An error occured
  • ALLOW – not allowed to search on resource
Explanation of the Output values:
  • base – Database code
  • base_001 – Resource number. Unique number with institution prefix.
  • full_name – Resource name.
  • set_number – Sequence number for each resource per search.
  • find_status – Search status per resource.
  • 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 result per resource.
Example:
<x_server_response metalib_version="4.00 (20)">
  <find_group_info_response>
   <group_number>00181</group_number>
    <base_info>
      <base>BCL01</base>
      <base_001>CKB00025</base_001>
      <set_number>000035</set_number>
      <full_name>Boston College</full_name>
      <find_status>DONE</find_status>
      <no_of_documents>000000048</no_of_documents>
    </base_info>
    <base_info>
      <base>NTIS</base>
      <base_001>CKB02319</base_001>
      <full_name>NTIS</full_name>
      <set_number>000036</set_number>
      <find_status>DONE</find_status>
      <no_of_documents>000000000</no_of_documents>
    </base_info>
    <base_info>
      <base>PUBMED</base>
      <base_001>CKB00158</base_001>
      <full_name>PubMed</full_name>
      <set_number>000037</set_number>
      <find_status>DONE</find_status>
      <no_of_documents>000000198</no_of_documents>
    </base_info>
    <session_id new_session="N">QCALGQ8JUY5XB87GTU47UH54FEHFPRDR3289VBRRPMTK46X4FR</session_id>
  </find_group_info_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_group_info X-Service was activated after the session had timed out:

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

3. If the group_number parameter is missing:

<error_code>2008</error_code>
<error_text>The group-number is missing from the input.</error_text>

4. If there are no results:

<error_code>2007</error_code>
<error_text>There are no results</error_text>

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>

Comments

After using merge_sort_request with action merge_more, the group_number element is repeated for every base_info (with the same value) which is probably a bug. With xpath you have to select it using /descendant::group_number[1].

Also, a new “resource” appears in the list:

<base_info>
      <base>MERGESET</base>
      <full_name>Combined Set</full_name>
      <set_number>091428</set_number>
      <find_status>DONE</find_status>
      <no_of_documents>000000035</no_of_documents>
</base_info>