If you are the project leader for a stream, you must create new build streams from time to time so you can build OpenVMS for your release. You may also have to create the stream you are project-leading. This section tells you how to perform these operations.

Streams are classified into build streams, and into release streams. Build streams are used for builds and establish the files involved with each build, and are usually of interest only to those engineers directly involved with source code builds. Release streams are of general interest to all VDE or VSC users, as they are the streams used for managing source code development.

5.7.1 Creating Build Streams

To create a build stream for the development stream that you project lead, you must perform two operations: Create the build stream in the VSC database and create a CMS class for that build stream. To create the build stream in the VSC database, use the CREATE STREAM command. If you are the project leader for stream BIRCH, for example, you could use the following command to create a build stream:

VSC„ CREATE STREAM BIRCH_BUILD - _VSC„ /PARENT=BIRCH /CMS_CLASS - _VSC„ /REMARK="Build stream"

This example creates build stream BIRCH_BUILD and specifies that its parent is stream BIRCH. This means that stream BIRCH_BUILD will be created with the same module generations as stream BIRCH currently has. Once you have created the new stream, the two streams can diverge; the next replacement into BIRCH, for example, will make it different from stream BIRCH_BUILD.

The CREATE STREAM command does not create a CMS class for the stream, but the /CMS_CLASS qualifier specifies that a CMS class for each facility should be maintained for the new stream as that stream is modified with future VSC commands (such as INSERT or DELETE GENERATION). How you create the CMS class initially is discussed shortly.

Specification of a remark is required; if you omit the /REMARK qualifier, VSC prompts you for a remark string.

For the OpenVMS VAX VDE library, the CREATE STREAM command takes about 20 minutes. You should run this command after you have performed all replacements that you want included in the build stream. It is best to run this command at less-busy times as it locks parts of the VSC database and can therefore prevent access by other users for various operations.

To create and populate a CMS class in each facility for the new stream, you must run the SYSBLDCOM$:POPULATE_LIBRARIES.COM command procedure. This procedure submits a separate batch job for each OpenVMS facility in order to populate the desired class as fast as possible. The whole operation is still time-consuming; it takes about four hours for the OpenVMS VAX library. To run this command procedure, enter the following command at DCL level:

$ @SYSBLDCOM$:POPULATE_LIBRARIES.COM BIRCH_BUILD BIRCH

This command procedure should be run after normal working hours. While it runs, you cannot modify stream BIRCH by replacing modules or inserting generations into it. You must ensure that no PERFORM REPLACEMENT commands run that can affect stream BIRCH, directly or through change propagation. However, you can (and preferrably should) run the CREATE STREAM command for the new build stream at the same time. It is important that the VSC database is updated and the CMS classes are created at the same time so that they are consistent with each other.

If you already have an existing CMS class you want to reuse, you can use the SYSBLDCOM$:POP_REUSED_CLASS.COM command procedure instead. Its invocation is similar to that of POPULATE_LIBRARIES; the comments in the procedure give the details.

5.7.2 Creating Release Streams

To create a development stream for a new OpenVMS release (in other words, a stream that most OpenVMS developers will use to reserve and replace modules), you must make a number of decisions:

• decide what the parent stream will be. Preservation and continuity of the mainline is particularly important to modules on the mainline. Proper specification of stream parentage is of critical and central importance when the /FROM_CMS_LIBRARY qualifer is to be used on any subsequent CREATE FACILITY commands.
• decide if the stream should become the latest stream on the mainline, or if it should be treated as a variant branch and be located somewhere off the mainline. Exactly one stream in the VSC database is the mainline stream, while there can be many streams feeding into the mainline stream---these other streams are sometimes confusingly refered to as being "on the mainline".
• Create the stream in the VSC database, create the CMS class associated with it, and specify the stream's change propagation behavior.
• Decide if you want propogation of modules from the parent stream. By default, such propogation is enabled.
• You may also want to specify developers who should review replacements or be notified of replacements going into the new stream.

To create the stream, use the CREATE STREAM command, much the same as explained in Section 5.7.1 for build streams. To create a new development stream MAPLE, for example, you might enter the following command:

VSC„ CREATE STREAM MAPLE - _VSC„ /OWNER=SMITH - _VSC„ /PARENT=BIRCH /MAIN - _VSC„ /CMS_CLASS /REPLACEMENT=QUEUE - _VSC„ /REMARK="New-feature stream"

This command specifies that the parent of the new mainline stream MAPLE is the existing stream BIRCH. The newly created MAPLE mainline stream initially inherits all current generations from the parent BIRCH stream.

The use of the /OWNER qualifier specifies the owner of the new stream; this person is typically the stream's project leader. If you use this qualifier, developers can later use the SHOW STREAM command to determine the stream's owner.

The /MAIN qualifier causes the new stream to become the last stream on the main line of descent, and it causes VSC to use whole-number CMS generation expressions for the stream. /MAIN also causes VSC to update all successor stream links to link to this new mainline stream.

The /PARENT qualifier is informational in some cases, but can be critical during certain VSC operations such as CMS facility uploads. It should always be specified, and it should always specify the correct parent stream.

Just as for build streams, the /CMS_CLASS qualifier specifies that a CMS class in each facility should be maintained for the stream.

The /REPLACEMENT qualifier specifies that the new stream requires all replacements into the stream to be queued (as opposed to immediate) replacements. Queued replacements go through the VSC review mechanism and give you control over when replacements are actually performed. The /REMARK qualifier specifies a remark string for the stream; if you omit this qualifier, VSC prompts you for a remark string.

As explained in Section 5.7.1, the CREATE STREAM command does not create and populate the CMS class for the stream. Instead, you must submit the SYSBLDCOM$:POPULATE_LIBRARIES.COM or SYSBLDCOM$:POP_REUSED_CLASS.COM command procedure at DCL level to create and populate a CMS class for the stream in each facility. Section 5.7.1 describes how you use these procedures. One of these procedures should be run at the same time as you run the CREATE STREAM command, and you must ensure that no VSC commands that update the parent stream run at that time.

When you create a new development stream, you often want to specify that future replacements into some previously existing stream should be propagated to the new stream. For example, if stream MAPLE is created from stream BIRCH, you may want all future changes to BIRCH to be propagated to MAPLE so that MAPLE will contain all features and bug fixes that BIRCH contains. As a later stream, MAPLE will presumably also receive new features that are omitted from BIRCH. To specify this sort of stream successor relationship, you use the /SUCCESSOR qualifier to the MODIFY STREAM command. This is an example:

VSC„ MODIFY STREAM BIRCH /SUCCESSOR=MAPLE

This command specifies that stream MAPLE is a successor to stream BIRCH. As a result, all code changes replaced into BIRCH will automatically be propagated to MAPLE if possible. If automatic change propagation is not possible for a given module replacement, VSC will create a fold record in its database.

You can specify multiple successors for a given stream if that is the behavior you want. To do so, specify a parenthesized list of stream names separated by commas with the /SUCCESSOR qualifier. Alternatively, specify each successor stream with a separate MODIFY STREAM command. To cancel successor relationships, use the /NOSUCCESSOR qualifier to the MODIFY STREAM command. (The HELP text has the details.)

To confirm that you have established the successor relationships correctly, use the /SUCCESSOR qualifier to the SHOW STREAM command. This example illustrates its output:

VSC„ SHOW STREAM/SUCCESSOR BIRCH, MAPLE Stream BIRCH Successor chains: BIRCH -> MAPLE Stream MAPLE Successor chains: MAPLE (no successors) VSC„

This output shows that stream MAPLE is a successor to stream BIRCH and that stream MAPLE does not itself have any successors. Because this is the desired successor relationship, VSC will perform change propagation correctly for these streams.

When you create a new release stream, you should also determine whether you want certain developers to review or be notified of all replacements into the stream. In particular, you probably want to be notified of all such replacements yourself. To specify the reviewers and developers to notify, use the /REVIEWER and /NOTIFY qualifiers to the CREATE STREAM or MODIFY STREAM command. Section 5.6 describes these qualifiers.

5.7.3 Example Stream Creations

The following code example shows how an OpenVMS development stream is created and populated. The example is typical of an OpenVMS mainline development stream.

The steps outlined below create a new mainline stream int the OpenVMS database, and a matching mainline stream in the OpenVMS test database. It temporarily disables propogation from the parent stream, as populating the stream can require some time. It then populates the new mainline streams, disables propogation into the new mainlines to prevent unintentional overwriting, and finally resets the proper propogation attribute on the parent stream.

These operations should be performed only when the VSC database is quiescent, as one typically wishes all modifications to the parent database to be propogated into the new stream.

$ VDE Set Library VMS$ Create Stream - /CMS_CLASS/NOINIT_CMS_CLASS - /noGENERATION - /DEFER - /MAIN - ! warning: alters generation selection /Populate - /Frozen - /Conference=YELLOW$NOTES:DRAGON-YELLOW.NOTE - /PARENT=CORAL - /NoSuccessor - /REPLACEMENT=QUEUE - /REMARK="Post-CORAL release stream"- DRAGON Modify Stream DRAGON - /Reviewer=(projectleader) - /NOTIFY=(projectleader,DRAGONbld) - DRAGON Modify Stream CORAL/NoSuccessor Populate Stream DRAGON/From_Stream=CORAL Modify Stream DRAGON/NoPopulate Modify Stream CORAL/Successor=DRAGON Exit $! $ VDE Set Library VMSTEST$ Create Stream/CMS_CLASS/NOINIT_CMS_CLASS - /noGENERATION - /DEFER - /MAIN - ! warning: alters generation selection /Populate - /Frozen - /conference=YELLOW$NOTES:VMSTEST-YELLOW.NOTE - /PARENT=CORAL - /noSuccessor - /REPLACEMENT=QUEUE - /REMARK="Post-CORAL release stream"- DRAGON $! Modify Stream DRAGON - /reviewer=(projectleader,testleader) - /NOTIFY=(projectleader,testleader,DRAGONbld) Modify Stream CORAL/NoSuccessor Populate Stream DRAGON/From_Stream=CORAL Modify Stream DRAGON/NoPopulate Modify Stream CORAL/Successor=DRAGON Exit $ EXIT

The above example creates a mainline stream, which effects

5.8 Tailoring Processing With Scripts

As a project leader, you can tailor how VSC or VDE responds to certain situations using script files. Script files allow a number of common operations to be customized to site-specific requirements.

Table 5-5 contains a list of the available script types, and a brief description of each. Script creation uses the CREATE SCRIPT command, and requires the CRESCRP privilege.

Table 5-5 Script Commands

BUILD
	The build script sets up optional build-job definitions. This script is executed at the start of each build-job process.
COMPILE
	The compile script contains the command(s) used to compile a module. The compile script is called by a build job, and by a COMPILE command.
COPY
	copy command copies a module. The script is called as part of a build job, and is called by the COPY command.
DELETE_GENERATION
	The delete-generation script performs optional processing for the DELETE GENERATION command.
DIFFERENCES
	The differences script is used to determine the differences between two generations of a module. The script is called by the DIFFERENCES command.
FETCH
	The fetch script performs optional processing for the FETCH command.
INSERT_GENERATION
	The insert-generation script performs optional processing for the INSERT GENERATION command.
LINK
	The link script links a module. This script is called by build jobs and by the LINK command.
NEW_STREAM
	The new-stream script copies files for a particular facility from the parent stream into a new stream. This script is called when a new stream is created.
NOKEEP
	The nokeep script performs optional processing for the REPLACE command. Specifically, the nokeep script is called when the REPLACE/NOKEEP command is specified.
REPLACE
	The replace script performs optional processing for the REPLACE command. If stream-specific reference directories are required, this script can be used to update the reference directory on each replacement.
RESERVE
	The reserve script performs optional processing when a RESERVE command is entered. Should notification of a reservation be required, a site-specific reserve script can be coded to send mail.
SET_FACILITY
	The set-facility script performs optional processing for the SET FACILITY command.
SET_STREAM
	The set-stream script performs optional processing for the SET STREAM command.
STAGING
	The staging script copies a source file to a staging area for the REPLACE command when the replacement is queued.
UNRESERVE
	The unreserve script performs optional processing for the UNRESERVE command.