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

,Revision/Update InformationDRAFT

.Revision/Update Information: Revision Date/ April 1992

 ,  

@Contents



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

HThe VSC tool is used for source control of VMS versions. VSC uses a RDB Hdatabase to track reservations, replacements and other updates to a VMS Hversion. VSC uses CMS libraries to store the actual source code changes Cfor a version. Presently, there are over two hundrec CMS libraries Dmaintained on the masterpack. Each CMS library contains CMS classes Ewhich mirror a VSC stream stored in the RDB database. Maintenance of Fthe 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 Gversion-wide operations such as stream creation, stream population and Hstream renaming. The project leader menu provides a convenient means to Aperform CMS commands on the many CMS libraries to mirror the VSC Dcommand. Failure to successfully perform the CMS commands can cause 4problems between source control and system building.

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

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


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

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

EStream creation, population and renaming is significantly faster for Astreams that do not maintain CMS classes in all the VMS facility Dlibraries. For example, to create a build class for the CORAL(V6.1) Fstream, takes about 6 hours with the CMS classes and about 40 minutes Fwithout the CMS classes. Stream population times are also drastically ;reduced. The source fetching during the build is also more Gefficient(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?

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

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

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


 

" $ $@VMSCMS$:PLMENU 1VAX/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 7 (8) Populate a Stream in Selected Facilities & (9) Compare Two CMS Streams * (10) Archive/Obsolete a Facility 6What action do you want to perform? (1-10,EXIT,HELP):  



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

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

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

:Common Prompts


6There are five prompts common to the PLMENU functions.

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

:Prompt features


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

r  ' !              

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



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

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

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

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

ARequired Privileges


CThe create build stream option requires that the user hold the VDE Gprivileges CRESTRM and PERFREP and the process rights Hidentifiers VMS_ENABLE_CMS and VMS_SOURCE. If the user Bdoes not hold these privileges, the submitted batch job will fail.g

3.1 Invoking the create build stream procedure

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

 

" 7What 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 5Prompt default values (if any) appear in brackets [] ;Enter <Ctrl Z>, "Quit" or "Exit" to exit immediately  Product Root [VMS$]:  



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

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

 

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



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

 

m " 9 Enter the new build stream name [V5.5_BLD0]: V5.5_BLD_Z - n



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

 

n " 6Remark string for V5.5_BLD_Z [Build stream for V5.5]:  e



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

t 

_ " B Directory for log files [WORK212:[SWEENEY.SCRATCH]]: sys$scratch  o



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

f 

u " 1 Queue to submit create job [CLUSTER_LONGBATCH]:  y



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

 

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



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

a 

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

U

3.2 Create Stream Processing

DThe batch job submitted by the create stream procedure performs the )following steps to create a build stream:t

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

s

I
• 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!J
• Please coordinate your stream creations with other VMS development I projects so that your stream creation does not interfere with a system I' build or with other stream creations.rJ
• It is not useful to attempt to create more than one build stream at H the same time because there will be many conflicts on the masterpack. H If you need to create multiple streams it is suggested that you space * the submit times by at least four hours.F
• If the create a stream batch job fails, the recovery steps vary & depending upon where the job failed.
  L
  • If the job fails before the VDE stream is created, rerun the create K a stream procedure from the menu and use the same input. The restarted sI batch job may give you warnings that the CMS class already exists in s some facilities.H
  • If the batch job fails after the VDE stream is created, use the L populate stream option of the menu to populate your new stream from the  parent stream.K
  • If your job fails due to a privilege problem, you need your VMS or sK VDE user profile changed to include all the privileges and identifiers f+ noted in the beginning of this chapter.o
  o