Guide to Creating OpenVMS Modular Procedures

Updated: 11 December 1998

Order Number: AA--PV6AB--TK

November 1996

This manual describes how to create a complex application program by dividing it into modules and coding each module as a separate procedure.

Revision/Update Information: This manual supersedes the Guide to Creating OpenVMS Modular Procedures, Version 1.0.

Software Version: OpenVMS Alpha Version 7.1
OpenVMS VAX Version 7.1

Digital Equipment Corporation Maynard, Massachusetts

November 1996

Digital Equipment 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.

Digital 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 Digital Equipment Corporation: Bookreader, DEC Ada, DEC Fortran, DECmigrate, DECnet, DECthreads, DECwindows, Digital, FMS, OpenVMS, VAX, VAX BASIC, VAX C, VAX FORTRAN, VAX MACRO, VAX Pascal, VMS, and the DIGITAL logo.

The following is a third-party trademark:

Motif is a registered trademark of the Open Software Foundation.

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

ZK4518

The OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

Intended Audience

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.

Document Structure

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 AST-reentrant code.
Chapter 4 describes methods for testing procedures for modularity, language-independence, and reentrancy. This chapter also provides general information about performance testing and monitoring procedures.
Chapter 5 shows you how to create object module libraries, shareable images, and shareable image libraries from your completed procedures.
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.

Reader's Comments

Digital 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, ZKO3-4/U08

Mail OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following table to order additional documentation or information. If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825).

Conventions

The name of the OpenVMS AXP operating system has been changed to the OpenVMS Alpha operating system. Any references to OpenVMS AXP or AXP are synonymous with OpenVMS Alpha or Alpha.

VMScluster systems are now referred to as OpenVMS Cluster systems. Unless otherwise specified, references to OpenVMS Cluster or clusters in this document are synonymous with VMScluster.

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

The following conventions are also 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 or
GOLD x A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button.
GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.

[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.)

... Horizontal ellipsis points in examples indicate 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.

.
.
. Vertical ellipsis points indicate 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, if you choose more than one option, you must enclose the choices in parentheses.

[ ] 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, braces indicate a required choice of options; you must choose one of the options listed.

text style This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
This style is also used to show user input in Bookreader versions of the manual.

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 device-name contains up to five alphanumeric characters).

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 type 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 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
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
Invoking modular procedures
Using procedure libraries
Existing OpenVMS system procedures
Using 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 reliability.
You can modify or replace a procedure without modifying the calling program, provided that you adhere to the guidelines for maintaining upward compatibility.
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 link time.
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 Procedures

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.

Chapter 2
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 application:

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 3.1.1.3. For information about naming modules, refer to Section 3.1.1.4.

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, and share a significant amount of code.

If you are writing a large number of related procedures that 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 abstraction:

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:

argument-name OpenVMS usage: argument-data-structure type: argument-data-type access: argument-access mechanism: argument-passing-mechanism

For descriptions of each of these four argument attributes, see the OpenVMS Programming Interfaces: Calling a System Routine.

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.

Contents

Index

Legal

 
4518PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 881-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	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 or GOLD x	A sequence such as PF1 x or GOLD x indicates that you must first press and release the key labeled PF1 or GOLD and then press and release another key or a pointing device button. GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.
`[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.)
...	Horizontal ellipsis points in examples indicate 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.
. . .	Vertical ellipsis points indicate 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, if you choose more than one option, you must enclose the choices in parentheses.
[ ]	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, braces indicate a required choice of options; you must choose one of the options listed.
text style	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason. This style is also used to show user input in Bookreader versions of the manual.
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 device-name contains up to five alphanumeric characters).
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 type	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 following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.