retrieve_my_sets

General Purpose

This X-Service retrieves a list of ‘My Databases’ sets defined for a logged-in user and retrieve information about each set.

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 handleor bor_info
  • retrieve_my_sets

Input Parameters

Mandatory

1. SESSION_ID – X(50)

2. USER ID OPTIONS:

  • Option 1
    • SOURCE_ID – X(40).
    • INSTITUTE – X(30).
    • VERIFICATION – X(20).
  • Option 2
    • BOR_ID – X (12).
    • VERIFICATION – X (20).
  • Option 3
    • PDS_HANDLE – X(50)

Explanation of the mandatory and optional parameters:

  • session_id – The session ID is the unique identifier of the login.
  • user id – One of the following:
    1. source_id – source_ID of user requesting My Databases.
      institute – User’s institution.
      verification – User’s password
    2. bor_id – User_ID of the user requesting My Databases.
      verification – User’s password
    3. pds_handle – User’s unique token returned by the remote authentication system

Input XML Format

Example:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <retrieve_my_sets_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
      <source_id>metalib</source_id>
      <verification>metalib</verification>
      <institute>METALIB</institute>
  </retrieve_my_sets_request>
</x_server_request>

Input URL Syntax

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

MetalibPath:port/X?op=retrieve_my_sets_request&bor_id=patron num&verification=***&session_id=session_id

Example URL Syntax

http://ram47:8334/X?op=retrieve_my_sets_request&source_id=David&verification=David&institute=metalib&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Information about each MySet:

  • Set sequence – Unique key in MetaLib. Use this key for searching the MySet by the search_my_sets X-Service.
  • Set name – Name of the Set.
  • Set description – Description of the Set.
  • No bases – Number of resources, defined in the Set.

Example:

<x_server_response metalib_version="4.00 (20)">
  <retrieve_my_sets_response>
  <set_info>
    <set_sequence>000000001</set_sequence>
    <set_name>Private1</set_name>
    <set_description></set_description>
    <no_bases>000000005</no_bases>
  </set_info>
  <set_info>
    <set_sequence>000000002</set_sequence>
    <set_name>Private2</set_name>
    <set_description></set_description>
    <no_bases>000000004</no_bases>
  </set_info>
  <session_id new_session="n">32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
  </retrieve_my_sets_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 user-id cannot be found:

<error_code>6001</error_code>
<error_text>User does not exist</error_text>

4. User ID is mandatory:

<error_code>6004</error_code>
<error_text>User Id is mandatory</error_text>

5. If the requested user has no sets:

<error_code>6005</error_code>
<error_text>User has no MySets</error_text>

6. If the institution does not exist:

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

7. If the format of the pds_handle is incorrect:

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

8. If the pds_handle is not valid:

<error_code>6061</error_code>
<error_text>Invalid pds_handle</error_text>

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

Notes

Output XML Format example is wrong (or valid only for a very old MetaLib version). There is no set_sequence element, it’s mysets_id.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<x_server_response metalib_version="4.4.3 (731)">
  <retrieve_my_sets_response>
    <set_info>
      <mysets_id>000102013</mysets_id>
      <set_name>Clipboard</set_name>
      <set_description/>
      <no_bases>000000024</no_bases>
    </set_info>
    <set_info>
      <mysets_id>000115950</mysets_id>
      <set_name>Test 1</set_name>
      <set_description>Description 1</set_description>
      <no_bases>000000004</no_bases>
    </set_info>
    <session_id new_session="N">9F6MY1YE6IEU19AV2TP83JNIA483AF4LVTKHA582QB9CH7GBA2</session_id>
  </retrieve_my_sets_response>
</x_server_response>