SRU VERSION 1.1 ARCHIVE

Scan Operation

Request Parameters - Response Parameters - Term Parameters - Examples

While the searchRetrieve operation enables searches for a specific term within a list of indexed terms from the records, the scan operation allows the client to request a range of the available terms at a given point within that list. This enables clients to present an ordered list of values and, if supported, how many hits there would be for a search on that term. Scan is often used to select terms for subsequent searching or to verify visually a negative search result.

The index to be browsed and the start point within it is given in the scanClause parameter as a complete index, relation, term clause in CQL. The relation and relation modifiers may be used to determine the format of the terms returned. For example 'dc.title any fish' will return a list of keywords, whereas 'dc.title exact fish' would return a list of full title fields. Range relations, such as <, >=, within and so forth, are prohibited for use with scan, and diagnostic 'info:srw/diagnostic/1/19' should be returned. See below for a clarifying example.

The term given in the clause is the position within the ordered list of terms at which to start, however see the responsePosition parameter below for more information. If the empty term is given, then even if searching for it is unsupported by the server, it may be interpreted as the beginning of the term list.

Scan Request Parameters

Parameter Name	Mandatory or optional	Description
version	mandatory	Indicates the scan version of the request and the highest version the client can support for the response.
scanClause	mandatory	The index to be browsed and the start point within it, expressed as a complete index, relation, term clause in CQL.
responsePosition	optional	The position within the list of terms returned where the client would like the start term to occur. If the position given is 0, then the term should be immediately before the first term in the response. If the position given is 1, then the term should be first in the list, and so forth up to the number of terms requested plus 1, meaning that the term should be immediately after the last term in the response, even if the number of terms returned is less than the number requested. The range of values is 0 to the number of terms requested plus 1. The default value is 1.
maximumTerms	optional	The number of terms which the client requests be returned. The actual number returned may be less than this, for example if the end of the term list is reached, but may not be more. The explain record for the database may indicate the maximum number of terms which the server will return at once. All positive integers are valid for this parameter. If not specified, the default is server determined.
stylesheet	optional	A URL for an xml stylesheet. The client requests that the server simply return this URL in the response.
extraRequestData	optional	Provides additional, profile specific information. See Extra Data.
operation	mandatory	The string: 'scan'.

Scan Response Parameters

Parameter Name	Mandatory or optional	Type	Description
version	mandatory	xsd:string	The version of the response. This must be less than or equal to the version requested by the client.
terms	optional	sequence of term. Each term structured; see table below	A sequence of terms which match the request.
diagnostics	optional	sequence of diagnostic	A sequence of non surrogate diagnostics generated during execution.
extraResponseData	optional	xmlFragment	Additional, profile specific information provided by the server along with the response. See Extra Data.
echoedScanRequest	optional	ScanRequest	The request parameters echoed back to the client in a simple XML form.

Sub Parameters for Term

Parameter Name	Mandatory or optional	Type	Description
value	mandatory	xsd:string	The term, exactly as it appears in the index.
numberOfRecords	optional	xsd:non NegativeInteger	The number of records which would be matched if the index in the request's scanClause was searched with the term in the 'value' field.
displayTerm	optional	xsd:string	A string to display to the end user in place of the term itself. For example this might add back in stopwords which do not appear in the index.
whereInList	optional	xsd:string	A flag to indicate the position of the term within the complete term list. It must be one of the following values: 'first' (the first term), 'last' (the last term), 'only' (the only term) or 'inner' (any other term)
extraTermData	optional	xml	Additional profile specific information (see extra data) concerning the term

Examples

A typical scan request might be:

   http://myserver.com/myurl/?operation=scan&version=1.1
   & scanClause=%2fdc.title%3d%22cat%22&responsePosition=3 &
   maximumTerms=50&stylesheet=http://myserver.com/myStyle
   & x-info-2-auth1.0-authenticationToken=%22XDFPQR5ZZ%22

The response would be of the form:


    <?xml-stylesheet type=text/xsl" href="http:myserver.com/myStyle"?>
    <srw:scanResponse 
             xmlns:srw="http://www.loc.gov/zing/srw/" 
             xmlns:diag="http://www.loc.gov/zing/srw/diagnostic/"
             xmlns:myServer="http://myServer.com/">
      <srw:version>1.1</srw:version>
      <srw:terms>
        <srw:term>
          <srw:value>CARTESIAN 4456345</srw:value>
          <srw:numberOfRecords>35645</srw:numberOfRecords>
          <srw:displayTerm>Carthesian</srw:displayTerm>
          <srw:extraTermData>
            <myserver:ID>4456345</myserver:ID>
          </srw:extraTermData>
        </srw:term>
        <srw:term>
          <srw:value>CARTESIAN 4456376</srw:value>
          <srw:numberOfRecords>2154</srw:numberOfRecords>
          <srw:displayTerm>Carthésian</srw:displayTerm>
          <srw:extraTermData>
             <myServer:ID>4456376</myServer:ID>
          </srw:extraTermData>
        </srw:term>
        <srw:term>
          <srw:value>CAT 4456392</srw:value>
          <srw:numberOfRecords>8739972</srw:numberOfRecords>
          <srw:displayTerm>Cat</srw:displayTerm>
          <srw:extraTermData>
             <myserver:ID>4456392</myserver:ID>
          </srw:extraTermData>
        </srw:term>
        <srw:term>
          <srw:value>CATHOLIC DOGMA 4456888</srw:value>
          <srw:numberOfRecords>35</srw:numberOfRecords>
          <srw:displayTerm>Catholic Dogma</srw:displayTerm>
          <whereInList>last</whereInList>
          <srw:extraTermData>
            <myserver:ID>4456888</myserver:ID>
          </srw:extraTermData>
        </srw:term>
      </srw:terms>
      <srw:extraResponseData> 
        <rob:authenticationToken
          xmlns:rob="info:srw/extension/2/auth-1.0">
              XDFPQR5ZZ
         </rob:authenticationToken>
      </srw:extraResponseData> 
      <srw:echoedScanRequest>
        <srw:version>1.1</srw:version>
        <srw:scanClause>dc.title="cat"</srw:scanClause>  
        <srw:responsePosition>3</srw:responsePosition>
        <srw:maximumTerms>3</srw:maximumTerms>
        <srw:stylesheet>http://myserver.com/myStyle</srw:stylesheet>
      </srw:echoedScanRequest>
    </srw:scanResponse>

sru home » version 1.1 archive »scan