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 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
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
vCancelFlag = 1
RETURN, vCancelFlag
END
PRO ogc_wcs_describecoverage_doc
url="http://mydataserver.com:80/cgi-bin" + $
"/mapserv.exe?MAP=/OGC_Data/WCS/wcs_demo.map" + $
"&SERVICE=WCS&VERSION=1.0.0&REQUEST=GetCapabilities"
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
oWcs = OBJ_NEW("IDLnetOGCWCS", $
CALLBACK_FUNCTION="ogcwcs_callback")
oWcs->ParseUrl, url
count = oWCS->GetCapabilities()
arrName=' '
IF (count NE 0) THEN BEGIN
briefStruct = oWCS->GetCoverageOfferingBriefs $
(COUNT=briefcount, NUMBER=2)
PRINT, "Returning structures for ", + briefcount, + " briefs"
FOR x=0, briefCount-1 DO BEGIN
PRINT, 'CoverageOfferingBrief = ', strtrim(x,2)
PRINT, ' name = ', briefStruct[x].name
arrName = [arrName, briefStruct[x].name]
ENDFOR
arrName=arrName[1:*]
PRINT, "Number of arrName elements = " $
+ STRING(N_ELEMENTS(arrName))
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
OBJ_DESTROY, oWcs
END
Version History
See Also
IDLnetOGCWCS::GetCoverageOffering