A menu of tools to perform masterpack operations needed by the VMS Release project leader.

Revision/Update Information DRAFT

Revision/Update Information: Revision Date/ April 1992

Contents

The release project leader menu provides an interface to perform functions which manipulate the VDE VMS Source Control (VSC) Database and it's underlying CMS libraries. The operations available from the menu are usually performed by a release project leader or by a builder. Most of the menu functions require special VDE privileges not available to the general VMS developer. The primary purpose of the menu is to provide a convenient means for the release project leader to maintain the integrity between the VMS source control environment and the VMS system building environment.

The VSC tool is used for source control of VMS versions. VSC uses a RDB database to track reservations, replacements and other updates to a VMS version. VSC uses CMS libraries to store the actual source code changes for a version. Presently, there are over two hundrec CMS libraries maintained on the masterpack. Each CMS library contains CMS classes which mirror a VSC stream stored in the RDB database. Maintenance of the CMS classes requires much overhead in terms of I/O and processing time. Due to this overhead, the CMS classes are not completely maintained by VSC. + VSC will not update CMS classes on many version-wide operations such as stream creation, stream population and stream renaming. The project leader menu provides a convenient means to perform CMS commands on the many CMS libraries to mirror the VSC command. Failure to successfully perform the CMS commands can cause problems between source control and system building.

VMS system building requires a CMS class representing the target version to build. Typically a build stream is created from a snapshot of a development stream. The build stream is used as the target version of a system build. Creating a build stream currently requires over eleven thousand RDB table updates and over eleven thousand corresponding CMS insert generation commands in the VMS masterpack CMS libraries. In addition, the CMS class must be created in all applicable CMS libraries before performing the insert generations. The project leader menu provides a method to create, populate and rename build streams.

UPDATE: CMS Classes are optional for streams created after January 1993

VMS development projects can now chose not to maintain CMS classes for their build streams. The VMS build procedures and the Project Leader Menu tools have been modified to fetch all generations of the VMS source code using the VDE database alone. The behaviour of the build, and of the tools, is determined by the value of a logical, VDE$FETCH_METHOD. If VDE$FETCH_METHOD is "VDE", then the tools and the build procedures will maintain only the VDE library with the build stream generations.

It is important to define the VDE$FETCH_METHOD logical in the LOGIN.COM file for the account that will be creating, populating, renaming and building streams. The logical must be defined for the batch jobs submitted by the PLMENU tools and the logical must be defined for the VMS build batch jobs.

Stream creation, population and renaming is significantly faster for streams that do not maintain CMS classes in all the VMS facility libraries. For example, to create a build class for the CORAL(V6.1) stream, takes about 6 hours with the CMS classes and about 40 minutes without the CMS classes. Stream population times are also drastically reduced. The source fetching during the build is also more efficient(faster) using the VDE subprocess to fetch the sources rather than image activating CMS to perform each fetch operation.

Why should you use the project leader menu?

Below as reasons why you should use the menu for masterpack operations:

1. The menu provides a means to perform operations that cannot be completely executed using VSC alone or CMS alone. Some operations, such as renaming a stream, require execution of a VSC MODIFY STREAM /NAME command and execution of a CMS MODIFY CLASS/NAME command for every CMS library.
2. Consistency between the VSC stream and the underlying CMS class is better maintained using the project leader menu.
3. The menu tools provide increased performance over VSC for stream-wide operations.
4. The menu provides safeguards against initiating operations that would lock out other update usage on the masterpack during regular working hours.
5. Use of the menu provides for a consistent stream naming convention across VMS versions.
6. Free disk space on the VMS masterpack is a valuable commodity. The CMS history produced by the project leader tools is tagged with a special string to allow purging the CMS history without losing valuable historic events in the library.

The project leader menu consists of ten options. Masterpack operations should be performed on the STAR VMS production cluster. Following is an example of how to invoke the menu on the STAR cluster:

$ $@VMSCMS$:PLMENU VAX/VMS Project Leader Menu (PLMENU) Version X-6 Enter ? or "HELP" at any prompt to obtain help Enter <Ctrl>Z, "Quit" or "Exit" to exit immediately Choose an action from the list below: (1) Create a new build stream (2) Populate a build stream (3) Rename a stream (4) Set/Show PLMENU logicals (5) Create a baselevel stream from a build stream (6) Compare VDE to CMS for a stream (7) Create a New Facility (8) Populate a Stream in Selected Facilities (9) Compare Two CMS Streams (10) Archive/Obsolete a Facility What action do you want to perform? (1-10,EXIT,HELP):

Each action available from the menu is described in detail in this document.

This section describes prompts which are common to most of the PLMENU options. The logical names referenced in this section can be assigned values with the Set/Show PLMENU logicals option of the menu.

The project leader menu functions are performed by batch jobs which are submitted for you by the menu. Batch jobs are used because the functions of the menu take minutes or hours to complete. There are five questions which are asked by all the menu options to control the batch job attributes.

Common Prompts

There are five prompts common to the PLMENU functions.

• Product Root [VMS$]: The product root defines the VDE database and the CMS libraries that are to be processed. The product root will default to VMS$. You can override this default value by defining the logical name PLMENU$DEFAULT_PRODUCT to another value. The valid product roots available are TOOLS$, VMS$ and VMSTEST$.
• Queue to submit job [SYS$LOBUILD]: You must give a queue in which to run the batch job. The batch queue will default to SYS$LOBUILD. You can override the queue default value by defining the logical name PLMENU$DEFAULT_BATCH_QUEUE to another value. Note that using the SYS$LOBUILD and SYS$BUILD queues requires you to hold the SYSTEM_BUILDER process rights identifier.
• Directory for log and work files? [default]: This prompt defines where the log file produced by the submitted batch job will be located. Some of the menu options, like populate a build stream, produce work files. The work files produced by a submitted job will be located in this directory. The directory will default to your current default directory. You can override the directory default by defining the logical name PLMENU$DEFAULT_DIRECTORY to another value.
• Time to submit job? [default]: The batch job will be submitted to begin execution at the time specified by the answer to this prompt. The default value to this prompt varies depending on what menu option you are performing. The default submission time for a new stream create is usually midnight(it's the current time if you are working on weekends or between midnight and 3:00AM on weekdays). The default submit time for a VDE/CMS stream comparison is "NOW" (submit the job immediately).
• Do you wish to proceed? [default]: Each option displays a summary of the job to be submitted and asks for your confirmation to proceed.

Prompt features

Below is a summary of special strings and input recognized by the project leader menu prompts.

Table 2-1 Special input recognized by PLMENU

Prompt Input	Action
Ctrl Y, Ctrl Z, "EXIT", "QUIT"	Terminate current option
"Back", "Prev"	Return to the previous prompt
"HELP", "?"	Display help

Creating a new stream is one of the most expensive operations performed on the VMS master pack. Over 11,000 RDB updates and 11,000 CMS updates are needed to create the new stream. Due to this overhead, it is undesirable to create a new build stream during working hours. The create stream option of the menu prompts you for all the information necessary to successfully create a build stream in the VSC database and the masterpack CMS libraries.

This option of the menu should always be used to create new build streams, regardless of whether CMS classes are maintained or are not maintained for the build stream. The create build stream option avoids locking up the VDE database by breaking the create stream into two separate transactions. To create a stream in the VDE database only, remember to have the logical VDE$FETCH_METHOD define to "VDE" before invoking the menu. NOTE: A CMS class is still created in the VMS$:[SYS.CMS] library because of the system base level updating procedures.

The VDE CREATE STREAM command executes as a single transaction. If the VDE CREATE STREAM command is used to create AND POPULATE a new stream, the transaction creating the stream locks out all other write access to much of the VDE database. This lockout would be from 30 to 40 minutes for the current development stream size(V6.0 & CORAL).

The create stream option uses the VDE CREATE STREAM command with the /NOGENERATIONS qualifier. This qualifier tells VDE to not insert any of the generations from the parent stream into the newly created stream. This transaction takes about 1 minute. The VDE POPULATE STREAM command is then used to insert the parent stream module generations into the new stream. The POPULATE STREAM command uses many transactions to insert small sets of generations into the new stream. The small transactions allow other write access users to update the database while the populate is in progress. For more information on the VDE CREATE STREAM command, consult the VDE reference manual.

Required Privileges

The create build stream option requires that the user hold the VDE privileges CRESTRM and PERFREP and the process rights identifiers VMS_ENABLE_CMS and VMS_SOURCE. If the user does not hold these privileges, the submitted batch job will fail.

3.1 Invoking the create build stream procedure

To create a new build stream, select option one from the main menu. The create build stream command procedure executes.

What action do you want to perform? (1-6,EXIT,HELP): 1 Create Build Stream Version X-1 Enter ? or "HELP" at any prompt to obtain help Prompt default values (if any) appear in brackets [] Enter <Ctrl Z>, "Quit" or "Exit" to exit immediately Product Root [VMS$]:

Enter the product root. See Chapter 2 for a definition of product root.

The next prompt asks you for the parent stream of the build stream. The parent stream is the stream for which the build stream is to be a snapshot. The parent stream module generations are used to populate the new build stream. The build stream will be marked as a descendent of the parent stream. The parent defaults to the value of logical name PLMENU$DEFAULT_SOURCE_STREAM. In the example below, the user enters stream V5.5 to create a new build stream for version V5.5.

Parent stream for new build stream [V5.4]: V5.5

After you enter the parent stream you will be asked to supply the new build stream name. It is a convention in VMS that the build stream name begin with the development stream name followed by the string "_BLD" and a suffix. Please try to adhere to this convention. In the example below, the new stream is named "V5.5_BLD_Z". You can define the logical PLMENU$DEFAULT_TARGET_STREAM to suppy a default value to this prompt.

Enter the new build stream name [V5.5_BLD0]: V5.5_BLD_Z

The create stream procedure now asks for a remark string to be associated with the new build stream. This remark string is used for the CMS classes and the VDE stream remark. This remark is displayed by a VSC show stream or CMS show class command. Enter a remark string (no quotes) if you do not like the default remark.

Remark string for V5.5_BLD_Z [Build stream for V5.5]:

You are now asked for the work directory into which to place the log file and work files produced by the procedure. The submitted job name is formatted as CREATE_'new_build_stream_name'. In our example the job name is CREATE_V55_BLD_Z. Periods are removed from the build stream string in the job name.

Directory for log files [WORK212:[SWEENEY.SCRATCH]]: sys$scratch

Enter the batch queue to submit the creation job at the next prompt.

Queue to submit create job [CLUSTER_LONGBATCH]:

The procedure prompts you for the time to begin the create job. On weekdays, you are warned of possible masterpack disk contentions if you choose a time between 3:00AM and 11:59PM. You may submit the job at the entered time if you answer affirmatively to the "Do you want to submit the job anyway?" question.

Time to begin create job? [TOMORROW]: NOW Due to lock conflicts and disk contention on the master pack, this job should be submitted after 12:00AM and before 3:00AM on working days. It is strongly advised to avoid creating a stream during regular working hours. Do you want to submit the job anyway? [N]:BACK Time to begin create job? [TOMORROW]: TOMORROW+01:00

You are asked to confirm your input and submit the batch job.

You are attempting to create a new build stream, V5.5_BLD_Z for development stream V5.5. Do you wish to proceed? [Yes]: Validating stream V5.5 in VDE... Validating stream V5.5_BLD_Z in VDE... Job CREATE_V55_BLD_Z (queue CLUSTER_LONGBATCH, entry 633) holding until 10-APR-1992 01:00

3.2 Create Stream Processing

The batch job submitted by the create stream procedure performs the following steps to create a build stream:

1. Creates a CMS build class for all facilities which contain the parent class and which are not marked archived or marked no propagation.
2. Checks if there is a facility whose name matches the parent stream name. If a match is found, the CMS build class is created in the matched facility even if the facility is marked no propagation.
3. Creates an empty (no module generations) build stream in the VDE database.
4. Populates the build stream from the parent stream module generations. The population method used is identical to the stream population processing described in Chapter 4.

• It's a good idea to plan ahead and create build streams before you actually need them, but don't create more than you need!
• Please coordinate your stream creations with other VMS development projects so that your stream creation does not interfere with a system build or with other stream creations.
• It is not useful to attempt to create more than one build stream at the same time because there will be many conflicts on the masterpack. If you need to create multiple streams it is suggested that you space the submit times by at least four hours.
• If the create a stream batch job fails, the recovery steps vary depending upon where the job failed.
  • If the job fails before the VDE stream is created, rerun the create a stream procedure from the menu and use the same input. The restarted batch job may give you warnings that the CMS class already exists in some facilities.
  • If the batch job fails after the VDE stream is created, use the populate stream option of the menu to populate your new stream from the parent stream.
  • If your job fails due to a privilege problem, you need your VMS or VDE user profile changed to include all the privileges and identifiers noted in the beginning of this chapter.