Platform SDK: Transaction Server

Generating MTS Executables

[This product will work only on Windows NT 4.0 versions and earlier. For Windows 2000 and later, see COM+ (Component Services).]

Using the MTS Explorer, you can generate an application executable that installs and configures a client computer to access a remote server application. The client computer that installs the executable must have distributed COM (DCOM) support, but does not require any MTS server files other than the executable to access a remote MTS server application.

The application executable utility is part of the package export feature in the MTS Explorer. This utility allows you to automatically generate application executables that install a client application and configure the client computer to access a server application on a remote MTS servers. Executables generated by the application executable utility by default will configure a client computer to access the deployment server on which the executable was generated.

You can also configure the Remote server name field on the Options tab on the Computer property sheet to point client applications to a server other than the deployment server. If you do not enter the name of another server computer before exporting the package to generate an executable, application executables created on the local computer will automatically configure client computers to access server packages on the local computer.

To configure a client application executable to access a server computer other than the local computer:

Select My Computer.
Right-click and select Properties from the right-click menu.
Select the Options tab and enter the name of the remote server in the Remote server name field in the Replication section.
Click OK, and export the package to create the application executable.

The application executable utility automatically creates an executable for the client application.

On the client, the executable automates the following steps:

Copies to a temporary directory on the client or server machine and then extracts the necessary client-side files, including type libraries and custom proxy-stub DLLs.
Transfers type libraries and proxy-stub DLLs for the server application to the Remote Applications directory in the \Program Files sub-directory. All remote applications are stored in the Remote Applications directory. Each remote application has an individual directory named by the package globally unique identifier (GUID).
Updates the system registry with the entries that either enable clients to use the server application remotely (including information that is related to application, class, programmatic, interface, and library identifiers) or allows the server application to run on the server computer.
Registers the application so that a user can use the Add/Remove Programs icon in Control Panel to remove it at a later date. All remote applications are prefaced with “Remote Application” so that you can easily find your application in the list of installed components.
Deletes files in the temporary directory generated during installation of the application.

When run on a client computer, the client executable copies the necessary proxy-stub DLLs and type libraries to that computer and updates the client’s system registry with information needed by DCOM, including the name of the server computer. Client applications can then access the remote server application.

To create a client executable:

Install the server application using the Package Wizard if you have not already done so.
Export your package, and specify a new filename (YourNewFileName) as the package export filename. (Note that you must configure the Remote server name property on the Options tab of the Computers property sheet if you would like your clients to access a server other than the deployment server on which you are creating the executable.) .
Locate the folder into which you exported your package. Exporting an existing package in the MTS Explorer generates a "clients" subdirectory beneath the directory to which you exported the package. The clients sub-directory contains a single executable with the name specified during package export. When run on any client supporting DCOM, this executable installs all the necessary information for remote clients to access the server application.

Important Do not run this client executable file on your server computer. Running the client executable on the server computer removes the registry entries required to run the server package. If you make this mistake, you must remove the application using the Add/Remove Programs property sheets in the Control Panel. Then delete and re-install the package using the MTS Explorer.

If another version of a component installed by a client executable already exists on the client machine, the component will only be updated if:

both versions of the component have version numbers
the version of the component being installed is later than the version of the component already on the client machine.

You can customize the installation of your client application to include additional files by creating a setup file called "clients.ini" in the clients sub-directory. The clients.ini file can be modified to combine installation of client executables for several different applications, or to include application documentation.

To customize installation:

Create an .ini file called clients.ini and save the file into the folder into which the package will be exported.

Copy the following text into the blank clients.ini file.

[ClientApplicationFiles]
SourcePath=c:\temp\custom vb bank

[ClientApplicationInstallCommands]
1=notepad {{{readme.txt}}}
2={{{vbbank.exe}}}

[ClientApplicationSetup]
ExploreApplication=Y

Below the ClientApplicationFiles heading, modify the path to the directory in which you want the source code installed on the client computer. For example,
```
Source Path=c:\program files\mts\test\vb bank
```
Below the ClientApplicationInstallCommands heading, enter the names of the files that you wish to install. Use triple-brackets to enclose the names of the files that you want to install. For example:
```
1=notepad {{{readme.txt}}}
2={{{vbbank.ex}}}}
```

Note that the files that you wish to install must exist in the directory specified by the Source Path file path.

Below the ClientApplicationSetup heading, indicate if you would like to enable the ExploreApplication setup option by typing “Y” for yes or “N” for no. For example, the following entry would display the application immediately after setup so that the client could create a shortcut to the desktop:
```
ExploreApplication=Y
```

After you have saved the clients.ini file with these changes, you can use the MTS Explorer to export the server package to create a client executable.

To create a client executable:

Install the server application using the Package Wizard if you have not already done so.
Create a folder into which you want to export your package.
Export your package from the server on which your server application is installed to another server. (Note that you must configure the Remote server name property on the Options tab of the Computers property sheet if you would like your clients to access a server other than the deployment server on which you are creating the executable.) Specify a new filename (YourNewFileName) as the package export filename.
Locate the folder into which you exported your package. Exporting an existing package in the MTS Explorer generates a "Clients" subdirectory beneath the directory to which you exported the package. The Clients sub-directory contains a single executable with the name specified during package export. When run on any client supporting DCOM, this executable installs all the necessary information for remote clients to access the server application.

If another version of a component installed by a client executable already exists on the client machine, the component will only be updated if:

both versions of the component have version numbers
the version of the component being installed is later than the version of the component already on the client machine.

Distributing the Client Executable

The MTS Explorer automates packaging and installing client applications into executables for distribution. Distribute those executables by using one of the following methods:

Sharing a directory so that clients can copy the executable and run it on their computers.
Sending an email attachment so that clients can save and run the executable on their computers.
Incorporating an executable into an HTML script using the <OBJECT> tag. The <OBJECT> tag allows the browser to download the application from a specified object store location to the client machine if the client initiates an event on the HTML page (such as clicking a button). Using the <OBJECT> tag to distribute executables facilitates upgrading executables, since the browser automatically checks the client’s registry for the current version of the application. If the existing executable is outdated, the browser downloads the latest version from the object store.
Using Microsoft System Management Server (SMS) to “push” the distribution of your application from a central location to tens or hundreds of computers at once. Note that you must install the client application itself after installing the application on remote computers.

Removing the Client Executable

Clients can remote the client executable through the Add/Remove option in the Control Panel. Applications installed by MTS executables begin with "Remote Application" in the Install/Uninstall list. To remove the executable, select the appropriate application and click Remove.