IDLnetOGCWMS::GetLayers

Syntax | Return Value | Arguments | Keywords | Examples | Version History | See Also

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 33-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.

Note
When populating a user interface, it is useful to set this keyword equal to the number of rows in the table.

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.

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 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://data.ittvis.com:80/cgi-bin/mapserv.exe?" + $ 
   "map=/OGC_Data/WMS/wms_demo.map&service=WMS" 
 
; Catch error. 
CATCH, errorStatus 
IF (errorStatus NE 0) THEN BEGIN 
   CATCH,/CANCEL 
   PRINT, !ERROR_STATE.MSG 
   IF OBJ_VALID(oWms) THEN OBJ_DESTROY, oWms 
   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 


Tip

Also see Sample WMS Browser.

Version History

See Also

IDLnetOGCWMS::GetCapabilities, IDLnetOGCWMS::GetServiceSection