Clarion Community Help

Choosing a Configuration

This section is included to help you decide what kind of target file to specify for your project..

Clarion produces executable files which you may distribute on a royalty-free basis. The applications you distribute require a Windows 32-bit environment (95/98, NT, 2000, XP, etc.).

Clarion executables come in two flavors: .EXE files, and .DLL files. An .EXE file is simply an executable program. A .DLL (Dynamic Link Library) file is executable code that is linked into an .EXE file at run-time. This is in contrast to .OBJ and .LIB files which are linked into an .EXE at compile time. The most obvious benefit of the .DLL is that it provides a method of modifying .EXE operation without remaking (compiling and linking) the .EXE.

Clarion executables may be distributed in the following four configurations where [x] indicates the 32-bit runtime library for applications running on 32-bit operating systems (95/98, NT, 2000, XP, etc.):

*.EXE

A one-piece .EXE will usually be larger than an .EXE distributed with .DLLs. However, the one-piece .EXE will probably be smaller than the combined sizes of an .EXE and its associated .DLLs.

The one-piece .EXE is made as small as possible by Clarion's smart linking process that only links in procedures actually called by the application program (whereas the .DLL contains a fixed set of procedures, whether or not they are actually called by your program).

A one-piece .EXE cannot have conflicts or problems that arise from linking with the wrong .DLLs at run time.

Make (compile and link) time for a one-piece .EXE is greater than for an .EXE combined with .DLLs.

*.EXE + ClaRUN.DLL

Splitting the executables between .EXEs and .DLLs allows for more efficient use of disk space. Many Clarion applications (.EXEs) can share a single ClaRUN.DLL. Or, a single application suite with several .EXEs can share a single ClaRUN.DLL. However, as a developer, you must ensure that your application accesses the correct version of ClaRUN.DLL.

An example of .DLL usage is the typical accounting system where the .EXE controls the system main menu, and calls system subparts such as Accounts Receivable and Accounts Payable from separate .DLLs. This method of distribution allows for program parts to be sold and maintained separately.

Splitting executables between .EXEs and .DLLs allows for more efficient use of disk space, but less efficient use of RAM. This is because Windows 95 loads an additional ClaRUN.DLL into memory for each active Clarion executable, and because the ClaRUN.DLL contains some procedures your .EXE never calls.

To make an .EXE + ClaRUN.DLL: in the Global Options dialog, set Target Type to .EXE and set Run-Time Library to Standalone.

*.EXE + ClaRUN.DLL + *.DLL1 + … + *.DLLn

This configuration offers the same advantages and disadvantages as the .EXE + ClaRUN.DLL configuration. It is listed here to illustrate that you are not limited to a single .DLL, nor are you limited to Clarion .DLLs. Your Clarion applications may make use of .DLLs compiled from other languages as well as the ClaRUN.DLL and SoftVelocity database driver .DLLs. See the Database Drivers help section for more information on database drivers.

*.EXE + *.DLL1 + … + *.DLLn

This configuration offers most of the same advantages and disadvantages as the .EXE + ClaRUN.DLL configuration. It is listed here to illustrate that the ClaRUN.DLL may be linked into another .DLL. This technique “hides” the ClaRUN.DLL and ensures that your application will never get the wrong version of ClaRUN.DLL, because, technically, it isn't looking for ClaRUN.DLL.

Installing and Accessing Your Application's DLLs

If you distribute ClaRUN.DLL, it must reside in the same directory as the application program, in the Windows\System subdirectory, or in a directory referenced in the system PATH. We recommend that you install ClaRUN.DLL to the application directory.

Remember, multiple Clarion applications may use the same ClaRUN.DLL file, thus saving space on the users' hard drive. On the other hand, sharing a single ClaRUN.DLL raises the possibility of conflicts among applications developed under different versions of Clarion. To avoid possible conflicts, install a separate ClaRUN.DLL to each application directory, or distribute the application as a single .EXE file, or link the ClaRUN.DLL into another .DLL that is unique to your application.

The Ship List

For generated applications, Clarion templates automatically create a ship file (.SHP) that contains the names of the files that are needed to run your application. The file is called application.SHP and is in the same subdirectory as your .APP file.

This ship file only includes those files that are visible to the templates. Any DLLs loaded in EMBEDs or INCLUDE files may not be visible to the templates, and may not be in the list.

In the case of external library modules, the .LIB file is also included in the list. Some of the .LIBs (WINDOWS.LIB for example) do not have associated DLLs; however, most do have associated .DLLs that you will need to distribute with your application.

In the case of an external library module generated by Clarion, you must ensure that all files on the shipping list for that LIB/DLL are also included.

You can modify your application's ship list by embedding text at the Inside the Shipping List Global Embed point.