HP OpenVMS Programming Concepts Manual
This manual describes the features that the OpenVMS operating system
provides to programmers.
This manual supersedes the HP OpenVMS Programming Concepts Manual, Version 7.3-1.
OpenVMS I64 Version 8.2 OpenVMS Alpha Version 8.2
Hewlett Packard Company Palo Alto, California
© Copyright 2005 Hewlett-Packard Development Company, L.P.
Confidential computer software. Valid license from HP required for
possession, use or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
The information contained herein is subject to change without notice.
The only warranties for HP products and services are set forth in the
express warranty statements accompanying such products and services.
Nothing herein should be construed as constituting an additional
warranty. HP shall not be liable for technical or editorial errors or
omissions contained herein.
Intel and Itanium are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States and other
Microsoft, Windows, and Windows NT are U.S. registered trademarks of
UNIX is a registered trademark of The Open Group.
X/Open is a registered trademark, and the X device is a trademark of
X/Open Company Ltd. in the UK and other countries.
Printed in the US.
The HP OpenVMS documentation set is available on CD-ROM.
This manual is intended for system and application programmers. It
presumes that its readers have some familiarity with the HP OpenVMS
The following chapters provide information about the programming
features of the OpenVMS operating system. A list of the chapters and a
summary of their content is as follows:
- Chapter 1 describes the structure of the two-volume manual, and
an introduction to the OpenVMS operating system, and its tools that are
available in the programming environment.
- Chapter 2 defines the two types of processes, what constitutes
the context of a process, and the modes of execution of a process. It
also describes kernel threads and the kernel threads process structure.
- Chapter 3 describes communication within a process and between
- Chapter 4 describes how to use the creation and control of a
process or kernel thread for programming tasks. It also describes how
to gather information about a process or kernel thread and how to
synchronize a program by using time.
- Chapter 5 describes overview concepts of symmetric
multiprocessing (SMP) systems.
- Chapter 6 describes synchronization concepts and differences
between synchronization techniques on VAX systems, Alpha systems, and
I64 systems. It presents methods of synchronization such as event
flags, asynchronous system traps (ASTs), parallel processing RTLs, and
process priorities, and the affects of kernel threads upon
synchronization. It also describes using synchronous and asynchronous
system services, and how to write applications in a multiprocessing It
also describes using synchronous and asynchronous system services, and
how to write applications in a multiprocessing environment.
- Chapter 7 describes the use of the lock manager system services
to synchronize access to shared resources. This chapter presents the
concept of resources and locks; it also describes the use of the
SYS$ENQ and SYS$DEQ system services to queue and dequeue locks.
- Chapter 8 describes how to use asynchronous system traps (ASTs).
It describes access modes and service routines for ASTs and how ASTs
are declared and delivered. It also describes the effects of kernel
threads on AST delivery.
- Chapter 9 describes the OpenVMS Condition Handling facility. It
describes VAX, Alpha, and I64 system exceptions, arithmetic exceptions,
and Alpha and I64 system unaligned access traps. It describes the
condition value field, exception dispatcher, signaling, and the
argument list passed to a condition handler. Additionally, types of
condition handlers and various types of actions performed by them are
presented. This chapter also describes how to write and debug a
condition handler, and how to use an exit handler.
- Chapter 10 describes the 32-bit and 64-bit use of virtual address
- Chapter 11 describes all the services, routines, tools, and
programs that support 64-bit addressing.
- Chapter 12 describes system services and RTLs of Alpha and I64
systems to manage memory. It describes the page size and layout of
virtual address space on Alpha and I64 systems. This chapter also
describes how to add virtual address space, adjust working sets,
control process swapping, and create and manage sections on Alpha and
- Chapter 13 describes the of system services and RTLs of VAX
systems to manage memory. It describes the page size and layout of
virtual address space of VAX systems. This chapter also describes how
to add virtual address space, adjust working sets, control process
swapping, and create and manage sections on VAX systems.
- Chapter 14 describes how to use RTLs to allocate and free pages
and blocks of memory, and how to use RTLs to create, manage, and debug
virtual memory zones.
- Chapter 15 describes the importance and techniques of instruction
and data alignment.
- Chapter 16 describes the VLM memory management features, such as
Memory-resident global sections
Fast I/O and buffer objects for global sections
Shared page tables
Expandable global page table
Reserved memory registry
- Chapter 17 describes the format used to document system routine
calls and explains where to find and how to interpret information about
- Chapter 18 describes the concepts and conventions used by common
languages to invoke routines and pass data between them.
- Chapter 19 describes a set of language-independent routines that
establish a common run-time environment for user programs.
- Chapter 20 describes the system services available to application
and system programs for use at run time.
- Chapter 21 describes the libraries that contain C header files
- Chapter 22 describes the different I/O programming capabilities
provided by the run-time library.
- Chapter 23 describes how to use system services to perform input
and output operations.
- Chapter 24 describes the run-time library (RTL) routines that
allow access to various operating system components.
- Chapter 25 describes how cross-reference routines that are
contained in a separate, shareable image are capable of creating a
cross-reference analysis of symbols.
- Chapter 26 describes the techniques available for sharing data
and program code amoung programs.
- Chapter 27 describes the system time format, and the manipulation
of date/time and time conversion. It further describes how to obtain
and set the current date and time, how to set and cancel timer
requests, and how to schedule and cancel wakeups. The Coordinated
Universal Time (UTC) system is also described.
- Chapter 28 describes file attributes, strategies to access files,
and file protection techniques.
- Chapter 29 describes the extended file specifications features.
- Chapter 30 describes the use of the DECdtm system services to
ensure the integrity and consistency of distributed transactions by
implementing a two-phase commit protocol.
- Chapter 31 describes how to create user-written system services
with privileged shareable images for VAX, Alpha, and I64 systems.
- Chapter 32 describes the system services that establish
protection by using identifiers, rights databases, and access control
entries. This chapter also describes how to modify a rights list as
well as check access protection.
- Chapter 33 describes how to write a new authentication and
credential management (ACM) client program or update existing programs
to be an ACM client program.
- Chapter 34 describes how to create and use logical name services,
how to use logical and equivalence names, and how to add and delete
entries to a logical name table.
- Chapter 35 describes how to use the LIB$INITIALIZE routine to
initialize an image.
- Appendix A describes the C language macros for manipulating
64-bit addresses, for checking the sign extension of the low 32 bits of
64-bit values, and for checking descriptors for the 64-bit format.
- Appendix B illustrates writing a program with a 64-bit region
created and deleted by system services.
- Appendix C demonstrates the memory management VLM features
described in Chapter 16.
- Appendix D describes the use of generic macros to specify
argument lists with appropriate symbols and conventions in the system
services interface to MACRO assembles.
- Appendix E describes the data types that provide compatibility
between procedure calls that support many different high-level
- Appendix F describes the Digital Distributed Name Service
(DECdns) Clerk by introducing the functions of the DECdns (SYS$DNS)
system service and various run-time library routines.
- Authentication Glossary contains definition for terms used in Chapter 33,
Authentication and Credential Management (ACM) System Service.
For a detailed description of each run-time library and system service
routine mentioned in this manual, see the OpenVMS Run-Time Library
documentation and the HP OpenVMS System Services Reference Manual.
You can find additional information about calling OpenVMS system
services and Run-Time Library routines in your language processor
documentation. You may also find the following documents useful:
- HP OpenVMS DCL Dictionary
- OpenVMS User's Manual
- Guide to OpenVMS File Applications
- HP OpenVMS Guide to System Security
- DECnet for OpenVMS Networking Manual
- OpenVMS Record Management Services documentation
- OpenVMS Utility Routines Manual
- HP OpenVMS I/O User's Reference Manual
For additional information about HP OpenVMS products and services,
visit the following World Wide Web address:
HP welcomes your comments on this manual. Please send comments to
either of the following addresses:
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
How To Order Additional Documentation
For information about how to order additional documentation, visit the
following World Wide Web address:
The following conventions may be used in this manual:
A sequence such as Ctrl/
x indicates that you must hold down the key labeled Ctrl while
you press another key or a pointing device button.
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
In examples, a key name enclosed in a box indicates that you press a
key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as
brackets, rather than a box.
A horizontal ellipsis in examples indicates one of the following
- Additional optional arguments in a statement have been omitted.
- The preceding item or items can be repeated one or more times.
- Additional parameters, values, or other information can be entered.
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
In command format descriptions, parentheses indicate that you must
enclose choices in parentheses if you specify more than one.
In command format descriptions, brackets indicate optional choices. You
can choose one or more items or no items. Do not type the brackets on
the command line. However, you must include the brackets in the syntax
for OpenVMS directory specifications and for a substring specification
in an assignment statement.
In command format descriptions, vertical bars separate choices within
brackets or braces. Within brackets, the choices are optional; within
braces, at least one choice is required. Do not type the vertical bars
on the command line.
In command format descriptions, braces indicate required choices; you
must choose at least one of the items listed. Do not type the braces on
the command line.
Bold type represents the introduction of a new term. It also represents
the name of an argument, an attribute, or a reason.
Italic type indicates important information, complete titles of
manuals, or variables. Variables include information that varies in
system output (Internal error
number), in command lines (/PRODUCER=
name), and in command parameters in text (where
dd represents the predefined code for the device type).
Uppercase type indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
This typeface indicates code examples, command examples, and
interactive screen displays. In text, this type also identifies URLs,
UNIX commands and pathnames, PC-based commands and folders, and certain
elements of the C programming language.
A hyphen at the end of a command format description, command line, or
code line indicates that the command or statement continues on the
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
Overview of Manuals and Introduction to Development on OpenVMS Systems
This chapter describes the structure of the manual. This chapter also
provides an overview of the OpenVMS operating system, its components,
and the tools in programming software.
1.1 Overview of the Manual
This manual introduces the resources and features of the OpenVMS
operating system that are available to help you develop programs.
Table 1-1 describes the parts of each volume.
Table 1-1 Manual Description
Process and Synchronization. Describes the creation,
communication, and control of processes. It also describes symmetric
multiprocessing (SMP), and the synchronizing of data access,
programming operations, and access to resources.
Interrupts and Condition Handling. Describes the use
of asynchronous system traps (ASTs), and the use of routines and
services for handling conditions.
Addressing and Memory Management. Describes 32-bit and
64-bit address space, and the support offered for 64-addressing. It
also provides guidelines for 64-bit application programming interfaces
(APIs); and Alpha, I64, VAX, and VLM memory management with run-time
routines for memory management, and alignment on OpenVMS Alpha, VAX,
and I64 systems.
Appendixes: Macros and Examples of 64-Bit Programming.
Describes the macros used in 64-bit programming, along with two
examples of 64-bit programmming.
OpenVMS Programming Interfaces: Calling a System
Routine. Describes the basic calling format for OpenVMS
routines and system services. It also describes the STARLET structures
and definitions for C programmers.
I/O, System and Programming Routines. Describes the
I/O operations, and the system and programming routines used by
run-time libraries and system services.
Generic Macros for Calling System Services. Describes
in appendixes the generic macros used for calling system services,
OpenVMS data types, and the distributed name services on OpenVMS VAX
1.2 Overview of the OpenVMS Operating System
The OpenVMS operating system is a highly flexible, general-purpose,
multiuser system that supports the full range of computing
capabilities, providing the high integrity and dependability of
commercial-strength systems along with the benefits of open,
distributed client/server systems.
OpenVMS operating systems can be integrated with systems from different
vendors in open systems computing environments. HP has
"opened" the traditional VMS system to support software that
conforms to international standards for an open environment. These
industry-accepted, open standards specify interfaces and services that
permit applications and users to move between systems and allow
applications on different systems to operate together.
The OpenVMS operating system configuration includes OpenVMS integrated
software, services and routines, applications, and networks. The system
supports all styles of computing, from timesharing to real-time
processing to transaction processing. OpenVMS systems configured with
optional software support distributed computing capabilities and can
function as servers in multivendor client/server configurations.
The OpenVMS operating system is designed to provide software
compatibility across all the processors on which it runs.
The following sections describe the components of the OpenVMS operating
system, give a general overview of the system software, and describe
the various styles of computing that OpenVMS software supports. The
sections also summarize the basic ways in which OpenVMS software can be
configured and connected to other software, and the hardware platforms
and processors on which the OpenVMS software runs.
1.3 Components of the OpenVMS Operating System
The OpenVMS operating system is a group of software programs (or
images) that control computing operations. The base operating system is
made up of core components and an array of services, routines,
utilities, and related software. The OpenVMS operating system serves as
the foundation from which all optional software products and
applications operate. The services and utilities in the base OpenVMS
operating system support functions such as system management, data
management, and program development. Other integrated software that
adds value to the system provides functions such as clustering and
Optional software products, including application programs developed by
OpenVMS programmers and other programmers, run on the core operating
system. The OpenVMS system supports a powerful, integrated development
environment with a wide selection of software development tools
supplied by HP and other vendors.
Application programs written in multiple languages provide
computational, data-processing, and transaction-processing
capabilities. Thousands of applications have been developed for OpenVMS
systems by HP and independent software vendors.
Compatibility Between Software Versions
OpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 software exhibits
compatibility from version to version:
- User-mode programs and applications created under earlier versions
of OpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 run under subsequent
versions with no change.
- Command procedures written under one version of OpenVMS continue
to run under newer versions of the software.
OpenVMS software developed on VAX platforms can migrate easily to Alpha
and I64 platforms (see Section 126.96.36.199):
- Most user-mode OpenVMS VAX sources can be recompiled, relinked, and
run on an OpenVMS Alpha and OpenVMS I64 system without modification.
Code that explicitly relies on the VAX architecture requires
- Most OpenVMS Alpha images run under translation on OpenVMS I64.
- Translation is available for OpenVMS VAX applications without
sources or that you do not want to recompile.