Compaq DECset for OpenVMS

Cookbook for an Integrated Project Development Environment

August 2000

This document is a collection of articles written by various individuals in the DECset Engineering group. It describes some of the main features of the Compaq DECset for OpenVMS software and how the individual tools can be used to form an integrated development environment.

Revision/Update Information: This is a revised document.

Software Version: Compaq DECset for OpenVMS, Version 12.4

Compaq Computer Corporation
Houston, Texas

COMPAQ, VAX, VMS, the Compaq logo, and the DIGITAL logo Registered in U.S. Patent and Trademark Office.

DECnet, DECset, DECwindows, eXcursion, OpenVMS, and PATHWORKS are trademarks of Compaq Information Technologies Group, L.P.

Microsoft, Visual C++, Windows, and Windows 95, Windows 98, Windows 2000, and Windows NT are trademarks of Microsoft Corporation.

Motif is a registered trademark of The Open Group.

All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq or authorized sublicensor 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 publication is subject to change without notice and is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK ARISING OUT OF THE USE OF THIS INFORMATION REMAINS WITH RECIPIENT. IN NO EVENT SHALL COMPAQ OR EDS BE LIABLE FOR ANY DIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL, PUNITIVE, OR OTHER DAMAGES WHATSOEVER (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, OR LOSS OF BUSINESS INFORMATION), EVEN IF COMPAQ OR EDS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. THE FOREGOING SHALL APPLY REGARDLESS OF THE NEGLIGENCE OR OTHER FAULT OF EITHER PARTY AND REGARDLESS OF WHETHER SUCH LIABILITY SOUNDS IN CONTRACT, NEGLIGENCE, TORT, OR ANY OTHER THEORY OF LEGAL LIABILITY, AND NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY LIMITED REMEDY.

The limited warranties for Compaq and EDS products are exclusively set forth in the documentation accompanying such products. Nothing herein should be construed as constituting a further or additional warranty.

Contents

Chapter 1
Introduction

The Compaq DECset for OpenVMS tool set consists of the following core components:

Compaq Code Management System for OpenVMS (CMS)
Compaq Language-Sensitive Editor for OpenVMS (LSE)
Compaq Source Code Analyzer for OpenVMS (SCA)
Compaq Module Management System for OpenVMS (MMS)
Compaq Digital Test Manager for OpenVMS (DTM)
Compaq Performance and Coverage Analyzer for OpenVMS (PCA)

In addition to these components, DECset also includes the Compaq DECset Environment Manager for OpenVMS, which is a tool that provides a single mechanism for tailoring the execution environment across the DECset tools.

To provide support for the Windows programming environment, client applications are also available for CMS and MMS. The Compaq DECset Clients for CMS and MMS enable PC desktop access to CMS libraries and frequently used MMS and CMS features that reside on OpenVMS systems. This offers the opportunity to take advantage of convenient access to CMS features through the Windows interface, the API, or through Microsoft Visual Studio. The DECset Clients run on Windows 95, Windows 98, Windows 2000, and Windows NT systems.

1.1 Main DECset Tools

All the DECset tools run on the Compaq OpenVMS Operating System (VAX and Alpha platforms) and have both command-line and Compaq DECwindows Motif for OpenVMS interfaces. LSE/SCA, CMS, and DTM also provide an interface via routines which may be called from the majority of languages supported on OpenVMS.

1.1.1 Compaq Code Management System for OpenVMS (CMS)

CMS is a code management tool providing an efficient method for storing files and tracking all changes to those files.

CMS stores any RMS supported file type. CMS tracks changes in ASCII text files by storing only the changes. This not only reduces the amount of disk space used for storing multiple versions of files but allows CMS to reconstruct any previous version and to identify the changes made between any two versions. In addition to storing successive changes, CMS maintains a record of who is currently working on a library element and a historical record of library access.

Detailed information on CMS can be found in:

Compaq DECset for OpenVMS Software Product Description
Compaq Code Management System for OpenVMS Release Notes (SYS$HELP:CMS*.RELEASE_NOTES)
CMS DECwindows and command-line online help
Guide to DIGITAL Code Management System for OpenVMS Systems
DIGITAL Code Management System Reference Manual
DIGITAL Code Management System Callable Routines Reference Manual

1.1.2 Compaq Language-Sensitive Editor for OpenVMS (LSE)

LSE is a text editor (built on top of DECTPU) with a built-in knowledge of many languages. It supports the expansion and customization of the edit environment to match programming and style preferences. From within LSE programmers can edit, compile, review diagnostics from compilations, and also correct compile time errors. Programmers can perform low-level program designs with LSE by embedding pseudocode in source code. They can also view source code at various levels of detail by replacing a sequence of source lines with a single overview line.

Detailed information on LSE can be found in:

Compaq DECset for OpenVMS Software Product Description
Compaq Language-Sensitive Editor for OpenVMS Release Notes (SYS$HELP:LSE*.RELEASE_NOTES)
DECwindows and command-line online help. LSE has both Portable and VMSLSE command language help.
Guide to DIGITAL Language-Sensitive Editor for OpenVMS Systems
DIGITAL Language-Sensitive Editor Command-Line Interface and Callable Routines Manual
DECset Guide to Detailed Program Design for OpenVMS Systems

1.1.3 Compaq Source Code Analyzer for OpenVMS (SCA)

SCA is an interactive cross-reference and static analysis tool that works with many languages and also provides navigation capabilities to assist users in checking the consistency and locating and viewing components of source code.

Detailed information on SCA can be found in:

Compaq DECset for OpenVMS Software Product Description
Compaq Source Code Analyzer for OpenVMS Release Notes (SYS$HELP:SCA*.RELEASE_NOTES)
SCA (and LSE) DECwindows and command-line online help. Like LSE, SCA also has both portable and VMSLSE versions of its help files.
Guide to DIGITAL Source Code Analyzer for OpenVMS Systems
DIGITAL Source Code Analyzer Command-Line Interface and Callable Routines Manual
DECset Guide to Detailed Program Design for OpenVMS Systems

1.1.4 Compaq Module Management System for OpenVMS (MMS)

MMS automates and simplifies the building of software applications. By rebuilding only those components (and their dependencies) in a system that have changed since the system was last built, MMS also helps to optimize the build process. For supported languages, MMS can now automatically generate description files (see Chapter 3).

Detailed information on MMS can be found in:

Compaq DECset for OpenVMS Software Product Description
Compaq Module Management System for OpenVMS Release Notes (SYS$HELP:MMS*.RELEASE_NOTES)
MMS DECwindows and command-line online help
Guide to DIGITAL Module Management System for OpenVMS Systems

1.1.5 Compaq Digital Test Manager for OpenVMS (DTM)

DTM organizes and automates the software regression testing process. It is used to run, review, and store software regression tests and test results. Two types of testing are currently supported:

Non-interactive terminal-oriented or workstation testing, based around command scripts and output capturing
Interactive terminal or DECwindows record-and-play testing

Detailed information on the DTM can be found in:

Compaq DECset for OpenVMS Software Product Description
Compaq Digital Test Manager for OpenVMS Release Notes (SYS$HELP:DTM*.RELEASE_NOTES)
DECwindows and command-line online help
Guide to DIGITAL Test Manager for OpenVMS Systems
DIGITAL Test Manager for OpenVMS Reference Manual

1.1.6 Compaq Performance and Coverage Analyzer for OpenVMS (PCA)

PCA helps analyze the performance of application programs. It can measure where a program spends its time, causes page faulting, and performs I/O. PCA consists of two components: the Collector, and the Analyzer. The Collector gathers performance and coverage data from a running program and writes that data to a performance data file. The Analyzer processes and displays that data in the form of histograms and tables.

Detailed information on PCA can be found in:

Compaq DECset for OpenVMS Software Product Description
Compaq Performance and Coverage Analyzer for OpenVMS Release Notes (SYS$HELP:PCA*.RELEASE_NOTES)
Guide to DIGITAL Performance and Coverage Analyzer for OpenVMS Systems
DECwindows and command-line online help
DIGITAL Performance and Coverage Analyzer for OpenVMS Reference Manual
DIGITAL Performance and Coverage Analyzer for OpenVMS Command-Line Interface Guide

Chapter 2
The Environment Manager

The Compaq DECset Environment Manager for OpenVMS provides a common interface for defining the execution environment for all the DECset tools displaying on a particular DECwindows display device.

The DECwindows interface is provided by the Environment Manager. The command-line interface is provided by new DCL DECset commands. Both of these interfaces are described in Chapter 2 of the Using DECset for OpenVMS Systems. Another good source of information is the online help for DECset and the Environment Manager (DECwindows).

Each tailored execution environment is known as a context, which consists of a named set of values that tailor the DECset tools for a specific activity. Any context may be based upon another context; the base context is known as the parent, and the new context is known as the child context. A child context inherits all the information from its parent. The context information is stored within ASCII text files. Contexts are listed in ASCII text files, known as context databases.

The rest of this chapter shows how to setup a context database and contexts, how and what may be set by a context, and introduces the concept of context inheritance.

2.1 Activating the Environment Manager

The Environment Manager is invoked from the DECset tool selection and context management pull-down menus provided in the Session Manager or FileView windows, or through the DECwindows interface of a DECset application.

Depending on how the Environment Manager is invoked, it is displayed either as an icon or in its expanded form.

From this initial screen you can set up context databases and create and tailor contexts. A context allows you to define settings for the default directory, CMS libraries, Test Manager library, logical names, MMS options, SCA libraries, source directories, and symbols. Be careful when setting a default directory, as every invocation of a DECset tool following the context application will change the user's default directory to the one defined.

2.2 Setting Up a Project Database and Contexts

There are a number of steps involved in setting up a project context:

Project definition and initial set up.
Context database creation.
Project context creation.
Team context creation.
Individual context creation.
Applying and using a context.

2.2.1 Project Definition and Initial Setup

Some initial groundwork is required before creating project contexts. This involves specifying how the project directories and files are to be organized, how the DECset tools are to look and behave, and what definitions and symbols are to be available.

Most of this information is project/company specific, but for the purposes of these examples, the project is broken down into a number of teams, each team defines their directory and library structure, and the team members tailor their own contexts.

The directory and library structures are illustrated in Figure 2-1.

Figure 2-1 Example Project Directory Structure

DISK2:[PROJECT_EG...] | ..------+------------------+----------------+------------+-----.. | | | | [TESTING] [DOCUMENTATION] [SOURCE] [TEAMS] | | | | +------+----.. +----+------+ | +-----+-----+ | | | | | | [INTEGRATION] [DOC_CMSLIB] [DOC_REF] | [TEAM_A] .. [TEAM_n] | | : : +------+------+ +----------+------------+ | | | | | [DTMLIB] [DTM_CMSLIB] [SCALIB] [EG_CMSLIB] [EG_REF] ------------------- Release Process ------------------- : [TEAM_Z] | +-----------+------------+------------+------------+-----.. | | | | | [ACCOUNTS] [SOURCE] [TESTING] [RELEASE] [BUILD] | | | : | <user accounts> | +-----+------+ +------+----.. | | | | | | [DTMLIB] [TST_CMSLIB] [OBJ] [EXE] | +------------+-----------+----------+---------+ | | | | | [SRC_CMSLIB] [DOC_CMSLIB] [SRC_REF] [DOC_REF] [SCALIB]

In this example:

The entire project resides on one disk (DISK2).
All project files reside under the main project directory (PROJECT_EG).
The team directories and libraries reside under a team directory (TEAMS).
All the Test Manager libraries use CMS libraries.
All the non-Test Manager CMS libraries have reference directories.
There is also an undefined release process to handle the transfer of files from a team to the project; otherwise, each team is responsible for its own code management.

The examples in this chapter show the setting up of three contexts: a project context (PROJECT_EG), a team context (TEAM_Z), and a user context (TOWNSEND). In reality, many other contexts may also be required: contexts for QA, source code librarians, project managers, documentation, release testing, and so on.

Once the project structure has been defined, the next step is to create all the directories and libraries. Figure 2-2 and Figure 2-3 show the creation of SCA and CMS libraries for PROJECT_EG and a test library for TEAM_Z. Subsequent examples assume that all the directories and libraries have been fully created.

Figure 2-2 Creating an SCA and a CMS Library

$ CREATE/DIRECTORY DISK2:[PROJECT_EG.SOURCE.SCALIB] $ SCA CREATE LIBRARY DISK2:[PROJECT_EG.SOURCE.SCALIB] %SCA-S-NEWLIB, SCA Library created in DISK2:[PROJECT_EG.SOURCE.SCALIB] $ CREATE/DIRECTORY DISK2:[PROJECT_EG.SOURCE.EG_CMSLIB] ! library $ CREATE/DIRECTORY DISK2:[PROJECT_EG.SOURCE.EG_REF] ! reference directory $ SET DEFAULT DISK2:[PROJECT_EG.SOURCE] $ CMS CREATE LIBRARY [.EG_CMSLIB] /REFERENCE_COPY=[.EG_REF] _Remark: PROJECT_EG CMS Library %CMS-S-CREATED, CMS Library DISK2:[PROJECT_EG.SOURCE.EG_CMSLIB] created

Figure 2-3 Creating a Test Library

$ CREATE/DIRECTORY DISK2:[PROJECT_EG.TEAMS.TEAM_Z.TESTING.DTMLIB] $ CREATE/DIRECTORY DISK2:[PROJECT_EG.TEAMS.TEAM_Z.TESTING.TST_CMSLIB] $ SET DEFAULT DISK2:[PROJECT_EG.TEAMS.TEAM_Z.TESTING] $ CMS CREATE LIBRARY [.TST_CMSLIB] "Testing CMS Library" %CMS-S-CREATED, CMS Library ...TST_CMSLIB] created $ DTM DTM> CREATE LIBRARY [.DTMLIB] "Test DTM Library" %DTM-S-CREATED, Digital Test Manager library ...DTMLIB] created DTM> SET TEMPLATE_DIRECTORY CMS$LIB "" %DTM-S-NEWDEF, ...TST_CMSLIB] is the new default collection template directory DTM> SET BENCHMARK_DIRECTORY CMS$LIB "" %DTM-S-NEWDEF, ...TST_CMSLIB] is the new default collection benchmark directory DTM> EXIT

2.2.2 Context Database Creation

After the creation of the directories and libraries, the next step is to create the project context database. This can be achieved by with the Environment Manager, as follows:

Select New Database from the File pull-down menu.
Enter the appropriate information.
Click the OK button.

Although the database is now be available, no physical file is created until the first context is defined and saved.

2.2.3 Project Context Creation

A project context can be created from with the Environment Manager, as follows:

Select New Context from the File pull-down menu.
Enter the appropriate information.
Click the OK button and the context is created.
All the examples throughout this chapter use the logical name DISK2 to define the disk. However, as the Environment Manager expands all the logical names used in directory specifications, in many of the examples, the translation of the logical for DISK2 ($1$DIA3) is displayed.
Define the context settings. As this process is both straight-forward and described in some detail in the Environment Manager's documentation, examples are limited to the definition of a few logical names and a test library .

Figure 2-4 contains extracts from a defined project context file.

Figure 2-4 Context File for PROJECT_EG

! ! Context file $1$DIA3:[PROJECT_EG]PROJECT_EG.DECSET_CONTEXT ! Written by DECset Environment Manager at 31-OCT-1995 14:17:37.03 ! DEFINE/TABLE=LNM$PROCESS DTM$LIB - DISK2:[PROJECT_EG.TESTING.INTEGRATION.DTMLIB] DEFINE/TABLE=LNM$PROCESS CMS$LIB - DISK2:[PROJECT_EG.SOURCE.EG_CMSLIB],DISK2:[PROJECT_EG.DOCUMENTATION.DOC_CMSLIB] DEFINE/TABLE=LNM$PROCESS SCA$LIBRARY - DISK2:[PROJECT_EG.SOURCE.SCALIB] : SET_DIRECTORY SOURCE - DISK2:[PROJECT_EG.SOURCE] CMS SET LIBRARY - DISK2:[PROJECT_EG.SOURCE.EG_CMSLIB], - DISK2:[PROJECT_EG.DOCUMENTATION.DOC_CMSLIB] SCA SET LIBRARY - DISK2:[PROJECT_EG.SOURCE.SCALIB] DTM SET LIBRARY DISK2:[PROJECT_EG.TESTING.INTEGRATION.DTMLIB] SET_MMS RULES : SET_MMS NOLOG

As a context file is an ASCII text file, it may be edited to remove or add context information. For example, you might find it quicker to add numerous symbols manually instead of using the symbol definition screen. The online help describes the format of a context file (see Figure 2-5).

Figure 2-5 $ HELP DECSET CONTEXT_FILE

Context_File : CMS_SET_LIBRARY DTM_SET_LIBRARY Comments DEASSIGN DEFINE DELETE_SYMBOL SCA_SET_LIBRARY SET_DEFAULT SET_DIRECTORY SET_LINKER SET_MMS Symbol_Assignment

2.2.4 Team Context Creation

Team contexts (for example TEAM_Z) are created as child contexts of the main project context (PROJECT_EG).

The steps to create a team context are the same as those for the project (see Section 2.2.3), except the project context is specified as a parent context.

As with the project context, once the team context has been created, the next stage is to define the settings. The following steps show how a linker options file (for MMS builds) can be defined:

Select MMS Options from the Settings pull-down menu, then select Linker Options. This brings up the MMS Linker Options Files dialog box.
Click the Select Option File button and specify the options file .
Click the OK button to return to the MMS Linker Options Files dialog box.
Click the Append button to add the options into the list.
Click the OK button to set the options file.

Figure 2-6 contains extracts from the TEAM_Z context file after setting the libraries and source directories, an MMS rules file, a default description file, a linker options files and some symbols.

Figure 2-6 Context File for TEAM_Z

! ! Context file $1$DIA3:[PROJECT_EG]TEAMZ.DECSET_CONTEXT ! Written by DECset Environment Manager at 31-OCT-1995 17:11:59.71 ! DEFINE/TABLE=LNM$PROCESS SCA$LIBRARY - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SCALIB] DEFINE/TABLE=LNM$PROCESS DTM$LIB - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.TESTING.DTMLIB] : DEFINE/TABLE=LNM$PROCESS CMS$LIB - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SRC_CMSLIB], - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.DOC_CMSLIB] LEADER == "EDSDS1::SMITH" : QA == "EDSDS1::JONES" SET_DIRECTORY SOURCE - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE] CMS SET LIBRARY - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SRC_CMSLIB], - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.DOC_CMSLIB] SCA SET LIBRARY - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SCALIB] DTM SET LIBRARY DISK2:[PROJECT_EG.TEAMS.TEAM_Z.TESTING.DTMLIB] SET_MMS RULES=DISK2:[PROJECT_EG.TEAMS.TEAM_Z.BUILD.TOOLS]RULES.MMS SET_MMS DESCRIPTION=( - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.BUILD.TOOLS]DESCRIP.MMS) SET_MMS SCA_LIBRARY SET_LINKER OPTIONS_FILE - DISK2:[PROJECT_EG.TEAMS.TEAM_Z.BUILD.TOOLS]C.OPT SET_MMS NOOVERRIDE SET_MMS CMS : SET_MMS NOLOG

2.2.5 Personal Context Creation

A personal or user context (for example, TOWNSEND) is created as a child context of the team context. The steps to create it are identical to those for TEAM_Z (see Section 2.2.4), except TEAM_Z is specified as the parent.

No examples are given here for how a personal context may be tailored. However, for the purposes of this example, the following definitions are assumed:

Redefinition of the LSE environment and section files to pick up the local customizations.
Definition of a local SCA library in a search list with the team's library.
MMS definitions to build from the source directories, rather than CMS, by default, and specification for compilation settings (Diagnostic and Debug flags).

You can show how a context combined with its parent contexts will tailor an environment by selecting View Context Including Inheritance from the View pull-down menu in the Environment Manager.

The equivalent command-line command is DECSET SHOW CONTEXT. Figure 2-7 contains extracts from this command for the TOWNSEND context.

Figure 2-7 $ DECSET SHOW CONTEXT

$ DECSET SHOW CONTEXT Context TOWNSEND -------------------------------------------------- Context description: DECUS Presentation Example Individual Context Name of parent context: TEAMZ Database file spec: $1$DIA3:[PROJECT_EG]PROJECT.DECSET_CONTEXT_DB Context file spec: $1$DIA3:[PROJECT_EG.TEAMS.TEAM_Z.USERS.TM1]PT1.DECSET_CONTEXT; No default directory was specified. Logical Name Definitions + Deassignments (by table): Logical Name Table: LNM$PROCESS Definitions: DTM$LIB = DISK2:[PROJECT_EG.TEAMS.TEAM_Z.TESTING.DTMLIB] CMS$LIB = DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SRC_CMSLIB] DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.DOC_CMSLIB] SCA$LIBRARY = DISK2:[PROJECT_EG.TEAMS.TEAM_Z.USERS.TM1.WORK.SCALIB] DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SCALIB] LSE$SOURCE = DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE] DOC$ = DISK2:[PROJECT_EG.DOCUMENTATION.DOC_REF] SRC$ = DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCES] TOOLS$ = DISK2:[PROJECT_EG.TEAMS.TEAM_Z.BUILD.TOOLS] Deassignments: Logical Name Table: LNM$JOB Definitions: LSE$SECTION = DISK2:[PROJECT_EG.SOURCE]LSE$SECTION.TPU$SECTION LSE$ENVIRONMENT = DISK2:[PROJECT_EG.SOURCE]LSE$ENVIRONMENT.ENV Deassignments: Symbol definitions: : Symbol deletions: MMS macro definitions: Source directories: DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE] CMS libraries: DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SRC_CMSLIB] DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.DOC_CMSLIB] SCA libraries: DISK2:[PROJECT_EG.TEAMS.TEAM_Z.USERS.TM1.WORK.SCALIB] DISK2:[PROJECT_EG.TEAMS.TEAM_Z.SOURCE.SCALIB] DTM libraries: DISK2:[PROJECT_EG.TEAMS.TEAM_Z.TESTING.DTMLIB] MMS macro definition files: MMS rules file: DISK2:[PROJECT_EG.TEAMS.TEAM_Z.BUILD.TOOLS]RULES.MMS MMS description files: DISK2:[PROJECT_EG.TEAMS.TEAM_Z.BUILD.TOOLS]DESCRIP.MMS MMS changed sources: MMS SCA library to generate: : Linker options files: DISK2:[PROJECT_EG.TEAMS.TEAM_Z.BUILD.TOOLS]C.OPT MMS-related Flags: Override macros: 0 : Enable DEBUG macro (MMS): 0 : [End of Listing]