If you intend to use VDE to build your software system, you must set up a directory tree for each development stream that you want to build. That directory tree will contain clear copies (as opposed to delta-file copies) of your source files along with all output files produced by the builds. If you intend to use VDE only for source control and not for building, you do not need directory trees for streams unless you want VDE to maintain clear copies of your modules for debugging or for general reference. This section explains both how to set up stream directory trees if needed and how to suppress them if not needed.

By default, VDE creates a directory tree for each new development stream that you create. The root directory for this directory tree has the same name as the stream and is a subdirectory of the library root directory. Any periods (.) in the stream name are changed to underscores (_) in the directory name to maintain valid OpenVMS file names. Within the stream root directory, there is one subdirectory for each facility in your software system. Each such subdirectory has the same name as the facility. Table 6-3 shows this structure.

Within each facility subdirectory, VDE creates several additional subdirectories. By default, there are four such subdirectories called SRC, OBJ, VDE$COM, and VDE$LOG. The SRC subdirectory is meant to hold source files in clear-copy form. The OBJ directory is meant to hold object files, executable images, and all other derived modules that can be produced when your software system is built. The VDE$COM subdirectory will hold command files that VDE creates to perform build steps and the VDE$LOG subdirectory will hold the corresponding log files. The contents of the VDE$COM and VDE$LOG subdirectories are thus under VDE control while the contents of the SRC and OBJ directories are under your control when you set up the VDE library. These subdirectories are further illustrated in Table 6-3.

Table 6-3 Stream Disk Directories

Library root directory:	DEV$:[ROOTDIR]
Stream V1.5 root directory:	DEV$:[ROOTDIR.V1_5]
Facility FACNAM root directory:	DEV$:[ROOTDIR.V1_5.FACNAM]
Source-file subdirectory:	DEV$:[ROOTDIR.V1_5.FACNAM.SRC]
Object-file subdirectory:	DEV$:[ROOTDIR.V1_5.FACNAM.OBJ]
VDE build subdirectory:	DEV$:[ROOTDIR.V1_5.FACNAM.VDE$COM]
VDE build log-file subdirectory:	DEV$:[ROOTDIR.V1_5.FACNAM.VDE$LOG]
Source file MUMBLE.C:	DEV$:[ROOTDIR.V1_5.FACNAM.SRC]MUMBLE.C
Object file MUMBLE.OBJ:	DEV$:[ROOTDIR.V1_5.FACNAM.SRC]MUMBLE.OBJ

You can direct VDE to create additional subdirectories within the facility root directory and you can explicitly specify your own locations for the stream and facility root directories. This topic is covered in more detail later in this section.

Suppressing Stream Directories

If you want to use VDE for source control only and not for building, you may want to suppress the creation of stream directory trees because you are not going to use them. (However, if you want VDE to maintain clear copies of source files on replacement then you do need stream directories.) To suppress creation of stream directory trees, take the following steps:

• Specify the /DEFER qualifier with the CREATE LIBRARY command. This qualifier prevents VDE from creating the directory tree for the default stream MAIN when creating the library.
• Enter CREATE DIRECTORY_TREE commands with the /DELTA_FILES and /STAGING qualifiers in order to create the delta-file directory tree and the staging area root directory. See Section 6.3.1 and Section 6.3.2.
• Enter the SET DIRECTORY command with the /STREAM and /DEFER qualifiers for stream MAIN:

  VDE„ SET STREAM MAIN VDE„ SET DIRECTORY /STREAM /DEFER

  /DEFER specifies that when new streams are created from the current stream, directory-tree creation will be deferred for those streams. This means that the descendants of stream MAIN will not get directory trees unless you enter explicit CREATE DIRECTORY_TREE commands for them.

After these steps are done, you can create new streams with the CREATE STREAM command as needed. Because of the SET DIRECTORY command, each subsequent CREATE STREAM command has an implicit /DEFER qualifier which suppresses creation of the stream's directory tree.

Defining Your Own Stream Directories

If you need stream directory trees but you do not like the default directory structure or placement, then you can define your own stream directories. One way to do so is to explicitly specify the root directory for new streams when you create the streams. Another way is to use the SET DIRECTORY command with the /STREAM qualifier to specify the directory structure and placement you want for a given stream. You can enter multiple SET DIRECTORY commands to specify different aspects of the desired directory structure; together these commands define a template for the directory structure and placement that you want. Then use the CREATE DIRECTORY_TREE command with the /STREAM qualifier to actually create the directory tree for that stream. In addition, any future child streams that are created from a given stream will inherit the directory structure of the parent. The actual directory trees for such descendant streams are created when the streams are created.

The following are the options you have in specifying the directory structure and placement for streams:

• To specify the placement of a new stream's root directory, create the stream using the /DIRECTORY qualifier with the CREATE STREAM command:

  VDE„ CREATE STREAM BIRCH /DIRECTORY=DEV2$:[MY_BIRCH]

  This example creates stream BIRCH and makes DEV2$:[MY_BIRCH] its root directory. This is generally the best way to specify the root directory for a new development stream. Specifying stream root directories this way allows you to spread your VDE library over multiple disks for better performance and disk utilization.
  You can also specify that all future descendants of the current stream must have their root directories specified when those streams are created. To do so, enter a SET DIRECTORY command with the /PROMPT qualifier for the current stream. For example:

  VDE„ SET STREAM BIRCH VDE„ SET DIRECTORY /STREAM /PROMPT

  These commands specify that a stream root directory must be explicitly specified for each future descendant of the existing stream BIRCH. When each such descendant is created with the CREATE STREAM command, VDE prompts the user for the name of the stream root directory unless the user specifies it with the /DIRECTORY qualifier. This feature is useful when you want each future stream's directory tree to go on a separate device to be selected when the stream is created.
  Note that the SET DIRECTORY /STREAM command acts on the current default stream. For it to act on a given stream, you must thus set that stream using the SET STREAM command, as shown in the example.

• To specify the placement of the root directory of an already existing stream's directory tree, use the SET DIRECTORY command with the /STREAM qualifier. Then use the CREATE DIRECTORY_TREE command to actually create the stream directory tree. For example:

  VDE„ SET STREAM BIRCH VDE„ SET DIRECTORY /STREAM DEV2$:[MYDIR] VDE„ CREATE DIRECTORY_TREE /STREAM VDE„ CANCEL DIRECTORY /STREAM

  The first three commands make directory DEV2$:[MYDIR] the root directory for the existing stream BIRCH. If these commands are not specified, VDE uses subdirectory BIRCH in the library root directory by default. After you have created the directory tree, you should use the CANCEL DIRECTORY command to prevent future child streams from inheriting the DEV2$:[MYDIR] root directory. This ensures that subsequent streams created from stream BIRCH do not attempt to use the same root directory; instead they get a subdirectory within the library root directory by default.

• To specify the placement of the root directory for a given facility for the current stream, use the /FACILITY qualifier as well:

  VDE„ SET STREAM BIRCH VDE„ SET DIRECTORY /STREAM /FACILITY=FOO DEV2$:[BIRCHFOO] VDE„ CREATE DIRECTORY_TREE /STREAM/ /FACILITY=FOO VDE„ CANCEL DIRECTORY /STREAM /FACILITY=FOO

  These commands make directory DEV2$:[BIRCHFOO] the root directory for facility FOO within stream BIRCH. If this command is not specified, VDE uses subdirectory FOO within the stream root directory by default. This form of the SET DIRECTORY command is seldom used because there is usually no need to place the directories for an individual facility on a different disk than other facilities. However, if you do use it, use the indicated CANCEL DIRECTORY command after creating the directory so that subsequent child streams will not use the same directory.

• To specify that a given stream's directory tree should have additional subdirectories within each facility's root directory, use the /SUBDIRECTORY qualifier to the SET DIRECTORY command. To specify that each facility should have a subdirectory for analysis (.ANA) files, for example, you would use the following commands:

  VDE„ SET STREAM BIRCH VDE„ SET DIRECTORY /STREAM /SUBDIRECTORY=ANASYM [.ANA]

  This SET DIRECTORY command specifies that each facility in stream BIRCH and its descendant streams should have a subdirectory ANA. The form of the directory specification [.ANA] indicates that it is relative to each facility's root directory. The ANASYM parameter is a directory symbol which is used later in VDE scripts to reference the new subdirectory. (Usually the directory symbol is the same as the directory name but here they differ for clarity of exposition.)
  VDE gives you four facility subdirectories by default: SCR, OBJ, VDE$COM, and VDE$LOG. The /SUBDIRECTORY qualifier to SET DIRECTORY allows you to specify additional such subdirectories. As always, the SET DIRECTORY command only creates a template for the desired directory tree; the actual directories are not created until you use the CREATE DIRECTORY_TREE command or create new streams that inherit the template from their parent.

These various ways of specifying directory placement and structure give you considerable control over VDE's stream directory trees. You can spread your VDE library over multiple disks using these capabilities. You can control how the various subdirectories for each facility are used by the way that you write the VDE scripts that determine how build steps and certain other operations are performed.

6.4 Adding Users to the Library

Before users other than yourself (the library creator) can use the new VDE library you have created, those users must be added to the library's database. This was described briefly in Section 6.2.3. When a user is added to the database, VDE creates a User Table entry for the user in the VDE database. When that user subsequently tries to access the VDE library through the VDE utility, VDE checks that the user is recorded in the database. Provided this is the case, VDE retrieves the user's VDE privileges and other attributes from the User Table entry and uses those attributes to control the rest of the VDE session. VDE denies access to the library to users who are not recorded in the database.

There are three ways of adding users to your library's database:

• VDE automatically adds the library creator to the database when the library is created. This user is authorized to set all VDE privileges and has all administrative privileges set by default.
• You can use the CREATE USER command to add users. This command lets you manually specify the users to add to the database, including their privileges and other attributes.
• You can enable a library attribute that causes VDE to automatically add new users to the library database when they first access the library through the VDE utility. Each such user gets the standard default and authorized privileges for the library.

The CREATE USER command lets you specify the OpenVMS username, the full name (first and last names), the VDE default and authorized privileges, and certain other information about each user to be added to the database. This is an example of a CREATE USER command that adds user Jane Smith to the database:

VDE„ CREATE USER SMITH /NAME="Jane Smith" /REMARK="Project leader" - _VDE„ /AUTH_PRIVILEGES=(CREFAC,CREMOD,CRESTRM,RESREP,PERFREP) - _VDE„ /DEF_PRIVILEGES=(CREMOD,RESREP,PERFREP)

After this command has completed, Jane Smith can start VDE sessions using the VDE library. By default, she has the privileges necessary to create new source modules, to reserve and replace modules, and to perform queued replacements for herself and other developers. In addition, she is authorized to set the privileges necessary to create new facilities and development streams.

Using the CREATE USER command is the most practical way to add users to a VDE library if the library has a small number of users or if you want to exercise careful control over who accesses the library.

6.4.2 Automatic Addition of Users

If you specify the /AUTO_ADD_USER qualifier with the CREATE LIBRARY or MODIFY LIBRARY command, VDE will automatically add new users to the library database the first time each such user uses VDE to access the library. If this qualifier is used without a parameter, any user who attempts to access the VDE library through VDE is automatically added to the database. Each such user gets the standard default and authorized VDE privileges for that library. The OpenVMS username is retrieved from the operating system. The full name of the user is taken from the owner field of the user's record in the system User Authorization File (UAF). Other attributes, such as the remark string, are not set.

The /AUTO_ADD_USER qualifier can also be specified with a OpenVMS rights identifier parameter, as in /AUTO_ADD_USER=rights-id. In this case, VDE stores the given rights identifier in the database. Subsequently, VDE adds only those users to the database who hold the stored rights identifier. The users are added when they first access the library through VDE, just as for the plain /AUTO_ADD_USER qualifier. This way of adding users is useful when you use a OpenVMS rights identifier to protect the files and directories of your project. Because the intended users of your VDE library must hold the rights identifier anyway, you can use the rights identifier as your mechanism to control access to the library.

If you use automatic addition of users to your VDE library, you should periodically run the program VDE/READ_UAF. This program reads the system user authorization file (SYSUAF) of your OpenVMS system and updates the User Table in your VDE database to be consistent with the SYSUAF. It updates each user's full name in the VDE database to match the owner field in the SYSUAF. VDE/READ_UAF also marks users as deleted in the VDE database if they no longer have accounts in the UAF. VDE/READ_UAF thus allows you to maintain your database User Table by having it automatically track the SYSUAF, which your system manager must maintain anyway. And with /WRITE_UAF, the command can update the process quotas of OpenVMS users in the System Authorization Database (SYSUAF). The VDE/READ_UAF command should be included in a command procedure that runs regularly, perhaps every night or every weekend.

To run VDE/READ_UAF, you must specify the target VDE via the /LIBRARY qualifier or via the VDE$LIBRARY logical name. You must also have read access to the OpenVMS system authorization database, or read and write access when the /WRITE_UAF qualifier is specified. Installation of the VDE/READ_UAF image with enhanced privileges is not recommended. You can execute the program as follows:

$ SET PROCESS/PRIVILEGE=BYPASS $ VDE/READ_UAF/WRITE_UAF/LIBRARY=lib-name

Automatic addition of users is the most practical approach for VDE libraries with a large number of potential users. Even if you automatically add users, you can of course still use the CREATE USER command to add users. This makes sense if you want to add a user who does not hold the rights identifier required to be added automatically or who should be added with a different set of privileges than the standard privileges for the library. In addition, you can always use the MODIFY LIBRARY command to change the privileges or other attributes of any user already recorded in the database.

The VDE/READ_UAF command, with the specification of the /WRITE_UAF qualifier and with read-write access to the System Authorization Database, can update process quotas of VDE users in the System Authorization Database (SYSUAF). This command is particularly useful when users are reporting quota-related messages when invoking VDE.

6.5 Creating Streams

Section under construction...

To create a stream, use the CREATE STREAM command. You normally need to select a parent stream for the operation, and you need to consider the stream propogation order.

VDE„ CREATE STREAM V2.0/PARENT=V1.0

In addition to choosing the parent stream, you need to choose whether or not the new stream is a direct descendent of the parent stream (/MAINLINE), or if it is a variant and will diverge (/NOMAINLINE). (Mainline streams will keep the same generation identification values as the parent, while variant streams select longer generation identification values. The main line of descent is often an integer generation number, while variants tend to include increasing numbers of letters in the identification value. There are no other differences. Once the stream has been created, this setting cannot be easily changed.)

Other qualifiers of interest during stream creation include /CONFERENCE, /[NO]INIT_CMS_CLASS, /NOTIFY, /[NO]GENERATIONS, and /REVIEW.

Once created, streams can be repopulated via a POPULATE STREAM command. Once a stream is populated, either via the initial CREATE STREAM command or via the POPULATE STREAM command, a MODIFY STREAM/NOPOPULATE command should be issued, to prevent accidental repopulation of the stream.

6.5.1 Stream Directory Tree

Section under construction...

Streams typically have an associated directory tree.

6.5.2 Scripts to Populate New Streams

Section under construction...

To cancel a module reservation without replacing the module, use the ...

6.5.3 Stream Successor Relationships

Section under construction...

To cancel a module reservation without replacing the module, use the

6.6 Creating Facilities

Section under construction...

To cancel a module reservation without replacing the module, use the UNRESERVE command. The following example illustrates its use:

VDE„ CREATE FACILITY FACNAM - _VDE„ /REMARK="The fumble utility"

This command cancels the reservation of module MOD.TYP in facility FACIL. The /STREAM qualifier specifies the stream for which the reservation was made. If you omit this qualifier, your default stream is assumed. If you have more than one reservation of the module for that stream, you must specify its reservation identifier with the /IDENTIFICATION qualifier. The command can cancel both queued reservation requests and real reservations.

6.7 Populating a Facility with Modules

Section under construction...

There are various ways to load modules into a VDE database. One can upload modules into a facility from an existing CMS library, an operation that normally only occurs during library creation, and one can also upload a directory containing a number of modules into a facility in a VDE database using the CREATE MODULE/FROM_DIRECTORY command. And one can upload individual modules into a facility using the CREATE MODULE command.

A new VDE database can be created and loaded using the procedure described in Section 6.7.3.

6.7.1 Getting Source Modules from a Directory

One can use the CREATE MODULE/FROM_DIRECTORY command for this task. This command will create one module in the facility for every file found in the specified directory. When /FROM_DIRECTORY is specified, no module name parameter is specified on the CREATE MODULE command.

VDE„ CREATE MODULE/FROM_DIRECTORY=DEV$:[NEWFAC]