Examples


8This is an example of the output of the RESERVE command:

 

" 8VSC> RESERVE/STREAM=BIRCH [FACIL]MOD.TYP "Fix QAR 55"C%VDE-I-FETCHED, generation [FACIL]MOD.TYP;3(3) fetched from library3%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MOD.TYP;J%VDE-I-RESERVED, generation [FACIL]MOD.TYP;3(3) reserved from stream BIRCHG%VDE-I-EXPGENEXPR, expected generation expression at replacement is 3A1>%VDE-I-COMMIT, database transaction has successfully committedVSC> 

GIn this example, module MOD.TYP in facility FACIL is reserved from the EOpenVMS VAX library. The module is reserved for stream BIRCH and all Esuccessor streams that have the same generation of MOD.TYP as BIRCH. GOne of the log messages indicates that generation 3 in that stream was Cfetched out. The new generation created when you later replace the Emodule is expected to have the generation expression 3A1; you should Cuse this string as the audit trail identifier in the code comments explaining your changes.

:The following example shows how VSC displays multiple log Amessages when you reserve multiple modules with the same RESERVE command:

 

" VSC> SET FACILITY SYSGVSC> RESERVE/STREAM=PHOENIX A.MAR,B.MAR,C.MAR "Add scramble feature"C%VDE-I-FETCHED, generation [FACIL]A.MAR;5(2A3) fetched from library1%VDE-I-OUTFILE, output file is DEV$:[MYDIR]A.MAR;A%VDE-I-FETCHED, generation [FACIL]B.MAR;1(1) fetched from library1%VDE-I-OUTFILE, output file is DEV$:[MYDIR]B.MAR;A%VDE-I-FETCHED, generation [FACIL]C.MAR;3(3) fetched from library1%VDE-I-OUTFILE, output file is DEV$:[MYDIR]C.MAR;L%VDE-I-RESERVED, generation [FACIL]A.MAR;5(2A3) reserved from stream PHOENIXG%VDE-I-EXPGENEXPR, expected generation expression at replacement is 2A4J%VDE-I-RESERVED, generation [FACIL]B.MAR;1(1) reserved from stream PHOENIXE%VDE-I-EXPGENEXPR, expected generation expression at replacement is 2J%VDE-I-RESERVED, generation [FACIL]C.MAR;3(3) reserved from stream PHOENIXE%VDE-I-EXPGENEXPR, expected generation expression at replacement is 4>%VDE-I-COMMIT, database transaction has successfully committedVSC> 

?

2.2.1 Concurrent Reservations

BA module reservation is said to "cover" all development Gstreams to which you expect the module to be propagated when you later Ereplace it. This means that, if the stream that you reserve a module Cfrom has a successor stream and if the module has not yet diverged Ebetween the two streams, the reservation covers both streams. If the Fsuccessor stream also has a successor, that stream is covered too (if Dthe module has not diverged), and so on. If two reservations of the Gsame module cover at least one common development stream, then the two Hreservations are said to be concurrent reservations of the module.

BThe source control system does not by default create a concurrent Areservation for you when you reserve a module. If someone else's Fexisting reservation conflicts with the reservation you are trying to Fcreate, it is best for you to wait for the other developer to replace H(or unreserve) the module before you reserve it and start to modify it. EIf both of you modify a module at the same time for the same stream, Gone of you will have to manually merge the parallel sets of changes to Emake the module right. This extra step in effect requires someone to Eenter his or her changes twice, which is more work and increases the Hrisk of errors. Avoiding concurrent reservations is therefore your best policy.

DHowever, there are exceptions. Sometimes you might need to change a Cmodule to fix a bug in the current build, for example, even though Hsomeone else (or even you yourself) already has reserved the module for 7more extensive changes. In such cases, you can use the F/OVERRIDE=CONCURRENT qualifier on the RESERVE command to concurrently Greserve the module. When you have completed your change, you queue the Bmodule for replacement with the REPLACE command. When the release @project leader performs your replacement, the other developer's Ereservation is cancelled and he or she is notified of this fact by a Cmail message. That other developer must then rereserve the module, Emerge his or her changes with your changes, and then continue his or Dher work. When you create a concurrent reservation for a module and @then replace the module first, you thus create work for another 2developer, so you need a good reason for doing so.

GThe following example illustrates what happens when you try to reserve "a module that is already reserved:

 

" 5VSC> 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 RESERVATIONK%VDE-E-MODALRRES, module [RMS]MODULE_E.B32 already reserved by another user% attempt to reserve module has failed1%VDE-I-ROLLBACK, database transaction rolled backVSC> 

AIn this example, the RESERVE command fails because the module is Falready reserved by another user. The command's output identifies the Dconflicting reservation so you can see who owns it (user HOFFMAN in Dthis example). The reservation conflicts with the one you wanted to >make because it covers some common stream for the same module.

DIf you decide that you must create a concurrent reservation for the )module after all, you enter this command:

 

" IVSC> 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 RESERVATIONF%VDE-I-FETCHED, generation [RMS]MODULE_E.B32;1(1) fetched from library8%VDE-I-OUTFILE, output file is DEV$:[MYDIR]MODULE_E.B32;M%VDE-I-RESERVED, generation [RMS]MODULE_E.B32;1(1) reserved from stream BIRCHE%VDE-I-EXPGENEXPR, expected generation expression at replacement is 2>%VDE-I-COMMIT, database transaction has successfully committedVSC> 

EThis RESERVE command creates a concurrent reservation for the module Fbecause it contains the /OVERRIDE=CONCURRENT qualifier. It also sends Bmail to user HOFFMAN to notify HOFFMAN that you just concurrently reserved the module.

FWhen you reserve a module, you can specify that you do not want other Hdevelopers to create concurrent reservations for that module. To do so, 7use the /NOCONCURRENT qualifier on the RESERVE command:

 

" >VSC> RESERVE/NOCONCURRENT [RMS]MODULE_E.B32 "Remark string" 

AThis qualifier causes the source control system to reject future Hattempts to create reservations that are concurrent with this one until Dyou replace the module into the library or unreserve it. If you are Dabout to make complicated changes to a module, you can thus prevent Gothers from concurrently reserving that module. Normal usage, however, Gis to omit this qualifier and to allow concurrent reservations in case @they are needed in an emergency. You can change a reservation's ;noconcurrent attribute with the MODIFY RESERVATION command.;

2.2.2 Queued Reservations

2VSC and VSC support queued reservations. When you Cqueue a reservation request, the source control system records the Dqueued reservation in its database, pending the availability of the Fspecified module. When the developer who owns the current reservation Glater replaces the module into the library or cancels the reservation, 7VSC sends a mail message to each user who has queued a #reservation request for the module.

FThe queued reservation request mail message indicates that the module Bis now available for reservation, and it lists all users who have Frequested it, in the order the requests were posted. The users listed Cin the message must decide among themselves who should reserve the module first.

CTo actually reserve the module, one must enter an explicit RESERVE command.

BIn addition to displaying other reservation information, the SHOW 5RESERVATION command displays all queued reservations.U

2.3 Creating New Modules

=To create a new source module, use the CREATE MODULE command:

 

" JVSC> CREATE MODULE [FACIL]MOD.TYP /STREAM=BIRCH /REMARK="Remark string" 

GThis command records the new module in the source control database and Fcreates a reservation for the module in the specified stream. It does Gnot create the first generation of the module, however. You must use a Hsubsequent REPLACE command to actually create the initial generation of the module.

GYou can create multiple modules with a single CREATE MODULE command by 6specifying a list of module names separated by commas.

:VDE also allows you to associate a number of modules from Bvarious RESERVE and CREATE MODULE commands together, by using the E/SESSION qualifier. The /SESSION qualifier allows you to pick a name Ffor a group of modules, and to avoid having to specify each module on Ethe 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.

CIf you should mistakenly create a module under an incorrect module Bname, or should you create a module that becomes unnecessary, you Ccan---prior to module replacement---issue a DELETE MODULE 2command. The DELETE MODULE command will cancel theHreservation, and will correctly back out the CREATE MODULE command. For ?further details on this, see the VDE Reference Manual.

HThe CREATE MODULE command accepts a number of qualifiers. The help text Cand the reference manual have the details on all of the qualifiers jaccepted by the command. Table 2-2 lists some of the more commonly-used qualifiers.

t                                    

Table 2-2 Qualifiers to the CREATE MODULE command

 /LOG  /NOLOG
	I Specify whether informational log messages are printed after each M module is created. /LOG causes such messages to be printed and /NOLOG , suppresses them. /LOG is the default.
/MARKER /NOMARKER
	N Specify that the module is a "marker file". A marker file is N any binary, image, saveset, or library file that should not stored via  the normalJ delta mechanism used within the CMS library, but should be I stored as a seperate module in the marker file directory (see SHOW K DIRECTORY/DELTA). This setting avoids having extensive delta-related 1 processing and storage overhead between one % % % : generation of a binary module and the next.
' /REMARK="string"
	L Specifies a one-line remark string to be associated with the module. M 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
	N /SESSION allows you to associated various reserved and created modules L together into a session; sessions allow you to later replace a whole L series of reserved and created modules via a single REPLACE command. N When used with the queued-replacement environment, the use of sessions L also provides a clear indication to the reviewers and to the project M leader that the modules being replaced are associated. The particular N session name used is typically a mnemonic name chosen by the user, and A usually reflects the particular set of changes being made.
* /STREAM=stream-name
	O Specifies the development stream from which the new module is reserved. TheN stream-name parameter gives the name of the stream. If J this qualifier is omitted, the module is reserved from your default 2 development stream, provided one is defined.



<Examples


0This is an example of the CREATE MODULE command:

 

" VSC> SET STREAM PHOENIXDVSC> CREATE MODULE [FACNAM]NEWMOD.C /REMARK="Update widget table"I%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 committedVSC> 

EThis example makes stream PHOENIX the default development stream and Dthen creates the new module NEWMOD.C in facility FACNAM. The CREATE BMODULE command adds the module to the source control database and Greserves it from the default stream. A subsequent REPLACE command (not Eshown) is needed to create the first generation of the module in the library.O

2.4 Fetching Modules

@To fetch an existing module without reserving it, use the FETCH command. For example:

 

" 'VSC> FETCH/STREAM=FOO [FACIL]MOD.TYP 

CThis command copies the latest generation for stream FOO of module 4MOD.TYP in facility FACIL to your default directory.

HThe FETCH command accepts multiple module names separated by commas and Eaccepts the asterisk (*) and percent sign (%) wildcard characters in @the module-name parameters. Those modules whose names match the wildcard patterns are fetched.

GYou can specify the specific generation you want to fetch in two ways. HOne way is to specify a generation number preceded by a semicolon after Hthe module name. For example, MOD.TYP;5 refers to absolute generation 5 Efor the specified development stream. MOD.TYP;0 refers to the latest Hgeneration of the module in the specified stream and MOD.TYP;--1 refers Fto generation --1 relative to the latest generation in the stream (in Gother 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 D"generation expression" of the desired generation. If you Cspecify neither a generation number nor the /GENERATION qualifier, 8VSC fetches the latest generation for the specified (or default) development stream.

FIn addition to the /GENERATION qualifier, the FETCH command accepts a Asubset of the RESERVE command qualifiers. The FETCH command also Haccepts an optional quoted remark parameter for compatibility with CMS, Dbut since there is no reason to record fetch operations, the remark string is simply discarded.

HThe FETCH command accepts a number of qualifiers. The help text and the Dreference manual have the details on the qualifiers accepted by the jcommand. Table 2-3 contains some of the more commonly-used qualifiers.

k                             

Table 2-3 Qualifiers to the FETCH command

/CONFIRM ! /NOCONFIRM  /LOG  /NOLOG  /OUTPUT  /STREAM
	& Same as for the RESERVE command.
+ /GENERATION=gen-expr
	H Specifies that the module generation be fetched that has the CMS ) generation expression given by theG gen-expr parameter. This expression is also the M generation's audit trail identifier. If this qualifier is omitted, the K command fetches the generation given by the generation number on the N module-name parameter. If both this qualifier and the generation number I are omitted, the command fetches the most recent generation of the 1 module in the specified development stream.
* /HISTORY[="string"] ! /NOHISTORY
	L Determine whether CMS history information is included in the fetched M source module. /HISTORY causes CMS history information to be included I in the output file and /NOHISTORY suppresses such information. If M neither qualifier is specified, the history attribute for each module L determines whether history information is included. For OpenVMS VAX, 4 history information is turned off by default.
( /NOTES[="string"]  /NONOTES ( /POSITION=col-num
	J Determine whether CMS notes information is included in the fetched L source module. /NOTES causes CMS notes information to be included in N the output file and /NONOTES causes such information to be omitted. If L CMS notes are included, the /POSITION qualifier specifies the column N number of the notes text. If neither /NOTES nor /NONOTES is specified, H the notes attribute for each module determines whether notes are B included. For OpenVMS VAX, notes are turned off by default.



:Examples


(This is an example of the FETCH command:

 

" VSC> FETCH A.REQD%VDE-I-FETCHED, generation [FACNAM]A.REQ;3(2A1) fetched from library1%VDE-I-OUTFILE, output file is DEV$:[MYDIR]A.REQ;VSC> 

EThis example fetches generation 3 (for the default stream) of module EA.REQ in facility FACNAM. The generation's CMS generation expression 7(and audit trail identifier) is 2A1. VSC places a file 5containing that generation in your default directory.

EThe following example fetches two modules, C.B32 in facility SYS and <D.B32 in facility BAD, and copies them to directory [MYDIR]:

 

" MVSC> 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 library1%VDE-I-OUTFILE, output file is DEV$:[MYDIR]C.B32;A%VDE-I-FETCHED, generation [BAD]D.B32;5(3A2) fetched from library1%VDE-I-OUTFILE, output file is DEV$:[MYDIR]D.B32;VSC> 



HThe command fetches the latest generation of C.B32 for stream V4.4, and Fit fetches the generation of D.B32 that has CMS generation expression 3A2.R

2.5 Unreserving Modules

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

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.

EThe UNRESERVE command accepts wildcard characters in the module-name Dparameter. Those modules whose names match the wildcard pattern are Eunreserved. The command also accepts multiple module-name parameters separated by commas.

FThe optional remark string parameter specifies a remark that explains Cwhy 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 tqualifiers (see Table 2-5). The following qualifiers have the same ;meanings as for the REPLACE command: /CONFIRM, /NOCONFIRM, 6/IDENTIFICATION, /LOG, /NOLOG, /STREAM, and /USERNAME.U

2.6 Displaying Reservations

EOnce a reservation has been entered into the source control system's Hdatabase, you can display it with the SHOW RESERVATION command. This is a typical example:

 

" 'VSC> SHOW RESERVATION [FACIL]MOD.TYP 

HThis command shows all reservations and queued reservation requests for Bmodule MOD.TYP in facility FACIL. If the module-name parameter is Comitted, the command displays all reservations for modules in your default facility.

FThe SHOW RESERVATION command accepts a list of module names separated Aby commas, and you can use the asterisk (*) and percent sign (%) Fwildcard characters in the module names. All reservations for modules /that match the wildcard patterns are displayed.

FThe SHOW RESERVATION command accepts a number of qualifiers. The help Htext and the reference manual have the details on all of the qualifiers raccepted by the command. Table 2-4 describes a number of the more commonly-used qualifiers.

w                                                         

Table 2-4 Qualifiers to the SHOW RESERVATION command

( /BEFORE=date-time
	N Displays only those reservations created before the specified date and  time.
/BRIEF  /FULL
	I Determine the type of information displayed for each reservation. L /BRIEF displays the reservation identifier, the name of the reserved O module, the reserving user, the date of the reservation, and the stream J in which the module is reserved. This display normally fits on one L line. /FULL displays all database information about the reservation; J this display requires several lines per reservation. /BRIEF is the  default.
/NOQUEUE
	L Specifies that queued reservation requests not be displayed. If this J qualifier is omitted, the command displays both queued reservation ( requests and normal reservations.
' /OUTPUT=filespec
	J Directs the printed output of this command to a specified file. TheJ filespec parameter specifies the name of the file. C VSC creates a new file with that name, directs the command's N 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
	O Displays only those reservations created on or after the specified date  and time.
, /STREAM[=stream-name]
	N Displays only those reservations made for the development stream given by the4 stream-name parameter. If theJ stream-name parameter is omitted, the command only G displays those reservations made for your default stream. If the B /STREAM qualifier is omitted entirely, the command displays # reservations for all streams.
/TOTAL
	N Shows the total number of reservations that match the specified module O names, usernames, and other constraints. Only the total count is shown; H other information about the individual reservations is not shown.
+ /USERNAME[=username]
	G Specifies the OpenVMS user name for the user whose reservations A are to be shown. If this qualifier is specified, VSC only 0 displays that user's reservations. If the? username parameter is omitted, VSC only I displays your own reservations. If the whole qualifier is omitted, . VSC displays reservations for all users.



9Examples


GThis is an example of the brief output of the SHOW RESERVATION command:

 

" VSC> SHOW RESERVATIONJReservation 1 of [FACIL]FOO.MAR SMITH 18-NOV-1990 BIRCHLReservation 1 of [FACIL]FUMBLE.MAR JONES 5-SEP-1990 PHOENIXLQueued reservation 2 of [FACIL]FUMBLE.MAR MURGATROID 21-NOV-1990 PHOENIXMReservation 1 of [FACIL]SCRAMBLE.B32 SMITH 31-OCT-1990 MUSHROOMVSC> 



DThe following example shows the full output of the SHOW RESERVATION command for one reservation:

 

" ,VSC> SHOW RESERVATION/FULL [FACIL]FOO.MARReservation 1 of [FACIL]FOO.MAR1 Reservation created on 18-NOV-1990 10:39:54.311 Reservation created by user SMITH (Jane Smith)0 Generation 15 (15) reserved from stream BIRCHO Expected generation expression at replacement is 16 (audit trail identifier)& Concurrent reservations are allowed Remark: Fix QAR 23 again VSC>