ILayerDescription.DefinitionExpression Property

The definition expression for the layer.

[Visual Basic .NET]
Public Property DefinitionExpression As String

[C#]
public string DefinitionExpression {get; set;}

[C++]
HRESULT get_DefinitionExpression(
  System.String* Expression
);

[C++]
HRESULT put_DefinitionExpression(
  BSTR Expression
);

[C++]

Parameters
Expression [out, retval]

  Expression is a parameter of type BSTR*
Expression [in]

  Expression is a parameter of type BSTR

Product Availability

Remarks

A DefinitionExpression can be set on a layer in order to limit layer features available for display or query. This only applies for the
request and does not replace the definition query set in the source
map.

When UseStandardizedQueries is True:

• the DefintionExpression of a LayerDescription retrieved from IMapServerInfo.DefaultMapDescription is always empty regardless of whether a definition expression is set on the layer in the source map. Use IMapTableInfo3::DefinitionExpression, to find out what is the definition expression set, if there is any, to the layer in the source map.
• an expression set in the LayerDescription will be appened to the one set for the layer in the source map.
• you can only use StandardizedQueries. This means you will always  format a query on a date field the same way or if you want to find all features where the value in a string field contains a specified keyword, you can use the same function name regardless of the underlying database type. Queries containing anything specific to the underlying database, for example, a function that is only supported by the database but is not part of the StandardizedQueries specification will fail.

When UseStandardizedQueries is False:

• a layer can have a default definition expression that is set for that layer in the source map.
• an expression set in the LayerDescription will override the one set for the layer in the source map.
• the query must conform to the underlying database's syntax and use functions supported by that database.

Let's look at some examples. You have a layer in your map that represents sales regions. The layer includes fields: REGIONS, SALES and MANAGER.

Example #1: In the source map the layer has a definition query, "REGION=North". No DefintionExpression is specified in LayerDescription. Only those features where REGION=North will be displayed in your map.

Example #2: In the source map the layer has a definition query, "REGION=�North�". You apply a DefinitionExpression in LayerDescription as "SALES > 1000". The LayerDescription DefinitionExpression overrides the definition query set in the source map. Only those features where SALES > 1000 will be displayed in your map.

If you wish to use the DefinitionExpression as a way of getting a subset of the features already filtered by the definition query in the map you will need to save the original expression and then add it to the new expression to form one compound expression, �REGION=�North� AND SALES > 1000�. This will display map features that are belong to the North region and have sales over 1000.

Example #3: In the source map the layer has no definition query. You apply a DefinitionExpression in LayerDescription as "SALES > 1000". Only those features where SALES > 1000 will be displayed in your map.

The following MapServer methods will honor DefinitionExpression: Find, Identify, QueryFeatureCount2, QueryFeatureIds2, QueryFeatureData2 and QueryHyperlinks2.

Although the DefinitionExpression set in the LayerDescription will override any any definition query set in the source map, there are MapServer methods that only honor the expression set in the source document. Any expression set in DefinitionExpression in the LayerDescription will be ignored. These mothods include: QueryFeatureCount, QueryFeatureIds, and QueryFeatureData. MapDescription, which contains the LayerDescriptions, are not a parameter for these methods.

DefinitionExpression does not affect spatial extents.

See Also