| Previous | Contents | Index |
Transfers control from your current process to the specified process.
ATTACH process-name
process-name
Specifies the parent process or a spawned subprocess to which control is to be passed. The process must already exist, be part of your current job, and share the same input stream as your current process. However, the process cannot be the current process or a subprocess created with the /NOWAIT qualifier.Do not specify the process-name parameter if you use the /IDENTIFICATION qualifier.
The ATTACH command allows you to quickly transfer control between processes. (For information about creating a subprocess, see the SPAWN command.) For example, you can transfer control from a parent process to a subprocess using the ATTACH command. Then, in the subprocess, you can start a build job using VDE and, after you finish, you can enter the ATTACH command to move back to the parent process. If you later want to display the status of your build job, you can enter another ATTACH command at DCL level (or from many utilities) to move back to the VDE subprocess you created.Do not attempt to use the DCL ATTACH command to attach to a VDE kept subprocess.
/IDENTIFICATION=pid
Specifies the process identification (PID) of the process to which terminal control is transferred. Leading zeros can be omitted. Do not specify the process-name parameter when you use this qualifier.
| #1 |
|---|
$ EDIT VACATION.TXT
.
.
.
[CTRL/Y]
$ SPAWN VDE
%DCL-S-SPAWNED, process SMITH_1 spawned
%DCL-S-ATTACHED, terminal now attached to process SMITH_1
VDE„ BUILD GAME_PROG
VDE„ ATTACH SMITH
%DCL-S-RETURNED, control returned to process SMITH
.
.
.
[CTRL/Y]
$ ATTACH SMITH_1
VDE„
|
This example shows how to spawn a subprocess (SMITH_1) to invoke VDE and use the ATTACH command to move between VDE (SMITH_1) and the DCL command level (SMITH). The ATTACH command allows you to transfer control between subprocesses.
Note
Use the SPAWN command to create a new process and the ATTACH command to connect to a process that already exists.
Creates and optionally starts a build job to build the specified modules. The discrete steps performed during the build are derived from VDE scripts.
BUILD mod-name [, mod-name...]
mod-name
Specifies a module or build group to be produced by the build job.If the parameter is a module name, it is typically the name of an executable image or another type of derived module that is the end result of a build operation. Each such module is a target of the build.
The module name must consist of a module name and a module type separated by a period (as in MODNAM.EXE) and may optionally be preceded by a facility name enclosed in square brackets (for example, [FACIL]MODNAM.EXE). If no facility name is specified, the module is assumed to belong to the default facility.
You can build more than one target 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 builds those modules whose names match the wildcard pattern.
If the mod-name parameter specifies a build group, the BUILD command builds all modules that are members of the build group. A build-group name is a simple name that has been declared with a CREATE GROUP/BUILD command. A build-group name may not contain wildcard characters.
The BUILD command performs two distinct operations: it creates a build job for the default development stream in the VDE database and it optionally starts that build job on a set of OpenVMS batch queues.To create a build job in the database, the BUILD command does the following three things:
- First, the BUILD command determines the target modules to be built. The target modules are specified by the mod-name parameters of the command.
- Next, the command determines the build steps that must be performed to build those target modules. The needed build steps are determined by the build dependencies stored in the VDE database, by the modules that have changed since the last time the targets were built, and by whether the user requests a full or minimal build.
- Finally, the BUILD command records information about the new build job in the database. The information specifies the build steps to be performed, any constraints on the order in which the steps are performed, and other attributes. (An example of an order constraint is the requirement that a compile step must complete before a dependent link step starts.)
The build job is always created for the default development stream. It uses the build dependencies of the default stream to determine the build steps to perform and it uses module replacement data for the default stream to determine the modules that have changed since the last build. The build job is then identified by the stream name and a build-job identification number. For example, the second build job for stream V1.0 is labeled "build job 2 for stream V1.0" in VDE messages.
You cannot create a new build job for a given stream if a build job already exists for that stream and that existing build job has not yet completed execution. This restriction ensures that two build jobs for the same stream do not execute at the same time. If you do not want the existing build job to run, stop it with the STOP BUILD_JOB command before creating the new build job.
To start a build job, the BUILD command submits one or more batch jobs to the OpenVMS batch queues that the user specified either with the /QUEUE qualifier or by default. Then each batch job runs the VDE$BUILD utility that executes the build steps belonging to the build job. The steps are executed in a loop until all the steps are done. The VDE$BUILD utility does the following for each build step:
- The program looks in the database for the next available build step. (A build step, normally a compile, copy, or link step, is available if it is not waiting for another step to complete.) If no step is available, the program waits a few seconds before looking for another available build step.
- When the program finds a build step to run, it looks up the VDE script for that step and, from the script, generates the DCL commands needed to run the step. The program then sends the DCL commands to a subprocess that executes the build step, and waits for the step to complete.
- After the step completes, the program records the completion status of the step in the database. A step completes either successfully or with errors. If the step completes successfully, the program updates the step's build dependency information in the database and then looks for another step to perform.
The BUILD command always creates a new build job in the VDE database. It also starts the build job unless you use the /NOSTART qualifier or you answer NO to a query asking whether to start the build. If the BUILD command does not start the build job, you can start it later with the START BUILD_JOB command. After the build job is created (whether or not you start it), you can use the SHOW BUILD_JOB command to display the attributes of the build, including the size of the build job and the exact build steps and build-step dependencies that make up the build job.
You can distribute the build job across several processors (whether in a single machine or in multiple machines in a cluster) by specifying the /QUEUE and /PROCESS_COUNT qualifiers. The /QUEUE qualifier specifies the batch queues to run the build job. The /PROCESS_COUNT qualifier specifies the total number of processes VDE submits to the batch queues performing the build job. By specifying the batch queues and the number of processes VDE submits to each queue, you can decide how to distribute the build job over a cluster with processors of different speeds and configurations.
If you do not specify the /QUEUE or /PROCESS_COUNT qualifier, VDE uses the default batch queues and process counts of the default development stream. You can establish these defaults using the /QUEUE and /PROCESS_COUNT qualifiers with the CREATE STREAM and MODIFY STREAM commands. If you have not specified such defaults, VDE submits one process to queue SYS$BATCH.
/AFTER=date-time
Indicates the date and time at which the build job begins execution. Specify the date and time using OpenVMS date-time syntax. Use this qualifier only if the BUILD command starts the build job: the qualifier specifies the start time for each batch job that is submitted to execute the build job./CONFIRM
/NOCONFIRM (default)
Controls whether VDE asks you to confirm that you want the build job started. The /CONFIRM qualifier causes VDE to print a message asking whether you want to start the build job. This message is displayed after VDE creates the build job and displays a message stating the size of the job. If you answer YES (or Y), the build job is started. If you answer NO (or N), the build job is not started. The /NOCONFIRM qualifier causes VDE to start the build job without asking for confirmation. Neither qualifier has any effect if you use the /NOSTART qualifier: /NOSTART unconditionally prevents VDE from starting the build job./FULL
Directs the BUILD command to perform a full build of your software system. In a full build, all source modules that contribute to the target modules you specified are compiled or otherwise processed. If you do not specify the /FULL qualifier, the BUILD command performs a minimal system build, which means that only the source modules that have changed since the last build of the specified target modules are compiled or processed. A minimal build is normally much quicker than a full build because it performs only the minimal work needed to propagate your source changes to the target modules./LOG (default)
/NOLOG
Controls whether log messages are printed after the build job is created and submitted to batch queues for execution. The /LOG qualifier causes such messages to be printed and the /NOLOG qualifier suppresses them. These messages indicate that the build job has been created, that the database transaction has successfully committed, and that batch jobs have been submitted to various batch queues to execute the build job./PROCESS_COUNT=proc-count
Specifies the number of processes to execute the build job. 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. 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, the /PROCESS_COUNT qualifier states the total number of build-job processes to create. In that case, the process counts attached to the queue-name parameters on the /QUEUE qualifier are 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 the new build job. The quoted remark string, which can be up to 132 characters long, may contain any explanatory remark about the build job that you want to store in the database./START (default)
/NOSTART
Controls whether the build job is started or not. The /START qualifier starts the build job, which means that VDE submits batch jobs to the appropriate OpenVMS batch queues. These batch jobs run programs that execute all the build steps that make up the build job. The /NOSTART qualifier prevents VDE from submitting the batch jobs. If you use the /NOSTART qualifier, you can start the build job later with the START 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 a 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.When multiple processes run a build job, one process may be idle until a second process completes its current build step. In that situation, the first process periodically looks in the database to see if the second process has finished its step. The step-delay interval determines how often the first process looks in the database for an available step.
Use the following syntax to denote the number of hours, minutes, and seconds in the interval:
/STEP_DELAY=hh:mm:ss.ssFor example, an interval of three and one half seconds is specified as follows:
Usually the interval is set at a few seconds. If this qualifier is not specified, VDE uses the default step-delay interval of the stream. If no default has been specified, the delay interval is five seconds.
/STEP_DELAY=00:00:03.50/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.Normally, a build job only times out if a node that is running one of the build-job processes fails. When a node fails, other build-job processes may be unable to proceed because they are waiting for a build step that ran on the failed node to complete, which will not happen. In that case, after the timeout interval expires, one of the waiting processes marks the build job as timed out, after which the remaining processes terminate themselves. You can later restart the build job using the START BUILD_JOB command.
Use the following syntax to denote the number of hours, minutes, and seconds in the interval:
/TIMEOUT=hh:mm:ss.ssFor example, an interval of two and one half hours is specified as follows:
The length of the timeout interval should be set based on the length of the longest build step in the build job. If this qualifier is not specified, VDE uses the default timeout interval of the stream. If no default has been specified, the timeout interval is one hour.
/TIMEOUT=02:30:00.00
| #1 |
|---|
VDE„ BUILD FOO.EXE
%VDE-I-BLDJOBCRE, build job 1 for stream BL22 has been created
%VDE-I-BLDJOBSIZ, build job 1 for stream BL22 consists of 5 steps
%VDE-I-COMMIT, database transaction has successfully committed
%VDE-I-BLDJOBSTARTING, starting build job 1 for stream BL22
%VDE-I-BLDJOBENT, entry number 308 submitted to queue SYS$BATCH
Job VDEBUILD_0001 (queue CLUSTER_BATCH, entry 308) started on PHI_BATCH
%VDE-I-BLDJOBSTARTED, build job 1 for stream BL22 started with 1 processes
VDE„
|
This example performs a minimal system build to build module FOO.EXE. The created build job is build job 1 for stream BL22. The build job consists of five build steps, such as compile and link steps. Because the /NOSTART qualifier is omitted, the build job is started on the default queue for the stream, SYS$BATCH. The build job runs on only one process.
| #2 |
|---|
VDE„ BUILD/FULL/NOSTART BLDGRP
%VDE-I-BLDJOBCRE, build job 2 for stream BL22 has been created
%VDE-I-BLDJOBSIZ, build job 2 for stream BL22 consists of 125 steps
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
|
In this example, build job 2 for the default stream, BL22, is created. This is a full build (not a minimal build) that builds all modules that are members of build group BLDGRP. This build requires 125 build steps. The build job is not started because the /NOSTART qualifier is specified. (To start it later, use the START BUILD_JOB command.) Although the build job is not started, it exists in the database so you can display information about it using the SHOW BUILD_JOB command.
| #3 |
|---|
VDE„ BUILD/PROCESS_COUNT=3 *.EXE
%VDE-I-BLDJOBCRE, build job 2 for stream V2.0-3 has been created
%VDE-I-BLDJOBSIZ, build job 2 for stream V2.0-3 consists of 25 steps
%VDE-I-COMMIT, database transaction has successfully committed
%VDE-I-BLDJOBSTARTING, starting build job 2 for stream V2.0-3
%VDE-I-BLDJOBENT, entry number 317 submitted to queue SYS$BATCH
Job VDEBUILD_0001 (queue CLUSTER_BATCH, entry 317) started on PHI_BATCH
%VDE-I-BLDJOBENT, entry number 318 submitted to queue SYS$BATCH
Job VDEBUILD_0001 (queue CLUSTER_BATCH, entry 318) started on FOO_BATCH
%VDE-I-BLDJOBENT, entry number 319 submitted to queue SYS$BATCH
Job VDEBUILD_0001 (queue CLUSTER_BATCH, entry 319) started on FUM_BATCH
%VDE-I-BLDJOBSTARTED, build job 2 for stream V2.0-3 started with 3 processes
VDE„
|
This example creates and starts a build job that builds all executable images for the default stream. It runs the build job with three parallel processes, all submitted to queue SYS$BATCH. The batch jobs execute on three separate batch queues, in this case on separate nodes in a cluster.
| #4 |
|---|
VDE„ BUILD/QUEUE=(PHI_BATCH,FOO_BATCH(2),FUM_BATCH) *.EXE
%VDE-I-BLDJOBCRE, build job 3 for stream V2.0-3 has been created
%VDE-I-BLDJOBSIZ, build job 3 for stream V2.0-3 consists of 25 steps
%VDE-I-COMMIT, database transaction has successfully committed
%VDE-I-BLDJOBSTARTING, starting build job 3 for stream V2.0-3
%VDE-I-BLDJOBENT, entry number 417 submitted to queue PHI_BATCH
Job VDEBUILD_0001 (queue PHI_BATCH, entry 417) started on PHI_BATCH
%VDE-I-BLDJOBENT, entry number 418 submitted to queue FOO_BATCH
Job VDEBUILD_0001 (queue FOO_BATCH, entry 418) started on FOO_BATCH
%VDE-I-BLDJOBENT, entry number 419 submitted to queue FOO_BATCH
Job VDEBUILD_0001 (queue FOO_BATCH, entry 419) started on FOO_BATCH
%VDE-I-BLDJOBENT, entry number 420 submitted to queue FUM_BATCH
Job VDEBUILD_0001 (queue FUM_BATCH, entry 420) started on FUM_BATCH
%VDE-I-BLDJOBSTARTED, build job 3 for stream V2.0-3 started with 4 processes
VDE„
|
Like the previous example, this example creates and starts a build job that builds all executable images. In this case, the /QUEUE qualifier specifies that four batch jobs are submitted: one to batch queue PHI_BATCH, two to queue FOO_BATCH, and one to queue FUM_BATCH. These queues belong to specific nodes in the cluster. As a result, the /QUEUE qualifier determines precisely how the build job is distributed across the nodes of the cluster.
| #5 |
|---|
VDE„ BUILD/CONFIRM FOO.EXE
%VDE-I-BLDJOBCRE, build job 8 for stream BL22 has been created
%VDE-I-BLDJOBSIZ, build job 8 for stream BL22 consists of 2 steps
%VDE-I-COMMIT, database transaction has successfully committed
Start build job 8 for stream BL22 ? [No]: YES
%VDE-I-BLDJOBSTARTING, starting build job 8 for stream BL22
%VDE-I-BLDJOBENT, entry number 79 submitted to queue SYS$BATCH
Job VDEBUILD_0001 (queue CLUSTER_BATCH, entry 79) started on PHI_BATCH
%VDE-I-BLDJOBSTARTED, build job 8 for stream BL22 started with 1 processes
VDE„
|
The /CONFIRM qualifier causes VDE to ask the user whether to start the new build job. VDE asks the question after creating the build job and after displaying its size (in this example, only two steps). The user answers YES and VDE starts one process for the build job on queue SYS$BATCH.
Cancels a directory template in the VDE database. Directory templates determine what disk directories VDE creates when creating new development streams and facilities.
CANCEL DIRECTORY
The CANCEL DIRECTORY command deletes a "directory template" from the VDE database. Directory templates are defined with the SET DIRECTORY command and specify the names that VDE should assign to disk directories when creating directories for new development streams or facilities or for the library's queued-replacement staging area. The CANCEL DIRECTORY command can delete all templates that the SET DIRECTORY command can create. The CANCEL DIRECTORY command does not delete or otherwise affect existing disk directories, however.Unless the cancelled template is for the library's delta files or its staging area, it is only cancelled for the default development stream. Because directory templates are inherited by a stream's descendants, the CANCEL DIRECTORY command will affect the disk directories created for all future descendants of the default stream. It may also affect the directories created for new facilities in the default stream.
When you have cancelled a directory template, VDE uses its default rules to create directory trees for subsequent streams and facilities. VDE always creates stream, facility, and delta-file root directories, whether there are templates for such directories or not. VDE does not create facility subdirectories unless there are templates for them, however, so if you cancel a subdirectory template, you prevent that subdirectory from being created for new streams or facilities.
For additional information on directory creation, and on directory symbols (dir-symbol) and directory symbol processing, see SET DIRECTORY, SHOW DIRECTORY, and Script Functions.
/DELTA_FILES
/STAGING
/STREAM (default)
Specifies whether a directory template for delta files, the staging area, or the default stream is deleted. The /DELTA_FILES qualifier specifies that a directory template for the VDE library's delta files (CMS libraries) be deleted. The /STAGING qualifier specifies that the directory template for the library's staging-area root directory be deleted. (Staging areas hold files for queued replacements.) The /STREAM qualifier specifies that a directory template for the default stream be deleted.Of /DELTA_FILES, /STAGING and /STREAM, the latter is the default.
/FACILITY=fac-name
Specifies that a directory template for the facility specified by the fac-name parameter be deleted. If both this qualifier and the /SUBDIRECTORY qualifier are specified, VDE deletes the directory template for the specified facility subdirectory. If the /FACILITY qualifier is specified and the /SUBDIRECTORY qualifier is omitted, VDE deletes the directory template for the specified facility's root directory.If the /FACILITY qualifier is omitted and the /SUBDIRECTORY qualifier is specified, VDE deletes the directory template for the given facility subdirectory for all facilities that are not explicitly specified in other templates. If both the /FACILITY qualifier and the /SUBDIRECTORY qualifier are omitted, VDE deletes the template for the stream or delta-file root directory.
You can delete more than one directory template at a time by using wildcard characters in the fac-name parameter. 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. Directory templates for those facilities whose names match the wildcard pattern are deleted.
/LOG (default)
/NOLOG
Controls whether log messages are printed after the directory template is deleted. The /LOG qualifier causes such messages to be printed and the /NOLOG qualifier suppresses them. These messages indicate that the directory template has been deleted from the database and that the database transaction has completed successfully./SUBDIRECTORY=dir-symbol
Specifies that a directory template for a facility subdirectory be deleted. The dir-symbol parameter specifies the directory symbol that identifies the subdirectory. Among other uses, the directory symbol is used within VDE scripts; see Script Keywords for further details. If this qualifier is omitted, VDE deletes the directory template for a facility, stream, or delta-file root directory. (The description of the /FACILITY qualifier explains how the qualifiers interact to select the template to delete.)
| #1 |
|---|
VDE„ CANCEL DIRECTORY/FACILITY=RMS
%VDE-I-DIRDEL, directory specification [MYDIR.RMS] deleted from database
%VDE-I-COMMIT, database transaction has successfully committed
VDE„
|
Previous Next Contents Index