@This chapter contains preliminary information; sections are Acurrently under construction... And other sections are currently undergoing demolition...

:This chapter describes how to set up a new VDE library by Dcreating its database, setting up its disk directory structure, and Fpopulating it with users, development streams, facilities, and source <modules. These commands must be performed before VDE can be ?used to manage the source code or or build the software system.

?Commands and operations described in this section are normally Hperformed only by the maintainers of the source code control libraries, =by the database maintainance staff, or by the maintainers of >VDE. These commands are also used by those users that wish to %maintain private libraries using VDE.

BInformation pertaining to the tailoring and to the performance of mVDE database backup operations is included in Section 7.4. HOnce you have created the library, you should establish the appropriate Cbackup procedures, and determine the appropriate backup scheduling.



5A VDE library consists of various components: a root :directory, a VDE database, and a disk directory tree. The Hroot directory is the disk directory that contains the <VDE database and that normally serves as the root directory 7for the remaining disk directories in the library. The 8VDE database is a Oracle Rdb7 database 7which stores all information that VDE needs about your 9software system. Rdb is a relational database management 2system, and VDE reads and writes the VDE database ?using SQL, and industry-standard query language for relational Edatabases. The library's directory tree consists of Fall disk directories that hold the CMS libraries, source files, build Foutput files, and other files that comprise your software system. The =VDE database records the locations of all directories in the directory tree.

8To create a VDE library, you must first create the root 4directory and the VDE database. Thereafter, VDE can Acreate the rest of the directory tree for you, depending on what Ffacilities and development streams you need for your software system. 8VDE can create the directory tree using its own default Frules, but you can also explicitly specify how you want the directory tree created.



9VDE includes a utility, VDE$UPLOAD, that can perform the >entire creation of a VDE database, based on the specification 4of a directory containing one or more CMS libraries.

HThe contents of all of the CMS libraries under the target directory are :uploaded into VDE, including converting the specified CMS classes into VDE streams.

<For information on VDE$UPLOAD, see the VDE Reference Manual.

7As an alternative to the VDE$UPLOAD procedure, the VDE Gdatabase can be created via a series of manual commands. An example is Gincluded in the kit, the VDE$CREATE procedure. For further information Mon this, see Section 6.7.3.M

6.1.2 The CREATE LIBRARY Command

;To create the root directory and the VDE database, use the DCREATE LIBRARY command. This command creates the root directory you 8specify, creates and initializes a VDE database in that Hdirectory, and sets up an initial facility and an initial stream in the >library. In short, it creates the minimal usable VDE library. 5The following example illustrates the command syntax:

 

" FVDEä CREATE LIBRARY DEV$:[ROOTDIR] /NAME=LIBNAME /CREATOR="John Doe" -K_VDEä /REMARK="Library for gadget development" 

7This example creates a VDE library with root directory 7DEV$:[ROOTDIR]. After creating the root directory, VDE 9creates the library's VDE database in that directory and Brecords a library name, the library creator, a remark string, and Gcertain other attributes in the database. (The library name is LIBNAME Hand the library creator is John Doe in this example.) You should expect Flibrary creation to take at least two to ten minutes of elapsed time, Gdepending on your system configuration and load. The bulk of this time 6is required to create and initialize the Rdb database.

HIt is strongly recommended that you use a system-wide concealed logical <name for the disk name so that you can move the VDE library Eto another disk at a later time by simply moving the library's files 9and directories and redefining the logical name. The VDE Gdatabase records the device names and full directory specifications of Anumerous subdirectories within the root directory. This makes it ;difficult to move the VDE library to another disk unless a Bconcealed logical name is used to denote the disk. It should be a =system-wide name so it is accessible to all users of the VDE Blibrary. A group-wide concealed logical name is acceptable if all =users, present and future, will belong to the same UIC group.

FThe CREATE LIBRARY command establishes a default facility called CODE @in your library. For a simple software system, you can use this Cfacility for your source code and then set up other facilities for Gtools, specifications, and documentation as needed. For a more complex Csoftware system, you can delete the CODE facility and create other Hfacilities that better suit your needs. In addition, the CREATE LIBRARY Fcommand creates a default development stream called MAIN. You can use Bthis stream for your main development thread unless your software Dsystem requires a more complex stream structure. Stream MAIN is the @ancestor of all other streams you create as the library evolves.

GWhen you enter the CREATE LIBRARY command, you are required to specify Fthe desired library root directory, the library name, the name of the Flibrary creator (your own first and last names), and a remark string. CThe root directory name is the command parameter while the library Ename, creator name, and remark string are specified with qualifiers. 5VDE stores the library name and remark string in the 8"database header record" in the Rdb database. ;Because you are the library creator, VDE records your full Aname (as specified with the /CREATOR qualifier) and your OpenVMS @user name in a User Table entry in the database. A field in the Hdatabase header record points to your User Table entry to indicate that you created the library.

>If you omit any required item, VDE prompts you for its value. 6The following example illustrates how VDE prompts for .information if all required items are omitted:

 

" VDEä CREATE LIBRARYAEnter directory specification for the new library: DEV$:[ROOTDIR]4Enter the name you want for the new library: LIBNAME5Enter your full name (first and last names): John Doe@Enter the remark for new library: Library for gadget development 

FThis example creates exactly the same library as the previous example.

EBy default, the CREATE LIBRARY command creates the initial directory =tree for your library. VDE creates a delta-file root >directory called VDE$CMS.DIR within the library root Gdirectory. The delta-file root directory will contain one subdirectory Efor each facility in your software system to hold the facility's CMS >library. Each CMS library will hold CMS elements, also called C"delta files," to contain all generations of each source =module in a condensed form. VDE accesses these CMS libraries using callable CMS.

;VDE creates one stream root directory and Fassociated directory tree for each development stream in your system. GBecause the CREATE LIBRARY command always creates stream MAIN, it also Acreates the root directory and directory tree for that stream by Cdefault. The stream MAIN root directory is named MAIN.DIR and is a +subdirectory of the library root directory.

AThe CREATE LIBRARY command also creates the staging area Fdirectories for the library. The top-level of this directory Htree is called VDE$STAGE.DIR, and is a subdirectory of the library root 7directory. VDE uses subdirectories of the staging area Ddirectories to store, or "stage," source files for queued zreplacements. Queued Replacements describes queued replacements and how they use staging area directories.

DBy default, the CREATE LIBRARY command creates the directories just Cdescribed for the new library. It also creates the CMS library for Gfacility CODE. However, you can defer directory creation by specifying Dthe /DEFER qualifier with the CREATE LIBRARY command. /DEFER causes >VDE to not create any directories other than the library root Gdirectory and to not create the CMS library for facility CODE. You can Cthen use the SET DIRECTORY command to specify where you want these tdeferred directories to be created (see Section 6.3). After entering =all desired SET DIRECTORY commands, you can enter the CREATE ADIRECTORY_TREE command to actually create the directory tree (or Evarious components thereof) for your library. Using this method, you @can specify that some directories be placed on other disks, for >example, or that each facility get additional subdirectories. cSection 6.3 describes how to use these capabilities.

DThe CREATE LIBRARY command also specifies a number of other library @attributes. These attributes include the default and authorized ;VDE privileges that new users are assigned, information on Dhow new users are added to the library, whether the RESERVE command Fdisplays the expected CMS generation expression for the corresponding Greplacement, whether the REPLACE command requests information files by tdefault, and various other attributes. Section 6.2 gives more detail Eon these attributes. If you do not specify these optional attributes 6with the CREATE LIBRARY command, VDE provides default Asettings. You can modify all such settings later with the MODIFY GLIBRARY command. You can also use the MODIFY LIBRARY command to change Bthe library name and remark string. The only attribute you cannot 9change with MODIFY LIBRARY is the library root directory.?

6.1.3 Examples

>This is an example of a CREATE LIBRARY command and its output:

 

" FVDEä CREATE LIBRARY DEV$:[ROOTDIR] /NAME=LIBNAME /CREATOR="John Doe" -;_VDEä /REMARK="Library remark">Library LIBNAME to be created in root directory DEV$:[ROOTDIR]8 Library root directory DEV$:[ROOTDIR] already exists.: Logical name VDE$LIBRARY now points to the new library., Creating library database; please wait...% Library database has been created. EStaging area root directory DEV$:[ROOTDIR.VDE$STAGE] has been created (Creating directory tree for delta files:9 Root directory DEV$:[ROOTDIR.VDE$CMS] has been createdD Facility CODE root directory DEV$:[ROOTDIR.VDE$CMS.CODE] has been created4 CMS library for facility CODE has been created, All directories for delta files now exist (Creating directory tree for stream MAIN:6 Root directory DEV$:[ROOTDIR.MAIN] has been created? Subdirectory DEV$:[ROOTDIR.MAIN.VDE$BLD] has been createdA Facility CODE root directory DEV$:[ROOTDIR.MAIN.CODE] has been created@ Subdirectory DEV$:[ROOTDIR.MAIN.CODE.OBJ] has been created@ Subdirectory DEV$:[ROOTDIR.MAIN.CODE.SRC] has been createdD Subdirectory DEV$:[ROOTDIR.MAIN.CODE.VDE$COM] has been createdD Subdirectory DEV$:[ROOTDIR.MAIN.CODE.VDE$LOG] has been created, All directories for stream MAIN now exist Library creation completed. VDEä 

=In this example, VDE creates a new library in root directory HDEV$:[ROOTDIR]. The library has name LIBNAME and the library creator is 2named John Doe. The VDE output shows that VDE has Fcreated the library root directory (which turned out to already exist 1in this case), the VDE database, the VDE staging Barea directories, the delta-file directory tree including the CMS Glibrary for facility CODE, and the directory tree for stream MAIN. The ;new VDE library thus has the initial facility CODE and the Ginitial stream MAIN fully set up. There are no modules in the library, Fhowever, and only one allowed user (the creator John Doe) is recorded in the library database.

EIn the following example, the library is created the same way except Hthat the library creator (Jane Smith) specifies the /DEFER qualifier to Edefer the creation of the library directory tree and the CMS library Gfor facility CODE. In addition, all required parameters and qualifiers <are omitted from the command line. As a result, VDE prompts for all required information:

 

" VDEä CREATE LIBRARY /DEFERAEnter directory specification for the new library: DEV$:[ROOTDIR]4Enter the name you want for the new library: LIBNAME7Enter your full name (first and last names): Jane Smith7Enter the remark for new library: Library remark string>Library LIBNAME to be created in root directory DEV$:[ROOTDIR]: Library root directory DEV$:[ROOTDIR] has been created.: Logical name VDE$LIBRARY now points to the new library., Creating library database; please wait...% Library database has been created. Library creation completed. VDEä 

<As the output shows, VDE creates the library root directory Hand the library database, but does not create the rest of the directory @tree. The user thus has the opportunity to modify the directory Estructure and its exact locations with SET DIRECTORY commands before Busing CREATE DIRECTORY_TREE commands to create the directory tree.

>The following example shows the VDE library creation, as well .as a number of other ancillary steps involved.

 

" $! G$! Locate and delete previous incarnations of the test facility files, 8$! then unpack the saveset containing the test files... $! P$ if f$search("sys$scratch:A.REQ") .nes. "" Then Delete sys$scratch:A.REQ;*/log P$ if f$search("sys$scratch:B.REQ") .nes. "" Then Delete sys$scratch:B.REQ;*/log P$ if f$search("sys$scratch:C.B32") .nes. "" Then Delete sys$scratch:C.B32;*/log P$ if f$search("sys$scratch:D.B32") .nes. "" Then Delete sys$scratch:D.B32;*/log P$ if f$search("sys$scratch:E.B32") .nes. "" Then Delete sys$scratch:E.B32;*/log P$ if f$search("sys$scratch:F.B32") .nes. "" Then Delete sys$scratch:F.B32;*/log $! *$ Backup VDE$CREATE.BCK/SAVE Sys$Scratch: $! 8$! Create the core directory -- this must be present... $! 4$ Create/Directory STAR$DATA:[QTV.WWW.VDE$DATABASE] $ VDE ! >! create the WWW library in STAR$DATA:[QTV.WWW...], using the >! mnemonic WWW, placing all Rdb-related library components in $! STAR$DATA:[QTV.WWW.VDE$DATABASE]. ! 9create librar STAR$DATA:[QTV.WWW.VDE$DATABASE] /DEFER - /NAME=WWW - $ /REMARK="QTV WWW Source Library" - 8 /NOAUTO_CONVERT /AUTO_ADD_USER=VMS_SOURCE /AUTO_MAIL - = /ASK_INFO_FILE /ASK_REPL_CAUSE /SHOW_GEN_EXPR /NOSTATISTI - 4 /NOHISTORY_NOTES /NOALLOW_DELETE /NOWILD_INS_GEN - / /NOCMS_ELEM_HIST /CREATOR="Stephen Hoffman" - * /DEF_PRIVILEGES=(CREMOD,RESREP,CREFAC) - + /AUTH_PRIVILEGES=(CREMOD,RESREP,CREFAC) - * /data=STAR$DATA:[QTV.WWW.VDE$DATABASE] - + /journ=STAR$DATA:[QTV.WWW.VDE$DATABASE] - ( /snap=STAR$DATA:[QTV.WWW.VDE$DATABASE] ! SHOW DEFAULTS SHOW LIBRARY/FULL 2MODIFY CONTEXT/PUBLIC DEFAULT/NOSTREAM/NOFACILITY ! ?CREATE USER SYSTEM /NAME="System Manager"/DEF_P=ALL/AUTH_P=ALL System Manager ! 8! Create the CMS ("delta") library directory structure. >! Configure the CMS libraries to use the directory structure: 5! STAR$DATA:[QTV.WWW.CMS$DATABASE.'facility'.CMS]. ?! Configure the "marker" files to use the directory structure: 7! STAR$DATA:[QTV.WWW.CMS$DATABASE.'facility'.SRC]... ! ;SET DIRECTORY/DELTA_FILES STAR$DATA:[QTV.WWW.CMS$DATABASE] 6SET DIRECTORY/DELTA_FILES/SUBDIRECTORY=VDE$CMS [.CMS] 9SET DIRECTORY/DELTA_FILES/SUBDIRECTORY=VDE$MARKER [.SRC] "CREATE DIRECTORY_TREE/DELTA_FILES SHOW DIRECTORY/DELTA_FILES ! ! Create the staging area... ! 6SET DIRECTORY/STAGING STAR$DATA:[QTV.WWW.VDE$STAGING] CREATE DIRECTORY_TREE/STAGING ! &! Create the stream/build directories ! 5SET DIRECTORY/STAGING STAR$DATA:[QTV.WWW.VDE$STREAM] CREATE DIRECTORY_TREE/STREAM ! )! create and load the VDE test facility. ! CREATE FACILITY AAA_VDE_TEST - / /REMARK="Test facility for VDE developers" SET FACILITY AAA_VDE_TEST" 7CREATE MODULE/NODELETE/REMARK="VDE self-test module" -  A.REQ /INPUT=SYS$SCRATCH: 7CREATE MODULE/NODELETE/REMARK="VDE self-test module" -  B.REQ /INPUT=SYS$SCRATCH: 7CREATE MODULE/NODELETE/REMARK="VDE self-test module" -  C.B32 /INPUT=SYS$SCRATCH: 7CREATE MODULE/NODELETE/REMARK="VDE self-test module" -  D.B32 /INPUT=SYS$SCRATCH: 7CREATE MODULE/NODELETE/REMARK="VDE self-test module" -  E.B32 /INPUT=SYS$SCRATCH: 7CREATE MODULE/NODELETE/REMARK="VDE self-test module" -  F.B32 /INPUT=SYS$SCRATCH: ! EXIT $ $ Exit  

k

6.2 Optional Library Attributes and Settings

EThere are a number of library attributes that you can optionally set Cwith the CREATE LIBRARY command. These attributes all have default Gvalues (which is why their specification is optional) and most of them Fcan be altered later with the MODIFY LIBRARY command. However, before Hyou specify the CREATE LIBRARY command, you should consider whether you &need to set these optional attributes.



8One attribute you must consider before creating the VDE 2library is the placement of the VDE database. The >VDE database consists of three files: a database root file, a Hstorage area file, and a snapshot file file. (These three files use the 6file extention types RDB, RDA, and SNP, respectively.)

=The database root file (VDE$DATABASE.RDB) must reside in the =VDE library root directory; the library root directory is by Ddefinition the directory that contains the database root file. This >file is small, however; it only contains information that Rdb needs to manage the database.

FThe database storage area file (VDE$DATABASE.RDA) contains the actual >data that VDE keeps about your software system. This file can Gbe quite large, its actual size depending on the size of your software system.

GThe snapshot file (VDE$DATABASE.SNP) retains the information necessary Dto support concurrent access to the database. This file can also be relatively large.

3By default, VDE places all three files in your VDE >library's root directory. However, if your software system is Hsufficiently large or sufficiently active, you should place the storage Farea (RDA) and snapshot (SNP) files on seperate disk spindles or disk seperate shadow sets.

@To relocate the storage and snapshot areas, specify the desired Adirectory for each on the CREATE LIBRARY /DATABASE and /SNAPSHOT Fqualifiers. If /SNAPSHOT is not specified, the snapshot file Cwill be coresident in the /DATABASE database directory. If neither Dqualifier is specified, all three database files will be coresident.

FThe following example illustrates how you can use these qualifiers to 4control the placement of the various database files:

 

" BVDEä CREATE LIBRARY DEV1$:[ROOTDIR] /DATABASE=DEV2$:[PROJDIR.DB] -=_VDEä /SNAPSHOT=DEV1$:[SNAPDIR] 

8This command causes VDE to place the database root file 9(VDE$DATABASE.RDB) in the library root directory on disk GDEV1$, to place the database data file (VDE$DATABASE.RDA) in directory G[PROJDIR.DB] on disk DEV2$, and to place the database snapshot file in Edirectory [SNAPDIR] on disk DEV1$. Spreading the database files over Etwo disks, as done here, can improve the performance of the database.

<The Rdb database may also use a fourth file, an after-image <journal file (with file type AIJ). When an Rdb database has Aafter-image journalling enabled, all changes to the database are @recorded in that journal file. If the database is later lost or Fdamaged, perhaps due to hardware problems or disk corruption, you can Frestore the database from a backup file and then use the journal file Fto recover all updates since the last backup. Journalling is optional Fbut strongly recommended. To enable journalling, you must specify the Hlocation of the journal file using the /JOURNAL qualifier to the CREATE ELIBRARY or MODIFY LIBRARY command. The journal file should always be Cplaced on a different physical disk from the other database files. lSection 7.4 describes how to back up and recover your VDE 5database and gives more information on journal files.K

6.2.2 Standard User Privileges

>When you create your VDE library, you can specify the default =and authorized VDE privileges you want assigned to new users +as they are added to your VDE library. VDE Fprivileges determine whether a user is allowed to reserve and replace <modules or not, whether a user is allowed to perform queued Breplacements or not, whether a user is allowed to create modules, Fstreams, and facilities or not, and so on. The description of the SET 5PRIVILEGES command contains the full list of all VDE privileges.

BEach user has a set of default privileges and a set of authorized Aprivileges. The default privileges are those privileges that are 7enabled by default each time the user starts a new VDE Fsession. The authorized privileges are those privileges that the user Bis allowed to enable with the SET PRIVILEGES command. The default Bprivileges are always a subset of (or the same as) the authorized privileges.

>The VDE database stores a "standard" set of default Eand authorized privileges that are assigned to new users as they are Fadded to the database. You can override these standard privileges for Fany given user by explicitly specifying different privileges with the CREATE USER or MODIFY USEREcommand. However, use of the standard privileges relieves you of the 5necessity of specifying VDE privileges for each user Dindividually. This is especially important if you allow users to be padded to the database automatically (see Section 6.2.3).

GThe /DEF_PRIVILEGES qualifier to the CREATE LIBRARY command allows you Bto specify the default privileges you want new users to have. The @/AUTH_PRIVILEGES qualifier allows you to specify the authorized ?privileges you want new users to have. You can later use these Cqualifiers with the MODIFY LIBRARY command to change the library's Hstandard privileges. If you do not specify standard privileges for your 0VDE library, VDE gives new users the CREMOD and RESREP privileges by default.

EThe following example shows how you can specify the standard default :and authorized privileges for a VDE library being created:

 

" 5VDEä CREATE LIBRARY /DEF_PRIVILEGES=(CREMOD,RESREP) -;_VDEä /AUTH_PRIVILEGES=(CREMOD,RESREP,CREGRP) 

>The example omits other qualifiers and parameters for clarity.