Before a user can use the new VDE library you are creating, that user must be added to the library's VDE database. This means that VDE must create an entry for the user in the database User Table. This entry records the user's OpenVMS username, full name (first and last names), default and authorized privileges, and other information. A user who has not been added to the database cannot use VDE to access information in that database or to perform VDE operations on the VDE library.

The CREATE LIBRARY command automatically adds the creator of a new VDE library to the library's database. Additional users must be added in one or two ways. First, they can be added manually using the CREATE USER command. This command allows you to specify the attributes of each new user explicitly. This way of adding users is most practical for VDE libraries with a small number of users, especially if you want careful control over who accesses the library.

Second, you can set a library attribute that allows new users to be added automatically the first time they access the VDE library. This way of adding users is more practical for VDE libraries with a large number of potential users. To enable automatic addition of new users, you must use the /AUTO_ADD_USER qualifier to the CREATE LIBRARY or MODIFY LIBRARY command. If this qualifier is used without a parameter, any user who attempts to access the VDE library through VDE is automatically added to the VDE database with the standard default and authorized VDE privileges for that library.

The qualifier can also be specified with a rights identifier parameter, as in /AUTO_ADD_USER=rights-id. In this case, VDE will only add those users to the database who hold the OpenVMS rights identifier given by the parameter. This way of adding users is useful when you already use a OpenVMS rights identifier to protect the files and directories of your VDE library. In this case, the OpenVMS security mechanism for the library also serves as the mechanism that restricts access to the VDE library through the VDE utility.

Section 6.4 gives a more complete description of how you can add users to your VDE library.

If you do not specify the /AUTO_ADD_USER qualifier, you must add users with explicit CREATE USER commands. However, you can change the library attribute that controls automatic addition of users at any time by using the /AUTO_ADD_USER or /NOAUTO_ADD_USER qualifier with the MODIFY LIBRARY command.

The owner information specified in the OpenVMS SYSUAF database will be used as the owner of any new VDE username created. VDE will ignore any leading numerics, leading hyphens, leading space characters, and leading tilde characters, listed in the SYSUAF owner field.

6.2.4 Conversion of Library Format

VDE maintains data about your VDE library in a relational database. As new capabilities are added to VDE, the format of this database may change from one version of VDE to the next. A new feature may, for example, require the addition of new database tables or of new columns to existing tables in order to store the data required to implement the feature. New features may also require other changes to your VDE library, such as the addition of a subdirectory or a new file. To accommodate such changes to the library format, each new version of VDE that requires a format change contains code that converts your existing VDE library to the new format. VDE also maintains a database format version number in your database so that it always knows the current format of your library and its database.

When a new version of VDE is installed on your system, that version may require that your existing VDE library be convered to a new format. If so, there are two ways to effect this conversion. One is to allow VDE to automatically convert the library format the first time any user accesses the library through VDE. The second way is to explicitly convert the library using the CONVERT LIBRARY command.

By default, VDE will not convert your VDE library automatically the first time any user starts a new VDE session that attaches to that library ¹ Automatic conversion is useful for small libraries, for libraries that are accessed only by the local copy of VDE, and for libraries that are easily restored from backup. In order to avoid unexpected conversions and the resulting potential for library access outages, automatic conversion is, by default, disabled when the library is created.

If you specify the /AUTO_CONVERT qualifier with the CREATE LIBRARY or MODIFY LIBRARY command, VDE will automatically convert your library when new versions of VDE are installed on your system. If automatic conversion is disabled, a user must enter an explicit CONVERT LIBRARY command to convert the library. To use this command, you must have the VDE privilege MODLIB. This approach gives you more control over when conversions occur so that your VDE library cannot be accidentally converted to the format for a new version of VDE that you do not yet want to use.

Furthermore, when the library format changes, you should in general delete all processes connected to the VDE library before converting the library so that all user processes use the new version of VDE after the conversion. This is especially important if most users use kept VDE subprocesses to access the library. To delete such processes, use the RMU/CLOSE command with the /ABORT=DELPRC qualifier. For example:

$ RMU/CLOSE/CLUSTER/ABORT=DELPRC DEV$:[ROOTDIR]VDE$DATABASE

After entering this command, use the VDE CONVERT LIBRARY command. This procedure ensures that all users of your library will access it with the new version of VDE and that your library has the format that this version requires.

To use the RMU/CLOSE command, you must have the OpenVMS privilege SYSPRV.

You can modify the library attribute that controls automatic library conversion using the /AUTO_CONVERT or /NOAUTO_CONVERT qualifier with the MODIFY LIBRARY command.

6.2.5 Sending Mail Notifications

The /AUTO_MAIL qualifier specifies that VDE should send a mail notification message to the user who has queued a replacement when that replacement is later performed (see Queued Replacements). The /NOAUTO_MAIL qualifier suppresses such notification messages. These qualifiers thus control the volume of mail messages VDE sends. If you specify neither qualifier, /AUTO_MAIL is assumed by default.

The /NOSEND_MAIL qualifier suppresses all VDE mail notification messages for the library. This qualifier is useful if you are setting up a VDE library for testing purposes or simply to play with. For a production VDE library you should always enable mail notifications, which can you do by specifying the /SEND_MAIL qualifier or by simply omitting the /NOSEND_MAIL qualifier.

6.2.6 Allowing Deletion of Library Entities

VDE allows you to delete library entities such as modules, facilities, and streams with various DELETE commands. To use such commands, you must in general have the corresponding delete privileges. These delete privileges protect against deletion of library entities by unauthorized users. They also require authorized users to set those privileges before deleting entities, thus providing some protection against accidental deletion.

As an additional protection against accidental deletion of library entities, VDE allows you to specify that certain entities, such as specific modules, facilities, and streams, are not allowed to be deleted even when the user has the corresponding delete privilege. A given stream, for example, can have its delete attribute set to no-delete using the /NODELETE qualifier to the MODIFY STREAM command. VDE will then not allow the DELETE STREAM command to delete that stream. The stream can still be deleted, but only if the attribute is first changed with another MODIFY STREAM command to allow the stream to be deleted. The no-delete attribute thus prevents accidental deletion of the stream by requiring an extra command to explicitly allow deletion before the DELETE STREAM command can be used. The delete-stream privilege is required as well.

When you create your VDE library, you can specify the default setting of the deletion attribute for new database entities. The /ALLOW_DELETE qualifier to CREATE LIBRARY specifies that new database entities should be allowed to be deleted by default. The /NOALLOW_DELETE qualifier specifies that database entities should not be allowed to be deleted by default. If you specify neither qualifier, VDE by default marks new database entities as being allowed to be deleted. You can of course always override this default by explicity specifying the delete attribute when creating new entities. In general, allowing deletion is more convenient for the library maintainer. Not allowing deletion is more appropriate when numerous individuals have access to the library and some of them may be accident-prone when entering commands.

6.2.7 CMS History and Notes Defaults

Two sets of qualifiers to the CREATE LIBRARY command controls VDE's treatment of CMS history and notes information in the VDE library. The /NOCMS_ELEM_HIST qualifier causes VDE to create CMS elements (that is, delta files) with no default history and notes strings. This prevents CMS from producing files with history or notes information when modules are fetched with the CMS FETCH command. This library attribute has no effect on modules fetched with the VDE FETCH command, so it is only relevant if DCL command procedures access the CMS elements in the VDE library using CMS directly.

The /NOHISTORY_NOTES qualifier causes the VDE RESERVE command to never produce CMS history or notes information in its output files and to not accept the /HISTORY, /NOTES, and /POSITION qualifiers. Disabling history and notes information in reserved files makes certain mistakes less likely where such information gets replaced into the VDE library as part of the module text.

Both of these qualifiers prevent certain problems where history or notes information gets included in output files where this information must not be present. Such problems only occur in special circumstances and do not affect most VDE libraries. As a result, these qualifiers are optional and the default settings are given by the positive forms of those qualifiers, /CMS_ELEM_HIST and /HISTORY_NOTES.

6.2.8 Configuring Architectures

This section is under construction...

After the creation of the various architectures using one or more CREATE ARCHITECTURE commands, one normally enables the display of differnt architectures with the MODIFY LIBRARY/SHOW_ARCHITECTURE command.

See Chapter 9 for further information.

6.2.9 Miscellaneous Attributes

Other qualifiers to the CREATE LIBRARY command allow you to set various miscellaneous library attributes. The /ASK_INFO_FILE qualifier determines whether the REPLACE command will by default ask the user whether to edit a replacement information file (see Section 2.7). The /SHOW_GEN_EXPR qualifier determines whether the RESERVE command displays the expected generation expression of the new module generation to be created when the module is later replaced. These and other qualifiers are described in more detail in the description of the CREATE LIBRARY command. Whether they are applicable to you depends on the development process you think is appropriate for your project.

If you have no strong feelings on these options, use the defaults. If you later change your mind, you can always change these setting with the MODIFY LIBRARY command.

6.3 Library Directory Structure

In addition to its root directory and database, your VDE library contains a number of additional disk directories and subdirectories. These additional directories contain the source modules for your software system, all associated derived modules (such as object modules and executable images), and various command files and log files that VDE uses to perform its functions. This section describes the structure and functions of these disk directories.

6.3.1 Delta File Directories

VDE always stores all source modules that are part of your software system in "delta files." A delta file stores all generations of a source module in a condensed form. The delta file stores every line that has ever been part of the source module, along with information specifying which lines belong to which generations of the module. Because a line that is the same from one generation to the next is only stored once in the delta file, the file saves space by essentially only storing differences between generations. (Such files are called "delta files" because the Greek letter delta is often used to denote differences between quantities in mathematical notation.)

VDE uses callable CMS (VAX/VMS Code Management System) to manage its delta files. VDE sets up one CMS library for each facility in your software system. VDE also creates one CMS element (which is a delta file) for each source module in your software system.

By default, VDE creates a delta-file root directory called VDE$CMS.DIR within the library root directory when you create the library. Each time you create a new facility, VDE creates a subdirectory for that facility within the delta-file root directory. The CMS library for the facility is created in the facility's subdirectory. CMS uses additional subdirectories within the CMS library to store the actual delta files (CMS elements), but VDE does not keep track of the internal organization of the CMS library. Table 6-1 illustrates the disk directories that VDE establishes for delta files.

Table 6-1 Delta File Disk Directories

Library root directory:	DEV$:[ROOTDIR]
Delta-file root directory:	DEV$:[ROOTDIR.VDE$CMS]
Directory for facility FOO:	DEV$:[ROOTDIR.VDE$CMS.FOO]
Directory for facility BAR:	DEV$:[ROOTDIR.VDE$CMS.BAR]

VDE records the directory specification for the delta-file root directory and each facility's delta-file directory in its database. The SHOW LOCATION /DELTA_FILE command displays this information on your terminal.

Although VDE uses the default locations just described, you can specify different locations for the delta-file directories. To specify a different delta-file root directory (VDE$CMS by default), you must take the following actions:

• Specify the /DEFER qualifier with the CREATE LIBRARY command. This qualifier prevents VDE from initializing the delta-file directory tree using its default rules.
• Enter the SET DIRECTORY command with the /DELTA_FILE qualifier to specify the desired delta-file root directory. For example, to specify that the delta-file root directory should be DEV$:[DELTAROOT], use the following command:

  VDE„ SET DIRECTORY /DELTA_FILES DEV$:[DELTAROOT]

  This command causes VDE to use directory DEV$:[DELTAROOT] as the delta-file root directory instead of DEV$:[ROOTDIR.VDE$CMS].

• Enter the SET DIRECTORY command with the /DELTA_FILE and /FACILITY qualifiers to specify the desired delta-file directory for a specific facility. For example, to specify that the delta-file directory for facility FOO should be DSK2:[PQR.STU], use the following command:

  VDE„ SET DIRECTORY /DELTA_FILES /FACILITY=FOO DSK2:[PQR.STU]

  Note that you can use this command to place the delta-file directory for a given facility on a different disk than the rest of the VDE library.

• After having entered all desired SET DIRECTORY commands, enter the following command to actually create the specified delta-file root directory and the rest of the delta-file directory tree:

  VDE„ CREATE DIRECTORY_TREE /DELTA_FILES

  This command creates the CMS library for each facility in addition to creating the actual directories.
  To create the delta-file directory and CMS library for a specific facility FOO, use the following command:

  VDE„ CREATE DIRECTORY_TREE /DELTA_FILES /FACILITY=FOO

Note that the SET DIRECTORY command specifies where a directory should be located, but does not actually create the directory. In effect, it creates a template for some part of the VDE directory tree. To actually create directories from that template, you must enter the CREATE DIRECTORY_TREE command. This arrangement allows you to specify templates for many parts of the directory tree before you actually use the templates to create directories.

6.3.2 Staging Area Directories

When you use VDE for source control, you can replace modules in two ways. One is to replace modules immediately, in which case the modules being replaced are inserted into the VDE library right away. The other way is to queue modules for replacement, in which case the modules are not inserted into the library until an authorized user "performs" the queued replacement. Queued replacements are useful because they give project managers more control over the timing of replacements and they allow the replaced modules to be reviewed before being inserted into the library.

When a user queues modules for replacement, VDE copies the files being replaced into the library's staging area. The staging area is a disk directory tree that temporarily holds files being replaced until the corresponding replacements are performed by an authorized user. The staging area starts with the staging area root directory. By default, this root directory is subdirectory VDE$STAGE within the library root directory.

Within the staging area root directory, VDE creates two more levels of subdirectories. The staging area root directory contains subdirectories with names of the form VDE$STG_n. Each such directory holds a group of 100 replacements. Directory VDE$STG_12, for example, contains replacements with Replacement Id values in the range 1200 to 1299. Within each such directory, VDE creates second-level directories that each hold the files for a single replacement. Within VDE$STG_12, for example, there are subdirectories with names such as VDE$REP_1261, representing replacement 1261. Table 6-2 illustrates this structure.

Within the replacement subdirectory, VDE creates one subdirectory for each facility involved in the replacement. VDE stores the individual files being replaced in those facility subdirectories. Comment and information files for the replacement are stored in the replacement subdirectory. This is also shown in Table 6-2.

Table 6-2 Staging Area Disk Directories

Library root directory:
	DEV$:[ROOTDIR]
Staging area root directory:
	DEV$:[ROOTDIR.VDE$STAGE]
Directory for 100 replacements:
	DEV$:[ROOTDIR.VDE$STAGE.VDE$STG_12]
Directory for one replacement:
	DEV$:[ROOTDIR.VDE$STAGE.VDE$STG_12.VDE$REP_1261]
Comment file for replacement ID 1261:
	DEV$:[ROOTDIR.VDE$STAGE.VDE$STG_12.VDE$REP_1261]DOE.VDE$COMMENT
Directory for facility FACNAM:
	DEV$:[ROOTDIR.VDE$STAGE.VDE$STG_12.VDE$REP_1261.FACNAM]
File for module being replaced:
	DEV$:[ROOTDIR.VDE$STAGE.VDE$STG_12.VDE$REP_1261.FACNAM]MOD.TYP

As mentioned above, VDE's default location for the staging area root directory is subdirectory VDE$STAGE within the library root directory. To change this default, you must take the following actions:

• Specify the /DEFER qualifier with the CREATE LIBRARY command. This qualifier prevents VDE from initializing the staging area root directory using its default rules.
• Enter the SET DIRECTORY command with the /STAGING qualifier to specify the desired staging area directory. For example, to specify that the staging area directory should be DEV2$:[PROJ.STAGE], use the following command:

  VDE„ SET DIRECTORY /STAGING DEV2$:[PROJ.STAGE]

  This command causes VDE to use directory DEV2$:[PROJ.STAGE] as the staging area root directory instead of DEV$:[ROOTDIR.VDE$STAGE]. It is preferable that the staging area be on a different disk than the rest of the library.

• Enter the following command to actually create the specified staging area root directory:

  VDE„ CREATE DIRECTORY_TREE /STAGING

The SET DIRECTORY and CREATE DIRECTORY_TREE commands can be used at any time after library creation to redirect the staging area to a different disk location.

After a given replacement has been performed, VDE no longer needs the corresponding staging area. VDE does not itself delete those files, but you should do so periodically to reclaim the disk space. Staging area files can be useful for some time, however, because they contain copies of the files inserted into the VDE library. They can thus be used to recover lost information if your delta files (CMS libraries) are lost or damaged. In case of such loss, you have to restore the CMS libraries from backups. That should make them close to being consistent with the information in the VDE database. After that, you can use the VDE VERIFY GENERATION command with the /RECOVER qualifier to restore the CMS libraries to the state given by the VDE database. This recovery operation requires access to the old staging area directories---to retrieve copies of any lost module generations for insertion into the CMS libraries. For this reason, you should always have the staging areas on a different disk than the delta files or the VDE database and you should keep the staging areas for old replacements around for some time after the replacements are performed.

For information on typical staging area maintenance operations, see Section 7.5.