CGM Protocol

Submit a Query

Verb name: Search
Verb version: 1.0
Modification Date: 2003-03-24
Required arguments: field, value, op
Optional arguments: set, sort, startResult, resultSize
MIMETYPE of response: text/xml

Verb Description

Specifies a search request to an index server. Arguments indicate search criteria and the order and amount of search results to be returned. The response is a structured list of documents that match the search criteria, and includes a results summary. It is possible to request the results summary only.

Arguments

The arguments field[n] and value[n] enumerate, beginning with 1. For op[n], see below.

Supported values for bibliographic field arguments may vary among index servers. The DescribeVerb verb returns the set of field values supported by a particular server. The arguments and values that must be submitted and/or supported are marked "required" in the following:

set :: an optional grouping construct, identical in definition to OAI's use. With CGM Search, however, multiple sets can be indicated in a single query by using a delimiter ( | ); for example: set=set1|set2|set3. When searching across multiple sets, the complete query is executed within each set (effectively OR'ing the sets). When no set is indicated, the default is either 1) all sets, when a repository supports sets, or 2) all repository content, when the repository does not support sets.
sort :: a requested sort order for result sets. Default is rank. Possible values are:
- rank [required] based on whatever relevance data is provided by the repository.
- title
- author
- pubdate
startResult :: the numerical order of the first result to be returned in the response. Value is an integer, 0 or greater; default is 1. If the value is set to 0, no results will be returned, regardless of the value of resultSize.
resultSize :: the number of result records requested. Value is an integer, 0 or greater; default is all results. If the value is set to 0, no results will be returned, regardless of the value of startResult.
field[n] :: [required] Following is a list of permitted argument values. Those marked "[required]" must be supported (indexed).
- title [required]
- identifier
- author [required]
- pubtype [required] indicates whether monograph or serial
- subject
- language [required] use ISO639-1 or ISO639-2
- fullbib [required]
- abstract
- pubdate [required]
- publisher [required]
- fulltext
value[n] :: [required] the query string
op[n] :: [required, if multiple field/value pairs submitted] op[n] will normally operate on n and n-1 field/value arguments. See the separate document on RPN Notation. Following is a list of permitted argument values. Those marked "[required]" must be supported.
- and [required]
- or [required]
- not
- within
- including

Rules for field matching: the value of the value argument is treated as a single string (word or phrase) and matched exactly as submitted; the wild card symbol * should be used to indicate truncation.

Operator Precedence: queries are assumed to be submitted using Reverse Polish Notation (RPN). See the separate document on RPN Notation

Response

Unless there is an error, all responses include a single resultsSummary and zero to many record elements.

A well-formed query that executes properly and yet has no matches is not considered an error. In this case, a resultsSummary would be returned, but no record elements.

<resultsSummary> :: [required] an empty element with data about the results returned. All of the following attributes must be included, using defaults if not specified in request. These values describe the results actually returned; they may differ from values in the request.
- repositoryIdentifier :: the repository identifier.
- set :: if no set was indicated in the response, then return either 1) a list of all sets searched, if sets are supported (set="set1|set2|set3"); or 2) an empty value, if sets are not supported (set="").
- sort :: use default when not in request.
- totalResults :: the total number of matches on a query, regardless of how many or which results are returned.
- startResult :: the order of the first result returned in this response. Value is 0 when no results are returned.
- resultSize :: the number of results returned in this response. This may be less than the resultSize requested, if there are fewer results than requested.
<record> :: zero to many record elements allowed. Each contains the following elements:
- <identifier> :: [required] the unique document identifier. Its format is determined by the repository.
- <title> :: [required]
- <author> :: [required if available] Repeatable. Each author is in last, first middle format.
- <pubdate> :: [required] The date of publication of the document in ISO 8601 format.
- <rank> :: [required] Relevance data in any form. Should be made as meaningful as possible.

Error Codes

badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.
noSetHierarchy :: the repository does not support sets

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Search&ver=1.0&set=math&resultSize=100
	&field1=author&value1=todhunter&field2=title
	&value2=trigonometry&op2=and

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-01T19:20:30Z</responseDate>
  <request verb="Search" ver="1.0" set="math" resultSize="100"
           field1="author" value1="todhunter" field2="title"
           value2="trigonometry" op2="and">
           http://some.cgm.server/script</request>
  <Search ver="1.0">
    <resultsSummary repositoryIdentifier="CULmath" set="math" sort="title"
                    totalResults="2" startResult="1" resultSize="2" />
    <record>
      <identifier>cul.math/98765432</identifier>
      <title>Fun with Trigonometry</title>
      <author>Todhunter, I.</author>
      <author>Disney, W.</author>
      <pubdate>1888</date>
      <rank>2859</rank>
    </record>
    <record>
      <identifier>cul.math/00640001</identifier>
      <title>Spherical Trigonometry</title>
      <author>Todhunter, I.</author>
      <pubdate>1886</date>
      <rank>2857</rank>
    </record>
  </Search>
</CGM>

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Search&ver=1.0&set=math&startResult=0
	&field1=fulltext&value1=geometry&field2=fulltext
	&value2=trigonometry&op2=and

http://some.cgm.server/script?protocol=CGM
	&verb=Search&ver=1.0&set=math&resultSize=0
	&field1=fulltext&value1=geometry&field2=fulltext
	&value2=trigonometry&op2=and

These two requests are equivalent. The response below is to the first one.

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="Search" ver="1.0" set="math" startResult="0"
           field1="fulltext" value1="geometry" field2="fulltext"
           value2="trigonometry" op2="and">
           http://some.cgm.server/script</request>
  <Search ver="1.0">
    <resultsSummary repositoryIdentifier="CULmath" set="math" sort="title"
                    totalResults="1024" startResult="0" resultSize="0" />
  </Search>
</CGM>

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Search&ver=1.0&set=math
	&field1=author&value1=bush&field2=fullbib
	&value2=basic%20counting&op2=and

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="Search" ver="1.0" set="math" field1="author"
           value1="bush"field2="fullbib" value2="basic counting"
           op2="and">http://some.cgm.server/script
           </request>
  <Search ver="1.0">
    <resultsSummary repositoryIdentifier="CULmath" set="math" sort="title"
                    totalResults="0" startResult="0" resultSize="0" />
  </Search>
</CGM>

Verb History

Substantial reworking and extension of Dienst verb SearchBoolean, version 5.0.

Display a Document in Local Viewer

Verb name: Display
Verb version: 1.0
Modification Date: 2003-01-06
Required arguments: identifier
Optional arguments: none
MIMETYPE of response: will depend on request and viewer mechanism

Verb Description

Request to view a document in a repository's local viewer.

Arguments

identifier :: the identifier for the document requested.

Response

A repository can display a document however it chooses.

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Display&ver=1.0&identifier=cul.math/00640001

Verb History

New to CGM.

Get Document Structure

Verb name: Structure
Verb version: 1.0 beta
Modification Date: 2003-03-03
Required arguments: identifier
Optional arguments: version, view
MIMETYPE of response: text/xml

Verb Description

This verb returns a structured response describing a structural view available for a document. A client may use this structural information as the basis for document requests using the Disseminate verb.

Arguments

identifier :: [required] the document identifier
version :: specifies the document version for which the structure information is requested. If omitted, the response provides information about the latest document version.
view :: specifies the the view of the document for which structure information is requested. If omitted, the response provides information about the default view. Specific views are requested using the view id value, obtained using the ListViews verb.

Response

Each response will include one view element. There will always be one and only one default view of a document.

<view> :: contains one high-level, or root, div element, within which nested div hierarchies are allowed. view element attributes are:
- id :: [required] an id value for this view. This id is defined as an XML ID.
- label :: [required] a displayable label identifying this view. These are applied by the local repository and should help end users choose an appropriate document view.
- default :: [required for default view] equals 1 for the sole default view; equals 0 for all other views. If absent, default="0" is assumed.
<div> :: may contain one or more div elements. div element attributes are:
- id :: [required] an ID value for this division, usable as is in Disseminate and other requests. This is not defined as an XML ID.
- type :: if any of the following div types are present, they must be identified as such with the type attribute [open issue--coordinating this with possible docstruct values used in enhance Search and ListDocstruct]:
  - maindocument
  - front
  - body
  - back
  - chapter
  - section
  - page
- order :: [required] the order of this div among its siblings. Values are positive integers, beginning with 1.
- label :: a displayable label for this division. These are applied by the local repository and should make sense in a navigational context.

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.
badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Structure&ver=1.0&identifier=cul.math/00640001

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="Structure" ver="1.0" identifier="cul.math/00640001">
           http://some.cgm.server/script</request>
  <Structure ver="1.0">
    <identifier value="cul.math/00640001"/>
    <view id="v123-a" label="Page Listing" default="1">
      <div id="a123-1" type="maindocument" order="1" label="Entire Monograph">
        <div id="a123-1" type="page" order="1" label="Page NA">
        <div id="a123-2" type="page" order="2" label="Page i">
        <div id="a123-3" type="page" order="3" label="Page ii">
        <div id="a123-4" type="page" order="4" label="Page 1">
        <div id="a123-5" type="page" order="5" label="Page 2">
        <div id="a123-6" type="page" order="6" label="Page 3">
        <div id="a123-7" type="page" order="7" label="Page 4">
        <div id="a123-8" type="page" order="8" label="Page 5">
        <div id="a123-9" type="page" order="9" label="Page 6">
      </div>
    </view>
  </Structure>
</CGM>

The response above describes the physical structure of a document. Because no view was specified in the request, the default view was returned.

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Structure&ver=1.0&identifier=cul.math/00640001&view=v123-b

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="Structure" ver="1.0" identifier="cul.math/00640001"
           view="v123-b">http://some.cgm.server/script</request>
  <Structure ver="1.0">
    <identifier value="cul.math/00640001"/>
    <view id="v123-b" label="Chapter Listing" default="0">
      <div id="a123" type="maindocument" order="1" label="Entire Monograph">
        <div id="a123-1" type="front" order="1" label="Front Matter">
          <div id="a123-1-1" type="page" order="1" label="Page i">
          <div id="a123-1-2" type="page" order="2" label="Page ii">
          <div id="a123-1-3" type="page" order="3" label="Page iii">
        </div>
        <div id="a123-2" type="chapter" order="2" label="Chapter I">
          <div id="a123-2-1" type="page" order="1" label="Page 1">
          <div id="a123-2-2" type="page" order="2" label="Page 2">
          <div id="a123-2-3" type="page" order="3" label="Page 3">
          <div id="a123-2-4" type="page" order="4" label="Page 4">
          ....
          <div id="a123-2-36" type="page" order="36" label="Page 36">
        </div>
        <div id="a123-3" type="chapter" order="3" label="Chapter II">
          <div id="a123-3-37" type="page" order="1" label="Page 37">
          <div id="a123-3-38" type="page" order="2" label="Page 38">
          <div id="a123-3-39" type="page" order="3" label="Page 39">
          <div id="a123-3-40" type="page" order="4" label="Page 40">
          ....
          <div id="a123-3-77" type="page" order="41" label="Page 75">
        </div>
        ...
      </div>
    </view>
  </Structure>
</CGM>

This response describes a non-default view of the identified document. The document view is structured into a front section and following chapters, with individual page images available within these structures. ("..." indicates where additional pages and chapters have been omitted in the example for brevity).

Verb History

Modification of Dienst verb Structure, version 2.0. CGM has removed all format related functions from the Dienst Structure.

Earlier NSF-DFG note: For Structure, we discussed replacing the unnumbered DIVs, which can nest, with numbered DIVs (e.g., DIV1, DIV2, etc.). Further, Structure should use real ID values (i.e., only NAME characters, beginning with an alpha character), and need to have a sense of relationship between layers (e.g., what shows first, GIF or PDF?) and a repository's desire to suppress or hold back a layer (e.g., don't show the OCR without this caveat, or don't show it until you've shown other layers, and then only with this caveat).

Get Formats

Verb name: Formats
Verb version: 1.0 beta
Modification Date: 2003-03-18
Required arguments: identifier
Optional arguments: version, div, view
MIMETYPE of response: text/xml

Verb Description

Returns a structured response indicating the formats available for the various structural components of a document.

Arguments

identifier :: [required] the document identifier
version :: specifies the document version for which the format information is requested. If omitted, it provides information about the latest document version available (see ListVersions).
div :: specifies the id value of a div component provided in the Structure response. Use to request format information for a specific structual component. [Is there a default then? Highest level div of document?]
view :: specifies the the view of the document for which format information is requested. If omitted, the response provides information about the default view. Specific views are requested using the view id value, obtained using the ListViews verb. [Some uncertainty how view works with Formats, and whether it's necessary/desirable. Currently not in response, but should be if we keep it.]

Response

Each response includes a single high-level divReq element.

<divReq> :: The div for which format information has been requested becomes the divReq or root div element in the response. The divReq element has the same attributes as a Structure response div [except order?]:
- id :: [required] an ID value for this division, usable as is in Disseminate and other requests. This is not defined as an XML ID.
- type :: if any of the following div types are present, they must be identified as such with the type attribute [open issue--coordinating this with possible docstruct values used in enhance Search and ListDocstruct]:
  - maindocument
  - front
  - body
  - back
  - chapter
  - section
  - page
- order :: [required] the order of this div among its siblings. Values are positive integers, beginning with 1. [this doesn't make any sense here, since there's always only one divReq. Do away with order here?]
- label :: a displayable label for this division. These are applied by the local repository and should make sense in a navigational context.
The divReq element may contain (and must contain at least one of) the following:
- zero or more format elements for the complete divReq;
- zero or more formatSeq elements;
<format> :: an empty element with attributes describing a single format available for its parent element, which may be divReq, div, or formatDiv. The format element has four attributes:
- type :: [required] from a controlled vocabulary of format types.
- mime :: [required] the mime-type of the format.
- size :: [optional?] in bytes [or KB?].
- label :: [required] a displayable label identifying this format for use in a user interface.
<formatSeq> :: an element that contains one or more div or formatDiv elements. Each formatSeq gives a format representation of the entire divReq [so, formatSeq can occur only directly under divReq? Not within some nested hierarchy?]. The formatSeq element has one attribute:
- label :: a displayable label identifying this group of formats, for use in a user interface. [ListBinders and ListEncoding may argue for an ID value on formatSeq??]
<div> :: a structural division within formatSeq that contains one or more format elements. If div is used, as opposed to formatDiv, it is assumed that the same structural division is also represented in Structure verb responses. div has four attibutes, corresponding exactly to div attributes in a Structure Verb response:
- id :: [required] an ID value for this division, usable as is in Disseminate and other requests. This is not defined as an XML ID.
- type :: if any of the following div types are present, they must be identified as such with the type attibute:
  - maindocument
  - front
  - body
  - back
  - chapter
  - section
  - page
- order :: [required] the order of this div among its siblings. Values are positive integers, beginning with 1.
- label :: a displayable label for this division. These are applied by the local repository and should make sense in a navigational context.
<formatDiv> :: a division within formatSeq that contains one or more format elements. If formatDiv is used, as opposed to div, it is assumed that this division is not structural--not represented in Structure verb responses--but rather indicates a division peculiar to a Formats verb response. This element has four attibutes:
- id :: [required] an ID value for this division, usable as is in Disseminate and other requests. This is not defined as an XML ID.
- type :: [makes no sense to use the div types above here. What would make this useful? Do we need it at all?]
- order :: [required] the order of this div among its siblings. Values are positive integers, beginning with 1.
- label :: a displayable label for this division. These are applied by the local repository and should make sense in a navigational context.

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.
badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Formats&ver=1.0&identifier=cul.math/00640001

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="Structure" ver="1.0" identifier="cul.math/00640001">
           http://some.cgm.server/script</request>
  <Formats ver="1.0">
    <identifier value="cul.math/00640001"/>
    <divReq id="a123-a" type="chapter" order="1" label="chapter 1">
      <format type="PDF.600" mime="application/pdf" size="5500000"
              label="Entire Document in PDF"/>
      <format type="OCR" mime="text/plain" size="412000" label="Un-proofed
              OCR text"/>
      <formatSeq label="Sequence of pages">
        <div id="a123-1" type="page" order="1" label="i">
          <format type="GIF" mime="image/gif" size="63488" label="Page
                  image"/>
          <format type="PDF.600" mime="application/pdf" size="54272" 
                  label="Page in PDF"/>
          <format type="OCR" mime="text/plain" size="4096" label="Un-proofed
                  OCR text"/>
        </div>
        <div id="a123-2" type="page" order="2" label="ii">
          <format type="GIF" mime="image/gif" size="63488" label="Page
                  image"/>
          <format type="PDF.600" mime="application/pdf" size="54272"
                  label="Page in PDF"/>
          <format type="OCR" mime="text/plain" size="4118" label="Un-proofed
                  OCR text"/>
        </div>
        <div id="a123-3" type="page" order="3" label="1">
          <format type="GIF" mime="image/gif" size="63488" label="Page
                  image"/>
          <format type="PDF.600" mime="application/pdf" size="54272"
                  label="Page in PDF"/>
          <format type="OCR" mime="text/plain" size="4616" label="Un-proofed
                  OCR text"/>
        </div>
        ...
        <div id="a123-103" type="page" order="103" label="100">
          <format type="GIF" mime="image/gif" size="63488" label="Page
                  image"/>
          <format type="PDF.600" mime="application/pdf" size="54272"
                  label="Page in PDF"/>
          <format type="OCR" mime="text/plain" size="4580" label="Un-proofed
                  OCR text"/>
        </div>
      </formatSeq>
      <formatSeq label="PDF Chunks" >
        <formatDiv id="chunk1" type="chunk" order="1" label="Pages 1-30">
          <format type="PDF.600" mime="application/pdf" size="1620000"
                  label="Multi-page PDF"/>
          <format type="OCR" mime="text/plain" size="110000" label="Un-proofed
                  OCR text"/>
        </formatDiv>
        <formatDiv id="chunk2" type="chunk" order="2" label="Pages 31-60">
          <format type="PDF.600" mime="application/pdf" size="1650000"
                  label="Multi-page PDF"/>
          <format type="OCR" mime="text/plain" size="120000" label="Un-proofed
                  OCR text"/>
        </formatDiv>
        <formatDiv id="chunk3" type="chunk" order="3" label="Pages 61-90">
          <format type="PDF.600" mime="application/pdf" size="1650000"
                  label="Multi-page PDF"/>
          <format type="OCR" mime="text/plain" size="120000" label="Un-proofed
                  OCR text"/>
        </formatDiv>
        <formatDiv id="chunk4" type="chunk" order="4" label="Pages 91-103">
          <format type="PDF.600" mime="application/pdf" size="550000"
                  label="Multi-page PDF"/>
          <format type="OCR" mime="text/plain" size="40000" label="Un-proofed
                  OCR text"/>
        </formatDiv>
      </formatSeq>
    </divReq>
  </Formats>
</CGM>

Verb History

Modification of Dienst verb Formats, version 4.0.

Get Formats - original take

Verb name: Formats
Verb version: 1.0 alpha
Modification Date: 2003-03-03
Required arguments: identifier
Optional arguments: version, div, view
MIMETYPE of response: text/xml

Verb Description

Returns a structured response indicating the formats available for the various structural components of a document.

Arguments

identifier :: [required] the document identifier
version :: specifies the document version for which the format information is requested. If omitted, it provides information about the latest document version available (see ListVersions).
div :: specifies the id value of a div component provided in the Structure response. Use to request format information for a specific structual component. [Is there a default then? Highest level div of document?]
view :: specifies the the view of the document for which format information is requested. If omitted, the response provides information about the default view. Specific views are requested using the view id value, obtained using the ListViews verb. [Some uncertainty how view works with Formats, and whether it's necessary/desirable. Currently not in response, but should be if we keep it.]

Response

Each response includes a single high-level divReq element.

<divReq> :: The div for which format information has been requested becomes the divReq or root div element in the response. The divReq element has the same attributes as a Structure response div [except order? The point is, this div is the same as the Structure response divs. The divs below are not really Structure divs.]:
- id :: [required] an ID value for this division, usable as is in Disseminate and other requests. This is not defined as an XML ID.
- type :: if any of the following div types are present, they must be identified as such with the type attribute [open issue--coordinating this with possible docstruct values used in enhance Search and ListDocstruct]:
  - maindocument
  - front
  - body
  - back
  - chapter
  - section
  - page
- order :: [required] the order of this div among its siblings. Values are positive integers, beginning with 1. [this doesn't make any sense here, since there's always only one divReq]
- label :: a displayable label for this division. These are applied by the local repository and should make sense in a navigational context.
The divReq element may contain (and must contain at least one of) the following:
- zero or more format elements for the complete divReq;
- zero or more formatSeq elements;
<format> :: an empty element with attributes describing a single format available for its parent divReq or div element. The format element has four attributes:
- type :: [required] from a controlled vocabulary of format types.
- mime :: [required] the mime-type of the format.
- size :: [optional?] in bytes [or KB?].
- label :: [required] a displayable label identifying this format for use in a user interface.
<formatSeq> :: an element that contains one or more div elements. Each formatSeq gives a format representation of the entire divReq. The formatSeq element has one attribute:
- label :: a displayable label identifying this group of formats, for use in a user interface..
<div> :: an element within formatSeq that contains one or more format elements. This element has four attibutes, corresponding to div attributes in a Structure Verb response [these divs *seem* like the divs from Structure response, but they won't be in all cases. So, should we call them something else, like formatDiv? Larger question, how do we connect Structure response info to Formats response info, if the divs in one don't match up with the divs in the other???]:
- id :: [required] an ID value for this division, usable as is in Disseminate and other requests. This is not defined as an XML ID.
- type :: if any of the following div types are present, they must be identified as such with the type attibute [but these aren't the same types as in Structure, so this doesn't make sense. Compare type=chunk in example]:
  - maindocument
  - front
  - body
  - back
  - chapter
  - section
  - page
- order :: [required] the order of this div among its siblings. Values are positive integers, beginning with 1.
- label :: a displayable label for this division. These are applied by the local repository and should make sense in a navigational context.

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.
badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Formats&ver=1.0&identifier=cul.math/00640001

Response

<?xml version="1.0" encoding="UTF-8"?>
  <CGM>
    <responseDate>2002-10-02T19:20:30Z</responseDate>
    <request verb="Structure" ver="1.0" identifier="cul.math/00640001">
             http://some.cgm.server/script</request>
    <Formats ver="1.0">
      <identifier value="cul.math/00640001"/>
      <divReq id="a123-a" type="chapter" order="1" label="chapter 1">
        <format type="PDF.600" mime="application/pdf" size="5500000" label="Entire Document in PDF"/>
        <format type="OCR" mime="text/plain" size="412000" label="Un-proofed OCR text"/>
        <formatSeq label="Sequence of pages">
          <div id="i1" type="page" order="1" label="i">
            <format type="GIF" mime="image/gif" size="63488" label="Page image"/>
            <format type="PDF.600" mime="application/pdf" size="54272" label="Page in PDF"/>
            <format type="OCR" mime="text/plain" size="4096" label="Un-proofed OCR text"/>
          </div>
          <div id="i2" type="page" order="2" label="ii">
            <format type="GIF" mime="image/gif" size="63488" label="Page image"/>
            <format type="PDF.600" mime="application/pdf" size="54272" label="Page in PDF"/>
            <format type="OCR" mime="text/plain" size="4118" label="Un-proofed OCR text"/>
          </div>
          <div id="i3" type="page" order="3" label="1">
            <format type="GIF" mime="image/gif" size="63488" label="Page image"/>
            <format type="PDF.600" mime="application/pdf" size="54272" label="Page in PDF"/>
            <format type="OCR" mime="text/plain" size="4616" label="Un-proofed OCR text"/>
          </div>
          ...
          <div id="i103" type="page" order="103" label="100">
            <format type="GIF" mime="image/gif" size="" label="Page image"/>
            <format type="PDF.600" mime="application/pdf" size="54272" label="Page in PDF"/>
            <format type="OCR" mime="text/plain" size="4580" label="Un-proofed OCR text"/>
          </div>
        </formatSeq>
        <formatSeq label="PDF Chunks" >
          <div id="chunk1" type="chunk" order="1" label="Pages 1-30">
            <format type="PDF.600" mime="application/pdf" size="1620000" label="Multi-page PDF"/>
            <format type="OCR" mime="text/plain" size="110000" label="Un-proofed OCR text"/>
          </div>
          <div id="chunk2" type="chunk" order="2" label="Pages 31-60">
            <format type="PDF.600" mime="application/pdf" size="1650000" label="Multi-page PDF"/>
            <format type="OCR" mime="text/plain" size="120000" label="Un-proofed OCR text"/>
          </div>
          <div id="chunk3" type="chunk" order="3" label="Pages 61-90">
            <format type="PDF.600" mime="application/pdf" size="1650000" label="Multi-page PDF"/>
            <format type="OCR" mime="text/plain" size="120000" label="Un-proofed OCR text"/>
          </div>
          <div id="chunk4" type="chunk" order="4" label="Pages 91-103">
            <format type="PDF.600" mime="application/pdf" size="550000" label="Multi-page PDF"/>
            <format type="OCR" mime="text/plain" size="40000" label="Un-proofed OCR text"/>
          </div>
        </formatSeq>
      </divReq>
    </Formats>
  </CGM>

Verb History

Modification of Dienst verb Formats, version 4.0.

Disseminate Content

Verb name: Disseminate
Verb version: 1.0 beta
Modification Date: 2003-03-03
Required arguments: identifier, format-type
Optional arguments: version, div, view, binder?, encoding?
MIMETYPE of response: Dependent on dissemination requested.

Verb Description

Request a dissemination of a digital object. The characteristics of the dissemination that can be requested (the arguments to the Disseminate verb), are determined by the responses to the Structure, Formats, ListViews, and ListVersions verbs for the specific document. The response is a MIME-typed byte stream.

Arguments

identifier :: [required] the document identifier
version :: specifies the document version for which the format information is requested. If omitted, it provides information about the latest document version available (see ListVersions).
div :: specifies the id value of a div component provided in the Formats response [or Structure???]. Use to request dissemination of a specific structural component of the specified document. [Is there a default then? Highest level div of document?]
view :: specifies the the view of the document for which a dissemination request is made. If omitted, ???. Specific views are requested using the view id value, obtained using the ListViews verb. [As with Formats, it's unclear how view works here, and whether it's necessary/desirable. Doesn't really make sense as is. That is, if there's a div requested, then it may conflict with view. I'd like not to use it unless there's some compelling reason to.]
format-type :: [required] specifies the MIME-type of the content in the dissemination. The list of available formats for a document is indicated by the response to the Formats request. Note that the value supplied for the argument is not a mime-type, but the format "type" indicated in the response to the Formats request.
binder :: [included for now; do we keep this?] specifies the encapsulating binder for the dissemination. The MIME type of the stream disseminated to the requesting client is then the output of the binder application. A binder argument is required if the dissemination contains multiple logical objects (e.g., multiple page images in image/tiff). The list of Binders supported by a repository is available through the ListBinders protocol request.
encoding :: [included for now; do we keep this?] specifies the compression encoding scheme that should be applied to the dissemination. The encoding applied is reflected in the HTTP Content-encoding header returned from the Disseminate request. The list of Encodings supported by a repository is available through the ListEncodings protocol request.

Response

The response to Disseminate is the requested content, directly. [do we consider wrapping content in xml, with something like base64 encoding?]

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.
badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Disseminate&ver=1.0&identifier=cul.math/00640001
	&div=chunk2&format-type=PDF.600

Response

The response returns a PDF file associated with a division identified as "chunk2", part of the specified document.

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Disseminate&ver=1.0&identifier=cul.math/00640001
	&div=i2&format-type=GIF

Response

Returns a GIF image of this division. Note that we are depending on divs from the Formats verb response, and not the Structure response. Is this what we want??

Verb History

Modification of Dienst Disseminate verb, version 1.0. Our position on the current CGM verb is that the record-oriented components (metadata) are to be replaced by OAI verb GetRecord, and that Disseminate needs to continue for handling the actual content.

Removed from Dienst verb description: "The MIME type of the byte stream is either the MIME type of the specified content-type or, if a binder is specified, the MIME type of that binder."

Removed from above, this was a definition of argument div (from jpw?): "<div> narrows the dissemination request to a specific structural component (e.g., a chapter) of the specified view of the document instance. The supplied argument must be one the available divs of the view (indicated by the output of the Structure request) paired with a value that is an identifier of one of those divs (again indicated by the output of the Structure request). For example, if a Structure request indicates that there is a div of type chapter with identifier 1, then this argument could by chapter=1. Note that the div argument can not be used in combination with the pageimage argument."

Also removed from argument section: "<viewID>,where <viewID> is one of the available views for the document instance. The resulting dissemination, if there is no pageimage argument, is then the specified view of the document instance."

List Views Available

Verb name: ListViews
Verb version: 1.0 beta
Modification Date: 2003-02-17
Required arguments: identifier
Optional arguments: none
MIMETYPE of response: text/xml

Verb Description

Returns a structured list of the possible views available for a single document.

Arguments

identifier :: [required] an identifier of the document for which a list of views is requested.

Response

One view, but only one, must be identified as the default view.

<view> :: an empty element, one per view, with three attributes:
- id :: [required] an id of the view (XML ID).
- label :: [required] a displayable, short label describing this view. These are applied by the local repository and should help end users choose an appropriate document view.
- default :: [required for default view] possible values are 1 or 0. If not included, default="0" is assumed.

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.
badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=ListViews&ver=1.0&identifier=cul.math/00640001

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="ListViews" ver="1.0" identifier="cul.math/00640001">
           http://some.cgm.server/script</request>
  <ListViews ver="1.0">
    <identifier value="cul.math/00640001">
    <view id="v123-a" label="Page listing" default="1" />
    <view id="v123-b" label="Chapter and Sections" />
  </ListViews>
</CGM>

Verb History

New to CGM. No corresponding Dienst verb.

Stage II Verbs

Describe Verb

Verb name: DescribeVerb [this needs work yet]
Verb version: 1.0 alpha
Modification Date: 2003-01-01
Required arguments: value
Optional arguments: none
MIMETYPE of response: text/xml

Verb Description

Returns a structured response that contains a list, where each element of the list provides information on a version of the specified verb that is supported by this service.

Arguments

value :: [required] name of the verb to be described.

Response

The following information may be provided at the verb or version level.

description :: , description of the verb or a specific version
note :: , information pertaining to the verb or a specific version

Each element of the list contains the following information:

version number :: of the verb.
arguments :: , a list of the names of the fixed and keyword arguments, if any, accepted by the verb in that version.
example :: template of request to this repository, with fixed argument indicated in brackets
returns :: , optional, contains information about response format.

Note that a service may implement more than one version of a verb.

Error Codes

Examples

Request

protocol=CGM&verb=DescribeVerb&ver=1.0&value=Formats

Response

<?xml version="1.0" encoding="UTF-8"?>
  <DescribeVerb ver="1.0">
    <verb name="Formats">
      <description>Returns a structured response indicating
        the formats of disseminations available for this document
      </description>
      <versions>
        <version id="1.0">
              <example>http://www.umdl.umich.edu/cgi/b/broker/broker?
				protocol=CGM&ver=2.0&
				verb=Formats&identifier=identifiervalue></example>
          <arguments>
            <required>
              <arg name="identifier" />
            </required>
            <optional>
              <arg name="version" />
              <arg name="view" />
            </optional>
          </arguments>
        </version>
      </versions>
    </Verb>
  </Describe-Verb>

Verb History

Modification of Dienst verb Describe-Verb, version 2.0.

List Verbs

Verb name: ListVerbs
Verb version: 1.0 beta
Modification Date: 2003-03-24
Required arguments: none
Optional arguments: none
MIMETYPE of response: text/xml

Verb Description

Returns a structured response containing the name and version number of each CGM verb supported by this repository. Different versions of the same verb should be included, within separate verb elements.

Arguments

Response

The List Verbs response contains a single, repeatable element.

<verb> :: an EMPTY element with two attributes:
- name :: the verb name.
- ver :: the version of the verb.

Error Codes

badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=ListVerbs&ver=1.0

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="ListVerbs" ver="1.0">
           http://some.cgm.server/script</request>
  <ListVerbs ver="1.0">
    <verb name="Disseminate" ver="1.0" />
    <verb name="Display" ver="1.0" />
    <verb name="Formats" ver="1.0" />
    <verb name="Search" ver="1.0" />
    <verb name="Search" ver="2.0" />
    <verb name="Structure" ver="1.0" />
    <verb name="ListViews" ver="1.0" />
    <verb name="ListVerbs" ver="1.0" />
  </ListVerbs>
</CGM>

Verb History

Dienst verb, version 2.0

Optional Verbs

List Binders Available

Verb name: ListBinders
Verb version: 1.0 alpha
Modification Date: 2003-03-18
Required arguments: none
Optional arguments: none
MIMETYPE of response: text/xml

Verb Description

Returns a structured list of the types of binders available in this repository. [In this repository? or for a specific document, or even a specific div within a document? Does this make any sense at the repo level?]

Arguments

Response

Error Codes

badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=ListBinders&ver=1.0

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="ListBinders" ver="1.0">
           http://some.cgm.server/script</request>
  <ListBinders ver="1.0">
    <binder type="tar" />
  </ListBinders>
</CGM>

Verb History

Dienst verb, version 1.0

List Encodings Available

Verb name: ListEncodings
Verb version: 1.0 alpha
Modification Date: 2003-03-18
Required arguments: none
Optional arguments: none
MIMETYPE of response: text/xml

Verb Description

Return a structured list of the types of encodings available in this repository. [same questions as with ListBinders--should this be aimed at documents or document divisions rather than the entire repo?]

Arguments

Response

Error Codes

badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=ListEncodings&ver=1.0

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="ListEncodings" ver="1.0">
           http://some.cgm.server/script</request>
  <ListEncodings ver="1.0">
    <encoding type="gzip" />
  </ListEncodings>
</CGM>

Verb History

Dienst verb, version 1.0

List Document Versions Available

Verb name: ListVersions
Verb version: 1.0 alpha
Modification Date: 2003-03-18
Required arguments: identifier
Optional arguments: none
MIMETYPE of response: text/xml

Verb Description

Returns a structured response describing the current versions available for the requested document.

Arguments

identifier :: [required] the document identifier for which version information is requested.

Response

<version> :: its attribute value is the version number, a positive integer, used when requesting a specific version in Structure, Formats, and Disseminate verbs. The element contains two subelements:
- <date> :: the date the version was last modified, expressed in the ISO 8601 format YYYY-MM-DD.
- <comment> :: a comment or description.

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.
badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=ListVersions&ver=1.0&identifier=cul.math/00640001

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="ListVersions" ver="1.0" identifier="cul.math/00640001">
           http://some.cgm.server/script</request>
  <ListVersions ver="1.0">
    <identifier value="cul.math/00640001">
    <version value="2">
      <date>2002-03-18</date>
      <comment>Author revised version.</comment>
    </version>
    <version value="1">
      <date>1999-10-01</date>
      <comment>Original published version.</comment>
    </version>
  </ListVersions>
</CGM>

Verb History

Modification of Dienst verb List-Versions, version 1.0.

Terms of Use

Verb name: Terms
Verb version: 1.0 alpha
Modification Date: 2003-03-18
Required arguments: identifier??
Optional arguments: none
MIMETYPE of response: text/xml

Verb Description

Returns terms of use and rights information [for a document, or entire collection? I'm assuming for a document here, for now. Some rights information is available at the repository level via OAI Identify].

Arguments

identifier :: [required] the document identifier for which terms of use information is requested.

Response

Error Codes

idDoesNotExist :: the value of the identifier argument is unknown or illegal.
badArgument :: the request includes illegal arguments, is missing required arguments, or contains invalid argument values.

Examples

Request

http://some.cgm.server/script?protocol=CGM
	&verb=Terms&ver=1.0&identifier=cul.math/00640001

Response

<?xml version="1.0" encoding="UTF-8"?>
<CGM>
  <responseDate>2002-10-02T19:20:30Z</responseDate>
  <request verb="Terms" ver="1.0" identifier="cul.math/00640001">
           http://some.cgm.server/script</request>
  <Terms ver="1.0">
    <identifier value="cul.math/00640001">
    <terms>
      <date>2002-03-18</date>
      <comment>This digital material is made available by Cornell 
         University Library, and is to be used for personal or research use
         only. Any other use, including but not limited to commercial or
         scholarly reproductions, redistribution, publication, or transmission,
         whether by electronic means or otherwise, without prior written
         permission of the Library is prohibited.</comment>
    </terms>
  </Terms>
</CGM>

Verb History

New to CGM?

CGM Protocol

Stage I Verbs

Verb Description

Arguments

Response

Error Codes

Examples

Request

Response

Request

Response

Request

Response

Verb History

Verb Description

Arguments

Response

Error Codes

Examples

Request

Verb History

Verb Description

Arguments

Response

Error Codes

Examples

Request

Response

Request

Response

Verb History

Verb Description

Arguments

Response

Error Codes

Examples

Request

Response

Verb History

Verb Description

Arguments

Response

Error Codes

Examples

Request

Response

Verb History

Verb Description

Arguments

Response

Error Codes

Examples

Request

Response

Request

Response

Verb History

Verb Description

Arguments

Response

Error Codes

Examples

Request

Response

Verb History

Stage II Verbs

Verb Description

Arguments

Response

Error Codes

Examples

Request

Response

Verb History

Verb Description

Arguments

Response

Error Codes

Examples

Request