Document revision date: 30 March 2001

Order Number: AA--PV6AD--TK

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 7.1

Software Version: 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 Trademark Office.

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

ZK4518

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents

Index

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.

Related Documents

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 Routine¹
• 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:

http://www.openvms.compaq.com/

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@compaq.com
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.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

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 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 text	This typeface represents the introduction of a new term. It also represents 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 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.

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

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.

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

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.

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

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, 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 abstraction:

1. User program interface (UPI)
2. User program data formatting (UDF)
3. 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

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.

2.2.2.1 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 other.
• 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.

	privacy and legal statement
4518PRO.HTML