Example 4: Sending a Mail

This example shows how travel guides are automatically notified by email whenever they are scheduled on a particular scheduled tour.

Technically, the email is sent when the record is stored (at record validation), since this is when the Rules Engine processes transitional multi-record constraints. If a rollback subsequently occurs, the mail action cannot be revoked. If you want to tie the mail action more closely to the commit event, you can present the user with a confirmation dialog at commit time, or you can flag the record and invoke the component later on the basis of the flag, or process mailing through a separate batch job in a separate transaction.

The example uses the Travel Agency case (Expanded Version).

To try out this example:

•Locate the Samples/Usmail directory on your CD.

•Read the README.TXT file for information on installing, running and inspecting the sample component.

Component

USMAIL

Component Prog ID

UsMail.Class1

Method

SEND_MAIL_EXE

Physical Method

send

Parameters of SEND_MAIL_EXE

1, In, String

2, In, String

3, In, String

4, Return, Long Integer

Query Protocol

Component Name = USMAIL

Protocol Name = SEND_MAIL

Exe Method Name = SEND_MAIL_EXE

Constraint

SEND_EMAIL

Transition Table: SCHEDTOUR

Alias: S

Fire on Insert: Always

Fire on Delete: Always

Fire on Update: Used Columns

INVOKE    usmail.send_mail    /* email address, subject, message-text */

WITH

SELECT    

p.email,

   'Tour guide',

   'Dear ' || p.first_name ||

',

With this mail we would like to inform you that we have scheduled you as a guide on a tour to ' || s.destination || '.

Please contact the office as soon as possible for details.

Kind regards,

The Travel Agency.

'

FROM    person    p,

   schedtour    s

WHERE    s.guide = p.person_id

AND    p.email is not null

AND    ( s.guide != old(s.guide)

     or old(s.guide) is null

   )

Description of functionality:

The component sends an email message to a Microsoft Exchange account using Microsoft's standard MAPI component. The recipient account depends on the input parameters of the INVOKE. The component then returns 0 (no violation) if the operation concludes normally, or -1 if an error occurs.

Visual Basic code of subprogram directly invoked by USoft:

Const USOFT_STATUS_VIOLATION = 1

Const USOFT_STATUS_NO_VIOLATION = 0

Const USOFT_STATUS_ERROR = -1

Public Function send(address As String, _

                       Optional subject As String, _

                       Optional text As String, _

                       Optional password As String, _

                       Optional profile_name As String, _

                       Optional silent As Boolean) _

                       As Long

  ' Initialize this function to return a violation

  send = USOFT_STATUS_VIOLATION

  Dim objSession As Object

  Dim objMessage As Object

  On Error GoTo on_error

  ' Apply defaults for optional arguments

  If IsNull(silent) Then

     silent = False

  End If

  ' Create a objSession

  Set objSession = newSession(profile_name:=profile_name, _

                                password:=password, _

                                no_mail:=False)

  ' Create a new message

  Set objMessage = newMessage(objSession, address)

  If Not IsNull(subject) Then

     objMessage.subject = subject

  End If

  If Not IsNull(text) Then

     objMessage.text = text

  End If

  objMessage.Recipients.Resolve

  objMessage.send

  If Not silent Then

     MsgBox "Email successfully sent to " & address & "."

  End If

  cleanUp objSession, objMessage

  send = USOFT_STATUS_NO_VIOLATION

  Exit Function

on_error:

  If Not ignoreError() Then

     showError "send"

     send = USOFT_STATUS_ERROR

  End If

  cleanUp objSession, objMessage

End Function