SetSearchSpec Method for a Business Component

The SetSearchSpec method sets the search specification for a business component. This method does not return any information.

Caution: Do not use the SetSearchExpr method and the SetSearchSpec method together. They are mutually exclusive.

Format

BusComp.SetSearchSpec FieldName, searchSpec

The following table describes the arguments for the SetSearchSpec method.

Argument	Description
FieldName	String that identifies the name of the field where Siebel CRM sets the search specification.
searchSpec	String that contains the search specification.

Usage

You must call the SetSearchSpec method before you call the ExecuteQuery method.

To avoid an unexpected compound search specification on a business component, it is recommended that you call the ClearToQuery method before you call the SetSearchSpec method. It is not necessary to use the ActivateField method on a field that you reference in the SetSearchSpec method.

Making Multiple Calls to the SetSearchSpec Method

If you instruct Siebel CRM to make multiple calls to the SetSearchSpec method for a business component, then it handles the multiple search specifications in the following ways:

If the existing search specification is on the same field as the new search specification, then Siebel CRM replaces the existing search specification with the new search specification. For example, consider the following code:
```
myBusComp.SetSearchSpec("Status", "<> 'Renewal'");
myBusComp.SetSearchSpec("Status", "<> 'Dropped'");
```
This code 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 Siebel CRM creates a search specification that 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'");
```
This code 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 Siebel CRM replaces only that part of the existing search specification that includes fields that the new search specification also includes. For example:
```
myBusComp.SetSearchSpec("Status", "<> 'In Progress'")
```
This code results in the following WHERE clause:
```
WHERE Type <> 'Renewal' AND Status <> 'In Progress' 
```
Siebel CRM replaces the search specification only on the Status field.

Combining Declarative and Scripted Search Specifications

If you define a search specification declaratively in Siebel Tools, and if you use the SetSearchSpec method to define another search specification in script, then Siebel CRM creates a search specification that is a logical AND of the declarative search specification and the scripted search specification. For example, consider the following scripted search specification:

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

Consider the following declarative search specification:

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

When Siebel CRM creates a logical AND between these search specifications, the following WHERE clause results:

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

Using Logical and Comparison Operators in a Search Specification

You can use logical operators and comparison operators. Consider the following example, in Siebel VB:

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

Using Special Characters in a Search Specification

The search specification can contain any of the following special characters:

" (double quote)
' (single quote)
= (equal sign)
> (greater than symbol)
< (less than symbol)
( (opening parenthesis)
) (closing parenthesis)
[ (opening square bracket)
[ (closing square bracket)
, (comma)
~ (tilde)

You must enclose each of these special characters in quotes. This rule applies to operators that are part of the search expression and to the search text.

Using Quotes and Other Characters in a Search Specification

If the search expression contains quotes or another special character, then you must enclose the entire search specification in double quotes. An apostrophe is an example of a special character.

If the search object includes a special character, then you must double that character. For example, assume your specification must search for text that contains a single double quote:

"We must

In this situation, you must do the following work:

Use two double quotes before the word We:
```
""We must
```
Enclose the string you created in the preceding step with single quotes:
```
'""We must'
```
Enclose the entire expression in double quotes:
```
"'""We must'"
```
Add the expression to the search specification:
```
SetSearchSpec "Comments", "'""We must'"
```

In another example, assume your search specification must search for the following text in the Name field:

Phillie’s Cheese Steaks

In this situation, you must use the following search specification:

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

Using Quotes and Other Characters in a Search Specification in Siebel eScript or Browser Script

To mark a special character in Siebel eScript or Browser Script, you must use a backslash instead of a double quote. For example:

To include double quotes before the word We, you must use the following format:
```
SetSearchSpec("Comments", "\'\"We must\'")
```

To include the string Phillie’s Cheese Steaks, you must use the following format:
```
SetSearchSpec("Name", "\'Phillie\'\'s Cheese Steaks\'")
```

Using a Search Specification to Search Text in a Nontext Field

If any of the following situations are true, then you must use double quotes to enclose the text you use in a search specification:

The search expression queries a field of any type other than a text field.
The search expression includes any character that is not included in the following list:
- Any upper-case letter of the alphabet. For example:
  ABCDEFGHIJKLMNOPQRSTUVWXYZ
- Any lower-case letter of the alphabet. For example:
  abcdefghijklmnopqrstuvwxyz
- Any of the following special characters:
  - underscore (_)
  - question mark (?)
  - back slash (\)
  - double quote (")
  - single quote (')
  - opening bracket ([)
  - closing bracket (])

Using a Search Specification to Return All Records

To return all records, use the ClearToQuery method and then the ExecuteQuery method. Do not use the SetSearchSpec method. For more information, see ClearToQuery Method for a Business Component and ExecuteQuery Method for a Business Component.

Using a Search Specification to Search for a Null Field

To search for a null field, 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", ""

Used With

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

Examples

The following Siebel VB code searches for a contact by name, and then navigates to a view that displays this record:

(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

For other Siebel VB examples, see FirstRecord Method for a Business Component, SetFormattedFieldValue Method for a Business Component, and BusComp_PreQuery Event.

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;

For another Siebel eScript example, see ClearToQuery Method for a Business Component.