Guide to Creating OpenVMS Modular Procedures

Document revision date: 19 July 1999

Guide to Creating OpenVMS Modular Procedures

Order Number: AA--PV6AC--TK

January 1999

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

The content of this document has not changed since OpenVMS Version 7.1.

Compaq Computer Corporation Houston, Texas

Reprinted 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 Compaq 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: Alpha, Compaq, DEC Ada, DECdirect, DEC Fortran, DECmigrate, DECthreads, DECwindows, DIGITAL, OpenVMS, VAX, VAX BASIC, VAX C, VAX DOCUMENT, VAX FORTRAN, VAX MACRO, VAX Pascal, VAXcluster, VMS, and the Compaq 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

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 884-0120, Attention: OSSG Documentation, ZKO3-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-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.)

... 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, 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 a required choice of options; 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 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 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.

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.

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.

Contents

Index

privacy and legal statement

4518PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-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.)
...	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, 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 a required choice of options; 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 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 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.