|Document revision date: 30 March 2001|
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.
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 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.
This chapter describes important aspects of maintaining modular procedures. Specifically, it covers the following topics:
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:
CALL LIB_TOTAL_BILL (sale, tax)
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:
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:
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
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.
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 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.
|privacy and legal statement|