IDL Reference Guide: Network Objects

IDLnetOGCWMS::GetLayers

The IDLnetOGCWMS::GetLayers function method provides access to the layer details that were returned and parsed by the IDLnetOGCWMS::GetCapabilities method. You can return information for all layers or a subset of the layers, which can be useful when:

Syntax

Result = Obj->[IDLnetOGCWMS::]GetLayers ([, COUNT=variable], [, NUMBER=value] [, INDEX=value])

Return Value

The return value is an array of structures containing one or more layers. Use the COUNT keyword to verify that layers are available since the returned value can be zero when layers are not available. The layer structure contains single values, arrays of strings, and structures.

Layer Structure

The layer structure is complex. Some elements in the main structure return other structures as shown in the following figure. Click on the names of any of the structures in the boxes to go to the associated reference section.

Figure 9-2: Layer Structure and Sub-structures

Figure 9-2: Layer Structure and Sub-structures

Main Layer Structure

The following table contains a list of tags found in the main level Layer structure. All items return string values unless otherwise noted. All tags are valid in versions 1.1.1 and 1.3.0 unless otherwise noted.

1.1.1 XML source: 
<WMT_MS_Capabilities><version>  
1.3.0 XML source: 
<WMS_Capabilities><version>  

1.1.1 XML source: 
<WMT_MS_Capabilities><updatesequence>  
1.3.0 XML source: 
<WMS_Capabilities><updatesequence>  

1.1.1, 1.3.0 XML source: <layer><name>  

1.1.1, 1.3.0 XML source: 
<layer><title>  

1.1.1, 1.3.0 XML source: 
<layer><abstract>  

1.1.1, 1.3.0 XML source: 
<capability><request><getmap><format>  

1.1.1, 1.3.0 XML source: 
<capability><request><getfeatureinfo>
<format>  

1.1.1, 1.3.0 XML source: 
<layer><keywordlist><keyword>  

1.1.1 XML source: <layer><srs>  

1.3.0 XML source: <layer><crs>  

1.1.1 XML source: 
<layer><latlonboundingbox>  

1.3.0 XML source: 
<layer><ex_geographicboundingbox>  

1.1.1, 1.3.0 XML source: 
<layer><bounding_box>  

1.1.1 XML source: <layer><extent>  

1.1.1, 1.3.0 XML source: 
<layer><dimension>  

1.1.1, 1.3.0 XML source: 
<layer><attribution>  

1.1.1, 1.3.0 XML source: 
<layer><authority>  

1.1.1, 1.3.0 XML source: 
<layer><identifier>  

1.1.1, 1.3.0 XML source: 
<layer><metadataurl>  

1.1.1, 1.3.0 XML source: 
<layer><dataurl>  

1.1.1, 1.3.0 XML source: 
<layer><featurelisturl>  

1.1.1, 1.3.0 XML source: 
<layer><style>  

1.1.1 XML source: 
<layer><scalehint><min>  
1.3.0 XML source: 
<layer><minscaledenominator>  

1.1.1 XML source: 
<layer><scalehint><max>  
1.3.0 XML source: 
<layer><maxscaledenominator>  

1.1.1, 1.3.0 XML source: 
<layer><queryable>  

1.1.1, 1.3.0 XML source: 
<layer><cascaded>  

1.1.1, 1.3.0 XML source: 
<layer><opaque>  

1.1.1, 1.3.0 XML source: 
<layer><nosubsets>  

1.1.1, 1.3.0 XML source: 
<layer><fixedwidth>  

1.1.1, 1.3.0 XML source: 
<layer><fixedheight>  

Lat_Lon_Bbox Structure

This child structure is accessed through the LAT_LON_BBOX field of the parent layer structure. All elements are strings unless otherwise noted.

1.1.1 XML source: 
<layer><latlonboundingbox><minx>  

1.1.1 XML source: 
<layer><latlonboundingbox><miny>  

1.1.1 XML source: 
<layer><latlonboundingbox><maxx>  

1.1.1 XML source: 
<layer><latlonboundingbox><maxy>  

Ex_GeoBox Structure

This child structure is accessed through the EX_GEOBOX field of the parent layer structure. All elements are strings unless otherwise noted.

1.3.0 XML source: 
<layer><ex_geographicboundingbox><westboundlongitude>  

1.3.0 XML source: 
<layer><ex_geographicboundingbox><eastboundlongitude>  

1.3.0 XML source: 
<layer><ex_geographicboundingbox><southboundlatitude>  

1.3.0 XML source: 
<layer><ex_geographicboundingbox><northboundlatitude>  

Bounding_Box Structure

This child structure is accessed through the BOUNDING_BOX field of the parent layer structure. To determine the number of Bounding_Box structures, access the NUM_BOUNDING_BOX field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1 XML source: <layer><boundingbox><srs>  

1.3.0 XML source: <layer><boundingbox><crs>  

1.1.1, 1.3.0 XML source: 
<layer><boundingbox><minx>  

Extent Structure

This child structure is accessed through the EXTENT field of the parent layer structure. To determine the number of Extent structures, access the NUM_EXTENT field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1 XML source: <layer><extent><name>  

1.1.1 XML source: <layer><extent><default>  

1.1.1 XML source: <layer><extent><nearestvalue>  

1.1.1 XML source: <layer><extent>  

Dimension Structure

This child structure is accessed through the DIMENSION field of the parent layer structure. To determine the number of Dimension structures, access the NUM_DIMENSION field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><dimension><name>  

1.1.1, 1.3.0 XML source: 
<layer><dimension><units>  

1.1.1, 1.3.0 XML source: 
<layer><dimension><unitsymbol>  

1.3.0 XML source: <layer><dimension><default>  

1.3.0 XML source: 
<layer><dimension><multiplevalues>  

1.3.0 XML source: 
<layer><dimension><nearestvalue>  

1.3.0 XML source: <layer><dimension><current>  
Valid only in version 1.3.0.  

1.1.1, 1.3.0 XML source: <layer><dimension>  

Attribution Structure

This child structure is accessed through the ATTRIBUTION field of the parent layer structure. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><attribution><title>  

1.1.1, 1.3.0 XML source: 
<layer><attribution><onlineresource>  

1.1.1, 1.3.0 XML source: 
<layer><attribution><logourl><format>  

1.1.1, 1.3.0 XML source: 
<layer><attribution><logourl><onlineresource>  

1.1.1, 1.3.0 XML source: 
<layer><attribution><logourl><width>  

1.1.1, 1.3.0 XML source: 
<layer><attribution><logourl><height>  

Authority Structure

This child structure is accessed through the AUTHORITY field of the parent layer structure. To determine the number of Authority structures, access the NUM_AUTHORITY field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><authorityurl><name>  

1.1.1, 1.3.0 XML source: 
<layer><authorityurl><onlineresource>  

Identifier Structure

This child structure is accessed through the IDENTIFIER field of the parent layer structure. To determine the number of Identifier structures, access the NUM_IDENTIFIER field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><identifier>  

1.1.1, 1.3.0 XML source: 
<layer><identifier><authority>  

Metadata_URL Structure

This child structure is accessed through the METADATA_URL field of the parent layer structure. To determine the number of Metadata_URL structures, access the NUM_METADATA_URL field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><metadataurl><type>  

1.1.1, 1.3.0 XML source: 
<layer><metadataurl><format>  

1.1.1, 1.3.0 XML source: 
<layer><metadataurl><onlineresource>  

Data_URL Structure

This child structure is accessed through the DATA_URL field of the parent layer structure. To determine the number of Data_URL structures, access the NUM_DATA_URL field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><dataurl><format>  

1.1.1, 1.3.0 XML source: 
<layer><dataurl><onlineresource>  

Feature_URL Structure

This child structure is accessed through the FEATURE_URL field of the parent layer structure. To determine the number of Feature_URL structures, access the NUM_FEATURE_URL field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><featurelisturl><format>  

1.1.1, 1.3.0 XML source: 
<layer><featurelisturl><onlineresource>  

Style Structure

This child structure is accessed through the STYLE field of the parent layer structure. To determine the number of Style structures, access the NUM_STYLE field value. The number of structures can be 0 to many. All elements are strings unless otherwise noted.

1.1.1, 1.3.0 XML source: 
<layer><style><name>  

1.1.1, 1.3.0 XML source: 
<layer><style><title>  

1.1.1, 1.3.0 XML source: 
<layer><style><title>  

1.1.1, 1.3.0 XML source: 
<layer><style><legendurl><format>  

1.1.1, 1.3.0 XML source: 
<layer><style><legendurl><onlineresource>  

1.1.1, 1.3.0 XML source: 
<layer><style><legendurl><width>  

1.1.1, 1.3.0 XML source: 
<layer><style><legendurl><height>  

1.1.1, 1.3.0 XML source: 
<layer><style><stylesheeturl><format>  

1.1.1, 1.3.0 XML source: 
<layer><style><stylesheeturl>
<onlineresource>  

1.1.1, 1.3.0 XML source: 
<layer><style><styleurl><format>  

1.1.1, 1.3.0 XML source: 
<layer><style><styleurl><onlineresource>  

Arguments

None

Keywords

COUNT

Set this keyword to a variable that will contain the number of layer structures returned in this method's structure array. This value can be zero.

NUMBER

Set this keyword to the number of layers to return. If this keyword is not set, all layers will be returned minus the number of those skipped up to the INDEX keyword, if it is set. If this value is zero, zero layers will be returned. If the value is greater than the number of available layers, then this value is ignored and the number of available layers (COUNT) is returned.

INDEX

Set this keyword to the zero-based index of the first layer to return, skipping over all preceding layers. If this keyword is not set, all layers will be returned. You can use this property to enable navigation through a list of layers displayed in a user interface. For example, suppose there are 10 rows in a table. On the first call to GetLayers, set this value to 0 and NUMBER to 10. To display the next set of values, you would set this keyword to 10 (skip the first 10 values and display the next ten).

Examples

The following code parses the URL of WMS server, queries its capabilities (using GetCapabilities) and then extracts information from the returned XML file using GetLayers and GetServiceSection. Information is printed to the IDL Output Log.

FUNCTION ogcwms_callback,  StatusInfo, CallbackData  
  
PRINT, StatusInfo  
  
; Indicate all is well.  
vCancelFlag = 1  
RETURN, vCancelFlag  
  
END  
  
PRO ogc_wms_getlayers_doc  
  
; Use the GetLayers method to access data returned in  
; the XML file by the GetCapabilities method.  
  
; 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://xtra.interactive-instruments.de/cgi-bin/wms?"  
  
; Catch error.  
CATCH, errorStatus  
IF (errorStatus NE 0) THEN BEGIN  
   CATCH,/CANCEL  
   PRINT, !ERROR_STATE.MSG  
   RETURN  
ENDIF  
  
; Create an IDLnetOGCWMS object and parse a known, working URL   
; to set mandatory properties. Use /VERBOSE to show additional   
; information.  
oWms = OBJ_NEW("IDLnetOGCWMS", $  
   CALLBACK_FUNCTION="ogcwms_callback", /VERBOSE)  
oWms->ParseUrl, url  
  
; Return and parse a description of all data holdings on  
; the WMS server.  
count = oWMS->GetCapabilities()  
  
; Make sure the server returned some layers.  
If (count NE 0) THEN BEGIN  
  
   ; Use the GetLayers method to translate the  
   ; parsed XML data into an array of IDL structures. The NAME  
   ; field of this structure is used to identify what layer   
   ; to request data for from the server.  
   layerStruct = oWMS->GetLayers $                            
      (COUNT=layercount, NUMBER=5, INDEX = 1)  
   PRINT, "Returning structures for ", + layercount, + " layers"  
  
   ; Access elements of the GetLayers structure.  
   FOR x=0, layerCount-1 DO BEGIN  
      PRINT, 'Layer = ', strtrim(x,2)  
      PRINT, '  parent          = ', layerStruct[x].parent  
      PRINT, '  level           = ', layerStruct[x].level  
      PRINT, '  name            = ', layerStruct[x].name  
      PRINT, '  title           = ', layerStruct[x].title  
      PRINT, '  version         = ', layerStruct[x].version  
      PRINT, '  authority_url   = ', layerStruct[x].authority  
      PRINT, '  num styles      =  ', layerStruct[x].num_style  
      FOR j=0, layerStruct[x].num_style-1 do begin  
        PRINT, '  style name   = ' , layerStruct[x].style[j].name  
        PRINT, '  style title  = ' , layerStruct[x].style[j].title  
      ENDFOR  
   ENDFOR  
  
   ; Use the GetServiceSection method to get the Service section  
   ; data from the XML file containing the layer info.  
   serviceStruct = oWMS->GetServiceSection()  
  
   PRINT, 'Service Section'  
   PRINT, '  name              = ', serviceStruct.name  
   PRINT, '  title             = ', serviceStruct.title  
   PRINT, '  abstract          = ', serviceStruct.abstract  
   HELP, serviceStruct.keyword  
   PRINT, '  keywords          = ', serviceStruct.keyword  
   PRINT, '  accessConstraints = ', serviceStruct.access  
ENDIF ELSE BEGIN  
   void = DIALOG_MESSAGE("No information available " $  
      + "from WMS Server", /ERROR)  
   RETURN  
ENDELSE  
  
; Cleanup.  
OBJ_DESTROY, oWms  
  
END  

Version History

See Also

IDLnetOGCWMS::GetCapabilities, IDLnetOGCWMS::GetServiceSection

  IDL Online Help (March 06, 2007)