XmlFilter.FilterScalar Method (String, String)

XmlFilterFilterScalar Method (String, String)

Content Studio 5.7 SDK

Content Studio Web Content Management System

[This is preliminary documentation and is subject to change.]

Performs the filter operation against Content Studio EPT Xml index and returns the first document identifier that matches the filter condition and data from one field of that document.

Namespace: ContentStudio.Document.EPT
Assembly: CSServer5 (in CSServer5.dll) Version: 5.7.5016.0 (5.7.5016.0)

Syntax

Copy

public int FilterScalar(
	string fieldName,
	out string returnedFieldValue
)

Public Function FilterScalar ( 
	fieldName As String,
	<OutAttribute> ByRef returnedFieldValue As String
) As Integer

Parameters

fieldName: Type: SystemString
The name of an indexed EPT field that contains the data to retrieve. In order to be able to return any data in the returnedFieldValue the field must be indexed and be specified to return data. This parameter cannot be null or empty.
returnedFieldValue: Type: SystemString
When this method returns, if any match was found, this parameter contains the value if the field specified in the fieldName parameter, if no match could be found this parameter will be null (Nothing in Visual Basic). This parameter is passed uninitialized.

Return Value

Type: Int32
An Int32 that identifies the first matching document, zero if no match could be found.

Exceptions

Exception	Condition
ArgumentNullException	FieldName cannot be null or empty
InvalidOperationException	Cannot execute the Filter method without first initialize the connectionID and sessionID properties.
CSException	A business rule was violated in the underlying Content Studio database
SqlException	An error occurred when executing the command against the Content Studio database

Remarks

This method is optimized for returning one record only and has the following behavior

It temporarily sets the RangeSize and PageSize properties to 1 to optimize the query for one record only
The RecordCount and PageCount properties cannot be trusted after the call.

For queries that return multiple records, use the FilterReader method that returns a XmlFilterReader object for optimized read-only, forward only access to the data.

Examples

The following code sample shows how to use the FilterScalar method to the value of an inventory item in a fictive inventory system. In this system the InventoryNumber is always unique thus we can be sure that only one or none item exists that satisfies the criteria. In this case the FilterScalar method is optional to use.
Note
Note the usage of single quotation marks around the filter argument ([InventoryNo] = '234875'). Even though that the data to compare is an integer it is stored in the database as a string. In Sql Server it is possible to do an exact integer matching but this approach is not optimal for performance since Sql Server must implicitly convert the values to an integer before the comparison is done. In this case it is better to do a direct string comparison instead something that will return the same result.

Copy

//Define the category id to select from.
int CategoryId = 200;
//Create a new instance of the XmlFilter object.
try
{
  XmlFilter xfi = new XmlFilter(CS_ConnectionId, CS_UserSessionId, categoryID);
  //Add the field to return first (document id is always returned)
  xfi.AddField("ItemName", true);
  //Add a field to filter on
  xfi.AddField("InventoryNo", false);
  //Add a filter condition
  xfi.FilterCriteria = "[InventoryNo] = '234875'";
  //Get the name of this item and its document id
  string ItemName;
  int documentID = xfi.FilterScalar("ItemName", out ItemName);
  //Anything found?
  if(documentID != 0)
    Response.Write("Item " + ItemName + " found");
  else
    Response.Write("No item could be found");
}
catch (Exception ex)
{
  Response.Write("Error querying data. " + ex.Message);
}

'Define the category id to select from.
Dim CategoryId As Integer = 200;
'Create a new instance of the XmlFilter object.
Try
  Dim xfi As New XmlFilter(CS_ConnectionId, CS_UserSessionId, categoryID)
  'Add the fields to return first (document id is always returned)
  xfi.AddField("ItemName", True)
  'Add a field to filter on
  xfi.AddField("InventoryNo", False)
  'Add a filter condition
  xfi.FilterCriteria = "[InventoryNo] = '234875'"
  'Get the name of this item and its document id
  Dim ItemName As String
  Dim documentID As Integer = xfi.FilterScalar("ItemName", ItemName)
  'Anything found?
  If documentID <> 0
    Response.Write("Item " & ItemName & " found")
  Else
    Response.Write("No item could be found")
  End If
Catch ex As Exception
  Response.Write("Error querying data. " & ex.Message)
End Try

Reference

XmlFilter Class

FilterScalar Overload

ContentStudio.Document.EPT Namespace

XmlFilterFilter

XmlFilterFilterReader

XmlFilterFilterScalar