Siebel Object Interfaces Reference > Programming > Siebel Object Interface Events and Siebel Extension Events >

How Your Script Affects Program Flow

For every Siebel operation event handler, there is also a preoperation event handler. Generally, scripts are placed in the preoperation event. You can alter the effect of an event by attaching a script to the preoperation event handler. The events with the most important effects are the PreInvokeMethod events. In a PreInvokeMethod event, you can call a method that substitutes for the internal Siebel code.

You can change the outcome of an event by specifying the return value on the preoperation events. The standard return value for preoperation events is ContinueOperation, which tells the calling Siebel object to continue processing the remaining operations associated with the event.

If you wish to create an alternative to an existing routine, change the return value in your custom event handler to CancelOperation. This tells the Siebel application to cancel the remaining operations associated with the event. If, for example, the validation in the PreDeleteRecord event fails, set the return value for the event to CancelOperation. If you want to preprocess before the default event method executes, use the return value ContinueOperation.

The post-event handler is rarely scripted, but you may use it for such post-operation events as posting a notice to a log when the event completes successfully.

CAUTION:  You must use CancelOperation with custom methods. If you do not, the code flow would continue to the C++ code, which does not have the ability to handle the custom method, and would therefore throw an "Unknown method name" error. For more information on the differences in handling standard and custom methods, see Figure 7.

The following eScript example sets up a validation routine in which a specific field is queried to determine whether the event should fire:

function BusComp_PreSetFieldValue (FieldName, FieldValue)
{
   var iReturn = ContinueOperation;
   //Routine to check if a quote discount > 20%
   //if it is, notify user and cancel the operation
   var varvalue;
   var msgtext;
   if (FieldName == "Discount")
   {
      varvalue = ToNumber(FieldValue);
      if (varvalue > 20)
      {
         msgtext = "Discounts greater than 20% must be approved";
         TheApplication().RaiseErrorText(msgtext); // cancels execution
      }
      else
      {
         iReturn = ContinueOperation;
      }
   }
}

The following Siebel VB example sets up a validation routine in which a specific field is queried to determine whether the event should fire:

Function BusComp_PreSetFieldValue (FieldName As String,
               FieldValue As String) As Integer
' Routine to check if a quote discount > 20%
'       if it is, notify user and cancel the operation
Dim value as Integer
Dim msgtext as String
   If FieldName = "Discount" then
      value = Val(FieldValue)
      If value > 20 then
          msgtext = "Discounts greater than 20% must be approved"
         TheApplication.RaiseErrorText msgtext ' cancels execution
      Else
         BusComp_PreSetFieldValue = ContinueOperation
       End if
End If
End Function

Note the logical structure of this routine:

If (condition is true)
   [perform custom routine]
   [cancel operation by raising error text]
Else
   returnValue = ContinueOperation
End If

Within this structure, the custom routine is executed only if the condition is true. If the condition is true, the custom routine substitutes for the built-in routine. If it is not true, the built-in routine is executed because the event handler returns ContinueOperation.

The following alternative structure is also acceptable:

returnValue = ContinueOperation
If (condition is true)
   [perform custom routine]
End If

Note that in PreInvokeMethod events, the condition should always be a test for the method name; for example in Siebel eScript:

if (methodName == "PushOpportunity")

If more than one method may be invoked, you may find it more efficient to use a Select structure (in Siebel VB) or a switch structure (in Siebel eScript). The following example is in Siebel VB:

Dim iReturn As Integer
iReturn = ContinueOperation
Select Case methodName
   Case "PushOpportunity"
      [custom routine]
      iReturn = CancelOperation
   Case "Stage3"
      [custom routine]
      iReturn = CancelOperation
End Select
object_PreInvokeMethod = iReturn

The following example is in Siebel eScript:

var iReturn;
switch (methodName)
{
   case "PushOpportunity":
      //[custom routine]
      iReturn = CancelOperation;
      break;
   case "Stage3":
      //[custom routine]
      iReturn = CancelOperation;
      break;

   default:
      iReturn = ContinueOperation;
}
return (iReturn);

To make your code easier to read and maintain, you can create the custom routines as subprograms or functions in the (general) (declarations) section.