Chapter 18 Creating ActiveX Clients

Deploy the ActiveX client

You can deploy the ActiveX client on any number of machines. To install the ActiveX client on a client machine:

Copy the client installer, JagClient.exe, to the client machine. Double-click on JagClient.exe and select the ActiveX Runtime option to install the ActiveX runtime files (including the jagproxy.dll, JaguarORB.tlb, SessionManager.tlb, CtsSecurity.tlb, JaguarORB.reg, SessionManager.reg, and CtsSecurity.reg files) on the client machine. For information about running the client installer, see the EAServer Installation Guide for Windows.
JaguarADO.tlb is obsolete and has been replaced by JaguarORB.tlb.
For an ActiveX proxy automation server client, if you do not plan to specify the machine name and IIOP port number of the machine on which the server resides directly in the Connection Host property, you must define (in the System Properties from the Control Panel) a user environment variable for each server that the ActiveX client will invoke components on. By default, the client installer creates an environment variable JS_JAGUAR and sets its value to localhost:9000 . The syntax for environment variable is:
```
JS_JaguarServerName
```
where:

JaguarServerName is the host name used in the ActiveX client code.

The syntax for the value of the environment value is:
```
machine_name:iiop_port#
```
where:

machine_name is the name of the machine that the server resides on.

iiop_port# is the IIOP port number for the server.

For the default server, jaguar, on a machine, puddle, with the default IIOP port number, 9000, you specify this user environment variable:
```
JS_JAGUAR
```
where the value for this environment variable is puddle:9000.
For an ActiveX proxy automation server client, set the JAG_LOGFILE environment variable, which specifies the log file in which initialization errors are recorded. Error messages that occur during the initialization stage are logged into a client log file. If the environment variable is not set, then the error messages in the startup phase will not be seen by the client application. For example:set JAG_LOGFILE=%JAGUAR%\bin\client.logIf the ActiveX proxy is running on the server, then the messages will be logged to the server log file.
Copy the component and package type libraries and registry files from your development machine to the client machine. The directory in which you place the files does not matter because registering the registry files specifies the type libraries location to the machine. The type library file name is the package or component name with a .tlb extension. The registry file name is the package or component name with a .reg extension.
Use the jagreg utility to register the APAS, component type libraries, and registry files. jagreg will also create a new file that reflects the type library and APAS DLL locations that you specify on the command line. You can use the new registry file to reregister the APAS if you change the location of the APAS DLL or type library files.

Running jagreg

To run jagreg, open an MS-DOS Command Prompt window and enter:

jagreg /d jagproxy_dir /f registry_file  [/t tlb_dir] [/o output] [/nr]

jagreg /t tlb_dir /f registry_file [/d jagproxy_dir] [/o output] [/nr]

where:

jagproxy_dir is the directory in which the APAS DLL resides. By default, the APAS installer places jagproxy.dll in the APAS dll subdirectory. Specify this parameter if jagproxy.dll is in a location different from when you generated the registry file. If you are not sure what location is stored in a registry file, specify the current location of jagproxy.dll when you run jagreg.

tlb_dir is the directory where the type library files reside.

output is an optional path to the directory in which updated registry file(s) are written. If you don't specify an output directory, the new registry file replaces the previous file; the previous file is saved with a .KEEP extension.

/nr is the option that prevents the new registry files from being registered. Use this option to update the .reg files without immediately applying them to the Windows Registry.

registry_file is the name of the registry file that you want to change. Use wildcards to specify multiple files, for example *.reg.

The following example updates all .reg files in the current directory, changing the type library location to d:\jag_axp and the APAS DLL location to d:\jag_axp\dll. .reg files in the current directory are updated and previous versions are saved with a .KEEP extension:

jagreg /t %JAGUAR%\dll /f *.reg /d %JAGUAR%\dll

If jagreg does not run, make sure the JAGUAR environment variable is set to the location of your EAServer installation and the PATH environment variable contains the location of the Windows regedit.exe tool as well as the EAServer bin and dll subdirectories.You can use a hyphen (- ) or forward slash (/ ) to delimit jagreg options. For example, both -t and /t are valid.

jagreg creates a new registry file from the existing registry file and:

Replaces the InProcServer32 entry under the CLSID key with the path to the APAS directory.
Replaces the DIR entry under the TypeLib key with the path to the type library files directory.

In the registry file, the InProcServer entry under the CLSID key contains the absolute path to the jagproxy.dll. The DIR entry under the TypeLib key contains the absolute path to the type libraries directory.

If you move the APAS or type libraries, you must run jagreg again with the new settings.

You can run jagreg from a batch file to automate deployment of ActiveX clients. If running jagreg from a batch file, you can check for success by checking the JAGREG_STATUS environment variable. A value of 0 indicates success, and a value of 1 indicates failure.

Normally, jagreg runs silently. You can activate status tracing by setting the JAGREG_TRACE environment variable to "true" before running jagreg. With tracing enabled, jagreg prints status information to the screen as it runs.