|
HP OpenVMS Systems Documentation |
|
OpenVMS Utility Routines Manual
FDL$RELEASE
The FDL$RELEASE routine deallocates the virtual memory used by the OpenVMS RMS control blocks created by FDL$PARSE. You must use FDL$PARSE to populate the control blocks if you plan to deallocate memory later with FDL$RELEASE. FormatFDL$RELEASE [fab_pointer] [,rab_pointer] [,flags] [,badblk_addr] RETURNS
Arguments
Condition Values Returned
Chapter 12
|
| Routine Name | Function |
|---|---|
| LBR$CLOSE | Closes an open library. |
| LBR$DELETE_DATA | Deletes a specified module's header and data. |
| LBR$DELETE_KEY | Deletes a key from a library index. |
| LBR$FIND | Finds a module by using an address returned by a preceding call to LBR$LOOKUP_KEY. |
| LBR$FLUSH | Writes the contents of modified blocks to the library file and returns the virtual memory that contained those blocks. |
| LBR$GET_HEADER | Retrieves information from the library header. |
| LBR$GET_HELP | Retrieves help text from a specified library. |
| LBR$GET_HISTORY | Retrieves library update history records and calls a user-supplied routine with each record returned. |
| LBR$GET_INDEX | Calls a routine to process modules associated with some or all of the keys in an index. |
| LBR$GET_RECORD | Reads a data record from the module associated with a specified key. |
| LBR$INI_CONTROL | Initializes a control index that the Librarian uses to identify a library. |
| LBR$INSERT_KEY | Inserts a new key in the current library index. |
| LBR$LOOKUP_KEY | Looks up a key in the current index. |
| LBR$OPEN | Opens an existing library or creates a new one. |
| LBR$OUTPUT_HELP | Retrieves help text from an explicitly named library or from user-supplied default libraries, and optionally prompts you for additional help queries. |
| LBR$PUT_END | Terminates the writing of a sequence of records to a module using the LBR$PUT_RECORD routine. |
| LBR$PUT_HISTORY | Inserts a library update history record. |
| LBR$PUT_RECORD | Writes a data record to the module associated with the specified key. |
| LBR$REPLACE_KEY | Replaces an existing key in the current library index. |
| LBR$RET_RMSSTV | Returns the last RMS status value. |
| LBR$SEARCH | Finds index keys that point to specified data. |
| LBR$SET_INDEX | Sets the index number to be used during processing of the library. |
| LBR$SET_LOCATE | Sets Librarian subroutine record access to locate mode. |
| LBR$SET_MODULE | Reads and optionally updates a module header. |
| LBR$SET_MOVE | Sets Librarian subroutine record access to move mode. |
1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM. |
12.2 Using the LBR Routines: Examples
This section provides programming examples that call LBR routines. Although the examples do not illustrate all the LBR routines, they do provide an introduction to the various data structures and the calling syntax.
The program examples are written in Compaq Pascal and the subroutine examples are written in Compaq Fortran. The listing of each program example contains comments and is followed by notes about the program. The highlighted numbers in the notes are keyed to the highlighted numbers in the examples.
Each sample program calls the LBR$INI_CONTROL routine and the LBR$OPEN routine before calling any other routine.
The one exception is that when you call the LBR$OUTPUT_HELP routine, you need not call the LBR$INI_CONTROL routine and the LBR$OPEN routine. |
The sample programs require access to various symbols derived from definition macros. Use the INHERIT attribute to access these symbols from definition macros in SYS$LIBRARY:STARLET.PEN.
The LBR$INI_CONTROL routine sets up a control index; do not confuse this with a library index. The control index is used in subsequent LBR routine calls to identify the applicable library (because you may want your program to work with more than one library at a time).
Do not alter the control index value. |
Upon completion of the LBR$INI_CONTROL routine, call the LBR$OPEN routine to open the library. Open an existing library, or create and open a new library, in either the UPDATE or READ mode, checking for an error status value of RMS$_FNF. If this error occurs, open the library in CREATE mode.
When you open the library, specify the library type and pass the file specification or partial file specification of the library file.
If you are creating a new library, pass the create options array. The CRE symbols identify the significant longwords of the array by their byte offsets into the array. Convert these values to subscripts for an array of integers (longwords) by dividing by 4 and adding 1. If you do not load the significant longwords before calling LBR$INI_CONTROL, the library may be corrupted upon creation.
Finally, pass any defaults for the file specification. If you omit the device and directory parts of the file specification, the current default device and directory are used.
When you finish working with a library, call LBR$CLOSE to close the library by providing the control index value. You must close a library explicitly before updates can be posted. Remember to call LBR$INI_CONTROL again if you want to reopen the library. LBR$CLOSE deallocates all the memory associated with the library, including the control index.
The order in which you call the routines between LBR$OPEN and LBR$CLOSE depends upon the library operations you need to perform. You may want to call LBR$LOOKUP_KEY or LBR$GET_INDEX to find a key, then perform some operation on the module associated with the key. You can think of a module as being both the module itself and its associated keys. To access a module, you first need to access a key that points to it; to delete a module, you first need to delete any keys that point to it.
Do not use LBR$INI_CONTROL, LBR$OPEN, and LBR$CLOSE for writing help text with LBR$OUTPUT_HELP. Simply invoke LBR$OUTPUT_HELP. |
Example 12-1 is a sample Compaq Pascal program that creates, opens, and then closes a text library. The program is summarized in the following steps:
| Example 12-1 Creating a New Library Using Compaq Pascal |
|---|
PROGRAM createlib(INPUT,OUTPUT);
(*This program creates a text library*)
TYPE (*Data type of*)
Create_Array = ARRAY [1..20] OF INTEGER; (*create options array*)
VAR (*Constants and return status error
codes for LBR$_OPEN & LBR$INI_CONTROL.
These are defined in $LBRDEF macro*)
LBR$C_CREATE,LBR$C_TYP_TXT,LBR$_ILLCREOPT,LBR$_ILLCTL, (1)
LBR$_ILLFMT,LBR$_NOFILNAM,LBR$_OLDMISMCH,LBR$_TYPMISMCH :
[EXTERNAL] INTEGER;
(*Create options array codes. These
are defined in $CREDEF macro*)
CRE$L_TYPE,CRE$L_KEYLEN,CRE$L_ALLOC,CRE$L_IDXMAX,CRE$L_ENTALL,
CRE$L_LUHMAX,CRE$L_VERTYP,CRE$L_IDXOPT,CRE$C_MACTXTCAS,
CRE$C_VMSV3 : [EXTERNAL]INTEGER;
Lib_Name : VARYING [128] OF CHAR; (*Name of library to create*)
Options : Create_Array; (*Create options array*)
File_Type : PACKED ARRAY [1..4] (*Character string that is default*)
OF CHAR := '.TLB'; (*file type of created lib file*)
lib_index_ptr : UNSIGNED; (*Value returned in library init*)
status : UNSIGNED; (*Return Status for function calls*)
(*-*-*-*-Function and Procedure Definitions-*-*-*-*)
(*Function that returns library
control index used by Librarian*)
FUNCTION LBR$INI_CONTROL (VAR library_index: UNSIGNED; (2)
func: UNSIGNED;
typ: UNSIGNED;
VAR namblk: ARRAY[l..u:INTEGER]
OF INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that creates/opens library*)
FUNCTION LBR$OPEN (library_index: UNSIGNED;
fns: [class_s]PACKED ARRAY[l..u:INTEGER] OF CHAR;
create_options: Create_Array;
dns: [CLASS_S] PACKED ARRAY [l3..u3:INTEGER] OF CHAR;
rlfna: ARRAY [l4..u4:INTEGER] OF INTEGER := %IMMED 0;
rns: [CLASS_S] PACKED ARRAY [l5..u5:INTEGER] OF CHAR :=
%IMMED 0;
VAR rnslen: INTEGER := %IMMED 0):
INTEGER; EXTERN;
(*Function that closes library*)
FUNCTION LBR$CLOSE (library_index: UNSIGNED):
INTEGER; EXTERN;
(*Error handler to check error codes
if open/create not successful*)
|
PROCEDURE Open_Error; (3) BEGIN WRITELN('Open Not Successful'); (*Now check specific error codes*) IF status = IADDRESS(LBR$_ILLCREOPT) THEN WRITELN(' Create Options Not Valid Or Not Supplied'); IF status = IADDRESS(LBR$_ILLCTL) THEN WRITELN(' Invalid Library Index'); IF status = IADDRESS(LBR$_ILLFMT) THEN WRITELN(' Library Not In Correct Format'); IF status = IADDRESS(LBR$_NOFILNAM) THEN WRITELN(' Library Name Not Supplied'); IF status = IADDRESS(LBR$_OLDMISMCH) THEN WRITELN(' Old Library Conflict'); IF status = IADDRESS(LBR$_TYPMISMCH) THEN WRITELN(' Library Type Mismatch') END; (*of procedure Open_Error*) BEGIN (* *************** DECLARATIONS COMPLETE ************************* *************** MAIN PROGRAM BEGINS HERE ********************** *) (*Prompt for Library Name*) WRITE('Library Name: '); READLN(Lib_Name); (*Fill Create Options Array. Divide by 4 and add 1 to get proper subscript*) Options[IADDRESS(CRE$L_TYPE) DIV 4 + 1] := IADDRESS(LBR$C_TYP_TXT); Options[IADDRESS(CRE$L_KEYLEN) DIV 4 + 1] := 31; (4) Options[IADDRESS(CRE$L_ALLOC) DIV 4 + 1] := 8; Options[IADDRESS(CRE$L_IDXMAX) DIV 4 + 1] := 1; Options[IADDRESS(CRE$L_ENTALL) DIV 4 + 1] := 96; Options[IADDRESS(CRE$L_LUHMAX) DIV 4 + 1] := 20; Options[IADDRESS(CRE$L_VERTYP) DIV 4 + 1] := IADDRESS(CRE$C_VMSV3); Options[IADDRESS(CRE$L_IDXOPT) DIV 4 + 1] := IADDRESS(CRE$C_MACTXTCAS); (*Initialize library control index*) status := LBR$INI_CONTROL (lib_index_ptr, (5) IADDRESS(LBR$C_CREATE), (*Create access*) IADDRESS(LBR$C_TYP_TXT)); (*Text library*) IF NOT ODD(status) THEN (*Check return status*) WRITELN('Initialization Failed') ELSE (*Initialization was successful*) BEGIN (*Create and open the library*) status := LBR$OPEN (lib_index_ptr, Lib_Name, Options, (6) File_Type); IF NOT ODD(status) THEN (*Check return status*) Open_Error (*Call error handler*) (7) ELSE (*Open/create was successful*) BEGIN (*Close the library*) status := LBR$CLOSE(lib_index_ptr); IF NOT ODD(status) THEN (*Check return status*) WRITELN('Close Not Successful') END END END. (*of program creatlib*) |
Each item in the following list corresponds to a number highlighted in Example 12-1:
| Previous | Next | Contents | Index |
