19.3 Using Automation Objects

In this section, we're going to explore automation objects by building a simple progam that sends a message using Microsoft's Active Messaging Library. If you don't have Active Messaging (if you have MAPI, you probably have it) on your system, you can still follow the concepts, which are generally applicable to using automation. Remember, though, that the specific methods, properties, and objects that a server exposes are specific to that server. To learn more about Active Messaging, try the Microsoft MSDN[2] web site at www.microsoft.com/msdn/sdk/ and look for the for Active Messaging Library documentation. The Active Message Library is a complex API that provides complete services for messaging, message stores, providers, transports, and more; but we're just going to touch on the basics of sending a message here.

[2] Microsort Developer Network - you might also have it on CD, if you're a Win32 programmer and subscribe to MSDN.

The first thing we need to do is to create a Active Messaging session. This happens to be the top-level automation object for our purposes, so we'll start here with CreateObject:

use OLE;
$ActiveSession = CreateObject OLE "MAPI.Session" || 
        die "CreateObject: $!";

The ProgID for the Active Messaging Session object is MAPI.Session, so that's the argument that we give to CreateObject. After we have an Active Messaging session, we need to logon. Active Messaging provides a couple of options for doing this. If you don't supply a valid username/password combination, you'll get a logon dialog that lets you supply a user and password:

$LogonName = "Erik Olson";
$LogonPasswd = undef; # use stored one, or prompt
die "Logon: $!" if $ActiveSession->Logon($LogonName, 
        $LogonPasswd); # Logon returns 0 on success

Here, we're calling the Logon method of the Active Messaging Session object. Because Logon returns 0 on success, we are only dying if we get a return value (indicating an error code). If we successfully logon to the Active Messsaging session, we're ready to create a Message object. A message object is another automation object that (appropriately enough) encapsulates a message. For example:

$Message = $ActiveSession->Outbox->Messages->Add();

Now, things are starting to get interesting. We're using the $ActiveSession object to call a method named Outbox that returns an automation object (the Outbox object). We're then calling a method of the Outbox object called Messages that returns another automation object (the Message object). We're then calling a method of the Message object named Add that returns yet another automation object, which we're assiging to our $Message variable. Perl lets you merrily create as many nested automation objects as you need.

Now that we have a Message object, we can start doing things with the message. First, we need to add a recipient. This involves another nested automation-object call:

$Recipient = $Message->Recipients->Add();

Here we're calling the Recipients method of the message object that returns a recipients object. We then call the Add method of the recipients object to get a Recipient object that we can use. Let's set some properties of the recipient object:

$Recipient->{Name} = "Erik Olson"; # to address
$Recipient->{Type} = 1; # ugly constant, means this is a To address

We've set the Name property of the Recipient object by setting the property using the object's hash. As for that assignment to the Type property, we've set it to 1, which is the Active Messaging value for a TO recipient (as opposed to a CC or BCC recipient). Table 19.1 displays the values for the recipient types.

After setting the recipient information, we need to resolve it to a name in the Active Messaging address book. We do this by calling the Resolve member of the Recipient object:

$Recipient->Resolve();

Now that we know where our message is going, let's add some data to it. We need at least a subject and a body, both of which are properties of the Message object.

$Message->{Subject} = "A Message From Perl";
$Message->{text} = "Perl does automation!";

All that remains is to save the message, send it, and terminate our session:

$Message->Update();
$Message->Send(1, 0, 0);
$Message->Logoff();

We call the Update method of the message object to save it, then the Send method to actually send the message. The parameters to Send are shown in Table 19.2.

Let's put everything together:

use OLE;
$LogonName = "Erik Olson";         # send message to me
$LogonPasswd = undef;              # use stored passwd
$ActiveSession = CreateObject OLE "MAPI.Session" || 
        die "CreateObject: $!";    # create session
die "Logon: $!" if $ActiveSession->Logon($LogonName, 
        $LogonPasswd);             # logon (returns 0 on success)
$Message = $ActiveSession->Outbox->Messages->Add();
$Recipient = $Message->Recipients->Add();
$Recipient->{Name} = "Erik Olson"; # to address
                            # ugly constant, means this is a To address
$Recipient->{Type} = 1; 
$Recipient->Resolve();             # resolve name - hope it's there
$Message->{Subject} = "A Message From Perl";
$Message->{text} = "Perl does automation!";
$Message->Update();                # save it
$Message->Send(1, 0, 0);           # send it - don't show UI
$ActiveSession->Logoff();          # end session

use OLE;
$conn = CreateObject OLE "ADODB.Connection" || 
        die "CreateObject: $!";    # create ADO auto object
$conn->Open('OLE_DB_NWind_Jet');   # connect to data source
$sql = "SELECT * FROM Employees ORDER BY LastName, FirstName";
$rs = $conn->Execute($sql);        # grab all records in table
while(!$rs->EOF()) {
    $lastname = $rs->Fields('LastName')->Value;
    $firstname = $rs->Fields('FirstName')->Value;
    $empid = $rs->Fields('EmployeeId')->Value;
    write;                         # print them out
    $rs->MoveNext();
}

$rs->Close();                      # shut down the recordset
$conn->Close();                    # close the data source
# some formats for a quick printout
format STDOUT =
@<<<<<      @<<<<<<<<<<<<<<<<<<<   @<<<<<<<<<<<<<<<<<<<<<<<<
$empid,     $firstname,            $lastname
.
format STDOUT_TOP =
Page @<<
$%
ID          First                  Last
=====       ====================   =========================
.

use OLE;
$firstname = "Homer";             # hardcode some values to insert
$lastname = "Simpson";
$empid = "3001";
$conn = CreateObject OLE "ADODB.Connection" || 
        die "CreateObject: $!";   # create the ADO object
$conn->Open('OLE_DB_NWind_Jet');  # connect to the data source
# build a simple SQL INSERT
$sql = "INSERT into Employees (LastName, FirstName, EmployeeID)";
$sql .= "VALUES ('$lastname', '$firstname', '$empid')";
$conn->Execute($sql);             # run it
$conn->Close();