skip book previous and next navigation links
go up to top of book: HP OpenVMS Alpha Partitioning and Galaxy Guide HP OpenVMS Alpha Partitioning and Galaxy Guide
go to beginning of chapter: OpenVMS Galaxy Concepts OpenVMS Galaxy Concepts
go to previous page: Configuring OpenVMS Galaxy Instances in Time Zones Configuring OpenVMS Galaxy Instances in Time Zones
go to next page: NUMA Implications on OpenVMS ApplicationsNUMA Implications on OpenVMS Applications
end of book navigation links

Developing OpenVMS Galaxy Programs  



The following sections describe OpenVMS programming interfaces that are useful in developing OpenVMS Galaxy application programs. Many of the concepts are extensions of the traditional single-instance OpenVMS system.

To see the C function prototypes for the services described in these chapters, enter the following command:

$ LIBRARY/EXTRACT=STARLET SYS$LIBRARY:SYS$STARLET_C.TLB/OUTPUT=FILENAME
Then search the output file for the service you want to see.

Locking Programming Interfaces  

One of the major features of the Galaxy platform is the ability to share resources across multiple instances of the operating system. The services described in this chapter provide primitives upon which a cooperative scheme can be created to synchronize access to shared resources within a Galaxy.

A Galaxy lock is a combination of a spinlock and a mutex. While attempting to acquire an owned Galaxy lock, the thread spins for a short period. If the lock does not become available during the spin, the thread puts itself into a wait state. This is different from SMP spinlocks in which the system crashes if the spin times out, behavior that is not acceptable in a Galaxy.

Given the nature of Galaxy locks, they reside in shared memory. That shared memory can be allocated either by the user or by the Galaxy locking services. If the user allocates the memory, the locking services track only the location of the locks. If the locking services allocate the memory, it is managed on behalf of the user.

Unlike other monitoring code which is only part of the MON version of execlets, the Galaxy lock monitoring code is always loaded.

There are several routines provided to manipulate Galaxy locks. The routines do not provide anything but the basics when it comes to locking. They are a little richer than the spinlocks used to support SMP, but far less than what the lock manager provides. Galaxy System Services for Lock Programming summarizes the OpenVMS Galaxy system services for lock programming. Syntax for the services in Galaxy System Services for Lock Programming and Galaxy System Services for Events Programming can be found in the HP OpenVMS System Services Reference Manual.

Table 1   Galaxy System Services for Lock Programming
System Service Description
$ACQUIRE_GALAXY_LOCK
Acquires ownership of an OpenVMS Galaxy lock.
$CREATE_GALAXY_LOCK
Allocates an OpenVMS Galaxy lock block from a lock table created with the $CREATE_GALAXY_LOCK service.
$CREATE_GALAXY_LOCK_TABLE
Allocates an OpenVMS Galaxy lock table.
$DELETE_GALAXY_LOCK
Invalidates an OpenVMS Galaxy lock and deletes it.
$DELETE_GALAXY_LOCK_TABLE
Deletes an OpenVMS Galaxy lock table.
$GET_GALAXY_LOCK_INFO
Returns certain fields from the specified lock.
$GET_GALAXY_LOCK_SIZE
Returns the minimum and maximum size of an OpenVMS Galaxy lock.
$RELEASE_GALAXY_LOCK
Releases ownership of an OpenVMS Galaxy lock.

System Events Programming Interfaces  

Applications can register to be notified when certain system events occur; for example, when an instance joins the Galaxy or if a CPU joins a configure set. (A configure set is a membership of processors that are actively owned and controlled by the current instance.) If events are registered, an application can decide how to respond when the registered events occur.

Galaxy System Services for Events Programming summarizes the OpenVMS system services available for events programming.

Table 2   Galaxy System Services for Events Programming
System Service Description
$CLEAR_SYSTEM_EVENT
Removes one or more notification requests previously established by a call to $SET_SYSTEM_EVENT.
$SET_SYSTEM_EVENT
Establishes a request for notification when an OpenVMS system event occurs.

Using SDA in an OpenVMS Galaxy  

This section describes SDA information that is specific to an OpenVMS Galaxy computing environment.

For more information about using SDA, see the OpenVMS Alpha System Analysis Tools Manual .

Dumping Shared Memory  

When a system crash occurs in a Galaxy instance, the default behavior of OpenVMS is to dump the contents of private memory of the failed instance and the contents of shared memory. In a full dump, every page of both shared and private memory is dumped; in a selective dump, only those pages in use at the time of the system crash are dumped.

Dumping of shared memory can be disabled by setting bit 4 of the dynamic SYSGEN parameter DUMPSTYLE. This bit should only be set after consulting your HP support representative, as the resulting system dump may not contain the data required to determine the cause of the system crash.

Definitions of Bits in DUMPSTYLE shows the definitions of all the bits in DUMPSTYLE and their meanings in OpenVMS Alpha. Bits can be combined in any combination.

Table 3   Definitions of Bits in DUMPSTYLE
Bit Value Description
0
1
0 = Full dump. The entire contents of physical memory are written to the dump file. 1 = Selective dump. The contents of memory are written to the dump file selectively to maximize the usefulness of the dump file while conserving disk space. (Only pages that are in use are written).
1
2
0 = Minimal console output. This consists of the bugcheck code; the identity of the CPU, process, and image where the crash occurred; the system date and time; plus a series of dots indicating progress writing the dump. 1 = Full console output. This includes the minimal output described above plus stack and register contents, system layout, and additional progress information such as the names of processes as they are dumped.
2
4
0 = Dump to system disk. The dumps are written to SYS$SYSDEVICE:[SYSn.SYSEXE]SYSDUMP.DMP, or in its absence, SYS$SYSDEVICE:[SYSn.SYSEXE]PAGEFILE.SYS.1 = Dump to alternate disk. The dumps are written to dump_dev:[SYSn.SYSEXE]SYSDUMP.DMP, where dump_dev is the value of the console environment variable DUMP_DEV.
3
8
0 = Uncompressed dump. Pages are written directly to the dump file. 1 = Compressed dump. Each page is compressed before it is written, providing a saving in space and in the time taken to write the dump, at the expense of a slight increase in time taken to access the dump.
4
16
0 = Dump shared memory. 1 = Do not dump shared memory.

The default setting for DUMPSTYLE is 0 (an uncompressed full dump, including shared memory, written to the system disk). Unless a value for DUMPSTYLE is specified in MODPARAMS.DAT, AUTOGEN.COM sets DUMPSTYLE to 1 (an uncompressed selective dump, including shared memory, written to the system disk) if there are less than 128 MB of memory on the system, or to 9 (a compressed selective dump, including shared memory, written to the system disk) otherwise.

Summary of SDA Command Interface Changes or Additions  

SDA Command Enhancements summarizes enhancements to the System Dump Analyzer to view shared memory and OpenVMS Galaxy data structures. For more details, see the appropriate commands.

Table 4    SDA Command Enhancements
Command Description
SHOW SHM_CPP
The default is a brief display of all SHM_CPPs.
VALIDATE SHM_CPP
The default action is to validate all SHM_CPPs and the counts and ranges of attached PFNs, but not the contents of the database for each PFN.
SHOW SHM_REG
The default is a brief display of all SHM_REGs.
/GLXSYS and /GLXGRP to SHOW GSD
Displays Galaxy data structures.
SHOW GMDB
Displays the contents of the GMDB and NODEB blocks. The default is a detailed display of GMDB.
SHOW GALAXY
Shows a brief display of GMDB and all node blocks.
SHOW GLOCK
Displays Galaxy lock structures. The default is a display of base GLOCK structures.
SHOW GCT
Displays Galaxy configuration tree. The default is /SUMMARY.
SHOW PAGE_TABLE and SHOW PROCESS/PAGE_TABLE
Shows page and process page tables.


go to previous page: Configuring OpenVMS Galaxy Instances in Time Zones Configuring OpenVMS Galaxy Instances in Time Zones
go to next page: NUMA Implications on OpenVMS ApplicationsNUMA Implications on OpenVMS Applications