This options allows you to check the consistency of a stream representation between VDE and CMS. The module generations in the VDE database are compared to the module generations in the CMS library.

Required Privileges

The process rights identifiers (VMS_SOURCE or VMS_SOURCE_READ) and VMS_ENABLE_CMS are required.

7.1 Invoking the compare stream procedure

The VDE to CMS comparison utility is invoked by selecting option 6 from the project leader main menu.

What action do you want to perform? (1-6,EXIT,HELP): 6 Compare 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 the product root.

The next prompt asks you for the stream you want to compare. This prompt defaults to the value of logical name PLMENU$DEFAULT_SOURCE_STREAM.

Stream to compare [V5.4]:

Enter the work directory where you want the utility's file(s) to reside.

Directory for log files [WORK212:[SWEENEY.SCRATCH]]:

Enter the queue in which to run the compare stream batch job.

Queue to submit compare job [CLUSTER_LONGBATCH]:

Indicate if you want the report of stream differences to be displayed in the log file (default) or written to a separate report file. If you do not give a directory specification to the file name, the report will be located in the work directory. The default file type is .LIS.

Report file name ? [LOG]: TEST

Enter the facility to process. By default, the procedure submitted will compare VDE to CMS for all non-archived facilities in the product root. Archived facilities are skipped by the procedure. Facilities marked no propagation are compared by this procedure. You may enter a full facility name or a partial facility name with wildcards. For example you may enter SYS* to process all facilities beginning with SYS.

Facility to process [ALL]: SYS*

The procedure prompts you for the time to begin the compare job. This option is a read only function so there is no warning notice on any entered time.

Time to submit compare job? [NOW]:+00:01

You are asked to confirm your comparison request.

If you proceed you will submit a job to compare stream V5.4 for all facilities matching the file specification VMS$:[SYS*.CMS]. Differences in the stream will be reported to file WORK212:[SWEENEY.SCRATCH]TEST.LIS; Do you wish to proceed? [Yes]: Validating stream V5.4 in VDE... Job V54_COMPARE (queue CLUSTER_LONGBATCH, entry 526) holding until 13-APR-1992 09:17

7.2 Compare Stream Processing

The compare stream utility compares the stream for each facility matching the entered specification. For each facility, a message is displayed to the log file indicating whether the VDE stream and the CMS class differed or matched. Differences are reported to the location specified in the report file prompt.

7.3 Suggestions for Comparing Streams

• There are some known differences between CMS and VDE that can be ignored. These differences are:
  1. BASE_LEVEL.MAR in facility SYS. This module is updated in CMS only by the system building tools.
  2. Facilities AAA_VDE_TEST and YELLOW_TEST are testing facilities for the tools group. Any differences encountered in these facilities may be ignored.
• A difference between VDE and CMS may be the result of a rolled back VDE transaction. The difference is self-correcting once the transaction is run successfully.
• As mentioned in the populate stream section, if you allow changes to a source stream during a population, you may encounter differences in the target stream after the population. This is due to the fact that the CMS populations take place after the VDE stream is populated.

When you need to create a new facility on the masterpack, you can use this option to create the facility. This option creates the new facility in the VDE database and creates the facility CMS library. The utility creates three modules in the facility which are template files to be used for system building. The utility also sets up no propagation facilities in the most efficient manner.

The facility is created interactively. There is no batch procedure submitted by this option.

Required Privileges

The VDE privilege CREFAC is required to run this option. The process rights identifiers VMS_SOURCE and VMS_ENABLE_CMS are required.

8.1 Invoking the create facility procedure

To run the create facility procedure, choose option seven from the project leader main menu.

What action do you want to perform? (1-7,EXIT,HELP): 7 Create Facility 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 [TOOLS$]:

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

A stream needs to be defined for the facility. The stream should be the first development stream in which you expect the components of this facility to ship. For example, if you are creating a facility to hold the update files for version V5.5, you would enter V5.5 to this prompt.

Facility begins with what development stream? [MAIN]:

Enter the new facility name. The product root is checked to see if a CMS library for this facility already exists. If a CMS library is found you will receive an error.

Facility Name?: VIC %CREFAC-E-ALREXISTS, facility VIC CMS library already exists! Facility Name?: wrench

Enter a remark for the new facility. This remark is displayed by the VDE show facility command.

Remark string for wrench [wrench FACILITY]: Wrench test facility

If the facility will accept change propagation enter yes to the next prompt. If you are creating a facility to hold update files for a particular release you should answer no to this question.

Will facility wrench accept module change propagation? [YES]:

You are asked to confirm your input to proceed and create the facility.

If you proceed you will create facility wrench in root TOOLS$. Stream MAIN will be populated with three system build template files. The facility is created by this procedure. No batch job is submitted. Do you wish to proceed? [Yes]:yes Validating stream MAIN in VDE... %CREFAC-I-CREATING, Creating facility wrench... %CREFAC-S-CREATED, facility wrench created

8.2 Create Facility Processing

The create facility processing is broken down as follows:

• The VDE facility and CMS library are created using the VDE create facility command.
• If the new facility is a no propagation facility, the file VMSCMS$NO_PROPAGATE.FLAG is created in the facility directory.
• Three modules are created in the facility. These three files are templates you edit to perform a facility build. The three files are:
  1. 'facility name'BLD.COM - This file contains a template of a command procedure to perform all the steps of a VMS system build. In the example used in this chapter the file name is WRENCHBLD.COM.
  2. 'facility name'ASM.DAT - This is a specially formatted data file that is used to contain information on which files to compile or assemble in the facility. In the example used in this chapter, the file name is WRENCHASM.DAT.
  3. 'facility name'LNK.COM - This is a command file where all link commands needed to build the facility should be located.
• The CMS group BUILD is created. The three build files created above are inserted into the build group.

• Be sure the propagation attribute for the facility is set correctly. Unnecessarily propagating changes in a facility is expensive.
• Remember, facilities used for holding a release's update files are nopropagate facilities.
• If the create facility procedure is abnormally terminated, it may require manual intervention to correctly cleanup the facility.

This option is virtually identical to the populate stream option. While the populate stream option populates the stream in all CMS libraries, this option only populates the facility CMS libraries which are specified in a data file, or in a user entered list. The populate facilities utility gives you the flexibility to populate both the CMS libraries and VDE database, the CMS libraries only, or, the VDE database only. The prompts are identical to the populate stream option except there are three additional questions. This option is useful when you know only a few facilities have changed since the previous population. It is important to realize that, if you populate the VDE stream, the population covers ALL facilities. The list of facilities to populate is used for controlling the CMS library populations and is ignored by the VDE population.

Required Privileges

The populate selected facilities option requires that the user hold the VDE privileges FROZEN 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.

9.1 Invoking the populate facilities procedure

To populate a stream in selected facilities, use option eight from the main menu. The populate facilities command procedure executes.

What action do you want to perform? (1-6,EXIT,HELP): 8 Populate Facilities 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.

Next you are asked for the source stream for the population. The source stream is the stream to populate from, or, if you like, the stream for which to create a snapshot. Usually the source stream is a VMS development stream but this is not a requirement. The source stream is similar to the parent stream of the create stream option. The source stream defaults to the value of logical name PLMENU$DEFAULT_SOURCE_STREAM.

Source Stream [V5.4]: V5.5

Upon entering the source stream you will be asked for the target stream to populate. This is usually a build stream for a development project. The target stream must have the VDE stream population attribute set for this procedure to work. The target stream defaults to the value of logical name PLMENU$DEFAULT_TARGET_STREAM.

Target Stream: V5.5_BLD_Z

The next question is used to determine if you want to interactively enter a list of facilities to process. If you answer affirmatively to this question, you are prompted for a list of facilities. If you answer "N"o to this question, you are asked to supply a file listing the facilities to process.

Do you want to enter the facilities to process? [Y]: help Answer "Y"es if you want to interactively enter the facilities to process. If you answer no, you will be expected to supply the name of a file which lists the facilities to process. Enter BACK or PREV to return to the target stream prompt. Do you want to enter the facilities to process? [Y]:<RET>

Enter the list of facilities to populate.

Enter a list of facilities delimited by commas(,)(256 character maximum) Hit <RET> to finish : help Enter a list of facility names delimited by commas "," or enter one facility name. Enter BACK or PREV to return to the facility input prompt. Enter a list of facilities delimited by commas(,)(256 character maximum) Hit <RET> to finish : sys,sysloa,driver,starlet<RET>

If you did not indicate you wanted to enter a list of facilities, you are asked for the location of a file that lists the facilities to process. The file must be a text file with one facility name per record. For example, the file below is used to process facilities DRIVER, SYS and SYSLOA.

$ type work$:[Sweeney.tools]facs.dat SYS SYSLOA DRIVER $

Enter the facility list file specification. Your default directory is searched for the file if you omit the directory from the file specification.

Facility List File: work$:[Sweeney.tools]facs.dat

The next prompt is used to indicate how the VDE database and CMS libraries are to be populated. If you want to populate the stream in both the VDE database and the CMS libraries enter "BOTH" to this prompt. If you want to update the VDE database only, enter "VDE" to this prompt. If you want to populate only the facility "CMS" libraries, enter CMS.

Populate CMS, VDE or BOTH [BOTH]: BOTH

The populate stream job now prompts you for the queue to submit the populate jobs.

Queue to submit populate jobs [CLUSTER_LONGBATCH]

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 'target_stream_name'_POP. In our example the job name is V55_BLD_Z_POP.

Directory for logs and work files [WORK212:[SWEENEY.SCRATCH]]:

The procedure prompts you for the time to begin the populate job. On weekdays, you are warned of possible masterpack disk contentions if you choose a time between 5:00AM and 5:00PM. You may submit the job at the entered time if you answer affirmatively to the "Do you still want to submit the job at the entered time? [N]:" question.

Time to begin submission of populate jobs? [ 9-APR-1992 17:00:00]: NOW Due to locking contention on the master pack, this job should be submitted after 5:00PM and before 5:00AM on weekdays. It is advised to avoid submitting populations during regular working hours unless you are sure the source stream and the target stream are almost identical. Do you still want to submit the job at the entered time? [N]: YES

You are asked to confirm your population request.

If you proceed you will populate stream V5.5_BLD_Z from stream V5.5 for the facilities listed in work$:[Sweeney.tools]facs.dat. Do you wish to proceed? [Y]: Validating stream V5.5 in VDE... Validating stream V5.5_BLD_Z in VDE... Job V55_BLD_Z_POP (queue CLUSTER_LONGBATCH, entry 633) started on queue CLUSTER_LONGBATCH

9.2 Populate Facilities Processing

The populate stream batch job maintains a status file to indicate the current state of the stream population. Any warnings or errors encountered during the population are marked in this file. A population status is mailed to the user upon completion of the populate job. The populate batch job processing is summarized as follows:

1. The target VDE stream is populated from the source VDE stream. The population is broken down into many small RDB transactions to avoiding locking out other update usage on the masterpack. If any error is detected at this point, the batch job will terminate. The stream is populated for ALL facilities due to the current implementation of the VDE POPULATE STREAM command.
2. The procedure submits a batch job to perform the CMS insert generation commands for every non-archived facility which is in the facility list file. You are not allowed to populate archived facilities.
3. Each CMS insert generation procedure checks if the source stream exists in the facility CMS library. If the source stream does not exist a warning message will be output in the log file and into the procedure status file. If the source stream exists, the target stream is populated from the source. +
4. The procedure waits for the CMS insert generation batch jobs to complete. When all jobs are complete the status file is checked for errors. The user who submitted the job will receive a mail message indicating the status of the population.

9.3 Suggestions for populating facilities

• NEVER DELETE AN EXECUTING CMS POPULATE JOB FROM THE QUEUE. An improper termination of a CMS insert generation command can corrupt a CMS library so, please don't delete the CMS population jobs. A future version of CMS is supposed to correct this problem. If you need to stop CMS population jobs from processing the jobs can be stopped by defining the logical name FAC$ABORT_POPLIBS in the system logical name table on all relevant nodes. The FAC$ABORT_POPLIBS logical stops ALL populate jobs from processing. After your jobs have stopped be sure to deassign this logical to allow future populations to run successfully.
• If the stream you are populating is very different from the source stream please don't submit the populate during "regular" working hours.
• Don't panic if you receive warning messages in the population status. There may be facilities for future VMS releases that are not applicable to your development stream.
• If you are going to do a build with the target stream, it's not wise to allow changes to the development stream during the population. If you allow replacements into the development stream during the population, the VDE representation of the build stream will differ from the CMS representation of the build stream. This could be a source of confusion after the build. Remember, it is the CMS representation of the stream that is used to build VMS.
• If your populate stream job fails, rerun the populate stream using the same input.
• If you fail to populate a facility in which the source stream has changed since the previous population of the target stream, you will cause the VDE stream representation to differ from the CMS representation for the facility.