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

This chapter describes how to set up a new VDE library by creating its database, setting up its disk directory structure, and populating 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 performed 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.

Information pertaining to the tailoring and to the performance of VDE database backup operations is included in Section 7.4. Once you have created the library, you should establish the appropriate backup procedures, and determine the appropriate backup scheduling.

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

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

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

The 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.

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

6.1.2 The CREATE LIBRARY Command

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

VDE„ CREATE LIBRARY DEV$:[ROOTDIR] /NAME=LIBNAME /CREATOR="John Doe" - _VDE„ /REMARK="Library for gadget development"

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

It is strongly recommended that you use a system-wide concealed logical name for the disk name so that you can move the VDE library to another disk at a later time by simply moving the library's files and directories and redefining the logical name. The VDE database records the device names and full directory specifications of numerous subdirectories within the root directory. This makes it difficult to move the VDE library to another disk unless a concealed 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 library. A group-wide concealed logical name is acceptable if all users, present and future, will belong to the same UIC group.

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

When you enter the CREATE LIBRARY command, you are required to specify the desired library root directory, the library name, the name of the library creator (your own first and last names), and a remark string. The root directory name is the command parameter while the library name, creator name, and remark string are specified with qualifiers. VDE stores the library name and remark string in the "database header record" in the Rdb database. Because you are the library creator, VDE records your full name (as specified with the /CREATOR qualifier) and your OpenVMS user name in a User Table entry in the database. A field in the database 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. The following example illustrates how VDE prompts for information if all required items are omitted:

VDE„ CREATE LIBRARY Enter directory specification for the new library: DEV$:[ROOTDIR] Enter the name you want for the new library: LIBNAME Enter your full name (first and last names): John Doe Enter the remark for new library: Library for gadget development

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

By 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 directory. The delta-file root directory will contain one subdirectory for each facility in your software system to hold the facility's CMS library. Each CMS library will hold CMS elements, also called "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 associated directory tree for each development stream in your system. Because the CREATE LIBRARY command always creates stream MAIN, it also creates the root directory and directory tree for that stream by default. The stream MAIN root directory is named MAIN.DIR and is a subdirectory of the library root directory.

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

By default, the CREATE LIBRARY command creates the directories just described for the new library. It also creates the CMS library for facility CODE. However, you can defer directory creation by specifying the /DEFER qualifier with the CREATE LIBRARY command. /DEFER causes VDE to not create any directories other than the library root directory and to not create the CMS library for facility CODE. You can then use the SET DIRECTORY command to specify where you want these deferred directories to be created (see Section 6.3). After entering all desired SET DIRECTORY commands, you can enter the CREATE DIRECTORY_TREE command to actually create the directory tree (or various 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. Section 6.3 describes how to use these capabilities.

The 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 how new users are added to the library, whether the RESERVE command displays the expected CMS generation expression for the corresponding replacement, whether the REPLACE command requests information files by default, and various other attributes. Section 6.2 gives more detail on these attributes. If you do not specify these optional attributes with the CREATE LIBRARY command, VDE provides default settings. You can modify all such settings later with the MODIFY LIBRARY command. You can also use the MODIFY LIBRARY command to change the library name and remark string. The only attribute you cannot change with MODIFY LIBRARY is the library root directory.

6.1.3 Examples

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

VDE„ CREATE LIBRARY DEV$:[ROOTDIR] /NAME=LIBNAME /CREATOR="John Doe" - _VDE„ /REMARK="Library remark" Library LIBNAME to be created in root directory DEV$:[ROOTDIR] 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. Staging area root directory DEV$:[ROOTDIR.VDE$STAGE] has been created Creating directory tree for delta files: Root directory DEV$:[ROOTDIR.VDE$CMS] has been created Facility CODE root directory DEV$:[ROOTDIR.VDE$CMS.CODE] has been created CMS library for facility CODE has been created All directories for delta files now exist Creating directory tree for stream MAIN: Root directory DEV$:[ROOTDIR.MAIN] has been created Subdirectory DEV$:[ROOTDIR.MAIN.VDE$BLD] has been created 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 created Subdirectory DEV$:[ROOTDIR.MAIN.CODE.VDE$COM] has been created 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 DEV$:[ROOTDIR]. The library has name LIBNAME and the library creator is named John Doe. The VDE output shows that VDE has created the library root directory (which turned out to already exist in this case), the VDE database, the VDE staging area directories, the delta-file directory tree including the CMS library for facility CODE, and the directory tree for stream MAIN. The new VDE library thus has the initial facility CODE and the initial stream MAIN fully set up. There are no modules in the library, however, and only one allowed user (the creator John Doe) is recorded in the library database.

In the following example, the library is created the same way except that the library creator (Jane Smith) specifies the /DEFER qualifier to defer the creation of the library directory tree and the CMS library for 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 /DEFER Enter directory specification for the new library: DEV$:[ROOTDIR] Enter the name you want for the new library: LIBNAME Enter your full name (first and last names): Jane Smith Enter 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 and the library database, but does not create the rest of the directory tree. The user thus has the opportunity to modify the directory structure and its exact locations with SET DIRECTORY commands before using 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.

$! $! Locate and delete previous incarnations of the test facility files, $! then unpack the saveset containing the test files... $! $ if f$search("sys$scratch:A.REQ") .nes. "" Then Delete sys$scratch:A.REQ;*/log $ if f$search("sys$scratch:B.REQ") .nes. "" Then Delete sys$scratch:B.REQ;*/log $ if f$search("sys$scratch:C.B32") .nes. "" Then Delete sys$scratch:C.B32;*/log $ if f$search("sys$scratch:D.B32") .nes. "" Then Delete sys$scratch:D.B32;*/log $ if f$search("sys$scratch:E.B32") .nes. "" Then Delete sys$scratch:E.B32;*/log $ if f$search("sys$scratch:F.B32") .nes. "" Then Delete sys$scratch:F.B32;*/log $! $ Backup VDE$CREATE.BCK/SAVE Sys$Scratch: $! $! Create the core directory -- this must be present... $! $ 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]. ! create librar STAR$DATA:[QTV.WWW.VDE$DATABASE] /DEFER - /NAME=WWW - /REMARK="QTV WWW Source Library" - /NOAUTO_CONVERT /AUTO_ADD_USER=VMS_SOURCE /AUTO_MAIL - /ASK_INFO_FILE /ASK_REPL_CAUSE /SHOW_GEN_EXPR /NOSTATISTI - /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 MODIFY CONTEXT/PUBLIC DEFAULT/NOSTREAM/NOFACILITY ! CREATE USER SYSTEM /NAME="System Manager"/DEF_P=ALL/AUTH_P=ALL System Manager ! ! Create the CMS ("delta") library directory structure. ! Configure the CMS libraries to use the directory structure: ! STAR$DATA:[QTV.WWW.CMS$DATABASE.'facility'.CMS]. ! Configure the "marker" files to use the directory structure: ! STAR$DATA:[QTV.WWW.CMS$DATABASE.'facility'.SRC]... ! SET DIRECTORY/DELTA_FILES STAR$DATA:[QTV.WWW.CMS$DATABASE] SET DIRECTORY/DELTA_FILES/SUBDIRECTORY=VDE$CMS [.CMS] SET DIRECTORY/DELTA_FILES/SUBDIRECTORY=VDE$MARKER [.SRC] CREATE DIRECTORY_TREE/DELTA_FILES SHOW DIRECTORY/DELTA_FILES ! ! Create the staging area... ! SET DIRECTORY/STAGING STAR$DATA:[QTV.WWW.VDE$STAGING] CREATE DIRECTORY_TREE/STAGING ! ! Create the stream/build directories ! SET 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" CREATE MODULE/NODELETE/REMARK="VDE self-test module" - A.REQ /INPUT=SYS$SCRATCH: CREATE MODULE/NODELETE/REMARK="VDE self-test module" - B.REQ /INPUT=SYS$SCRATCH: CREATE MODULE/NODELETE/REMARK="VDE self-test module" - C.B32 /INPUT=SYS$SCRATCH: CREATE MODULE/NODELETE/REMARK="VDE self-test module" - D.B32 /INPUT=SYS$SCRATCH: CREATE MODULE/NODELETE/REMARK="VDE self-test module" - E.B32 /INPUT=SYS$SCRATCH: CREATE MODULE/NODELETE/REMARK="VDE self-test module" - F.B32 /INPUT=SYS$SCRATCH: ! EXIT $ $ Exit

6.2 Optional Library Attributes and Settings

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

One attribute you must consider before creating the VDE library is the placement of the VDE database. The VDE database consists of three files: a database root file, a storage area file, and a snapshot file file. (These three files use the file 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 definition the directory that contains the database root file. This file is small, however; it only contains information that Rdb needs to manage the database.

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

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

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

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

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

VDE„ CREATE LIBRARY DEV1$:[ROOTDIR] /DATABASE=DEV2$:[PROJDIR.DB] - _VDE„ /SNAPSHOT=DEV1$:[SNAPDIR]

This command causes VDE to place the database root file (VDE$DATABASE.RDB) in the library root directory on disk DEV1$, to place the database data file (VDE$DATABASE.RDA) in directory [PROJDIR.DB] on disk DEV2$, and to place the database snapshot file in directory [SNAPDIR] on disk DEV1$. Spreading the database files over two 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 after-image journalling enabled, all changes to the database are recorded in that journal file. If the database is later lost or damaged, perhaps due to hardware problems or disk corruption, you can restore the database from a backup file and then use the journal file to recover all updates since the last backup. Journalling is optional but strongly recommended. To enable journalling, you must specify the location of the journal file using the /JOURNAL qualifier to the CREATE LIBRARY or MODIFY LIBRARY command. The journal file should always be placed on a different physical disk from the other database files. Section 7.4 describes how to back up and recover your VDE database and gives more information on journal files.

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 privileges determine whether a user is allowed to reserve and replace modules or not, whether a user is allowed to perform queued replacements or not, whether a user is allowed to create modules, streams, and facilities or not, and so on. The description of the SET PRIVILEGES command contains the full list of all VDE privileges.

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

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

The /DEF_PRIVILEGES qualifier to the CREATE LIBRARY command allows you to 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 qualifiers with the MODIFY LIBRARY command to change the library's standard privileges. If you do not specify standard privileges for your VDE library, VDE gives new users the CREMOD and RESREP privileges by default.

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

VDE„ CREATE LIBRARY /DEF_PRIVILEGES=(CREMOD,RESREP) - _VDE„ /AUTH_PRIVILEGES=(CREMOD,RESREP,CREGRP)

The example omits other qualifiers and parameters for clarity.