Creating and using COM objects

You must use the cfobject tag or the CreateObject function to create an instance of the COM object (component) in ColdFusion before your application pages can invoke any methods or assign any properties in the component.

For example, the following code uses the cfobject tag to create the Windows CDO (Collaborative Data Objects) for NTS NewMail object to send mail:

<cfobject type="COM"

    action="Create"
    name="Mailer"
    class="CDONTS.NewMail">

The following line shows how to use the corresponding CreateObject function in CFScript:

Mailer = CreateObject("COM", "CDONTS.NewMail");

The examples in later sections in this chapter use this object.

Note: CDO is installed by default on all Windows NT and 2000 operating systems that have installed the Microsoft SMTP server. In Windows NT Server environments, the SMTP server is part of the Option Pack 4 setup. In Windows 2000 Server and Workstation environments, it is bundled with the operating system. For more information on CDO for NTS, see http://msdn.microsoft.com/library/default.asp?URL=/library/psdk/cdo/_olemsg_overview_of_cdo.htm.

The CDO for NTS NewMail component includes a number of methods and properties to perform a wide range of mail-handling tasks. (In the OLE/COM Object Viewer, methods and properties might be grouped together, so you could find it difficult to distinguish between them at first.)

The CDO for NTS NewMail object includes the following properties:

Body [ String ]

Cc  [ String ]
From  [ String ]
Importance  [ Long ]
Subject  [ String ]
To  [ String ]

You use these properties to define elements of your mail message. The CDO for NTS NewMail object also includes a send method which has a number of optional arguments to send messages.

Connecting to COM objects

The action attribute of the cfobject tag provides the following two ways to connect to COM objects:

Create method (cfobject action="Create") Takes a COM object, typically a DLL, and instantiates it prior to invoking methods and assigning properties.
Connect method (cfobject action="Connect") Links to an object, typically an executable, that is already running on the server.

You can use the optional cfobject context attribute to specify the object context. If you do not specify a context, ColdFusion uses the setting in the Registry. The following table describes the context attribute values:

Attribute value

Description

InProc

An in-process server object (typically a DLL) that is running in the same process space as the calling process, such as ColdFusion.

local

An out-of-process server object (typically an EXE file) that is running outside the ColdFusion process space but running locally on the same server.

remote

An out-of-process server object (typically an EXE file) that is running remotely on the network. If you specify remote, you must also use the server attribute to identify where the object resides.

Attribute value	Description
InProc	An in-process server object (typically a DLL) that is running in the same process space as the calling process, such as ColdFusion.
local	An out-of-process server object (typically an EXE file) that is running outside the ColdFusion process space but running locally on the same server.
remote	An out-of-process server object (typically an EXE file) that is running remotely on the network. If you specify `remote`, you must also use the `server` attribute to identify where the object resides.

Setting properties and invoking methods

The following example, which uses the sample Mailer COM object, shows how to assign properties to your mail message and how to execute component methods to handle mail messages.

In the example, form variables contain the method parameters and properties, such as the name of the recipient, the desired e-mail address, and so on:

<!--- First, create the object --->

<cfobject type="COM"
  action="Create"
  name="Mailer"
  class="CDONTS.NewMail">

<!--- Second, use the form variables from the user entry form to populate a number
    of properties necessary to create and send the message. --->
<cfset Mailer.From = "#Form.fromName#">
<cfset Mailer.To = "#Form.to#">
<cfset Mailer.Subject = "#Form.subject#">
<cfset Mailer.Importance = 2>
<cfset Mailer.Body = "#Form.body#">
<cfset Mailer.Cc = "#Form.cc#">

<!--- Last, use the Send() method to send the message.
  Invoking the Send() method destroys the object.--->
<cfset Mailer.Send()>

Note: Use the cftry and cfcatch tags to handle exceptions thrown by COM objects. For more information on exception handling, see "Handling runtime exceptions with ColdFusion tags," in Chapter 14.

COM object considerations

When you use COM objects, consider the following to prevent and resolve errors:

Ensure correct threading.
Use input and output arguments correctly.
Understand common COM-related error messages.

The following sections describe these issues.

Ensuring correct threading

Improper threading can cause serious problems when using a COM object in ColdFusion. Make sure that the object is thread-safe. An object is thread-safe if it can be called from many programming threads simultaneously, without causing errors.

Visual Basic ActiveX DLLs are typically not thread-safe. If you use such a DLL in ColdFusion, you can make it thread-safe by using the OLE/COM Object Viewer to change the object's threading model to the Apartment model.

If you are planning to store a reference to the COM object in the Application, Session, or Server scope, do not use the Apartment threading model. This threading model is intended to service only a single request. If your application requires you to store the object in any of these scopes, keep the object in the Both threading model, and lock all code that accesses the object, as described in "Locking code with cflock," in Chapter 15.

To change the threading model of a COM Object:

Open the OLE/COM Object Viewer.
Select All Objects under Object Classes in the left pane.
Locate your COM object. The left pane lists these by name.
Select your object.
Select the Implementation tab in the right pane.
Select the Inproc Server tab, below the App ID field.
Select the Threading Model drop down menu and select Apartment or Both, as appropriate.

Using input and output arguments

COM object method in arguments are passed by value. The COM object gets a copy of the variable value, so you can specify a ColdFusion variable without surrounding it with quotation marks.

COM object out method arguments are passed by reference. The COM object modifies the contents of the variable on the calling page, so the calling page can use the resulting value. To pass a variable by reference, surround the name of an existing ColdFusion variable with quotation marks. If the argument is a numeric type, assign the variable a valid number before you make the call. For example:

<cfset inStringArg="Hello Object">

<cfset outNumericArg=0>
<cfset result=myCOMObject.calculate(inStringArg, "outNumericArg")>

The string "Hello Object" is passed to the object's calculate method as an input argument. The value of outNumericArg is set by the method to a numeric value.

Understanding common COM-related error messages

The following table described some error messages you might encounter when using COM objects:

Error

Cause

Error Diagnostic Information Error trying to create object specified in the tag. COM error 0x800401F3. Invalid class string

The COM object is not registered or does not exist.

Error Diagnostic Information Error trying to create object specified in the tag. COM error 0x80040154. Class not registered

The COM object is not registered or does not exist. This error usually occurs when an object existed previously, but was uninstalled.

Error Diagnostic Information Failed attempting to find "SOMEMETHOD" property/method on the object COM error 0x80020006. Unknown name.

The COM object was instantiated correctly, but the method you specified does not exist.

Developing ColdFusion MX Applications with CFML
Integrating COM and CORBA Objects in CFML Applications