present

General Purpose

This X-Service is used to retrieve a single record or multiple records (documents) from the results set.

The calling application sends the result set identifier, and the record number or a range of numbers from the required set. If used in conjunction with the retrieve_cluster_facet service, the calling application sends a list of document numbers. All of the input parameters are taken from the find and/or search_my_sets and/or search_quick_sets and/or find_group_info and/or retrieve_cluster_facet  X-Services.
This service supports the OpenURL 1.0 standard and when requested, retrieves it as a context object in the response. Documents can be retrieved in one of three view options: full , brief or customize; according to the <view> input parameter. Documents can be displayed in one of two formats:

 

  • Original – The original record from the search target as loaded into MetaLib’s temporary database in MARC exchange format (ISO 2709). In this X-Service, the original record type is specified as ‘original-marc’ format.
  • Converted – The original record as converted by MetaLib for display in MARC21 format. In this X-Service, the converted record type is specified as ‘marc’ format, and is the default value.

Both record types are returned in the X-Service response in OAI-MARC-XML format.

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 – locates database(s) by criteria.
  • Search – performs a search request on a single resource or on a group of resources, using one of the services:
    • find
    • search_my_sets
    • search_quick_sets
  • find_group_info (mandatory for asynchronic searches) – returns the status of the search process.
  • retrieve_cluster_facet(optional) – retrieves cluster and facet data for the search results.
  • present

Input Parameters

Mandatory
1. SESSION_ID – X(50)
2. SET_NUMBER – X(6)
3. SET_ENTRY – X(1000)
or DOC_NUMBER – X(1000) instead of SET_ENTRY, and only in conjunction with retrieve_cluster_facet

 

Optional
1. FORMAT – X(20)
2. VIEW
3. FIELD
4. SUB_FIELD
5. FULL_TXT – X(1)
6. ADD_PROXY – X(1)

7. REQUESTER_IP – X(30) (available from version 4.3.1)

Explanation of the mandatory and optional parameters:

  • session_id – The session ID is the unique identifier of the login.
  • set_number – Group identifier of the result sets (sequence number). Retrieved in find or search_my_sets or search_quick_sets response.
  • set_entry – One or more numbers that represent search results. These numbers should be within the specific set_number’s results set range.
    Note: There are two options for retrieving multiple records by entering the set_entry field:

    • 000000001-000000010 – Display all documents in the range
    • 000000001,000000010,000000005 – Display specific documents
  • doc_number – One or more actual document numbers returned by the retrieve_cluster_facet service (comma delimited up to 100 doc numbers):
    • 001736198,001737194,001737211,001746425 – Display specific documents for a selected cluster/facet
  • full_txt – An indicator that activates the full text availability check. Valid values:
    • N – default
    • Y
  • add_proxy – An indicator that determines whether a Proxy address will be added to the results links. Valid values
    • N – default
    • Y
  • requester_ip – Sending the IP address of the requester enables SFX (when using RSI) to more accurately determine the availability of full text (available from version 4.3.1).
  • format – Document display format. Valid values:
    1. marc – default, used to retrieve records converted in MetaLib for uniform display
    2. original-marc – to retrieve records as received from target resource:
      – after converting physical record format from SUTRS to MARC in MetaLib
      – after converting logical record format to UTF-8 in MetaLib.
  • view – Valid values:
    1. full – default, used to retrieve all fields/sub-fields from search result records, including all external links
    2. brief – used to retrieve only fields/sub-fields from search result records as defined in dat01/tab/www_tab_present_brief (equivalent to ‘brief view’ in /V)
    3. customize – used to retrieve only specified fields/sub-fields from search result records, according to input parameters below (in the <field> and <sub_field> fields)
  • field – enter one of the document field codes.
    The field code format is in total five characters according to the following combination:

    • – The first 3 characters represent the document tags, for instance: “245”,”SID”, “LDR” (for leader).
    • – The last 2 characters represent the tag indicators. “#” is a wildcard for any character.
    • – Character #4 represents tag-ind1 and character #5 represent tag-ind2.
    • – Exceptions are the “YR” (Year) field, which has 2 characters for the tag and 2 characters for the tag indicator and OPURL (for OpenURL 1.0 as a context object). If enabled in MetaLib, ranking “RAN” and duplicate-detection indicators (in UID field) can be requested.
    • – The whole combination should match the MARC21 format.
    • – Use ##### to retrieve all fields and subfields.
    • – Use “OPU##” to retrieve the OpenURL inside the marc21 record.
For URL syntax, use “%23” instead of “#”.
  • sub_field – valid values:
    1. empty – retrieves all the subfields
    2. letters – retrieves the specified subfields

Input XML Format

Examples:

Option 1: Full view for one specific record

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <present_request>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
    <present_command>
      <set_number>000551</set_number>
      <set_entry>000000001</set_entry>
      <format>marc</format>
    </present_command>
  </present_request>
</x_server_request>

Option 2: Full view for a specific cluster/facet, with full text (if available):

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <present_request>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
    <present_command>
      <set_number>000551</set_number>
      <doc_number>001736198,001737194,001737211,001746425</doc_number>
      <full_txt>Y</full_text>
      <format>marc</format>
    </present_command>
  </present_request>
</x_server_request>

Option 3: Customized view for six selected fields

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <present_request>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
    <present_command>
      <set_number>000551</set_number>
      <set_entry>000000001</set_entry>
      <format>marc</format>
       <view>customize</view>
       <field>LDR##</field>
       <field>700##</field>
       <sub_field>ab</sub_field>
       <field>SID  </field>
       <sub_field>aij</sub_field>
       <field>YR###</field>
       <field>RAN##</field>
       <field>OPURL</field>
    </present_command>
  </present_request>
</x_server_request>

Option 4: Customized view for six selected fields with the “OPU##” field

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_request>
  <present_request>
    <session_id>3N175V44EL8HQI46U9K1QY4BXU488UF215P2R2XAMD4DQX6CCM</session_id>
    <present_command>
      <set_number>000551</set_number>
      <set_entry>000000001</set_entry>
      <format>marc</format>
       <view>customize</view>
       <field>LDR##</field>
       <field>700##</field>
       <sub_field>ab</sub_field>
       <field>SID  </field>
       <sub_field>aij</sub_field>
       <field>YR###</field>
       <field>RAN##</field>
       <field>OPU##</field>
    </present_command>
  </present_request>
</x_server_request>

Input URL Syntax

In order to retrieve result(s) document(s), the session_id, set_number, set_entry and format attributes must be embedded within the URL syntax:

MetalibPath:port/X?op= present_request&set_number=set number&set_entry=one of the results set range&format=marc&session_id=Login session id

Example URL Syntax

Option 1: Full view for One Specific Record

http://10.1.235.47:8335/X?op=present_request&set_number=000027&set_entry=000000001&format=marc&session_id=PB3AK5YHFB3AIN2T12FXX267SPABSADKJ8SYEN3CYJMR6A5TLL

Option 2: Customized view for the first 10 retrieved records

http://10.1.235.47:8335/X?op=present_request&set_number=000027&set_entry=000000001-000000010&format=marc&view=customize&field=022%23%23&field=245%23%23&session_id=PB3AK5YHFB3AIN2T12FXX267SPABSADKJ8SYEN3CYJMR6A5TLL

Option 3: Full view for a specific cluster/facet, with full text (if available):

http://10.1.235.47:8335/X?op=present_request&set_number=000027&doc_number=001736198,001737194,001737211,001746425&full_txt=Y&format=marc&view=customize&field=022%23%23&field=245%23%23&session_id=PB3AK5YHFB3AIN2T12FXX267SPABSADKJ8SYEN3CYJMR6A5TLL

Output XML Format

If the record and the set exist, the document will be retrieved in MARC format, and will include MetaLib internal information such as SID and RAN.

 

  • SID – This field is created automatically by the system. It includes the name of the resource, the access method and the ID number of the record in the target. Subfield “s” holds the original Set ID.
  • RAN – The ranked value of the document. Valid values: 0-99, where 99 means an excellent ranking grade.
  • openURL – Retrieves the OpenURL of the document (search result) for the customize view option, according to request
  • SET – Retrieves set number of the document.
  • NEW – This field specifies if the document is a newly fetched document to a merged set
  • OPU – This field containing a subfield with the OpenURL 1.0 data, enclosed in [[CDATA[MetaLib:…]]
  • SYS – The system number for the document
If MetaLib’s dedup functionality is enabled by the global parameter “enable_dedupe” (defined in www_server.conf), the output will include a UID tag.
  • UID – Contains an index of the duplicate records in the merged set. The pointers are comma delimited.
Examples:
Option 1: Full View
In the case of a Search and Link resource, a search_and_link_type tag will be retrieved with two valid values, GET or POST, indicating the type of link:
<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response>
  <present_response>
    <search_and_link_type>GET</search_and_link_type>
    <search_and_link>http://www.ahajournals.org/cgi/search?sendit=Search&
journalcode=all&author1=&author2=&titleabstract=&fulltext=crypto&
fyear=&tyear=</search_and_link>
    <session_id new_session="N">S1EB9YQX153LAU4UDJLTE7MEQH9F934MTSNQ83GX5U33NQBJT5</session_id>
  </present_response>
</x_server_response>

Option 2: Brief View with Full Text (if available): 

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response metalib_version="4.00 (20)">
  <present_response>
    <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="SID" ind1=" " ind2=" ">
        <subfield code="a">EXTERNAL</subfield>
        <subfield code="b">PUBMED</subfield>
        <subfield code="d">CKB00158</subfield>
      </datafield>
      <datafield tag="245" ind1=" " ind2=" ">
        <subfield code="a">A tax to prevent the epidemic of lung cancer.</subfield>
      </datafield>
      <datafield tag="YR " ind1=" " ind2=" ">
        <subfield code="a">2005</subfield>
      </datafield>
       <controlfield tag="SET">000004</controlfield>
        <datafield tag="SID" ind1=" " ind2=" ">
        <subfield code="a">EXTERNAL</subfield>
        <subfield code="b">PUBMED</subfield>
        <subfield code="d">CKB00158</subfield>
      </datafield>
      <datafield tag="245" ind1=" " ind2=" ">
        <subfield code="a">The relationship between time since registration and
measured incidence rates in the General Practice Research Database.</subfield>
      </datafield>
      <datafield tag="YR " ind1=" " ind2=" ">
        <subfield code="a">2005</subfield>
      </datafield>
     <controlfield tag="SET">000004</controlfield>
    <datafield tag="SID" ind1=" " ind2=" ">
        <subfield code="a">EXTERNAL</subfield>
        <subfield code="b">PUBMED</subfield>
        <subfield code="d">CKB00158</subfield>
      </datafield>
      <datafield tag="245" ind1=" " ind2=" ">
        <subfield code="a">Study of tumour cell invasion by Fourier transform infrared microspectroscopy.</subfield>
      </datafield>
      <datafield tag="YR " ind1=" " ind2=" ">
        <subfield code="a">2005</subfield>
      </datafield>
      <controlfield tag="SET">000004</controlfield>
      <controlfield tag="NEW">N</controlfield>
      <controlfield tag="SYS">005555206</controlfield>
    </record>
    <full_txt>N</full_txt>
    <session_id new_session="N">GYMF5TT51PPEIIK9CKG7B4LFGKAM7JXHN7IVI4MJUB5KBRINJJ</session_id>
  </present_response>
</x_server_response>

Option 3: Customize View with the OPURL Field
If the record has an ISSN, the OpenURL as a context object will display as follows:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response metalib_version="4.00 (20)">
  <present_response>
    <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="SID" ind1=" " ind2=" ">
      <subfield code="a">EXTERNAL</subfield>
      <subfield code="b">PUBMED</subfield>
      <subfield code="d">TST01788</subfield>
      <subfield code="i">000000</subfield>
      <subfield code="j">000001</subfield>
      <subfield code="s">000146</subfield>
    </datafield>
    <controlfield tag="RAN">062</controlfield>
    <controlfield tag="UID">000000013,000000014,000000015</controlfield>
    <controlfield tag="SET">000004</controlfield>
    <openURL>
        <ctx:context-objects xmlns:ctx="info:ofi/fmt:xml:xsd:ctx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="info:ofi/fmt:xml:xsd:ctx http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:ctx">
          <ctx:context-object timestamp="2004-01-16T12:13:00Z" version="Z39.88-2004" identifier="123">
            <ctx:referent>
              <ctx:metadata-by-val>
                <ctx:format>info:ofi/fmt:xml:xsd</ctx:format>
                <ctx:metadata>
                  <rft:journal xmlns:rft="info:ofi/fmt:xml:xsd:journal" xsi:schemaLocation="info:ofi/fmt:xml:xsd:journal http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:journal">
                    <rft:author rank="1">
                      <rft:aulast>Mandal</rft:aulast>
                      <rft:aufirst> Madhumanjari</rft:aufirst>
                      <rft:auinit></rft:auinit>
                    </rft:author>
                    <rft:atitle>Physiological changes in certain test plants under automobile exhaust pollution.                            </rft:atitle>
                    <rft:stitle>J Environ Biol</rft:stitle>
                    <rft:date>2006</rft:date>
                    <rft:volume>27</rft:volume>
                    <rft:issue>1</rft:issue>
                    <rft:spage>43</rft:spage>
                    <rft:epage>7</rft:epage>
                    <rft:genre></rft:genre>
                    <rft:issn>0254-8704</rft:issn>
                    <rft:doi></rft:doi>
                    <rft:sici></rft:sici>
                    <rft:opid></rft:opid>
                  </rft:journal>
                </ctx:metadata>
              </ctx:metadata-by-val>
              <ctx:metadata-by-ref>
                <ctx:format></ctx:format>
                <ctx:location>http://il-metalsfx01.corp.exlibrisgroup.com:8332/X?OP=sfx-get-doc&doc-number=000036655                               </ctx:location>
              </ctx:metadata-by-ref>
            </ctx:referent>
            <ctx:referrer>
              <ctx:identifier>info:sid/metalib.com:PUBMED</ctx:identifier>
            </ctx:referrer>
          </ctx:context-object>
        </ctx:context-objects>
      </openURL>
    </record>
    <session_id new_session="N">QIM24XDP4VMC3BLG2EALKGAR2TKH28KNNLBH4XM3GMJMC5XMPN</session_id>
  </present_response>
</x_server_response>

If the record has an ISBN, the OpenURL as a context object will display as follows:

<?xml version = "1.0" encoding = "UTF-8"?>
  <x_server_response metalib_version="4.00 (20)">
    <present_response>
      <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">
      <openURL>
        <ctx:context-objects xmlns:ctx="info:ofi/fmt:xml:xsd:ctx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="info:ofi/fmt:xml:xsd:ctx http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:ctx">
          <ctx:context-object timestamp="2002-06-14T12:13:00Z" version="Z39.88-2004" identifier="125">
            <ctx:referent>
              <ctx:metadata-by-val>
                <ctx:format>info:ofi/fmt:xml:xsd:book</ctx:format>
                <ctx:metadata>
                  <rft:book xmlns:rft="info:ofi/fmt:xml:xsd:book" xsi:schemaLocation= "info:ofi/fmt:xml:xsd:book http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:book">
                    <rft:authors>
                      <rft:author>
                        <rft:aulast>Bloom</rft:aulast>
                        <rft:aufirst> Harold</rft:aufirst>
                        <rft:auinit></rft:auinit>
                      </rft:author>
                    </rft:authors>
                    <rft:title></rft:title>
                    <rft:btitle>Ernest Hemingway's The old man and the sea</rft:btitle>
                    <rft:date>1996</rft:date>
                    <rft:pub></rft:pub>
                    <rft:place></rft:place>
                    <rft:isbn>0791040712</rft:isbn>
                    <rft:genre></rft:genre>
                    <rft:edition></rft:edition>
                    <rft:doi></rft:doi>
                    <rft:sici></rft:sici>
                    <rft:opid></rft:opid>
                  </rft:book>
                </ctx:metadata>
              </ctx:metadata-by-val>
              <ctx:metadata-by-ref>
                <ctx:format></ctx:format>
                <ctx:location></ctx:location>
              </ctx:metadata-by-ref>
            </ctx:referent>
            <ctx:referrer>
              <ctx:identifier>info:sid/metalib.com:LOC</ctx:identifier>
            </ctx:referrer>
          </ctx:context-object>
        </ctx:context-objects>
      </openURL>
    </record>
    <session_id new_session="N">QIM24XDP4VMC3BLG2EALKGAR2TKH28KNNLBH4XM3GMJMC5XMPN</session_id>
  </present_response>
</x_server_response>

If the record has neither an ISSN nor an ISBN, the OpenURL as a context object will display as follows:

<?xml version = "1.0" encoding = "UTF-8"?>
<x_server_response metalib_version="4.00 (20)">
  <present_response>
    <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">
      <openURL>
        <ctx:context-objects xmlns:ctx="info:ofi/fmt:xml:xsd:ctx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="info:ofi/fmt:xml:xsd:ctx http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd:ctx">
         <ctx:context-object timestamp="2004-01-16T12:13:00Z" version="Z39.88-2004" identifier="123">
          <ctx:referent>
            <ctx:metadata-by-val>
              <ctx:format>info:ofi/fmt:xml:xsd</ctx:format>
              <ctx:metadata>
                <rft:journal xmlns:rft="info:ofi/fmt:xml:xsd" xsi:schemaLocation="info:ofi/fmt:xml:xsd http://www.openurl.info/registry/docs/info:ofi/fmt:xml:xsd">
                  <rft:author rank="1">
                    <rft:aulast>Lloyd</rft:aulast>
                    <rft:aufirst> A  L</rft:aufirst>
                    <rft:auinit></rft:auinit>
                  </rft:author>
                  <rft:atitle></rft:atitle>
                  <rft:stitle>The bird in the bush</rft:stitle>
                  <rft:date>1966</rft:date>
                  <rft:volume></rft:volume>
                  <rft:issue></rft:issue>
                  <rft:spage></rft:spage>
                  <rft:epage></rft:epage>
                  <rft:issn></rft:issn>
                  <rft:doi></rft:doi>
                  <rft:sici></rft:sici>
                  <rft:opid></rft:opid>
                </rft:journal>
              </ctx:metadata>
            </ctx:metadata-by-val>
            <ctx:metadata-by-ref>
              <ctx:format></ctx:format>
                <ctx:location></ctx:location>
            </ctx:metadata-by-ref>
          </ctx:referent>
          <ctx:referrer>
            <ctx:identifier>info:sid/metalib.com:LOC</ctx:identifier>
          </ctx:referrer>
         </ctx:context-object>
        </ctx:context-objects>
      </openURL>
    </record>
    <session_id new_session="N">QIM24XDP4VMC3BLG2EALKGAR2TKH28KNNLBH4XM3GMJMC5XMPN</session_id>
  </present_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 the set number does not exist:

<error_code>2030</error_code>
<error_text>Invalid set number 000010</error_text>

5. If the document number is invalid:

<error_code>2033</error_code>
<error_text>Invalid doc number 000586830</error_text>

6. If the set entry is invalid:

<error_code>2032</error_code>
<error_text>The entry number is higher then the number of the documents</error_text>

7. If Search results are missing:

<error_code>2031</error_code>
<error_text>Search results are missing</error_text>

8. If the input XML is invalid:

<error_code>2000</error_code>
<error_text>Input xml is invalid</error_text>

9. If the set entry is invalid:

<error_code>2034</error_code>
<error_text>Invalid set entry number</error_text>

10. If the Z39.50 gate is down:

<error_code>6012</error_code>
<error_text>Z39.50 gate is not running</error_text>