Chapter 10: Library: Command Line Interface

This chapter describes the Library utility.

10.1 Overview

Library enables you to groups individual files into one file. You also can use Library to group together static source code to create copy libraries. 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.

Warnings:

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.
Once a library file has been created, files within it can only be updated. It is not possible to extract files from a library file.
As files packaged in library files cannot be extracted, you cannot use the debugging features of Server Express with them.

You invoke Library from the operating system command line; it 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.

10.2 Invoking Library

To invoke Library, enter:

library filename [filename...] [==library-name]

where the parameters are:

`filename`	A file to be included in the library, or a library whose contents are to be included in the library, 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 `filename-1.lbr.`

filename 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 filename, 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 overlaid program is in a library, all the overlays must be in the same library as the program root segment.

Because filename 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. You must give the name of the new library by using the library-name parameter.

Example:

library $COBDIR/mylib1.lbr/linein.gnt == mylib2.lbr

10.3 Creating a Library Batch File

Batch files can be used with the load function to save you entering filenames individually. To create a batch file, enter the COBOL Editor; type one filename on each line in the file starting at column one; then save the file using a .lbt extension. This file contains the filenames 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 filenames with a pathname identifier.

10.4 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 filename 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, leaves it open for the rest of the compilation, so that the OF phrase can be omitted from the following COPY statements. See the chapter Directives for Compiler in your Server Express User's Guide for information on CANCELLBR.

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 filename of the following form:
```
path/library-name.lbr/filename.ext
```
This opens library-name.lbr on path and takes filename.ext from it. If the library does not exist or does not contain the file, a file not found error is returned.

Notes:

If you create a library while working in 64-bit mode, the library cannot be used by the 32-bit version of Library, nor by a 32-bit application. Similarly, a 32-bit library file, created in 32-bit mode or using an earlier version of Server Express or Object COBOL Developer Suite, cannot be used by the 64-bit version of Library, nor by a 64-bit application.
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 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.

Infomgr

Profiler