The SHOW GENERATION command lists historical and differential information about the module generations present in the current library. For example:

VSC> SHOW GENERATION [FACIL]MOD.TYP

This example displays information about the latest generation of module [FACIL]MOD.TYP in your default development stream. If the facility name is omitted, your default facility is assumed. If the whole parameter is omitted, the most recent generations for the default stream of all modules in the default facility are shown.

With the SHOW GENERATION 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. The SHOW GENERATION command displays generations for all modules that match the wildcard patterns.

Each generation for a given module is named in two ways. One name is the generation number that VSC assigns and the other is the generation expression that CMS assigns. You can use either name to specify the generation to display.

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 can be two different generations (if the streams have diverged).

When you refer to a generation by its generation number, you specify a semicolon and the generation number after the module name. For example, MOD.TYP;5 refers to generation 5 for the default stream (or the stream specified by the /STREAM qualifier). You 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. If you specify the asterisk (*) wildcard character in place of the generation number (as in MOD.TYP;*), the SHOW GENERATION command displays all generations for the stream starting with the most recent generation.

CMS generation expressions are assigned a different way. 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, you must use the /GENERATION qualifier. For example, MOD.TYP/GENERATION=1B1 refers to the generation of module MOD.TYP that has generation expression 1B1.

If you omit both the generation number and the /GENERATION qualifier, VSC displays the latest generation in the default or specified stream.

The SHOW GENERATION command also accepts a number of qualifiers that select subsets of the specified generations. For example, you can select all generations created before or since a certain date and time, you can select the generations created by a certain user, and you can select those generations that differ between two streams.

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

Table 3-3 Qualifiers to the SHOW GENERATION command

/BEFORE=date-time
	Displays only those generation created before the specified date and time.
/BRIEF /FULL
	Determine the type of information displayed for each generation. /BRIEF displays the module name, generation number, generation expression, creating user, and creation date and time of each generation that matches the generation-specification parameters. /FULL displays all database information for each generation.
/GENERATION=gen-expr
	Specifies that the module generation with the CMS generation expression given by the gen-expr parameter be displayed.
/IF_SAME=stream-name /IF_DIFFERENT=stream-name
	Displays only those generations that are the same (or different) in two streams. These qualifiers select the latest generation of each specified module in the stream given by the /STREAM qualifier (or your default stream). The /IF_SAME qualifier displays this generation only if it is also the latest generation of the module in the stream given by the stream-name parameter. The /IF_DIFFERENT qualifier displays this generation only if it differs from the latest generation of the module in the stream given by the stream-name parameter. These qualifiers thus show for what modules two developments streams are still the same and for what modules the streams differ.
	The latest generations of two streams are considered to be the same only if they are the identical generation with the same generation expression. VSC determines this from the contents of the source control database, not by comparing the text of the two generations.
/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 generation created on or after the specified date and time.
/STATISTICS=(keyword [, keyword...])
	Computes and displays certains statistics about the selected generations. 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 generation count. FACILITY---Compute and display the number of generations in each facility. TYPES---Compute and display the number of generations 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 generations is not shown. Use selection qualifiers and wildcard characters in the generation specification parameters to select the generation population for which you want statistics.
/STREAM=stream-name
	Specifies that the generation numbers you specify on the command parameters are for the stream specified by the stream-name parameter. If this qualifier is omitted, generation numbers are relative to your default stream.
/TOTAL
	Shows the total number of generations that match the specified generation-specification parameters. Only the total count is shown; other information about the individual generations is not shown.
/TREE
	Displays the full generation tree for each specified module. The generations are ordered by creation date (the most recent generations are shown first). For each generation that is the latest generation of some development stream, the name of that stream is displayed. This display is equivalent to the display that the CMS SHOW GENERATION /DESCENDANTS /MEMBER command gives.
/USERNAME[=username]
	Displays only those generations created by the user specified by the username parameter. If the username parameter is omitted, VSC displays only those generations that you created. If the whole qualifier is omitted, VSC displays generations created by any user.

Examples

This example shows the brief output of the SHOW GENERATION command. Each generation's module name is followed by a semicolon and the VCS generation number which in turn is followed by the CMS generation expression (audit trail identifier) in parentheses. The output also shows who created the generation and when it was created:

VSC> SHOW GENERATION *.* Generations for development stream MUSHROOM: Generation [RMS]MODULE_A.REQ;2(2) SMITH 12-DEC-1989 08:44:12 Generation [RMS]MODULE_B.REQ;25(10A12B3) JONES 9-DEC-1989 20:34:00 Generation [RMS]MODULE_C.B32;14(9H5) BROWN 9-DEC-1989 20:34:45 Generation [RMS]MODULE_D.B32;1(1) MURGATROID 9-DEC-1989 20:34:57 Generation [RMS]MODULE_E.B32;8(6A2) JONES 29-DEC-1989 13:12:32 VSC>

This next example shows how to display all generations of a given module that gave rise to the latest generation in your default stream:

VSC> SHOW GENERATION MODULE_E.B32;* Generations for development stream MUSHROOM: Generation [RMS]MODULE_E.B32;8(6A2) JONES 29-DEC-1989 13:12:32 Generation [RMS]MODULE_E.B32;7(6A1) JONES 26-DEC-1989 14:00:00 Generation [RMS]MODULE_E.B32;6(6) SMITH 19-DEC-1989 15:37:12 Generation [RMS]MODULE_E.B32;5(5) PORTER 12-DEC-1989 13:10:01 Generation [RMS]MODULE_E.B32;4(4) DINGDONG 12-DEC-1989 08:43:27 Generation [RMS]MODULE_E.B32;3(3) SMITH 12-DEC-1989 08:37:31 Generation [RMS]MODULE_E.B32;2(2) JONES 12-DEC-1989 08:35:54 Generation [RMS]MODULE_E.B32;1(1) JONES 9-DEC-1989 20:34:02 VSC>

The following example shows the full output of the SHOW GENERATION command for a specific generation:

VSC> SHOW GENERATION [RMS]MODULE_E.B32;8/FULL Generation [RMS]MODULE_E.B32;8 Generation created on 29-DEC-1989 13:12:32.25 Generation created by user JONES (Jim Jones) Module is a source module CMS generation expression is "6A2" Delta letters in use: None Generation created in stream V5.4 Latest generation for stream MUSHROOM, X4PM_BIRCH, V5.4 Module is current for stream MUSHROOM Remark: Add the mumble-fratz feature VSC>

This example shows the output of the /TREE qualifier:

VSC> SHOW GENERATION/TREE [EXEC]MODULE_X.MAR Generation tree for module [EXEC]MODULE_X.MAR: (5B2) 19-DEC-1989 15:37:12.37 SMITH "This time it will work for sure!" Latest generation for stream MUSHROOM, X4PS_MUSHROOM (5B1) 19-DEC-1989 15:37:12.11 SMITH "Fix whizbang feature again" Latest generation for stream X4PR_MUSHROOM (5A1) 19-DEC-1989 15:37:12.00 SMITH "Fix whizbang feature" Latest generation for stream X4PQ_MUSHROOM (5) 12-DEC-1989 13:10:01.45 PORTER "Add whizbang feature" Latest generation for stream PHOENIX, X4PP_PHOENIX (4) 12-DEC-1989 08:43:27.29 DINGDONG "Implement look-aside lists" (3A2) 12-DEC-1989 13:10:01.00 PORTER "Fix some bad comments" Latest generation for stream X4PM, X4PN, X4PO (3A1) 12-DEC-1989 13:10:01.56 PORTER "Add comments" (3) 12-DEC-1989 08:37:31.18 SMITH "Implement look-down algorithm" Latest generation for stream X4PK, X4PL (2) 12-DEC-1989 08:35:54.47 JONES "Implement new look-up algorithm" Latest generation for stream V5.2, V5.3, V5.4, X4PJ_BIRCH (1) 9-DEC-1989 20:34:02.13 JONES "Initial generation of module" VSC>

3.4 Displaying Differences between Generations

VSC provides a DIFFERENCES command that determines and displays the differences between the texts of any two module generations. This is in addition to the ability to display differences between module generations through the REVIEW REPLACEMENT subsystem. The DIFFERENCES command fetches two specified generations into a scratch directory and runs the DCL DIFFERENCES command in a subprocess to display the differences between the two generations on your terminal. The following example shows how to use the DIFFERENCES command:

VSC> DIFFERENCES [FACIL]MOD.TYP;5 [FACIL]MOD.TYP;2

This example fetches generation 5 of module MOD.TYP in facility FACIL and generation 2 of the same module, computes the differences between those two files, and displays the differences. These generations are for your default development stream. The second parameter can be abbreviated to just a semicolon and the generation number (such as ;2) if the module name is the same for both generations. If the second parameter is omitted entirely, the specified generation is compared with the immediately preceding generation in the same development stream. If the second parameter is omitted in the previous example, generation 5 is thus compared with generation 4. Zero and negative generation numbers are also allowed; these generation numbers are relative to the latest generation of the module for the stream. If the generation number is omitted, generation 0 (the latest generation) is assumed by default.

The generations can also be identified by their CMS generation expressions (such as 10A2) with the /GENERATION qualifier. If both generations are generations of the same module (the usual case), this form of the qualifier is allowed:

VSC> DIFFERENCES [FACIL]MOD.TYP/GENERATION=(10A2,11B1)

This command compares the generations of [FACIL]MOD.TYP identified by the CMS generation expressions 10A2 and 11B1.

If you do not specify the /GENERATION qualifier, VSC uses the specified (or default) generation numbers and assumes the generation numbers to be relative to your default development stream. You can specify that you want to compare generations from other streams with the /STREAM qualifier:

VSC> DIFFERENCES [FACIL]MOD.TYP/STREAM=PHOENIX

This command compares the two most recent generations of the specified module in stream PHOENIX. To compare generations from different streams, you can either specify the /STREAM qualifier on both command parameters or you can use this special form of the qualifier with just one parameter:

VSC> DIFFERENCES [FACIL]MOD.TYP/STREAM=(V5.4,PHOENIX)

This command computes the differences between the most recent generations of the module for streams V5.4 and PHOENIX.

The DIFFERENCES command also accepts all qualifiers that the DCL DIFFERENCES command accepts. These qualifiers are simply passed through to the subprocess that runs the OpenVMS DIFFERENCES utility.

To perform its action, the DIFFERENCES command fetches the specified generations into a scratch directory. If you have defined logical name VDE$SCRATCH, VSC uses the directory given by that logical name as the scratch directory. If this logical name is not defined, VSC creates a subdirectory VDE$SCRATCH.DIR (unless it exists already) in directory SYS$SCRATCH and stores the files in that subdirectory. (By default, SYS$SCRATCH is your login directory.) VSC then spawns a subprocess to run the DCL DIFFERENCES command and display the differences. VSC deletes the fetched files at the end of the command unless you specify the /KEEP qualifier. The difference output goes to your terminal by default, but you can direct it to a file with the /OUTPUT qualifier.

Table 3-4 lists the qualifiers for the DIFFERENCES command and describes their functions.

Table 3-4 Qualifiers to the DIFFERENCES command

/GENERATION=gen-expr
	Specifies that the module generation that has the CMS generation expression given by the gen-expr parameter be compared. If this qualifier is omitted, the command uses the generation given by the generation number on the module-name parameter. If both this qualifier and the generation number are omitted, the command uses the latest generation of the module for the specified development stream.
/KEEP
	Specifies that the fetched and compared module generations be retained after the command completes. If this qualifier is omitted, the files containing those generations are deleted after the differences are computed.
/STREAM=stream-name
	Specifies that the generation to be compared should be taken from the development stream given by the stream-name parameter. If this qualifier is omitted, the generation is taken from your default stream unless you use the /GENERATION qualifier.
/CHANGE_BAR /COMMENT_DELIMITER /IGNORE /MAXIMUM_DIFFERENCES /MATCH /MERGED /MODE /NUMBER /NONUMBER /OUTPUT /PARALLEL /SEPARATED /SLP /WIDTH /WINDOW
	These qualifiers are passed through to the spawned OpenVMS DIFFERENCES command without change. See the description of the DIFFERENCES command in the OpenVMS DCL Dictionary manual for a description of these qualifiers and their parameters.

3.5 Displaying Development Streams

The SHOW STREAM command lists information about the development streams defined in the source control database. Streams include past versions of OpenVMS, versions currently under development, build base levels, and off-to-the-side development streams. The following example illustrates the syntax of the SHOW STREAM command:

VSC> SHOW STREAM PHOENIX

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

Table 3-5 lists the qualifiers for the SHOW STREAM command and describes their functions.

Table 3-5 Qualifiers to the SHOW STREAM command

/BRIEF /NORMAL /FULL
	Determine the type of information displayed for each stream. /BRIEF displays the name of each stream that matches the stream-name parameters. /NORMAL displays the name and remark string for each stream; this is the default output. /FULL displays all attributes of each stream, including its name, creation date and time, reviewers, and remark string.
/OPEN /FROZEN /CLOSED
	Displays only those streams with the specified status. /OPEN displays only those streams that are open for replacements. /FROZEN displays only those streams that are "frozen" so that replacements are not currently possible. /CLOSED displays only those streams that are permanently closed against replacements. If you omit all of these qualifiers, VSC displays all streams regardless of status.
/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.
/SUCCESSOR
	Shows the full stream successor chain for each displayed development stream. This information shows to what streams changes will be propagated from a given stream.
/TOTAL
	Shows the total number of streams that match the specified stream-name parameters. Only the total count is shown; other information about the individual streams is not shown.

Examples

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

VSC> SHOW STREAM Stream MUSHROOM "Maintenance stream, formerly V5.4-1" Stream PHOENIX "V6.0 (?) release stream (née Thunderbolt)" Stream V4.4 "SDC release of VMS V4.4" Stream V5.0 "SDC release of VMS V5.0" Stream V5.2 "SDC release of VMS V5.2" Stream V5.4 "SDC release of VMS V5.4" VSC>

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

VSC> SHOW STREAM/BRIEF * Stream MUSHROOM Stream PHOENIX Stream V4.4 Stream V5.0 Stream V5.2 Stream V5.4 VSC>

The following example shows the full output of the SHOW STREAM command for one stream:

VSC> SHOW STREAM/FULL MUSHROOM Stream MUSHROOM Stream created on 19-OCT-1990 10:37:00.77 Stream created by user SMITH (Jane Smith) Stream owner is user SNURD (Mortimer Snurd) Parent stream is V5.4 Successor streams: PHOENIX Stream is part of the main development thread Stream cannot be deleted CMS class is maintained for stream Replacements are queued for stream Stream is open for checkins Remark: V5.4-1 release class VSC>

This example shows the effect of the /SUCCESSOR qualifier:

VSC> SHOW STREAM V5.3 /SUCCESSOR Stream V5.3 Successor chains: V5.3 -> V5.3-1 -> V5.3-2 -> V5.4 -> MUSHROOM -> PHOENIX VSC>