When you replace a module, you make your new source file the most recent generation of the module in the specified (or default) development stream. That instance of the module is thus the generation you get by default in a subsequent FETCH or RESERVE command and is the generation that is built for that stream.

If the specified stream has successors, VSC propagates the new module generation to all successor streams if possible. For example, if stream V5.4 is a successor of stream V5.3, then any module that is replaced into stream V5.3 is also replaced in stream V5.4 automatically. If stream V5.4 has additional successors (such as stream V5.5), the new module generation is propagated to those streams, and so on recursively.

Change propagation works as follows. If the latest generations of the module for the original development stream and the successor stream are the same, then the new module instance being replaced becomes the latest generation for both streams. Both streams are thus equally up-to-date with respect to the changes made to that module. However, if the latest generations of the module differ for the two streams, which means that the module has already diverged between those two streams, the source control system does not propagate the new module generation to the successor stream. Instead, it creates a fold record in the database to remind the developer that the change made to the module for the first stream must be manually "folded" into the successor stream.

You display fold records with the SHOW FOLD command. This example shows the brief output of the command:

VSC> SHOW FOLD *.MAR Fold 1 of [FACIL]FOO.MAR;29(27B2) into stream V5.4 23-MAR-1989 SMITH Fold 2 of [FACIL]BAR.MAR;2(1A1) into stream V5.5 24-MAR-1989 JONES VSC>

Each fold record is identified by a fold identifier. This identifier is a unique, small integer value that VSC assigns when creating the fold record.

The following example shows the full output of the SHOW FOLD command for one fold record:

VSC> SHOW FOLD/FULL FOO.MAR Fold 1 of [FACIL]FOO.MAR;29(27B2) Module to be folded from stream V5.3 into stream V5.4 Reservation performed by user SMITH (Jane Smith) Reservation performed on 23-MAR-1989 18:09:51.80 Replacement performed on 25-MAR-1989 20:29:05.23 Remark: Fix QAR 23 again VSC>

The normal way to remove fold records is to specify the /FOLD qualifier with the REPLACE command that replaces the folded source file. This is an example:

VSC> REPLACE/STREAM=V5.4 [FACIL]FOO.MAR/FOLD=2

This example replaces module FOO.MAR into stream V5.4 to propagate a change that VSC could not automatically propagate. The parameter to the /FOLD qualifier (the value "2") is the fold identifier of a fold record to delete as part of the replacement. This parameter can be omitted if the module only has one outstanding fold record. For queued replacements, VSC deletes the fold record when the release project leader performs your replacement.

You can also delete a fold record that is no longer needed (possibly because the change is no longer required) with an explicit CANCEL FOLD command:

VSC> CANCEL FOLD [FACIL]FOO.MAR/IDENTIFICATION=2/STREAM=BIRCH

This command deletes fold record 2 (as given by the /IDENTIFICATION qualifier) for module FOO.MAR in facility FACIL. This fold record is a reminder to fold a change into stream BIRCH. If there is only one fold record for the given module and stream, you can omit the /IDENTIFICATION qualifier.

2.9 Displaying Queued Replacements

Once the REPLACE command has entered a queued replacement into the source control system's database, you can display the replacement with the SHOW REPLACEMENT command. This example illustrates the command's syntax:

VSC> SHOW REPLACEMENT SMITH-1

This command displays all queued replacements specified by the replacement name parameter (SMITH--1 in the example). If the replacement name is omitted, the command displays all queued replacements.

With the SHOW REPLACEMENT command, you can specify a list of replacement names separated by commas, and you can use the asterisk (*) and percent sign (%) wildcard characters. All queued replacements that match the wildcard patterns are displayed.

The SHOW REPLACEMENT 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-6 lists some of the more commonly-used qualifiers.

Table 2-6 Qualifiers to the SHOW REPLACEMENT command

/ACCEPTED
	Specifies that only those replacements that have been accepted by all their reviewers be displayed.
/BEFORE=date-time
	Displays only those replacements queued before the specified date and time.
/BRIEF /FULL
	Determine the type of information displayed for each replacement. /BRIEF displays the replacement name, the date of the replacement, the replacing user, and the replacement status. This display normally fits on one line. /FULL displays all information about the replacement stored in the database; this display requires multiple lines per replacement.
/IN_REVIEW
	Specifies that only those replacements that are in review be displayed. A replacement is in review if it has not been rejected by any reviewer, has been accepted by at least one reviewer, and has not yet been accepted by all reviewers.
/NOT_REVIEWED
	Specifies that only those replacements that have not yet been accepted or rejected by any reviewers be displayed.
/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.
/REJECTED
	Specifies that only those replacements that have been rejected by at least one reviewer be displayed.
/REVIEWER[=username]
	Specifies that only those replacements for which the specified user is a reviewer be displayed. The username parameter specifies the OpenVMS user name of the reviewer whose replacements are to be shown. If the username parameter is omitted, those replacements for which you are a reviewer are shown. If the qualifier is omitted entirely, replacements for all reviewers are shown.
/SINCE=date-time
	Displays only those replacements queued on or after the specified date and time.
/STREAM[=stream-name]
	Displays replacements for the development stream given by the stream-name parameter. If this parameter is omitted, the command displays replacements for your default development stream. If the /STREAM qualifier is omitted entirely, the command displays replacements for all development streams.
/TOTAL
	Shows the total number of replacements that match the specified replacement names and other selection criteria. Only the total count is shown; other information about the individual replacements is not shown.
/USERNAME[=username]
	Specifies the OpenVMS user name of the user whose replacements are to be shown. If this qualifier is specified, only that user's replacements are shown. If the username parameter is omitted, only your own replacements are shown. If the /USERNAME qualifier is omitted entirely, replacements for all users are shown.

Examples

This is an example of the brief output of the SHOW REPLACEMENT command:

VSC> SHOW REPLACEMENT SMITH-5 Queued replacement SMITH-5 23-MAR-1989 SMITH Rejected Queued replacement JONES-3 24-MAR-1989 JONES Not reviewed VSC>

The following example shows the full output of the SHOW REPLACEMENT command for one queued replacement. Note that this output lists all modules that belong to the replacement and all reviewers for the replacement.

VSC> SHOW REPLACEMENT/FULL SMITH-5 Queued replacement SMITH-5 Replacement queued by user SMITH (Jane Smith) Replacement queued on 4-OCT-1990 16:55:02.06 Replacement staging directory is VSC$STAGEDISK:[VMS.STAGE.VDE$STG_1.VDE$REP_115] Replacement review status: Rejected Replacement is for stream PHOENIX Unique replacement number is 115 Reservations in replacement: Reservation 1 of [FACIL]FOO.MAR for stream PHOENIX Reservation 1 of [RMS]FUMBLE.B32 for stream PHOENIX Replacement contains 2 reservations Reviewers for replacement: Accepted by user HOFFMAN (Bill Hoffman) on 4-OCT-1990 17:08:03.08 Rejected by user JONES (Jim Jones) on 4-OCT-1990 17:08:03.08 Remark: Bad choice of variable name Not reviewed by SNURD (Mortimer Snurd) Remark: Fix bad-status bug VSC>

2.10 Cancelling Queued Replacements

If you decide that a replacement you queued should not be performed, you can cancel that replacement with the following command:

VSC> CANCEL REPLACEMENT SMITH-1

This command removes the queued replacement specified by the replacement name parameter (SMITH--1) from the source control system's database. The original module reservations associated with the cancelled replacement remain in the database. The typical reason for cancelling a replacement is that you or a reviewer found something wrong with the code to be replaced. After fixing the erroneous code, you can queue a new replacement with another REPLACE command.

With the CANCEL REPLACEMENT command, you can specify a list of replacement names separated by commas, and you can use the asterisk (*) and percent sign (%) wildcard characters in the names. The command deletes all queued replacements that match the wildcard pattern.

The CANCEL REPLACEMENT command accepts a number of qualifiers. The help text and the reference manual contain the details on the qualifiers accepted by the command. Table 2-7 lists the more commonly-used qualifiers.

Table 2-7 Qualifiers to the CANCEL REPLACEMENT command

/CONFIRM /NOCONFIRM
	/CONFIRM asks you to confirm that you want each replacement deleted. This qualifier is particularly useful if you use wildcard characters in the replacement name. /NOCONFIRM deletes each replacement without asking for confirmation. /NOCONFIRM is the default.
/LOG /NOLOG
	Specify whether informational log messages are printed after the replacement is deleted. /LOG causes such messages to be printed and /NOLOG suppresses them. /LOG is the default.

This chapter tells you how to display information stored in the OpenVMS source control database. Earlier sections have already described how you display module reservations ( Section 2.6), fold records ( Section 2.8), and queued replacements ( Section 2.9). This chapter describes how to display information about facilities, modules, module generations, development streams, and the users of the source control system.

3.1 Displaying Facilities

The SHOW FACILITY command lists information about the facilities into which the OpenVMS sources are divided. For example:

VSC> SHOW FACILITY FACNAM

This example displays information about facility FACNAM. If the facility name is omitted, the command displays information about all facilities in the current library. With this command, you can specify a list of facility names separated by commas, and you can use the asterisk (*) and percent sign (%) wildcard characters in the facility names. All facilities that match the wildcard patterns are displayed.

Table 3-1 lists the qualifiers for the SHOW FACILITY command and describes their functions.

Table 3-1 Qualifiers to the SHOW FACILITY command

/BRIEF /NORMAL /FULL
	Determine the type of information displayed for each facility. /BRIEF displays the name of each facility that matches the facility-name parameters. /NORMAL displays the name and remark string for each facility; this is the default output. /FULL displays all attributes of each facility, including its name, creation date and time, and remark string.
/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.
/TOTAL
	Shows the total number of facilities that match the specified facility-name parameters. Only the total count is shown; other information about the individual facilities is not shown.

Examples

This is an example of the normal output of the SHOW FACILITY command:

VSC> SHOW FACILITY B* Facility BACKUP "BACKUP facility Facility BAD "Michael Jackson facility" Facility BADBLK "Bad-block faciility" Facility BASRTL "BASIC Run-Time Libary facility" Facility BLAS1 "Blasphemous facility" Facility BOOTS "OpenVMS boot facility" VSC>

The following is an example of the brief output of the SHOW FACILITY command:

VSC> SHOW FACILITY/BRIEF B* Facility BACKUP Facility BAD Facility BADBLK Facility BASRTL Facility BLAS1 Facility BOOTS VSC>

The following example shows the full output of the SHOW FACILITY command for one facility:

VSC> SHOW FACILITY/FULL SYS Facility SYS Facility added to database on 19-OCT-1990 10:38:05.44 Facility added to database by user SMITH (Jane Smith) Facility cannot be deleted Remark: OpenVMS Executive modules VSC>

This example shows the effect of the /TOTAL qualifier:

VSC> SHOW FACILITY/TOTAL * Number of facilities matching name *: 228 VSC>

3.2 Displaying Modules

The SHOW MODULE command lists information about the modules under source control. For example:

VSC> SHOW MODULE [FACIL]MOD.TYP

In this example, VSC displays information about module MOD.TYP in facility FACIL. If the facility name is omitted, the current default facility is assumed. If the whole module-name parameter is omitted, information about all modules in the default facility is shown.

With the SHOW MODULE 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 displayed.

Table 3-2 lists the qualifiers for the SHOW MODULE command and describes their functions.

Table 3-2 Qualifiers to the SHOW MODULE command

/BRIEF /NORMAL /FULL
	Determine the type of information displayed for each module. /BRIEF displays the name of each module that matches the module-name parameters. /NORMAL displays the name and remark string for each module; this is the default output. /FULL displays all attributes of each module, including its name, creation date and time, CMS history and notes attributes, reviewer and notify lists, and remark string.
/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.
/STATISTICS=(keyword [, keyword...])
	Computes and displays certains statistics about the modules that match the module-name parameters. The keyword parameters specify what statistics to display and how to sort them. The qualifier accepts the following keyword parameters: ALPHABETICALLY---Sort the display alphabetically by facility name or type name. If this keyword is omitted, VSC sorts the display in descending order by module count. FACILITY---Compute and display the number of modules in each facility. TYPES---Compute and display the number of modules that have each module type. If you specify only one of these keywords, the surrounding parentheses can be omitted.
	When this qualifier is used, other information about the individual modules is not shown. Use wildcard characters in the module-name parameters to select the module population for which you want statistics.
/TOTAL
	Shows the total number of modules that match the specified module-name parameters. Only the total count is shown; other information about the individual modules is not shown.

Examples

This is an example of the normal output of the SHOW MODULE command:

VSC> SHOW MODULE [ADARTL]PPLSS_* Module [ADARTL]PPLSS_DISPATCH.MAR "SS dispatcher" Module [ADARTL]PPLSS_KERNEL_WORKER.B32 "Kernel worker" Module [ADARTL]PPLSS_RESET.MAR "Cleanup routine" Module [ADARTL]PPLSS_SERVICES.MAR "Service entry points" Module [ADARTL]PPLSS_TABLE.B32 "Sys Service definitions" Module [ADARTL]PPLSS_TABLE.REQ "Sys Service definitions" Module [ADARTL]PPLSS_USER_WORKER.B32 "User mode worker routines" VSC>

The following is an example of the brief output of the SHOW MODULE command:

VSC> SHOW MODULE/BRIEF Module [FACIL]FOO.BAR Module [FACIL]MOD1.FOR Module [FACIL]MOD2.FOR Module [FACIL]MOD3.FOR Module [FACIL]MOD4.FOR Module [FACIL]MOD5.FOR Module [FACIL]MOD6.FOR VSC>

The following example shows the full output of the SHOW MODULE command for one module:

VSC> SHOW MODULE [FACIL]MOD1.FOR/FULL Module [FACIL]MOD1.FOR Module added to database on 4-APR-1989 14:58:39.66 Module added to database by user SMITH (Jane Smith) Module is a source module Module cannot be deleted Module may be concurrently reserved History information is not provided by default History string: C #B Notes information is not provided by default Notes string: ! #G Note position: 81 Reviewers: JONES, SNURD Users to notify: MERMAN Remark: Test module VSC>

This example shows the effect of the /TOTAL qualifier:

VSC> SHOW MODULE/TOTAL [RMS]* Number of modules matching name [RMS]*.*: 236 VSC>