The Review Replacement Commands are used to review replacements queued to the current library. The commands are valid at the VDEREVREP> prompt during the REVIEW REPLACEMENT command.

Format

DIRECTORY [mod-name [, mod-name...]]

SELECT [mod-name]

SHOW [keyword]

EDIT [keyword]

NEXT

BACK

CURRENT

FIRST

LAST

ACCEPT ["remark-string"]

REJECT "remark-string"

SPAWN

ATTACH

EXIT

Description

The REVIEW REPLACEMENT subsystem accepts the following commands at the VDEREVREP> prompt:

• DIRECTORY [mod-name [, mod-name...]]
  Displays a list of all information files, comment files, replacement log files, and modules on the replacement review list. For each file, this command displays the type (information, comment, log, module, or binary module) and the name of user who created the file (for information and comment files) or the name of the module. If you specify one or more mod-name parameters, the command displays only those modules whose names match the parameters. You can use wildcards in the mod-name parameter. An information or comment file has the author's OpenVMS username as its file name, so these files can also be selected with mod-name parameters. The replacement log file (if present) has the file name LOG.VDE$LOG.
• SELECT [mod-name]
  Selects the first review list element whose module or file name matches the mod-name parameter and makes that the current review list element. This command prints one line identifying the selected module or file. You can select an information or comment file by specifying the author's OpenVMS username in the mod-name parameter. You can select the log file (if present) by specifying LOG in the mod-name parameter.
  If you omit the mod-name parameter, the command displays the next element on the review list that matches the most recently specified module name from a previous SELECT command. Using this feature, you can enter a SELECT command with a mod-name parameter containing wildcards to select the first module (or other file) that matches the parameter. You can then enter SELECT commands without parameters to successively select all other modules and files that match the original parameter, one module or file per SELECT command.
• SHOW [keyword]
  Prints the text of the current review-list element on your terminal. If the current element is an information or comment file, VDE reads that file and prints it on your terminal. If the current element is a module, VDE prints the new version of the module (the version about to be replaced into the library), the old version of the module (the generation that was fetched when the module was reserved), or the differences between the two. The keyword parameter determines what is displayed for a module; this parameter may be the keyword NEW, OLD, or DIFFERENCES. This parameter is ignored for information, comment, and log files.
  If you specify the OLD keyword, VDE fetches out the old module generation unless a previous reviewer has already fetched it into the replacement's staging area. VDE then displays that file. If you specify the DIFFERENCES keyword, VDE fetches out the old module generation if necessary. VDE then runs the OpenVMS DIFFERENCES command to create a differences file unless a previous reviewer has already created it. VDE then displays that file.
  This command will not display any files for binary source modules.
• EDIT [keyword]
  Invokes your preferred editor in read-only mode to display the text of the current review-list element. If the current element is an information or comment file, VDE spawns the editor to display that file. If the current element is a module, VDE spawns the editor to display the new version of the module (the version about to be replaced into the library), the old version of the module (the generation that was fetched when the module was reserved), or the differences between the two. The keyword parameter determines what is displayed for a module; this parameter may be the keyword NEW, OLD, or DIFFERENCES. This parameter is ignored for information, comment, and log files.
  If you specify the OLD keyword, VDE fetches out the old module generation unless a previous reviewer has already fetched it into the replacement's staging area. VDE then displays that file. If you specify the DIFFERENCES keyword, VDE fetches out the old module generation if necessary. VDE then runs the OpenVMS DIFFERENCES command to create a differences file unless a previous reviewer has already created it. VDE then displays that file.
  This command will not display any files for binary source modules.
  Use the SET EDITOR command at the VDE„ prompt to specify your preferred editor. If you do not declare an editor, VDE invokes the system default editor.
• 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 the same as entering the 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.
• CURRENT
  Displays the name of the current element of the replacement review list.
• 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.
• ACCEPT ["remark-string"]
  Records in the VDE 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 VDE-level ACCEPT REPLACEMENT command.
• REJECT "remark-string"
  Records in the VDE 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, VDE prompts you for a remark. This command accepts the same qualifiers as the VDE-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 and attaches the terminal to that subprocess. See the description of the VDE SPAWN command for details.
• ATTACH
  Attaches the terminal to a specified process. See the description of the VDE ATTACH command for details.
• EXIT
  Exits from the REVIEW REPLACEMENT subsystem and returns you to the VDE„ prompt.

The following keywords are used in VDE build scripts stored in the VDE database.

Requires CRESCRP privilege.

Format

EMIT

EXIT

FETCH

Description

Scripts are used to add various user-defined extensions to various VDE functions and commands. VDE invokes various scripts at various times during VDE processing---see Script Types for further information on this.

Scripts of various types are recorded in the VDE database. A script is a sequence of keywords in the VDE script language that VDE can execute to create a DCL command file. VDE can then invoke that DCL command file in a subprocess to perform the action of the script. VDE uses scripts to perform many different kinds of actions. For example, VDE uses "compile scripts" to compile modules in a build job. Similarly, it uses "new-stream scripts" to populate the directories of a new stream with files when it performs the CREATE STREAM command. There are many other kinds of scripts, all distinguished by the keywords or circumstances that cause them to be invoked.

The primary purpose of VDE scripts is to insert names and directory specifications from the VDE database into text you specify to generate DCL command files that perform various actions. A VDE script is thus a mixture of plain text and invocations of functions that retrieve names (such as module names, type names, and facility names) and directory strings (such as the names of facility subdirectories) from the VDE database.

Since you define scripts, you define how VDE should perform the corresponding actions. For example, you decide how a Pascal module is compiled because you define the Pascal compilation script. Similarly, you can define a script that defines auxiliary actions of the REPLACE command. Scripts thus let you make policy decisions for your own project, while VDE provides the mechanisms that implement your policies.

When a new development stream is created, all script definitions from the parent stream are copied to the child stream. If modified, the script definitions then evolve independently in the two development streams.

A VDE script is a sequence of text lines that contain VDE script keywords. There are only three VDE script commands: EMIT, FETCH, and EXIT.

In addition, a script may contain blank lines and comment lines. The exclamation point (!) is the comment character. VDE ignores any text on a script line after an exclamation point, provided the exclamation point is not within quotes. A script keyword command may be continued from one line to the next by ending the first line with the sequence space-minus ( --).

VDE accepts the following keyword commands in a script:

• EMIT string [, string...]
  Emits one line into the DCL command file. This keyword command evaluates each string parameter, concatenates the resulting character strings into a single line of text, and writes this line of text to the DCL command file being generated. Each string parameter may be a quoted character string, an invocation of a script function, or a directory symbol name.
  If the EMIT command parameter contains spaces or other characters, the string must be enclosed in a pair of quoting characters. (eg: If the command is a typical DCL command and contains blanks and various other characters, it must be quoted.) Valid quoting character pairs include the double-quote pair: (") and ("), and the double-caret pair: («) and (»). Use of the end-quoting character within the string is permissible, but requires that the character be doubled. (eg: a double-quote character within the string is specified by double double-quotes; by two consecutive double-quotes: ("").)
  If the parameter is an invocation of a script function, you must specify the function name or the function name followed by a parenthesized list of function parameters. VDE evaluates the function to produce a character string that is concatenated to the current DCL command line. (Next section lists the available script functions.)
  If the parameter is a directory symbol name, VDE looks up the OpenVMS directory specification associated with the directory symbol from the VDE database and concatenates that string to the current DCL command line. OpenVMS directory symbols are defined using the SET DIRECTORY command.
  To exit from the generated DCL in the script, issue one of the following script commands:

  EMIT «$ GOTO VDE$ERROR» EMIT «$ GOTO VDE$SUCCESS» EMIT "$ EXIT"

• EXIT
  Exits from the script during script execution. Subsequent script commands are thus not executed to produce DCL commands. (Note that the EXIT keyword does not create an EXIT command in the DCL command file; it only stops script execution. See the documentation on the EMIT script command for information on generating the proper DCL exit sequence from within a script.)
• FETCH string [, string...]
  Fetches a module generation from the VDE library. This keyword evaluates each string parameter, concatenates the resulting character strings into a single line of text, and interprets the line as the qualifiers and parameters to a VDE FETCH command. Each string parameter may be a quoted character string, an invocation of a script function, or a directory symbol name.
  Your string parameters should generate the full VDE FETCH command you want performed except for the FETCH keyword. The string parameters can generate all qualifiers and parameters that the VDE FETCH keyword accepts, and can use script functions to include strings such as module names, stream names, and directory specifications. The resulting command string is parsed and executed as if it belonged to a normal FETCH keyword entered from the terminal. Use the FETCH keyword when you want VDE to fetch a generation directly, without using a DCL command file, and you want it performed in the same database transaction as the operation performing the script.
  By default, VDE fetches the latest generation of the specified module in the stream for which the script is invoked. You can override this default by generating a /STREAM qualifier, /GENERATION qualifier, or a generation number for the FETCH keyword. The script FETCH keyword suppresses log messages by default, but you can override this default by generating a /LOG qualifier. Otherwise, all parameters, qualifiers, and defaults are the same as for the regular VDE FETCH keyword described elsewhere.
  If a string parameter is a quoted character string, the string must be enclosed in double quotes ("). A double-quote character within the string is specified by two consecutive double quotes (""). VDE concatenates the quoted string to the current FETCH keyword line.
  If the parameter is an invocation of a script function, you must specify the function name or the function name followed by a parenthesized list of function parameters. VDE evaluates the function to produce a character string that is concatenated to the current FETCH keyword line. (Next section lists the available script functions.)
  If the parameter is a directory symbol name, VDE looks up the OpenVMS directory specification associated with the directory symbol from the VDE database and concatenates that string to the current FETCH keyword line. OpenVMS directory symbols are defined using the SET DIRECTORY command.

When executing a script, VDE executes successive script keywords from the script until it encounters an EXIT keyword or the end of the script. VDE executes FETCH keywords immediately as they are encountered. VDE writes all lines generated by EMIT keywords to the output DCL command file. At the end of the script, VDE executes that command file in a subprocess to perform the action of the script.

Selection of Scripts

Many types of scripts are invoked when a certain operation must be applied to a specific module, such as compiling or reserving the module. For such operations, VDE must select the script that is appropriate to the module. The type of the script is of course the primary selection criterion, but even for a given type, different scripts are needed for different modules. The script that compiles a Fortran module is not appropriate for a C module, for example, and the script that links one image cannot link another. (Script Functions contains the types of scripts supported by VDE.)

To accommodate such situations, VDE lets you specify how scripts are selected based on the module name. You can specify that a script should be used only for a specific module, for all modules of a certain type in a given facility, for all modules of a given type regardless of facility, or for all modules regardless of type or facility. When you create such a script, you specify the script type with a qualifier, such as /COMPILE or /RESERVE. You also specify the modules to which the script applies through a module-name parameter to the qualifier. A restricted form of wildcarding determines what modules the script can be used for. The following module-name specifications are allowed:

• [FACIL]MOD.TYP
  If you fully specify the module name, the script applies only to that specific module. For example, the qualifier /LINK=[CODE]X.EXE says that the script can only be used to link image X.EXE in facility CODE. If you omit the facility name, the current default facility is assumed.
• [FACIL]*.TYP
  If you specify the facility name and type name but specify an asterisk (*) in place of the module name, the script applies to all modules of that type in that facility. For example, the qualifier /COMPILE=[FACIL]*.C says that the script can be used to compile all C modules in facility FACIL. If you omit the facility name, the current default facility is assumed.
• [*]*.TYP
  If you specify the type name but specify an asterisk (*) in place of both the facility name and the module name, the script applies to all modules of that type in all facilities. For example, the qualifier /COMPILE=[*]*.FOR says that the script can be used to compile all Fortran modules in all facilities.
• [*]*.*
  If you specify an asterisk (*) for each of the three components of the module name, the script applies to all modules regardless of type and facility. For example, the qualifier /RESERVE=[*]*.* says that the script can be used to reserve all modules in all facilities.

No other forms of wildcarding are allowed in the module-name parameters to script-type qualifiers.

When VDE looks for a script to perform some action for a module, it always selects the script that is most specific to that module. If it can find a script with a fully specified module name ([FACIL]MOD.TYP) for the module in question, it uses that script. Otherwise, it looks for a script with a matching module-name specification of the form [FACIL]*.TYP or [*]*.TYP or [*]*.*, in that order. This rule allows you to specify generic scripts that apply to all modules or to all modules of a certain type, but to override those scripts for specific modules or for modules in specific facilities when appropriate.

Similar rules apply to scripts that are selected by facility. A NEW_STREAM script, for example, is invoked for each facility in your system when you create a new stream. In this case, VDE accepts two forms of facility-name specification on the script-type qualifiers:

• FACIL
  If you fully specify the facility name, the script applies only to that specific facility. For example, the qualifier /NEW_STREAM=RMS says that the script can only be used for facility RMS when VDE creates new streams.
• *
  If you specify an asterisk (*) for the facility name, the script applies to all facilities. For example, the qualifier /NEW_STREAM=* says that the script can be invoked for every facility in your system when VDE creates new streams.

No other forms of wildcarding are allowed in the facility-name parameters to script-type qualifiers.

When VDE looks for a script to perform an action for a facility, it first looks for a script with a fully specified facility name. If no such script exists in the database, VDE selects the script with the wildcard in the facility name, provided it exists. You can thus specify a generic script that applies to all facilities, and then override that script for specific facilities when appropriate.

Generating Command Files in Segments

Normally, VDE generates the DCL command file to perform some action from a single VDE script. In some situations, however, it is necessary to generate different "segments" of the DCL command file from different scripts. The DCL command file that compiles a MACRO module, for example, may need to consist of three segments:

• The first segment sets up logical names for the MACRO assembler and includes the MACRO command and its qualifiers. The MACRO command is ended with the continuation character. This segment is the same for all MACRO modules, and the VDE script that generates it has the selection template [*]*.MAR.
• The second segment contains the name of the module to assemble and a plus-list of macro libraries to use with that module. This segment of the command file is different for each MACRO module, and the VDE script that generates it has a selection template of the form [FAC]MOD.TYP.
• The third segment inserts the assembled object module into an object library and runs VDE/DEPEND to collect dependency data. This segment of the DCL command file is the same for all MACRO modules, and the VDE script that generates it has the selection template [*]*.MAR.

One VDE script could generate all three segments of the DCL command file, but then a separate script is needed for each MACRO module in the library. This solution is undesirable because the script keywords that generate the first and third segments of the DCL command file are the same for all MACRO modules, thus wasting space in the VDE database and making it difficult to modify the common parts of the scripts. A better solution is to have two generic scripts with selection templates [*]*.MAR that generate the first and third segments of each MACRO module's DCL command file, and to have a small script specific to each module to generate the second segment. This solution makes it easy to modify the module-independent segments of the keyword files because they are derived from just two VDE scripts.

To allow you to generate different segments of a DCL command file from separate scripts, VDE allows you to assign a segment number to each script. A segment number is an integer value in the range from 1 to 20 that is specified with the /SEGMENT qualifier to the CREATE SCRIPT command. When VDE generates a DCL command file from scripts, it looks for an appropriate script for each possible segment number. VDE selects the script for each segment number using the normal script selection rules so that more module-specific or facility-specific scripts are favored over more generic scripts. After selecting the scripts, VDE interprets them in order by segment number to generate the DCL command file. If there are no scripts for a given segment, that segment is simply omitted from the command file. As a result, you can have up to twenty segments in a DCL command file, each generated by a separately selected script.

If you do not specify a segment number for a script, VDE assigns segment number 10 to the script. If your DCL command files do not need multiple segments, you can thus ignore segment numbers and let VDE generate segment 10 (and only that segment) for each command file. If you later decide that you need additional segments before or after the original segment, you have ample segment numbers to choose from in both directions.

Debugging Scripts

The INVOKE SCRIPT command is a useful tool for debugging scripts. INVOKE SCRIPT allows you to fetch and invoke a specified script, and then to examine the DCL command(s) generated by the script.

For further information on this command, see INVOKE SCRIPT.

Examples

$ TYPE [MYDIR]SCRIPT_C.VDESCRIPT
! Script to compile a C module.
!
EMIT "$ SET VERIFY"
EMIT "$ DEFINE/NOLOG SRC$ ", $DIR(SRC)
EMIT "$ DEFINE/NOLOG OBJ$ ", $DIR(OBJ)
EMIT "$ CC/DEBUG/OBJ=OBJ$:/ANA=OBJ$: SRC$:",$MODTYP
EMIT "$ VDE/DEPEND C OBJ$:",$MOD,".ANA"
EXIT
$ VDE
VDE„ CREATE SCRIPT/COMPILE=[RMS]*.C [MYDIR]SCRIPT_C.VDESCRIPT
%VDE-I-SCRPADDED, script from file DEV$:[MYDIR]SCRIPT_C.VDESCRIPT;9 added to
 the database
 script to compile module [RMS]*.C (segment 10)
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
      

In this example, the user first types the script file [MYDIR]SCRIPT_C.VDESCRIPT on the terminal. The script contains five EMIT keywords followed by an EXIT keyword. The user then enters VDE and uses the CREATE SCRIPT keyword to enter that script file into the VDE database as the compile script for all C modules in facility RMS. The log messages confirm that the script was successfully entered into the database.

$ TYPE [MYDIR]SCRIPT_LINK_X.VDESCRIPT
! VDE script to generate the DCL commands needed to link module X.EXE.
!
EMIT "$ SET VERIFY"
EMIT "$ DEFINE OBJLIB ", $DIR(OBJ,CODE)
EMIT "$ LINK/EXE=OBJLIB:X.EXE/MAP=OBJLIB:X.MAP  -"
EMIT "        OBJLIB:OBJLIB.OLB/INCLUDE=C,OBJLIB:OBJLIB.OLB/LIBRARY"
EMIT "$ DEASSIGN OBJLIB"
$ VDE
VDE„ CREATE SCRIPT/LINK=X.EXE [MYDIR]SCRIPT_C
%VDE-I-SCRPADDED, script from file DEV$:[MYDIR]SCRIPT_LINK_X.VDESCRIPT;2
 added to the database
 script to link module [CODE]X.EXE (segment 10)
%VDE-I-COMMIT, database transaction has successfully committed
VDE„ SHOW SCRIPT/TEXT/LINK=X.EXE
Script to link module [CODE]X.EXE (segment 10)
   Text of script:
     1: ! VDE script to generate the DCL commands needed to link module X.EXE.
     2: !
     3: EMIT "$ SET VERIFY"
     4: EMIT "$ DEFINE OBJLIB ", $DIR(OBJ,CODE)
     5: EMIT "$ LINK/EXE=OBJLIB:X.EXE/MAP=OBJLIB:X.MAP  -"
     6: EMIT "        OBJLIB:OBJLIB.OLB/INCLUDE=C,OBJLIB:OBJLIB.OLB/LIBRARY"
     7: EMIT "$ DEASSIGN OBJLIB"
 
VDE„
      

---

Previous

Next

Contents

Index