Background:  This page describes how to host a ConvertIt.com-like measurement converter on your site.  ConvertIt.com uses the Entisoft Tools software to power its measurement converter.  ConvertIt.com has a license to use the Entisoft Tools software on the Web and to sublicense its use to others.  Unless you have a written contract from ConvertIt.com authorizing you to host the Entisoft Tools software on your site, then it is a violation of Entisoft's License Agreement and Copyright to use the Entisoft Tools software as described on this page.

Overview:  You might want to try out our measurement conversion calculator at
   http://www.convertit.com/Go/ConvertIt/Measurement/Converter.ASP
to get an idea of what it can do.  In addition to performing measurement conversions, it can generate tips and factual information, display the name of related measurements, and perform sample conversions to related measurements.  We have a variety of functions that actually perform measurement conversions; the most important ones are described below.

Download:  You will need to download version 2.0 of Entisoft Tools in order to use our measurement conversion functions. 

Installation:  After you download the file EST2_0S.EXE, run it and follow the prompts to install the software onto one of your PCs.  You may want to install Entisoft Tools onto one of your workstation PCs so that you can familiarize yourself with its functions by testing them from within Visual Basic.  Once you have completed the installation procedure, it will place our ActiveX DLL in your Windows System directory (usually C:\WINDOWS\SYSTEM under Windows 95/98 and C:\WINNT\SYSTEM32 under Windows NT/2000).

Branding:  We will provide you with the Entisoft Tools Runtime file via e-mail.  You must then copy the attached ESTOOLS.RUN file into the Windows System directory so that you will have the Runtime Edition of Entisoft Tools.  (The DLL by itself is the Trial Edition which has "nag" screens.  Copying this runtime key file into the same directory as the Entisoft Tools DLL will remove the nag screens.)  This is also very important when you install the DLL onto your servers.  If you do not also install the associated ESTOOLS.RUN file, the DLL will display data entry forms that will not be visible in the foreground.

Testing:  Once you have Entisoft Tools installed on one of your PCs, you will probably want to try out some of the functions.  This is very simple using Visual Basic.  Create a new Visual Basic 6.0 Project.  Establish a Reference within that project to the Entisoft Tools 2.0 Object Library.  Then, add a statement like:
    Public EU As New Units
to the Declarations section of some Visual Basic Module.  You can then try out the measurement conversion functions from within that project.

There is an alternative way to create an instance of the Units Class within Entisoft Tools.  This way does not require you to establish a Reference to Entisoft Tools within your project.  If you want, you can create an Object variable somewhere:
    Public EU As Object
then execute the following statement:
    Set EU = CreateObject("EntisoftTools2_0.Units")
We recommend that you establish a Reference to the DLL for testing purposes; that way you can take advantage of the IntelliSense features within Visual Basic.

The Main Measurement Conversion Function:  The main measurement conversion function is called ConvertToExpr.  For example, try this within the Visual Basic Debug Window:
    ?EU.ConvertToExpr("1/5 m","feet", 45)
and the result will be:
    0.2 meter = 0.656167979002625 foot
                 (length)
Try:
    ?EU.ConvertToExpr("1/5 kg*m/s^2", "feet", 100)
and the result will be:
    0.2 kilogram meter               0.656167979002625 newton
    ------------------ TO   foot   = ------------------------
         second^2                             meter
         (force)          (length)      (surface tension)
The first argument is the "Convert From" expression; the second argument is the "Convert To" expression; and the third argument is the maximum line width (not the maximum length) of the result string.  For example,
    ?EU.ConvertToExpr("1/5 kg*m/s^2", "feet", 45)
will return:
    0.2 kilogram meter / second^2 (force) TO foot
    (length) = 0.656167979002625 newton / meter
    (surface tension)
The result is more concise in order to fit within a width of 45 characters wide.

The ConvertToExpr function replaces certain HTML meta-characters with their names. For example:
    ?EU.ConvertToExpr("230 knots", "mach", 100)
returns
    230 nautical miles per hour = 0.356972854106747 Mach at sea level & 32 dF (velocity)
Notice that the ampersand ("&") was replaced by &

If this conversion function is too high-level for your use--for example, if you want to change the layout of the results--you can use our ConvertMeasure function:
    ?EU.ConvertMeasure(.2, "feet", "m")
returns
    0.06096
as a number and
    ?EU.ConvertMeasure(.2, "kg*m/s^2", "feet")
returns
    0.656167979002625 N/m
as a string.

If you set the ConvertToBaseUnits property to True like this:
    EU.ConvertToBaseUnits = True
then all results will be displayed in terms of the base measurements involved.  For example:
    ?EU.ConvertMeasure(.2, "kg*m/s^2", "feet")
would then return
    0.656167979002625 kg/s^2

Other Important Functions:  There are some other important functions which ConvertMeasure uses and which you may want to use.  The FindCategory function will find the most-prevalent physical category which is referred to by a measurement expression. For example:
    ?EU.FindCategory("kg*m/s^2")
will return
    force
The EnumerateUnits function will enumerate the names of the units mentioned within a measurement expression.  For example:
    ?EU.EnumerateUnits("kg*m/s^2")
will return
    kilogram*meter/second^2
The FindBaseCategories function is similar, though it enumerates the base physical categories described by the measurement expression.  For example:
    ?EU.FindBaseCategories("kg*m/s^2")
will return
    mass*length/time^2
With the ConvertToBaseUnits Property set to False, you can use the ConvertMeasure function to find the SI (metric system) Base or Derived unit specified by a measurement conversion expression.  For example:
    ?EU.ConvertMeasure(1,"kg*m/s^2","")
will return
    N
and
    ?EU.EnumerateUnits("N")
will return
    newton

Displaying Tips:  You may want to use our GeneralTip function.  For example, one call to
    ?EU.GeneralTip
might return:
    Tip #86: Entisoft Units contains all of the important metric, SI, English, Avoirdupois, Troy, and ancient conversion factors. For example, converting "10 cups" to "liters" returns 2.37. and the next call might return: "electric dipole moment" is measured in C*m.

The tips alternate between displaying general information about the measurement conversion calculator, and displaying information about the measurements recognized.  You may want to filter-out all of the tips that begin with the string Tip # because some of them refer to the Windows-based version of the Entisoft Tools Units class; those tips are only appropriate for programmers using the Units class, or for people using the Windows-based version of the Entisoft Units program.  We expect to update those tips within the Entisoft Tools Units class so that that they are all appropriate for use within Web pages based on the Entisoft Tools Units software.

Related Measurements:  Our RelatedUnits function will return a string describing the measurements related to a specific measurement.  For example:
    ?EU.RelatedUnits("kg*m/s^2", 20, True, False)
might return:
    Try converting from "kg*m/s^2" to atomic weight, dyne (cm*gm/s^2), gram force, kip (kilopound force), newton, pound force, poundal, sthene, ton force, or any combination of units which equate to "mass length / time squared" and represent bending moment to length, force, or weight.

Assuming that you use the vAddHTML argument of the RelatedUnits function in order to generate HTML links from the related measurements back to the measurement conversion calculator, you will have to perform string substitution on the A HREF strings that are returned.  They are hard-coded to call UnitsCGI.Exe, which was the name of our original CGI-based measurement conversion calculator page.

Sample Conversions:  Our SampleConversions function is very similar, though it actually performs sample conversions to related units and returns them in the form of a string. For example:
    ?EU.SampleConversions("2.34 kg*m/s^2", 20, True, False)
might return:
    2.34 kg*m/s^2 = 1.44E+26 atomic weight, 234,000 dyne (cm*gm/s^2), 238.61 gram force, .00052605 kip (kilopound force), 2.34 newton, .52605293 pound force, 16.93 poundal, .00234 sthene, .00023861 ton force.
I say "might return" because there is some randomness involved.  You can specify the maximum number of related units or sample conversions to return, and if it knows of more related measurements, then it will randomly select the units it returns.

Assuming that you use the vAddHTML argument of the SampleConversions function in order to generate HTML links from the related measurements back to the measurement conversion calculator, you will have to perform string substitution on the A HREF strings that are returned.  They are hard-coded to call UnitsCGI.Exe, which was the name of our original CGI-based measurement conversion calculator page.

Upgrades:  We are currently reviewing and updating our measurement conversion definitions.  We will probably have some updates for you soon.  We can either 1) send these updated measurement unit definitions in the form of a text file that can be read up directly by our measurement conversion functions, or 2) have you download a new version of the Entisoft Tools program.  We recommend that you make your programs read the measurement definitions from a text file as described below, because you will get the updates sooner using this method.  The following paragraphs describe how to use the Entisoft Tools Units class to load the measurement definitions from a text file.

In order to update your programs with these definitions, we will probably have you add some code like the following to your programs:
    EU.InitializeDone = True
    EU.LoadOneFile "C:\Entisoft\Units.Txt", False
If you would like to add this code to your programs now before you actually start using our software in a production environment, then you must place that code in the initialization section within your programs.  For example, you must execute that code before you use any other functions from the Units Class.  Also, you must then create the file C:\Entisoft\Units.Txt with the following single line:
    AddBuiltIn
The EU.InitializeDone = True statement tells the Units Class that it has been initialized--that it need not load its built-in measurement definitions.  The EU.LoadOneFile call tells the Units Class to load the measurement definitions from the named file, in this case C:\Entisoft\Units.Txt.  When it reads that file and encounters the line AddBuiltIn, the Units Class will load all of its built-in measurement definitions.

We suggest that you check after the LoadOneFile statement to make sure that some measurement definitions were loaded.  If there was some problem loading the measurements, then you should clear all of the definitions and force the program to load its built-in definitions.  For example, use something like the following:
    If EU.GetUnitCount < 100 Then
        EU.ClearAll
        EU.InitializeMandatory
    EndIf

When we send you updated measurement definitions, they will be in the form of a text file.  You will replace that Units.Txt file with the new text file that we send, then your programs will have all of the most recent measurement definitions.

List of Measurements Recognized:  We have the HTMLUnitsList subroutine which creates the pages listing the various units.  There is not much flexibility in the way that the pages are created.  You could either 1) use that function to create the basic pages, then modify those pages manually, or 2) use the lower-level functions to create your own pages listing the various units, prefixes, etc., or 3) use the .inc files that we have created which contain the measurements in the form of an HTML bullet list.  If you choose to create your own pages using the lower-level functions, see the GetPrefix, GetPrefixCount, GetReplacement, GetReplacementCount, GetUnit, and GetUnitCount functions for information on how to access the measurement definitions.  If you would like to use the .inc files that we have prepared, they are available in the
   http://www.convertit.com/Global/Measurement/Units/
directory.

Please call or write with any questions!
Steve Schmidt, ConvertIt.com
Telephone: +1-517-256-1939
mailto:Info@ConvertIt.com