Distributing SftMask/OCX	Softel vdm, Inc.

This section describes the preferred distribution method when shipping SftMask/OCX with your application. This method follows Microsoft's guidelines on ActiveX control distribution. While these guidelines are not enforced, it is highly recommended that they are followed as outlined here. This insures that your application can be safely installed and use SftMask/OCX even if another vendor has already installed an application which also uses SftMask/OCX.

SftMask/OCX is not supported on Windows 95 or Windows NT 4.0. Supported platforms include Windows 98, Windows ME and Windows 2000, Windows XP, Windows Server 2003, Windows Vista and Windows Server 2008.

Installing SftMask/OCX (for an Application)

When distributing SftMask/OCX with your application, only the following files can be distributed with your application royalty-free. These files allow the use of the control with your application. The design-time interface is no longer available once SftMask/OCX is shipped with your application. For additional information regarding distributing this control with your application, see the license agreement.

Required Files

Important: Redistributable files are located in the SftMask/OCX installation directory (\Program Files\Softelvdm\SftMask OCX 6.5\Redist).

These files must be shipped with your application if SftMask/OCX is used:

File Name	Description
SftMask_IX86_U_65.ocx	Required. SftMask/OCX control.
Softelvdm.OCXHelper.dll	Required for .NET ONLY. This .NET component is required when distributing managed .NET applications. It is not used for other (unmanaged) languages, like VC++, VB6, etc. This file must be registered for COM Interop during installation (e.g., using Regasm.exe or using the provided registry scripts Softelvdm.OCXHelper.Add.reg and Softelvdm.OCXHelper.Rem.reg).
Unicows.dll	Required for Windows 98, ME.  It can optionally be installed on Windows 2000, Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, but is never used.  The DLL Unicows.dll can only be distributed under license from Microsoft Corp. This DLL can be downloaded at no charge from Microsoft's web site at http://www.microsoft.com/downloads/ searching for product "Platform SDK".  The title of the item is "Platform SDK Redistributable: MS Layer for Unicode on Windows 95/98/ME Systems".
Comctl32.dll	Optional. This file is only required if the popup calendar is used. The minimum version required is 4.70. This version is part of Internet Explorer 3.x and later. When installing on Windows 95 or NT4, this file must be installed (with version checking of course) as a standard Windows 95 and Windows NT4 installation only has version 4.00 of Comctl32.dll. Windows 2000, Windows 98 and Windows NT SP1 (and newer) already have a more recent version of this file. Any operating system with Internet Explorer 3.x (or better) installed has a more recent version installed. As a rule, this file should always be installed by your SETUP program if your application uses the popup calendar. Microsoft provides setup programs on its web site for distribution of Comctl32.dll (i.e., Common Controls). Included with SftMask/OCX is the file 401Comupd.exe (Redist directory), which is a stand-alone setup program, distributed and supported by Microsoft, to update the Common Controls. This only needs to be run if the Comctl32.dll version on the target system is lower than 4.70. Please see Microsoft's Knowledge Base article Q186176 INFO: Redistribution of Comctl32.dll for more information.
ShFolder.dll	Optional. This file is only required on Windows 95 and NT4 when using the leading "-" character of the AutoComplete.File property. Windows 98, 2000 or newer do not require this file. This file can be installed on all Windows versions (with version checking of course) even if the file is not required. SftMask/OCX is not supported on Windows 95 or Windows NT 4.0.
Oleaut32.dll	Required. OLE support. While normally present, the installation must insure that the current version is installed. This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.
Olepro32.dll	Required. OLE property and standard types support. While normally present, the installation must insure that the current version is installed. This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.
Stdole2.tlb	Required. OLE support. While normally present, the installation must insure that the current version is installed. This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.
Asycfilt.dll	Required. OLE support. While normally present, the installation must insure that the current version is installed. This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.
Comcat.dll	Required. OLE support. While normally present, the installation must insure that the current version is installed. This file is also needed by the container (VB, VC++, etc.) to support OLE and any ActiveX control.
Regsvr32.exe	Optional. Control registration utility, for "manual" registration. Not needed with most commercial Setup creation tools.

Target Directory

Depending on the target operating systems, one of the following target directories can be chosen.

A) Windows\System(32)

Installing the ActiveX control into the Windows\System(32) directory is possible on all supported Windows platforms.

The setup program you provide with your application should install the SftMask/OCX control SftMask_IX86_U_65.ocx into the Windows System directory.  The Windows System directory name can be found using the GetSystemDirectory API function.  All other files shown in the above tables also have to be installed into the Windows System directory.  On Windows 95, 98, ME, the Windows System directory is usually named C:\Windows\System or on Windows NT, 2000, XP, Server 2003, Vista, it is usually named C:\Windows\System32.

The control is installed into the Windows/System(32) directory and registered using proper versioning and reference counting of the OCX file (usually automatic, with most commercial installers).  

B) Application Directory

An ActiveX control can be installed in the application directory using DLL/COM redirection, which is available on Windows 2000, 98SE and better only. 

DLL/COM redirection is activated on an application-by-application basis by the presence of a ".local" file. The ".local" file is an empty file in the same directory as the application's .exe file, with the same name as the application's .exe file with ".local" appended to the end of the name. 

For example, to activate DLL/COM redirection for an application called "SampleApp.exe", create an empty file called "SampleApp.exe.local" in the same directory where SampleApp.exe is installed.

On Windows XP or better, "Registration-Free Activation" (see below) can be used, which eliminates the need for the ".local" file.

Once DLL/COM redirection is activated, whenever the application loads a DLL or an OCX, Windows looks first for the DLL or OCX in the directory where the application's .exe file is installed.  If a version of the DLL or OCX is found in the directory where the application's .exe file is installed, the application uses it regardless of any directory path specified in the application or the registry.  If a version of the DLL or OCX is not found in the directory where the application's .exe file is installed, the normal search path or server path is used.

Even if DLL/COM redirection is used, the control must be registered during installation (see "Registering SftMask/OCX" below).  The control must be installed into the Windows/System(32) directory and registered using proper versioning and reference counting of the OCX file (usually automatic, with most commercial installers).  In addition, a private copy in your application directory is always installed (but not registered), along with the application's ".local" file.

Version Control

The setup program should only install the SftMask/OCX files if the version number in the new files is higher than the files already installed. Maintenance releases of the product are fully upward compatible and are guaranteed to have a newer version number. New versions of the product will use new file names and new GUIDs so there will be no conflict between different (major) versions, such as 5.0, 6.0 and 6.5.

Reference Counting

When installing DLLs or OCX files into a "shared" location, such as the Windows\System(32) directory, proper reference counting must be performed, to insure that the file isn't uninstalled until all applications making use of the DLL or OCX have also been uninstalled.  Reference counting is generally available with most commercial installers.  The Windows Registry contains a count of all such shared files in the following Registry location:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs

Registering SftMask/OCX

Depending on the target operating systems, one of the following ActiveX/COM registration methods can be selected.

A) Windows Registry

Registering the ActiveX control in the Windows Registry is possible on all supported Windows platforms.

The setup program should register SftMask/OCX in the Windows registration database (Registry).  This can be done manually using Regsvr32.exe which is discouraged. Many commercially available setup programs can register SftMask/OCX during the installation of your application.

SftMask/OCX is a self-registering ActiveX control. By using the LoadLibrary Windows API function, the GetProcAddress API can be used to obtain the DllRegisterServer function. By calling this function, the SftMask/OCX control will register itself with the Windows registration database (Registry). Most commercially available setup programs have support for this built-in. Check the documentation of your setup application for information on how to install ActiveX controls.

The following files need to be registered in this manner:

B) Registration-Free Activation

On Windows XP and better it is possible to deploy this ActiveX control using "Registration-Free Activation".  Registration-free activation allows distribution of the control without the requirement to register the ActiveX control in the Windows Registry (using REGSVR32 or a Setup application).  Registration-free activation is supported by the operating system, so the .NET run-time is not required for registration-free activation.

By using registration-free activation, true XCOPY deployment is possible.  Your application uses its own copy of the control.  Versioning, reference counting and registration of the control are completely eliminated and other installed versions of the control cannot interfere with your application.

By using an application manifest and copying the OCX file SftMask_IX86_U_65.ocx into your application directory, the ActiveX control is automatically registered when it is used the first time.  Your application manifest must include the comClass and typelib definitions shown below.  These insure that your application automatically registers the control and uses the control located in your application directory, regardless of any other controls or other versions of the same control already installed or in use.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly 
   xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0"> 
<assemblyIdentity version="1.0.0.0" processorArchitecture="x86" name="SoftelvdmInc.SftMask60.Sample.exe" type="win32" /> 
   <description>SftMask Sample Application</description> 
   <dependency>
     <dependentAssembly>
        <assemblyIdentity type="win32" 
             name="Microsoft.Windows.Common-Controls"
             version="6.0.0.0" 
             processorArchitecture="x86"
             publicKeyToken="6595b64144ccf1df"
             language="*" /> 
     </dependentAssembly> 
   </dependency>

   <file name="SftMask_IX86_U_65.ocx">
       <comClass description="SftMask/OCX 6.5 Masked Edit Control"
           clsid="{5F2D1CA4-5580-4d70-8B3A-228A2C660BB9}"
           threadingModel="Apartment"
           miscStatus="setclientsitefirst,alignable,activatewhenvisible,insideout,cantlinkinside,recomposeonresize"
           progid="SftMaskOCX65.SftMask.1"
           tlbid="{5F2D1CA0-5580-4d70-8B3A-228A2C660BB9}"/>
       <typelib tlbid="{5F2D1CA0-5580-4d70-8B3A-228A2C660BB9}"
           version="6.5" helpdir=""/>
   </file>

</assembly>

Testing a Setup Program

If you test the installation of your application's Setup program on a system where SftMask/OCX is installed, you may notice that you can no longer use SftMask/OCX in your development environment. This is caused by the fact that your Setup program installed a “run-time” only control on your system, which has replaced the “design-time” or development version of SftMask/OCX. You can reinstate (or re-register) the design-time version of SftMask/OCX by using the program entry “Maintenance, Register SftMask OCX in Windows Registry” in the SftMask OCX 6.5 program group.

Installing SftMask/OCX (for a Web Page)

When using SftMask/OCX on your web pages, only the following file(s) can be distributed royalty-free. These files allow the use of the control on your web pages. The design-time interface is not available to visitors of your web site.

This product must be licensed separately for use on web sites.  A special run-time license is required to use this product on web pages hosted on web sites.  Such a web license can be obtained from our web site at http://www.softelvdm.com/weblicense. The web license is entered at design-time into the property pages by updating the WebLicense property. The WebLicense property defines the license information for use on one web site. A web license is valid for one domain and supports third level domains (e.g., one license covers "softelvdm.com", "www.softelvdm.com", "test.softelvdm.com", etc.).

Required Files

Important: Redistributable files are located in the SftMask/OCX installation directory (\Program Files\Softelvdm\SftMask OCX 6.5\Redist).

One of the following files is referenced by the OBJECT tag of a web page containing a SftMask/OCX control. This file must be available on your web server:

File Name	Description
SftMask_IX86_I_65.cab	Cabinet file containing the SftMask/OCX control, run-time only, compressed, with digital signature. This is the preferred distribution method.
SftMask_IX86_U_65.ocx	This file cannot directly be used on a web page. If you wish to create your own cabinet file (replacing SftMask_IX86_I_65.cab) and use your own digital signature, you can use this standard ActiveX control, which is normally used in applications and create your own cabinet file. Please see the Microsoft ActiveX SDK, Internet Client SDK or Platform SDK for information on cabinet files and digital signatures.

The cabinet file does not include Comctl32.dll, even though this DLL is needed if your application uses the popup calendar. Any version of Internet Explorer on all supported platforms already includes the correct minimum version of Comctl32.dll, so this file does not need to be installed again.

Version Control

Version control is insured by using the proper HTML OBJECT (see Using SftMask/OCX with Internet Explorer, CODEBASE keyword). Maintenance releases and new versions of the product are fully upward compatible and are guaranteed to have a newer version number. Make sure to check the file Readme.html which was installed with SftMask/OCX for the most current version number to use.