Concurrency Support | Device Handling |
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.
The Library Manager program enables you to dynamically create, update and edit Micro Focus .lbr files. The program name for Library Manager is Lbrman.
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.
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.
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.
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.
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
.
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
.
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:
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.
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
.
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.
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.
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
.
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.
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.
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.
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.
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.
The show-normal function prevents hidden files from being visible to Library Manager.
The show-hidden function makes the hidden files visible to Library Manager.
The lbrman-attrib-byte
data item contains a numeric
value between 0 and 3, indicating the library catalog entry type that is
present.
The file attribute indicates that this is a standard file catalog entry.
The entry-point attribute indicates that this is a program entry point catalog entry.
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
)
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
).
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 |
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 |
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.
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.
The operation was successful.
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.
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.
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.
An error occurred while opening a file.
Check the file status of the specified file to ensure that it is not locked.
An error occurred while closing a file.
Check the file status of the specified file to ensure that it is not locked.
An error occurred while reading a file.
Cancel the Library Manager program, check the file that caused the error and retry the operation.
An error occurred while writing to a file.
Cancel the Library Manager program, check the file that caused the error and retry the operation.
A selected file had previously been selected.
The program can be continued without taking any further action.
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.
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.
An invalid value is in lbrman-function
.
Correct your program.
A fatal error occurred while accessing the library catalog.
Cancel the Library Manager program and attempt to rebuild the library file.
The lbrman-size-byte-4
data item contains the size (in
bytes) of the specified file.
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.
Concurrency Support | Device Handling |