OpenVMS Programming Concepts Manual
OpenVMS Programming Concepts Manual
This manual describes the features that the OpenVMS operating system
provides to programmers.
This manual supersedes the OpenVMS Programming Concepts Manual, Version 7.2.
OpenVMS Alpha Version 7.3
OpenVMS VAX Version 7.3
Compaq Computer Corporation
© 2001 Compaq Computer Corporation
Compaq, AlphaServer, VAX, VMS, and the Compaq logo Registered in U.S.
Patent and Trademark Office.
Alpha, OpenVMS, PATHWORKS, DECnet, and DEC are trademarks of Compaq
Information Technologies Group, L.P.
UNIX and X/Open are trademarks of The Open Group in the United States
and other countries.
All other product names mentioned herein may be the trademarks or
registered trademarks of their respective companies.
Confidential computer software. Valid license from Compaq 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.
Compaq shall not be liable for technical or editorial errors or
omissions contained herein. The information in this document is
provided "as is" without warranty of any kind and is subject to change
without notice. The warranties for Compaq products are set forth in the
express limited warranty statements accompanying such products. Nothing
herein should be construed as constituting an additional warranty.
Printed in the U.S.A.
The Compaq OpenVMS documentation set is available on CD-ROM.
This document was prepared using DECdocument, Version V3.3-1e.
This manual is intended for system and application programmers. It
presumes that its readers have some familiarity with the 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, Overview of Manuals and Introduction to Development on
OpenVMS Systems, 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, Process Creation, 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
- Chapter 3, Process Communication, describes communication within
a process and between processes.
- Chapter 4, Process Control, 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, Symmetric Multiprocessing (SMP) Systems, describes
overview concepts of symmetric multiprocessing (SMP) systems.
- Chapter 6, Synchronizing Data Access and Program Operations,
describes synchronization concepts and differences between the VAX
system and Alpha system synchronization techniques. 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
- Chapter 7, Synchronizing Access to Resources, 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, Using Asynchronous System Traps, 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, Condition-Handling Routines and Services, describes
the OpenVMS Condition Handling facility. It describes VAX system and
Alpha system exceptions, arithmetic exceptions, and Alpha 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 action 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, Overview of Virtual Address Space, describes the
32-bit and 64-bit use of virtual address space.
- Chapter 11, Support for 64-bit Addressing, describes all the
services, routines, tools, and programs that support 64-bit addressing.
- Chapter 12, Memory Management Services and Routines on OpenVMS
Alpha, describes system services and RTLs of Alpha systems to manage
memory. It describes the page size and layout of virtual address space
of Alpha systems. This chapter also describes how to add virtual
address space, adjust working sets, control process swapping, and
create and manage sections on Alpha systems.
- Chapter 13, Memory Management Services and Routines on OpenVMS
VAX, 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, Using Run-Time Routines for Memory Allocation,
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
- Chapter 15, Alignment on OpenVMS Alpha and VAX Systems, describes
the importance and techniques of instruction and data alignment.
- Chapter 16, Memory Management with VLM Features, describes the
VLM memory management features, such as the following:
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, Call Format to OpenVMS Routines, describes the format
used to document system routine calls and explains where to find and
how to interpret information about routine calls.
- Chapter 18, Basic Calling Standard Conventions, describes the
concepts and conventions used by common languages to invoke routines
and pass data between them.
- Chapter 19, Calling Run-Time Library Routines, describes a set of
language-independent routines that establish a common run-time
environment for user programs.
- Chapter 20, Calling System Services, describes the system
services available to application and system programs for use at run
- Chapter 21, STARLET Structures and Definitions for C Programmers,
describes the libraries that contain C header files for routines.
- Chapter 22, Run-Time Library Input/Output Operations, describes
the different I/O programming capabilities provided by the run-time
- Chapter 23, System Service Input/Output Operations, describes how
to use system services to perform input and output operations.
- Chapter 24, Using Run-Time Library Routines to Access Operating
System Components, describes the run-time library (RTL) routines that
allow access to various operating system components.
- Chapter 25, Using Cross-Reference Routines, 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, Shareable Resources, describes the techniques
available for sharing data and program code amoung programs.
- Chapter 27, System Time Operations, 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, File Operations, describes file attributes,
strategies to access files, and file protection techniques.
- Chapter 29, Using the Distributed Transaction Manager, describes
the use of the DECdtm system services to ensure the integrity and
consistency of distributed transactions by implementing a two-phase
- Chapter 30, Creating User-Written System Services, describes how
to create user-written system services with privileged shareable images
for both VAX systems and Alpha systems.
- Chapter 31, System Security Services, 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 32, Logical Name and Logical Name Tables, 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
- Chapter 33, Image Initialization, describes how to use the
LIB$INITIALIZE routine to initialize an image.
- Appendix A, C Macros for 64-Bit Addressing, 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, 64-Bit Example Program, illustrates writing a program
with a 64-bit region created and deleted by system services.
- Appendix C, VLM Example Program, demonstrates the memory
management VLM features described in Chapter 16.
- Appendix D, Generic Macros for Calling System Services, describes
the use of generic macros to specify argument lists with appropriate
symbols and conventions in the system services interface to MACRO
- Appendix E, OpenVMS Data Types, describes the data types that
provide compatibility between procedure calls that support many
different high-level languages.
- Appendix F, Distributed Name Service, describes the Digital
Distributed Name Service (DECdns) Clerk by introducing the functions of
the DECdns (SYS$DNS) system service and various run-time library
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 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:
- OpenVMS DCL Dictionary
- OpenVMS User's Manual
- Guide to OpenVMS File Applications
- OpenVMS Guide to System Security
- DECnet for OpenVMS Networking Manual
- OpenVMS Record Management Services documentation
- OpenVMS Utility Routines Manual
- OpenVMS I/O User's Reference Manual
For additional information about OpenVMS products and services, access
the following World Wide Web address:
Compaq welcomes your comments on this manual. Plese send comments to
either of the following addresses:
Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
How To Order Additional Documentation
Use the following World Wide Web address to order additional
If you need help deciding which documentation best meets your needs,
The following conventions are 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.
This typeface represents the introduction of a new term. It also
represents the name of an argument, an attribute, or a reason.
Italic text 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 text indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
Monospace text indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the
following elements: keywords, the names of independently compiled
external functions and files, syntax summaries, and references to
variables or identifiers introduced in an example.
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 this two-volume 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 two-volume 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 OpenVMS Alpha, VAX, and VLM memory management with run-time
routines for memory management, and alignment on OpenVMS Alpha and VAX
Appendices: 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 appendices 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. Compaq 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:
- OpenVMS VAX software runs on the complete family of VAX processors,
which support traditional 32-bit processing.
- OpenVMS Alpha software runs on a full series of very high-speed
RISC processors that support 64-bit as well as 32-bit processing.
Both VAX and Alpha processors encompass a wide range of computing
power: from desktop and deskside workstations, through distributed
office systems and data center servers, to extremely high performance
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.