### Packaging the IBM C and C++ Compilers Run-Time DLLs

If your application uses functions from the IBM C and C++ Compilers libraries, you need to ensure the code for those libraries is always available to your application. You cannot ship the IBM C and C++ Compilers DLLs themselves with your application because of the product licensing agreement and because if more than one application included the IBM C and C++ Compilers DLLs, but at different levels, at least one application would be using the wrong level.

If you are shipping your application to other users who do not have access to the library DLLs, you can use one of three methods to include the IBM C and C++ Compilers library code:

1. Statically bind every module to the library (.LIB) files. Compile with /Gd-, which is the default.

   This method increases the size of your modules and slows the performance because the library environment has to be initialized for each module. Having multiple library environments also makes signal handling, file I/O, and other operations more complicated.

2. Create your own run-time DLLs.

   This method provides one common run-time environment for your entire application. It also lets you apply changes to the run-time library without relinking your application, meaning that if the IBM C and C++ Compilers DLLs change, you need to rebuild only your DLL.

   For a description of how to build your own run-time DLL, or subsystem run-time DLL, see Create a DLL.

3. Use the DLL rename utility, DLLRNAME, to rename the IBM C and C++ Compilers library DLLs. This utility also changes the names in your executable files that call the DLLs. DLLRNAME is part of the IBM C and C++ Compilers product, and is described in "Using the DLLRNAME Utility" below.

Using the DLLRNAME Utility

To use the DLL rename utility, build your application using the import libraries provided with IBM C and C++ Compilers (compiling with the /Gd+ option). Then, before you ship your application:

1. Copy the IBM C and C++ Compilers DLLs that your application uses into a working directory.
2. Run the DLL rename utility, DLLRNAME, against your executable files and your working copies of the IBM C and C++ Compilers DLLs. The utility will rename the DLLs as well as all internal names that need to be changed as a result.

The syntax for the dllrname command is:

> dllrnameModule-name Oldname=Newname / Option

Module Names

The list of module names includes the IBM C and C++ Compilers library DLLs your application uses, along with the EXEs and DLLs that reference them. They must be present in the current directory, unless their paths are specified. Case is disregarded when matching names.

Note: It is important that you include all the modules in your application in this list, since the names by which the modules reference the IBM C and C++ Compilers library DLLs must also be changed in the modules themselves.

Name Changes

You specify the list of the name changes to be made by indicating Oldname=Newname on the DLLRNAME command line.

Oldname is the name of the IBM C and C++ Compilers library DLL as it was shipped with IBM C and C++ Compilers.

Newname is the name under which you will be shipping the IBM C and C++ Compilers library DLL with your application.

Note: The DLLRNAME utility requires that Oldname and Newname have the same number of characters.

For example, to rename the IBM C and C++ Compilers library DLL CPPWS35.DLL to MYLIBRY.DLL in the modules myprog.exe and mydll.dll, specify the following on the DLLRNAME command line:

> `dllrname myprog.exe mydll.dll CPPWS35=MYLIBRY`

How DLLRNAME Works

All modules (.EXE and .DLL files) that use other DLLs contain records specifying a set of external file names that are needed to run the module. The DLLRNAME utility manipulates only these records; it does not modify your executable code.

One of the external names specified in a module is the name of the module itself. The name of module, as it appears in its own internal records, is called its internal name. You specify this name with the NAME or LIBRARY statement in a DLL module definition (.DEF) file when you link the module. In the case of an .EXE file, the loader essentially ignores the internal name. For a .DLL, its internal name must match its filename; otherwise the loader will refuse to load the DLL. By default, DLLRNAME will also change the filename of a DLL if it changed its internal name.

The rest of the external names specified in a module are the names of the DLLs to be loaded when the Windows loader loads the module. All of these DLLs must be loaded for the Windows loader to successfully load the module. If you specify any of these required DLLs for rename on the DLLRNAME command line, DLLRNAME also changes the names of the required DLLs in the module itself.

On OS/2, the DLLRNAME utility accepts 32-bit Linear eXecutable (LX) executables.

On Windows platforms, the DLLRNAME utility accepts 32-bit Microsoft Portable Executable (PE) executables.

What DLLRNAME Will Not Do

The DLLRNAME utility will not:

- Modify DOS executables.
- Modify DLLs named explicitly in your executable code. This is important to remember if you use the Windows LoadLibrary() API or the IBM C and C++ Compilers_loadmod function to load a required DLL. You must modify your code to load the DLL using its modified name.
- Change the name of a DLL to a name of different length.

Other Uses for DLLRNAME

The DLLRNAME utility can also be used to:

- Rename your own DLLs so that you can have multiple versions of your application resident on the same machine for testing purposes.
- Obtain a report that lists all the DLLs used by a module. Simply invoke the DLLRNAME utility without specifying any DLL name changes.

An Example

If you compiled your application using the following command lines:

> `ICC /Gd+ /Ge- /FeA.DLL A.C B.C C.C D.C A.DEF
> ICC /Gd+ /FeE.EXE E.C F.C G.C H.C A.LIB`

`your application would be made up of the files A.DLL and E.EXE. Since you specified the /Gd+ compile option, your application also requires the file CPPWS35I.DLL from IBM C and C++ Compilers.`

`To obtain a renamed copy of CPPWS35I.DLL that you may ship with your application, use the following set of commands:`

    REM Get a working copy of the IBM C and C++ Compilers library DLL
    COPY D:\IBMCPPW\DLL\CPPWS35I.DLL

    REM Change all the names
    dllrname A.DLL E.EXE CPPWS35I=MYDLL35I

    dllrname CPPOS30.DLL CPPWS35I=MYDLL35I

`These commands will change A.DLL and E.EXE so that they will now require MYDLL35I.DLL instead of CPPWS35I.DLL. DLLRNAME will also rename CPPWS35I.DLL to MYDLL35I.DLL.`

`The following is the text of the report generated by the DLLRNAME utility:`

>     > dllrname a.dll e.exe cppws35i.dll cppws35i=mydll35i

>     Licensed Materials - Property of IBM
>     IBM C/C++ Tools Version 2.0 - DLL Rename Utility
>     (C) Copyright IBM Corp., 1993, All Rights Reserved
>     US Government Users Restricted Rights - Use, duplication or disclosure
>     restricted by GSA ADP Schedule Contract with IBM Corp.

>     Processing file a.dll.
>     1 external names in file a.dll have been left unchanged.
>     2 names found in file a.dll.
>     Executable name a has been left unchanged.
>     Imported DLL name CPPWS35I has been changed to mydll35i.
>     Imported DLL name KERNEL32 has been left unchanged.

>     Processing file e.exe.
>     1 external names in file e.exe have been left unchanged.
>     2 names found in file e.exe.
>     Executable name e has been left unchanged.
>     Imported DLL name CPPWS35I has been changed to mydll35i.
>     Imported DLL name KERNEL32 has been left unchanged.

>     Processing file cppws35i.dll.
>     1 external names in file cppws35i.dll have been left unchanged.
>     2 names found in file cppws35i.dll.
>     Executable name CPPWS35I has been changed to mydll35i.
>     Imported DLL name KERNEL32 has been left unchanged.
>     File cppws35i.dll has been renamed to mydll35i.DLL to match internal
>     DLL name.

>     Complete. 0 error(s) detected.

DLLRNAME Options