source_locate

Ex Libris Developer Network MetaLib Documentation MetaLib APIs X-Services source_locate

General Purpose

This X-Service is used to locate databases by matching criteria.

Access to resources in MetaLib is controlled by the affiliation of a user to an institution and optionally to a user group and IP (the <source_locate_filter> parameters).

This service returns a list of databases matching the criteria with partial, full or selected (customized) information on each of the retrieved databases.

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 (optional, 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 (optional)
retrieve_category – optional, retrieves Categories ID, used in conjunction with WFL (see below)
source_locate

Input Parameters

Mandatory
1. SESSION_ID – X(50)
2. LOCATE_COMMAND – X(500)

Optional
1. SOURCE_FULL_INFO_FLAG – X(1)

2. VIEW – X(9)

FIELD
SUB_FIELD

3. SOURCE_LOCATE_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)

4. CALLING_APPLICATION – X(100)
5. PRIMO_DETAILS – X(1)

Explanation of the mandatory and optional parameters:

Note that you can use either source_full_info_flag or view, but not both.

source_full_info_flag – Retrieve full resource information indicator. Valid Values:
- N – Retrieve partial information for each resource – Default
- Y – Retrieve full information for each resource
view – used to retrieve only specified fields/sub-fields from database records, according to input parameters below (in the <field> and <sub_field> fields). Valid values:
- customize
field – enter one of the document field codes.
The field code format is between three to five characters, for example: “245” – Full name, “85641” – Link to URL, “AF3” – User group, “LCL1” – Local field 1.
- – Use # to specify a wildcard, for example 856## for all the external links.
- – Use ##### to retrieve all fields and subfields.
- – For URL syntax, use “%23” instead of “#”.
sub_field – valid values:
1. empty – retrieves all the subfields
2. letters – retrieves the specified subfields
source_locate_filter – wrapper of three input parameters (requester_ip, institute and user_group) used for filtering of resources. If source_locate_filter is not provided, the requester_ip, institute and user_group are ignored.
session_id: The session ID is the unique identifier of the login.
locate_command – Search criteria key words. More than one command can be entered. The commands will create one unified string. Syntax: WCL=name, WRD=any word, WTY=type, WPB=publisher, WFL=category sequence.
The locate_command can be used to perform an “exact”, “starts with” and “new” search:
- exact – use SNM=”institute_code search_term”, for example: SNM=”METALIB Pubmed”.
- starts with – use SNM=”institute_code A-Z?”, for example: SNM=”METALIB P?”.
- new – to return resources defined as new use WND = ( current_date -> 99999999 ) AND WIN = institute_code, for example: WND = ( 20090205 -> 99999999 ) AND WIN = METALIB.
  For more information on IRD indexes, see the MetaLib Resource Management Guide. Note that the WFL index cannot be used in conjuction with other indexes.
requester_ip – IP of the machine to which the requester is connected.
institute – The requested user’s institution.
user_group – Defined groups in the institution. Retrieved in the bor_info response. “Guest” or ” ” are both valid values and will locate resources available to non-authenticated (guest) users.
pds_handle – User’s unique token returned by the remote authentication system
calling_application – Name of the calling application. If not specified, default name is “X-SERVER”, and it will be stored in exact case.
primo_details – Additional information indicator. Valid Values:
- N – Retrieves authorized resources only (according to the defined filter).
- Y – Retrieves all resources with authorization data and the resource’s IP range (if defined).

Input XML Format

Example 1:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <source_locate_request>
    <session_id>32GS85B67MEX93N5PX6AAH8PYEXI1XPNPMQU8SCHJ9QR1R5I5D</session_id>
    <source_locate_filter>
      <requester_ip>REQUESTER IP</requester_ip>
      <institute>Institution</institute>
      <user_group></user_group>
    </source_locate_filter>
    <locate_command>WIN=METALIB AND WRD=global</locate_command>
    <source_full_info_flag>N</source_full_info_flag>
  </source_locate_request>
</x_server_request>

Example 2:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <source_locate_request>
    <session_id>89U4TMKUXI5H3T34GIU1F89VS82FKLYJTXAI1C3D1KGIN2PXGK</session_id>
    <source_locate_filter>
      <requester_ip></requester_ip>
      <institute>METALIB</institute>
      <user_group></user_group>
    </source_locate_filter>
    <locate_command>WFL=000000082</locate_command>
    <view>customize</view>
    <field>245</field>
    <sub_field>a</sub_field>
    <field>520</field>
    <field>260</field>
    <field>85642</field>
  </source_locate_request>
</x_server_request>

Input URL Syntax

In order for the calling application to locate database(s), the session_id, request_id, institute, user_group and locate_command attributes must be embedded within the URL string:

MetalibPath:port /X?op=source_locate_request&session_id=Login session&source_locate_filter=&requester_ip=requester ip&institute=Institution&user_group= group name&locate_command=WIN=METALIB&source_full_info_flag=N/Y

Example URL Syntax

Example 1:

http://10.1.235.47:8334/X?op=source_locate_request&source_locate_filter=&requester_ip=10.1.235.47&institute=METALIB&user_group=GUEST&locate_command=WIN=(METALIB)&source_full_info_flag=N&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Example 2:

http://10.1.235.47:8334/X?op=source_locate_request&locate_command=WFL=000000179&source_full_info_flag=N&session_id=L9UUHVLPA7LUTEQYM7YJX8GLH6FDR2V77GRG6TIQ21UIXQEXH2

Output XML Format

Explanation of the output values:

source_internal_number – Unique IRD (Resource) system number.
source_001 – Resource number. Unique number with the institution’s prefix.
source_name – Resource full name.
source_short_name – Resource display name.
source_searchable_flag – Link to resources or searchable resources.
no_of_hits – Results (records) number.
ird_permission – Resource’s authorization status.
ip_filter_from – Resource’s IP range indicators.

Example 1:

There are results and source_full_info_flag is “N”

If there are results and the source_full_info_flag is “N”, partial information on the requested resource(s) is returned:

<x_server_response metalib_version="4.00 (20)">
  <source_locate_response>
    <source_info>
      <source_internal_number>000000389</source_internal_number>
      <source_001>CKB02166</source_001>
      <source_name>Ingenta Select (Ingenta)</source_name>
      <source_short_name>Ingenta Select (Ingenta)</source_short_name>
      <source_searchable_flag>Y</source_searchable_flag>
    </source_info>
    <source_info>
      <source_internal_number>000000443</source_internal_number>
      <source_001>CKB02241</source_001>
      <source_name>Journal of Medical Systems (IngentaSelect)</source_name>
      <source_short_name>Journal of Medical Systems (IngentaSelect)</source_short_name>
      <source_searchable_flag>Y</source_searchable_flag>
      </source_info>
    <no_of_hits>000002</no_of_hits>
    <session_id new_session="N">3B7F9EQE259KNK1YUK462VCCG4455T4BUPUC5B9LVQS9XD16U6</session_id>  </source_locate_response>
</x_server_response>

Example 2:

There are results and source_full_info_flag is “Y”, MARC

If there are results and the source_full_info_flag is “Y”, MARC format full information for the requested resource(s) is returned:

<x_server_response metalib_version="4.00 (20)">
  <source_locate_response>
    <source_full_info>
      <source_info><source_internal_number>000000389</source_internal_number>
      <source_001>CKB02166</source_001>
      <source_name>Ingenta Select (Ingenta)</source_name>
      <source_short_name>Ingenta Select (Ingenta)</source_short_name>
      <source_searchable_flag>Y</source_searchable_flag>
      </source_info>
        <record xmlns="http://www.loc.gov/MARC21/slim/"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.loc.gov/MARC21/slim
        >http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd"
          <controlfield tag="001">CKB02166</controlfield>
        <datafield tag="245" ind1="1" ind2=" ">
          <subfield code="a">Ingenta Select (Ingenta)</subfield>
        </datafield>
        <datafield tag="246" ind1="1" ind2=" ">
          <subfield code="a">was Catchword</subfield>
        </datafield>
        <datafield tag="210" ind1=" " ind2<=" "
          <subfield code="a">Ingenta Select (Ingenta)</subfield>
        </datafield>
        <datafield tag="520" ind1=" " ind2<=" "
          <subfield code="a">Providing access to thousands of online journals from leading scholarly, academic and
          business publishers, the Ingenta Select service provides fast and reliable access from a global network of
          servers to users' desktops around the world. ## ## Ingenta Select provides access
          to more than 5,000 electronic publications from over 190 publisher clients and bring together an extensive
          range of services for the librarian and nd-user alike</subfield>
        </datafield>
        <datafield tag="594" ind1=" " ind2=" ">
          <subfield code="a">FREE</subfield>
        </datafield>
        <datafield tag="592" ind1=" " ind2=" ">
          <subfield code="a">There are no ISBNs in this resource. ## ##Year searches are not          supported.</subfield>
        </datafield>
        <datafield tag="595" ind1=" " ind2=" ">
          <subfield code="a">There are no ISBNs in this resource. ## ##Year searches are           not supported.</subfield>
        </datafield>
        <datafield tag="593" ind1=" " ind2=" ">
          <subfield code="a">This resource uses WEBConfig. The Hostname:Port is http://www.ingentaselect.com/rpsv//
          cgi-bin/jsearch?mode=search&form=expert&search1=&action~searchdb=Search&
          ## ##The CKB also includes an example of an IRD that searches one journal in Ingenta Select.
          See Journal of Medical Systems. The parameter LimitToTitle=0148-5598& is added to the Hostname:Port
          to limit searches just to that journal.</subfield>
        </datafield>
        <datafield tag="110" ind1="2" ind2=" ">
          <subfield code="a">Ingenta</subfield>
        </datafield>
        <datafield tag="260" ind1=" " ind2=" ">
          <subfield code="b">Ingenta</subfield>
        </datafield>
        <datafield tag="TAR" ind1=" " ind2=" ">
          <subfield code="a">INGENTA_SELECT>/subfield<
          <subfield code="f">Y</subfield>
        </datafield>
        <datafield tag="ZHS" ind1=" " ind2=" ">
          <subfield code="a">http://www.ingentaselect.com/rpsv//cgi-bin/jsearch?mode=search&form=expert
          &search1=&action~searchdb=Search&</subfield>
        </datafield>
        <datafield tag="AF1" ind1=" " ind2=" ">
          <subfield code="a">METALIB</subfield>
        </datafield>
        <datafield tag="AF3" ind1=" " ind2=" ">
          <subfield code="a">GUEST</subfield></datafield>
        <datafield tag="STA" ind1=" " ind2=" ">
          <subfield code="a">ACTIVE</subfield>
        </datafield>
        <datafield tag="FIL" ind1=" " ind2=" ">
          <subfield code="a">General Interest</subfield>
        </datafield>
        <datafield tag="LUP" ind1=" " ind2=" ">
          <subfield code="a">20040709</subfield>
        </datafield><controlfield tag="FMT">DD</controlfield>
        <datafield tag="856" ind1="4" ind2="2">
          <subfield code="u"><//subfield>
        </datafield>
        <datafield tag="856" ind1="4" ind2="1">
          <subfield code="u"><//subfield>
        </datafield>
        <datafield tag="655" ind1=" " ind2=" ">
          <subfield code="a">Index</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2<=" "
          <subfield code="c">20040518</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1744</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="a">chrisr</subfield>
          <subfield code="b">00</subfield>
          <subfield code="c">20040630</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1735</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="a">chrisr</subfield>
          <subfield code="b">00</subfield>
          <subfield code="c">20040708</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1119>/subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040723</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">0902>/subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040723</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">0905</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040723</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1639</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2=" ">
          <subfield code="c">20040805</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1348</subfield>
        </datafield>
        <datafield tag="CAT" ind1=" " ind2<=" "
          <subfield code="c">20041130</subfield>
          <subfield code="l">DAT01</subfield>
          <subfield code="h">1646</subfield>
        </datafield>
      </record>
    </source_full_info>
    <no_of_hits>000002</no_of_hits>
    <session_id new_session="N">3B7F9EQE259KNK1YUK462VCCG4455T4BUPUC5B9LVQS9XD16U6</session_id>
  </source_locate_response>
</x_server_response>

Example 3:

There are results, view flag is “customize”, field is set to “245” and sub-field to “a”

If there are results only the Title field is returned in the “source_customize_info” element.

<?xml version = "1.0" encoding = "UTF-8"?> 
<x_server_response metalib_version="4.01 (42)"> 
  <source_locate_response> 
    <source_customize_info> 
      <source_info> 
        <source_internal_number>000000524</source_internal_number> 
        <source_001>CKB02329</source_001> 
        <source_name>DOE Information Bridge</source_name> 
        <source_short_name>DOE Information Bridge</source_short_name> 
        <source_searchable_flag>Y</source_searchable_flag> 
      </source_info> 
      <record xmlns="http://www.loc.gov/MARC21/slim"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://www.loc.gov/MARC21/slim 
      >http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd" 
        <datafield tag="245" ind1="1" ind2=" "> 
          <subfield code="a">DOE Information Bridge</subfield> 
        </datafield> 
      </record> 
    </source_customize_info> 
    <source_customize_info> 
       <source_info> 
         <source_internal_number>000000537</source_internal_number> 
         <source_001>CKB02342</source_001> 
         <source_name>Energy Citations Database (DOE)</source_name> 
         <source_short_name>Energy Citations Database (DOE)</source_short_name> 
         <source_searchable_flag>Y</source_searchable_flag> 
       </source_info> 
       <record xmlns="http://www.loc.gov/MARC21/slim"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.loc.gov/MARC21/slim 
       >http://www.loc.gov/standards/marcxml/schema/MARC21slim.xsd" 
         <datafield tag="245" ind1="1" ind2=" "> 
           <subfield code="a">Energy Citations Database (DOE)</subfield> 
         </datafield> 
       </record> 
     </source_customize_info> 
  <no_of_hits>000002</no_of_hits> 
  <session_id new_session="N">P8XPG7H6D8Y8S3CKMTCXCNHXCJNQKTAC4Y5DXSB5YEAPUT1PGP</session_id> 
  </source_locate_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 one of the parameters is missing:

<error_code>2038</error_code>
<error_text>Missing element from XML request</error_text>

4. If there are no results:

<error_code>0149</error_code>
<error_text>No resources found</error_text>

5. If both parameters are given values:

<error_code>2125</error_code>
<error_text>The VIEW and SOURCE_FULL_INFO_FLAG parameters can't be used together</error_text>

6. If the locate command consists of WFL=<category_sequence> and another search term:

<error_code>2126</error_code>
<error_text>Invalid LOCATE_COMMAND</error_text>

7. If no fields are specified and the view option is set to “customize”:

<error_code>2128</error_code>
<error_text>No fields specified for the customize option</error_text>

8. If the Source_full_info_flag is not Y/N:

<error_code>3000</error_code>
<error_text>One of the input parameters is not correct.</error_text>

9. If the institution does not exist:

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

10. If the view flag is not “customize”:

<error_code>6028</error_code>
<error_text>Invalid view</error_text>

11. If the format of the pds_handle is incorrect:

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

12. If the pds_handle is not valid:

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

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