VDE supports a number of convenience features.

1.9.1 Kept Subprocess

VDE can utilitize a kept subprocess. The kept subprocess is created when the command interface is first activated, and it greatly improves overall performance. With the kept subprocess, all of the processing required to initially connect to the database is performed only once, not each time the utility is activated.

To force an update of the security and quota attributes in the kept subprocess, issue the following commands:

VDE„ EXIT/KEPT_PROCESS $ VDE/KEPT_PROCESS VDE„

The above commands cause the kept subprocess to exit and, as any subsequent invocation of VDE (with /KEPT_PROCESS) determines that there is no kept subprocess present, it will then spawn one.

1.9.2 Initialization Files

One can use an initialization file to set up VDE command abbreviations (with DEFINE/COMMAND), keypad definitions (with DEFINE/KEY), and session environment defaults (with SET FACILITY and SET STREAM). An initialization file can contain zero or or more VDE commands.

VDE supports a user-specified initialization file. Each utility processes an initialization file in a similar fashion, though each uses a unique name for the file. The initialization file is automatically invoked at the start of each VDE session.

To establish an initialization file for the VDE utility, define the logical name VDE$INIT³ before starting the VDE session. This logical name must reference the file name of the VDE initialization file. If the file name and/or the file extension is omitted from the logical name translation, the VDE utility uses the default value VDE$INIT.VDE for the initialization file.

An initialization file is usually resident in the user's SYS$LOGIN: directory.

If desired, the exclamation point (!) can be used as a comment character in an VDE or an VDE initialization file. All text located after a exclamation point is ignored up to and including the end of the line, if the exclamation point is not located within a quoted string. The space-hyphen ( --) can be used as a line continuation. The space-hyphen character must be the last character of a line; it causes the subsequent command line to be considered part of the current line.

1.9.3 Selecting a Text Editor

VDE lets one establish a text editor for the VDE session. VDE invokes the specified editor when certain commands are entered. For example, VDE lets one use an editor to review code changes on behalf of another user. The editor is invoked in a spawned subprocess, and can be invoked in read-write or read-only mode, depending on the context. To specify the editor for the current VDE session, use the SET EDITOR command. For example:

VDE„ SET EDITOR "LSEDIT"

This command tells VDE to spawn the LSEDIT command, which invokes the VAX Language-Sensitive Editor, whenever a VDE command requires an editor to be invoked. If you prefer some other editor, you should specify the DCL command for that editor instead. You can also include any qualifiers you want in the quoted string. VDE simply starts with the string you specify, appends a space and the name of the file to edit, and spawns the resulting DCL command string. If the editor is invoked in read-only mode, VDE appends the /READ_ONLY qualifier (which most OpenVMS editors accept), a space, and a file name to the string you specify, and then spawns that. (If your editor does not accept the /READ_ONLY qualifier, see the HELP text to see how you can specify a separate read-only editor string.)

The /DEFAULT qualifier on the SET EDITOR command allows one to establish the default editor strings for future VDE sessions. These editor strings are stored in the source control database. The SHOW EDITOR command displays the current editor strings.

VDEalso supports a number of standard utility commands. These commands include @file-spec (which executes a file containing VDE commands), SPAWN, ATTACH, EXIT, HELP, DEFINE/KEY and SET KEY, DEFINE/COMMAND, SET LOG and CANCEL LOG, SET VERIFY and CANCEL VERIFY, SET TERMINAL, and all associated SHOW commands. See the HELP text for descriptions of these commands.

1.9.4 Grouping Reservations into Sessions

VDE and VDE module reservations can be grouped together using sessions. One can create a session that contains a group of modules involved in a particular modification or fix---all modules contained in a session can be referenced in a single command.

VDE„ REPLACE/SESSION=WIN32_VMS

The above command replaces all modules included in the WIN32_VMS session.

Information on how to reserve and replace modules is included in Chapter 2.

1.9.5 Defining Defaults Using Contexts

A context allows you to easily switch an entire group of related VDE default settings among a set of possible values. You can keep multiple sets of VDE defaults around.

Each context is comprised of a set of defaults: a default facility, a default stream, and a default architecture. (For information on architectures, see Chapter 9.) You can specify one context for use when you are making bugfixes to a particular stream and facility, and another context for when you are adding new features to a different facility in a newer stream. And using key definitions (DEFINE/KEY), you can switch among your various contexts using a single keystroke.

Contexts can be private and user-defined, or they can be publically established and available for whole groups of users. Project leaders can establish a set of contexts for use by a particular group of users.

1.9.6 Default Libraries, Mnemonics

VDE utilitizes a set of logical names to determine the names, contents and locations of commonly-accessed libraries. To see which libraries have been established by default (if any), issue the command:

VDE„ SET LIBRARY

In addition to telling you that the command needs another parameter, this command will display any default libraries.

For information on the VDE$LIBRARY_DEFAULTS logical names, see VDE Reference Manual, or see Section 10.1.3.

This chapter describes how to use the VSC utility to identify specific modules in a VDE library. It also shows you how to create, reserve and replace modules, how to fetch module generations without reserving them, how to create new modules, how to cancel reservations, and how to display reservation information from the source control database.

This section also describes some convenience features present in VSC and VDE. Examples of these features include the ability to reserve groups of modules, called sessions, and treat these modules as a unit. Also covered is the ability to queue a reservation request when a module is reserved by another user, and how to receive notification when the queued reservation request is eventually granted.

2.1 Identifying Module Generations

Each generation of a given module can be referenced using either of two names. One generation name is the generation number. This number is assigned and maintained by VSC. The other generation name is the generation expression. The generation expression is assigned by CMS. One can use either generation name to specify a specific generation in VSC commands.

VSC assigns generation numbers in sequential order to the generations for each development stream. Generation 1 is thus the first generation for the stream, generation 2 is its successor, and so on. Generation 2 of stream A can be the same as generation 2 of stream B (if the streams have not yet diverged) or they may be two different generations (assuming the streams have diverged).

When one refers to a generation by its generation number on a VSC command, one specifies a semicolon and the generation number after the module name. The generation number is relative to some stream that one specifies explicitly (usually with the /STREAM qualifier) or by default. For example, MOD.TYP;5 refers to generation 5 for the specified stream. One can also specify a zero or negative generation number; such a generation number is relative to the latest generation for the stream. MOD.TYP;0 thus refers to the latest generation and MOD.TYP;--1 refers to the next most recent generation, and MOD.TYP;--0 refers to the oldest.

CMS generation expressions are assigned by different means. The first generation for a module has generation expression 1. It can have multiple successors (for different streams) with generation expressions 2, 1A1, 1B1, 1C1, and so on. Generation 1B1 can in turn have successors 1B2, 1B1A1, 1B1B1, and so on. Each generation thus has a unique generation expression that encodes its genealogy. This expression is independent of stream. To specify a generation by its generation expression, one must use the /GENERATION qualifier for those commands that accept it. For example, MOD.TYP/GENERATION=1B1 refers to the generation of module MOD.TYP that has generation expression 1B1.

If one omits both the generation number and the /GENERATION qualifier, most VSC commands reference the latest generation of the module for the specified stream. This causes the command to operate on the most recent generation by default---this is normally the desired effect.

Because generation numbers are always relative to some stream, they are used to show lines of descent for a given stream and to reference generations relative to a specific stream. CMS generation expressions are independent of stream and thus give absolute names to the generations of a module. These two kinds of generation names are primarily used with the SHOW GENERATION and FETCH commands. For example, to fetch the next most recent generation of module FOO.BAR for stream FRED, one would request generation number --1, as shown in this example:

VSC„ FETCH /STREAM=FRED FOO.BAR;-1

However, one can also request the generation with generation expression 10A3 (which is an absolute name; entirely independent of stream), as in this example:

VSC„ FETCH FOO.BAR /GENERATION=10A3

For most commands, including FETCH, one should not specify a generation. The default references the latest generation for a specified (or defaulted) stream, and this is nearly always the generation one typically wishes to reference. When reserving a module, one never specifies a generation to reserve; VSC always retrieves the latest generation for the specified stream.

Audit Trail Identifiers

When modifying a source module, one typically adds code comments that explain the nature of the changes. These comments should be labelled by an audit trail identifier. The audit trail identifier is simply the expected CMS generation expression of the new generation one creates when replacing the changed module into the VDE library. VDE displays the expected CMS generation expression when the module is initially reserved. In rare circumstances, the actual generation expression used when the module is replaced may differ from the expected generation expression displayed when the module is reserved. If this happens, VSC displays an informational message. One must then update the source module to correct the audit trail identifier in the code comments.

2.2 Reserving Modules

To reserve a module from a VDE library, use the RESERVE command. This command reserves a specified module for a given development stream and fetches that module into your default directory. This example illustrates the syntax of the RESERVE command:

VSC> RESERVE/STREAM=FOO [FACIL]MOD.TYP "Remark string"

This command reserves module MOD.TYP in facility FACIL from a VDE library. The latest generation of the module for stream FOO is copied into your default directory.

With the RESERVE command, you can specify a list of module names separated by commas. This syntax---or the session support---allows you to manipulate a number of modules with only a few commands. For example:

VSC> SET FACILITY SYS VSC> RESERVE/STREAM=FOO A.MAR,B.MAR,C.MAR "Reduce memory-scrambling"

This example reserves modules A, B, and C in facility SYS from stream FOO. Note that you do not have to include the facility names with the RESERVE command if the modules belong to the default facility established with a previous SET FACILITY command.

You can use wildcard characters in the module names. The percent sign (%) in a name matches any single character in the position it occupies and the asterisk (*) matches zero or more characters in the position it occupies. All modules that match the wildcard pattern are reserved.

VDE also allows you to associate a number of modules from various RESERVE and CREATE MODULE commands together, by using the /SESSION qualifier. The /SESSION qualifier allows you to pick a name for a group of modules, and to avoid having to specify each module on the REPLACE command. The use of /SESSION also provides the reviewers and the project leader with a clear indication that a group of replacement modules are related.

The reservation remark string can be specified as a parameter at the end of the command, as shown in the previous example. The remark parameter has the same effect as the /REMARK qualifier described in Table 2-1 and applies to all reserved modules unless overridden by /REMARK qualifiers on the individual module-name parameters.

The RESERVE command displays the expected CMS generation expression for the new generation that will be created when the module is later replaced. You should use this generation expression as the "audit trail identifier" for the comments in your code that explain your new changes. This example illustrates the RESERVE command's output:

VSC>RESERVE/STREAM=BIRCH [FACIL]MOD.TYP "Add gasket modulator" %VDE-I-FETCHED, generation [FACIL]MOD.TYP;3(3) fetched from library %VDE-I-OUTFILE, output file is DEV$:[MYDIR]MOD.TYP; %VDE-I-RESERVED, generation [FACIL]MOD.TYP;3(3) reserved from stream BIRCH %VDE-I-EXPGENEXPR, expected generation expression at replacement is 3A1 %VDE-I-COMMIT, database transaction has successfully committed VSC>

In this case, you should use 3A1 as your audit trail identifier. This expected CMS generation expression might differ from the one actually assigned when you later replace the module, but only in certain unusual circumstances. VSC prints a message when the replacement is performed if the expected and actual generation expressions differ. If so, you need to rereserve the module to correct the audit trail identifier.

The source control system keeps track of successor relationships between streams. If source changes replaced into a stream A should normally also be propagated to another stream B, then stream B is a successor of stream A. Successor relationships between streams are defined by the maintainers of the VDE libraries, and reside in the source control database. These relationships ensure that bug fixes and other changes made to one version of OpenVMS are propagated to all later versions of OpenVMS.

Successor relationships determine what streams are affected by a module reservation. Normally, a reservation covers the development stream specified with the /STREAM qualifier and all successors of that stream, including the successors of the successors, and so on recursively. If you omit the /STREAM qualifier, the reservation covers your default stream and its successors. This means that you expect your changes to be propagated to those streams when you later replace the module. However, the reservation does not cover any stream in which the module has already diverged from the original stream because VSC cannot automatically propagate source changes to such a stream.

The RESERVE command determines what streams your reservation will cover and checks if any existing reservation for the module already covers one of those streams. If so, the RESERVE command rejects your reservation attempt unless you explicitly request a concurrent reservation. You can limit change propagation, and therefore restrict the streams covered by your reservation, by using the /PROPAGATE and /NOPROPAGATE qualifiers. By covering fewer streams (when appropriate), you make reservation conflicts less likely.

The RESERVE command accepts a number of qualifiers. The help text and the reference manual have the details on all of the qualifiers accepted by the command. Table 2-1 lists some of the more commonly-used qualifiers.

Table 2-1 Qualifiers to the RESERVE command

/CONFIRM /NOCONFIRM
	/CONFIRM asks you to confirm that you want each module reserved. This qualifier is particularly useful if you use wildcard characters in the module name. /NOCONFIRM reserves each module without asking for confirmation. /NOCONFIRM is the default.
/IDENTIFICATION=res-ident
	Specifies that the reservation be identified by the name given by the res-ident parameter. This name can be an arbitrary string that is meaningful to you. (The name must consist of letters, numbers, dollar signs, and underscores and can be up to 39 characters long.) If this qualifier is omitted, the source control system automatically assigns a numeric reservation identifier. Reservation identifiers distinguish between multiple concurrent reservations for the same module by the same user.
/LOG /NOLOG
	Specify whether informational log messages are printed after each module is reserved. /LOG causes such messages to be printed and /NOLOG suppresses them. /LOG is the default.
/NOCONCURRENT
	Specifies that concurrent reservations not be allowed for any of the modules reserved by this command. If this qualifier is omitted, other users are allowed to concurrently reserve the modules.
/OUTPUT=filespec /NOOUTPUT
	/OUTPUT specifies that the reserved module be written to the file or directory given by the filespec parameter. /NOOUTPUT specifies that the reserved module not be written to an output file at all. If neither qualifier is specified, VSC creates the output file in your current default directory and gives it the same name and type as the module.
/OVERRIDE=CONCURRENT
	Specifies that the RESERVE command should reserve each specified module even if the module is already reserved by another user. This qualifier is required to create concurrent reservations. However, VSC creates a concurrent reservation for a module only if all previous, conflicting reservations of that module allow concurrent reservations. If this qualifier is omitted, the RESERVE command reserves the module only if it is not already reserved. When this qualifier creates a concurrent reservation, the VSC utility automatically sends a mail message to each developer who already holds a reservation for the module in order to notify him or her of the new concurrent reservation.
/PROPAGATE=stream-name /NOPROPAGATE
	Determine what streams are covered by the current reservation and how module changes are propagated to successor streams when the module is later replaced into the library. /PROPAGATE specifies that the reservation should be propagated to all successors of the initial development stream up to and including the stream specified by the stream-name parameter. /NOPROPAGATE specifies that the reservation not be propagated past the initial stream. If neither /PROPAGATE nor /NOPROPAGATE is specified, the reservation is propagated to all successors (recursively) of the initial stream. These qualifiers are used when a change is appropriate for only a subset of the streams in the successor chain. For example, a bug fix might apply only to the initial stream because it is replaced by a new algorithm in later streams. For OpenVMS VAX, most reservations should use the default propagation behavior and you should seldom need these qualifiers.
/QUEUE
	Specifies that a reservation request should be queued if you cannot reserve the module because it is already reserved by another user. If the requested module can be reserved now, the module is reserved and this qualifier has no effect. If the module is not available, VSC queues a reservation request for it. When the module later becomes available, you are notified by a mail message and you can then reserve the module.
	When you queue a reservation request, the source control system records the queued reservation in its database. The SHOW RESERVATION command displays queued reservations. When the developer who owns the current reservation later replaces the module into the library or cancels the reservation, VSC sends a mail message to each user who has queued a reservation request for the module. The mail message says that the module is available and lists all users who have requested it in the order that they requested it. Those users must then decide among themselves who should reserve the module first. To actually reserve the module, you must enter another RESERVE command.
/REMARK="string"
	Specifies a one-line remark string to be associated with the reservation. The string can be up to 132 characters long.
/SESSION=session-name
	/SESSION allows you to associated various reserved and created modules together into a session; sessions allow you to later replace a whole series of reserved and created modules via a single REPLACE command. When used with the queued-replacement environment, the use of sessions also provides a clear indication to the reviewers and to the project leader that the modules being replaced are associated. The particular session name used is typically a mnemonic name chosen by the user, and usually reflects the particular set of changes being made.
/STREAM=stream-name
	Specifies the development stream from which the specified modules are reserved. The stream-name parameter gives the name of the stream. If this qualifier is omitted, the modules are reserved from your default development stream, provided one is defined.
/USERNAME=username
	Specifies that the module should be reserved on behalf of the user whose OpenVMS user name is given by the username parameter. To use this qualifier, you must have a VSC privilege (USERNAME); the qualifier is meant for release project leaders and others who manage the VDE libraries, and is intended to be used only in special or unusual situations.