The SHOW USER command lists information about the users of the OpenVMS source control system. These users are the OpenVMS developers and others who are allowed to access the OpenVMS current library. The following example shows how to use the SHOW USER command:

VSC> SHOW USER SMITH

This example displays information about the user with OpenVMS user name SMITH. If the user name is omitted, the command shows information about all users recorded in the database. With this command, you can specify a list of user names separated by commas, and you can use the asterisk (*) and percent sign (%) wildcard characters in the user names. All users whose OpenVMS user names match the wildcard patterns are displayed.

The qualifiers available on the SHOW USER command are described in Table 3-6.

Table 3-6 Qualifiers to the SHOW USER command

/BRIEF /FULL
	Determine the type of information displayed for each user. /BRIEF displays the OpenVMS user name and the full name (first name and last name) of each user who matches the user name parameters. /FULL displays all database information about each user.
/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 users that match the specified username parameters. Only the total count is shown; other information about the individual users is not shown.

Examples

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

VSC> SHOW USER S* User SMITH (Jane Smith) User SNURD (Mortimer Snurd) VSC>

The following example shows the full output of the SHOW USER command:

VSC> SHOW USER/FULL SNURD User SNURD (Mortimer Snurd) User added to database on 19-OCT-1990 22:12:40.91 User added to database by user JONES (Jim Jones) Remark: VMS Developer Default privileges: CREMOD RESREP Authorized privileges: CREMOD RESREP VSC>

This chapter tells you how to review modules on behalf of another developer who has queued those modules for replacement. When you are a reviewer for a replacement, it is your responsibility to review the code being replaced for errors, quality, and appropriateness for the development stream. Based on these factors, you must then record in the source control database that you either accept or reject the proposed replacement. This chapter tells you how to perform these operations.

4.1 Reviewing Modules Queued for Replacement

When you queue a replacement with the REPLACE command, you can use the /REVIEWER qualifier to that command to specify who should review your replacement. The source control system might assign additional reviewers to your replacement because some developers automatically review every change to certain modules or development streams. VSC records the reviewer list in the database and sends mail to all the reviewers to request that they review your replacement. The SHOW REPLACEMENT/FULL command will display the reviewer list for you.

Once a replacement has been queued, the reviewers for that replacement are allowed to review it and to vote to accept or reject it. Reviewing the replacement means examining the source changes about to be replaced into the source code library to determine if they appear correct in style, substance, and appropriateness. The REVIEW REPLACEMENT command helps you review the source changes that comprise a replacement. For example, if you are a reviewer for the replacement SMITH--1, you should enter the following command to review it:

VSC> REVIEW REPLACEMENT SMITH-1

This command places you in a VSC subsystem that presents the VSC_REVIEW> prompt. This subsystem accepts a limited set of commands that allow you to examine the source code being replaced, differences between the new source code and the previous code in the source code library, and text files written by the replacement's submittor or by other reviewers. When you are done reviewing the replacement, you enter the EXIT command or press Ctrl/Z to return to the normal VSC> prompt.

To perform its function, the REVIEW REPLACEMENT command first creates a review list for the specified replacement. The elements of the review list consist of the information file created by the user queing the replacement (if such a file was specified), the comment files created by previous reviewers (if such files were specified), and the modules queued for replacement. The review list will also contain a log file from the PERFORM REPLACEMENT command if that command was used but encountered errors when it tried to perform the replacement. One element of the review list is always designated as the current element; that is the element whose contents you can display. Initially, the first element on the list is the current element, but various commands allow you to change the current element.

The commands in the REVIEW REPLACEMENT subsystem let you display the review list, navigate back and forth among the elements of the list to select the current element, and display the contents of the current element. To display an information or comment file, VSC simply types the file on your terminal. To diplay a module being reviewed, VSC can show the source being replaced, the original source currently in the library, and the differences between these two. VSC also lets you use an editor to examine files if you prefer.

The REVIEW REPLACEMENT command accepts several qualifiers that let you control the composition of the review list. Table 4-1 lists these qualifiers and describes their functions.

Table 4-1 Qualifiers to the REVIEW REPLACEMENT command

/COMMENT
	Causes all comment files provided by previous reviewers to be included in the review list.
/INFORMATION
	Causes the replacement owner's information file to be included in the review list.
/MODULE
	Causes all source modules that are part of the replacement to be included in the review list.
You can use these qualifiers in combination to include the elements you want in the review list. If you omit all three qualifiers, the command automatically includes all three kinds of elements in the review list.

Subsystem Commands

As already mentioned, the REVIEW REPLACEMENT subsystem accepts a special set of commands and keeps prompting for such commands until you enter the EXIT command. Table 4-2 lists the REVIEW REPLACEMENT subsystem commands and describes their functions.

Table 4-2 Commands Accepted in the REVIEW REPLACEMENT Subsystem

EXIT
	Exits from the subsystem and returns you to the VSC> prompt. Pressing Ctrl/ Z performs the same function.
DIRECTORY
	Displays the review list for the replacement being reviewed. The command displays one line for each information file, comment file, log file, and module that is part of the queued replacement.
CURRENT
	Displays the name of the current element in the review list. The current element is the file or module that VSC displays if you enter a SHOW or EDIT command.
NEXT
	Makes the next element on the review list the current element and displays the name of that element. Pressing the KP0 key (the 0 key on the numeric keypad) is equivalent to entering a NEXT command. As a result, you can step from element to element by repeatedly pressing the KP0 key. Similarly, the COMMA (,) key on the numeric keypad enters the NEXT and SHOW commands with a single keystroke and the MINUS (--) key on the numeric keypad enters the NEXT and EDIT commands.
BACK
	Makes the previous element on the review list the current element and displays the name of that element.
FIRST
	Makes the first element on the review list the current element and displays the name of that element.
LAST
	Makes the last element on the review list the current element and displays the name of that element.
SELECT mod-name
	Makes the review-list element specified by the mod-name parameter the current element and displays the name of that element. To select a module, the mod-name parameter must specify the name of that module in the normal VSC module-name syntax. To select an information or comment file, the mod-name parameter must specify the user name of the developer who created that information or comment file. To select the log file that VSC created if an attempt to perform the replacement failed, the mod-name parameter must specify the file name LOG.
SHOW
	Types the contents of the current review-list element on your terminal. The SHOW command takes an optional keyword parameter. If the current element is a module, the NEW keyword displays the new version of the module queued for replacement, the OLD keyword displays the old version of that module currently in the library, and the DIFFERENCES keyword displays the differences between the new and the old versions. If no keyword is given, VSC displays differences by default. If the current element is an information, comment, or log file, VSC displays the text of that file and ignores any keyword you specify.
EDIT
	Spawns an editing session to display the current review-list element. The EDIT command takes an optional keyword parameter. If the current element is a module, the NEW keyword displays the new version of the module queued for replacement, the OLD keyword displays the old version of that module currently in the library, and the DIFFERENCES keyword displays the differences between the new and the old versions. If no keyword is given, VSC displays differences by default. If the current element is an information, comment, or log file, VSC displays the text of that file and ignores any keyword you specify.
	Use the SET EDITOR command at the VSC> prompt to specify your preferred editor. If you have not specified an editor, VSC uses the system default text editor by default.
ACCEPT ["remark-string"]
	Records in the VSC database that you accept the replacement currently being reviewed. You must be a reviewer for the replacement to use this command. You can specify the optional remark string to give a reason for accepting the replacement. This command accepts the same qualifiers as the VSC-level ACCEPT REPLACEMENT command.
REJECT "remark-string"
	Records in the VSC database that you reject the replacement currently being reviewed. You must be a reviewer for the replacement to use this command. The remark string should specify a reason for rejecting the replacement. If you omit the remark parameter, VSC prompts you for a remark. This command accepts the same qualifiers as the VSC-level REJECT REPLACEMENT command. Like REJECT REPLACEMENT, the REJECT command lets you specify a comment file to more fully explain your reasons for rejecting the replacement.
SPAWN
	Spawns a subprocess. This command accepts the same parameters and qualifiers as the VSC-level SPAWN command.
ATTACH
	Attaches to a specified subprocess. This command accepts the same parameters and qualifiers as the VSC-level ATTACH command.

The normal way to use the REVIEW REPLACEMENT subsystem is to step from one review-list element to the next with the NEXT command (or the KP0 key on the numeric keypad) and to then examine each element with the SHOW or EDIT command. To examine an information, comment, or log file, just use the SHOW command. To examine a module, you should generally start by examining the differences between the new and old versions of the module. The SHOW or EDIT command without a keyword parameter will create and display the differences file. If that does not give you enough information, use the EDIT NEW command to see the full text of the source module to be replaced. Use the EDIT OLD command if you want to see the old source code for comparison. When you are done reviewing the replacement, enter the EXIT command to return to the VSC> prompt.

To traverse and display the review-list elements slightly faster, you can press the COMMA (,) key on the numeric keypad to perform the NEXT and SHOW commands with a single keystroke. Similarly, you can press the MINUS (--) key on the numeric keypad to perform the NEXT and EDIT commands with a single keystroke.

The new version, old version, and differences file for a module are all stored in the queued replacement's staging area. VSC fetches the old version and generates the differences file the first time a reviewer displays differences. For subsequent reviewers, VSC uses the files that already exist in the staging area.

Examples

In the following example, Jane Smith has queued a replacement consisting of two modules, [FACIL]FOO.MAR and [RMS]FUMBLE.B32. She has also supplied an information file for the replacement. If you were a reviewer for this replacement, you might first enter the following command to display information about it:

VSC> SHOW REPLACEMENT/FULL SMITH-5 Queued replacement SMITH-5 Replacement queued by user SMITH (Jane Smith) Replacement queued on 4-OCT-1997 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: Not reviewed by BROWN (Bill Brown) on 4-OCT-1997 17:08:03.08 Rejected by user JONES (Jim Jones) on 4-OCT-1997 17:08:03.08 Remark: Bad choice of variable name Not reviewed by SNURD (Mortimer Snurd) Remark: Fix bad-status bug VSC>

You would then enter the following command to review it:

VSC> REVIEW REPLACEMENT SMITH-1 VSC_REVIEW>

At the subsystem prompt, you might want to see what modules and files are in the replacement's review list. The DIRECTORY command performs this function:

VSC_REVIEW> DIRECTORY Modules and files being reviewed for replacement SMITH-1: Information file by user SMITH (Jane Smith) Comment file by reviewer JONES (Jim Jones) rejecting replacement Module [FACIL]FOO.MAR Module [RMS]FUMBLE.B32 VSC_REVIEW>

The review list includes SMITH's information file, a comment file from another reviewer JONES, and the two source modules. The information file is initially the current element since it is the first element on the list. To display that file, enter the SHOW command:

VSC_REVIEW> SHOW Please perform this replacement after replacement SNURD-2 has run. This replacement depends on a data cell defined by that code. VSC_REVIEW>

The next element on the list is a comment file that user JONES created when he voted to reject the replacement. Such a comment file normally gives the reason for rejecting the replacement. To select and display that comment file, enter the NEXT command followed by the SHOW command:

VSC_REVIEW> NEXT Comment file by reviewer JONES (Jim Jones) rejecting replacement VSC_REVIEW> SHOW The code looks correct, but the name of variable USER_IS_A_JERK should be changed to something more appropriate, such as USER_ERROR_FLAG. VSC_REVIEW>

To see the differences for the first module on the review list (module FOO.MAR), enter another NEXT command followed again by a SHOW command:

VSC_REVIEW> NEXT Module [FACIL]FOO.MAR VSC_REVIEW> SHOW %VDE-I-FETCHED, generation [FACIL]FOO.MAR;5(5) fetched from library %VDE-I-OUTFILE, output file is VSC$STAGEDISK:[VMS.STAGE.VDE$STG_1.VDE$REP_115 .FACIL]FOO.MAR_VDE$OLD; ************ File VSC$STAGEDISK:[VMS.STAGE.VDE$STG_1.VDE$REP_115.FACIL]FOO.MAR;1 46 Init_Linked_List(LST_PTR); 47 X = 5; ****** File VSC$STAGEDISK:[VMS.STAGE.VDE$STG_1.VDE$REP_115.FACIL]FOO.MAR_VDE$OLD;1 46 X = 5; ************ Number of difference sections found: 1 Number of difference records found: 1 DIFFERENCES /IGNORE=()/MERGED=1/OUTPUT=VSC$STAGEDISK:[VMS.STAGE.VDE$STG_1.VDE$REP_115.FACIL] FOO.MAR_VDE$DIFF;1- VSC$STAGEDISK:[VMS.STAGE.VDE$STG_1.VDE$REP_115.FACIL]FOO.MAR;1- VSC$STAGEDISK:[VMS.STAGE.VDE$STG_1.VDE$REP_115.FACIL]FOO.MAR_VDE$OLD;1 VSC_REVIEW>

If the difference file had been large, it might have been easier to display it with the EDIT command. Also, to see the actual code to be replaced, you could use the EDIT NEW command at this point.

To examine module FUMBLE.B32, you repeat the NEXT and SHOW commands, as shown in the previous example. If you enter yet another NEXT command, VSC tells you that there are no more modules on the review list. You can then enter the EXIT command to return to the VSC> prompt:

VSC_REVIEW> EXIT VSC>

At this point, you can enter normal VSC commands again.

4.2 Accepting or Rejecting a Queued Replacement

Once you have reviewed the changes that make up a queued replacement, you should record whether the replacement is acceptable or not. If you find the replacement acceptable, you enter the following command:

VSC> ACCEPT REPLACEMENT SMITH-1 "Remark string"

This command records, in the source-control database, that you have reviewed the source changes in the specified queued replacement (SMITH--1) and have found them to be acceptable. Optionally, you can specify a remark string (using the /REMARK qualifier or a remark parameter as shown) or a comment file (using the /INPUT qualifier) to explain or comment on your decision to accept the replacement.

If you decide that the source changes in the queued replacement are not acceptable, you reject the replacement with the following command:

VSC> REJECT REPLACEMENT SMITH-1 "Remark string"

This command records, in the source-control database, that you have reviewed the source changes in the specified queued replacement (SMITH--1) and have rejected them for some reason. This command requires you to specify a one-line remark string that summarizes why you reject the replacement. You can specify the remark string with the /REMARK qualifier or with a remark parameter as shown. If you do not specify a remark, VSC prompts you for the remark string. You must always give a reason for rejecting a replacement so the owner of the replacement learns how to make it acceptable.

If your reasons for rejecting the replacement are too long to fit in the remark string, you should explain your reasons in a comment file. You can edit this file ahead of time and specify its file name with the /INPUT qualifier. Alternatively, you can specify the /EDIT qualifier, which causes VSC to invoke an editor to create the comment file. The owner of the replacement can read your comment file through the REVIEW REPLACEMENT subsystem. If you specify neither the /INPUT nor the /EDIT qualifier for the REJECT REPLACEMENT command, VSC asks you whether you want to edit a comment file. For the ACCEPT REPLACEMENT command, the default is to not provide a comment file.

If you have accepted or rejected a replacement and change your mind, you can enter another ACCEPT or REJECT REPLACEMENT command to reverse the earlier judgement. You can also enter another such command to modify your remark string or comment file.

You can accept or reject a replacement only if you are a reviewer for that replacement. Anyone can review a queued replacement using the REVIEW REPLACEMENT command, but only designated reviewers can vote for or against a replacement. Also, the votes of the reviewers only constitute advice to the release project leader to help him or her decide whether to perform the replacement or not. The project leader can decide for or against a given replacement regardless of what the reviewers say. Normally, however, the project leader relies on the reviewers to certify the quality and correctness of the replacement and takes their advice accordingly.

Table 4-3 lists the qualifiers for the ACCEPT REPLACEMENT and REJECT REPLACEMENT commands and describes their functions.

Table 4-3 Qualifiers to the ACCEPT REPLACEMENT and REJECT REPLACEMENT commands

/INPUT=filespec
	Specifies a text file with comments about the replacement, such as reasons for rejecting it or descriptions of possible improvements. The source control system copies this file to the replacement's staging area. If you omit the directory specification from this qualifier, the file is taken from your default directory.
/EDIT
	Specifies that VSC should start an editing session for you to create a text file with comments about the replacement. These comments can give reasons for rejecting the replacement or descriptions of possible improvements. The editor creates the file in the replacement's staging area. If you specify neither the /INPUT nor the /EDIT qualifier for the REJECT REPLACEMENT command, VSC asks you whether you want to edit a comment file.
	Use the SET EDITOR command to specify your preferred editor. If you have not specified an editor, VSC defaults to the system default text editor.
/LOG /NOLOG
	Specify whether informational log messages are printed after the replacement is accepted or rejected. /LOG causes such messages to be printed and /NOLOG suppresses them. /LOG is the default.
/REMARK="string"
	Specifies a one-line remark string to be associated with your acceptance or rejection of the replacement. If you omit this qualifier from the REJECT REPLACEMENT command, the command prompts you for a remark string. (A replacement can thus be accepted without giving a reason but cannot be rejected without a stated cause.)
/USERNAME=username
	Specifies that the replacement should be accepted or rejected 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 to be used only in special or unusual situations.