Invokes a VDE script from the VDE database and writes the resulting DCL command file to a directory in the current VDE library or to a VDE scratch directory.

Format

INVOKE SCRIPT

Description

The INVOKE SCRIPT command reads a specified VDE script from the VDE database, executes the script language in the script to produce a DCL command file, and writes that DCL command file to the appropriate directory. The INVOKE SCRIPT command does not execute the resulting DCL command file.

The directory that receives the DCL command file is the directory that would receive it if the script were executed normally as part of a VDE command. This directory depends on the script type, and is displayed in a log message. You can use the INVOKE SCRIPT command to examine the DCL code generated by VDE in response to your scripts.

You must specify a script-type qualifier to select the script you want invoked. See the description of the CREATE SCRIPT command for an explanation of the format of scripts and the different types of scripts. Also see the description of the CREATE SCRIPT command for an explanation of how VDE selects scripts for specific modules or facilities. If the scripts you select have multiple segment numbers, VDE selects one script for each segment number and generates the DCL command file from those scripts in order by their segment numbers.

The INVOKE SCRIPT command always selects and invokes the desired script in the context of the default development stream.

Keywords used within scripts are documented in Script Keywords, while script functions are in Script Functions, and script types are in Script Types. For other script-related commands, also see CREATE SCRIPT, DELETE SCRIPT, EXTRACT SCRIPT, MODIFY SCRIPT, and SHOW SCRIPT.

Qualifiers

/BUILD

Specifies that the default stream's BUILD script be invoked.

/COMPILE=mod-name

Specifies that a COMPILE script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/COPY=mod-name

Specifies that a COPY script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/CREATE_FACILITY

Specifies that the facility creation script be invoked. The the values of the $FAC, $MOD, and $TYP script functions (among others) are determined when the script is invoked.

/DELETE_GENERATION=mod-name

Specifies that a DELETE_GENERATION script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/DIFFERENCES=mod-name

Specifies that a DIFFERENCES script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/FETCH=mod-name

Specifies that a FETCH script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/INSERT_GENERATION=mod-name

Specifies that an INSERT_GENERATION script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/LINK=mod-name

Specifies that a LINK script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/LOG (default)

/NOLOG

Controls whether log messages are printed after the script is invoked. The /LOG qualifier causes such messages to be printed and the /NOLOG qualifier suppresses them. These messages indicate that the script has been invoked and give the name of the resulting DCL command file.

/NEW_STREAM=fac-name

Specifies that a NEW_STREAM script for the default stream be invoked for a specified facility, using VDE's normal script selection rules. The fac-name parameter specifies the name of the facility. This name may not contain wildcard characters. The specified facility determines the value of the $FAC script function when the script is invoked.

/NOKEEP=mod-name

Specifies that a NOKEEP script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/REPLACE=mod-name

Specifies that a REPLACE script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/RESERVE=mod-name

Specifies that a RESERVE script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/SET_FACILITY=fac-name

Specifies that a SET_FACILITY script for the default stream be invoked for a specified facility, using VDE's normal script selection rules. The fac-name parameter specifies the name of the facility. This name may not contain wildcard characters. The specified facility determines the value of the $FAC script function when the script is invoked.

/SET_STREAM

Specifies that the SET_STREAM script for the default stream be invoked.

/STAGING=mod-name

Specifies that a STAGING script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

/UNRESERVE=mod-name

Specifies that an UNRESERVE script for the default stream be invoked for a specified module, using VDE's normal script selection rules. The mod-name parameter specifies the name of the module. This name may not contain wildcard characters. The specified module determines the values of the $FAC, $MOD, and $TYP script functions (among others) when the script is invoked.

Examples

$ INVOKE SCRIPT/COMPILE=MODNAM.C
%VDE-I-SCRPUSED, script to compile module [CODE]*.C (segment 10) used
%VDE-I-SCRPFILE, script produced DCL command file DEV$:[PROJDIR.MAIN.CODE
.VDE$COM]MODNAM.C;12
 script to compile module [CODE]*.C
VDE„ EXIT
$
$ TYPE [PROJDIR.MAIN.CODE.VDE$COM]MODNAM.C
$ ! DCL command file to execute a VDE script
$ !
$ ON WARNING THEN GOTO VDE$ERROR
$ !
$ SET VERIFY
$ DEFINE/NOLOG SRC$ DEV$:[PROJDIR.MAIN.CODE.SRC]
$ DEFINE/NOLOG OBJ$ DEV$:[PROJDIR.MAIN.CODE.OBJ]
$ CC/DEBUG/OBJ=OBJ$:/ANA=OBJ$: SRC$:MODNAM.C
$ VDE/DEPEND C OBJ$:MODNAM.ANA
$ !
$ SET NOVERIFY   ! Successful script completion
$ VDE/STATUS SUCCESS
$ EXIT
$VDE$ERROR:
$ SET NOVERIFY   ! Script completed with errors
$ VDE/STATUS FAILURE
$ EXIT
$
      

In this example, the user invokes the script that compiles module MODNAM.C in facility CODE. VDE selects the appropriate script using its normal script selection rules and applies the script to that module. VDE writes the resulting DCL command file to a file called MODNAM.C in the VDE$COM subdirectory for the given stream and facility. (The COMPILE and BUILD commands use this directory when they generate and execute build-step command files.) The subsequent DCL TYPE command shows the text of the DCL command file. This text includes some standard "boiler-plate" at the beginning and end of the file. In the middle of the file are the DCL commands that come from the script itself. These commands enable command-line verification, define two logical names, compile the module MODNAM.C, and use the VDE/DEPEND command to record the compile step's build dependencies. The surrounding boiler-plate traps errors and records the build step's status (success or failure).

Links the specified modules using the appropriate scripts from the database.

Requires BUILD privilege.

Format

LINK mod-name [, mod-name...]

Parameter

mod-name

Specifies a module to be linked. The module name consists of an optional facility name enclosed in square brackets, a module name, and an optional type name preceded by a period, such as [FACIL]MOD1.EXE. If no facility name is specified, the default facility is assumed. If no type name is specified, module type EXE is assumed.

You can link more than one module by using wildcard characters in any of the three components of the module name. The percent sign (%) in a name matches any single character in the position it occupies and the asterisk (*) matches zero or more characters in the position it occupies. VDE links modules whose names match the wildcard pattern.

Description

The LINK command links a module the same way it is linked in a build job. The LINK command retrieves the link script for each specified module and generates a DCL command file from the script. The command then executes the command file in a subprocess. If the module links successfully, VDE updates the build dependency information for the link step in the database.

The LINK command can be used to link a module without starting a build job. It is often used to test link scripts. It can also be used to collect the initial dependency information for a link step that does not yet have dependency information in the database.

Qualifiers

/LOG (default)

/NOLOG

Controls whether log messages are printed after the link step executes. The /LOG qualifier causes such messages to be printed and the /NOLOG qualifier suppresses them. These messages indicate that the link step has completed, either successfully or with errors, and that the dependency information for the step has been updated in the VDE database.

/STREAM=stream-name

Specifies that the modules be linked for the stream given by the stream-name parameter. If this qualifier is omitted, the modules are linked for the default stream.

Examples

VDE„ LINK [CODE]X.EXE
$ DEFINE/NOLOG OBJ$ DEV$:[PROJDIR.MAIN.CODE.OBJ]
$ LINK /EXE=OBJ$:X.EXE /MAP=OBJ$:X.MAP -
        OBJ$:OBJLIB.OLB/INCLUDE=C,OBJ$:OBJLIB.OLB/LIBRARY
$ !
$ SET NOVERIFY   ! Successful script completion
%VDE-I-LINKSUCC, link of [CODE]X.EXE completed successfully
%VDE-I-DEPUPDATE, dependency information updated for build step
VDE„
      

This example links module X.EXE in facility CODE. The output from the execution of the link script is displayed on the terminal. The final log messages show that the link step completed successfully and that its dependency information was updated in the database.

Modifies one or more architecture table entries in the VDE database. Each architecture table entry...

Requires the CREARCH privilege.

ARCHITECTURE support is not fully implemented.

An architecture is a construct that encompasses one or more facilities, and allows modules to exist in a "common" or "default" facility, and zero or more architecture specific facilities. In must the same fashion as the SYS$SYSROOT: logical name allows one to support both system-specific and cluster-common files, an architecture allows one to support architecture-specific and architecture-common modules.

Format

MODIFY ARCHITECTURE arch-name [, arch-name...]

Parameter

arch-name

The name of the architecture to be modified. This name may be up to 39 characters long and must follow VDE name syntax.

Description

Under Construction...

Qualifiers

/CONFIRM (default)

/NOCONFIRM

Under Construction...

/DELETE (default)

/NODELETE

Under Construction...

/LOG (default)

/NOLOG

Under Construction...

/NAME

Under Construction...

/REMARK="string"

Specifies a remark string to be stored for the modified architecture. The quoted remark string, which can be up to 132 characters long, may contain any explanatory remark about the architecture. that you want stored in the VDE database. Typically the remark describes the function or purpose of the architecture.

Examples

VDE„ MODIFY ARCHITECTURE VAXPDP/REMARK="Version n"
VDE„
      

Under Construction...

Modifies the batch queues, process count, remark string, and other attributes of existing build jobs in the VDE database.

Requires BUILD privilege.

Format

MODIFY BUILD_JOB [stream-name [, stream-name...]]

Parameter

stream-name

The name of a development stream containing the build jobs to be modified. To specify the build jobs, use the /IDENTIFICATION qualifier. If you do not use the /IDENTIFICATION qualifier, the most recent build job for the stream is modified.

You can modify build jobs in more than one stream by using wildcard characters in the stream name. The percent sign (%) in a name matches any single character in the position it occupies and the asterisk (*) matches zero or more characters in the position it occupies. Build jobs in those streams whose names match the wildcard pattern are modified.

If you omit the stream-name parameter, VDE modifies the attributes of one or more build jobs for the default development stream.

Description

The MODIFY BUILD_JOB command modifies the attributes of build jobs having the specified stream names and build job identification numbers. You can modify the following attributes: the batch queues to which the job is submitted for execution, the total number of batch processes submitted, the remark string, the step-delay interval, and the timeout interval. VDE modifies these attributes by updating the database with the information you specify. You cannot modify the queues or process count of a build job that has started running or that has completed execution. You can, however, suspend a running build job, modify those attributes, and restart the job.

Qualifiers

/CONFIRM

/NOCONFIRM (default)

Controls whether VDE asks you to confirm that you want each build job modified. The /CONFIRM qualifier causes VDE to print a message for each build job asking whether you want that build job modified. If you answer YES (or Y), the attributes of the build job are modified in the database. If you answer NO (or N), the attributes are not modified. The /NOCONFIRM qualifier causes VDE to modify the attributes of the specified build jobs without asking for confirmation.

/IDENTIFICATION=id-range

Specifies the build job identification numbers of the build jobs to be modified for the specified development stream. The id-range parameter can be a single integer value, a range of integers, or a wildcard character. If the parameter is a single integer value (for example, /IDENT=5), VDE modifies the build job with that identification number. If the parameter is a range of integers (specified as two build job identification numbers separated by a colon as in /IDENT=3:5), VDE modifies all build jobs with identification numbers in that range. Finally, if the id-range parameter is the asterisk wildcard (as in /IDENT=*), VDE modifies all build jobs for the specified stream.

If you specify a zero or negative build job identification number in the id-range parameter, that number is relative to the identification number of the most recent build job for the stream. For example, if the most recent build job is job 5, then /IDENT=0 is equivalent to /IDENT=5 and /IDENT=--1 is equivalent to /IDENT=4.

If you do not use the /IDENTIFICATION qualifier, VDE modifies the attributes of the most recent build job for the specified stream.

/LOG (default)

/NOLOG

Controls whether log messages are printed after each build job is modified. The /LOG qualifier causes such messages to be printed and the /NOLOG qualifier suppresses them. These messages indicate that the build job has been modified in the database and that the database transaction has successfully committed.

/PROCESS_COUNT=proc-count

Specifies the number of processes to execute the build job. When the build job is started with a START BUILD_JOB command, VDE creates the processes by submitting batch jobs to the queues specified by the /QUEUE qualifier or to the default queues for the default stream. The number of processes that VDE creates (that is, the number of OpenVMS batch jobs it submits) is specified by the proc-count parameter. As a result, this parameter determines the degree of parallelism for the build job.

/QUEUE=(queue-name [,queue-name...])

Specifies the OpenVMS batch queues to which the build job is submitted by a subsequent START BUILD_JOB command. Each queue-name parameter specifies the name of one batch queue. The queue-name parameter may optionally be followed by a process count in parentheses. This count specifies the number of processes that are started on the queue to run the build job. For example, SYS$BATCH(3) causes three build-job processes to be submitted to queue SYS$BATCH. If the process count is omitted, one process is submitted to the queue.

If you only specify one queue-name parameter, the parentheses may be omitted.

If you also use the /PROCESS_COUNT qualifier, that qualifier states the total number of build-job processes to create. The process counts attached to the queue-name parameters on the /QUEUE qualifier are then used as scaling factors to distribute build-job processes among the queues proportionally. For example, if you specify queues HI_BATCH, HO_BATCH(3), and a total process count of eight, then two processes are submitted to queue HI_BATCH and six processes to queue HO_BATCH. If the total process count does not divide evenly into the sum of the scaling factors, the remaining processes are allocated to the queues in the order the queues are listed. If the total process count is nine, for example, the one extra process is allocated to queue HI_BATCH because HI_BATCH is listed first.

/REMARK="string"

Specifies a remark string to be stored in the database for each specified build job. The quoted remark string, which can be up to 132 characters long, may contain any explanatory remark that you want to store in the database. This string replaces the remark string from the original BUILD command or from any previous MODIFY BUILD_JOB command.

/STEP_DELAY=time-interval

Specifies the step-delay time interval used by VDE$BUILD. VDE$BUILD is the program that executes the build steps belonging to the build job. If VDE$BUILD cannot find an available build step in the database, the program waits the amount of time specified by the /STEP_DELAY qualifier before it looks in the database again. See the description of the BUILD command for a more detailed description of this qualifier.

/TIMEOUT=time-interval

Specifies the timeout interval for the build job. If no build steps complete during this interval, the VDE$BUILD utility stops the build job and assigns it TIMEOUT status. Therefore, the timeout interval must be longer than the time required to complete the longest build step. See the description of the BUILD command for a more detailed description of this qualifier.

Examples

VDE„ MODIFY BUILD_JOB V2.0-3/IDENT=15/REMARK="New remark string"
%VDE-I-BLDJOBMOD, build job 15 for stream V2.0-3 modified in database
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
      

This example modifies the remark string of build job 15 for stream V2.0-3.

VDE„ MODIFY BUILD_JOB/QUEUE=(PHI_BATCH, FOO_BATCH(3))/PROCESS_COUNT=10
%VDE-I-BLDJOBMOD, build job 12 for stream V5.2 modified in database
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
      

This command modifies the batch queues and process count associated with the most recent build job for the default stream, build job 12 of stream V5.2.