| Previous | Contents | Index |
After you have reserved a module and changed it, you need to build it, test it, and replace it onto the OpenVMS VAX library. This chapter describes how you replace modules back onto the OpenVMS VAX library after you have changed, built, and tested them as appropriate.
You use the REPLACE command to copy a new or changed module from your default directory (or another directory you specify) into the specified library. Before you can use the REPLACE command for a module, you must first reserve the module with the RESERVE command or create the module with the CREATE MODULE command. The REPLACE command replaces the module into the development stream you specify and automatically propagates the change to that stream's successors. The following example shows how to use the REPLACE command:
VSC> REPLACE/STREAM=FOO [FACIL]MOD.TYP "Remark string" |
With the REPLACE command, you can specify a list of module names separated by commas, and you can use the asterisk (*) and percent sign (%) wildcard characters in the module names. All modules that match the wildcard patterns are replaced.
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 you can avoid having to specify each individual 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.
Optionally, you can specify a remark string 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-5 and applies to all modules being replaced unless overridden by /REMARK qualifiers on the individual module-name parameters. If you do not specify a remark, VSC prompts you for it. If you then enter a null remark string, VSC uses the remark from your original RESERVE command.
The REPLACE command also asks you for the cause that is the reason or justification for the the replacement. The reason can be a fold record, a Source Control Tracking (SCT) entry, or other cause. If the reason is specified by an SCT entry, VSC allows several options: it can enter the SCT note for you, it can ask you for the number of a pre-existing SCT entry, and it allows you to edit the SCT note during the replacement. VSC also asks for any related QARs (Quality Assurance Reports) or CLDs (urgent customer problems). The following partial example shows how you specify the SCT entry and problem reports associated with a replacement:
VSC> REPLACE/STREAM=FOO [FACIL]MOD.TYP(1) Enter the replacement remark: example replacement command (2) General type of replacement: FO : Fold; see original change for info, SC : SCT; See Source Code Tracking Note, OT : Other; replacement made for other reason(s) Type of replacement? sct(3) Reason(s) for making this change (from the SCT note): BF : Bug Fix, NF : New Feature/Enhancement, PI : Performance Improvement, CS : Common Sources, CU : Cleanup/Retrofit/Regression, NH : New Hardware Support, FE : Functional Equivalence, OT : Other What was the reason for the change: bf(4) How many defects -- errors from any and all sources: design, coding, spelling, logic, etc. -- did this replacement repair? Number of defects: 2(5) Enter name of SCT conference [SCT-FOO]:(6) Enter SCT project name or [RETURN] for list: VORLON(7) Enter file to load into SCT: (filename/EDIT/NOTE) sys$login:sct.txt(8) %VDE-I-NOTEID, note 21.0 entered in conference(9) Please specify related QARs and CLDs, if applicable: Enter name of QAR database (or [RETURN] if none): QAR-DB-NAME(10) Enter QAR number: 13(11) Enter name of QAR database (or [RETURN] to end list):(12) Enter the CLD number (or [RETURN] if none): CLD-12345(13) Enter the CLD number (or [RETURN] to end list): (14) |
When you use the REPLACE command to replace a module into a normal OpenVMS VAX development stream, VSC does not immediately replace the module into the library, and it does not immediately cancel your reservation on the module. Instead, it queues the module for replacement at a later time when the release project leader for the stream allows the actual replacement to take place. The release project leader normally will not allow the actual replacement to proceed until your replacement has been reviewed.
When the REPLACE command queues your replacement (also called creating a queued replacement), it performs the following operations:
VSC queues the module replacement request into the VDE database for review, and notifies the release project leader. Once the changes are reviewed, the release project leader then uses the PERFORM REPLACEMENT command to accept the replacement. Once the replacement has been accepted, the pending modification request will be dequeued and the modification will be committed into the VDE database. You will typically receive a mail message from VSC when your replacement has been performed. See Chapter 4 and Section 5.1 for information on the VSC commands used by reviewers and by project leaders, respectively.
For some development streams, the VSC utility performs immediate replacements. An immediate replacement updates the library---you guessed it---immediately. When you enter the REPLACE command, the module is copied into the library. OpenVMS VAX does not typically permit immediate replacements into its major development streams, but might allow them for selected off-to-the-side development streams used by small numbers of developers. Whether the REPLACE command performs a queued or immediate replacement is thus a property of the development stream you are replacing modules into. If any development stream affected by the replacement (directly or through change propagation) requires queued replacements, the replacement is queued.
A disadvantage of immediate replacements is that they do not create staging areas, which can prevent recovery of lost generations after a VDE failure.
The REPLACE 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-5 lists the more commonly-used qualifiers.
|
/CONFIRM
/NOCONFIRM |
|
| /CONFIRM asks you to confirm that you want each module replaced. This qualifier is particularly useful if you use wildcard characters in the module name. /NOCONFIRM replaces each module without asking for confirmation. /NOCONFIRM is the default. | |
| /DEFECT=defect-count | |
| Specifies the number of defects the particular replacement remedied. Defects counted include spelling errors, run-time errors, design errors, etc. This qualifier is applicable only to changes with bug-related reason codes. | |
|
/FOLD[=fold-ident] |
|
| Specifies that the fold record identified by the fold-ident parameter be deleted from the database when the present replacement completes. If this qualifier is omitted, no fold record is cancelled. (See Section 2.8 for a discussion of fold records.) | |
| /IDENTIFICATION=res-ident | |
| Specifies the reservation to be replaced. This qualifier is required only when you have multiple concurrent reservations of the same module. The res-ident parameter is the reservation identifier of the reservation to be replaced. This is the reservation identifier that you specified or the source control system assigned when you reserved the module; it is usually a small integer value. | |
|
/INFORMATION[=filespec]
/NOINFORMATION |
|
| /INFORMATION specifies that additional information about the current queued replacement is found in the text file specified by the filespec parameter. This information might include instructions or advice that the release project leader should read before performing the queued replacement. It might also include information for your reviewers. The information file is copied to the replacement's staging area and is discarded once the replacement is performed. | |
| If the filespec parameter is omitted, you are placed in an editing session to create the information file. If the /NOINFORMATION qualifier is specified, no information file is attached to the replacement. If neither qualifier is specified for a queued replacement, you are asked whether you want to edit an information file. These qualifiers are ignored for immediate replacements. | |
| /INPUT=filespec | |
| Specifies the source file to be used as input for the replacement. If you omit the directory specification from the filespec parameter, the file is taken from your default directory. If you omit the file name or file type, the module name and module type are used by default. If you omit the /INPUT qualifier entirely, the file is taken from your default directory and must have the same file name and type as the module. | |
|
/LOG
/NOLOG |
|
| Specify whether informational log messages are printed after each module is replaced or queued for replacement. /LOG causes such messages to be printed and /NOLOG suppresses them. /LOG is the default. | |
| /NOTE=sct-note-number | |
| Specifies the number of a previously-entered SCT note in the SCT notes conference. When specified, VSC uses the default name for the SCT notes conference. If omitted, VSC will prompt for the SCT-related information. | |
| /OTHER="other reason" | |
| Specifies that the replacement is not associated with an SCT entry or a FOLD record, and includes the reason why. | |
| /PROJECT=project-name | |
| /PROJECT specifies the project name with which the replacement is associated. The project is used for statisitical purposes, and the project name is used in conjunction with the remark text as the title used for any SCT note entered by VSC. | |
|
/PROPAGATE=stream-name
/NOPROPAGATE |
|
|
/PROPAGATE specifies that the module changes being replaced should be
propagated to all successors of the initial development stream up to
and including the stream specified by the
stream-name parameter. Changes cannot be propagated
further than specified on the original RESERVE command, however.
/NOPROPAGATE specifies that the changes not be propagated past the
initial development stream. If neither qualifier is specified,
VSC propagates the changes as far as requested on the
original RESERVE command, which by default propagates changes to all
successors (recursively) of the current stream. See Section 2.8 for
more detail on change propagation.
For OpenVMS VAX, most replacements should use the default propagation behavior and you should seldom need these qualifiers. |
|
| /REASON=reason-code | |
| Specifies the reason code for the replacement. Typically associated with an SCT entry. Bug-related reason codes require the specification of the number of defects corrected. | |
| /REMARK="string" | |
| Specifies a one-line remark string to be associated with the replacement. If this qualifier and the remark parameter are omitted, you are prompted for a replacement remark. If you enter a null replacement remark, VSC uses the remark string from each module's reservation. The project name and the remark text are used as the title for any SCT note entered by VSC. | |
| /REPLACEMENT=repl-name | |
| Specifies the name of the queued replacement if the replacement is queued. (This qualifier is ignored for immediate replacements.) If a queued replacement by that name already exists, VSC appends the specified modules to that queued replacement. Otherwise, VSC creates a new queued replacement by that name. If this qualifier is omitted, VSC creates a new queued replacement and assigns it a unique replacement name based on your OpenVMS user name. | |
| /REVIEWER=(username [, username...]) | |
| Specifies the users who should review this replacement. Each username parameter specifies the OpenVMS user name of one reviewer for the replacement. Each such reviewer is automatically notified with a mail message. These reviewers are expected to review the changes that make up the current replacement as described in Chapter 4. | |
| /SCT=sct-file-name | |
| Specifies the SCT note to be entered into the SCT notes conference. When specified, VSC uses the default name for the SCT notes conference. If omitted, VSC will prompt for the SCT-related information. | |
| /SESSION=session-name | |
| /SESSION allows you to replace a number of reserved and created modules together with a single command, and allows you to avoid specifying each module on the 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 when the CREATE MODULE or RESERVE command is issued, and usually reflects the particular set of changes being made. | |
| /STREAM=stream-name | |
| Specifies the development stream in which the modules to be replaced are currently reserved and into which they should be replaced. The stream-name parameter gives the name of the stream. If this qualifier is omitted, VSC replaces the modules into your default development stream. | |
| /USERNAME=username | |
| Specifies that the modules should be replaced on behalf of the user whose OpenVMS user name is given by the username parameter. You must have a VSC privilege (USERNAME) to use this qualifier; it is meant for release project leaders and others who manage the OpenVMS libraries, and is intended only be used in unusual or special situations. | |
In the following example of a queued replacement, user HOFFMAN replaces module FOO.MAR into facility SYS in development stream PHOENIX:
VSC> REPLACE/STREAM=PHOENIX [SYS]FOO.MAR Enter the replacement remark: example replacement command General type of replacement: FO : Fold; see original change for info, SC : SCT; See Source Code Tracking Note, OT : Other; replacement made for other reason(s) Type of replacement? sctReason(s) for making this change (from the SCT note): BF : Bug Fix, NF : New Feature/Enhancement, PI : Performance Improvement, CS : Common Sources, CU : Cleanup/Retrofit/Regression, NH : New Hardware Support, FE : Functional Equivalence, OT : Other What was the reason for the change: bf How many defects -- errors from any and all sources: design, coding, spelling, logic, etc. -- did this replacement repair? Number of defects: 1 Enter name of SCT conference [SCT-PHOENIX]: Enter SCT project name or [RETURN] for list: BUCKAROO Enter file to load into SCT: (filename/EDIT/NOTE) sys$login:sct.txt %VDE-I-NOTEID, note 41.0 entered in conference Please specify related QARs and CLDs, if applicable: Enter name of QAR database (or [RETURN] if none): Enter the CLD number (or [RETURN] to end list): %VDE-I-FILCOPSTAG, file DEV$:[HOFFMAN]FOO.MAR;3 copied to staging area %VDE-I-REPLQUE, module [SYS]FOO.MAR queued for replacement HOFFMAN-1 %VDE-I-COMMIT, database transaction has successfully committed Do you want to edit an information file for replacement HOFFMAN-1 ? [No]: NO VSC> |
In the following example of an immediate replacement, module MOD.TYP in facility FACIL is replaced into development stream TOM:
VSC> REPLACE/STREAM=TOM [FACIL]MOD.TYP "Remark string"/NOTE=321 Type of entry to cause replacement (FOLD, SCT, OTHER): SCT Please specify related QARs and CLDs if applicable: Enter name of QAR database (or RETURN if none): V54-FT Enter QAR number: 35 Enter name of QAR database (or RETURN to end list): Enter the CLD number (or RETURN if none): APO-12345 Enter the CLD number (or RETURN to end list): %VDE-I-FILCOPLIB, file DEV$:[MYDIR]MOD.TYP;12 copied to library %VDE-I-REPLACED, generation [FACIL]MOD.TYP;4(4) replaced into stream TOM %VDE-I-REPLACED, generation [FACIL]MOD.TYP;4(4) replaced into stream JERRY %VDE-I-COMMIT, database transaction has successfully committed VSC> |
| Previous | Next | Contents | Index |