Chapter 9: Library: Command Line Interface

This chapter describes the Library utility, which groups individual files into one file. You also can use Library to group together static source code to create copylibraries.

9.1 Overview

Using Library gives you the following advantages:

Files are not so easily mislaid.
Whole suites of programs and/or sets of data files can be stored in one library file.
Performance is improved.
Once the library file is opened, all the files it contains are readily accessible. You access data files in libraries by the usual OPEN, READ, and CLOSE statements; OPEN and CLOSE become logical operations handled by the run-time system rather than the more time consuming physical operations.
Access to files in a library is maintained.
When you change directory you can still access files in a library in the original directory because the library catalog remains in memory.
Ease of use on floppy disk systems.
If an application contains a call to a library not currently on the logged-on drive and the library has been built into your program, the system prompts you to insert the .lbr file.

Warning: Files in libraries are read-only; you cannot access them via WRITE or REWRITE. Trying to open such a file using OPEN OUTPUT or OPEN I-O will open a file outside the library, then WRITE or REWRITE will update this file leaving the file in the library unchanged.

9.2 Operation

Library is invoked from the operating system command line and runs in batch mode. The following sections describe how to invoke Library, how to create a Library batch file and how to access files in libraries.

9.2.1 Invoking Library

To invoke Library, enter:

library file-name-1 [file-name-2...] [==library-name]

where the parameters are:

`file-name-n`	Either a file to be included in the library, a library whose contents are to be included, or a library batch file (see below).
`library-name`	The library to be saved. If this is not specified the library, takes the name of the first parameter, thus `file-name-1.lbr.`

file-name-n and library-name can include drive and/or path. If these are unspecified the current directory is assumed.

If you specify a .lbr library file as a file-name-n, the new library includes all the files contained in the old library.

For libraries that you are going to create and recreate frequently, you can write a library batch file (.lbt file) which contains the list of files to be included in the library. See the section Creating a Library Batch File below.

If an overlayed program is in a library, all the overlays must be in the same library as the program root segment.

Because file-name can include a library name as part of the path, you can use the Library Utility to copy files from one or more existing libraries into a new library. This is especially useful if you need to ship an application program that uses files supplied in utils.lbr; you can copy the necessary files from utils.lbr into a library of your own to ship with your application program. You must give the name of the new library by using the library-name parameter.

Example:

library $COBDIR/utils.lbr/linein.gnt == mylib.lbr

9.2.2 Creating a Library Batch File

Batch files can be used with the load function to save you entering file-names individually. To create a batch file, enter the COBOL Editor; type one file-name on each line in the file starting at column one; then save the file using a .lbt extension. This file contains the file-names only, not the actual files.

To run a library batch file, enter:

library batch.lbt == library-name

where the parameters are:

`batch`.lbt	The file you have just created, containing the list of files to be included in the library.
`library-name`	As described previously. However, in this case, if you do not specify, `library-name`, the library is assigned the name `batch.lbr.`

You can prefix any of the file-names with a path-name identifier.

9.2.3 Accessing Files in Libraries

The following program operations obtain access to files in libraries:

Calling a library opening routine.
Calling a program.
Using a COPY statement at compilation time.

Files within libraries can be found only if the library is open. There are several ways to open a library:

Calling program-name.
Calling a file-name without an extension causes all libraries currently opened to be searched for a program of that name. If the program is not found, and a library of that name exists, that library is opened. The program of that name within that library is run.

For example, if a library contains the program myprog.gnt, the root name of the library is also myprog, and there is no program outside of the library with the same name, then a CALL to myprog causes the library to be opened.

The library is left open, so it is added to the list of libraries which will be searched in a future CALL statement.
Calling library-name.lbr.
This opens library-name.lbr. It loads the catalog of the library into memory, thus making all the files and entry points that it contains available to the program.

The Directory Facility provides options for calling and canceling libraries explicitly. This can be useful during development and testing. See the chapter Directory Facility for details.
Using a COPY statement. For example,
```
copy "textname.ext" of "library-name.lbr"
```
This opens library-name.lbr, reads textname.ext from it, and depending on the CANCELLBR directive (see your Object COBOL User Guide) leaves it open for the rest of the compilation, so that the OF phrase can be omitted from the following COPY statements.

If the program is compiled with the COPYLBR directive, then:
```
copy "textname.ext" of "library-name"
```
is equivalent to the above, since this directive tells the Compiler that the name after OF in a COPY statement is a library-name, not a path.
Opening a file using a file-name of the following form:
```
path/library-name.lbr/file-name.ext
```
This opens library-name.lbr on path and takes file-name.ext from it. If the library does not exist or does not contain the file, a file not found error is returned.

Notes:

Attempting to open a library that is already open has no effect.
If you open a data file for input, and do not specify a device, all libraries currently open are searched. If you do specify a device, that device only is searched; libraries are not searched. This applies both to files declared using COBOL syntax and to byte-stream files (see the chapter Byte-stream File Handling in your Programmer's Guide to File Handling).
If multiple libraries are called, and each library contains a program of the same name, if that program is subsequently called, the copy of the program in the last library called is loaded and run. For example, if you call liba.lbr, libb.lbr, and libc.lbr, all of which contain the program myprog.gnt, and then call myprog.gnt, the copy in libc.lbr is loaded and run.
However, we strongly recommend that your applications are not designed to depend upon this behavior.
Once open, a library file remains open until it is canceled by the statement:
```
cancel "library-name.lbr" 
```
or a STOP RUN is executed. If any programs from the library file are in memory when the library file is canceled they remain in memory until they too are canceled.
If any programs in the library file have been called, and the library file is then canceled, load failures may result if the run-time system has to remove the called program from memory and then has to reload it. As the library file has been canceled, the run-time system is not able to find the program.
This restriction also applies to data files which reside in library files. If you cancel a library file that contains a data file which is currently open, and perform further file operations on that file, the results are unpredictable.

Forms-2

On-line Help System