Guide to Creating OpenVMS Modular Procedures
Guide to Creating OpenVMS Modular Procedures
This manual describes how to create a complex application program by
dividing it into modules and coding each module as a separate procedure.
This manual supersedes the Guide to Creating OpenVMS Modular
Procedures, Version 7.1
OpenVMS Alpha Version 7.3
OpenVMS VAX Version 7.3
Compaq Computer Corporation Houston, Texas
© 2001 Compaq Computer Corporation
Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and
OpenVMS is a trademark of Compaq Information Technologies Group, L.P.
in the United States and other countries.
All other product names mentioned herein may be trademarks of their
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.
The Compaq OpenVMS documentation set is available on CD-ROM.
This manual contains guidelines for developing, integrating, and
maintaining modular procedures. It is intended for advanced system and
applications programmers who are already familiar with OpenVMS
operating system concepts. Readers should also be proficient in at
least one supported language.
This book contains the following chapters and appendix:
- Chapter 1 defines modular procedures and discusses the benefits
of modular programming.
- Chapter 2 covers design topics, such as organizing new
applications, designing a modular procedure interface, using system
resources, using input/output, writing internal documentation, and
planning for signaling and condition handling.
- Chapter 3 presents general coding guidelines and information
about initializing modular procedures. It also discusses guidelines for
invoking optional user-supplied action routines, and writing
- Chapter 4 describes methods for testing procedures for
modularity, language-independence, and reentrancy. This chapter also
provides general information about performance testing and monitoring
- Chapter 5 shows you how to create object module libraries,
shareable images, and shareable image libraries from your completed
- Chapter 6 covers maintenance topics, such as upward
compatibility, regression testing, updating procedures and procedure
libraries, and changing the transfer vector or linker options file.
- Appendix A summarizes the modular programming guidelines presented
in this manual.
The following manuals provide additional details and the most current
information about the programming tasks described in this book:
- OpenVMS Programming Concepts Manual
- OpenVMS Programming Interfaces: Calling a System Routine1
- OpenVMS Calling Standard
- OpenVMS System Services Reference Manual: A--GETUAI
- OpenVMS System Services Reference Manual: GETUTC--Z
- OpenVMS Linker Utility Manual
- The documentation set for your language processor
For additional information about Compaq OpenVMS products and
services, access the Compaq website at the following location:
1 This manual has been archived but is
available on the OpenVMS Documentation CD-ROM.
Compaq welcomes your comments on this manual. Please 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 type 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
Introduction to Modular Procedures
A procedure is a set of related instructions that performs a task. A
module is a single body of code and text that can be assembled and
compiled as a unit.
A procedure is modular if it contains all the definitions and calls it
needs to perform a task. A modular procedure must also follow rules and
principles that permit it to be successfully linked with other
procedures that follow the same rules and principles.
This chapter briefly discusses:
- Programming benefits of modular procedures
- The way to invoke modular procedures
- The use of procedure libraries
- Existing OpenVMS system procedures
- The use of translated images
1.1 Why Bother with Modular Procedures?
Procedures can be combined to form programs in the following ways:
- Your procedure calls other procedures.
- Other procedures call your procedure.
- A calling program calls either your procedure or other procedures.
For procedures to execute successfully when they are combined to form a
program, they must follow general guidelines. Modular procedures that
do not follow these guidelines can cause other procedures in the
program image to execute incorrectly.
The modular programming guidelines in this manual are designed to give
programmers a common environment in which to write code. If all
programmers follow these guidelines, then any modular procedure can be
added to a procedure library without conflicting with procedures
already in the library or with any that are added later.
Modular programming offers the following advantages:
- You can use any modular procedure in any program.
- You can add a modular procedure to a library at any time.
- You do not need to rewrite common algorithms for a new program.
- You can reduce development time and complexity, and increase
- You can modify or replace a procedure without modifying the calling
program, provided that you adhere to the guidelines for maintaining
- You can control processwide resource allocation.
- You can use different programming languages to write different
procedures for a program.
Many of the guidelines in this manual are recommendations, not
requirements. By following all the guidelines, however, you can realize
the following additional advantages:
- Shareable library procedures can save memory space, disk space, and
- AST-reentrant procedures can be called by AST-level procedures.
- Modular procedures that conform to all coding recommendations are
similar in format; therefore, they are easier to use and maintain.
1.2 Invoking a Modular Procedure
Typically, you invoke a procedure by executing a VAX CALLS or CALLG
instruction (on VAX systems) or JSR instruction (on Alpha systems). If
you are using a high-level language, the compiler generates the
appropriate transfer instruction when you use the conventions required
by your language to implement a procedure.
For more information about calling sequences, refer to OpenVMS Programming Interfaces: Calling a System Routine. To
find out how specific languages implement procedures, refer to the
documentation set for your language processor.
1.3 Using Procedure Libraries
You can use modular procedures for general programming, or you can
group them in procedure libraries. Grouping procedures into libraries
is a way of collecting procedures so that calling programs can access
them easily. When you link your program to a library, the OpenVMS
Linker utility (linker) automatically searches that library to resolve
any references that your program makes to procedures in the library.
Because the linker searches the specified library automatically, your
program can call many modular procedures without including the name of
each procedure explicitly in the LINK command. The program's executable
image and the procedures that it calls are executed in the proper
sequence at run time.
Figure 1-1 shows the development of a program that calls one or more
procedures in a library. Depending on the options you select when
writing modular procedures, you can control the way the linker accesses
your procedures, and therefore, the way procedures are invoked at run
time. For example, if you place commonly used procedures within a
shareable procedure library or shareable image library, you can save
memory and disk space because all user processes can access a single
copy of the shared procedures.
Figure 1-1 Developing a Program That Calls Library
1.4 Existing System Procedures
The OpenVMS operating system includes many system routines that perform
advanced applications. These procedures are designed to perform various
general functions and can be useful building blocks for your own
procedures. Before you write a new procedure, make sure the application
does not already exist. You should call an existing procedure from a
system library whenever possible, instead of duplicating code.
The following types of callable system procedures are available as part
of the OpenVMS operating system:
- Run-Time Library (RTL) Procedures
- System Services
- Utility Routines
- Record Management Services (RMS)
For more information about how to use callable system procedures, refer
to OpenVMS Programming Concepts Manual.
1.5 Using Translated Images (Alpha Only)
Programs that run on VAX systems can be converted to run on Alpha
systems by recompiling and relinking or by translating. A single
application can include both native images (those that were recompiled
and relinked) and translated images.
The most effective way to convert a program that runs on a VAX system
to one that runs on an Alpha system is to recompile the source code
using a native Alpha compiler, and then to relink the object files and
shareable images using the linker.
The alternative method, translation, involves using DECmigrate for
OpenVMS Alpha, which supports the migration of VAX applications to
Alpha applications by translating images. DECmigrate converts VAX
images into functionally equivalent images that can run on Alpha
systems. DECmigrate includes the VAX Environment Software Translator
(VEST) utility, which analyzes a VAX executable or shareable image and
creates a functionally equivalent translated image.
The Translated Image Environment (TIE), which is part of the OpenVMS
Alpha operating system, provides the run-time support for translated
images on OpenVMS Alpha. The TIE includes an Alpha shareable image that
provides each translated image with an environment similar to OpenVMS
VAX, interprets untranslated VAX instructions, and processes all
interactions with the native Alpha system. The TIE also includes a
translated image that executes complex VAX instructions.
For more information about VEST and TIE, refer to DECmigrate for OpenVMS AXP Systems Translating Images. For
more information about mixing native Alpha and translated VAX modules
in a single application, see Migrating an Application from OpenVMS VAX to OpenVMS Alpha.
Designing Modular Procedures
Well-designed procedures are more likely to be modular, well-written,
and easy to maintain. Any time that you save by skimping at the design
stage will be lost as you fix problems stemming from a poor design.
This chapter discusses the following aspects of designing a new
- Organizing new applications
- Defining a modular procedure interface
- Using JSB entry points
- Using system resources
- Using input/output
- Documenting modules
- Planning for signaling and condition handling
2.1 Organizing New Applications
Before designing a new application, look at the overall organization.
An application should be made up of one or more files, each containing
one or more procedures. When linked, the procedures are organized into
program sections (PSECTs). Each procedure, as well as the interface
between the procedures, should conform to the modular guidelines
described in this manual.
2.1.1 Organizing Files and Modules
Each application contains one or more files. Each file contains exactly
one module. For information about naming files, refer to Section 22.214.171.124.
For information about naming modules, refer to Section 126.96.36.199.
2.1.2 Organizing Procedures into Modules
Each module should contain a single procedure or a group of related
procedures. The linker always brings the entire module containing a
called procedure into the image if any of its entry points are
referenced. Therefore, placing each procedure in a separate module
reduces image size and allows more flexibility when using a procedure
library. You can supply your own version of one procedure while using
other procedures from the library. If many procedures have been grouped
in a single module, the linker must link all or none of them.
Group procedures into a module if they share the same static storage or
if they have a similar calling sequence, perform similar functions, or
share a significant amount of code.
If you are writing a large number of related procedures that either
call one another or access common data blocks, make the relationship
among those procedures as clear as possible. To do this, use the
following guidelines to minimize the interaction between procedures,
and between procedures and data structures:
- Organize procedures into levels of abstraction.
- Make sure each level calls only the next lower level.
- Restrict read/write access to data structures and system components
to as few procedures as possible.
Figure 2-1 shows the BASIC and FORTRAN record I/O processing
procedures, which are implemented in the following three levels of
- User program interface (UPI)
- User program data formatting (UDF)
- Record processing and OpenVMS RMS interface (REC)
Figure 2-1 Levels of Abstraction
All calls are made in one direction, to the next innermost level.
Procedures at different levels should be in different modules.
Figure 2-2 shows possible groupings of procedures.
Figure 2-2 Possible Procedure Groupings
2.2 Defining a Modular Procedure Interface
Procedures communicate with one another by passing arguments. To
clarify the interactions between procedures and programs, you must
define each argument when you are designing a procedure. There are two
types of arguments: explicit arguments and implicit arguments. The
following sections define explicit and implicit arguments and describe
how to use them.
2.2.1 Explicit Arguments
Explicit arguments are a procedure's primary interface with other
programs. Therefore, to maintain a modular interface, you must follow
the rules for argument order, data types, and passing mechanisms. The
following format is used to describe each argument:
OpenVMS usage: argument-data-structure
For descriptions of each of these four argument attributes, see the
OpenVMS Programming Interfaces: Calling a System Routine1.
To make your procedures easier to call, be sure that the passing
mechanism used for particular data types is consistent throughout all
procedures in a facility. Passing all atomic data by reference and all
string data by descriptor is recommended.
2.2.2 Implicit Arguments
An implicit argument is one that is not specified in the argument list.
Implicit arguments provide additional information to your procedure
from static storage locations. Two types of implicit arguments are:
- Arguments allocated by the calling program
- Arguments allocated by your procedure
Using implicit arguments is discouraged because they make the
relationship across procedures less clear and tend to increase the
interaction between procedures in a way that might go undetected. If
your procedure must retain information from previous activations, see
Section 2.2.3 for ways to avoid using implicit arguments.
188.8.131.52 Implicit Arguments Allocated by the Calling Program
The calling program can allocate implicit arguments as statically
allocated variables in a named PSECT (for example, COMMON and MAP in
BASIC, COMMON in FORTRAN, or variables declared in the outer block of a
procedure or program in Pascal). The calling program can also allocate
implicit arguments as statically allocated global variables (for
example, symbols defined with a double colon [::] in MACRO and GLOBAL
variables in BLISS).
Allocation of implicit arguments by the calling program is not
recommended for the following reasons:
- Two programs could use the same PSECT name or global variable for
different values. This error would be undetected.
- The calling program is no longer independent of the called
procedure. Consequently, a change in one could inadvertently affect the
- In FORTRAN, the calling program declares all variables as COMMON
regardless of the number of implicit inputs actually needed. All COMMON
variables should also be declared by all modules that use the COMMON
storage, further decreasing independence.
1 This manual has been archived but is
available on the OpenVMS Documentation CD-ROM.