Creating Transactional Components

In this section, we'll create a server-side component using Visual Basic 6.0 and then place it under MTS control. We'll then create an ASP Web page to call the component, and we'll see how the ASP Web page and the component can work together in a single transaction.

Creating a Transactional Component

For our transactional component, we'll create an ActiveX dynamic-link library (DLL) project in Visual Basic 6.0 and define a class with one method—the Transaction class with the CommitOrAbort method—as shown in the following code.

 ' Filename: transaction.cls (mts_example.vbp) ' ' Description:  Transaction Class ' ' This file is provided as part of the "Programming Visual  ' InterDev 6.0" CD-ROM. ' ' THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT ' WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, ' INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES ' OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR ' PURPOSE. ' ' Copyright (C) 1998 Microsoft Corporation. All rights reserved Option Explicit Public Function CommitOrAbort(ByVal TransType As Integer)     Dim strResult As String          On Error GoTo ErrorHandler          Dim ctxObject As ObjectContext     Set ctxObject = GetObjectContext()          ' Take the appropriate action based on the TransType code.     If TransType = 1 Then         ' Commit         ctxObject.SetComplete         CommitOrAbort = "Committed"     Else         ' Abort         ctxObject.SetAbort         CommitOrAbort = "Aborted"     End If      Exit Function ErrorHandler:          ctxObject.SetAbort          CommitOrAbort = "Aborted" ' Indicate that an error occurred.          Err.Raise Err.Number, "MtsExample.Transaction.CommitOrAbort", _         Err.Description      End Function 

The CommitOrAbort method takes an integer as input and then explicitly commits or aborts the transaction based on the input. If the value of the TransType variable is 1, it will commit; otherwise, it will abort. The method also returns a text string to the calling program describing the action that took place.

You'll notice that the method gets its current context by calling the GetObjectContext function. The context is stored in a ContextObject object variable named ctxObject. To commit the transaction, the method calls ctxObject.SetComplete, and to abort the transaction, it calls ctxObject.SetAbort.

The code for this example is contained on the CD-ROM under the transactions/VB98 folder in a Visual Basic 6.0 project named mts_example.vbp. After opening this project file, you should see a screen similar to that shown in Figure 20-1.

Figure 20-1. The Visual Basic 6.0 development environment showing the transaction.cls class module within the mts_example.vbp project.

If you are creating your own Visual Basic 6.0 ActiveX DLL project, make sure that the References dialog box includes a reference to the Microsoft Transaction Server Type Library, as shown in Figure 20-2. You'll also want to go into the Project Properties dialog box (by choosing Properties from the Project menu) and mark the project for Unattended Execution. In the case of our example project, both of these settings are already stored in the project file on the CD-ROM. To compile an ActiveX DLL for your project, simply choose Make from the File menu.

Figure 20-2. Visual Basic 6.0 References dialog box showing the reference to the Microsoft Transaction Server Type Library.

After compiling the project to make an ActiveX DLL (mts_example.dll), you'll need to install it within MTS. You can install it using the Transaction Server Explorer to create a package and then using the Component Wizard to import the already registered component. Alternatively, you can take the DLL that is supplied on the CD-ROM and choose the Install New Component option from the Component Wizard. Figure 20-3 shows the MTS Example package within the Transaction Server Explorer. For more detailed information on how to create packages and install components into MTS, see the section "Deploying Transactional Components."

For an MTS component to be transactional, it needs to have its transaction attribute defined within the Transaction Server Explorer. You can do this by right-clicking the component and choosing Properties. Next choose the Transaction tab, and select the Requires A Transaction radio button in the Transaction Support group box. Finally, choose OK and you're done—your transactional component has been installed into MTS.

Figure 20-3. The MTS Example package within the Transaction Server Explorer.

Calling the Transactional Component from ASP

To call a transactional component from an ASP Web page, you simply use the Server.CreateObject syntax to instantiate the object and then you can reference its methods. Here is an example:

 <% Dim myObject Set myObject = Server.CreateObject("mtsexample.transaction") rtnString = myObject.CommitOrAbort(TransVal) Response.Write "Return status is '" +  rtnString + "'.<p>" %> 

To continue our transactional component example, we'll look at an HTML page and an ASP Web page. The HTML page allows you to specify the action the component should take: whether it should commit or abort. The ASP Web page captures this input (sent via an HTML form) and sends the appropriate code to the CommitOrAbort method of the mtsexample.transaction component. The ASP Web page displays both the resulting status returned from the component and the final status of the entire transaction.

The code beginning below shows the cmp_trans.htm page, which is in the transactions/VIntDev98 folder on the CD-ROM.

 <HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0"> <TITLE>Simple Transactional Web Page Using ASP and Components</TITLE> </HEAD> <BODY BGCOLOR="White" topmargin="10" leftmargin="10"> <!-- Display Header --> <font size="4" face="Arial, Helvetica"> <b>Simple Transactional Web Page Using ASP and Components</b> </font><br>         <hr size="1" color="#000000"> <!-- Brief Description Blurb --> This is a simple example demonstrating the basic structure of a transacted Web page using ASP and components. <p> The ASP Web page calls the CommitOrAbort method in the mtsexample.transaction component. You can make this  component either commit or abort by specifying the action to take on the cmp_trans.htm page. <p> <!-- HTML Form so you can make the component either  commit or abort --> Specify whether you would like the mtsexample.transaction  component to either commit or abort, and then click  the Submit button. <FORM METHOD=POST ACTION="cmp_trans.asp"> <TABLE> <TR> <TD><input type="radio" checked name="TransFlg"  value="Commit">Commit</TD> </TR> <TR> <TD><input type="radio" name="TransFlg" value="Abort">Abort</TD> </TR> <TR> </TR> <TR> <TD> <INPUT type="submit" name="Submit" value="Submit"> </TD> </TR> </TABLE> </FORM> <p> </BODY> </HTML> The cmp_trans.htm page simply sends the value of the currently  selected radio button ("Commit" or "Abort") to the  cmp_trans.asp page via an HTML form. The following code shows the cmp_trans.asp page. <%@ TRANSACTION=Required LANGUAGE="VBScript" %> <HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0"> <TITLE>Simple Transactional Web Page Using ASP and Components</TITLE> </HEAD> <BODY BGCOLOR="White" topmargin="10" leftmargin="10"> <!-- Display Header --> <font size="4" face="Arial, Helvetica"> <b>Simple Transactional Web Page Using ASP and Components</b> </font><br> <hr size="1" color="#000000"> <!-- Brief Description Blurb --> This is a simple example demonstrating the basic structure of a transacted Web page using ASP and components.  <p> The ASP Web page calls the CommitOrAbort method in the mtsexample.transaction component. You can make this  component either commit or abort by specifying the action to take on the cmp_trans.htm page. <p> <!-- Find out whether the users want to commit or abort. --> <% If Request.Form("TransFlg") = "Commit" Then     TransVal = 1 Else     TransVal = 0 End If %> <!-- Instantiate the transaction component, and      call the CommitOrAbort method. --> <%  Dim myObject Set myObject = Server.CreateObject("mtsexample.transaction") rtnString = myObject.CommitOrAbort(TransVal) Response.Write "The component transaction status is '" +  _     rtnString + "'.<p>" %> </BODY> </HTML> <%     ' The Transacted Script Commit Handler. This subroutine     ' will be called if the transacted script commits.     Sub OnTransactionCommit()         Response.Write "<p><b>The transaction just committed</b>."          Response.Write "This message came from the "         Response.Write "OnTransactionCommit() event handler."     End sub     ' The Transacted Script Abort Handler. This subroutine     ' will be called if the transacted script aborts.     Sub OnTransactionAbort()         Response.Write "<p><b>The transaction just aborted</b>."          Response.Write "This message came from the "         Response.Write "OnTransactionAbort() event handler."     End sub %> 

Notice in the code above that the value from the HTML form is obtained using the Form method of the Request object, as follows:

 Request.Form("TransFlg") 

The mtsexample.transaction component is instantiated using the Server.CreateObject syntax, and the CommitOrAbort method is called with the TransFlg variable passed along as a parameter. Finally the ASP Web page prints out the return status from the CommitOrAbort method. When you run this page within your browser, after first choosing "Commit" from the HTML page, you'll see the resulting output, as shown in Figure 20-4.

Figure 20-4. Output from the cmp_trans.asp page after selecting to commit the transaction.

You'll also notice from Figure 20-4 that the transaction as a whole completed successfully. Because the component's transaction was successful (that is, it fired the SetComplete method), the ASP Web page was able to capture the event in its OnTransactionCommit event handler. If you look at the Transaction Statistics within the Transaction Server Explorer, you'll see just one transaction for this entire process.

If you choose the Abort radio button from the HTML page, you see that the entire transaction aborts. The ASP Web page captures the event using the OnTransactionAbort event.

Using the Built-In ASP Objects from the Context Object

Within your Visual Basic server-side components, you can also use the context object to access the built-in ASP objects of Microsoft Internet Information Server (IIS). These are the Request, Response, Server, Session, and Application objects.

You can do this by using the Item method of the context object. The following example retrieves the value of the server name from the ServerVariables collection of the Request object. In the example below, oc is the object variable for the context object.

 Dim oc As ObjectContext Set oc = GetObjectContext() oc("Request").ServerVariables("SERVER_NAME") 

The ability to access the built-in ASP objects from within a server-side Visual Basic component yields some interesting possibilities. For example, you can actually write output to the browser from your component—you don't have to return the output to your ASP code for processing. The following code shows you an example.

 ' Filename: asp.cls (mts_example.vbp) ' ' Description:  ASP Class ' ' This file is provided as part of the "Programming Visual ' InterDev 6.0" CD-ROM. ' ' THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT ' WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, ' INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES ' OF MERCHANTABILITY AND/OR FITNESS FOR A  PARTICULAR ' PURPOSE. ' ' Copyright (C) 1998 Microsoft Corporation. All rights reserved Option Explicit Public Function BuiltInAsp() As String     Dim strResult As String          On Error GoTo ErrorHandler            ' Get the context object.     Dim oc As ObjectContext     Set oc = GetObjectContext()          ' Print some text to the browser using the Response object.     oc("Response").Write "<p>Here's some text from " & _         "the Visual Basic component!</p>"          ' Print the server name using the Request object.     oc("Response").Write "<p>Server Name: " & _         oc("Request").ServerVariables("SERVER_NAME") & "</p>"              ' Print the user's first name using the Request object.     oc("Response").Write "<p>First Name: " & _         oc("Request").Form("FirstName") & "</p>"          oc.SetComplete          BuiltInAsp = "Committed"          Exit Function ErrorHandler:          oc.SetAbort          BuiltInAsp = "Aborted" ' Indicate that an error occurred.          Err.Raise Err.Number, "MTSExample.ASP.BuiltInAsp", _         Err.Description      End Function 

The code for this example is contained on the CD-ROM under the transactions/VB98 folder in the Visual Basic 6.0 project named mts_example.vbp. This is the same project file that we looked at earlier in the chapter. The code is just stored in a class named ASP instead of in the previous class named Transaction.

You'll see from the code that there's a lot you can do by accessing the ASP built-in objects. The code uses the Write method of the Response object to send output to the browser. It prints a simple line of text, the server name from the Request object, and finally the value of the FirstName variable from an HTML form.

To run this example, you should choose the cmp_built-in.htm file from the transactions/VIntDev98 folder. This file captures the user's first name and then calls cmp_built-in.asp. The ASP file calls the BuiltInAsp method shown in the preceding code. You'll also want to install the mtsexample.asp component into MTS using the Transaction Server Explorer.

Notice that there's nothing significant about the names of these files or the names of the methods. They are just examples meant to demonstrate how to access the ASP built-in objects from within a server-side component. Figure 20-5 shows the output from this example as viewed within the browser. You'll notice that both the ASP Web page and the component are part of a transaction once again.

Figure 20-5. Output from the cmp_built-in.asp page after entering "Baby David" for the user's first name in the cmp_built-in.htm page.

An Overview of Transactional C/C++ Components

Working with transactions and the context object from C/C++ components is similar to Visual Basic—the syntax is just slightly different.

The IObjectContext interface provides access to the current object's context. You obtain a reference to the IObjectContext interface by calling the GetObjectContext function. As with any COM object, you must release an ObjectContext object when you're finished using it.

The IObjectContext interface exposes the following methods:

• CreateInstance
• DisableCommit
• EnableCommit
• IsCallerInRole
• IsInTransaction
• IsSecurityEnabled
• SetAbort
• SetComplete

These methods provide the same functionality as they do in Visual Basic. You'll notice that there is no Item method, as there is for Visual Basic. The Item method enabled us to access the ASP built-in objects and other context object properties. To do this within C/C++ components, you can use the IGetContextProperties interface. This interface has a method called GetProperty.

The IGetContextProperties interface also has a method named Count that returns the number of context object properties and a method named EnumNames that returns a reference to an enumerator that you can use to iterate through all the context object properties. You use the EnumNames method to obtain a reference to an enumerator object. The returned IEnumNames interface exposes several methods you can use to iterate through a list of BSTRs representing context object properties. Once you have a name, you can use the GetProperty method to obtain a reference to the context object property it represents.