IDLnetOGCWCS::GetCapabilities

The IDLnetOGCWCS::GetCapabilities function method retrieves an XML file containing coverage offering briefs from a remote OGC WCS server, writes the file to disk, and parses the file contents before returning. The XML file is written to disk according to the CAPABILITIES_FILENAME property, and will be overwritten if this property value remains unchanged between GetCapabilities requests.

You can parse the contents of an existing XML file by setting the FROM_FILE keyword. This avoids having to download the same information as that which exists on disk.

The URL_PATH and URL_HOSTNAME properties must be set before requesting information from a remote WCS server. You can either set these properties manually or pass a URL to the IDLnetOGCWCS::ParseUrl method prior to making a request. If you are working with a proxy server, you must also set the PROXY_HOSTNAME and PROXY_PORT properties to the correct values.

This method returns only when one of the following occur:

Completes retrieval and parsing of information from server
Encounters an HTTP error
Encounters an OGC exception
Responds to a cancel request as specified in a callback return value

You can implement a callback to return status information during the request by setting the CALLBACK_FUNCTION property. You can also use a callback to cancel a request. See Using Callbacks with the IDLnetOGCWCS Object for details. This method will throw an error if the GetCapabilities request fails.

After this method returns, you must use IDLnetOGCWCS::GetCoverageOfferingBriefs to return information about the coverage offering briefs. The GetCapabilities method accesses and parses the information from the server and returns a count containing the number of briefs received, but does not provide immediate access to the detailed information. You can also use the IDLnetOGCWCS::GetServiceSection method to access information about services contained in the XML file.

Syntax

Result = Obj->[IDLnetOGCWCS::]GetCapabilities ([ ,FROM_FILE=string] [,SCHEMA_CHECKING=value] [, VALIDATION_MODE=value])

Return Value

Returns the number of coverage offering briefs received.

Arguments

None

Keywords

FROM_FILE

Set this keyword to a string containing the full path and filename of the XML file to parse for coverage offering briefs and services. This allows you use a previously downloaded capabilities file.

When you use the FROM_FILE keyword and the CALLBACK_FUNCTION property is set, status information will be returned when the XML file is first accessed and when parsing has ended. The entire file contents are parsed.

SCHEMA_CHECKING

XML Schemas describe the structure and allowed contents of an XML document. Schemas are more robust than, and are envisioned as a replacement for, Document Type Definitions (DTDs). Schemas are typically provided via a link to an external document, which must be downloaded before validation can occur.

Set this keyword to one of the following values to control the degree of error-checking the parser should perform:

0	Turn schema checking off: The XML file is not checked for errors. Use this setting to avoid the delays associated with schema checking. This is the default.
1	Check for fatal schema errors in the XML file: This setting requires more time since the XML file is checked against a WCS schema reference document accessed from the OGC server.
2	Check for fatal errors in the XML file and schema document: This setting checks both the XML file and the reference schema document for fatal errors, and requires a considerable amount of time.

VALIDATION_MODE

XML Document Type Definitions (DTDs) describe the structure and allowed contents of an XML document. A DTD can be embedded in an XML document or provided via a link to an external document, which must be downloaded before validation can occur. In most applications, schemas provide a more robust validation mechanism.

Set this keyword to one of the following values to control DTD-based validation of the XML document:

0	Turn DTD validation off: External DTDs are not loaded and the XML file is not checked for errors. Use this setting to avoid the delays associated with loading and checking an external DTD. This is the default.
1	Validate only if an embedded DTD or a link to an external DTD is provided.
2	Always perform validation. If this option is in force and no DTD is provided, every XML element in the document will generate an error.

Examples

Parse a URL and then call GetCapabilities to return an XML file. Use a callback function to return status information about the query. See IDLnetOGCWCS::GetCoverageOfferingBriefs for an example that retrieves information needed for a DescribeCoverage query.

Note: You may need to replace the URL in the following example as there is no guarantee that the given OCG server will be available when you attempt to establish the connection.

FUNCTION ogcwcs_callback,  StatusInfo, CallbackData

PRINT, StatusInfo

; Indicate all is well.

RETURN, 1

END

PRO ogc_wcs_getcapabilities_doc

; This example queries an OGC server at the following URL. Change

; the value of this variable to access a server of your choice.

url="http://mydataserver.com:80/cgi-bin" + $

   "/mapserv.exe?MAP=/OGC_Data/WCS/wcs_demo.map" + $

   "&SERVICE=WCS&VERSION=1.0.0&REQUEST=GetCapabilities"

; Create object and define callback function. Adding /VERBOSE

; prints additional StatusInfo to the Output log.

oWcs = OBJ_NEW("IDLnetOGCWCS", $

   CALLBACK_FUNCTION="ogcwcs_callback", /VERBOSE)

; Parse the URL.

oWcs->ParseUrl, url

; Call GetCapabilities with schema checking off since this is for

; example purposes.

count = oWcs->GetCapabilities(SCHEMA_CHECKING=0)

oWcs->GetProperty, LAST_FILE=lastfile

; Show the number of returned coverage offering briefs.

PRINT, "Query returned ", $

   + STRING(count) + "  coverage offering briefs"

; Cleanup.

OBJ_DESTROY, oWcs

END

Version History

6.4	Introduced