PreviousConcurrency Support Device HandlingNext

Chapter 15: Library Manager

The Library utility groups individual files into one file. It is primarily of use when you want to package your application with the Build utility, but can also be used in many other circumstances when you want to group files together.

Library is supplied with a program interface, called Library Manager, which enables you to dynamically create, update, and edit Micro Focus .lbr files. This interface is described in this chapter.

15.1 Library Manager Program Interface

The Library Manager program enables you to dynamically create, update and edit Micro Focus .lbr files. The program name for Library Manager is Lbrman.

15.1.1 Call Interface

Library Manager uses a simple call interface to indicate the action to be performed on a specified library file. If an operation is unsuccessful, an error is returned. You use the following call to invoke Lbrman:

call "lbrman" using lbrman-parameter-block

where lbrman-parameter-block is defined as:

 01 lbrman-parameter-block.
    03 lbrman-function                pic  x comp-x.
      78 78-lbrman-create-library         value 1.
      78 78-lbrman-include-file           value 2.
      78 78-lbrman-update-library         value 3.
      78 78-lbrman-close-library          value 4.
      78 78-lbrman-list-catalog           value 5.
      78 78-lbrman-first-file             value 6.
      78 78-lbrman-next-file              value 7.
      78 78-lbrman-delete-file            value 8.
      78 78-lbrman-rename-file            value 9.
      78 78-lbrman-hide-file              value 10.
      78 78-lbrman-reveal-file            value 11.
      78 78-lbrman-extract-file           value 12.
    03 lbrman-filename                pic x(255).
    03 lbrman-file-attribute          pic x comp-x.
      78 78-lbrman-show-normal            value 0.
      78 78-lbrman-show-hidden            value 1.
    03 lbrman-attrib-byte             pic x comp-x.
      78 78-lbrman-file                   value 0.
      78 78-lbrman-entry-point            value 1.
      78 78-lbrman-hidden-file            value 2.
      78 78-lbrman-hidden-entry-point     value 3.
    03 lbrman-time-byte               pic x(2) comp-x.
    03 lbrman-date-byte               pic x(2) comp-x.
    03 lbrman-size-byte               pic x(2) comp-x.
      78 78-lbrman-use-size-4             value 4.
03 lbrman-error-status            pic x comp-x.
      78 78-lbrman-success                value 0.
      78 78-lbrman-no-library             value 1.
      78 78-lbrman-empty-library          value 2.
      78 78-lbrman-invalid-file           value 3.
      78 78-lbrman-open-file              value 4.
      78 78-lbrman-close-file             value 5.
      78 78-lbrman-reading-file           value 6.
      78 78-lbrman-writing-file           value 7.
      78 78-lbrman-file-loaded            value 8.
      78 78-lbrman-writing-library        value 9.
      78 78-lbrman-no-match-found         value 10.
      78 78-lbrman-invalid-function       value 11.
      78 78-lbrman-catalog-fail           value 255.
    03 lbrman-return-filename         pic x(255).
    03 lbrman-size-byte-4             pic x(4) comp-x.


Note: An additional file size parameter is available for returning file sizes greater than 65535; the field is lbrman-size-byte-4. This field is only used if lbrman-size-byte is set to 4 on the first call to Library Manager.


15.1.2 Parameter Block

The following sections describe the data items that can be specified when calling Library Manager. The data items appear in the order in which they occur in the parameter block.

lbrman-function

The lbrman-function data item must contain a numeric value between 1 and 12, indicating to the Library Manager what action you require. If no valid value is specified for this data item, Library Manager takes no action. Functions 1-4 enable you to create and modify libraries. Function 5 enables you to obtain a listing of the contents of a library. Functions 6-12 enable you to edit library files and search for specific occurrences of requested files. If any of the functions 1-3 are used, then function 4 must precede any use of functions 5-12.

-lbrman-create-library Value 1

The create-library function initializes the Library Manager program to create a new library. To do so, set lbrman-function to a value of one and specify the path and name of the library to be created in lbrman-filename. As this call initializes Library Manager to create a new library file, it must be made before any file can be selected for inclusion in the library.

-lbrman-include-file Value 2

The include-file function enables you to add member files to an existing library file. It is used in conjunction with the create-library and update-library functions. After making the first call to initialize Library Manager using either the create-library function or the update-library function, you make a new call for each file that is to be included in a new library file or added to an existing library file. To do so, set lbrman-function to a value of two and specify the path and name of each member to be added in lbrman-filename.

-lbrman-update-library Value 3

The update-library function initializes the Library Manager program to add files to an existing library. To do so, set lbrman-function to a value of three and specify the existing library's name in lbrman-filename.

-lbrman-close-library Value 4

The close-library function is used to commit any calls to create, include or update a library that have been made. To do so, after all files have been selected, set lbrman-function to a value of four and specify the path and name of the original library in filename.

You should keep the following in mind when using functions 1-4 to create and modify libraries:

-lbrman-list-catalog Value 5

The list-catalog function provides a catalog of the library files, library name, and any entry points for the specified library. To obtain a listing of the catalog set lbrman-function to value 5 and specify the desired library in lbrman-filename. The listing is placed in the same path and has the same filename as the original library, with an extension of .pnt.

-lbrman-first-file Value 6

The first-file function searches for the file specification given in lbrman-filename and then returns the first matching filename in the library file. To do so, set lbrman-function to value six and specify the desired library in lbrman-filename. If no matching filename is found, an error is returned.

For example, if path\library-name.lbr\*.cbl is specified in lbrman-filename using this function, the first .cbl file in the library is returned. This function can be used to list either the first file in a library using path\library-name.lbr\*.* or to test if a file exists in a library using path\library-name.lbr\filename.ext.

-lbrman-next-file Value 7

The next-file function is used in conjunction with the first-file function to enable the whole of a library catalog to be listed or to list all particular occurrences of certain file types, for example "*.cbl" files. To do so, after using the first-file function, set lbrman-function to value seven and specify the desired library file in the lbrman-filename. If no matching filename is found, an error is returned. You can repeat this function until you receive an error indicating that there are no further files to be found.

-lbrman-delete-file Value 8

The delete-file function enables you to delete a file from an existing library file. To do so, set lbrman-function to value eight and specify the drive, path, library name and filename of the desired file in lbrman-filename.

For example, specifying "d:\tictac.lbr\tictac.gnt" would delete tictac.gnt from the library file tictac.lbr on drive D:.

Member files can be added to a library file that has had member files deleted as long as the library is not empty. Library Manager treats a library file that has had its last member file deleted as no longer available for use. If you need to use the library again, you must delete it and create a fresh version.

-lbrman-rename-file Value 9

The rename-file function enables you to rename a file within an existing library file. To do so, set lbrman-function to value nine and specify the existing path, library filename, and filename in lbrman-filename and the new filename in lmrman-return-filename.

-lbrman-hide-file Value 10

The hide-file function enables you to make a library file invisible to the RTS, Directory Facility, and Library. To do so, set lbrman-function to value 10 and specify the file to be hidden in lbrman-filename data item. The file is only hidden; it still exists, and you can restore it using the reveal-file function.

The hide-file function is useful when changing files contained within library files. The member file in the library file can be hidden, so that when called it cannot be found by the RTS, thus forcing another updated version to be used.

-lbrman-reveal-file Value 11

The reveal-file function restores a hidden file so that it is again visible to the run-time system, Directory Facility, and Library. To do so, set lbrman-function to value 11 and specify the name of the hidden file in lbrman-filename.


Notes: If you want to use functions 10 and 11 to find files that have been hidden, you must set lbrman-file-attribute to value 1. If it is not set to 1, then hidden files are not recognized.

You are recommended to keep a record of files you have hidden using the hide-file function as the filename is required for the reveal-file function to restore them.


-lbrman-extract-file Value 12

The extract-file function extract a member file from an existing library file and places the information in a specified location. To do so, set lbrman-function to value 12 and specify the name of the member file to be extracted in lbrman-filename and the details of the new location in lbrman-return-filename. The original member file remains in the library file.


Note: The editing functions (values 6-12) can be used only on library files that already exist; you cannot use them to edit library files that are currently being created or updated.


lbrman-filename

The lbrman-filename data item contains the file specification for the target library file for a Library Manager operation. The file specification generally contains a drive, path, filename, and extension to uniquely identify the target file. However, when using the hide-file and reveal-file functions, you can specify a wildcard character along with the drive and path. If the drive and path are not provided in a file specification, the current drive and directory are assumed.

lbrman-file-attribute

The lbrman-file-attribute data item contains a numeric value of either 0 or 1, which determines whether or not files that have been hidden using the hide-file function are visible to the Library Manager program. The default value of this data item is 0.

-lbrman-show-normal Value 0

The show-normal function prevents hidden files from being visible to Library Manager.

-lbrman-show-hidden Value 1

The show-hidden function makes the hidden files visible to Library Manager.

lbrman-attrib-byte

The lbrman-attrib-byte data item contains a numeric value between 0 and 3, indicating the library catalog entry type that is present.

-lbrman-file Value 0

The file attribute indicates that this is a standard file catalog entry.

-lbrman-entry-point Value 1

The entry-point attribute indicates that this is a program entry point catalog entry.

-lbrman-hidden-file Value 2

The hidden-file attribute indicates that the file catalog entry has been hidden.

The catalog entry is not visible to the RTS. It can be accessed by Library Manager functions if the lbrman-file-attribute is set to 1. (78-lbrman-show-hidden)

-lbrman-hidden-entry-point Value 3

The hidden-entry-point attribute indicates that the program entry point has been hidden. The catalog entry is not visible to the RTS. It can be accessed by Library Manager functions if the lbrman-file-attribute is set to 1. (78-lbrman-show-hidden).

lbrman-time-byte

The lbrman-time-byte data item contains the time the specified library file was created or updated in the following format:

Bits 15-11 - Hours 0-23
Bits 10-5 - Minutes 0-59
Bits 4-0 - Bi-seconds 0-29

lbrman-date-byte

The lbrman-date-byte data item contains the date the specified library file was created or updated in the following format:

Bits 15-9 - Years 0-119 (1980-2099)
Bits 8-5 - Months 1-12
Bits 4-0 - Days 1-31

lbrman-size-byte

The lbrman-size-byte data item contains the size (in bytes) of the specified file.


Note: An additional file size parameter is available for returning file sizes greater than 65535, the field is lbrman-size-byte-4. This field is only used if lbrman-size-byte is set to 4 on the first call to Library Manager.


lbrman-error-status

The lbrman-error-status data item contains a value between 0 and 11 or 255, indicating whether or not an error has occurred during a call to Library Manager. A value of 0 represents a successful call, while values between 1 and 11 and 255 indicate the type of error that has occurred. After each call is made to Library Manager, you should check to see that this data item is equal to zero; if it is not, then an error has occurred during the call and appropriate action should be taken by the calling program.

-lbrman-success Value 0

The operation was successful.

-lbrman-no-library Value 1

An attempt has been made to add a member file to a library file, to select a member file to build into a library file or to close a library file when no library file has been specified.

Cancel the Library Manager program, specify a library filename and then retry the operation.

-lbrman-empty-library Value 2

An attempt was made to include the contents of a library file in another library file when the first library file either did not exist or contained no files of the specified type.

Ensure that the correct library filename was specified.

-lbrman-invalid-file Value 3

A file was selected that either did not exist, was not valid (in the case of a library file) or was of the wrong type.

Ensure that the correct file was specified.

-lbrman-open-file Value 4

An error occurred while opening a file.

Check the file status of the specified file to ensure that it is not locked.

-lbrman-close-file Value 5

An error occurred while closing a file.

Check the file status of the specified file to ensure that it is not locked.

-lbrman-reading-file Value 6

An error occurred while reading a file.

Cancel the Library Manager program, check the file that caused the error and retry the operation.

-lbrman-writing-file Value 7

An error occurred while writing to a file.

Cancel the Library Manager program, check the file that caused the error and retry the operation.

-lbrman-file-loaded Value 8

A selected file had previously been selected.

The program can be continued without taking any further action.

-lbrman-writing-library Value 9

An error occurred while writing to a library file.

Cancel the Library Manager program, check the file that caused the error and retry the operation.

-lbrman-no-match-found Value 10

No match was found for the file specified with the first-file, next-file, delete-file or extract-file functions.

Enter a new file specification and retry the operation.

-lbrman-invalid-function Value 11

An invalid value is in lbrman-function.

Correct your program.

-lbrman-catalog-fail Value 255

A fatal error occurred while accessing the library catalog.

Cancel the Library Manager program and attempt to rebuild the library file.

lbrman-size-byte-4

The lbrman-size-byte-4 data item contains the size (in bytes) of the specified file.

lbrman-return-filename

The lbrman-return-filename data item contains a specification for a library file output by the extract-file and rename-file functions. The file specification generally contains a drive, path, filename and extension to identify the output file uniquely. If the drive and path are not provided in a file specification, the current drive and directory are assumed.


Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousConcurrency Support Device HandlingNext