| Previous | Contents | Index |
Examples
This is an example of the output of the RESERVE command:
VSC> RESERVE/STREAM=BIRCH [FACIL]MOD.TYP "Fix QAR 55" %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> |
The following example shows how VSC displays multiple log messages when you reserve multiple modules with the same RESERVE command:
VSC> SET FACILITY SYS VSC> RESERVE/STREAM=PHOENIX A.MAR,B.MAR,C.MAR "Add scramble feature" %VDE-I-FETCHED, generation [FACIL]A.MAR;5(2A3) fetched from library %VDE-I-OUTFILE, output file is DEV$:[MYDIR]A.MAR; %VDE-I-FETCHED, generation [FACIL]B.MAR;1(1) fetched from library %VDE-I-OUTFILE, output file is DEV$:[MYDIR]B.MAR; %VDE-I-FETCHED, generation [FACIL]C.MAR;3(3) fetched from library %VDE-I-OUTFILE, output file is DEV$:[MYDIR]C.MAR; %VDE-I-RESERVED, generation [FACIL]A.MAR;5(2A3) reserved from stream PHOENIX %VDE-I-EXPGENEXPR, expected generation expression at replacement is 2A4 %VDE-I-RESERVED, generation [FACIL]B.MAR;1(1) reserved from stream PHOENIX %VDE-I-EXPGENEXPR, expected generation expression at replacement is 2 %VDE-I-RESERVED, generation [FACIL]C.MAR;3(3) reserved from stream PHOENIX %VDE-I-EXPGENEXPR, expected generation expression at replacement is 4 %VDE-I-COMMIT, database transaction has successfully committed VSC> |
A module reservation is said to "cover" all development streams to which you expect the module to be propagated when you later replace it. This means that, if the stream that you reserve a module from has a successor stream and if the module has not yet diverged between the two streams, the reservation covers both streams. If the successor stream also has a successor, that stream is covered too (if the module has not diverged), and so on. If two reservations of the same module cover at least one common development stream, then the two reservations are said to be concurrent reservations of the module.
The source control system does not by default create a concurrent reservation for you when you reserve a module. If someone else's existing reservation conflicts with the reservation you are trying to create, it is best for you to wait for the other developer to replace (or unreserve) the module before you reserve it and start to modify it. If both of you modify a module at the same time for the same stream, one of you will have to manually merge the parallel sets of changes to make the module right. This extra step in effect requires someone to enter his or her changes twice, which is more work and increases the risk of errors. Avoiding concurrent reservations is therefore your best policy.
However, there are exceptions. Sometimes you might need to change a module to fix a bug in the current build, for example, even though someone else (or even you yourself) already has reserved the module for more extensive changes. In such cases, you can use the /OVERRIDE=CONCURRENT qualifier on the RESERVE command to concurrently reserve the module. When you have completed your change, you queue the module for replacement with the REPLACE command. When the release project leader performs your replacement, the other developer's reservation is cancelled and he or she is notified of this fact by a mail message. That other developer must then rereserve the module, merge his or her changes with your changes, and then continue his or her work. When you create a concurrent reservation for a module and then replace the module first, you thus create work for another developer, so you need a good reason for doing so.
The following example illustrates what happens when you try to reserve a module that is already reserved:
VSC> RESERVE [RMS]MODULE_E.B32 "Emergency bug fix"
Module [BUILD_TEST]E.B32 is currently reserved:
Reservation 1 by user HOFFMAN on 18-JAN-1990 15:45:51.77
Remark: FIRST RESERVATION
%VDE-E-MODALRRES, module [RMS]MODULE_E.B32 already reserved by another user
attempt to reserve module has failed
%VDE-I-ROLLBACK, database transaction rolled back
VSC>
|
If you decide that you must create a concurrent reservation for the module after all, you enter this command:
VSC> RESERVE/OVERRIDE=CONCURRENT [RMS]MODULE_E.B32 "Emergency bug fix"
Module [BUILD_TEST]E.B32 is currently reserved:
Reservation 1 by user HOFFMAN on 18-JAN-1990 15:45:51.77
Remark: FIRST RESERVATION
%VDE-I-FETCHED, generation [RMS]MODULE_E.B32;1(1) fetched from library
%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MODULE_E.B32;
%VDE-I-RESERVED, generation [RMS]MODULE_E.B32;1(1) reserved from stream BIRCH
%VDE-I-EXPGENEXPR, expected generation expression at replacement is 2
%VDE-I-COMMIT, database transaction has successfully committed
VSC>
|
When you reserve a module, you can specify that you do not want other developers to create concurrent reservations for that module. To do so, use the /NOCONCURRENT qualifier on the RESERVE command:
VSC> RESERVE/NOCONCURRENT [RMS]MODULE_E.B32 "Remark string" |
VSC and VSC support queued reservations. When you queue a reservation request, the source control system records the queued reservation in its database, pending the availability of the specified module. 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 queued reservation request mail message indicates that the module is now available for reservation, and it lists all users who have requested it, in the order the requests were posted. The users listed in the message must decide among themselves who should reserve the module first.
To actually reserve the module, one must enter an explicit RESERVE command.
In addition to displaying other reservation information, the SHOW
RESERVATION command displays all queued reservations.
2.3 Creating New Modules
To create a new source module, use the CREATE MODULE command:
VSC> CREATE MODULE [FACIL]MOD.TYP /STREAM=BIRCH /REMARK="Remark string" |
You can create multiple modules with a single CREATE MODULE command by specifying a list of module names separated by commas.
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.
If you should mistakenly create a module under an incorrect module name, or should you create a module that becomes unnecessary, you can---prior to module replacement---issue a DELETE MODULE command. The DELETE MODULE command will cancel the reservation, and will correctly back out the CREATE MODULE command. For further details on this, see the VDE Reference Manual.
The CREATE MODULE 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-2 lists some of the more commonly-used qualifiers.
|
/LOG
/NOLOG |
|
| Specify whether informational log messages are printed after each module is created. /LOG causes such messages to be printed and /NOLOG suppresses them. /LOG is the default. | |
|
/MARKER
/NOMARKER |
|
| Specify that the module is a "marker file". A marker file is any binary, image, saveset, or library file that should not stored via the normal delta mechanism used within the CMS library, but should be stored as a seperate module in the marker file directory (see SHOW DIRECTORY/DELTA). This setting avoids having extensive delta-related processing and storage overhead between one generation of a binary module and the next. | |
| /REMARK="string" | |
| Specifies a one-line remark string to be associated with the module. This remark typically explains the purpose or function of the module. If you omit this qualifier, VSC prompts you for a remark. | |
| /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 new module is reserved. The stream-name parameter gives the name of the stream. If this qualifier is omitted, the module is reserved from your default development stream, provided one is defined. | |
This is an example of the CREATE MODULE command:
VSC> SET STREAM PHOENIX VSC> CREATE MODULE [FACNAM]NEWMOD.C /REMARK="Update widget table" %VDE-I-RESERVED, generation [FACNAM]NEWMOD.C reserved from stream PHOENIX %VDE-I-MODADDED, module [FACNAM]NEWMOD.C added to the database %VDE-I-COMMIT, database transaction has successfully committed VSC> |
To fetch an existing module without reserving it, use the FETCH command. For example:
VSC> FETCH/STREAM=FOO [FACIL]MOD.TYP |
The FETCH command accepts multiple module names separated by commas and accepts the asterisk (*) and percent sign (%) wildcard characters in the module-name parameters. Those modules whose names match the wildcard patterns are fetched.
You can specify the specific generation you want to fetch in two ways. One way is to specify a generation number preceded by a semicolon after the module name. For example, MOD.TYP;5 refers to absolute generation 5 for the specified development stream. MOD.TYP;0 refers to the latest generation of the module in the specified stream and MOD.TYP;--1 refers to generation --1 relative to the latest generation in the stream (in other words, to the next most recent generation). The second method to specify the generation you want is to use the /GENERATION=gen-expr qualifier to specify the CMS "generation expression" of the desired generation. If you specify neither a generation number nor the /GENERATION qualifier, VSC fetches the latest generation for the specified (or default) development stream.
In addition to the /GENERATION qualifier, the FETCH command accepts a subset of the RESERVE command qualifiers. The FETCH command also accepts an optional quoted remark parameter for compatibility with CMS, but since there is no reason to record fetch operations, the remark string is simply discarded.
The FETCH command accepts a number of qualifiers. The help text and the reference manual have the details on the qualifiers accepted by the command. Table 2-3 contains some of the more commonly-used qualifiers.
|
/CONFIRM
/NOCONFIRM /LOG /NOLOG /OUTPUT /STREAM |
|
| Same as for the RESERVE command. | |
| /GENERATION=gen-expr | |
| Specifies that the module generation be fetched that has the CMS generation expression given by the gen-expr parameter. This expression is also the generation's audit trail identifier. If this qualifier is omitted, the command fetches the generation given by the generation number on the module-name parameter. If both this qualifier and the generation number are omitted, the command fetches the most recent generation of the module in the specified development stream. | |
|
/HISTORY[="string"]
/NOHISTORY |
|
| Determine whether CMS history information is included in the fetched source module. /HISTORY causes CMS history information to be included in the output file and /NOHISTORY suppresses such information. If neither qualifier is specified, the history attribute for each module determines whether history information is included. For OpenVMS VAX, history information is turned off by default. | |
|
/NOTES[="string"]
/NONOTES /POSITION=col-num |
|
| Determine whether CMS notes information is included in the fetched source module. /NOTES causes CMS notes information to be included in the output file and /NONOTES causes such information to be omitted. If CMS notes are included, the /POSITION qualifier specifies the column number of the notes text. If neither /NOTES nor /NONOTES is specified, the notes attribute for each module determines whether notes are included. For OpenVMS VAX, notes are turned off by default. | |
This is an example of the FETCH command:
VSC> FETCH A.REQ %VDE-I-FETCHED, generation [FACNAM]A.REQ;3(2A1) fetched from library %VDE-I-OUTFILE, output file is DEV$:[MYDIR]A.REQ; VSC> |
The following example fetches two modules, C.B32 in facility SYS and D.B32 in facility BAD, and copies them to directory [MYDIR]:
VSC> FETCH/OUTPUT=[MYDIR] [SYS]C.B32/STREAM=V4.4,[BAD]D.B32/GENERATION=3A2 %VDE-I-FETCHED, generation [SYS]C.B32;4(4) fetched from library %VDE-I-OUTFILE, output file is DEV$:[MYDIR]C.B32; %VDE-I-FETCHED, generation [BAD]D.B32;5(3A2) fetched from library %VDE-I-OUTFILE, output file is DEV$:[MYDIR]D.B32; VSC> |
The command fetches the latest generation of C.B32 for stream V4.4, and
it fetches the generation of D.B32 that has CMS generation expression
3A2.
2.5 Unreserving Modules
To cancel a module reservation without replacing the module, use the UNRESERVE command. The following example illustrates its use:
VSC> UNRESERVE/STREAM=FOO [FACIL]MOD.TYP "Remark string" |
The UNRESERVE command accepts wildcard characters in the module-name parameter. Those modules whose names match the wildcard pattern are unreserved. The command also accepts multiple module-name parameters separated by commas.
The optional remark string parameter specifies a remark that explains why the module reservation was cancelled. You can also specify the remark string with the /REMARK qualifier.
The UNRESERVE command accepts a subset of the REPLACE command
qualifiers (see Table 2-5). The following qualifiers have the same
meanings as for the REPLACE command: /CONFIRM, /NOCONFIRM,
/IDENTIFICATION, /LOG, /NOLOG, /STREAM, and /USERNAME.
2.6 Displaying Reservations
Once a reservation has been entered into the source control system's database, you can display it with the SHOW RESERVATION command. This is a typical example:
VSC> SHOW RESERVATION [FACIL]MOD.TYP |
The SHOW RESERVATION command accepts a list of module names separated by commas, and you can use the asterisk (*) and percent sign (%) wildcard characters in the module names. All reservations for modules that match the wildcard patterns are displayed.
The SHOW RESERVATION 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-4 describes a number of the more commonly-used qualifiers.
| /BEFORE=date-time | |
| Displays only those reservations created before the specified date and time. | |
|
/BRIEF
/FULL |
|
| Determine the type of information displayed for each reservation. /BRIEF displays the reservation identifier, the name of the reserved module, the reserving user, the date of the reservation, and the stream in which the module is reserved. This display normally fits on one line. /FULL displays all database information about the reservation; this display requires several lines per reservation. /BRIEF is the default. | |
| /NOQUEUE | |
| Specifies that queued reservation requests not be displayed. If this qualifier is omitted, the command displays both queued reservation requests and normal reservations. | |
| /OUTPUT=filespec | |
| Directs the printed output of this command to a specified file. The filespec parameter specifies the name of the file. VSC creates a new file with that name, directs the command's print output to that file, and prints nothing on your terminal. If this qualifier is omitted, all output appears on the terminal. | |
| /SINCE=date-time | |
| Displays only those reservations created on or after the specified date and time. | |
| /STREAM[=stream-name] | |
| Displays only those reservations made for the development stream given by the stream-name parameter. If the stream-name parameter is omitted, the command only displays those reservations made for your default stream. If the /STREAM qualifier is omitted entirely, the command displays reservations for all streams. | |
| /TOTAL | |
| Shows the total number of reservations that match the specified module names, usernames, and other constraints. Only the total count is shown; other information about the individual reservations is not shown. | |
| /USERNAME[=username] | |
| Specifies the OpenVMS user name for the user whose reservations are to be shown. If this qualifier is specified, VSC only displays that user's reservations. If the username parameter is omitted, VSC only displays your own reservations. If the whole qualifier is omitted, VSC displays reservations for all users. | |
This is an example of the brief output of the SHOW RESERVATION command:
VSC> SHOW RESERVATION Reservation 1 of [FACIL]FOO.MAR SMITH 18-NOV-1990 BIRCH Reservation 1 of [FACIL]FUMBLE.MAR JONES 5-SEP-1990 PHOENIX Queued reservation 2 of [FACIL]FUMBLE.MAR MURGATROID 21-NOV-1990 PHOENIX Reservation 1 of [FACIL]SCRAMBLE.B32 SMITH 31-OCT-1990 MUSHROOM VSC> |
The following example shows the full output of the SHOW RESERVATION command for one reservation:
VSC> SHOW RESERVATION/FULL [FACIL]FOO.MAR Reservation 1 of [FACIL]FOO.MAR Reservation created on 18-NOV-1990 10:39:54.31 Reservation created by user SMITH (Jane Smith) Generation 15 (15) reserved from stream BIRCH Expected generation expression at replacement is 16 (audit trail identifier) Concurrent reservations are allowed Remark: Fix QAR 23 again VSC> |
| Previous | Next | Contents | Index |