Document revision date: 30 March 2001
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

Guide to Creating OpenVMS Modular Procedures

Previous Contents Index

4.6 Monitoring Procedures in the Run-Time Library

The run-time library (RTL) contains several procedures for time and resource monitoring. These RTL procedures and their functions are as follows:

For more information about these time and resource monitoring procedures, see the OpenVMS RTL Library (LIB$) Manual.

Chapter 5
Integrating Modular Procedures

Modular procedure libraries consist of compiled and assembled object code intended to be associated with a calling program at link time. The linker resolves references to procedures in these libraries when it searches user libraries specified in the LINK command, or when it searches the default system libraries. The program can then call library procedures at run time.

Compaq supplies several procedure libraries, such as the Run-Time Library, that support components of the OpenVMS operating system. You can use procedures in the Run-Time Library to perform frequently used operations by including calls to Run-Time Library procedures in your program. The linker automatically searches the default libraries to resolve references to Run-Time Library procedures. (For information about the procedures available in the Run-Time Library, see the OpenVMS Programming Concepts Manual.)

This chapter briefly describes how you can create your own procedure libraries and shareable images. For more information about creating libraries and shareable images, use the guidelines in the OpenVMS Linker Utility Manual.

5.1 Creating Facility Prefixes

A facility prefix is the group identifier for a set of related procedures contained in a library facility. The facility prefix appears in the procedure name of every procedure in that library facility. An example of a library facility is the Screen Management facility in the Run-Time Library. The names of all the procedures in the Screen Management facility begin with SMG, for example, SMG$ERASE_CHARS.

To create your own facility prefix, follow these steps:

  1. Choose a facility prefix. This prefix can be from 1 to 27 characters in length. However, Compaq recommends that you choose facility prefixes between 2 and 4 characters.
  2. If your facility will be generating messages, you must specify a unique facility number in the message source file. This number can range from 0 to 4095. Any number within this range, and not being used by someone else on your system, is acceptable. This facility number is used by the message utility in generating the condition value for the message.
    Bit 27 (STS$V_CUST_DEF) of a condition value indicates whether that value is supplied by the user or by Compaq. This bit must be 1 if the facility number is user created. For more information, see the OpenVMS System Messages and Recovery Procedures Reference Manual1.
  3. Use the facility prefix when naming all procedures within the new facility. Remember to follow the naming conventions described in Section 3.1.1.


1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM.

5.2 Creating Object Module Libraries

In addition to using the system default object module libraries, you can create your own object module libraries. An object module library that you create can contain object files produced by any language compiler supported by the OpenVMS operating system.

For more information about creating object module libraries, see the OpenVMS Linker Utility Manual.

5.3 Creating Shareable Image Libraries

If you have a collection of procedures you expect a number of users to use, you can group these procedures into a shareable image library. A shareable image library is similar to an object library, except that it has been prelinked so that all references between procedures in the library have already been resolved.

A shareable image has the following advantages:

For more information about creating shareable image libraries, see the OpenVMS Linker Utility Manual.

Chapter 6
Maintaining Modular Procedures

This chapter describes important aspects of maintaining modular procedures. Specifically, it covers the following topics:

6.1 Making Your Procedures Upwardly Compatible

Upward compatibility is very important when maintaining procedures. If a procedure is upwardly compatible, changes and updates to the procedure do not affect executing and using previous versions of that procedure.

For example, imagine a user-written procedure named LIB_TOTAL_BILL. The calling sequence for this procedure is as follows:


Assume that the user who wrote this procedure decided to update the procedure so that it could be used to calculate the total bill for credit-card customers. To do this, a third argument, interest, must be added. To be upwardly compatible, adding the argument interest must not conflict with the way the procedure was previously run. The new calling sequence would be as follows:

CALL LIB_TOTAL_BILL (sale, tax [,interest])

The procedure should be written so that the user can still call the procedure as it was called before, simply omitting the interest argument.

If, in the updated version of this procedure, the user can still follow the calling sequence of the previous versions, the procedure is said to be upwardly compatible.

To ensure that your procedures are compatible with future versions of a shareable image, see the OpenVMS Linker Utility Manual.

6.2 Regression Testing

Regression testing is a method of ensuring that new features added to a procedure do not affect the correct execution of previously tested features. In regression testing, you run established software tests and compare test results with expected results. If the actual results do not agree with what you expected, the software being tested may have errors. If errors do exist, the software being tested is said to have regressed.

Regression testing includes the following steps, as shown in Figure 6-1:

  1. Create tests by writing command files to test your software.
  2. Organize files to allow easy access to tests as they are needed.
  3. Run tests as follows:
  4. Calculate the expected test results either by hand or by using previously tested software.
  5. Compare actual test results to the results you expected. If there are inconsistencies, repeat your calculation in step 4. If the inconsistency still exists, examine the changes you have made to the software to discover the error.

Figure 6-1 Regression Testing

It is important to write new tests and repeat the regression testing steps every time you add new functionality to the procedure. If you do not do so, the procedure may regress while the errors go undetected.

6.3 Adding Arguments to Existing Routines

During the normal course of maintenance, it sometimes becomes necessary to pass new or additional information to an existing procedure rather than create a new procedure. This new information can be passed to the procedure in one of the following two ways:

6.3.1 Adding New Arguments to the Procedure

There are two rules you must follow when directly adding new arguments to a procedure:

It is important that new arguments be added at the end of the existing argument list to maintain upward compatibility. If you change the order of the existing arguments by placing the new argument at the beginning or middle of the list, all applications written with the previous version of the procedure will no longer work.

Your procedure should also treat the new argument as an optional argument. If the new argument is required, applications that used the previous version of the procedure are invalidated.

Because you cannot assume that all previously written applications will be rewritten to include the procedure's new argument, the procedure must test for the argument's presence before attempting to access it. If the procedure does not verify the presence of the new argument and attempts to access that argument when it is not present, the results will be unpredictable.

The passing mechanism of the new argument must conform to the guidelines in Section 2.2.1.

6.3.2 Using Argument Blocks

By using an argument block, you can avoid adding multiple arguments to your procedure. When an argument block is used, the calling program passes a single argument to the called procedure. This argument is the address of an argument block. The argument block is a block of information containing any information agreed on by the calling and called procedures. This information is required by the called procedure to perform its task.

The argument block is simply a contiguous piece of virtual memory. The information contained in the argument block can be numeric or scalar data, descriptors, bit vectors, and so on. The format is agreed on by the users of the procedure and its writer.

The first longword in the argument block contains the length of the block. The length can be in bytes or longwords, but it must be agreed on by both the calling program and the called process, and be implemented and documented as such.

One example of an argument block is the signal argument vector used in condition handling. A condition handler is called with a signal argument vector and a mechanism argument vector. Each vector is an example of an argument block. The signal argument vector in Figure 6-2 is an example of an argument block.

Figure 6-2 One Type of Argument Block, the Signal Argument Vector

The signal argument vector contains the number of longwords of actual information in its first longword. What information actually follows depends on the condition value of the signal.

Note that if you lengthen an argument block to provide new information to a called procedure, your procedure should check the length of the argument block for validity before attempting to access the information. As with adding new arguments directly to a procedure, the calling program may have been written to pass the previous, shorter argument block. If your procedure does not check and attempts to access information past the end of the actual argument block, the results will be unpredictable.

6.4 Updating Libraries

Any time you make modifications or enhancements to modular procedures that are a part of a library, you must update the library containing the procedures to reflect the new or changed procedures.

6.4.1 Updating Object Libraries

If the updated procedures are in an object library, the library must be updated so that subsequent access to that library by LINK or other commands will access the object modules for the new or changed procedures.

To update an object library, use the LIBRARY command with the REPLACE qualifier, as follows:

$ LIBRARY /REPLACE library-name filespec[,...]

In this example, library-name is the name you have given the library. The default file type for library-name is OLB. The name of an object module is filespec. The default file type for filespec is OBJ.

6.4.2 Updating Shareable Images

If the updated procedures are part of a shareable image, you must relink the shareable image so that it contains the new or changed versions of any updated object modules. If you add new procedures, you must update and recompile the transfer vector (on VAX systems) or symbol vector (on Alpha systems) before relinking the shareable image. If you add new modules, you must update the linker options file before relinking. If you add new procedures and new modules, you must update the transfer vector (on VAX systems) or symbol vector (on Alpha systems) and the linker options file. If you change the transfer vector (on VAX systems) or symbol vector (on Alpha systems), you must increment the minor identification value of the GSMATCH by one. You can then relink the shareable image.

For more information about updating shareable images, see the OpenVMS Linker Utility Manual.

Appendix A
Summary of Modular Programming Guidelines

This appendix summarizes the modular programming guidelines that are described in this manual. References to the appropriate sections appear after each guideline. The word Optional appears before the section reference if the guideline is not required to maintain modularity.

A.1 Coding Rules

The coding rules in this section pertain to all procedures. These rules are grouped in the following categories:

Detailed descriptions of the rules for each of these categories are presented in the sections that follow.

A.1.1 Calling Interface

A.1.2 Initializing

A.1.3 Reporting Exception Conditions

A procedure must not print error or informational messages either directly or by calling the $PUTMSG system service. It must either return a condition value in R0 as a function value or call LIB$SIGNAL or LIB$STOP to output all messages. (LIB$SIGNAL and LIB$STOP can be called either directly or indirectly.) (See Section 2.5.)


1 This manual has been archived but is available on the OpenVMS Documentation CD-ROM.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement