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

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

7Within 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 Gsubdirectory is meant to hold source files in clear-copy form. The OBJ Ddirectory is meant to hold object files, executable images, and all Hother derived modules that can be produced when your software system is =built. The VDE$COM subdirectory will hold command files that 3VDE creates to perform build steps and the VDE$LOG Hsubdirectory will hold the corresponding log files. The contents of the >VDE$COM and VDE$LOG subdirectories are thus under VDE control Awhile 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.

g                                     

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 Dthe facility root directory and you can explicitly specify your own Flocations for the stream and facility root directories. This topic is -covered in more detail later in this section.

WSuppressing Stream Directories


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

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

   

  " VDEä SET STREAM MAIN!VDEä SET DIRECTORY /STREAM /DEFER 

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

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

\Defining Your Own Stream Directories


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

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

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

   

  " 4VDEä CREATE STREAM BIRCH /DIRECTORY=DEV2$:[MY_BIRCH] 

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

   

  " VDEä SET STREAM BIRCH"VDEä SET DIRECTORY /STREAM /PROMPT 

  GThese commands specify that a stream root directory must be explicitly Hspecified for each future descendant of the existing stream BIRCH. When @each such descendant is created with the CREATE STREAM command, 5VDE prompts the user for the name of the stream root Fdirectory unless the user specifies it with the /DIRECTORY qualifier. DThis feature is useful when you want each future stream's directory Btree to go on a separate device to be selected when the stream is Ecreated.
  Note that the SET DIRECTORY /STREAM command acts on the Gcurrent default stream. For it to act on a given stream, you must thus Fset that stream using the SET STREAM command, as shown in the example.C

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

   

  " VDEä SET STREAM BIRCH(VDEä SET DIRECTORY /STREAM DEV2$:[MYDIR]"VDEä CREATE DIRECTORY_TREE /STREAMVDEä CANCEL DIRECTORY /STREAM 

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

• 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 BIRCH9VDEä SET DIRECTORY /STREAM /FACILITY=FOO DEV2$:[BIRCHFOO]1VDEä CREATE DIRECTORY_TREE /STREAM/ /FACILITY=FOO+VDEä CANCEL DIRECTORY /STREAM /FACILITY=FOO 

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

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

   

  " VDEä SET STREAM BIRCH6VDEä SET DIRECTORY /STREAM /SUBDIRECTORY=ANASYM [.ANA] 

  HThis SET DIRECTORY command specifies that each facility in stream BIRCH Gand its descendant streams should have a subdirectory ANA. The form of Dthe directory specification [.ANA] indicates that it is relative to Deach facility's root directory. The ANASYM parameter is a directory ;symbol which is used later in VDE scripts to reference the Cnew 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: CSCR, OBJ, VDE$COM, and VDE$LOG. The /SUBDIRECTORY qualifier to SET CDIRECTORY allows you to specify additional such subdirectories. As Balways, the SET DIRECTORY command only creates a template for the Edesired directory tree; the actual directories are not created until Eyou use the CREATE DIRECTORY_TREE command or create new streams that 'inherit the template from their parent.

HThese 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 Gthese capabilities. You can control how the various subdirectories for 9each facility are used by the way that you write the VDE Hscripts that determine how build steps and certain other operations are performed.c

6.4 Adding Users to the Library

GBefore 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. 9When a user is added to the database, VDE creates a User =Table entry for the user in the VDE database. When that user 9subsequently tries to access the VDE library through the 2VDE utility, VDE checks that the user is recorded >in the database. Provided this is the case, VDE retrieves the 9user's VDE privileges and other attributes from the User ATable entry and uses those attributes to control the rest of the 1VDE 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:

8
• VDE automatically adds the library creator to the G database when the library is created. This user is authorized to set ? all VDE privileges and has all administrative privileges set by default.J
• You can use the CREATE USER command to add users. This command lets I 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 F automatically add new users to the library database when they first = access the library through the VDE utility. Each such user F 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 Hauthorized privileges, and certain other information about each user to Fbe added to the database. This is an example of a CREATE USER command *that adds user Jane Smith to the database:

 

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

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

HUsing 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 Fif you want to exercise careful control over who accesses the library.L

6.4.2 Automatic Addition of Users

GIf 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 Doperating system. The full name of the user is taken from the owner Hfield of the user's record in the system User Authorization File (UAF). 9Other attributes, such as the remark string, are not set.

BThe /AUTO_ADD_USER qualifier can also be specified with a OpenVMS Frights identifier parameter, as in /AUTO_ADD_USER=rights-id. <In this case, VDE stores the given rights identifier in the 9database. Subsequently, VDE adds only those users to the Ddatabase who hold the stored rights identifier. The users are added <when they first access the library through VDE, just as for Gthe plain /AUTO_ADD_USER qualifier. This way of adding users is useful Bwhen 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 Euse the rights identifier as your mechanism to control access to the library.

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

1To 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 Eauthorization database, or read and write access when the /WRITE_UAF =qualifier is specified. Installation of the VDE/READ_UAF Himage 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 Dyou automatically add users, you can of course still use the CREATE FUSER 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 Hautomatically or who should be added with a different set of privileges Cthan the standard privileges for the library. In addition, you can Halways use the MODIFY LIBRARY command to change the privileges or other 8attributes of any user already recorded in the database.

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

6.5 Creating Streams

&Section under construction...

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

 

" #VDEä CREATE STREAM V2.0/PARENT=V1.0 

FIn addition to choosing the parent stream, you need to choose whether Bor not the new stream is a direct descendent of the parent stream C(/MAINLINE), or if it is a variant and will diverge (/NOMAINLINE). F(Mainline streams will keep the same generation identification values >as the parent, while variant streams select longer generation Didentification values. The main line of descent is often an integer Hgeneration number, while variants tend to include increasing numbers of Eletters 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 A/CONFERENCE, /[NO]INIT_CMS_CLASS, /NOTIFY, /[NO]GENERATIONS, and /REVIEW.

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

6.5.1 Stream Directory Tree

&Section under construction...

4Streams typically have an associated directory tree.T

6.5.2 Scripts to Populate New Streams

&Section under construction...

HTo cancel a module reservation without replacing the module, use the ...Q

6.5.3 Stream Successor Relationships

&Section under construction...

DTo cancel a module reservation without replacing the module, use theZ

6.6 Creating Facilities

&Section under construction...

ETo 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" 

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

6.7 Populating a Facility with Modules

&Section under construction...

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

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

6.7.1 Getting Source Modules from a Directory

DOne can use the CREATE MODULE/FROM_DIRECTORY command for this task. CThis command will create one module in the facility for every file Hfound 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]