Updated: 11 December 1998 |
OpenVMS Utility Routines Manual
Previous | Contents | Index |
The FDL$PARSE routine parses an FDL specification, allocates OpenVMS RMS control blocks (FABs, RABs, or XABs), and fills in the relevant fields.
FDL$PARSE fdl_desc ,fdl_fab_pointer ,fdl_rab_pointer [,flags] [,default_fdl_desc] [,stmnt_num]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
fdl_desc
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor---fixed-length string descriptor
Name of the FDL file or the actual FDL specification to be parsed. See the description of the fdl_desc argument in the section on FDL$CREATE for details.fdl_fab_pointer
OpenVMS usage: address type: longword (unsigned) access: write only mechanism: by reference
Address of an RMS file access block (FAB). The fdl_fab_pointer argument is the address of a longword that receives the address of the FAB. FDL$PARSE both allocates the FAB and fills in its relevant fields.fdl_rab_pointer
OpenVMS usage: address type: longword (unsigned) access: write only mechanism: by reference
Address of an RMS record access block (for VAX, this is the RAB; for Alpha, it is the RAB64). The fdl_rab_pointer argument is the address of a longword that receives the address of the RAB or RAB64. FDL$PARSE both allocates the RAB or RAB64 and fills in any fields designated in the FDL specification.For Alpha, the 64-bit record access block (RAB64) consists of the traditional 32-bit RAB followed by some 64-bit fields. The RAB64 is automatically allocated for Alpha users, who can either use it as a RAB64 or overlay it with the 32-bit RAB definition and use it as a traditional 32-bit RAB.
flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by reference
Flags (or masks) that control how the default_fdl_desc argument is interpreted and how errors are signaled. The flags argument is the address of a longword containing the control flags. If you omit this argument or specify it as zero, no flags are set. The flags and their meanings are as follows:
Flag Function FDL$V_DEFAULT_STRING Interprets the default_fdl_desc argument as an FDL specification in string form. By default, the default_fdl_desc argument is interpreted as the file name of an FDL file. FDL$V_FDL_STRING Interprets the fdl_desc argument as an FDL specification in string form. By default, the fdl_desc argument is interpreted as the file name of an FDL file. FDL$V_LONG_NAMES Allocates and returns a long name access block (NAML) linked to the returned RMS file access block (FAB). The appropriate values are set in the NAML and FAB blocks so that the long file name fields of the NAML block will be used. By default, a name block is not allocated and the file name fields of FAB are used.
If the FDL$V_LONG_NAMES flag is set, then the FDL$V_LONG_NAMES bit must also be set in the flags argument to the FDL$RELEASE routine to ensure that memory allocated for the NAML block is deallocated properly.
This flag is valid for OpenVMS Alpha only.
FDL$V_SIGNAL Signals any error. By default, the status code is returned to the calling image. By default, an error status is returned rather than signaled.
default_fdl_desc
OpenVMS usage: char_string type: character-coded text string access: read only mechanism: by descriptor---fixed-length string descriptor
The default_fdl_desc argument is the address of a character-string descriptor pointing to either the default FDL file or the default FDL specification. See the description of the fdl_desc argument in the section on FDL$CREATE for details.This argument allows you to specify default FDL attributes. In other words, FDL$PARSE processes the attributes specified in this argument unless you override them with the attributes you specify in the fdl_desc argument.
You can code the FDL defaults directly into your program, typically with an FDL specification in string form.
stmnt_num
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by reference
FDL statement number. The stmnt_num argument is the address of a longword that receives the FDL statement number. If the routine finishes successfully, the stmnt_num argument is the number of statements in the FDL specification. If the routine does not finish successfully, the stmnt_num argument receives the number of the statement that caused the error. Note that line numbers and statement numbers are not the same and that an FDL specification in string form has no "lines."By default, an error status is returned rather than signaled.
SS$_NORMAL Normal successful completion. LIB$_BADBLOADR Bad block address. LIB$_BADBLOSIZ Bad block size. LIB$_INSVIRMEM Insufficient virtual memory. RMS$_DNF Directory not found. RMS$_DNR Device not ready or not mounted. RMS$_WCC Invalid wildcard context (WCC) value.
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.
FDL$RELEASE [fab_pointer] [,rab_pointer] [,flags] [,badblk_addr]
OpenVMS usage: cond_value type: longword (unsigned) access: write only mechanism: by value
Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.
fab_pointer
OpenVMS usage: address type: longword (unsigned) access: read only mechanism: by reference
File access block (FAB) to be deallocated using the LIB$FREE_VM routine. The fab_pointer argument is the address of a longword containing the address of the FAB. The FAB must be the same one returned by the FDL$PARSE routine. Any name blocks (NAMs) and extended attribute blocks (XABs) connected to the FAB are also released.If you omit this argument or specify it as zero, the FAB (and any associated NAMs and XABs) is not released.
rab_pointer
OpenVMS usage: address type: longword (unsigned) access: read only mechanism: by reference
Record access block (RAB) to be deallocated using the LIB$FREE_VM system service. The rab_pointer argument is the address of a longword containing the address of the RAB. The address of the RAB must be the same one returned by the FDL$PARSE routine. Any XABs connected to the RAB are also released.If you omit this argument or specify it as zero, the RAB (and any associated XABs) is not released.
flags
OpenVMS usage: mask_longword type: longword (unsigned) access: read only mechanism: by reference
Flag (or mask) that controls how errors are signaled. The flags argument is the address of a longword containing the control flag (or a mask). If you omit this argument or specify it as zero, no flag is set. The flag is defined as follows:
FDL$V_SIGNAL Signals any error. By default, the status code is returned to the calling image. FDL$V_LONG_NAMES Deallocates any virtual memory used for a long name access block (NAML) created by the FDL$PARSE routine. This flag is valid for OpenVMS Alpha only.
badblk_addr
OpenVMS usage: address type: longword (unsigned) access: write only mechanism: by reference
Address of an invalid RMS control block. The badblk_addr argument is the address of a longword that receives the address of an invalid control block. If an invalid control block (a fatal error) is detected, this argument is returned; otherwise, it is ignored.
SS$_NORMAL Normal successful completion. FDL$_INVBLK Invalid RMS control block at virtual address 'hex-offset'. LIB$_BADBLOADR Bad block address. RMS$_ACT File activity precludes operation. RMS$_RNL Record not locked. RMS$_RSA Record stream currently active. SS$_ACCVIO Access violation.
The Librarian (LBR) routines let you create and maintain libraries and
their modules, and use the data stored in library modules. You can also
create and maintain libraries at the DCL level, using the DCL command
LIBRARY. For details, see the OpenVMS DCL Dictionary.
11.1 Introduction to LBR Routines
This section briefly describes the types of libraries you can create
and maintain using LBR routines and how the libraries are structured.
This section also lists and briefly describes the LBR routines.
Section 11.2 provides sample programs showing how to use various LBR
routines. Section 11.3 is a reference section that provides details
about each of the LBR routines.
11.1.1 Types of Libraries
You can use the LBR routines to maintain the following types of libraries:
You create libraries by executing the DCL command LIBRARY or by calling
the LBR$OPEN routine. When object, macro, text, help, or shareable
image libraries are created, the Librarian utility structures them as
described in Figure 11-1 and Figure 11-2. You can create
user-developed libraries only by calling LBR$OPEN; they are structured
as described in Figure 11-3.
11.1.2.1 Library Headers
Every library contains a library header that describes the contents of
the library, for example, its type, size, version number, creation
date, and number of indexes. You can retrieve data from a library's
header by calling the LBR$GET_HEADER routine.
11.1.2.2 Modules
Each library module consists of a header and data. The data is the
information you inserted into the library; the header associated with
the data is created by the LBR routine and provides information about
the module, including its type, attributes, and date of insertion into
the library. You can read and update a module's header by calling the
LBR$SET_MODULE routine.
11.1.2.3 Indexes and Keys
Libraries contain one or more indexes, which can be thought of as directories of the library's modules. The entries in each index are keys, and each key consists of a key name and a module reference. The module reference is a pointer to the module's header record and is called that record's file address (RFA). Macro, text, and help libraries (see Figure 11-1) contain only one index, called the module name table. The names of the keys in the index are the names of the modules in the library.
Object and shareable image libraries (see Figure 11-2) contain two indexes: the module name table and a global symbol table. The global symbol table consists of all the global symbols defined in the modules in the library. Each global symbol is a key in the index and points to the module in which it was defined.
If you need to point to the same module with several keys, you should create a user-developed library, which can have up to eight indexes (see Figure 11-3). Each index consists of keys that point to the library's modules.
The LBR routines differentiate library indexes by numbering them, starting with 1. For all but user-developed libraries, the module name table is index number 1 and the global symbol table, if present, is index number 2. You number the indexes in user-developed libraries. When you access libraries that contain more than one index, you may have to call LBR$SET_INDEX to tell the LBR routines which index to use.
Figure 11-1 Structure of a Macro, Text, or Help Library
Figure 11-2 Structure of an Object or Shareable Image Library
Figure 11-3 Structure of a User-Developed Library
All the LBR routines begin with the characters LBR$. Your programs can call these routines by using the OpenVMS Calling Standard. When you call an LBR routine, you must provide all required arguments. Upon completion, the routine returns its completion status as a condition value. In addition to the listed condition values, some routines may return the success code SS$_NORMAL as well as various OpenVMS RMS or system status (SS) error codes.
When you link programs that contain calls to LBR routines, the linker locates the routines during its default search of SYS$SHARE:LBRSHR. Table 11-1 lists the routines and summarizes their functions.
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 in PostScript and DECW$BOOK (Bookreader) formats on the OpenVMS Documentation CD-ROM. A printed book can be ordered through DECdirect (800-354-4825). |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4493PRO_019.HTML
|