Document revision date: 30 March 2001
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Utility Routines Manual


Previous Contents Index


FDL$PARSE

The FDL$PARSE routine parses an FDL specification, allocates OpenVMS RMS control blocks (FABs, RABs, or XABs), and fills in the relevant fields.

Format

FDL$PARSE fdl_desc ,fdl_fab_pointer ,fdl_rab_pointer [,flags] [,default_fdl_desc] [,stmnt_num]


RETURNS


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.


Arguments

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.


Condition Values Returned

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.

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.

Format

FDL$RELEASE [fab_pointer] [,rab_pointer] [,flags] [,badblk_addr]


RETURNS


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.


Arguments

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.

Condition Values Returned

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.


Chapter 11
Librarian (LBR) Routines

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:

11.1.2 Structure 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


11.1.3 Summary of LBR Routines

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.

Table 11-1 LBR Routines
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.

Note

1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4493PRO_019.HTML