Metcast Channels Table of Contents (CTOC)

Introduction
Contents of Metcast Channels
Sample CTOC requests
Examples
References

Introduction

Every Metcast server offers a reflexive facility: an ability to describe what it can deliver, both in principle and in reality. The server can send the comprehensive menu of products and indicate which products on that list are actually present in the Metcast database and thus available for immediate download. A server can also tell how to build a Request Language phrase to ask for a desired product.

The reflexive facility is implemented by Metcast server modules that accept Describe MBL requests and send Metcast Table of Contents documents in reply. The Metcast Table of Contents (MTOC) is an XML format introduced in [MTOC]. An MTOC document is a collection of descriptions for one or several product categories. The present web page specifies the format and semantics of the table of contents for one particular category: Metcast Channels [Channels].

The XML format introduced here can describe classes of Metcast Channel products (a potential MTOC, [MTOC]) as well as products in a particular channel (an actual MTOC).

Contents of Metcast Channels

An element channels collects separate items of the Channel Table of Contents. Each item describes one channel -- one class of products with its own set of attributes and its own access permissions.

The top element of the CTOC

	XML DTD
	<!ELEMENT channels ( channel )*>

Attributes

TStamp-OPT
	Time Stamp of the moment this description was created.
	This attribute may be omitted, in which case a `TStamp` attribute of the parent `MTOC` element is assumed.

<!ATTLIST channels
	%TStamp-OPT;
>

channel Element

Products in a Metcast Channels database are grouped into classes -- according to their mime type, intended audience, particular group of publishers, or simply for convenience. A channel element describes a particular class or summarizes the class' products that are currently in the database. All products of the same class have a common set of attributes, described by an attr element below. In a potential CTOC, the channel element is a collection of attr elements: the channel meta-data. In an actual CTOC, the channel element is a collection of ch-item s, which describe products in the channel.

	XML DTD
	<!ELEMENT channel (attr* \| ch-item*)>

Attributes

Name
	An identifier for the channel	char(8) `NMTOKEN`

Title
	Description for the channel	varchar or omitted `CDATA`

Comment
	More detailed summary for the channel	varchar or omitted `CDATA`
	This attribute is present only in the detailed description of a channel.

MaxLen
	The maximum number of products the channel may contain	integer or omitted `NMTOKEN`

Length
	The number of products of this class currently in the database	integer or omitted `NMTOKEN`
	This attribute is present only in the detailed description of a channel.

TRange
	Timestamps of the earliest and the latest product in the channel	or omitted `%TRange-type;`
	This attribute is present only in the detailed description of a channel and only if the channel is not empty.

<!ATTLIST channel
	Name NMTOKEN #REQUIRED
	Title CDATA #IMPLIED
	Comment CDATA #IMPLIED
	MaxLen NMTOKEN #IMPLIED
	Length NMTOKEN #IMPLIED
	TRange %TRange-type; #IMPLIED
>

attr Element

This element describes one attribute associated with a product or its class. An attribute of a class -- an attribute declaration -- has a name, the use type (required, optional or fixed) and, optionally, the default value in the character content of the element.

	XML DTD
	<!ELEMENT attr (#PCDATA)>

Attributes

Name
	The name of the attribute	varchar `CDATA`
	An attribute named `=mime-type` describes the media type of data stored in the channel. This attribute is set by a publisher and is reported to a client as a media type of the `content-type` header of the corresponding MIME entity. All other attributes are specified as name=value pairs in the `content-type` header.

Use
	The use mode for the attribute: `required` , `fixed` , or omitted for an optional attribute	enum or omitted `(required\|fixed)`

Comment
	Commentary string for the channel attribute	varchar or omitted `CDATA`
	This attribute is present only in the detailed description of a channel.

<!ATTLIST attr
	Name CDATA #REQUIRED
	Use (required|fixed) #IMPLIED
	Comment CDATA #IMPLIED
>

ch-item Element

This element describes meta-data of one product stored in a channel. A ch-item element is a set of attr s, whose content are the actual values of the corresponding attributes for this particular product.

	XML DTD
	<!ELEMENT ch-item (attr*)>

Attributes

OID
	The unique identifier of the product	integer `NMTOKEN`

TStamp
	The timestamp of the moment the product was added to the channel

<!ATTLIST ch-item
	OID NMTOKEN #REQUIRED
	%TStamp;
>

Sample CTOC requests

A user can obtain the description of channels or products in a channel by submitting a Describe MBL request or by GETting a resource described by a particular URL. The latter method is particularly appropriate for interactive use: the user may type the URL into any browser of his choice. The table below lists MBL requests and URLs. As you may have noticed, there are several ways to get a description. All the ways converge to the same describer procedure, however.

A Metcast Channels availability check

We can use the following requests to check to see if a particular Metcast server supports Metcast channels at all.

URL

http://www.metnet.navy.mil/cgi-bin/oleg/server/channels

MBL

     (descr (products 
              (Describe (channels (describe-scope short)))))

MBL

     (descr (products 
              (Describe (path "channels"))))

If the product channels is not available the last MBL request and the URL query return an empty reply (HTTP status code 304 ) rather than an error reply.

A detailed description of all channels available to the current user

URL

http://www.metnet.navy.mil/cgi-bin/oleg/server/channels/

MBL

     (descr (products 
              (Describe (channels))))

MBL

     (descr (products 
              (Describe (path "channels" ""))))

The present and the previous group of requests return a potential CTOC, which describes the classes (channels) of products that could be retrieved from the Metcast server. The potential CTOC does not say however if the channels currently have any products.

A brief description of products in a particular channel

The present group of requests gives a short description of products in a particular channel, e.g., VDU-INCR . The returned document is an actual CTOC. The short description tells the number of products in the channel and the earliest and the latest insertion timestamps.

URL

http://www.metnet.navy.mil/cgi-bin/oleg/server/channels/VDU-INCR

MBL

     (descr (describe-scope short)
       (products 
         (Describe (Channel VDU-INCR))))

MBL

     (descr (products 
              (Describe (path "channels" "VDU-INCR"))))

A detailed description of products in a particular channel

The present group of requests also returns the actual CTOC, describing products in a particular channel in detail. For each product, the server reports its OID and the insertion timestamp, as well as the values of all of product's attributes.

URL

http://www.metnet.navy.mil/cgi-bin/oleg/server/channels/VDU-INCR/

MBL

     (descr (products 
              (Describe (Channel VDU-INCR))))

MBL

     (descr (products 
              (Describe (path "channels" "VDU-INCR" ""))))

Examples

A potential CTOC for two channels.

     <!DOCTYPE MTOC SYSTEM "MTOC.dtd">
     <MTOC TStamp='1046218443' HREF='http://www.metnet.navy.mil/cgi-bin/oleg/server'>
     <channels>
      <channel Name='DEMO-IMG' Title='Demo Channel - imagery' MaxLen='1'>
        <attr Name='publisher' Use='fixed'>FNMOC</attr>
        <attr Name='=mime-type'>image/x-demo</attr>
        <attr Name='fname'/>
      </channel>
      <channel Name='VDU-INCR' Title='VDU: Incremental DNC updates' MaxLen='100'>
        <attr Name='region' Use='required'/>
        <attr Name='from-v' Use='required'/>
        <attr Name='os-type' Use='required'/>
        <attr Name='to-v' Use='required'/>
        <attr Name='=mime-type' Use='fixed'>application/x-vdu-incr</attr>
        <attr Name='lib' Use='required'/>
      </channel>
     </channels>
     </MTOC>

A detailed description for the channel VDU-INCR and a brief description of that channel's actual products.

     <!DOCTYPE MTOC SYSTEM "MTOC.dtd">
     <MTOC TStamp='1046218808' HREF='http://www.metnet.navy.mil/cgi-bin/oleg/server'>
     <channels>
      <channel Name='VDU-INCR' Title='VDU: Incremental DNC updates'
               Comment='VPF database updates, incremental patch,
                        from one DNC version to another'
               Length='15' TRange='1017696600 1017696600' MaxLen='100'>
        <attr Name='=mime-type' Use='fixed'>application/x-vdu-incr</attr>
        <attr Name='os-type' Use='required'/>
        <attr Name='region' Use='required'/>
        <attr Name='from-v' Use='required'/>
        <attr Name='to-v' Use='required'/>
        <attr Name='lib' Use='required'/>
      </channel></channels>
     </MTOC>

A detailed description of products in the channel VDU-INCR.

     <!DOCTYPE MTOC SYSTEM "MTOC.dtd">
     <MTOC TStamp='1046218663' HREF='http://www.metnet.navy.mil/cgi-bin/oleg/server'>
     <channels><channel Name='VDU-INCR'>
      <ch-item OID='988' TStamp='1017696600'>
        <attr Name='os-type'>UNIX</attr>
        <attr Name='=mime-type'>application/x-vdu-incr</attr>
        <attr Name='region'>17</attr>
        <attr Name='lib'>coa17dINCR</attr>
        <attr Name='from-v'>12</attr>
        <attr Name='to-v'>14</attr>
      </ch-item>
     </channel></channels>
     </MTOC>