Routines (alphabetical) > Object Classes > Network Object Classes > IDLnetOGCWCS::DescribeCoverage

# IDLnetOGCWCS::DescribeCoverage

The IDLnetOGCWCS::DescribeCoverage function method retrieves an XML file containing one or more descriptive coverage offerings 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 DESCRIBE_COVERAGE_FILENAME property, and will be overwritten if this property value remains unchanged between DescribeCoverage 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.

Note: 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 dealing 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

To return status information during the request, set 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 DescribeCoverage request fails.

After this method returns, you must use IDLnetOGCWCS::GetCoverageOffering to return the coverage offerings details. The DescribeCoverage method accesses and parses the information retrieved from the server, and returns the names of the coverages, but does not return the detailed information.

## Syntax

Result = Obj->[IDLnetOGCWCS::]DescribeCoverage ([, COUNT=variable] [, FROM_FILE=value] , NAMES=value [, SCHEMA_CHECKING=value] [, VALIDATION_MODE=value] )

## Return Value

Returns a string array listing the names of the coverages returned by the remote WCS server. This is a subset of the information returned by the IDLnetOGCWCS::GetCoverageOffering method and can be useful when populating a user interface with the names of the available coverage offerings.

This method returns an empty string when no names are available.

## Arguments

None

## Keywords

### COUNT

Set this keyword to a named variable that will contain the number of coverage offerings received.

### FROM_FILE

Set this keyword to a string containing the full path and filename of the XML file to parse for coverage offering details. This allows you use a previously downloaded coverage offering 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.

### NAMES

Set this keyword to a string containing a single coverage name or a string array of coverage names for which to return detailed coverage offering information from the WCS server. The name of a coverage can be found by accessing the NAME field of the structure returned by the IDLnetOGCWCS::GetCoverageOfferingBriefs method.

Note: Not all servers accept a string array. Always check the number of coverages returned before proceeding to avoid unexpected errors.

Note: Setting the NAMES keyword is mandatory unless you are returning coverage information from a file using FROM_FILE. Do not set both NAMES and FROM_FILE keywords.

When you use the NAMES keyword and the CALLBACK_FUNCTION property is set, status information will be returned each time a packet containing a portion of the file is delivered from the WCS server.

### 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

The following example accesses an OGC server and requests two coverage offering briefs. Retrieve the names of the briefs from the GetCoverageOfferingBriefs structure and add them to a string array. Then use the DescribeCoverage method to return detailed information about those two coverages from the server. After getting detailed coverage information, use the GetCoverageOffering method to access this information as shown in Examples.

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.

vCancelFlag = 1

RETURN, vCancelFlag

END

PRO ogc_wcs_describecoverage_doc

; Use the DescribeCoverage method to return detailed information

; about a coverage, identified by name to the default descov.xml

; file. Access the coverage name by querying the

; GetCoverageOfferingBriefs method's structure.

; 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://data.exelisvis.com:80/cgi-bin" + $

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

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

; Catch error.

CATCH, errorStatus

IF (errorStatus NE 0) THEN BEGIN

CATCH,/CANCEL

r = DIALOG_MESSAGE(!ERROR_STATE.MSG, $

TITLE='OGC WCS Error', /ERROR)

PRINT, !ERROR_STATE.MSG

IF OBJ_VALID(oWcs) THEN OBJ_DESTROY, oWcs

RETURN

ENDIF

; Create an IDLnetOGCWCS object and parse a known, working URL to

; set mandatory properties.

oWcs = OBJ_NEW("IDLnetOGCWCS", $

CALLBACK_FUNCTION="ogcwcs_callback")

oWcs->ParseUrl, url

; Return and parse a brief description of all data holdings

; on the WCS server.

count = oWCS->GetCapabilities()

; Initialize string array to hold names of briefs.

arrName=' '

; Make sure the server returned some coverage offering briefs.

IF (count NE 0) THEN BEGIN

; Return information about the holding using the

; GetCoverageOfferingBriefs method. The NAME field of the

; returned structure is used to identifywhat coverage

; to get more information about using the DescribeCoverage

; method. Here we return a maximum of 2 coverage briefs.

; You could use INDEX to specify the first item to return.

briefStruct = oWCS->GetCoverageOfferingBriefs $

(COUNT=briefcount, NUMBER=2)

PRINT, "Returning structures for ", + briefcount, + " briefs"

; Access the name element of the GetCoverageOfferingBriefs

; structre.

FOR x=0, briefCount-1 DO BEGIN

PRINT, 'CoverageOfferingBrief = ', strtrim(x,2)

PRINT, ' name = ', briefStruct[x].name

; Add the name to the string array.

arrName = [arrName, briefStruct[x].name]

ENDFOR

; Strip out empty string element.

arrName=arrName[1:*]

PRINT, "Number of arrName elements = " $

+ STRING(N_ELEMENTS(arrName))

; Call DescribeCoverage to acccess coverage details for the

; coverages offerings in the array.

covName = oWCS->DescribeCoverage(NAMES=arrName, COUNT=numCov)

PRINT, "Number of coverages returned by DescribeCoverage = " $

+ STRING(numCov)

PRINT, "Coverage Name(s) = " + covName

ENDIF ELSE BEGIN

void = DIALOG_MESSAGE("No information available" $

+ "from WCS Server", /ERROR)

RETURN

ENDELSE

; Cleanup.

OBJ_DESTROY, oWcs

END

## Version History

6.4 | Introduced

## See Also

IDLnetOGCWCS::GetCoverageOffering