| Previous[ | Contents] | Index |
;Defines a new build step in the VDE database. This command Glets you define a copy step or specify the input and output modules of a compile or link step.
>CREATE STEP step-mod-name = mod-name [, mod-name...]
step-mod-name
HThe name of the module that is compiled, copied, or linked by the build Gstep. This name consists of a module name and a type name separated by Ha period (such as MOD1.PAS) and may include a facility name enclosed in Dsquare brackets (such as [FACNAM]MOD1.PAS). The module name may not Ccontain wildcard characters. If no facility name is specified, the $current default facility is assumed.FIf the step is a compile step, this module is recorded as an input to Dthe step. If the step is a link step, this module is recorded as an Houtput of the step. If the step is a copy step, this module is recorded 7as the module that is copied (fetched out) by the step.
mod-name
GThe name of a module that you declare to be an input to or output from Dthe build step. This name consists of a module name and a type name D(for example, MOD1.OBJ) and may include a facility name enclosed in Hsquare brackets (for example, [FACNAM]MOD1.OBJ). If no facility name is 3specified, the current default facility is assumed.GYou can declare many modules to be inputs to or outputs from the build Fstep by specifying wildcard characters in any of the three components Fof the module name. The percent sign (%) in a name matches any single Hcharacter in the position it occupies and the asterisk (*) matches zero Dor more characters in the position it occupies. Those modules whose Fnames match the wildcard pattern are recorded as inputs to or outputs from the build step.
HIf an output module you specify does not already exist in the database, Dthe CREATE STEP command adds it to the database. Input modules must Halready be defined in the database, however. Also, you cannot specify a +source module as an output of a build step.
HIf you specify the /COPY qualifier to create a copy step, you must omit Fthe mod-name parameters and the preceding equal sign C(=). A copy step fetches a module from its CMS library, but has no 'inputs or outputs other than the module6given by the step-mod-name parameter.
=To be able to perform minimal system builds, VDE records all Einputs and outputs for each build step. This information is known as ?"build dependency information." The build dependency >information from all build steps is known collectively as the ;"build dependency graph." Normally, VDE collects Cbuild dependency information automatically when you perform system Dbuilds. However, for some build steps it is not possible to collect Fthis information automatically; some compilers and other tools do not 7make this information available to VDE. For such build ?steps, you must use the CREATE STEP command to enter the build -dependency information into the VDE database.HYou can define three kinds of build steps with the CREATE STEP command: =compile steps, link steps, and copy steps. A compile Fstep processes the step-mod-name module and Dpossibly other input modules to produce one or more output modules. CTypically, a compile step runs a compiler of some sort on a source Bmodule, but the exact semantics of the step are determined by the <VDE script that generates the DCL commands that perform the step.
*A link step produces the Hstep-mod-name module and possibly other output modules Gfrom one or more input modules. Typically, a link step runs the linker @to produce a shareable or executable image, but again the exact ;semantics are determined by the VDE script associated with Dthe step. Since a script can perform any action you want, a compile Fstep need not run a compiler and a link step need not run the linker. <To VDE, the only real difference between a compile step and Aa link step is that a compile step is named for one of the input Amodules while a link step is named for one of the output modules.
GA copy step copies the step-mod-name Cmodule from one place to another. Normally, a copy step is used to Cfetch out a source module from its delta file (CMS element) into a Eclear-copy file that can be used directly by subsequent build steps. DFor example, C programs generally include various .H files in their Gcompile steps. A copy step is needed for each .H file to fetch it from its CMS libraryBinto a text file that subsequent compile steps can use. Likewise, Elinker options files (.OPT files) must be fetched out before you can Huse them for subsequent link steps. You must create a copy step for any =module that must be fetched into the VDE library's directory Ftree during builds but which does not need any separate processing to Hproduce other output modules. For a copy step, the specified module can 5be seen as both the input and the output of the step.
CThe CREATE STEP command deletes all dependency information for the Fbuild step before recording the inputs and outputs you specify. Thus, >you can use the CREATE STEP command to completely replace the Ddependency information for a build step. To change only some of the ?dependency information for a step, use the MODIFY STEP command.
?Build dependency information is always specific to the default Gdevelopment stream. Different development streams in a software system Dcontain different versions of the code and generally have different build dependency graphs.
HTo define the same build step for more than one development stream, you Cmust use the CREATE STEP command for each stream. For each stream, Gfirst enter the SET STREAM command to set the development stream, then >enter the CREATE STEP command to enter the desired build-step dependencies into the database.
EWhen a new development stream is created, the build dependency graph @from the parent stream is copied to the child stream. The build ?dependency graph then evolves independently in the two streams.
/COMPILE (default)
/COPY
/LINK
GSpecifies whether the build step is a compile step, copy step, or link <step. The /COMPILE qualifier causes VDE to mark the step as @a compile step and to record the step-mod-name Fparameter as an input module to the compile step. The /COPY qualifier =causes VDE to mark the step as a copy step and to record the Fstep-mod-name parameter as the module that is copied =by the step. The /LINK qualifier causes VDE to mark the step @as a link step and to record the step-mod-name /parameter as an output module of the link step.6Of /COMPILE, /COPY and /LINK, /COMPILE is the default.
/INPUT (default)
/OUTPUT
HSpecifies whether the mod-name parameters are recorded Bas inputs to or outputs from the build step. The /INPUT qualifier Frecords modules as inputs to the build step and the /OUTPUT qualifier Grecords them as outputs of the step. If no qualifier is specified, all !modules are assumed to be inputs.ETo set the default for the command as a whole, specify the qualifier Fafter the CREATE STEP keywords. To override that default for a single Bmodule, specify the qualifier after the mod-name 3parameter you choose to mark as an input or output.
-Of /INPUT and /OUTPUT, /INPUT is the default.
/LOG (default)
/NOLOG
BControls whether log messages are printed after the build step is Grecorded in the database. The /LOG qualifier causes the messages to be Hprinted and the /NOLOG qualifier suppresses them. The messages indicate Ethat the build step has been created, that the specified modules are Finputs or outputs for the step, and that the database transaction has committed successfully.
6
| #1 |
|---|
*VDEä CREATE STEP FOO.MAR = FOO.$OBJ/OUTPUTE%VDE-I-COMSTEPADDED, compile step for [CODE]FOO.BAR added to databaseD%VDE-I-MODINSTEP, module [CODE]FOO.MAR is an input to the build stepI%VDE-I-MODOUTSTEP, module [CODE]FOO.$OBJ is an output from the build step>%VDE-I-COMMIT, database transaction has successfully committedVDEä |
6DThis command creates a build step definition for the compilation of @module FOO.MAR. The step is a compile step because the /COMPILE Fqualifier is the default. FOO.MAR is recorded as an input to the step Gand module FOO.$OBJ is recorded as an output from the step, as the log messages show.
| #2 |
|---|
?VDEä CREATE STEP/LINK MOD1.EXE = MOD1.$OBJ, MOD2.$OBJ, FOO.$OBJC%VDE-I-LNKSTEPADDED, link step for [CODE]MOD1.EXE added to databaseI%VDE-I-MODOUTSTEP, module [CODE]MOD1.EXE is an output from the build stepF%VDE-I-MODINSTEP, module [CODE]MOD1.$OBJ is an input to the build stepF%VDE-I-MODINSTEP, module [CODE]MOD2.$OBJ is an input to the build stepE%VDE-I-MODINSTEP, module [CODE]FOO.$OBJ is an input to the build step>%VDE-I-COMMIT, database transaction has successfully committedVDEä |
6DThis command creates the build dependency information for the build Fstep that links module MOD1.EXE. Module MOD1.EXE is the output of the Cstep and modules MOD1.$OBJ, MOD2.$OBJ, and FOO.$OBJ are the inputs.
| #3 |
|---|
JVDEä CREATE STEP/COMPILE/OUTPUT [CODE]MOD4.FOR = MOD4.$OBJ, [CODE]MOD4.LISF%VDE-I-COMSTEPADDED, compile step for [CODE]MOD4.FOR added to databaseE%VDE-I-MODINSTEP, module [CODE]MOD4.FOR is an input to the build stepJ%VDE-I-MODOUTSTEP, module [CODE]MOD4.$OBJ is an output from the build stepI%VDE-I-MODOUTSTEP, module [CODE]MOD4.LIS is an output from the build step>%VDE-I-COMMIT, database transaction has successfully committed VDEä SHOW STEP/FULL MOD4.FOR&Compile Step for module [CODE]MOD4.FOR* Dependency links for stream V2.1 follow Inputs to the build step: Module [CODE]MOD4.FOR Outputs from the build step: Module [CODE]MOD4.$OBJ Module [CODE]MOD4.LIS( Build step has 1 inputs and 2 outputs VDEä |
6HThe CREATE STEP command defines the compile step for module MOD4.FOR in Cfacility CODE as having one input module (MOD4.FOR) and two output Fmodules (MOD4.$OBJ and MOD4.LIS). The SHOW STEP command confirms that 8these build dependencies have been entered into the VDE database.
| #4 |
|---|
"VDEä CREATE STEP/COPY [CODE]MOD5.HA%VDE-I-COPSTEPADDED, copy step for [CODE]MOD5.H added to databaseC%VDE-I-MODINSTEP, module [CODE]MOD5.H is an input to the build stepG%VDE-I-MODOUTSTEP, module [CODE]MOD5.H is an output from the build step>%VDE-I-COMMIT, database transaction has successfully committedVDEä |
EThis example creates a copy step for module MOD5.H in facility CODE. ;VDE records the specified module as both the input and the Houtput of the step since a copy step simply copies the specified module ?from one form to another (normally from its delta-file form to text-file form).
8Creates a development stream in the current VDE library.
6CREATE STREAM stream-name [, stream-name...]
stream-name
>The name of a stream to be created. This name can be up to 39 8characters long. It must follow VDE name syntax. Unlike :other VDE names, the stream name can contain periods (.). EThe use of the facility prefix VDE$ is expressly prohibited.
>A development stream (or simply, a "stream") is any Bseparately evolving version of your software system. A stream may Bcorrespond to a previous or future version of your system or to a Cbase-level of the system. It may correspond to any instance of the Hsystem that evolves separately from the rest of the system. Each stream Fof your software system captures a different state of the system, and 4that state may evolve independently for each stream.EEach stream of your software system contains its own versions of all Fmodules in the system, and you may change these modules independently Fin each stream. Each stream also contains its own versions of various Adatabase tables, such as group definitions and module dependency Einformation. This information may also evolve independently for each stream.
EWhen you create a stream, the CREATE STREAM command first creates an =entry for the new stream in the VDE database. It then copies Hall stream-specific information from the parent stream (by default, the Gdefault stream) to the new stream (the child stream). This information @includes directory-creation rules, group definitions, the build Gdependency graph, and information about what module generations belong Fto the parent stream. In addition, the CREATE STREAM command executes Gscripts which may copy files from the parent stream's disk directories "to the child stream's directories.
;There are several key attributes to VDE module propogation Ccontrolled by the CREATE STREAM command, including the sequence of Astreams on the various lines of descent, and the presence of the Gparticular stream on the main line of development or on a variant line Dof descent. The former is controlled by the parentage and successor ?settings, and the latter is controlled by the mainline setting.
/
Note
HThe CREATE STREAM command can and does perform specific and potentially 6non-reversable modifications to the internal VDE data :associated with other streams present in the VDE Bdatabase, particularly around the /MAIN and /NOMAIN settings, and Faround the /PARENT and /SUCCESSOR settings. The CREATE STREAM command should be used with caution.FThe explicit specification of the appropriate value for the /[NO]MAIN Dqualifier (/MAIN or /NOMAIN) on a CREATE STREAM command is strongly recommended.
/CMS_CLASS
/NOCMS_CLASS(default)
FSpecifies whether a CMS class with the same name as the stream should Fbe maintained in each facility's CMS library. The /CMS_CLASS qualifier8causes VDE to create a CMS class for the stream in each Hfacility's CMS library and to then maintain that class when the REPLACE Bcommand and certain other commands change what module generations <belong to the stream. The /NOCMS_CLASS qualifier causes VDE +to not maintain a CMS class for the stream.@The /CMS_CLASS qualifier interacts with the /INIT_CMS_CLASS and G/NOINIT_CMS_CLASS qualifiers; see the descriptions of these qualifiers for details.
/CONFERENCE=file-spec
/NOCONFERENCE(default)
=Specifies whether a OpenVMS Notes conference for replacement Finformation should be associated with the new stream. The /CONFERENCE Gqualifier specifies that the notes conference file specification given Eby the file-spec parameter should be used to record =all replacements into the stream. VDE then enters a new note Cinto the conference for each queued or immediate replacement and a Greply to that note when a queued replacement is actually performed. TheG/NOCONFERENCE qualifier specifies that no such notes conference should be used.FUnder normal circumstances, just the file name should be specified in 6the file-spec parameter. VDE applies Adefaults to the notes conference file specification based on the 2translation of the logical name VDE$NOTES_LIBRARY.DIf this logical name is not defined, the default file specification 2"NOTES$LIBRARY:.NOTE" is applied to the %file-spec parameter.
/DEFER
/NODEFER (default)
GSpecifies whether the creation of the disk directory structure for the Gstream should be postponed. The /DEFER qualifier postpones creation of Hthe disk directory structure and the /NODEFER qualifier causes the disk Hdirectory structure to be created immediately. Use the /DEFER qualifier Bwhen the default directory structure is inappropriate for the new stream.CIf the /NODEFER qualifier is specified (or /DEFER is omitted), the CCREATE STREAM command creates the disk directory structure for the @stream. This structure includes a stream root directory, a root Gdirectory for each facility, and facility subdirectories that hold the Cfiles that are the contents of the facility in the new stream. The Hdirectory structure is determined by the SET DIRECTORY commands entered ?for the new stream (or inherited from the parent stream) or by 0VDE default rules. Once VDE has created the new <stream's directory structure for a given facility, VDE runs Bthe stream's new-stream script for that facility, provided such a Cscript is defined. Depending on how it is defined, this script may Cpopulate the directories for that facility with source modules and other files.
EIf the /DEFER qualifier is specified, the CREATE STREAM command does Dnot create a directory structure for the new stream. If you use the F/DEFER qualifier, you can enter SET DIRECTORY commands to specify the Fstructure of the disk directories. Then use the CREATE DIRECTORY_TREE >command to create the directory structure on disk. The CREATE ;DIRECTORY_TREE command uses VDE defaults and the rules you Fspecified with the SET DIRECTORY commands to create the new directory structure.
/DELETE
/NODELETE
FControls whether the delete attribute is set for the Dnew stream. This attribute allows the stream to be deleted with the GDELETE STREAM command. The /DELETE qualifier sets the delete attribute Fso that the new stream can be deleted. The /NODELETE qualifier clears Ethe delete attribute so that the new stream cannot be deleted unless Hyou first reset this attribute with a MODIFY STREAM command. This makes Bit harder to accidentally delete a stream. If you specify neither <qualifier, VDE uses the value of the allow-deletion library Fattribute as the initial value of the stream's delete attribute. This Hlibrary attribute is set with the /ALLOW_DELETE qualifier to the CREATE and MODIFY LIBRARY commands./DIRECTORY=dir-spec
ASpecifies the name of the root directory of the stream. The root Cdirectory normally contains a subdirectory for each facility. Each Gsubdirectory has additional subdirectories for the sources and derived 8files of the facility and stream. (To modify the defaultBdirectory structure, first use the CREATE STREAM command with the F/DEFER qualifier then use the SET DIRECTORY and CREATE DIRECTORY_TREE >commands to create the directory structure you want.) Use the 6OpenVMS directory specification format to specify the $dir-spec parameter./INIT_CMS_CLASS
/NOINIT_CMS_CLASS
8Specifies whether VDE initializes the CMS class for the Dstream in each facility's CMS library when the /CMS_CLASS qualifier specifies that suchGa class should be maintained. /INIT_CMS_CLASS causes the CREATE STREAM Eor MODIFY STREAM command with the /CMS_CLASS qualifier to create and Hpopulate a CMS class with the same name as the stream in each facility. G/NOINIT_CMS_CLASS causes these commands to not create or populate such <CMS classes. /NOINIT_CMS_CLASS is useful for very large VDE Flibraries where the initialization of CMS classes take an excessively Flong time. For such libraries, it is better to use a separate command Fprocedure to initialize the desired CMS classes; such a procedure can >process the facilities of your library in parallel for faster completion.9If you specify neither of these qualifiers, VDE uses the Hinitialization attribute of the new stream's parent stream. By default, 8the initial stream for the VDE library (stream MAIN) is Gcreated with initialization enabled (in effect, /INIT_CMS_CLASS is the Cdefault). All other streams will inherit this attribute unless you 7change it with an explicit /NOINIT_CMS_CLASS qualifier.
GUnless you have existing command procedures or programs that depend on Fthe presence of CMS classes, Digital recommends that you not maintain =CMS classes for the streams in your VDE library. Maintaining ECMS classes is quite slow, especially when creating new streams, and 7VDE does not need CMS classes for any of its functions.
/LOG (default)
/NOLOG
@Controls whether log messages are printed after new streams are Fcreated. The /LOG qualifier causes the messages to be printed and the F/NOLOG qualifier suppresses them. The messages indicate that each new Dstream has been created, that its disk directory structure has been Fcreated, and that the database transaction has successfully committed./MAIN
/NOMAIN (default)
HSpecifies whether the new stream is part of the main development thread Gfor your project. The /MAIN qualifier says that the new stream is part Hof the main development thread for the project and is expected to be in Guse for a relatively long time, and is expected to be in use after the 8parent stream has been closed. VDE assigns the shortest Hpossible CMS "generation expressions" to new generations in a Hmain stream. The /NOMAIN qualifier says that the new stream is not part Cof the project's main development thread and is expected to have a >shorter future lifetime than the parent stream. In this case, <VDE may assign longer CMS generation expressions (using CMS H"variant letters") to future module generations in the stream.GYou normally use the /MAIN qualifier when you create a stream for your Cproject that will be the future continuation of the parent stream. FCreating stream V2.0 from stream V1.0 is an example since development Eof Version 1.0 of your project will cease as Version 2.0 carries the Gproject into the future. You use the /NOMAIN qualifier when you create Gbase levels or other streams that are expected to have short lifetimes compared to the parent stream.
AIf you specify the /MAIN qualifier, the new stream automatically Hbecomes a successor of the parent stream so that changes are propagated Ffrom the parent to the new stream. If you specify the /MAIN qualifier Ebut you do not specify the /SUCCESSOR or /NOSUCCESSOR qualifier, the Emain streams that are successors of the parent stream are removed as Esuccessors of the parent stream and instead become successors of the Cnew stream. The effect is that the new stream is inserted into the Dsuccessor chain after the parent stream. If you specify the /NOMAIN )qualifier, no such insertion takes place.
HFor information on changing the main line of descent attribute specific Gto a particular module generation, see the documentation on the MODIFY fGENERATION/MAIN_STREAM command in MODIFY GENERATION.
/
Specification
CExplicit specification of /[NO]MAIN is not currently required, but Eexplicit specification of this qualifier may be required in a future /release of VDE. Explicit specification of this Cqualifier---either as /MAIN or as /NOMAIN---is highly recommended./NOGENERATIONS
FSpecifies that the new stream should not be populated with the latest Ggenerations of the parent stream. If you use this qualifier, you get a Bnew stream containing no generations. If you omit this qualifier, <VDE populates the new stream with the latest generations of the parent stream.*/NOTIFY=(username [,username...])
GSpecifies users to notify of all changes replaced into the new stream. ?Each username parameter specifies the OpenVMS Busername or mail address of a user who should be notified by mail Hmessage each time a module is replaced into the stream, and each time a &new facility is created in the stream.GEach username parameter can specify the username of a 5user already recorded in the VDE database, a OpenVMS Gmail address with one or more node names (such as NODE::SMITH), a mail Hforwarding alias, or a defined logical name bound to a list of users to Enotify. If you specify a logical name, keep in mind that the logical @name must be defined when it is later used to send notification Hmessages. It should thus be a group or system logical name or a logical <name that is in some other way defined for all users of the VDE library.
EIf you specify only one username parameter, you may !omit the surrounding parentheses.
/OPEN (default)
/FROZEN
/CLOSED
FDetermines the status of the new stream: open, frozen, or permanently Fclosed. If you specify the /OPEN qualifier, all users can reserve and Greplace source modules from the stream and thereby modify the contents of the stream.DIf you specify the /FROZEN qualifier, all users may reserve modules Bfrom the stream. However, a user must have the FROZEN privilege toHreplace modules into the stream; non-privileged users cannot change the Econtents of the stream. You can later change the status to open with Cthe MODIFY STREAM command, so the stream is not permanently frozen.
FIf you specify the /CLOSED qualifier, modules cannot be reserved from Bor replaced into the stream. This status cannot be changed with a Gsubsequent MODIFY STREAM command unless you have the UNCLOSE privilege.BUse the /CLOSED qualifier when you never want the contents of the Dstream to change again, for example, when capturing a base-level of Eyour software system or when capturing the final state of a released version of your software.
4Of /OPEN, /FROZEN and /CLOSED, /OPEN is the default.
/OWNER=username
ESpecifies the owner of the new stream. The username Aparameter specifies the OpenVMS username of a user who should be :considered to be the "owner" of the stream. VDE Bassigns no special meaning to the owner of a stream, but the SHOW FSTREAM command displays the owner. The owner could thus be the person +to contact with questions about the stream.9If you omit this qualifier, VDE records no owner for the stream.
/PARENT=stream-name
HSpecifies the parent of the new stream. If this qualifier is specified, Athe stream-name parameter gives the name of the Edevelopment stream that should be the parent of the new stream being Fcreated. If this qualifier is omitted, the default stream becomes the parent of the new stream.FCorrect specification of this qualifier is of central importance when Huploading facilities and streams from an existing set of CMS libraries. 1See the CREATE FACILITY/FROM_CMS_LIBRARY command.
%Specification of /PARENT is required.
/POPULATE (default)
/NOPOPULATE
=Specifies whether the stream is allowed to be populated with Cgenerations from another stream using the POPULATE STREAM command. B/POPULATE allows subsequent use of the POPULATE STREAM command to 7populate the stream and /NOPOPULATE disallows such use."/PROCESS_COUNT=proc-count
HSpecifies the default number of processes to execute build jobs for the Hnew stream. This parameter determines the degree of parallelism for the Dstream's build jobs. See the description of the BUILD command for a 'detailed description of this qualifier.-/QUEUE=(queue-name [,queue-name...])
CSpecifies the default batch queues to which build jobs for the new Estream are submitted. See the description of the BUILD command for a Ddetailed description of this qualifier and for a description of its .interaction with the /PROCESS_COUNT qualifier./REMARK="string"
FSpecifies a remark string to be stored for the new stream. The quoted Gremark string, which can be up to 132 characters long, may contain any Dexplanatory remark about the new stream that you want stored in the <VDE database. Typically the remark indicates the version or base-level of your system.
q
PreviousX Next[ Contents] Index