Siebel Object Interfaces Reference > Interfaces Reference > Business Component Methods >

SetSearchSpec Method

SetSearchSpec sets the search specification for a particular field. This method must be called before ExecuteQuery.

Syntax

BusComp.SetSearchSpec FieldName, searchSpec

Returns

Not applicable

Usage

To avoid an unpredicted compound search specification on a business component, it is recommended to call ClearToQuery before calling SetSearchSpec. It is not necessary to use ActivateField on a field that is used in SetSearchSpec.

If multiple calls are made to SetSearchSpec for a business component, then the multiple search specifications are handled as follows:

• If the existing search specification is on the same field as the new search specification, then the new search specification replaces the existing search specification. For example:

  myBusComp.SetSearchSpec("Status", "<> 'Renewal'");
  myBusComp.SetSearchSpec("Status", "<> 'Dropped'");

  results in the following WHERE clause:

  WHERE Status <> 'Dropped'

• If the existing search specification is not on the same field as the new search specification, then the resultant search specification is a logical AND of the existing and the new search specifications. For example:

  myBusComp.SetSearchSpec("Type", "<> 'Renewal'");
  myBusComp.SetSearchSpec("Status", "<> 'Sold' AND [Status] <> 'Cancelled' AND [Status] <> 'Renewed'");

  results in the following WHERE clause:

  WHERE Type <> 'Renewal' AND (Status<> 'Sold' AND Status <> 'Cancelled' AND Status <> 'Renewed')

• If the existing search specification includes one or more of the same fields as the new search specification, then the new search specification on those common fields only replaces the existing search specification on the common fields. For example, if:

  myBusComp.SetSearchSpec("Status", "<> 'In Progress'")

  is subsequently applied to the result of the previous example, then the following WHERE clause results:

  WHERE Type <> 'Renewal' AND Status <> 'In Progress'

  Only the search specification on Status is replaced in the compound WHERE clause.

• If a search specification is set declaratively in Siebel Tools, and another search specification is set with script using SetSearchSpec(), then the resultant search specification is a logical AND of the existing Tools-created specification and the scripted specification. For example:

  myBusComp.SetSearchSpec("Status", "<> 'Cancelled'")

  is applied to the following existing search specification created declaratively in Tools:

  [Type] <> 'Renewal' AND [Status] <> 'Sold'

  Then the following WHERE clause results:

  WHERE Type <> 'Renewal' AND (Status <> 'Sold' AND Status <> 'Cancelled')

  NOTE:  When an existing Tools-created search specification includes the same field as a subsequent search specification set with SetSearchSpec(), the behavior is not like the replacement behavior that results when both specifications are set by using SetSearchSpec().

The maximum length of a predefined query is 2000 characters.

CAUTION:  Do not use SetSearchExpr and SetSearchSpec together because they are mutually exclusive.

Using logical and comparison operators. Any search specification that can be created in the user interface can be duplicated in Siebel VB or eScript. Both logical operators and comparison operators may be used, provided that they are handled correctly. For example, in VB:

BC.SetSearchSpec "Status", "<> 'Closed' AND ([Owner] = LoginName () OR [Refer To] = LoginName ()) OR ([Owner] IS NULL AND [Support Group] = 'TS-AE')"

Using special characters. If the search specification contains any of the following characters.

= > < ( ) , ~ " ' [

it must be enclosed in quotes. This rule applies to operators that are part of the search expression as well as text to search for. If the search expression contains quotes, those quotes must be doubled. For example, in the preceding line of code, notice that the entire search specification is enclosed in double quotes, whereas fields and values referred to within the specification each have single quotes.

If the search object includes a single double quote, that quote must be doubled; for example, if you wanted to search for text containing:

"We must

the VB search specification would take this form:

SetSearchSpec "Comments", "'""We must'"

so that the initial quote is doubled, and the string containing it is placed within single quotes, and the entire expression, including the single quotes, is placed within double quotes.

If the search specification includes single quotes (including apostrophes), the expression must be placed within single quotes, apostrophes must be doubled, and double quotes must be placed around the entire string. Thus, for example, if you wanted to search for "Phillie's Cheese Steaks" in the Name field, you would have to enter the specification in VB as follows:

SetSearchSpec "Name", "'Phillie''s Cheese Steaks'"

NOTE:  eScript and Browser Script require backslashes instead of double quotes for marking special characters. For example: SetSearchSpec("Comments", "\'\"We must\'"); and SetSearchSpec("Name", "\'Phillie\'\'s Cheese Steaks\'");

Searching for text in non-text fields. If the search expression queries a field of any type other than text, or if it is an expression other than a field-level query, text must be placed within quotes if it contains any characters other than the following:

ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz _ ? \ " ' [

As with text field search expressions, quotes must be doubled.

Retrieving all records. To retrieve all records efficiently, use ClearToQuery followed by ExecuteQuery, without using SetSearchSpec.

Searching for a null field. To search for null fields, use the following form:

SetSearchSpec "Account", "is NULL"

If your search specification requests an empty string, then the search returns every record. For example:

SetSearchSpec "Account", ""

Any dates used with SetSearchSpec must use the format MM/DD/YYYY, regardless of the Regional control panel settings of the server or client computer.

Used With

COM Data Control, COM Data Server, Java Data Bean, Mobile Web Client Automation Server, Server Script

Example

For Siebel VB examples, read FirstRecord Method, SetFormattedFieldValue Method, and BusComp_PreQuery Event. For a Siebel eScript example, read ClearToQuery Method.

Example

This Siebel VB code searches for a contact by name and then navigates to the record displayed in a view:

(general)
(declarations)
Option Explicit

Sub Button1_Click
Dim theCurrComp As BusComp
Dim TargetView As String
Dim TargetBusObj As String
Dim TargetBusComp As String
Dim NewBusObj As BusObject
Dim NewComp As BusComp
Dim RecId1 As String
Dim RecId2 As String
Dim RecId3 As String

TargetView = "Visible Contact List View"
TargetBusObj = "Contact"
TargetBusComp = "Contact"
Set theCurrComp = Me.BusComp
RecId1 = theCurrComp.GetFieldValue("Last Name")
RecId2 = theCurrComp.GetFieldValue("First Name")
RecId3 = theCurrComp.GetFieldValue("Account Id")
Set NewBusObj = TheApplication.GetBusObject(TargetBusObj)
Set NewComp = NewBusObj.GetBusComp(TargetBusComp)
NewComp.ClearToQuery
NewComp.SetSearchSpec "Last Name", RecId1
NewComp.SetSearchSpec "First Name", RecId2
NewComp.SetSearchSpec "Account Id", RecId3
NewComp.ExecuteQuery ForwardBackward

TheApplication.GotoView TargetView , NewBusObj

Set NewComp = Nothing
Set NewBusObj = Nothing
Set theCurrComp = Nothing

End Sub

The following example is in Siebel eScript:

var oAccntBO = TheApplication().GetBusObject("Account");
var oAccntBC = oAccntBO.GetBusComp("Account");
var oAddrBC;

with (oAccntBC)
{
   SetViewMode(SalesRepView);
   ClearToQuery();
   SetSearchSpec("Name", "Hong Kong Flower Shop");
   ExecuteQuery(ForwardBackward);

   if (FirstRecord())

oAddrBC = GetMVGBusComp("Street Address");
with (oAddrBC)
{
   NewRecord(NewAfter);
   SetFieldValue("City", "Denver");
   SetFieldValue("Street Address", "123 Main Street");
   WriteRecord();
}

}

oAddrBC = null;
oAccntBC = null;
oAccntBO = null;

Related Topics

ExecuteQuery Method
ClearToQuery Method
SetSearchExpr Method
SetSortSpec Method