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 © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Concurrency Support | Device Handling |