### Managing Libraries (OS/2, Windows)

To create and maintain library files (.lib) and module definition files (.def), use the IBM Library Manager (ILIB) utility.

If you are using DLL files, you can use the DLLRNAME utility to globally rename a DLL.

Using IBM Library Manager

Use the IBM Library Manager (also referred to as ILIB in this reference) to create and maintain libraries of object code, create import libraries and export object pairs, and generate module definition (.def) files. Using the ILIB utility, you can:

- Create a new library from a collection of objects
- Maintain a library
  - Add objects to an existing library
  - Delete objects from an existing library
  - Copy objects from an existing library
  - Replace objects in an existing library
- List the contents of a new or existing library
- Create import library/export object pairs from:
  - Module definition (.def) files
  - Objects generated from source files containing #pragma export and _Export statements
  - A combination of the above
- Generate module definition (.def) files from:
  - An existing DLL
  - Objects generated from source files containing #pragma export and _Export statements
  - A combination of the above

Running ILIB

Run ILIB by typing ilib at the command prompt.

You can specify parameters in the following ways:

1. Enter them directly on the command line.
2. Use the ilib environment variable.
3. Put them in a text file, called a response file, and specify the file name after the ilib command.
4. A combination of the above

You can press Ctrl+C or Ctrl+Break at any time while running ILIB to return to the operating system. Interrupting ILIB before completion restores the original library from a backup.

Notes:

1. When started, ILIB makes a backup copy of the original library in case it is interrupted or a mistake is made. Make sure you have enough disk space for both your original library and the modified copy.
2. The library must end with the extension .lib. If you do not specify an extension, the default extension, .lib, will be appended.
3. Both OS/2 and Windows support long file names. However, OS/2 will support long file names only if you have the High Performance File System (HPFS).

Using the Command Line

You can specify all the input ILIB needs on the command line. The syntax of the command line is:

>     ilib [options] [libraries] [@responsefile] [objects]

options
  Options that affect the behavior of ILIB
libraries
  The input library to be created or modified
responsefile
  The name of a text file containing ILIB options
objects
  Commands used to add, delete, replace, copy, and move object modules within the library

The ILIB command line is a free format command line; that is, the input arguments can be specified any number of times, in any order. The only exception is the /FREEFORMAT option, which does have a position restriction. See /FREEFORMAT, /NOFREEFORMAT below for more information.

Note: For compatibility with older librarians, a fixed format command line is also supported. To use the fixed format command line, the /NOFREEFORMAT option must be specified immediately following ilib on the command line, or as the first parameter in the ilib environment variable (see "Using the ilib Environment Variable" below for more information). The default command line format is free format.

Using the ilib Environment Variable

You can use the ilib environment variable to specify any default ILIB options. When the ilib command is invoked, the environment variable will be parsed before the command line.

Use the SET command to give value to the ilib environment variable. You can do this in the following ways:

Command Line

When the SET command is used on the command line, the values you specify are in effect for only that session. They override values previously specified.

You can append the original value of the variable using %variable%. For example,

> `SET ilib=/FREEFORMAT %ilib%`

would cause the ilib environment variable to be set to the original value of the ilib environment variable, with the /NOFREEFORMAT option specified ahead of any existing options.

Windows NT Control Panel

Windows NT allows you to update environment variables and have them take effect immediately (i.e. no reboot required) using the Windows NT Control Panel.

To set the ilib environment variable:

- Select the Main group by double-clicking on the Main icon.
- Select the System icon from the Main group by double-clicking on it.
- Enter ilib in the Variable field.
- Enter the value for the ilib environment variable in the Value field.
- Choose Set.

Windows 95 AUTOEXEC.BAT file

Windows 95 allows you to set environment variables in the AUTOEXEC.BAT file. Any environment variables set in this fashion are available in every user session.

Add a line to your AUTOEXEC.BAT file that sets the environment variable to the value you want. For example,

> `SET ilib=/NOBROWSE /NOBACKUP`

Because environment variables specified in your AUTOEXEC.BAT file are in effect for every session you start, this is a good place to specify options that you want to apply each time you invoke ILIB. However, after you make a change to your AUTOEXEC.BAT file, you must reboot your system to have the change take effect.

Using an ILIB Response File

To provide input to ILIB with a response file, type:

> `ilib @``responsefile`

where responsefile is the name of a file containing the same information that can be specified on the command line.

Why use a response file?

Use a response file for:

- complex and long commands you type frequently
- strings of commands that exceed the limit for command line length

A response file extends the command line to include everything in the response file. To split input to ILIB between the command line and a response file, put part of your input on the command line and specify a response file (preceding the response file name with the at sign (@)). No space can appear between the at sign and the file name.

The response file name can be any valid file name. To use special characters in the file name, such as a space or the @ symbol, the file name must be enclosed in quotes.

ILIB responds to input you place in a response file just as it does to input you enter on a command line. Any newline characters that occur between arguments are treated as spaces. This allows you to extend an ilib command to multiple lines.

Note: The options which specify which format command line to use (/FREEFORMAT or /NOFREEFORMAT) must be specified as the first parameter following ilib on the command line or as the first parameter in the ilib environment variable. They cannot be specified inside the response file.

Examples (Specifying ILIB Parameters)

The following examples show different methods for specifying parameters to ILIB.

The operations shown in each example create a new library, newlib.lib, and its listing file, newlib.lst, from the existing mylib.lib library. mylib.lib is unchanged, but newlib.lib has these changes:

- the module text is deleted
- the object file root.obj is appended as an object module with the name root
- the module table is deleted and is replaced by a new table
- the module string is copied into an object file named string.obj

Command Line Method

At the command line prompt, enter the following:

>     ilib /out:newlib.lib /list:newlib.lst mylib.lib
>          /remove:text root table /extract:string

Response File Method

First, create a response file with the following contents:

>     /out:newlib.lib /list:newlib.lst mylib.lib
>          /remove:text root table /extract:string

Then, assuming the name of the response file is response.fil, invoke ILIB with:

> `ilib @response.fil`

Controlling ILIB Input

ILIB determines the format of any input files by examining the file contents. Most file formats can be identified by the file header information. If the format of an input file is not recognized and seems to contain only ASCII, it is assumed to be a module definition (.def) file.

ILIB allows you to place any extension you choose on a file and still have it dealt with correctly.

Controlling ILIB Output

ILIB determines what output is to be produced by examining the options that you supply on the command line. The following options control ILIB output:

Option | Description
/O[UT]:filename | A static library is produced.
/GEND[EF]:filename | A module definition file (.def) is produced. The short form, /gd, may also be used.
/GENI[MPLIB]:filename | An import library/export object pair is produced. The short form, /gi, may also be used.
/L[IST]:filename | A list file is produced.

If none of the above are specified, ILIB will determine what is to be produced, as follows:

- If a DEF file is input to ILIB, an import library/export object pair will be produced.

  Note: On OS/2, ILIB will not create an export object.

  Note: If there are no exported symbols, then no import library will be produced.

- If a library and/or object(s) are input to ILIB, a library combining them will be produced.

ILIB will allow you to generate a DEF file directly from a DLL.

On Windows, however, since the only information that a DLL has in it is the undecorated (exported) names, symbol decoration (calling convention) and type information (function or data) cannot be determined.

ILIB will assume that all symbols exported from the DLL are _Optlink (the default linkage convention), unless an object file is provided that indicates otherwise.

On OS/2, ILIB will generate import libraries from a DLL when you invoke the command

> `ilib /gi foo.dll`

The best way of using ILIB with a DLL is to use ILIB to create a DEF file using the /gd option. Edit the DEF file to change decorations, where appropriate, and then run the DEF file through ILIB using the /gi option to produce an import library/export object pair.

Notes:

1. If an import library/export object pair is requested, on Windows, and only a DLL is specified as input, ILIB will generate an error.
2. On Windows, the IBM C and C++ Compilers linker requires that an export (EXP) file be provided, along with object files, to build a DLL. If you use ICC to link your DLL and supply only the object files and a DEF file as input, ICC will detect the absence of an EXP file and will automatically invoke ILIB with the object files and DEF file to build the EXP file. Then ICC will invoke the IBM C and C++ Compilers linker with the object files and EXP file to build the DLL. The process is the same on OS/2 as it was in VisualAge for C++ for OS/2, Version 3.0, except that ILIB replaces the functionality of the IMPLIB tool.

Examples (Controlling ILIB Output)

The following are examples showing how to control ILIB output.

Library

The invocation

> `ilib /out:newlib.lib text.obj mylib.lib`

will create the library newlib.lib out of the objects in text.obj and mylib.lib.

Note: Unless newlib.lib is specified as an input file, its contents will not be included in the library. If an output file already exists, and is not used as an input file, it will be replaced.

DEF File

The invocation

> `ilib /gd:winner.def winner.dll`

will create the module definition file winner.def from the DLL winner.dll.

Import Library/Export Object Pair

The invocation

> `ilib /gi winner.def`

will create an import library named winner.lib and an export object named winner.exp.

However, if no exported symbols are contained in winner.def, then winner.lib will not be produced.

Note: On OS/2, ILIB will not create an export object.

List File

The invocation

> `ilib /list:mylib.lst mylib.lib`

will generate the list file mylib.lst, based on the library mylib.lib, in the current directory.

ILIB Objects
ILIB Options
ILIB Error Messages