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)
or
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:
- empty – retrieves all the subfields
- 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.