CFOBJECT and COM

Working with COM Objects and ColdFusion

You can call a COM object that resides either on your local machine or anywhere on your network; but before you can do so, you need to make sure the component you are trying to call is registered. To do this, you use the regsvr32 command from a Windows command prompt, like this:

C:\> regsvr32 someobject.dll

If a COM object has been registered on your machine, you can access it from CFOBJECT using this syntax:

<cfobject 
type="com" 
name="name" 
action="action" 
class="progID" 
context="context" 
server="your server name"

When you connect to a COM component, you need to set the CFOBJECT type attribute to COM . The name attribute is a reference variable and is also required. It is needed, as are other CFOBJECT calls, to provide a pointer to an object's attributes and methods.

class is a required attribute and points to the COM component's program ID for the object you want to invoke. You might have trouble finding the program ID, and if so, you should check the documentation for that component, which provides you with a list of its methods as well as the ProgramID. You can also use the OLE/COM Object Viewer that comes with Visual Studio or you can download it from www.microsoft.com/com/resources/oleview.asp.

The next attribute we have to deal with is the action attribute. This is a required attribute with two possible values: Create or Connect . Create takes a COM object and instantiates it prior to invoking methods and assigning properties, while Connect enables you to link/connect to a COM object (typically an executable) that is already running on the server. An example of the use of this type of object is a background service such as Net Stat.

The context attribute is an optional attribute that enables you to specify the context under which your object is running. Table 16.1 provides the various contexts.

Table 16.1. Context Attribute Values

The final attribute needed to call COM objects from CFOBJECT is server , which is required if the context attribute is set to remote . server simply specifics a valid server.

Properties and Methods

Any object has a series of methods and properties that you need to set and use. To set a property of a COM object, you only need to use the CFSET tag:

<cfset someobject.someproperty = "somevalue">

You can also access or get a property's value by doing this:

<cfset getProperty = someobject.someproperty>

To invoke a method with no arguments is just as simple:

<cfset variablename = someobject.somemethod()>

Methods that require arguments need to have those arguments passed by value:

<cfset somevar = 4> 
<cfset anothervar = someobject.somemethod (somevar, someOutput)

You can also pass arguments by reference. Arguments passed by reference have their values modified by the COM object 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 somestring="Print PI"> 
<cfset somenumeric=0> 
<cfset result=myCOMObject.calculate(somestring, " somenumeric ")>

The string "Print PI" is passed to the object's calculate method as an input argument. The value of somenumeric is set by the method to a numeric value.

Let's look at a real example. Let's pretend that we want to send out bulk mailings of special offers and other mail to our customers. To do this, we automate Microsoft Office to print a form letter with each of our customers, names and pertinent information. You can look at Microsoft's COM reference for Word on MSDN at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbawd10/html/wotocObjectModelApplication.asp.

Listing 16.9 mailmerge.cfm

<cfquery name="getCustomers" datasource="ICF" dbtype="ODBC"> 
SELECT Customer.CustomerID, Customer.CustomerFirstName, Customer.CustomerLastName, 
Customer.CustomerAddress, Customer.CustomerCity, Customer.CustomerStateID, 
Customer.CustomerZip, Customer.CustomerPhone, Customer.CustomerEmail, 
Customer.CustomerPassword, Customer.CustomerNotification 
FROM Customer, State 
</cfquery> 

<cftry> 

<!--- If it exists, connect to it ---> 

     <cfobject 
     action="Connect" 
     class="Word.Application"
 
     name="objWord" 
     type="COM"> 

<cfcatch> 
<!--- The object doesn't exist, so create it ---> 
     <cftry> 

     <cfobject 
     action="create" 
     class="Word.Application" 
     name="objWord" 
     type="COM"> 

     <cfcatch type="ANY"> 
     <cfabort showerror="<FONT COLOR='RED'>Cannot create Word Object<BR>Make sure Word 
     is installed and that ColdFusion has permissions to use the Word COM 
     objects</FONT><BR><B>Error Details:</B>  #CFCATCH.MESSAGE#"> 
     </cfcatch> 
     </cftry> 
</cfcatch> 
</cftry>   
<cfscript> 
/* This will open Word if running locally */ 
objWord.Visible = true; 
/* This returns the 'Documents' collection the Word Object */ 
objDoc = objWord.Documents; 
/* Create a new document */ 
newDoc = objDoc.Add(); 
</cfscript> 

<cfset strLoc = Application.DrivePath & "\temp\worddata.doc"> 
<!--- Delete file ---> 
<cfif FileExists('#Application.DrivePath#temp\worddata.doc')> 
      <cftry> 
      <cffile action="DELETE" FILE='#Application.DrivePath#temp\Worddata.doc'> 
      <cfcatch TYPE="Any"> 
      </cfcatch> 
      </cftry> 
</cfif> 
<cfscript> 
/* Save the document to a location */ 
newDoc.SaveAs(strLoc); 
 /* We specify the range of '0' -- start at the beginning of the document */ 
docRange = newDoc.Range(0); 
</cfscript> 

<cfset strtemp = ""> 
<!--- Loop through the query ---> 
<cfloop query="getCustomers"> 
<cfset i = getCustomers.CurrentRow> 
<cfset strtemp = strtemp & "#CustomerID#" & ","> 
<cfset strtemp = strtemp & "#CustomerFirstName#" & ","> 
<cfset strtemp = strtemp & "#CustomerLastName#" & Chr(13) & Chr(10)> 
</cfloop> 

<cfscript> 
/* Add text to the range */ 
docRange.Text = strtemp; 
 /* Save the changes */ 
newDoc.Save(); 
 /* Print document 
objWord.ActivePrinter = "HP LaserJet 6L on NE01:"; 
objWord.PrintOut();*/ 
 /* Close the document */ 
newDoc.Close(); 
 /* Quit Word */ 
objWord.Quit(); 
</cfscript>

Although this looks like a complicated template, it's really not. We connect to the Word object by specifying the class name "Word.Application" . Then we use a try-catch statement to see whether an instance of the object already exists and, if so, to connect to it. If not, we create an instance of it.

We then simply use the Word document's COM objects to add text to the created Word document.

Note

Before you get excited about automating your Office applications through ColdFusion and CFOBJECT , make sure to go to http://support.microsoft.com/default.aspx?scid=kb;EN-US;q257757. There you can read about some pitfalls and Microsoft's official view of automating Office applications.

Best Practices When Using COM Objects

Although using CFOBJECT and COM to create rich ColdFusion applications is easy, it is also easy to get yourself in trouble if you do not consider what you are doing. One of the main issues with calling COM objects from ColdFusion is improper threading. You must make sure that your COM object is thread-safe. If you do not, you might experience major issues under load and bring your server to its knees. 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 on storing a reference to the COM object in the application, session, or server scope, do not use the Apartment 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 model, and lock all code that accesses the object.

Summary

In this section, you have learned how to work with COM objects through CFOBJECT . You are provided with an invaluable tool to extend or rapidly add rich functionality to your ColdFusion applications. You can also use COM and CFOBJECT to provide a level of application integration between your ColdFusion web applications and sophisticated applications such as PeopleSoft and SAP, which provide extensive COM support.

It's important to note that although it is very simple and easy to work with COM from ColdFusion, there are risks and you need to read all the documentation on your COM object. You need to make sure it is thread-safe, or you must force it to be thread-safe through the OLE Object View application. Then you must rigorously test it before you use it in production.