═══ 1. Special Notices ═══ References in this help to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM licensed program in this help is not intended to state or imply that only IBM's licensed program may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this help. The furnishing of this help does not give you any license to these patents. The following terms, denoted by an asterisk (*) in this help, are trademarks of the IBM Corporation in the United States and/or other countries: IBM OS/2 Operating System/2 Presentation Manager WorkFrame/2. The following terms used in this publication are trademarks of Microsoft Corporation. They are denoted by a double asterisk (**) when they appear in the text. Microsoft Windows. This help contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. ═══ 2. Introduction ═══ The IBM* Library Manager (also referred to as LIB in this reference) lets you create and maintain libraries of object code. Library files are given the extension of ".LIB" (as in MYLIB.LIB). High Performance File System (HPFS) file names are also supported as long as the file names ends with ".LIB" (as in MYLIBRARYFILE.NEW.LIB). LIB works with standard libraries and OS/2* import libraries. It does not work with Dynamic Link Libraries (DLL). Use LIB to: o Create a new library o Add, delete, or replace modules in a library o Copy object modules in a library to object files o List the contents of a library ═══ 3. Running LIB ═══ Run LIB by typing "LIB" at the operating system prompt. Parameters can be supplied by one of three methods: 1. Enter them directly on the command line. 2. Respond to prompts. 3. Put them in a text file called a response file and specify the file name after the LIB command. To enter more commands than can be conveniently entered on one line, type an ampersand (&) at the end of the line and press Enter to extend the command field to a new line. The ampersand can be used with all three input methods. You can press Ctrl+C or Ctrl+Break at any time during a LIB run to return to the operating system. Interrupting LIB before completion restores the library from the backup. Note: o When started, LIB 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. o The library must end with the extension ".LIB". If an extension is not specified, the default extension, ".LIB", will be appended. HPFS file names are supported. Hence, MYLIBRARYNAME.NEW.LIB is still a valid library. Note that this implies that MYLIBRARYNAME.NEW refers to MYLIBRARYNAME.NEW.LIB. o If you enter an input library name and follow it immediately with a semicolon (;), LIB performs a consistency check on the library and takes no other action. ═══ 3.1. Using the Command Line ═══ You can specify all the input LIB needs on the command line. The syntax of the command line is: LIB [options] inlibrary [commands] [[,listfile] [, outlibrary]] [;] inlibrary The input library to be modified. options Options that affect the way LIB runs. commands Commands used to add, delete, replace, copy, and move modules within the library. listfile The name for a listing file. If you don't specify a name, no file is created. outlibrary The output library created from the input library. If you don't specify an output library, your input library is replaced with the modified version (see below). Commas are used to separate commands and options. The semicolon (;) is used to mark the end of the command line. ═══ 3.2. Using LIB Prompts ═══ If you don't provide input to LIB on the command line, LIB prompts you for the information it needs by displaying the following messages, one at a time: Prompt Enter Library name Name of the input library to be modified. Operations Commands to modify the library. If no operations are specified, the input library is unchanged. List file Name for a listing file If no listing file is specified, no listing file is created. Output library Name of the output library to be created from the input library. If no output library is specified, LIB modifies the input library. Enter the same information that you would enter when using the LIB command line. Notes o LIB waits for you to respond to each prompt before displaying the next prompt. If you notice that you have entered an incorrect response to a previous prompt, press Ctrl+C or Ctrl+Break to exit LIB and begin again. o A file name must be entered at the Library name: prompt. To choose a default response for any of the other prompts, press Enter. To choose default responses for all remaining prompts, type a semicolon (;) and press Enter. ═══ 3.3. Using a LIB Response File ═══ To provide input to LIB with a response file, type: LIB @responsefile; The field responsefile is the name of a file containing the same information that can be specified on the command line. In a sense, a response file extends the command line to include everything in the response file. To split input to LIB 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 (@)). The response file name can be any valid OS/2 file. To use special characters such as a space or the @ symbol, the filename must be enclosed in quotes. LIB responds to input you place in a response file just as it does to input you enter on a command line or after a prompt. Using a newline character in the response file is the equivalent of pressing the Enter key after a LIB prompt. A response file uses one text line for each prompt. To extend a LIB command to multiple lines, end each line except the last with an ampersand (&). Responses must appear in the same order as the prompts. If a response for one of the prompts does not appear, the default is used. Use a response file for: o Complex and long commands you type frequently o Strings of commands that exceed the limit for command line length. ═══ Specifying LIB Parameters - Examples ═══ This panel shows you examples of each method for specifying parameters to LIB. In the examples, the following operations 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: o The contents are case-insensitive. o The module TIM is deleted. o The object file SIMON.OBJ is appended as an object module with the name SIMON. o The existing module KEHM is deleted and is replaced by a new KEHM which is appended after SIMON. o The module LAM is copied into an object file named LAM.OBJ. Command Line Method At the operating system prompt, enter the following two lines. LIB /I MYLIB, SIMON-TIM-+KEHM & *LAM, NEWLIB.LST, NEWLIB; LIB Prompts Method To have LIB prompt you for input, enter LIB with no parameters. Library name: /I MYLIB Operations: +SIMON-TIM-+KEHM & Operations: *LAM List file: NEWLIB.LST Output library: NEWLIB Response File Method First, create a response file with the following contents. /I MYLIB +SIMON-TIM-+KEHM & *LAM NEWLIB.LST NEWLIB Then, assuming the name of the response file is response.fil, invoke LIB with: LIB @RESPONSE.FIL; Note that the lines in the response file match the entries you would have made with the prompting method. Even the ampersand character (&), the continuation character, is used in the same way. ═══ 4. Creating a New Library ═══ To create a new library file, give the name of the library file you want to create in the inlibrary field on the command line (or at the Library name: prompt when using LIB prompts). Note: A library file is automatically created if the library file name you specify is immediately followed by a command, comma, or semicolon. In this case, the prompt does not appear. If the name you specify for the new library file already exists, LIB assumes that you want to modify the existing file. When you give the name of a file that does not currently exist, LIB displays the following prompt: Library does not exist. Create library? (y or n) Type y to create the file; type n to terminate the LIB run. If you specified an extension other than .LIB, LIB will try to append the .LIB extension to the entire file name. If a library name is not entered, LIB will prompt you with Library name:. ═══ 5. Modifying a Library ═══ You can use LIB to alter the contents of any object code library. For example, if you work with high level language libraries, you may want to replace a standard routine with your own version of the routine. You may also want to add a new routine to the standard library so that your routine is available along with the standard routines. To modify an existing library file, give the name of the library file you want to modify in the inlibrary field of the command line (or at the Library name: prompt when using LIB prompts). In the command field, enter one or more commands to add, delete, or replace modules in the input library. Each command consists of a command character immediately followed by the name of the module or object file. Note that the Add command can be used to combine libraries as well as to add object files to a library. See: Add Command (+) Delete Command (-) Replace Command (-+) LIB creates a backup file of the library being modified if it already exists. This backup file has the same name as the original library with ".BAK" as the extension. ═══ 6. Copying Object Modules to Object Files ═══ To copy a module from a library file to an object file, give the name of the library file in the inlibrary field on the command line (or at the Library name: prompt when using LIB prompts). The command field on the command line allows you to move or copy modules. Command Action copy (*) LIB copies the module to an object file and retains the module in the library. move (-*) LIB copies the module to an object file and deletes the module from the library. ═══ 7. Listings ═══ Listings give you the exact names of modules and public symbols, allowing you to inspect the contents within a library. To generate a listing file, enter the following on the command line (or at the appropriate LIB prompt): o The name of the library file in the inlibrary field o The name of the listing file in the listfile field When generating a listing file, the amount of detail can be varied. The level of detail is specified with the /Listlevel:n option, with three different levels being available. Level 1 is the default. It is the fastest to generate and contains the least amount of information. All modules are listed in order of occurrence. For each module, the level 1 option: 1. Shows the relative position and size of each module. 2. Lists all the public symbols defined in the module. 3. Lists all external symbols which must be resolved at link time. Level 2 contains all the information of level 1. In addition, for each external symbol, level 2 shows which module in the library contains the required public symbols for resolving at link time. This can be overridden if a module is linked to another module that already contains the symbol. Level 3 contains all the information of level 2. In addition, Level 3 displays the technical characteristics of the library. This option also contains a dump of the extended dictionary. This is useful to determine which modules will be implicitly linked in whenever a particular module is linked in. Note: If you are using the IBM C/C++ Tools product, definitions with mangled names will be listed with the demangled form in brackets. Sample Cross Reference Listing LIB /LISTLEVEL:2 NEWLIB, NEWLIB.LST; The command above directs LIB to place a listing of the contents of NEWLIB.LIB into the file NEWLIB.LST. No path specification is given for NEWLIB.LST. By default, the file created is put in the current directory. ═══ Listing Example ═══ The syntax used to generate a listing file with level 3 option is: LIB /L:3 NEWLIB, NEWLIB.LST; This command generates the following listing file called NEWLIB.LST: IBM (R) Library Manager Version 2.00 Copyright (C) IBM Corporation 1991, 1992. All rights reserved. Library name : D:\TEMP\NEWLIB.LIB Listing detail level : 3 ┌───────────────────────────────────────────────────┐ ┌─┤Number of the module within the parent library. The│ │ │first module number in the listing file is 00000. │ │ └───────────────────────────────────────────────────┘ │ ┌──────────────────────────────────────┐ │ │Name of the module within the library.│ │ └──┬───────────────────────────────────┘   00000:francis(OFFSET:0x00000010, SIZE:0x000004ca):   │ ┌───────────┴─────────────────────────┐ │ │Size (in bytes) of the object module.│ │ └─────────────────────────────────────┘ ┌────────┴───────────────────────────────────────────────────┐ │Relative offset (in bytes) of the module within the library.│ └────────────────────────────────────────────────────────────┘ ┌────────────────────────────────┐ - Public Definitions:─┤Symbols defined by the module. │ francis └────────────────────────────────┘ ┌──────────────────────────────┐ │Symbols defined in a different│ - External Definitions:────┤module within the library. │ DosAllocMem └──────────────────────────────┘ _ilog2 _critlib_except _DosSelToFlat _DosFlatToSel 00001:lam (OFFSET:0x000004e0, SIZE:0x000001d1): - Public Definitions: lam - External Definitions: francis <- 00000:francis────┐ _critlib_except │ _DosSelToFlat ┌───────────────────────────────────┴────────────┐ _DosFlatToSel │Number and name of the module within the library│ │that defines the corresponding public symbol. │ └────────────────────────────────────────────────┘ 00002:hazlett (OFFSET:0x000006c0, SIZE:0x0000021a): - Public Definitions: hazlett - External Definitions: DosFreeMem _critlib_except _DosSelToFlat _DosFlatToSel _pBucketArr 00003:simon (OFFSET:0x000008e0, SIZE:0x00000428): - Public Definitions: simon - External Definitions: _ilog2 hazlett <- 00002:hazlett francis <- 00000:francis _critlib_except _DosSelToFlat _DosFlatToSel _pBucketArr 00004:kehm (OFFSET:0x00000d10, SIZE:0x00000342): - Public Definitions: _kehm - External Definitions: DosFreeMem _critlib_except _DosSelToFlat _DosFlatToSel _pBucketArr The following information describes the characteristics of the library. Page size = 16 The Flags field determines case sensitivity. 0x1 indicates case sensitivity. 0x0 indicates no case sensitivity. Flags = 0x0 Contains extended dictionary Total number of modules = 5 Total bytes for modules = 4592 Total number of symbols in dictionary = 10 Maximum number of symbols in dictionary = 74 Total number of pages for the dictionary = 2 The following is the extended dictionary information. The number in parentheses indicates the number of dependencies. It is followed by the list of modules In this case, modules 0, 2, and 4 have no dependencies, module 1 is dependent on module 0, and module 3 is dependent on modules 0 and 2. ======== Dependencies by Module ======== Module 00000 : (00000) Module 00001 : (00001) 00000 Module 00002 : (00000) Module 00003 : (00002) 00000 00002 Module 00004 : (00000) ═══ 8. Commands ═══ LIB commands are used to manipulate modules in a library. A single LIB run uses multiple commands in any order. Each command consists of a one or two character command symbol immediately followed by the name of the module or file that is the subject of the command. For example, +EFREM.OBJ adds the EFREM.OBJ object file to a library as EFREM. Command Action [+] Adds an object file or library to a library - Deletes a module from a library -+ Replaces a module in a library * Copies a module from a library to an object file -* Moves a module (copies the module and then deletes it) Notes o If you want to enter more commands than can be conveniently entered on one line, type an ampersand (&) and press Enter at the end of the line. This extends the command field to the next line. o When processing commands, LIB processes all copy commands first. LIB then processes the deletions and processes the additions last. o LIB never makes changes to your input library while it runs; it copies the library and makes changes to that copy. However, if you don't specify an output library, LIB overwrites the input library with the modified copy at the end of normal processing. See Using the LIB Command Line for more information. ═══ 8.1. Add Command (+) ═══ Use the add command to add an object module or library to a library. The add command is issued using the plus (+) sign or leaving a blank space. Adding an Object Module to a Library Type the name of the object file to be added immediately after the plus sign. The ".OBJ" extension may be omitted. LIB uses the base name of the object file as the name of the object module in the library. For example, if the object file B:\CURSOR.OBJ is added to a library file, the name of the corresponding object module is CURSOR. Object modules are always added to the end of a library file. Combining Two Libraries Give the name of the library file to be added, including the ".LIB" extension, immediately after the plus sign (+). A copy of the contents of that library is added to the library file being modified. If both libraries contain a module with the same name, LIB ignores the second module with that name. LIB adds the modules of the library to the end of the library being changed. Note that the added library still exists as an independent library because LIB copies the modules without deleting them. Examples LIB MYLIB +EFREM; The command above adds the file EFREM.OBJ to the library MYLIB.LIB. LIB NEWLIB +KAREN.LIB; The command above adds the contents of the library KAREN.LIB to the library NEWLIB.LIB. The library KAREN.LIB is unchanged after this command is executed. ═══ 8.2. Delete Command (-) ═══ Use the delete command (-) to delete an object module from a library. After the minus sign, give the name of the module to be deleted. Module names do not have path names or extensions. Example LIB MYLIB -EFREM; The command above deletes the module EFREM from the library MYLIB.LIB. ═══ 8.3. Replace Command (-+) ═══ Use the replace command (-+) to replace a module in a library. Following the symbol, give the name of the module to be replaced. To replace a module, LIB performs the following steps: 1. Deletes the existing module 2. Searches the current directory for the ".OBJ" file with the same file name as the deleted module 3. Appends to the library a copy of the object file with the original module name Example LIB MYLIB -+EFREM; The command above replaces the module EFREM in the MYLIB.LIB library with the contents of EFREM.OBJ from the current directory. The file EFREM.OBJ in the current directory is not altered. ═══ 8.4. Copy Command (*) ═══ Use the copy command (*) to copy a module from the library into an object file of the same name. The module remains in the library. When LIB copies the module to an object file, it adds the ".OBJ" extension to the module name and places the file in the current directory. If a file with this name already exists, LIB overwrites the existing ".OBJ" file. Example LIB MYLIB *EFREM; The command above copies the module EFREM from the MYLIB.LIB library to a file called EFREM.OBJ in the current directory. The module EFREM in MYLIB.LIB is not altered. ═══ 8.5. Move Command (-*) ═══ Use the move command (-*) to copy an object module from the library file to an object file. The object module is then deleted from the library file. This operation is equivalent to copying the module to an object file, then deleting the module from the library. Example LIB MYLIB -*KEELING; The command above moves the module KEELING from the MYLIB.LIB library to a file called KEELING.OBJ in the current directory. Upon completion of this process, MYLIB.LIB no longer contains the module KEELING. ═══ 9. Options ═══ Usage Notes: o Option characters are not case sensitive; /H and /h are equivalent. o The characters in brackets can be omitted; /H and /HELP are equivalent. o Unless otherwise specified, most options and commands need only the first letter of their names to be used. The following is a summary of LIB options: Option Action /? or ? or /H[ELP] Display Help /I[GNORECASE] Turn Case Sensitivity Off /NOE[XTDICTIONARY] Disable Generation of Extended Dictionary /NOI[GNORECASE] Turn Case Sensitivity On /NOL[OGO] Suppress LIB Banner /Q[UIET] Suppress LIB Banner /P[AGESIZE] Set Library Page Size /L[ISTLEVEL] List Current Contents of Library ═══ 9.1. /I Option ═══ Turn Case Sensitivity Off (/I) Syntax: /I[GNORECASE] Purpose: Turns off case sensitivity for symbols By default, case sensitivity is off. Use this option when you are combining a library that was created with case sensitivity on (using the /NOI option) with others that are not case sensitive. The resulting library is not case sensitive. ═══ 9.2. /NOE Option ═══ Disable Generation of Extended Dictionary (/NOE) Syntax: /NOE[XTDICTIONARY] Purpose: Disables generation of extended dictionary The extended dictionary is an optional part of the library that increases linking speed. However, using an extended dictionary requires more memory. The space reserved for the extended dictionary is limited to 64K, no more can be allocated. If LIB reports an out-of-memory error, you may want to use this option. As an alternative, you can split large libraries into smaller libraries to use in linking. ═══ 9.3. /NOI Option ═══ Turn Case Sensitivity On (/NOI) Syntax: /NOI[GNORECASE] Purpose: Turns on case sensitivity By default, case sensitivity is off (/I option). Using this option allows symbols that differ only in case, such as Sine and SINE, to be included as separate symbols in the same library. Note that when you create a library with the /NOI option, LIB marks the library internally to indicate that /NOI is in effect. If you combine multiple libraries, and any one of them is marked /NOI, then the output library is marked /NOI. ═══ 9.4. /P Option ═══ Set Library Page Size (/P) Syntax: /P[AGESIZE]: n Purpose: Sets library page size This option specifies the library page size of a new library or changes that of an existing library. The new page size n must be an integer value representing a power of 2 between the values 16 and 32,768. A library's page size affects the alignment of modules stored in the library. Modules are always aligned to start at a position that is a multiple of the page size (in bytes) from the beginning of the file. The default page size for a new library is 16 bytes. For an existing library, the default is its current page size. Because of LIB's indexing technique, the larger the page size, the more modules a library can hold. Each module requires an average of n/2 bytes of storage space. Therefore, you should use a small page size unless you need to put a very large number of modules in a library. Another consequence of LIB's indexing technique is that the page size limits the size of the library file to n * 65,536. For example, the option /P:16 limits the size to 1 megabyte (16 * 65,536 bytes). ═══ 9.5. / ? or ? or /H Option ═══ Display Help Syntax: /H[ELP] or /? or ? Purpose: Displays help on LIB A brief summary of LIB syntax is displayed. ═══ 9.6. /NOL or /Q Option ═══ Suppress LIB Banner Syntax: /NOL[OGO] or /Q[UIET] Purpose: Suppresses the LIB copyright notice. This option suppresses the banner message when LIB is started. It can be used in batch files. ═══ Library ═══ A library is an organized collection of object code which contains functions and data that are already assembled or compiled. Once an object file is incorporated into a library, it becomes an object module. Libraries are used to: o Support high level languages. Most compilers include libraries to perform standard operations, such as input/output and floating-point mathematics. When your program refers to a library routine, the compiler and linker combine the library routine with your program. o Perform complex and specialized activities, such as database management or advanced graphics. You can use your own libraries or specialized libraries supplied by a vendor. o Support your own work. If you have created routines that you use with a variety of programs, you may want to consolidate these routines into a library. You can then link to one library. ═══ Output Library ═══ If you specify a file in outlibrary, LIB creates a new output file with the modifications and leaves your input file intact. Otherwise, LIB replaces your input file with the modified file. In the latter case, a backup of your original input file is stored in the current directory with the file name extension ".BAK". ═══ Object File ═══ An object file is produced by a compiler or assembler from one or more source files. An object file has an extension of ".OBJ". (as in "MYPROJ.OBJ"). In LIB, HPFS file names are also supported as long as the file name ends with ".OBJ" (as in "MYOBJECTFILE.NEW.OBJ"). ═══ Object Module ═══ The object module is a self-contained unit within a library of precompiled or preassembled routines. When individual object files are combined into a single library file, they become object modules. In LIB, an object module is referred to by its name, without a file extension. For example, assume that the object file KEELING.OBJ is inserted into a library. It then becomes an object module and is simply referred to as KEELING.