HP OpenVMS Systems Documentation

HP OpenVMS Version 8.2 New Features and Documentation Overview

The LBR$REPLACE_KEY routine modifies or inserts a key into the library.

Format

LBR$REPLACE_KEY library_index ,key_name ,oldrfa ,newrfa [,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 routine. The library_index argument is the address of the longword that contains the index.

key_name

OpenVMS usage:	char_string
type:	character string
access:	read only
mechanism:	by reference

For libraries with ASCII keys, the key_name argument is the address of a string descriptor for the key.

For libraries with binary keys, the key_name argument is the address of an unsigned longword value for the key.

oldrfa

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

Old record file address (RFA). The oldrfa argument is the address of a 2-longword array containing the original RFA (returned by LBR$LOOKUP_KEY) of the module header associated with the key you are replacing.

newrfa

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

New RFA. The newrfa argument is the address of a 2-longword array containing the RFA (returned by LBR$PUT_RECORD) of the module header associated with the new key.

flags

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

If present, specifies the type of the key being replaced. The flag bits are:

Flag Bits	Description
LBR$M_SYM_WEAK = 0x1	UNIX-style weak symbol attribute
LBR$M_SYM_GROUP = 0x2	Group symbol attribute

If this parameter is not present, NonGroup-Global is the assumed type. In this case, all type lists are searched and the entries removed. The new symbol is placed as the new NonGroup-Global definition with newrfa as the defining module.

If this parameter is present, it represents the flags for the type of symbol being replaced. The replacement is done in place without losing its position in the type list. If the symbol does not exist when the call to this routine is made, the new definition is placed at the end of the type list for the specified type.

Because there are now different symbol definition types, HP advises using the LBR$DELETE_KEY routine followed by the LBR$INSERT_KEY routine, when the old key and new key differ in definition type.

Description

If LBR$REPLACE_KEY does not find the key in the current index, it calls the LBR$INSERT_KEY routine to insert the key. If LBR$REPLACE_KEY does find the key, it modifies the key entry in the index so that it points to the new module header.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_INVRFA	Specified RFA not valid.
LBR$_LIBNOTOPN	Specified library not open.

The LBR$SEARCH routine finds index keys that point to specified data.

Format

LBR$SEARCH library_index ,index_number ,rfa_to_find ,routine_name [, 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 routine. The library_index argument is the address of the longword that contains the index.

index_number

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

Library index number. The index_number argument is the address of a longword containing the number of the index you want to search.

rfa_to_find

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

Record's file address (RFA) of the module whose keys you are searching for. The rfa_to_find argument is the address of a 2-longword array containing the RFA (returned earlier by LBR$LOOKUP_KEY or LBR$PUT_RECORD) of the module header.

routine_name

OpenVMS usage:	procedure
type:	procedure value
access:	read only
mechanism:	by reference

Name of a user-supplied routine to process the keys. The routine_name argument is the address of the procedure value of a user-supplied routine to call for each key entry containing the RFA (in other words, for each key that points to the same module header).

This user-supplied routine cannot contain any calls to LBR$DELETE_KEY or LBR$INSERT_KEY.

flags

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

If present and nonzero, specifies the type, or all types, of the key provided. The flag bits are:

Flag Bits	Description
LBR$M_SYM_WEAK = 0x1	UNIX-style weak symbol attribute
LBR$M_SYM_GROUP = 0x2	Group symbol attribute
LBR$M_SYM_ALL = 0x80000000	All symbols

The user routine is provided the symbol's type through an additional third parameter.

Description

Searches the library index for symbols with the given RFA and calls the supplied routine with those symbols.

Use LBR$SEARCH to find index keys that point to the same module header. Generally, in index number 1 (the module name table), just one key points to any particular module; thus, you would probably use this routine only to search library indexes where more than one key points to a module. For example, you might call LBR$SEARCH to find all the symbols in the symbol index that are associated with an object module in an object library.

If LBR$SEARCH finds an index key associated with the specified RFA, it calls a user-supplied routine with three arguments:

• The key argument, which is the address of either of the following:
  • A string descriptor for the key name (libraries with ASCII key names)
  • An unsigned longword for the key value (libraries with binary keys)
• The RFA argument, which is the address of a 2-longword array containing the RFA of the module header
• The key's type whose flag bits are:

  Flag Bits	Description
  LBR$M_SYM_WEAK = 1	UNIX-style weak symbol attribute
  LBR$M_SYM_GROUP = 2	Group symbol attribute

The user routine must return a value to indicate success or failure. If the specified user routine returns a false value (low bit = 0), then the index search terminates.

Note that the key found by LBR$SEARCH is valid only during the call to the user-supplied routine. If you want to use the key later, you must copy it.

Condition Values Returned

LBR$_ILLCTL	Specified library control index not valid.
LBR$_ILLIDXNUM	Specified library index number not valid.
LBR$_KEYNOTFND	Library routine did not find any keys with the specified RFA.
LBR$_LIBNOTOPN	Specified library not open.

4.8.6 Library Format Changed due to New UNIX-Style Weak Symbols

UNIX-style weak symbol definitions behave in the same manner as weak transfer addresses on OpenVMS; that is, their definitions are tentative. If a definition of a stronger binding type is not seen during a link operation, a tentative definition is designated as the definitive definition.

4.8.6.1 New ELF Type for Weak Symbols

A new Executable and Linkable Format (ELF) type was generated to distinguish between the two types of weak symbol definitions.

For modules with ABI versions greater than or equal to 2:

• Type STB_WEAK represents the UNIX-style weak symbol (formerly, the OpenVMS-style weak symbol definition for ABI Version 1 ELF format)
• Type STB_VMS_WEAK represents the OpenVMS-style weak symbol definition.

The Librarian supports both the ELF ABI versions 1 and 2 of the object and image file formats within the same library.

HP recommends using the new Version 6.0 libraries.

However, note that with the new library index format, the LBR routines open Version 3.0 and Version 4.0 ELF object and shareable image libraries in read-only mode. You cannot modify the library with the LBR routines or with the Librarian utility. Instead, you can convert your older version libraries to version 6.0 libraries using the following LIBRARY command:

$  LIBRARY/COMPRESS library-name

Using the Librarian utility to modify a Version 3.0, 4.0 or 5.0 ELF object or shareable image library causes the Librarian to automatically convert your library to a version 6.0 library.

%LIBRAR-F-OPENIN, error opening library-name as input
 -LBR-E-UNSUPLVL, unsupported library format level

Symbols may be relative to sections contained in an ELF entity called a GROUP. These groups, and the symbols associated with them, behave in a similar fashion as the new UNIX-style weak symbol definitions; that is, they are tentative definitions. The library must now allow multiple symbol definitions in the library's symbol name index for these types of symbols.

4.8.6.4 Precedence Ordering Rules

The following list describes the symbol types for the combinations of GROUP and UNIX-style WEAK attributes in order of their precedence from highest to lowest. Within these symbol types, the ordering of symbol associations is by time of insertion, from earliest to latest. This ordering is important because when the OpenVMS I64 Linker asks for a symbol resolution from the library, it is given the earliest inserted module instance of the symbol with the highest precedence.

• NonGroup-Global symbols --Symbols that are not members of an ELF group and are not UNIX-style weak definitions. These symbols have the highest precedence. There may be only one definition of this type. If the symbol of this type already exists in the library, a subsequent symbol definition of this type returns an error.
• Group Global symbols--Symbols that belong to an ELF section associated with a group and are not UNIX-style weak definitions. Multiple definitions of this type may exist in the library. These definitions are stored in a list, ordered by insertion time. Note that if a module definition in the list is replaced, it does not lose its current position in the list.
• UNIX-style weak symbols--Symbols that have a UNIX-style weak binding and do not belong to a group. Multiple definitions of this type may exist in the library. These definitions are stored in a list, ordered by insertion time. Note that if a module definition in the list is replaced, it does not lose its current position in the list.
• Group weak symbols---Symbols that behave as combined Group Global and UNIX-style Weak attributes. Multiple definitions of this type may exist in the library. These definitions are stored in a list, ordered by insertion time. Note that if a module definition in the list is replaced, it does not lose its current position in the list.

Refer to Chapter 7 for information on the Linker utility.

4.10 HP OpenVMS Migration Software

HP OpenVMS Migration Software for Alpha to Integrity servers (OMSAI), also known as the binary translator, facilitates migrating OpenVMS Alpha applications to OpenVMS I64 systems by allowing you to translate the OpenVMS Alpha images into equivalent OpenVMS I64 images. When the translated image runs, the OpenVMS I64 transparently supports the image with an environment that allows it to run as if it were on an OpenVMS Alpha system. OMSAI consists of the Alpha Environment Software Translator (AEST) utility and a collection of programs and command files designed to ease the translation process.

For information on the availability of this feature, check the following web site:

http://h71000.www7.hp.com/openvms/products/omsva/omsva.html

4.11 POSIX Threads Features

The following sections describe the new features added to the POSIX Threads Library.

4.11.1 Lowercase Symbol Names for /NAMES=AS_IS Compilation

The POSIX threads library PTHREAD$RTL.EXE exports a number of symbol names (for the pthread API routines, predefined exception objects, and so forth). In prior releases, all letters in these symbols have been in uppercase. In OpenVMS Version 8.2, new lowercase variants of all the symbols are provided in addition to the existing uppercase symbols. These symbols facilitate use of the /NAMES=AS_IS qualifier that is present in a number of HP compiler products.

4.11.2 Support for Process-Shared Mutexes and Condition Variables

The POSIX Threads Library now supports process-shared mutexes and condition variables. Until now, these were supported only on UNIX systems. (Note, process-shared read-write locks are still supported only on UNIX systems.) The following pthread routines are now supported on OpenVMS Version 8.2:

• pthread_condattr_getpshared
• pthread_condattr_setpshared
• pthread_mutexattr_getpshared
• pthread_mutexattr_setpshared

The DCL commands SET and SHOW have been enhanced to allow a user to query and change two main-image header flags, UPCALLS and MKTHREADS on OpenVMS I64 systems. In addition, you can use the SET IMAGE and SHOW IMAGE commands on both Alpha and I64 systems to set and show only I64 images.

The DCL command THREADCP continues to be available on OpenVMS Alpha systems.

4.11.4 New Routine Added to Thread Independent Services API

A new routine, tis_mutex_init_type , has been added to the Thread Independent Services API (TIS). This routine is similar to the existing routine named tis_mutex_init .

Initializes the specified mutex object, establishing the mutex's type and name as specified by the caller.

Format

tis_mutex_init_type (mutex,type,name):

C Binding

#include <tis.h>

int
tis_mutex_init_type (
    pthread_mutex_t    *mutex,
    int   type,
    const char    *name );

Arguments

mutex

Pointer to a mutex object (passed by reference) to be initialized.

type

Value for the mutex type attribute. The type argument specifies the type of mutex that will be created. Valid values are:

• PTHREAD_MUTEX_NORMAL
• PTHREAD_MUTEX_DEFAULT
• PTHREAD_MUTEX_RECURSIVE
• PTHREAD_MUTEX_ERRORCHECK

name

Textual name to be associated with the mutex.

Description

This routine initializes a mutex object with the DECthreads default mutex attributes, except for mutex type and name, which are specified by the caller. A mutex is a synchronization object that allows multiple threads to serialize their access to shared data.

The mutex object is initialized and set to the unlocked state. Refer to the Guide to POSIX Threads Library for information on the types of mutexes.

The mutex name argument is a C language string and provides an identifier that is a meaningful to a person debugging a DECthreads multithreaded application. The name string should be a string literal, or other storage that will remain for the life of the mutex. The contents of the string are not copied as part of mutex initialization.

Return Values

If an error condition occurs, this routine returns an integer value indicating the type of error, the mutex is not initialized, and the contents of mutex are undefined. Possible return values are as follows:

0	Successful completion.
[EAGAIN]	The system lacks the necessary resources to initialize a mutex.
[EBUSY]	The implementation has detected an attempt to reinitialize mutex (a previously initialized, but not yet destroyed, mutex).
[EINVAL]	The value specified by mutex is not a valid mutex, or the type specified by type is not a valid mutex type.
[ENOMEM]	Insufficient memory exists to initialize the mutex.
[EPERM]	The caller does not have privileges to perform this.

Associated Routines

tis_mutex_destroy()
tis_mutex_init()
tis_mutex_lock()
tis_mutex_trylock()
tis_mutex_unlock()