OpenVMS Programming Concepts Manual

Document revision date: 19 July 1999

Order Number: AA--PV67D--TK

January 1999

This manual describes the features that the OpenVMS operating system provides to programmers.

Revision/Update Information: This manual supersedes the OpenVMS Programming Concepts Manual, Version 7.1.

Software Version: OpenVMS Alpha Version 7.2
OpenVMS VAX Version 7.2

Compaq Computer Corporation
Houston, Texas

January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Digital or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: ACMS, Alpha, AXP, Bookreader, Compaq, DBMS, DECdirect, DECdtm, DECthreads, DEC Fortran, DIGITAL, MicroVAX, OpenVMS, PDP-11, VAX, VAXcluster, VAX Ada, VAX BASIC, VAX BLISS-32, VAX DOCUMENT, VAX MACRO, VAX Pascal, VMS, VMScluster, VT100, and the Compaq logo.

The following are third-party trademarks:

Motif, OSF, OSF/1, OSF/Motif, and Open Software Foundation are registered trademarks of the Open Software Foundation, Inc.

All other trademarks and registered trademarks are the property of their respective holders.

ZK5841

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

Intended Audience

This manual is intended for system and application programmers. It presumes that its readers have some familiarity with the OpenVMS programming environment, derived from the OpenVMS Programming Environment Manual and OpenVMS high-level language documentation.

Document Structure

This manual's 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, 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 process structure.
Chapter 2, Process Communication, describes communication within a process and between processes.
Chapter 3, 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 4, Symmetric Multiprocessing (SMP) Systems, describes overview concepts of symmetric multiprocessing (SMP) systems.
Chapter 5, 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 6, 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 7, Using Run-Time Library Routines to Access Operating System Components, describes using run-time libraries (RTLs) with system services, the command language interpreter, and allowing high-level programs to use VAX machine instructions. Also, this chapter describes using RTLs to allocate processwide resources to a single process, perform performance evaluation, and control output formatting.
Chapter 8, Using Cross-Reference Routines, describes how to use cross-reference routines. Two facilities that use the cross-reference routines are the VMS Linker and the MACRO assembler.
Chapter 9, Run-Time Library Input/Output Operations, describes using RTLs for input/output operations within a program, using SYS$INPUT, and SYS$OUTPUT, as well as LIB$GET_INPUT and LIB$PUT_OUTPUT. Additionally, this chapter describes using the SMG$ routine for managing terminal screens, and for managing screen management routines.
Chapter 10, File Operations, describes file attributes, strategies to access files, and file protection techniques.
Chapter 11, System Service Input/Output Operations, describes using the SYS$QIO and SYS$QIOW system services for establishing quotas, privileges, and protection. It also describes assigning and deassigning I/O channels, queuing requests, and synchronizing I/O completions. This chapter describes how to use logical names and physical device names for I/O operations; how to use device name defaults; how to obtain information about physical devices; and how to allocate devices. Functions such as mounting, dismounting, and initializing disk and tape volumes, along with using mailboxes are explained.
Chapter 12, 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 table.
Chapter 13, Distributed Name Service (VAX Only), describes the use of the SYS$DNS system service to provide applications with a method to assign networkwide names to system resources such as printers, files, application databases, disks, nodes, and servers.
Chapter 14, 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 commit protocol.
Chapter 15, 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 16, 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 environment.
Chapter 17, 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 18, Image Initialization, describes how to use the LIB$INITIALIZE routine to initialize an image.
Chapter 19, Shareable Resources, describes how to share data and program code among programs. It defines shareable images; it also defines and describes how to use local and global symbols to share images.
Chapter 20, 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 21, Memory Management Services and Routines (VAX Only), describes the use 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 22, Memory Management Services and Routines (Alpha Only), describes the use of 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 23, 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 zones.
Chapter 24, Alignment on OpenVMS VAX and Alpha Systems, describes the importance and techniques of instruction and data alignment.
Chapter 25, 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.

OpenVMS Alpha Support for 64-Bit Addresses

As of Version 7.0, the OpenVMS Alpha operating system provides support for 64-bit virtual memory addresses, which makes the 64-bit virtual address space defined by the Alpha architecture available to the OpenVMS Alpha operating system and to application programs. In the 64-bit virtual address space, both process-private and system virtual address space extend beyond 2 GB. By using 64-bit addressing features, programmers can create images that map and access data beyond the previous limits of 32-bit virtual addresses.

Many tools and languages supported by OpenVMS Alpha (including the Debugger, run-time library routines, and DEC C) are enhanced to support 64-bit virtual addressing. Input and output operations can be performed directly to and from the 64-bit addressable space by means of RMS services, the $QIO system service, and most of the device drivers supplied with OpenVMS Alpha systems.

Underlying this are new system services, which allow an application to allocate and manage the 64-bit virtual address space that is available for process private use.

Nonprivileged programs may optionally be modified to exploit 64-bit addressing support. OpenVMS Alpha 64-bit virtual addressing does not affect nonprivileged programs that are not explicitly modified to exploit 64-bit support. Binary and source compatibility of existing nonprivileged programs is guaranteed.

For more information about OpenVMS Alpha 64-bit virtual addressing features, see the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 881-0120, Attention: OSSG Documentation, ZK03-4/U08

Mail 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 documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The following conventions are used in this manual:

Ctrl/ x 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.

PF1 x 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 button.

[Return] 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 possibilities:

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 the options in parentheses if you choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

italic text 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 Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text 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 following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Process Creation

This chapter describes process creation and the different types of processes. It also describes kernel threads and the kernel threads process structure. This chapter contains the following sections:

Section 1.1 defines a process and describes the two types of processes.

Section 1.2 describes the execution context of a process.

Section 1.3 describes the modes of execution of a process.

Section 1.4 describes the creation of a subprocess.

Section 1.5 describes the creation of a detached process.

Section 1.6 describes kernel threads and the parts that make up the kernel threads process.

1.1 Process Types

A process is the environment in which an image executes. Two types of processes can be created with the operating system: spawned subprocesses or detached processes.

A spawned subprocess is dependent on the process that created it (its parent), and receives a portion of its parent process's resource quotas. The system deletes the spawned subprocess when the parent process exits.

A detached process is independent of the process that created it. The process the system creates when you log in is, for example, a detached process. If you want a created process to continue after the parent exits, or not to share resources with the parent, use a detached process.

Table 1-1 compares the characteristics of subprocesses and detached processes.

Table 1-1 Characteristics of Subprocesses and Detached Processes
Characteristic Subprocess Detached Process

Privileges Received from creating process Specified by creating process

Quotas and limits Shared with creating process Specified by creating process, but not shared with creating process

User authorization file Used for information not given by creating process Used for most information not given by creating process

User identification code Received from creating process Specified by creating process

Restrictions Exist as long as creating process exists None

How created SYS$CREPRC, LIB$SPAWN or PPL$SPAWN from another process SYS$CREPRC from another process

When deleted At image exit, or when creating process exits At image exit

Command language interpreter (CLI) present Usually not if created with SYS$CREPRC; usually yes if spawned Usually not (though interactive user processes have CLI present, and they are created with SYS$CREPRC)

**Table 1-1 Characteristics of Subprocesses and Detached Processes**
Characteristic	Subprocess	Detached Process
Privileges	Received from creating process	Specified by creating process
Quotas and limits	Shared with creating process	Specified by creating process, but not shared with creating process
User authorization file	Used for information not given by creating process	Used for most information not given by creating process
User identification code	Received from creating process	Specified by creating process
Restrictions	Exist as long as creating process exists	None
How created	SYS$CREPRC, LIB$SPAWN or PPL$SPAWN from another process	SYS$CREPRC from another process
When deleted	At image exit, or when creating process exits	At image exit
Command language interpreter (CLI) present	Usually not if created with SYS$CREPRC; usually yes if spawned	Usually not (though interactive user processes have CLI present, and they are created with SYS$CREPRC)

1.2 Execution Context of a Process

The execution context of a process defines a process to the system. It includes the following:

Image that the process is executing
Input and output streams for the image executing in the process
Disk and directory defaults for the process
System resource quotas and user privileges available to the process

When the system creates a detached process as the result of a login, it uses the system user authorization file (SYSUAF.DAT) to determine the process's execution context.

For example, the following occurs when you log in to the system:

The process created for you executes the image LOGINOUT.
The terminal you are using is established as the input, output, and error stream device for images that the process executes.
Your disk and directory defaults are taken from the user authorization file.
The resource quotas and privileges you have been granted by the system manager are associated with the created process.
A command language interpreter (CLI) is mapped into the created process.

1.3 Modes of Execution of a Process

A process executes in one of the following modes:

Interactive---Receives input from a record-oriented device, such as a terminal or mailbox
Batch---Is created by the job controller and is not interactive
Network---Is created by the network ancillary control program (ACP)
Other---Is not running in any of the other modes (for example, a spawned subprocess where input is received from a command procedure)

1.4 Creating a Subprocess

You can create a subprocess using the LIB$SPAWN and PPL$SPAWN run-time library routines or the SYS$CREPRC system service. A subprocess created with LIB$SPAWN or PPL$SPAWN is called a spawned subprocess.

Table 1-2 lists the context values provided by LIB$SPAWN, PPL$SPAWN, and SYS$CREPRC for a subprocess when using the default values in the routine calls.

Table 1-2 Comparison of LIB$SPAWN, PPL$SPAWN, and SYS$CREPRC Context Values
Context LIB$SPAWN PPL$SPAWN SYS$CREPRC

DCL Yes Yes No ¹

Default device and directory Parent's Parent's Parent's

Symbols Parent's Parent's No

Logical names Parent's ² Parent's ² No ²

Privileges Parent's Parent's Parent's

Priority Parent's Parent's 0

**Table 1-2 Comparison of LIB$SPAWN, PPL$SPAWN, and SYS$CREPRC Context Values**
Context	LIB$SPAWN	PPL$SPAWN	SYS$CREPRC
DCL	Yes	Yes	No ¹
Default device and directory	Parent's	Parent's	Parent's
Symbols	Parent's	Parent's	No
Logical names	Parent's ²	Parent's ²	No ²
Privileges	Parent's	Parent's	Parent's
Priority	Parent's	Parent's	0

¹The created subprocess can include DCL by executing the system image SYS$SYSTEM:LOGINOUT.EXE.
²Plus group and job logical name tables.

Contents

Index

privacy and legal statement

5841PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZK03-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	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.
PF1 x	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 button.
`[Return]`	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 possibilities: 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 the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[\|]	In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.
bold text	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text	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	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	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 following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.