COM/MTS Guide

A COM component built in the Panther editor consists of a DLL file, a Panther service component, and possibly a type library, all having the same name. Once these files are available, the COM component can be deployed on:

• Windows workstation running COM or DCOM.

• Windows 2003 servers or later running COM, DCOM, or MTS.

Steps for Deployment

In order to make a COM component available in a Panther application:

• The COM component's DLL must reside on the server machine. If the DLL does not contain the type library definition, the type library must also be present.

• The Panther application library containing the service component must be available.

• The Panther DLLs must be in the system PATH.

• The COM component must be registered.

Create an Application Directory

Since the DLL for the COM component and the Panther application library containing the service component are typically located in the same directory, create an application directory and copy the following files to this directory:

• The application library containing the Panther service components. The default library is named server.lib.

• The COM components' DLLs.

Changing the Library Name

When the COM component is instantiated, Panther looks for a service component matching that name in an application library named server.lib. That library must be located in the same directory as the component's DLL.

To specify a different library name or location, create a smvars.bin file containing a setting for SMFLIBS with the library names. That smvars.bin file must reside in the same directory as the COM component's DLL.

Note: The smvars.bin file for COM components can contain two settings: SMFLIBS and SMPATH. Other settings are ignored.

Accessing Libraries

In order for an application to be able to access all its components (COM components, screens, menus), you must use SMFLIBS to open libraries. Threading specifications dictate that if an object opens a library, only that object will be able to use it.

Install the Panther DLLs

Three DLLs distributed with Panther must be on the system's PATH in order for Panther-built components to work:

• PrlSmCom.dll

• PrlDmCom.dll

• PrlTmCom.dll

The default location for these DLLs is PantherInstallDir\bin. The installation program places this directory in the system's PATH.

These DLLs support calls from individual components according to the COM apartment-threading model.

Register the COM Component

In COM applications, the client application and the COM component reside on the same machine; the COM component must be registered on that machine.

To register the component, use regsvr32.exe, located in your Panther util directory. For example, typing the following command in a DOS prompt window registers forecast.dll:

regsvr32 forecast

This process will include the path to the DLL in the Windows system registry. When the component is instantiated at runtime, COM will look for the component's DLL in this location.

For DCOM Deployment

In DCOM applications, the Panther application and the COM component reside on different machines. Each machine must register the component, but the process for the server machine (where the COM component is located) differs from the client machine (which runs the application and accesses the component).

For the server machine, register the component using regsvr32.exe (located in your Panther util directory).

regsvr32 forecast

For each client machine, register the component using the componentName.inf file. Before making the component's .inf file available to your application clients, check its settings (particularly the machine name), and edit those settings as needed. This is an ASCII file and can be edited with any text editor.

Once the .inf file is ready:

• Use regcli32.bat to install the component on the client machine.

  regcli32 forecast

• If the drive containing the component and the .inf file is mounted, run the file's install command (available by right-clicking on the file).

For more information about the settings in the .inf file, view the default file, PrlServer.inf, which is in ASCII format and located in the Panther config directory.

Changing the settings in PrlServer.inf affects all COM components generated from Panther. This file must be named PrlServer.inf.

Configuring DCOM

In order to use DCOM, it must be installed on the client and server machine and configured using dcomcfg. In particular, the check box for Enable Distributed Communication on This Machine must be selected. For more information, check Microsoft's documentation on configuring machines for DCOM.

For MTS Deployment

For MTS, the Microsoft Management Console contains options for registering components and creating export files for application clients. The following section details this process.

Registering Components for MTS

To deploy Panther-built COM components under MTS, you must complete the steps in the previous section, populating the application directory and installing the Panther DLLs, before registering the component.

Create a Component Package

Components must be installed into a component package. A package is a collection of components that run in the same process. You can create an new package or add components to an existing package.

To view the existing packages, start the Microsoft Management Console and choose the desired server machine. One of the settings for that machine is Packages Installed. One method to use to create a new package is to highlight Packages Installed and choose ActionNewPackage.

Refer to Microsoft's MTS Documentation for more information about creating packages.

Install the Component on the Server

To install a component under MTS on a server, use the Microsoft Management Console. This saves the path to the DLL in the Windows system registry.

Figure 5-1 The Microsoft Management Console window for this sample MTS application shows five COM components in the right panel.

How to Install the Component under MTS

1. Highlight the Components folder under the desired package.
2. Choose ActionNewComponent.

   The MTS Management Console will lead you through the steps to install a new component or a pre-existing component.

3. Choose Install New Component(s) if the components are not in the system registry. You will then select the component's DLL.
4. Choose Import Component(s) that Are Already Registered if the component is in the system registry. You will then be able to choose it by name from the list of COM components.

   Note: If you import a component that is already registered, you will be unable to view its interfaces through the MTS Management Console. For more information, refer to Microsoft's MTS Documentation.

• To unregister the component so that it can be installed as a new component, run:

  regsvr32 /u componentName

Assign Roles for Component Access

If you want to implement security features on your component packages, MTS offers two types of security checks: programmatic security, where you call interfaces from within the application, and declarative security, where you assign users, or groups of users, to roles.

A role is the name assigned to a group of users that will access a component package. For example, a human resources application could define roles for Manager and Employee. In the Microsoft Management Console, you assign users to the defined roles.

Panther MTS applications can implement programmatic security using the following functions which call methods of the IObjectContext interface:

• sm_mts_IsCallerInRole—Determines if a caller is assigned to a role, where caller is the identity of the process calling into the server.

• sm_mts_IsSecurityEnabled—Determines if security checking is enabled.

The following section of a JPL procedure, taken from a service component's processing for the UpdateData method, checks to see if the caller is in the writers role before proceeding:

proc UpdateData
vars security, role
role = sm_mts_IsCallerInRole("writers")
...

For more information about implementing security processing, refer to Microsoft's MTS Documentation.

Export the Component to Clients

If the COM component is to be accessed from other machines, it must be registered on those machines as well. The MTS Management Console provides facilities for exporting a component package which creates an executable for installing the package on a remote machine.

Highlight the component package and choose ActionExport.

Refer to Microsoft's MTS Documentation for information about exporting a package.

Using Database Transactions

MTS includes support for database transactions at the component level. For each component installed under MTS, the component's Transaction properties specify whether the component:

• Requires an existing transaction.

• Requires a new transaction.

• Supports transactions.

• Does not support transactions.

Panther MTS applications can control database transactions by calling the following functions:

• sm_mts_SetComplete—Tells MTS that the work is complete.

• sm_mts_SetAbort—Tells MTS to abort the transaction.

• sm_mts_DisableCommit—Tells MTS not to commit the transaction at this time.

• sm_mts_EnableCommit—Tells MTS that the work is complete and ready to be committed.

• sm_mts_IsInTransaction—Determines if a transaction is currently active.

Refer to Microsoft's MTS Documentation for additional information about MTS database transactions.