This chapter discusses the change control facilities provides by SysWorks.

Figure 4-1 illustrates the version control menu presented by using the CHGCTL command without any parameters or the session manager Manage => Versions pulldown menu.

Figure 4-1 CHGCTL menu

This chapter describes compiling sources and bbuilding targets.

5.1 Compiling Sources

The COMPILE command is used to compile or translate a source into its next form, which for most sources is an intermediate form such as an object file. For example, compiling a Cobol source would produce an object file. Some sources can be directly translated into a target form. For example, compiling a Linker options file would produce an image file. The one parameter to the COMPILE command is a list of source files. Generally the COMPILE command does not take into account dependences. For example, no attempt is made to check that a dictionary record used in a Cobol source is present or up-to-date in the dictionary. See the Command Dictionary for more details.

If a developer has just edited a single source, the COMPILE command is a much simpler way of building the target than using the BUILD command. For example, the command:

$ compile fixed_module.c,[-]main_prog.opt

might be useful if the developer has just fixed fixed_module.c which needs to be linked into main_prog.exe. This is much faster than the equivalent BUILD command which would be:

$ build fin_sft_dir:main_prog.exe

5.2 Building Targets

The BUILD command is used to build targets from their constituent sources. The one parameter to the BUILD command is a list of target files. The BUILD command uses MMS to ensure that all dependencies between sources are handled in a logical order. For example, building an image file will ensure the dictionary records are up-to-date, compile a Cobol source, and finally link it into an image.

In order to remove most the the need to maintain MMS description files, the BUILD command is implemented as a multi-phase tool. The standard phases are listed along with their qualifiers in Table 5-1.

Table 5-1 Build Phases

Phase	BUILD Qualifier
PRECLEAN	/FROM[=location]
UPDATE	/UPDATE
TIDY	/TIDY
FETCH	/FETCH
SETUP	/PHASE=SETUP
SCAN	/PHASE=SCAN
RULES	/PHASE=RULES
DESCRIP	/PHASE=DESCRIP
RELATED	/RELATED
KITBLD	/KITBLD

A BUILD operation consists of the execution of one or more of these phases. Each phase produces outputs which are used as input to the next phase. For example, the RULES phase might generate an MMS script of all source dependencies which in then used in the subsequent DESCRIP phase. An application may use any number of phases in a BUILD.

These phases may have any name, however, the DESCRIP phase has some special defaults applied to it. The UPDATE, FETCH and PRECLEAN phases are controlled by qualifiers on the BUILD command. All other phases is driven by a DCL command procedure and/or an MMS script. These have the same file name as the BUILD phase, and have a file type of .COM or .MMS as appropriate. They should be maintained in the CMS library as per any other source file. If both are found, the DCL command procedure is executed first.

Typically the SETUP, RULES and DESCRIP phases are MMS scripts, and the SCAN and KIT phases are DCL command procedures. The BUILD operation will fetch DCL command procedures associated with phases from the CMS in much the same fashion as MMS does.

When BUILD invokes MMS to perform actions during a phase, the target requested has the same name as the phase. The exception to this is the DESCRIP phase, in which MMS is passed the target from the original BUILD command.

5.2.1 Phases

The following sub-sections describe each phase in greater detail. They are presented in the order in which they would normally be executed.

5.2.1.1 PRECLEAN

Clean out appropriate intermediate and target areas. This is achieved by deleting all files from the work, library and/or software directory trees (including the CDD repository), thus forcing the application to be built from sources in the CMS library.

Note that the three files ENTER.COM, EXIT.COM and LOGICALS.COM are preserved in the software directory so that commands such as CONTEXT will continue to work.

This phase is not generally explicitly included in a build, rather the /FROM=location qualifier forces this phase to be executed before the SETUP phase.

The set of directories which will be emptied during the PRECLEAN phase is controlled by the location code specified with the /FROM qualifier. See the /FROM qualifier for details about the location codes, the directories which are emptied and the effect this has on building the application.

5.2.1.2 UPDATE

Update the application work directory with the latest sources form the developers work directory. This phase is not used with the SPECIFIC scope.

5.2.1.3 TIDY

Deletes files in the developers work directory which exist in the common work directory and are not reserved by the developer. Also deletes the associated files in the developers library directory. Also deletes all .TAG_CDD files in the developers library directory and all the objects in the developers CDD/Repository area. In a future release of SysWorks, only .TAG_CDD files and CDD/Repository objects that need to be deleted will be deleted.

5.2.1.4 FETCH

Fetches all newer sources from the CMS library. This phase is an alternative to using CMS during the RULES and DESCRIP phases.

5.2.1.5 SETUP

The SETUP phase performs actions required before other ALL type phases. It is typically used to generate build time structures and software. This allows build time executables (typically DCL command procedures and other scripts needed during the RULES sub-phase) to be built prior to the main build sub-phases.

5.2.1.6 SCAN

The SCAN phase is typically used to generate dependency lists based on current sources - i.e. convert a list of sources (usually taken from the CMS library) into an MMS script which will generate the source based MMS scripts in the RULES sub-phase. To standardise this phase, the DCL command procedure SWDEV_SFT_DIR:SWDEV_BUILD_SCAN may be executed to generate a set of standard MMS scripts. These MMS scripts are generated with a file type of .MMS, and are created in the library directory. Where targets in them are generated MMS scripts, the file type will be .MMS_INC. This is so that at the end of the RULES phase (when all these .MMS_INC scripts should be up to date), they can be copied into a single appl_APPENDS.MMS script for inclusion in the DESCRIP phase. This reduces the overhead of having to .INCLUDE a large number of individual source based MMS scripts.

The SCAN phase generated files are described in Table 5-2.

Table 5-2 SCAN Phase Generated Files

Generated File	Usage
appl_CONSTRAINTS.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_table_CK n.SQL, appl_table_FK n.SQL and appl_table_PK.SQL. The @ character precedes each source file specification so that this procedure can be used from within the SQL utility.
appl_DOCUMENTATION.MMS	A dependency list of all the documentation targets.
appl_DOMAINS.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_domain_DOM.SQL. The @ character precedes each source file specification so that this procedure can be used from within the SQL utility.
appl_DOMAIN_SDML_LIST.MMS	A dependency list of all the generated SDML domain documentation sources.
appl_FORM_LIST.MMS	A dependency list of all the generated DECforms form MMS scripts, so that a generated linker options file may be regenerated when any DECforms form is modified. This regeneration is typically performed near the end of the RULES phase.
appl_HELP.MMS	A dependency list of all the help targets.
appl_INDICES.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_index_IDX.SQL or appl_index_PIDX.SQL or appl_index_SIDX n.SQL. The @ character precedes each source file specification so that this procedure can be used from within the SQL utility.
appl_LINK_OPT_LIST.MMS	A dependency list of all the Linker options sources.
appl_MSGHLP.MMS	A dependency list of all the message help targets.
appl_PROTECTIONS.SQL	An SQL source which will apply a standard protection to each appropriate object in the database.
appl_ROUTINES.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_routine_RTN.SQL. The @ character precedes each source file specification so that this procedure can be used from within the SQL utility.
appl_SCHEMA.MMS	A dependency list of all the Rdb database schema sources. This script is usually included in the application DESCRIP.MMS script.
appl_STORAGE_MAPS.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_storage_map_SM.SQL. The @ character precedes each source file specification so that this procedure can be used from within the SQL utility.
appl_TABLES.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_table_TBL.SQL. Note that SQL constraints definitions are embedded within the table definition sources.
appl_TABLE_SDML_LIST.MMS	A dependency list of all the generated SDML table documentation sources.
appl_TARGETS.MMS	A dependency list of all the targets.
appl_TASK_LIST.MMS	A dependency list of all the generated ACMS task MMS scripts, so that a generated ACMS task group may be regenerated when any ACMS task is modified. This regeneration is typically performed near the end of the RULES phase.
appl_TRIGGERS.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_trigger_TRG.SQL or appl_trigger_TRGR.SQL. The @ character precedes each source file specification so that this procedure can be used from within the SQL utility.
appl_VIEWS.SQL	An SQL script containing a list of all the sources with a file name and type of the form appl_view_VIEW.SQL or appl_view_VW.SQL. The @ character precedes each source file specification so that this procedure can be used from within the SQL utility.
appl_VIEW_SDML_LIST.MMS	A dependency list of all the generated SDML view documentation sources.

5.2.1.7 RULES

The RULES phase is typically used to generate dependencies based on current sources - i.e. convert sources to MMS scripts. This can be achieved by including the appl_SCRIPT_LIST and appl_RULES scripts from the SCAN phase. The actions normally generated in the appl_RULES script are a DEVTOOLS CONVERT/GENERATE command to convert a source to an MMS include script (file type .MMS_INC).

At the end of the RULES phase, all the generated MMS include script files are copied into one large appl_APPENDS.MMS. This is because it is faster to copy all these files together into one script for MMS than have MMS include each of the scripts. This copy is achieved using the DEVTOOLS COPY/NODUPLICATES command, so that the application library directory logical name may be a search list and only the earliest copy of each MMS include script file is copied into the appl_APPENDS.MMS script file.

The RULES phase generated files (other than MMS scripts generated from sources) are described in Table 5-3.

Table 5-3 RULES Phase Generated Files

Generated File	Usage
appl_DEPENDENCIES.MMS	An MMS script containing all the generated dependencies used to build the application.

5.2.1.8 DESCRIP

The DESCRIP phase is used to create targets based on dependencies - i.e. the traditional MMS build. This is achieved by including the generated MMS scripts from the RULES sub-phase into the DESCRIP.MMS script.

5.2.1.9 KITBLD

The KITBLD phase is typically used to create installation kit which is a set of OpenVMS BACKUP save-sets ready for OpenVMS INSTAL to install on target clusters.This phase is only executed when the BUILD/KITBLD qualifier is used.

5.2.2 Add Extra Phases

Some applications may need extra site or application specific phases. This is typically the case when a database is designed externally to the application and/or the application has generated sources.

This chapter discusses the version control facilities provided by SysWorks.

Figure 6-1 illustrates the version control menu presented by using the VSNCTL command without any parameters or the session manager Manage => Versions pulldown menu.

Figure 6-1 VSNCTL menu

Figure 6-2 illustrates the various symbols used in the VSNCTL flow diagrams.

Figure 6-2 VSNCTL Diagrams Legend

This option invokes a set of questions which lead to a BUILD command being executed. See section 4.6.2 for more details on the BUILD command.

Example:

$ vsnctl build Use application or user username (Application/User) [Application]: From sources or work area (Source/Work) [Work]: Phases [All]: Use CMS library (Yes/No) [Yes]: Prefetch CMS (Yes/No) [Yes]: Debug (Yes/No) [Yes]: Target(s) [All]: Execution (Batch/Detached/Online/Subprocess) [Batch]: Batch queue [SYS$BATCH}: Execution after [NOW]:

Note that this build option does not support all of the BUILD commands qualifiers.

6.2 COMPARE

This option is used as a fron end to the DEVTOOLS DIFFERENCES/DATES command (see also known as the COMPARE command)

Example:

$ vsnctl compare

6.3 CLEANUP

Example:

$ vsnctl cleanup

6.4 DEVELOP

This option is used to take a released version into a development environment.

Example:

$ vsnctl develop Version: V1.0 Development environment [DEV]: Build (Yes/No) [Yes]: Development testing environment [DTST]: Execution (Batch/Detached/Online/Subprocess) [Batch]: Batch queue [SYS$BATCH]: Execute after [NOW]:

See the description of the SPLIT task for complete details of these questions and the actions associated with DEVELOP task.

6.5 MAINTAIN

This option is used to take a released version into a maintenance environment.

Example:

$ vsnctl maintain Version: V1.0 Maintenance environment [MNT]: Build (Yes/No) [Yes]: Maintenance testing environment [MTST]: Keep existing maintenance version (Yes/No) [Yes]: Execution (Batch/Detached/Online/Subprocess) [Batch]: Batch queue [SYS$BATCH]: Execute after [NOW]:)

See the description of the SPLIT task for complete details of these questions and the actions associated with MAINTAIN task.

6.6 SPLIT

This option is used to split a released version into a develoment and maintenance stream. It must be used in an environment which uses the common CMS library. The release version must contain the latest generations in the CMS library. This will be the case if a RELEASE task has been executed without any subsequent CMS REPLACE or TRIAL tasks being used. This restriction will be removed in a future release of SysWorks.

Figure 6-3 illustrates the flow of sources during a SPLIT.

Figure 6-3 SPLIT flow

The following steps are taken:

1. If the existing maintenance version is being kept, the existing maintenance and maintenance testing CMS classes are renamed. These renames will be from appl_envr to appl_envr_vrsn where envr are the maintenance and maintenance testing environment codes, and vrsn is the existing maintenance environment version (i.e. the released version from which the previous MAINTAIN or SPLIT was performed)
2. Any of the four target CMS classes which do not exist are created. These classes have names of the form appl_envr where envr are the development, development testing, maintenance and maintenance testing environment codes. Note that if step 1 was taken, the new maintenance and maintenance testing classes will always be created since they no longer exist.
3. Each generation from the released version class is reserved and replaced twice. The first time in the main line, and the second with a variant. Each of the new main line generations is placed in the development and development testing CMS classes. Each of the new variant generations is placed in the maintenance and maintenance testing CMS class. These actions are designed to force development generations and maintenance generations to not be in the same line of descent so that future merge operations will be able to work properly. Note that in this release of SysWorks, no check is made when creating the new mainline and variant generations as to whether such a generation already exists. This creates the restriction that no work (i.e reserve and replace) can be done between the start and finish of a trial replease split sequence.
4. If any of the four environments have their own CMS library, this library is populated with the new generations.
5. If requested, a BUILD/FROM_SOURCES is executed in the development environment.
6. If the existing maintenance version is being kept, the existing maintenance directory structure is moved down one level into the DISK_envr:[appl.vrsn] directory where envr is the maintenance environment code and vrsn is the previous version code. If a CDD repository is included, a CDO MOVE REPOSITORY command is used and the user needs to have the appropriate access to execute this command.
7. If requested, a BUILD/FROM_SOURCES is executed in the maintenance environment.
8. Actions similar to step 6 are taken for the maintenance testing environment.

Example:

$ vsnctl split Version: V1.0 Development environment [DEV]: Build (Yes/No) [Yes]: Development testing environment [DTST]: Maintenance environment [MNT]: Build (Yes/No) [Yes]: Maintenance testing environment [MTST]: Keep existing maintenance version (Yes/No) [Yes]: Execution (Batch/Detached/Online/Subprocess) [Batch]: Batch queue [SYS$BATCH]: Execute after [NOW]:

The version of the application specified by the version question is represented in the CMS library by a class with a name of the form appl_vrsn where appl is the application code and vrsn is an OpenVMS kit style version number. For example, V1.0 becomes V010.

The environments requested in the four environment questions are represented in the CMS library by classes of the form appl_envr where appl is the application code and envr is the environment code. The defaults for these four questions are derived by translating the logical names appl_DFLT_ENVR_envr for each envr from the set of standard environment codes DEV, DTST, MNT and MTST. These logical names would normally be defined in the application logical name table by the application LOGICALS.COM command procedure. If an appl_DFLT_ENVR_envr logical doesn't translate, a translation of the logical name of the form SWRK_DFLT_ENVR_envr is attempted.

The build questions apply to the development or maintenance environment preceding them. There are no builds performed in the development testing or maintennace testing environments. The builds performed are the equivalent of

build/from_sources