HP OpenVMS Systems Documentation

HP OpenVMS Version 8.2 New Features and Documentation Overview

OpenVMS I64 Debugger supports programs written in the following languages:

BASIC
BLISS
C
C++
COBOL
IMACRO
Fortran
Intel assembler (IAS)
Pascal

The Heap Analyzer is now available on OpenVMS I64 systems and is activated differently than on Alpha systems. A new start command, START HEAP_ANALYZER, is available from the debugger command-line prompt (DBG>) to start the Heap Analyzer from the OpenVMS I64 Debugger. For complete information, refer to the Heap Analyzer chapter in the HP OpenVMS Debugger Manual.

4.7 Extended Lock Value Block

A lock value block is a feature of the OpenVMS Lock Manager that provides a type of synchronized interprocess/intracluster communication. In the past, OpenVMS applications using the Lock Manager have been able to store and retrieve up to 16 bytes of lock value block data during locking operations. In OpenVMS Version 8.2, applications may now optionally store up to 64 bytes of data in the lock value block.

The $GETLKI system service has been modified to add two new item codes that this new feature requires. The purpose of the items codes is:

• To retrieve the extended value block (LKI$_XVALBLK) into a 64-byte buffer.
• To indicate whether the last writer wrote a short value block (LKI$_XVALNOTVALID) into a boolean value in a quadword buffer.

For more information, refer to HP OpenVMS Programming Concepts Manual and to the HP OpenVMS System Services Reference Manual.

4.8 Librarian Utility and Library Routines (I64 only)

The following sections provide information about the Librarian utility and Library routines on OpenVMS I64 systems. On OpenVMS Alpha systems, the Librarian utility and Library routines are unchanged.

You can use the DCL command LIBRARY to invoke the Librarian utility (or use Library [LBR] routines) to create the following library types:

• I64 (ELF) object library
• I64 (ELF) shareable image library
• Macro library
• Help library
• Text library

The LIBRARY command invokes the OpenVMS Librarian utility from which you can maintain library modules or simply display information about a library and its modules. The I64 Librarian utility provides the same features provided by the Alpha Librarian, except for the changes and restrictions specified in HP OpenVMS Version 8.2 Release Notes.

Table 4-1 shows the libraries that are created by the Librarian utility for each OpenVMS platform.

This section describes changes and restrictions to the Librarian utility on OpenVMS I64 systems.

4.8.2.1 Librarian Defaults to Intel® Itanium® Architecture

There is no architecture switch for the OpenVMS I64 Librarian utility. When used with the following qualifiers, the Librarian works on OpenVMS ELF object and image libraries:

/OBJECT---Work on OpenVMS ELF object libraries (default)
/SHARE---Work on OpenVMS ELF shareable image libraries

The default library type created is an object library if no OBJECT and SHARE qualifiers are specified.

4.8.2.2 No Support for /ALPHA and /VAX Qualifiers

The /ALPHA and /VAX qualifiers are not supported in the I64 Librarian utility. The Librarian utility works on the following library types only:

MACRO
TEXT
HELP
ELF OBJECT
ELF SHARABLE IMAGE

The /REMOVE qualifier has been enhanced for the I64 Librarian. The format now allows you to specify the module of the instance of the symbol to be removed.

Requests the LIBRARY command to delete one or more entries from the global symbol table in an object library.

symbol
The symbol to be deleted from the global symbol table.

module
The module whose instance of the symbol is to be removed from the global symbol table. With the support of UNIX-style weak symbols and ELF group symbols, a symbol can have definitions from more than one module. This extended syntax allows you to remove from the index a symbol of a specific module without removing the symbol instances of all other modules from the index.

Description

If you specify more than one symbol, separate the symbols with commas and enclose the list in parentheses. Wildcard characters are allowed in the symbol specification. To display the names of the deleted global symbols, you must also specify the /LOG qualifier.

4.8.3 Changes to the Library (LBR) Routines

The following sections describe changes and restrictions to the Library routines for OpenVMS I64 systems. All routines not listed here remain the same as on Alpha systems (and as documented in the OpenVMS Utility Routines Manual).

4.8.3.1 New Library Types Added

Two new library types for the LBR$OPEN routine have been added:

LBR$C_TYP_ELFOBJ (9)---Represents an ELF object library
LBR$C_TYP_ELFSHSTB (10)---Represents an ELF shareable image library

In addition, the following library types for the LBR$OPEN Library routine are not supported on OpenVMS I64:

LBR$C_TYP_OBJ (1)---Represents a VAX object library
LBR$C_TYP_SHSTB (5)---Represents a VAX shareable image library
LBR$C_TYP_EOBJ (7)---Represents an Alpha object library
LBR$C_TYP_ESHSTB (8)---Represents an Alpha shareable image library

ELF object modules are inherently random access modules, whereas OpenVMS Alpha objects, text modules, and so on, are sequential. To allow random access, a new library routine was created to map the ELF object modules into process P2 space so that applications can make random access queries. To recover virtual address space from this mapping another library routine was created to remove this mapping. These new routines (LBR$MAP_MODULE and LBR$UNMAP_MODULE) work only with ELF object libraries. These entry points are 64-bit interfaces since they refer to P2 space.

Because of the random-access nature of ELF object files, the following operations are not be allowed on ELF object libraries:

LBR$GET_RECORD
LBR$SET_LOCATE
LBR$SET_MOVE

Because inserting modules into the library is a sequential operation, LBR$PUT_RECORD is allowed on ELF object libraries. Since the ELF object modules are not segmented into records, the module's on-disk size needs to be provided upon the first call to LBR$PUT_RECORD when writing a module into the library.

The C code fragment in the following example illustrates how to use LBR$PUT_RECORD to insert an object module:

bufdesc->dsc$a_pointer = &p0_buffer ;
   bytes_to_transfer = module_size ;

   while ( bytes_to_transfer )  {
      transfer = MIN ( bytes_to_transfer ,
                       ELBR$C_MAXRECSIZ ) ;

      bufdesc->dsc$w_length = transfer ;

      status = lbr$put_record (  library_index ,
                               & bufdesc ,
                               & txtrfa ,
                                 module_size ) ;
      if ( (status & 1) == 0 )
         break ;

      bytes_to_transfer      -= transfer ;
      bufdesc->dsc$a_pointer += transfer ;
      } ;

   if ( (status & 1) == 1 )
      status = lbr$put_end ( library_index ) ;

To avoid making several calls to LBR$PUT_RECORD, a new library routine, LBR$PUT_MODULE, has been created (see Section 4.8.4).

4.8.4 New Librarian (LBR) Routines for ELF Object Libraries

This section describes the following four new Library routines for ELF object libraries:

• LBR$LOOKUP_TYPE
• LBR$MAP_MODULE
• LBR$PUT_MODULE
• LBR$UNMAP_MODULE

The LBR$LOOK_TYPE routine searches the index for the key from a particular module (RFA) and returns that key's type for that module.

Format

LBR$LOOKUP_TYPE library_index, key_name, txtrfa, ret_types

Arguments

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

key_name

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The key_name argument is the address of the string descriptor pointing to the key with the following argument characteristics:

Argument Characteristics	Entry
OpenVMS usage	char_string
type	character string
access	read only
mechanism	by descriptor

txtrfa

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array that specifies the RFA of the module header.

ret_types

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	write only
mechanism:	by reference

The address of a longword to receive the symbol types found for the specified module (txtrfa). The return type bits are:

LBR$M_SYM_NGG = 1
LBR$M_SYM_UXWK = 2
LBR$M_SYM_GG = 4
LBR$M_SYM_GUXWK = 8

Description

This routine searches the index for the key from a particular module (RFA) and returns that key's type for that module, if present. Otherwise, it returns LBR$_KEYNOTFND.

The LBR$MAP_MODULE routine maps a module into process P2 space.

Format

LBR$MAP_MODULE library_index, ret_va_addr, ret_mod_len, txtrfa

Arguments

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL library routine. The library_index argument is the address of the longword that contains the index.

ret_va_addr

OpenVMS usage:	address
type:	quadword address
access:	write only
mechanism:	by 32-bit or 64-bit reference

The 32-bit or 64-bit virtual address of a naturally aligned quadword into which the routine returns the virtual address at which the routine mapped the library module.

ret_mod_len

OpenVMS usage:	byte_count
type:	quadword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference

The address of a naturally aligned quadword into which the library routine returns the module length.

txtrfa

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array that specifies the RFA of the module header.

Description

This routine maps a module, with the given txtrfa, into process P2 memory space and returns the virtual address where the module is mapped and the module size.

Unlike other LBR services that use RMS services, LBR$MAP_MODULE also uses system services. Because of this, the secondary status for error returns is placed in LBR$$GL_SUBSTS. Use this to find further status when an error is returned.

The LBR$PUT_MODULE routine puts an entire module, with the module's record file address (RFA), from memory space into the current library.

Format

LBR$PUT_MODULE library_index, mod_addr, mod_len, txtrfa

Arguments

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index return by the LBR$INI_CONTROL library service. The library_index argument is the address of the longword that contains the index.

mod_addr

OpenVMS usage:	address
type:	quadword address
access:	read only
mechanism:	by 32- or 64-bit reference

The address from which the Library service will obtain the 64-bit address of where the module is mapped in memory. The mod_addr argument is the 32- or 64-bit virtual address of a naturally aligned quadword containing the virtual address location of the module to write to the library.

mod_len

OpenVMS usage:	byte count
type:	quadword (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference

The 64-bit virtual address of a naturally aligned quadword containing the length of the module that the Library service is to write into the library.

txtrfa

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	write only
mechanism:	by reference

The module's record file address (RFA) of the library module header. The txtrfa argument is the address of a 2-longword array receiving the RFA of the newly created module header.

Description

The LBR$PUT_MODULE routine puts an entire module, with the module's record file address (RFA), from memory space into the current library. LBR$PUT_END is not required when you write an entire module to the current library.

The LBR$UNMAP_MODULE routine unmaps a module from process P2 space.

Format

LBR$UNMAP_MODULE library_index, txtrfa

Arguments

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL routine. The library_index argument is the address of the longword that contains the index.

txtrfa

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

The module's record file address (RFA) of the library module header. The txtrfa argument is the address of the 2-longword array that specifies the RFA of the module header.

Description

Unmaps the module, with the record file address in txtrfa, from process P2 space. This releases the resources used to map the module.

Unlike other LBR services that use RMS services, LBR$UNMAP_MODULE also uses system services. Because of this, the secondary status for error returns is placed in LBR$GL_SUBSTS. Use this to find further status when an error is returned.

4.8.5 Extended Library (LBR) Routines for ELF Object Libraries

The following Library routines are listed in this section:

• LBR$DELETE_DATA
• LBR$DELETE_KEY
• LBR$GET_INDEX
• LBR$INSERT_KEY
• LBR$LOOKUP_KEY
• LBR$PUT_RECORD
• LBR$REPLACE_KEY
• LBR$SEARCH

Library routines not listed here remain the same for both OpenVMS I64 systems and OpenVMS Alpha systems and are documented in the OpenVMS Utility Routines Manual.

The LBR$DELETE_DATA routine deletes module data from the library.

Format

LBR$DELETE_DATA library_index, txtrfa, [flags]

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. Most utility routines return a condition value. Condition values that this routine can return are listed under Condition Values Returned.

Arguments

library_index

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Library control index returned by the LBR$INI_CONTROL library routine. The library_index argument is the address of the longword that contains the index.

txtrfa

OpenVMS usage:	vector_longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Record's file address (RFA) of the module header for the module you want to delete. The txtrfa argument is the address of the 2-longword array that contains the RFA. You can obtain the RFA of a module header by calling LBR$LOOKUP_KEY or LBR$PUT_RECORD.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

The contents of the flag are ignored. Its purpose is to indicate to this routine that the application knows about the new index structure for ELF object and ELF shareable image libraries.

Description

If you want to delete a library module, you must first call LBR$DELETE_KEY to delete all keys that point to it. If no library index keys are pointing to the module header, LBR$DELETE_DATA deletes the module header and associated data records; otherwise, this routine returns the error LBR$_STILLKEYS. Note that other library routines may reuse data blocks that contain no data.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_INVRFA	Specified RFA not valid.
LBR$_LIBNOTOPN	Specified library not open.
LBR$_STILLKEYS	Keys in indexes still point at the module header. Therefore, the specified module was not deleted.