HP OpenVMS Systems Documentation

HP OpenVMS Version 8.3 New Features and Documentation Overview

The object modules generated by C, C++, Ada, and possibly other compilers can have symbol names in the symbol table that have been altered; a process that is commonly referred to as "mangling". These names are the symbol names visible to the linker, which the linker uses for symbol resolution.

The reason for mangling can be an overload feature in the programming language or simply the need to uniquely shorten names. When you link such modules and get an undefined-symbol message, the linker displays only the symbol name from the object module's symbol table (that is, the mangled name). This processing makes it difficult to match the undefined, mangled symbol with the demangled, source code name. Therefore, to support upcoming compilers that produce display-name information (DNI), the linker can now process that information. In addition, the linker displays the source code name; that is, the linker can demangle the undefined symbol name. Further, if there is demangling information for universal symbols (that is, those to be exported from a shareable image), the linker can include that information in the generated shareable images.

The symbol resolution process remains unchanged. The linker still uses the mangled symbol names for symbol definitions and to resolve symbol references. The symbol vector option remains the same as well; it still requires the names found in the symbol tables---the mangled names.

You can use the new command-line qualifier, /DNI, to control the processing of the demangling information. Specify /DNI (the default) to allow the linker to attempt symbol-name demangling and move the necessary demangling information into the shareable image being created. Specify /NODNI when:

• You do not want the demangled names to be displayed.
• You do not want the demangling information to be moved into the shareable image.

You can request a new map section containing a translation table for the global symbol definitions. This table correlates the mangled symbol names with their demangled equivalents. By default, the linker does not generate this section in the map file. To request this section, specify the key word DEMANGLED_SYMBOLS to the /FULL qualifier. As with other keywords for the /FULL qualifier, specify the /MAP qualifier. Finally, specify the /DNI qualifier. The translation table in the map can be helpful to verify the symbol vector entries.

The following edited example shows how the demangled name is displayed in a linker message:

$ cre foo.cxx
extern double foo (int) ;
double bar (void) { return foo (123); }
[Ctrl/Z]
$ cxx foo
$ link foo
%ILINK-W-NUDFSYMS, 1 undefined symbol:
%ILINK-I-UDFSYM,        CXX$_Z3FOOI1RLFMIE
%ILINK-W-USEUNDEF, undefined symbol CXX$_Z3FOOI1RLFMIE referenced
        source code name: "double foo(int)"
        section: .text
        offset: %X0000000000000020  slot: 2
        module: FOO
        file: DISK$USER:[JOE]FOO.OBJ;1
$

The demangling information section is part of the object module or shareable image. The information needed to demangle the symbol name can be entirely contained within that section, or that information can include the name of a facilitator routine name and shareable image name to perform the demangling. This shareable image is usually located in SYS$LIBRARY and is provided by the language run-time environment already present on OpenVMS or is provided during the installation of the language compiler. If the facilitator routine is required, the linker attempts to activate the image and call the routine. If this fails at any point---for example, if the routine is not found in the shareable image or the image could not be located---then the linker displays an informational message indicating the problem. The link operation, as well as propagation of the demangling information into a shareable image, is independent of the success or failure of calling the facilitating routine.

5.7 Listing Demangled and Mangled Names with the Librarian (I64 Only)

The LIBRARY command now accepts the /DEMANGLED_SYMBOLS qualifier. When you use this qualifier, the Librarian lists symbols from an ELF object or ELF shareable image library that were altered by a language processor (also known as mangling) and prints their corresponding demangled name (that is, the name found in the source code). Mangled names are output as external symbols from an object module (or, as universal symbols from a shareable image). One reason for the language processor to mangle names is function overloading; a feature of the C++ language.

The Librarian stores the symbols that are emitted from an object module or shareable image. These symbols may include mangled symbols. The information needed to demangle these symbol names, along with a possible name of a facilitating shareable image, is contained in the object module or shareable image.

For an ELF object library, object modules are fully contained in the library. To retrieve the demangling information, the object module is mapped into memory and searched. It may be the case that language-specific demangling shareable images are also mapped into memory and activated. The symbols are read from the object library module and demangled with the information provided by the module. The library's symbol-name table is scanned to mark which of the object library module's symbols are in the library's symbol-name table. Subsequent modules are processed in the same way, and a listing is then generated.

For ELF shareable image libraries, the shareable image is not stored in the library. This is similar to OpenVMS Alpha and OpenVMS VAX shareable image libraries. Instead, only the exported symbols and other minimal information is stored in the library. As a result, the Librarian searches for the shareable image, external to the library, in order to obtain the demangling information.

The Librarian performs a three-step search; stopping when it successfully obtains a file:

1. First, the Librarian performs a logical name translation on the library module's name.
2. Failing that, the Librarian then searches for a module name with an extension of .EXE in the disk and directory in which the library resides.
3. If that fails, the Librarian finally looks in the device and directory indicated by the logical IA64$LIBRARY for a file with a filename of the library module and with a .EXE extension. If the Librarian finds a file specification, it maps it into memory and perform the same steps described above for ELF object libraries.

You can use the existing /OUTPUT= qualifier to direct the generated output from the demangling process to a file specification you choose. When you do not specify the /OUTPUT= qualifier, the Librarian by default places the output into a file in the current disk and directory, with the filename the same as the filename of the library and the extension .LIS as the file type.

You can also limit which library modules are selected for demangling by using the existing /ONLY= qualifier.

For example, to display the demangled symbols from an object library and have the output sent to the terminal screen, enter the following DCL command at the command line prompt:

$ LIBRARY /DEMANGLED_SYMBOLS /OUTPUT=SYS$OUTPUT OBJLIB.OLB

The following example captures the demangled symbol output to the file DUMP.LIS of the SHAREIMG.OLB shareable image library:

$ LIBRARY /DEMANGLED_SYMBOLS /OUTPUT=DUMP.LIS SHAREIMG.OLB

The following example captures the demangled symbol output to the default file specification SYS$DISK:[]SHAREIMG.LIS of the SHAREIMG.OLB shareable image library:

$ LIBRARY /DEMANGLED_SYMBOLS SHAREIMG.OLB

The following example captures the demangled symbol output to the default file specification SYS$DISK:[]OBJLIB.LIS of the object module MY_OBJ in the OBJLIB.OLB object library:

$ LIBRARY /DEMANGLED_SYMBOLS /ONLY=MY_OBJ OBJLIB.OLB

The MACRO compiler has been upgraded to use the latest GEM backend for Alpha systems. In addition, several enhancements have been made:

• An /ARCHITECTURE qualifier has been provided. Possible values are GENERIC, HOST, EV4, EV5, EV56, EV6, EV67, and EV7. For architecture values of EV56 and later, the compiler now automatically generates Alpha byte/word instructions for corresponding VAX operations. In addition, the instruction scheduler will use the /ARCHITECTURE value as appropriate.
• The machine code listing has been improved including command line summary and symbolic names for most PAL calls.
• Three additional Alpha instruction builtins have been added:
  • EVAX_CTLZ <RQ,WQ> Generate a CTLZ instruction (count leading zeros)
  • EVAX_CTPOP <RQ,WQ> Generate a CTPOP instruction (count bits)
  • EVAX_CTTZ <RQ,WQ> Generate a CTTZ instruction (count trailing zeros) These new builtins are also accepted by the I64 compiler and equivalent Itanium instructions are generated.
• The name of the compiler image has been renamed to SYS$SYSTEM:MACRO.EXE. The prior SYS$SYSTEM:ALPHA_MACRO.EXE image has been left on the kit in the event that the new compiler produces incorrect results. The new compiler is used by OpenVMS engineering as the compiler used to build the system itself so there has already been extensive testing. The prior SYS$SYSTEM:ALPHA_MACRO.EXE compiler will be removed in a future release.

The following sections describe the RMS enhancements provided in OpenVMS Version 8.3.

5.9.1 RMS CONVERT/FDL and CREATE/FDL Enhancements

The CONVERT/FDL and CREATE/FDL routines have been enhanced to allow an FDL string to be passed as the FDL file specification. If the /FDL qualifier value is a quoted string and is not a quoted POSIX pathname, then it is passed to the FDL parser as an FDL string. Quoted values within the string must be designated with double quotes. See the HP OpenVMS Utility Routines Manual FDL section for details of using an FDL string.

Note the following examples:

$  CONVERT/FDL="TITLE ""This is an FDL string"";File;org SEQ;Record;size 80" -
_$( input_file:  output_file:)
$   CREATE/FDL="record;format fixed;size 100" file.dat

Prior to the OpenVMS Version 8.3 release, RMS global buffers were exclusively mapped to P0 (32-bit address) space. This restricted the overall per-process limit to less than 1 GB for the total number of global buffers specified for all files accessed by a process. This per-process limit forced RMS users to compromise on the number of global buffers specified for each file. It also constrained the per-file maximum size allowed for a global cache (currently, 32767 buffers).

To improve the overall scalability and performance of RMS global buffers, this release introduces the following global buffer enhancements for indexed files:

• Mapping RMS global buffers for indexed files to P2 (64-bit address) space in order to remove the overall per-process limit of less than 1 GB. No application changes are required to utilize global buffers for indexed files mapped to P2 space. However, global buffers must be enabled on an indexed file to take advantage of the enhancement.
• Increasing the per-file maximum size allowed for a global cache from a signed word (32767) to a signed longword (2.1 billion) for indexed files. To take advantage of the per-file maximum size increase, new options must be used with the SET FILE/GLOBAL_BUFFER qualifier.

Because RMS global buffers are local to each node, these enhancements were designed so they could be implemented on OpenVMS Alpha and OpenVMS for Integrity servers Version 8.3 nodes in a mixed cluster environment without requiring any changes to OpenVMS VAX or earlier version nodes. The Version 8.3 Alpha and Integrity server nodes will be able to increase the global cache size on an indexed file, while other nodes continue to operate on the file with the pre-Version 8.3 global cache size. This is particularly attractive, because it allows users to phase in Version 8.3 (or later) Alpha or Integrity server nodes that can support larger global buffer caches for indexed files into clusters with earlier versions of OpenVMS, including nodes running OpenVMS VAX.

5.9.3 New Form of Global Buffers Specification

There are now two forms of the SET FILE/GLOBAL_BUFFER command:

1. SET FILE/[NO]GLOBAL_BUFFER[=n file name]
   Where n sets the old value for the number of global buffers that can be shared (limited to a maximum of 32767). This makes the file compatible with prior versions of OpenVMS and stores in the original location in the file's header.
2. SET FILE/[NO]GLOBAL_BUFFER[=keyword[=n]] file name
   Where keyword can be:
   • COUNT=n---The value n sets the longword count of the number of global buffers.
   • PERCENT=p---The value p expresses the size of the global cache as a percent of the total number of blocks currently used in the file.
   • DEFAULT---Requests RMS at runtime to recalculate the global cache size based on an algorithm that makes use of two global buffer SYSGEN parameters, GB_CACHEALLMAX and GB_DEFPERCENT.
   
   The value n sets the new value stored in a different location in a file's header.

For example, the following commands do four distinctly different things:

1. $ SET FILE/GLOBAL_BUFFER=20 NEWFILE.DAT ! Sets the compatibility (old) global buffer count (limited)
2. $ SET FILE/GLOBAL_BUFFER=COUNT=1000 NEWFILE.DAT ! Sets the new global buffer count (unlimited)
3. $ SET FILE/GLOBAL_BUFFER=PERCENT=50 INVENTORY.DAT ! Tells RMS to calculate the count as a percentage of the file
4. $ SET FILE/GLOBAL_BUFFER=DEFAULT INV.INX ! Tells RMS to calculate the count based on the total file size

Global buffers specified with the old syntax (SET FILE/GLOBAL_BUFFER=n) stores settings in the file header in one location, while the new syntax (SET FILE/GLOBAL_BUFFER=keyword[=n]) are stored elsewhere in the file's header and are used to implement the new variation of global buffers, allowing more buffers and automatic adjustments for file growth.

Note You can specify only one version of the global buffer qualifier in a command string. Here's an example of using both the old and new global buffer specifications to set the old compatibility global buffer count value (for OpenVMS versions prior to Version 8.3) to 100 and the new value (Version 8.3 and later) to 10000:

$ SET FILE/GLOBAL_BUFFER=100 NEWFILE.DAT
$ SET FILE/GLOBAL_BUFFER=COUNT=10000 NEWFILE.DAT

In a clustered environment with mixed OpenVMS versions, the same file can be opened on different nodes with different global buffer counts. For nodes prior to Version 8.3, use the old compatibility setting, and for Version 8.3 nodes and later use the new values.

5.9.4 New Fields Added to XABFHC

Two new fields have been added to the read-only XABFHC (file header characteristics):

The field descriptions for these fields are the following:

• XAB$L_GBC32 --- Enhanced longword global buffer count or percentage. If the XAB$V_GBC_PERCENT flag is set in the XAB$B_RECATTR_FLAGS field, the field contains a percentage.
• XAB$B_RECATTR_FLAGS --- Flags for record attribute area in file header. The following flags are currently implemented:
  • XAB$V_GBC_PERCENT --- This flag indicates the value in the global buffer count is expressed as a percent of the total number of blocks currently used in the file. This allows the size to dynamically grow over time because RMS recalculates the actual size to be mapped based on the current total number of blocks used in the file. The size is determined at run time each time the global cache is created by the first accessor on a node. Users can also specify a percentage greater than 100 percent to allow for rapid growth for a file that, once opened, is closed infrequently.
  • XAB$V_GBC_DEFAULT --- This flag requests RMS at run time to recalculate the global cache size based on an algorithm that uses two global buffer (GB) SYSGEN parameters, GB_CACHEALLMAX and GB_DEFPERCENT. If the default option is enabled, and if the size (in blocks) of the file is less than or equal to the specified size for the GB_CACHEALLMAX parameter, RMS allocates sufficient global buffers to cache the whole file. If the size (in blocks) is greater than the specified size for the GB_CACHEALL MAX parameter, RMS allocates sufficient global buffers to cache the percentage of the file indicated by the GB_DEFPERCENT (global buffer default percent) parameter.

The following field values have been added:

Figure 5-1, from the HP OpenVMS I/O User's Reference Manual, has been updated to reflect the new fields.

Figure 5-1 ACP-QIO Record Attributes Area

This release introduces two new per-file management options that allow simpler sizing of the global buffer cache for all RMS file organizations (sequential, relative, and indexed). These new options augment the existing global buffer count option:

• PERCENT --- Rather than specifying a global buffer count as the size, users can express the size of the global cache as a percent of the current total number of blocks used in the file. This allows the size to dynamically grow over time, because RMS recalculates the actual size to be mapped based on the current total number of blocks used in the file. The size is determined at run time when the global cache is initially created by the first accessor of the file on a node. Users can also specify a percentage greater than 100 percent to allow for rapid growth for a file that, once opened, is closed infrequently.
• DEFAULT --- The user can choose an option requesting that at run time each time the global cache is created by the first accessor on a node, RMS calculate a global cache size based on some file characteristics.

The RMS global buffer count (GBC) default is based on an algorithm that uses two new global buffer (GB) SYSGEN parameters: GB_CACHEALLMAX and GB_DEFPERCENT. If the default option is enabled, and if the size (in blocks) of the file is less than or equal to the size specified for the GB_CACHEALLMAX parameter, RMS allocates sufficient global buffers to cache the whole file.

If the size (in blocks) is greater than the specified size for the GB_CACHEALLMAX parameter, RMS allocates sufficient global buffers to cache the percentage of the file specified by the GB_DEFPERCENT (global buffer default percent) parameter. A percentage greater than 100 percent can be specified to provide space in the cache for the file to grow.

5.9.7 Size of Global Buffer Cache Connected to File (XAB$_GBC)

The XAB$_GBC item code can be used with an item list XAB on a $CONNECT or $DISPLAY with a SENSEMODE operation to sense the actual number of global buffers connected to a file when the global section for the file was created by the first accessor on the respective node.

The XAB$_GBC item code requires a 4-byte buffer to return the cache size that was connected. You cannot use a SETMODE with this item.

This option is not supported for DECnet operations; it is ignored.

5.9.8 Global Buffer Count (XAB$_GBC32)

The XAB$_GBC32 item code can be used with an item list XAB on a $CREATE with A SETMODE operation. It sets the longword global buffer count as a permanent attribute in the record-attribute area of the file header when a file is created. You can also use it with an item list XAB on a $CONNECT with a SETMODE to override at run time the permanent attribute in the file header. The override applies only if the process is the first connector of the cache on the respective node.

You cannot sense the global buffer count connected to a file using the XAB$_GBC32 item code. Use the XAB$_GBC item code to sense the actual global-buffer count.

The XAB$_GBC32 item code requires a 4-byte buffer to store the cache size that can be requested as either an actual count or a percentage of the total number of blocks in the file at run time. To specify the cache size as a percent, the XAB item list must also include the XAB$_GBCFLAGS item code; otherwise, the cache size value provided with the XAB$_GBC32 item code is interpreted as a count.

You can specify a maximum value of %x7FFFFFFF as the count for an indexed file; sequential and relative file organizations are restricted to a maximum of 32767. You can specify a percentage that is greater than 100 percent to allow for rapid growth for a file that, once opened, is closed infrequently.

Note that this option is not supported for DECnet operations; it is ignored.

5.9.9 Global Buffer Flags (XAB$_GBCFLAGS)

The XAB$_GBCFLAGS item code can be used with an item list XAB on a $CREATE with a SETMODE operation. It sets the global buffer flags value as a permanent attribute in the record attributes area of the file header when a file is created. You can also use it with an item list XAB on a $CONNECT with a SETMODE to override at run time the permanent attribute in the file header. The override applies only if the process is the first connector of the cache on the respective node.

You can sense the global buffer flags value using the XAB$_GBCFLAGS item code with an item list XAB on a $CONNECT or $DISPLAY with a SENSEMODE operation. The global buffer flags used in calculating the global buffer count when the global section for the file was created by the first connector is returned.

The two available flags are:

• XAB$M_GBC_PERCENT --- Indicates the value in the global buffer count is expressed as a percent of the total number of blocks currently in the file. This allows the size to grow dynamically over time, because RMS recalculates the actual size to be mapped based on the current total number of blocks used in the file. The size is determined at run time each time the global cache is created by the first accessor on a node. You can also specify a percentage greater than 100 percent to allow for rapid growth for a file that, once opened, is closed infrequently.
• XAB$M_GBC_DEFAULT --- Requests RMS at run time to recalculate the global cache size based on an algorithm that makes use of two global buffer (GB) SYSGEN parameters: GB_CACHEALLMAX and GB_DEFPERCENT. If the default option is enabled, and if the size (in blocks) of the file is less than or equal to the specified size for the GB_CACHEALLMAX parameter, RMS allocates sufficient global buffers to cache the whole file. If the size (in blocks) is greater than the specified size for the GB_CACHEALLMAX parameter, RMS allocates sufficient global buffers to cache the percentage of the file specified by the GB_DEFPERCENT (global buffer default percent) parameter.

The XAB$_GBCFLAGS item code requires a 4-byte buffer to store the flag value of either XAB$_GBC_PERCENT or XAB$_GBC_DEFAULT.

Note, this option is not supported for DECnet operations; it is ignored.