|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 Tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: P T
Length: 192762 (0x2f0fa)
Types: TextFile
Names: »PM_HELP«
└─⟦5f3412b64⟧ Bits:30000745 8mm tape, Rational 1000, ENVIRONMENT 12_6_5 TOOLS
└─⟦91c658230⟧ »DATA«
└─⟦f6fec0485⟧
└─⟦this⟧
@node !Commands.Activity
An activity maintains a mapping between subsystems and pairs of
views. The pair consists of a spec view and a load view from
that subsystem. An activity typically is used to specify an
implementation from each subsystem to be used for execution.
This package provides operations for creating, viewing, and
manipulating activities and for identifying which activity is
the current activity for a running job or session.
Editing Activities
In addition to the commands relating to activities, an editor
provides editing operations specific to activities. Many of the
operations in package !Commands.Common apply to activities. An
activity can be viewed with the Edit command (or simply by getting
the definition of the activity) and then can be edited with common
editing operations. This section describes the commands from
package !Commands.Common that apply to activities. Operations
from package Common that do not apply to activities produce a
message to that effect in the Message window.
Changes to activities are not made permanent until committed. When
an activity is changed, but not yet committed, the # symbol appears
in the window banner. Committing the activity makes all changes
to the activity permanent, and the = symbol appears in the window
banner.
Commands from Package !Commands.Common
!Commands.Common.Abandon
Ends editing of the activity and removes the window from the
screen. Because all changes to activities are not made permanent
until committed, any uncommitted changes will be lost.
!Commands.Common.Commit
Makes permanent any changes made to the activity.
!Commands.Common.Create_Command
Creates a Command window below the current window. The use clause
in the Command window includes package Activity, so operations in
package Activity are directly visible without qualification in the
Command window.
!Commands.Common.Definition
Finds the definition of the subsystem corresponding to the selected
entry or the entry on which the cursor resides, in the compressed
form of an activity. For expanded entries (that is, those expanded
to three lines: one each for the subsystem, the spec view, and the
load view), this command finds the definition of the corresponding
subsystem, spec view, or load view. This procedure creates a
window containing that subsystem or view.
!Commands.Common.Edit
Prompts the user for changes to the selected entry, or to the
entry on which the cursor resides when [Edit] is pressed, by creating
a Command window and placing in it the command:
Change (Spec_View => "", Load_View => "");
The user fills in values for one or both parameters, as desired.
Spec- or load-view entries also can be specified indirectly through
another activity. By specifying the name of an activity rather
than the name of an actual view, the user indicates that the
name of the desired view should be derived from the subsystem's
corresponding entry in the specified activity.
!Commands.Common.Release
Makes any changes to the activity permanent, releases control of
(unlocks) the activity, and then destroys the window.
!Commands.Common.Sort_Image
Sorts the activity image according to the specified sort format.
These formats are specified by number:
1 Sorts by subsystem
2 Sorts by kind and subsystem
3 Sorts by kind and value
4 Sorts by kind and view
5 Sorts by value and subsystem
6 Sorts by value and kind
7 Sorts by view and subsystem
8 Sorts by view and kind
!Commands.Common.Object.Child
Selects the entry in the activity on which the cursor currently
resides. If an entry is already selected, this command has no
effect.
!Commands.Common.Object.Delete
Deletes the selected entry or the entry on which the cursor
resides.
!Commands.Common.Object.Elide
Controls the level of detail displayed in the image of the current
activity. Successive uses display successively less information
about the activity entries, proceeding from top to bottom in the
following list:
o All data by subsystem
o Load data by subsystem (indirections are identified)
o Spec data by subsystem (indirections are identified)
o Both views by subsystem
o Load views by subsystem (indirections are not identified)
o Spec views by subsystem (indirections are not identified)
o Subsystems by subsystem
!Commands.Common.Object.Expand
Controls the level of detail displayed in the image of the current
activity. Successive uses display successively more information
about the activity entries, proceeding from bottom to top in the
list given under Common.Object.Elide.
!Commands.Common.Object.Explain
Uncompresses a subsystem entry, separating each component
(subsystem name, spec view, and load view) of the entry onto
separate lines.
!Commands.Common.Object.First_Child
Selects the first entry of the activity.
!Commands.Common.Object.Insert
Inserts a new subsystem entry or modifies an existing entry in the
activity by prompting the user. Creates a Command window and places
in it the command:
Insert (Subsystem => "", Spec_View => "", Load_View => "");
The user fills in values for parameters, as desired. If the
subsystem name is omitted, it will be derived from the view names,
provided that these are full pathnames.
Spec- or load-view entries also can be specified indirectly through
another activity. By specifying the name of an activity rather
than the name of an actual view, the user indicates that the
name of the desired view should be derived from the subsystem's
corresponding entry in the specified activity.
!Commands.Common.Object.Last_Child
Selects the last entry of the activity.
!Commands.Common.Object.Next
Selects the next entry in the activity if an entry is selected.
If no entry is selected, this command selects the entry on which
the cursor currently resides. If all entries are selected, this
procedure produces an error.
!Commands.Common.Object.Parent
Selects the entry in the activity on which the cursor currently
resides. If an entry is already selected, the procedure selects
all entries in the activity. Otherwise, the procedure has no
effect.
!Commands.Common.Object.Previous
Selects the previous entry in the activity if an entry is selected.
If no entry is selected, the procedure selects the entry on which
the cursor currently resides. If all entries are selected, this
procedure produces an error.
@node !Commands.Activity.Activity_Name
subtype Activity_Name is String;
Defines a string pathname that resolves to an activity in the
directory system.
@node !Commands.Activity.Add
procedure Add
(Subsystem : Subsystem_Name := "<CURSOR>";
Load_Value : View_Or_Activity_Name := Activity.Nil;
Spec_Value : View_Or_Activity_Name := Activity.Nil;
The_Activity : Activity_Name := Activity.The_Current_Activity;
Mode : Creation_Mode := Activity.Exact_Copy;
Response : String := "<PROFILE>");
Modifies the activity specified by The_Activity parameter by
updating an existing entry for a subsystem or by adding a new entry
if an entry for the specified subsystem does not already exist.
@node !Commands.Activity.Change
procedure Change (Spec_View : View_Or_Activity_Name := "";
Load_View : View_Or_Activity_Name := "");
Modifies the spec-view and/or load-view components of the
currently selected subsystem entry or the entry on which the cursor
currently resides.
The !Commands.Common.Edit command prompts the user with this
command. This command is meaningful only in a Command window
associated with an activity.
@node !Commands.Activity.Create
procedure Create (The_Activity : Activity_Name := ">>ACTIVITY NAME<<";
Source : Activity_Name := Activity.Nil;
Mode : Creation_Mode := Activity.Exact_Copy;
Response : String := "<PROFILE>");
Creates a new activity.
The created activity may be derived from the source activity based
on the Mode parameter.
@node !Commands.Activity.Creation_Mode
type Creation_Mode is (Differential, Exact_Copy, Value_Copy);
Defines three modes for the creation of spec-view and load-view
references for subsystem entries.
Differential
Indicates that the new entry should be formed as an indirect
reference to the source activity. The created entry will not be
the name of a view but the name of another activity that specifies
an actual view or another activity from which to derive the
view. With this mode, changes made to the source activity will
be reflected in the target activity.
Exact_Copy
Indicates that the new entry should be formed as an exact copy
of the entry in the source activity. Thus, if the source entry
contains the name of an actual view, the new entry also will
contain the actual view. If the source entry contains an indirect
reference, the new entry will contain an identical indirect
reference.
Value_Copy
Indicates that the new entry should be formed as the dereferenced
value of the corresponding source entry. Indirect (differential)
references will be resolved until an actual view is found.
@node !Commands.Activity.Current
procedure Current (Response : String := "<PROFILE>");
Displays the name of the activity that is associated with the
current job.
If no activity has been associated with the job, the procedure
returns the activity currently associated with the running
session.
The current activity is set by the Set and Set_Default procedures.
@node !Commands.Activity.Display
procedure Display
(Subsystem : Subsystem_Name := "?";
Spec_View : View_Name := "?";
Load_View : View_Name := "?";
Mode : Creation_Mode := Activity.Value_Copy;
The_Activity : Activity_Name := Activity.The_Current_Activity;
Response : String := "<PROFILE>");
Displays an image of the specified activity.
Only the mappings that match the patterns (Environment naming
conventions, including wildcards) given in the Subsystem,
Spec_View, and Load_View parameters are listed. In Value_Copy
mode, all indirect references are resolved; only the resolution is
displayed. In Exact_Copy mode, indirect mappings are not resolved;
the name of the source activity is displayed. In Differential
mode, the indirect mappings are resolved; both the resolution and
the original indirect activity are displayed.
@node !Commands.Activity.Edit
procedure Edit (The_Activity : Activity_Name := "<ACTIVITY>");
Invokes the activity object editor on the specified activity.
The default is to edit the current activity.
@node !Commands.Activity.Enclosing_Subsystem
procedure Enclosing_Subsystem (View : View_Name := "<IMAGE>";
Response : String := "<PROFILE>");
Displays the name of the subsystem that contains the specified
view.
The default is the currently selected view, the view containing the
current selection, or the view containing the current context.
The view may be either a spec or a load view.
@node !Commands.Activity.Enclosing_View
procedure Enclosing_View (Unit : Unit_Name := "<IMAGE>";
Response : String := "<PROFILE>");
Displays the name of the view that contains the specified unit.
The default is the currently selected unit or unit image.
@node !Commands.Activity.Insert
procedure Insert
(Subsystem : Subsystem_Name := ">>SUBSYSTEM NAME<<";
Spec_View : View_Or_Activity_Name := "";
Load_View : View_Or_Activity_Name := "");
Modifies an activity to update an existing entry for a subsystem
or adds a new entry if one does not already exist for the specified
subsystem.
The !Commands.Common.Object.Insert command prompts the user with
this command. This command is meaningful only in a Command window
associated with an activity.
@node !Commands.Activity.Merge
procedure Merge (Source : Activity_Name := ">>ACTIVITY NAME<<";
Subsystem : Subsystem_Name := "?";
Spec_View : View_Name := "?";
Load_View : View_Name := "?";
Mode : Creation_Mode := Activity.Exact_Copy;
Target : Activity_Name := "<ACTIVITY>";
Response : String := "<PROFILE>");
Copies into the specified target those subsystem entries defined
in the source activity that match the patterns specified in the
Subsystem, Spec_View, and Load_View parameters.
New subsystem entries are added as necessary; existing subsystem
entries are replaced.
Patterns for the Subsystem, Spec_View, and Load_View parameters
are the standard Environment naming conventions and wildcards.
@node !Commands.Activity.Nil
function Nil return Activity_Name;
Returns the name of an empty activity.
@node !Commands.Activity.Remove
procedure Remove
(Subsystem : Subsystem_Name := "<SELECTION>";
The_Activity : Activity_Name := Activity.The_Current_Activity;
Response : String := "<PROFILE>");
Deletes a subsystem entry from an activity.
The default activity is the current activity for the job or
session.
@node !Commands.Activity.Set
procedure Set (The_Activity : Activity_Name := "<ACTIVITY>";
Response : String := "<PROFILE>");
Changes the current activity for the running job to the specified
activity.
A session may have a current activity associated with it. The
Set_Default procedure is used to form this association. When a job
begins execution, its current activity is that of the current
session. The Set procedure changes a job's current activity
without changing the session's activity. Thereafter, until the
job terminates, the new activity is consulted when necessary,
instead of the current session's activity.
Note that this procedure cannot be used to affect the loading of a
subsequent command in the same job. Loading is done for the entire
job before execution begins and thus would be unaffected by the
execution of the Set command. In the following example:
Activity.Set ("New_Activity_Name");
Command_Requiring_Loading;
the Command_Requiring_Loading command will be loaded with the
current session's activity and not with New_Activity_Name.
By contrast, in the example:
Activity.Set ("New_Activity_Name");
Program.Run ("Command_Requiring_Loading");
the loading for the command via Program.Run is performed after the
execution of the Set procedure and thus will use New_Activity_Name.
@node !Commands.Activity.Set_Default
procedure Set_Default (The_Activity : Activity_Name := "<ACTIVITY>";
Response : String := "<PROFILE>");
Makes the specified activity the current activity for the current
session.
This procedure sets the value of the Profile.Activity_File
session switch. If the current activity of the job that executes
Set_Default is nil, the procedure sets this activity as well.
The default activity for a session is also preserved across
logouts.
@node !Commands.Activity.Set_Load_View
procedure Set_Load_View
(Load_View : View_Or_Activity_Name := "<CURSOR>";
Subsystem : Subsystem_Name := "";
Mode : Creation_Mode := Activity.Differential;
The_Activity : Activity_Name := Activity.The_Current_Activity;
Response : String := "<PROFILE>");
Modifies the load view for the specified subsystem entry in
The_Activity parameter.
If an entry for the specified subsystem does not exist, one is
added to the activity.
@node !Commands.Activity.Set_Spec_View
procedure Set_Spec_View
(Spec_View : View_Or_Activity_Name := "<CURSOR>";
Subsystem : Subsystem_Name := "";
Mode : Creation_Mode := Activity.Differential;
The_Activity : Activity_Name := Activity.The_Current_Activity;
Response : String := "<PROFILE>");
Modifies the spec view for the specified subsystem entry in
The_Activity parameter.
If an entry for the specified subsystem does not exist, one is
added to the activity.
@node !Commands.Activity.Subsystem_Name
subtype Subsystem_Name is String;
Defines a string pathname that resolves to a subsystem in the
directory system.
@node !Commands.Activity.The_Current_Activity
function The_Current_Activity return Activity_Name;
Returns the name of the current activity associated with the
running job.
If no activity has been associated with the running job, this
function returns the activity associated with the running session.
@node !Commands.Activity.The_Enclosing_Subsystem
function The_Enclosing_Subsystem (View : View_Name := "<IMAGE>")
return Subsystem_Name;
Returns the name of the subsystem that contains the specified view.
The default is the currently selected view, the view containing the
current selection, or the view containing the current context.
@node !Commands.Activity.The_Enclosing_View
function The_Enclosing_View (Unit : Unit_Name := "<IMAGE>")
return View_Name;
Returns the name of the view that contains the specified unit.
@node !Commands.Activity.Unit_Name
subtype Unit_Name is String;
Defines a string pathname that resolves to an Ada compilation unit
in the directory system.
@node !Commands.Activity.View_Name
subtype View_Name is String;
Defines a string pathname that resolves to a view of a subsystem.
@node !Commands.Activity.View_Or_Activity_Name
subtype View_Or_Activity_Name is String;
Defines a string pathname that resolves either to a view of a
subsystem or to an activity in the directory system.
@node !Commands.Activity.View_Simple_Name
subtype View_Simple_Name is String;
Defines a string that is the simple name of a view of a subsystem.
A simple name is an unqualified name not prefixed with the name of
the object's parent.
@node !Commands.Activity.Visit
procedure Visit (The_Activity : Activity_Name := "<ACTIVITY>");
Invokes the activity editor on the specified activity and replaces
the old activity if one is currently being edited.
This procedure is identical to the !Commands.Common.Edit command,
except that if the command is given on an activity window, the new
activity is displayed in that window rather than in a new one.
@node !Commands.Activity.Write
procedure Write (File : Activity_Name := "<ACTIVITY>");
Copies the contents of an activity window into a new activity in
the directory system.
This command is valid only in an activity window.
@node !Tools.Compatibility.Revn.Units.Check
Package Check provides interfaces for checking the compatibility
between spec and load views in a subsystem. Compatibility is
defined in the Key Concepts to this book. Command-oriented
interfaces and programmatic interfaces with status values are
provided. Interfaces are available for comparing units in load
views with their corresponding units in spec views or for comparing
a set of spec/load-view pairs.
The compatibility checking done by this package checks that every
declaration exported by a spec-view unit is also exported by the
corresponding load-view unit and that the spec and load views have
the same target key. These declarations do not need to be in the
same order or textually identical. Two declarations are considered
equivalent if they match according to the subprogram specification
conformance rules of the Ada Language Reference Manual, section
6.3.1. All units involved in the check must be in the installed or
coded state.
It is possible to construct an activity such that the spec/load-
view pairs named by the activity are compatible but the set of
load views specified would not execute correctly together. For
example, this could happen if two load views in the activity import
different spec views of the same subsystem. The checks done by
this package will not catch those situations, but the loader will
check for this and report these types of problems at load time.
@node !Tools.Compatibility.Revn.Units.Check.Activity
procedure Activity (The_Activity : String := "<ACTIVITY>";
Menu : Boolean := False;
Response : String := "<PROFILE>");
function Activity (The_Activity : String := "<ACTIVITY>";
Response : String := "<PROFILE>") return Status;
Checks the compatibility of all spec-view and load-view pairs
specified in an activity.
For each subsystem entry in the activity, each unit in the spec
view is checked for compatibility with the corresponding unit in
the load view. If an entry for a subsystem does not specify both a
spec and a load view, that subsystem will not be checked.
Two interfaces are provided: a procedure interface for Command
window usage and a functional interface returning a status value
for use in building tools.
@node !Tools.Compatibility.Revn.Units.Check.Status
type Status is (Compatible, Incompatible, Error);
Defines the range of possible outcomes of a compatibility check.
Compatible
Indicates that the unit or units included in the check are all
compatible with each other.
Error
Indicates that the operation failed to complete successfully. For
example, the name of a unit or view may not be resolvable. The log
output can be consulted to determine the reason for the error.
Incompatible
Indicates that at least one unit included in the check is not
compatible with another unit. The log output can be consulted to
determine which unit or units are not compatible.
@node !Tools.Compatibility.Revn.Units.Check.Units
procedure Units (Load_View_Units : String := "<CURSOR>";
Spec_Views : String := "<ACTIVITY>";
Menu : Boolean := False;
Response : String := "<PROFILE>");
function Units (Load_View_Units : String := "<CURSOR>";
Spec_Views : String := "<ACTIVITY>";
Response : String := "<PROFILE>") return Status;
Checks the compatibility of a set of units in load views with their
corresponding units in the specified spec views.
The Load_View_Units parameter specifies the set of units to be
checked, and the Spec_Views parameter specifies the set of spec
views used to perform the check.
Two interfaces are provided: a procedure interface for Command
window usage and a functional interface returning a status value
for use in building tools.
@node !Tools.Compatibility.Revn.Units.Check.Views
procedure Views (Load_Views : String := "<CURSOR>";
Spec_Views : String := "<ACTIVITY>";
Menu : Boolean := False;
Response : String := "<PROFILE>");
function Views (Load_Views : String := "<CURSOR>";
Spec_Views : String := "<ACTIVITY>";
Response : String := "<PROFILE>") return Status;
Checks the compatibility of all units in one or more spec/load-view
pairs.
The Load_View parameter specifies the set of views to be checked,
and the Spec_Views parameter specifies the set of spec views used
to perform the check.
Two interfaces are provided: a procedure interface for Command
window usage and a functional interface returning a status value
for use in building tools.
@node !Commands.Cmvc
Package Cmvc defines a set of operations that support the following
activities of project management:
o Partitioning projects into components using subsystems and
managing the interfaces among these components
o Creating and releasing alternative implementations (views) of
individual project components
o Placing the objects within project components under source
control to record generations of change history and to coordinate
the work of multiple developers
o Coordinating parallel development efforts both within and
between subsystems
The Key Concepts section of this book provides a guide to project
development using subsystems, views, and source control.
The following sections in this package introduction provide:
o A list of CMVC commands grouped by topic
o A summary of the types of objects you can create and manage
through CMVC commands
o A guide to the images and operations for managing configuration
information interactively
o A list of switches and commands from package Common that pertain
to CMVC
Commands Grouped by Topic
The commands in package Cmvc fall into several functional groups.
They are listed here by group for your convenience. (Note that the
reference entries for these commands are arranged in alphabetical
order by command name.)
o Commands for creating and destroying subsystems and systems:
Initial Destroy_Subsystem Destroy_System
o Commands for creating, releasing, destroying, and recreating
views:
Build Copy Destroy_View
Initial Make_Code_View Make_Path
Make_Spec_View Make_Subpath Release
o Commands for managing source control:
Abandon_Reservation Accept_Changes Check_In
Check_Out Join Make_Controlled
Make_Uncontrolled Merge_Changes Revert
Sever
o Commands for managing subsystem interfaces:
Import Imported_Views Remove_Imports
Remove_Unused_Imports Replace_Model
o Commands for interactively viewing notes and configuration
information:
Def Edit Notes
o Commands for displaying reports in I/O windows:
Information Show
Show_All_Checked_Out Show_All_Controlled
Show_All_Uncontrolled Show_Checked_Out_By_User
Show_Checked_Out_In_View Show_History
Show_History_By_Generation Show_Image_Of_Generation
Show_Out_Of_Date
o File-oriented commands for managing notes:
Append_Notes Create_Empty_Note_Window
Get_Notes Put_Notes
System Object and View Types
The Cmvc.Initial command can create several types of system objects
(see also System_Object_Enum type). A system object refers to both
systems and subsystems:
o Subsystems provide a means of partitioning applications into
components to facilitate parallel development, minimize
recompilation dependencies, and enforce design decisions. Each
subsystem contains the units that implement a component of an
application. As development progresses within a given subsystem,
releases can be made of its implementation.
o Systems provide an optional means of grouping the subsystems
that compose an application; within a system, operations are
available for tracking the latest release from each subsystem and
for referencing those releases for execution. These releases are
referenced by release activities that are built and maintained
within the system. Systems can form a hierarchy by including
other systems.
There is only one type of system, and systems contain only one type
of view---namely, system views. In contrast, there are two types
of subsystem---spec/load subsystems and combined subsystems.
Spec/load subsystems can contain spec and load views, which
function together, as well as combined views. Combined subsystems
can contain only combined views.
Within a spec/load subsystem, load views and combined views can be
created using the Initial, Copy, or Make_Path command; spec views
are created using the Make_Spec_View or Copy command:
o A load view contains an implementation of a subsystem. Load
views are specified in activities and are actually used for
execution.
o A spec view expresses a subsystem's exports. Exports are the
specifications of implemented units that are made available for
units in other subsystems to reference in with clauses. When a
spec view is imported by a view in another subsystem, units in
the importing view can compile against the units in the imported
view.
o A combined view combines characteristics of spec and load views.
A combined view both contains a subsystem implementation and
expresses the exports from that implementation. When a combined
view is imported, units in the importing subsystem can compile
against the combined view's units; at execution time, the units
in that combined view are executed.
Spec and load views provide greater flexibility than combined
views during development and test. Using spec and load views
minimizes the recompilation required after changes are made and
eliminates the need for recompilation during recombinant testing.
Using combined views involves no such reduction of recompilation
requirements; from a recompilation point of view, development in
combined views is equivalent to development in worlds. (Note,
however, that development in combined views makes CMVC operations
available, which are not available in worlds.)
In spite of the advantages of spec and load views, combined views
must be used in spec/load subsystems under certain circumstances-
--namely, when generics or inlined subprograms are exported from
implementations for non-R1000 targets.
Combined views also must be used in combined subsystems. Combined
subsystems must be used when import relationships in an application
need to be circular---that is, when a given view must be within its
own import closure (for example, when two views must import each
other). In contrast, import relationships among views in spec/load
subsystems must be hierarchic.
Within any system object (subsystem or system), there are working
views within which ongoing development and maintenance proceeds. A
view is recognized as a working view through a naming convention-
--namely, the _Working suffix. A load view, a combined view, or a
system view can serve as a working view.
At any time during development and maintenance, a release can
be made from a working view. A release is a frozen copy of the
working view; releases typically are made after the implementation
in the working view is compiled and tested.
Managing CMVC Information Interactively
When objects are controlled in one or more views in a subsystem,
you typically need to know the following information, which is
managed by the CMVC database:
o Which objects are controlled?
o Which objects are checked out and to which views?
o Which objects are joined to objects in other views?
o Which views contain the other objects in the join set?
o Which objects in a join set are out of date and which view
contains the latest generation of these objects?
Furthermore, because multiple generations typically exist for a
given object in a view, it is useful to be able to:
o View images of past generations for the object.
o View the line-by-line differences between two successive
generations.
o Find out when a given generation was created.
o Keep a scratchpad of notes recording the changes that were made
to each generation.
o Review the comments that were supplied each time the object was
checked out and checked in.
The Def, Edit, and Notes procedures bring up three kinds of
images in which such information is displayed. These images are
configuration images, generation images, and history images.
These images not only provide several levels of information but
also make available commands from package Common, which you can use
to traverse to other images and perform certain CMVC operations.
Configuration Images
The Edit procedure displays a configuration image for a specified
view or configuration object or for the view enclosing a specified
controlled object. A configuration image for a view is a library-
like display of CMVC information pertaining to the configuration
embodied by that view. (A configuration is a set of generations,
one for each controlled object in the view.) Note that Edit can be
used to display a configuration image for a configuration object
that has no view associated with it (for example, a configuration
release).
The information displayed in a configuration image represents the
contents of the CMVC database at the time the Edit procedure is
entered. Subsequent CMVC operations can change the CMVC database
without automatically updating the configuration image. You
can refresh a configuration image using the Common.Format or
Common.Revert command.
Levels of Information in Configuration Images
Several levels of information are available in a configuration
image. For example, Figure 11-1 shows the configuration image
displayed for the view !Programs.Mail.Mail_Utilities.
This image contains the first level of configuration information.
This level contains an entry for each controlled object in the
view's configuration. Each entry indicates the generation of the
object that is present in the view. An entry also indicates the
latest generation that exists for the object in any view, if the
object is out of date. Thus, Rev1_Working contains generation 4
out of a possible five generations for Destinations'Body.
With the cursor on the first line in the configuration image, the
Common.Expand command displays the second level of configuration
image, as shown in Figure 11-2.
Each entry in this expanded configuration image contains the
following additional information (from left to right):
o An asterisk indicating whether the object is out of date in the
view
o An indication of whether the unit is currently checked out (Out)
or checked in (In); libraries are indicated as Lib
o The date and time at which the object was checked out (if the
object is currently checked out) or checked in (if the object is
currently checked in)
o The user who performed the last checkout or checkin
o The view in which a given object is currently checked out
When objects are checked out or out of date, portions of their
entries are underlined, so you can use the Editor.Cursor.Next and
Editor.Cursor.Previous commands to move the cursor among these
objects.
Using Common.Expand again displays a third level of configuration
information, as shown in Figure 11-3. Each entry now displays the
reservation token associated with each controlled object in the
view.
Finally, using Common.Expand again displays a fourth level of
configuration information, as shown in Figure 11-4. At this level,
the entry for a given joined object displays the views containing
other objects in the join set.
Operations in Configuration Images
At any level of expansion, a configuration image provides a
convenient way to:
o Check objects in, using the Common.Promote command
o Check objects out, using the Common.Demote command
o Accept changes on objects, using the Common.Complete command
o Access generation and history images, using the
Common.Definition and Common.Explain commands, respectively
o Traverse to the designated object in the associated view, using
the Cmvc.Def command
A complete list of operations is given in "Commands from Package
!Commands.Common," below.
Restricting Operations in Configuration Images
Operations in configuration images can be restricted using the
Edit command. When creating a configuration image, you can set
the Allow_Check_Out, Allow_Check_In, and Allow_Accept_Changes
parameters to false to prevent the corresponding operations from
accessing objects through the configuration image.
You can also use the Edit command to reset the restrictions
on these operations in an existing configuration image. For
example, if a checkout operation currently is not permitted in
a given configuration image, you can enter the Edit command with
Allow_Check_Out set to true.
Alternative Ways of Displaying a Configuration Image
The basic way to create a configuration image is to enter the Edit
command from a view or object. Following are two alternative ways
of creating a configuration image:
o Within the Configurations directory in a subsystem, put the
cursor on the name of a configuration object and enter the
Common.Definition command.
o From a generation image (see "Generation Images," below), enter
the Common.Enclosing command.
In both of these cases, checkin, checkout, and accept-changes
operations are automatically restricted in the configuration
image. However, the Edit command can be entered from the existing
configuration image to change these restrictions as specified by
the Allow_Check_Out, Allow_Check_In, and Allow_Accept_Changes
parameters.
Generation Images
Generation images are textual representations of particular
generations of controlled objects. Generation images can be
displayed even for generations of objects that do not currently
exist outside the CMVC database. For example, using generation
images, you can browse the text of past generations from
configuration-only releases or from code views, which no longer
contain source objects. A given generation image can be expanded
to show differences between that generation and the previous one.
Generation images are available only for controlled objects for
which source is saved.
Accessing Generation Images
Generation images can be accessed in several ways. They can be
accessed from configuration images:
1. Display the configuration image for a view, code view, or
configuration object.
2. With the cursor on the configuration image entry for the desired
object, enter the Common.Definition command.
Alternatively, you can access a generation image for a given object
directly from view, as follows:
1. Put the cursor on the object's entry in the view.
2. Enter the Cmvc.Def command.
Generation images contain text reconstructed from the CMVC
database and does not have the underlying structure of an Ada
unit. Therefore, commands such as Common.Object.Parent select
text structures such as lines rather than Ada structures. A
generation image is identified in the window banner by the
generation attribute following the object's name and by the string
(cmvc).
Accessing Next and Previous Generation Images
An object's generations form a sequence from the starting
generation to the latest generation. When the image of a
particular generation is displayed, you can access images for
the previous and next generations in the sequence as follows:
o With the cursor in the generation image, enter the Common.Undo
command to access the image for the previous generation in the
sequence. Repeated uses of Common.Undo iterate toward the
starting generation.
o With the cursor in the generation image, enter the Common.Redo
command to access the image for the next generation in the
sequence. Repeated uses of Common.Redo iterate toward the latest
generation.
Displaying the Differences between Consecutive Generations
A given generation image can be expanded to show the differences
between it and the previous generation. Enter the Common.Expand
command to expand a generation image. (The Common.Elide command
removes the differences from the display.) For example, Figure 11-5
shows the result of using Common.Expand in the generation image for
generation 4 of Destinations'Body.
Differences are shown on a line-by-line basis:
o A line beginning with the minus sign (-) indicates that the line
was deleted from the previous generation.
o A line beginning with the plus sign (+) indicates that the line
was added to the previous generation.
o One or more lines beginning with the minus sign immediately
followed by one or more lines beginning with the plus sign
indicate changed lines.
Regions of difference begin with an underline so that you can use
the Editor.Cursor.Next and Editor.Cursor.Previous commands to move
the cursor among such regions.
Other operations available in generation images are listed in
"Commands from Package !Commands.Common," below.
History Images
The CMVC database stores history information pertaining to each
generation of a controlled object. The history image for a given
generation displays this stored information. Figure 11-6 shows the
history image for generation 4 of Destinations'Body.
The history image for a generation of an object contains:
o The history for the generation, which lists the time of checkout
and checkin and the user who performed these operations
o The notes for the generation, which contains comments provided to
various CMVC commands as well as arbitrary commentary associated
with that generation
The CMVC database also stores release history for each
configuration. Release history contains comments provided through
the Cmvc.Release command and also lists the date and time at which
spec views and releases were created.
Accessing History Images
History images can be accessed in several ways. They can be
accessed from configuration images:
1. Display the configuration image for a view, code view, or
configuration object.
2. With the cursor on the configuration image entry for the desired
object, enter the Common.Explain command.
If the cursor is on the header line of a configuration image,
then Common.Explain displays the release history for the
configuration.
If the cursor is on an underline other than the header line, an
explanation of the underline is displayed in the Message window.
Move the cursor off the underline to display a history window.
History images also can be accessed from generation images:
1. With the cursor in the appropriate generation image, enter the
Common.Explain command.
Finally, a history image for a given object can be accessed
directly, as follows:
1. Put the cursor on the object or on its directory entry.
2. Enter the Cmvc.Notes command.
Displaying History from Other Generations
From a history image, the Common.Undo and Common.Redo commands
iterate through history images of the previous and next
generations, respectively.
Furthermore, using the Common.Expand command in a history image
displays the cumulative history and notes for a range of previous
generations within the same image. The number of previous
generations for which history is displayed is determined by the
Repeat parameter of the Common.Expand command. The Common.Elide
command reduces the amount of cumulative history by the number of
generations specified by its Repeat parameter.
Managing Notes through History Images
History images provide an interactive way to manage notes. From a
history image, new notes can be added and saved. The Common.Edit
command displays a prompt in which additional notes can be entered.
The Common.Save or Common.Commit commands save the new notes in the
CMVC database.
The window banner for a history image contains the object name
followed by a generation attribute (for example 'G(3)), followed by
the attribute 'History. Furthermore, the window banner contains
the string (cmvc).
Traversing between Library and CMVC Images
Subsystems, views, configuration objects, and objects such as
files and Ada units are all part of the Environment library system.
Associated with these library objects are configuration images,
generation images, and history images, which display information
managed by the CMVC database.
As shown in Figure 11-7, the Cmvc.Edit, Cmvc.Def, and Cmvc.Notes
commands traverse between objects in the library system and images
managed by CMVC. Commands from package Common traverse among images
within each group.
Figure 11-8 shows the use of Common.Undo and Common.Redo to access
generation images for different generations of the same object.
Session Switches
A number of session switches have names that begin with the prefix
"Cmvc_". All but one of these pertain to objects that are
managed by commands in package Work_Order and are documented in
that package. The remaining switch, Cmvc_Enable_Relocation, is
for use by Rational personnel only.
Commands from Package !Commands.Common
Commands from Package Common in Configuration Images
!Commands.Common.Complete
Equivalent to entering the Accept_Changes command to update
the designated object (or the objects in the designated
configuration) to the latest generation. The Accept_Changes
operation is performed with default parameter values, except
that Allow_Demotion has the value true. The configuration image
is updated to reflect the operation. The operation performed
by the command is subject to restriction according to the
Allow_Accept_Changes parameter of the Cmvc.Edit command.
!Commands.Common.Definition
Displays the generation image for the current generation of the
object whose entry is designated in a configuration image. An
In_Place parameter specifies whether the current frame should be
used.
!Commands.Common.Demote
Equivalent to entering the Check_Out command to check out
the designated object (or the objects in the designated
configuration). The Check_Out operation is performed with default
parameter values, except that Allow_Demotion has the value true.
The configuration image is updated to reflect the operation. The
operation performed by the command is subject to restriction
according to the Allow_Check_Out parameter of the Cmvc.Edit
command.
!Commands.Common.Edit
Checks out the object whose entry is designated in the
configuration image and then displays the object. The object is
not opened for editing, in case it is an Ada unit to which you want
to make incremental changes. The Check_Out operation is performed
with default parameter values, except that Allow_Demotion has
the value true. The configuration image is updated to reflect
the operation. The operation performed by the command is subject
to restriction according to the Allow_Check_Out parameter of the
Cmvc.Edit command.
!Commands.Common.Elide
Reduces the level of information displayed in the configuration
image. As designated by the cursor, the level can be reduced for
an individual entry or for the entire image (the cursor must be on
the top header line of the image). See "Levels of Information in
Configuration Images," above.
!Commands.Common.Enclosing
Displays the subsystem that contains the configuration represented
in the configuration image. An In_Place parameter specifies
whether the current frame should be used.
!Commands.Common.Explain
Displays the history image for the generation of the designated
object. If the cursor is on the top header line in the
configuration image, release history for the configuration is
displayed. If the cursor is on an underline (other than the
header), an explanation of the underline is given.
!Commands.Common.Expand
Increases the level of information displayed in the configuration
image. As designated by the cursor, the level can be increased for
an individual entry or for the entire image (the cursor must be on
the top header line of the image). See "Levels of Information in
Configuration Images," above.
!Commands.Common.Format
Updates the configuration image with current information
from the CMVC database. Note that the configuration image is
updated automatically after Common.Promote, Common.Demote, or
Common.Complete is executed, but it is not updated when the CMVC
database is changed by any other operation.
!Commands.Common.Promote
Equivalent to entering the Check_In command to check in
the designated object (or the objects in the designated
configuration). The configuration image must have a view
associated with it. The Check_In operation is performed with
default parameter values. The configuration image is updated to
reflect the operation.
!Commands.Common.Revert
Updates the configuration image with current information from the
CMVC database. Note that the configuration image is automatically
updated after Common.Promote, Common.Demote, or Common.Complete is
executed, but it is not updated when the CMVC database is changed
by any other operation.
Commands from Package Common in Generation Images
!Commands.Common.Definition
Displays the controlled object associated with the generation in
the generation image containing the cursor. An In_Place parameter
specifies whether the current frame should be used.
!Commands.Common.Elide
Removes from the generation image the differences that were
displayed by the Common.Expand command.
!Commands.Common.Enclosing
Displays the configuration image for the last configuration that
was visited. An In_Place parameter specifies whether the current
frame should be used.
!Commands.Common.Explain
Displays the history image for the generation represented in the
current generation image. If the cursor is on an underline, an
explanation of the underline is given.
!Commands.Common.Expand
Displays the differences between the generation in the generation
image and the previous generation. Differences are shown on a
line-by-line basis. Lines beginning with a minus sign (-) indicate
lines deleted from the previous generation. Lines beginning with a
plus sign (+) indicate lines added to the previous generation. The
start of each difference region is underlined.
!Commands.Common.Redo
Displays the generation following the generation represented in
the current generation image. A Repeat parameter specifies which
succeeding generation is displayed, relative to the currently
displayed generation.
!Commands.Common.Undo
Displays the generation previous to the generation represented
in the current generation image. A Repeat parameter specifies
which preceding generation is displayed, relative to the currently
displayed generation.
Commands from Package Common in History Images
!Commands.Common.Commit
Saves the new notes entered through the prompt given by the
Common.Edit command.
!Commands.Common.Definition
Displays the controlled object associated with the generation
for which history is displayed. An In_Place parameter specifies
whether the current frame should be used.
!Commands.Common.Edit
Provides a prompt in the current history image in which new notes
can be entered.
!Commands.Common.Elide
Reduces the cumulative history that is displayed in the current
history image. The Repeat parameter specifies the number of
generations by which the cumulative history should be reduced.
!Commands.Common.Enclosing
Displays the generation image for the generation associated with
the current history image. An In_Place parameter specifies whether
the current frame should be used.
!Commands.Common.Expand
Expands the cumulative history that is displayed in the current
history image. The Repeat parameter specifies the number of
generations by which the cumulative history should be increased.
!Commands.Common.Format
Updates the history image with current information from the CMVC
database.
!Commands.Common.Promote
Saves the new notes entered through the prompt given by the
Common.Edit command.
!Commands.Common.Redo
Displays the history image for the generation following the current
generation. A Repeat parameter specifies which succeeding history
image is displayed, relative to the generation of the current
history image.
!Commands.Common.Revert
Updates the history image with current information from the CMVC
database.
!Commands.Common.Undo
Displays the history image for the generation previous to the
current generation. A Repeat parameter specifies which preceding
history image is displayed, relative to the generation of the
current history image.
@node !Commands.Cmvc.Abandon_Reservation
procedure Abandon_Reservation
(What_Object : String := "<SELECTION>";
Allow_Demotion : Boolean := False;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Abandons the reservation on one or more checked-out objects,
effectively canceling the checkout of those objects.
Any changes made during the canceled checkout are discarded.
When an object is checked out, a new generation is created.
The Abandon_Reservation procedure cancels this newly created
generation and causes the object to revert to the last checked-in
generation.
Note that checking out an object automatically updates that
object to the latest checked-in generation, accepting changes
as necessary. This procedure does not undo the implicit accept
changes, so the object remains at the latest generation.
@node !Commands.Cmvc.Accept_Changes
procedure Accept_Changes
(Destination : String := "<CURSOR>";
Source : String := "<LATEST>";
Allow_Demotion : Boolean := False;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Updates the object(s) specified in the Destination parameter to
the generation(s) indicated by the Source parameter; that is, the
destination objects are changed to reflect any modifications that
have been made to the corresponding source objects.
When changes to individual Ada units are being accepted, unit
specifications should be updated before their corresponding bodies
to ensure that the units compile correctly.
Typically, the Accept_Changes procedure is used to update each
destination object to the latest generation. The procedure thus is
a means of synchronizing the development of controlled objects that
are joined to objects in other views. When an object in a join set
is checked out and then checked in, a new generation is created,
rendering the other objects in the set at least one generation out
of date. This procedure can be used on the out-of-date objects to
update them to the latest generation. (Checking out an out-of-date
object implicitly accepts changes.)
The Accept_Changes procedure also can be used to "go backward
in time." If the name of a previous configuration is given as
the Source parameter, the objects specified by the Destination
parameter are changed to the generations given in that
configuration. Unless such objects are subsequently severed,
however, checking them out automatically updates them to the latest
generation.
The Accept_Changes procedure also can be used to copy new
controlled objects from the source view into the destination view.
This is more effective than using Library.Copy to propagate new
objects across views.
If Ada units are compiled against a specified unit, accepting
changes to that unit may require the demotion of the other
dependent units. The value of the Allow_Demotion parameter
controls whether the command actually performs the demotion and
updates the unit.
The configuration image displayed by the Edit command uses
an asterisk to indicate objects that require updating.
Alternatively, the Show_Out_Of_Date_Objects command can be used
to determine the objects that may require updating.
@node !Commands.Cmvc.Append_Notes
procedure Append_Notes (Note : String := "<WINDOW>";
What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
Appends the specified string to the end of the notes for the
specified controlled object.
The notes for a controlled object are stored in the CMVC database.
An object's notes can be used as a scratchpad for arbitrary
commentary to be associated with particular generations.
The contents of a file can be appended by specifying the filename
as an indirect file.
Append_Notes is one of a set of file-oriented commands for
managing notes. That is, these commands, including Get_Notes,
Create_Empty_Note_Window, and Put_Notes, are most useful for
managing notes through files. However, these commands also manage
special-purpose notes windows (identified by the Notes for string
in the banner) in which the Append_Notes command can be used as
follows:
o If the Create_Empty_Note_Window procedure has been used to
display an empty notes window for an object, text entered in
this window can be appended to the object's existing notes using
the Append_Notes procedure. In this case, Append_Notes must be
entered (with default parameter values) from a Command window
attached to the window that was created by the Create_Empty_Note-
_Window procedure.
Note that modified notes windows retain the * symbol in their
window banners, even after their contents have been entered in the
CMVC database using Append_Notes or Put_Notes. Accordingly, the
Quit command reports these windows as changed images when logout
is attempted. Because these windows cannot be committed, use the
Common.Abandon procedure to remove these windows.
The Notes command provides an interactive alternative to Create-
_Empty_Note_Window, Append_Notes, and the like. The Notes command
displays a history image (identified by 'History attribute
following the object name and generation in the window banner),
which allows interactive operations for managing an object's
notes.
@node !Commands.Cmvc.Build
procedure Build
(Configuration : String := ">>CONFIGURATION NAME<<";
View_To_Import : String := "<INHERIT_IMPORTS>";
Model : String := "<INHERIT_MODEL>";
Goal : Compilation.Unit_State := Compilation.Installed;
Limit : String := "<WORLDS>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Builds views from the specified configuration objects.
Views corresponding to the specified configuration objects must
not already exist.
Whenever a view is created or released, a configuration object is
created for it automatically. The configuration object for a view
lists the specific generations of the controlled objects in that
view and provides an index into the CMVC database where the source
for these generations is stored. Thus, views are realizations of
configuration objects, in that views contain library structure and
compilable units, whereas configuration objects merely summarize
the contents of the corresponding views.
Because configuration objects provide enough information to
reconstruct views, space can be saved by creating or keeping only
the configuration objects for views whose units do not need to be
compiled and executed frequently:
o The Release command creates only a configuration object
without creating the corresponding released view if the
Create_Configuration_Only parameter is true.
o The Destroy_View command destroys only a view without
destroying the corresponding configuration object if the
Destroy_Configuration_Also parameter is false.
The Build command is used when it is necessary to build a view for
a released configuration object or rebuild a destroyed view.
Note that when a view is built (or rebuilt) from a configuration
object, the only objects that can be recreated are controlled
objects for which source is saved in the CMVC database.
(Controlled objects for which source is not saved cannot be
rebuilt.)
Configuration objects reside in the directory subsys-
tem_name.Configurations. Each configuration object has the same
simple name as the view to which it corresponds.
@node !Commands.Cmvc.Check_In
procedure Check_In (What_Object : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Releases the reserved right to update the specified object or set
of objects and stores the text of the new generation(s) in the CMVC
database.
An object that is checked in cannot be modified until it is checked
out again. Only controlled objects can be checked in or out.
Because checked-in objects cannot be modified in any way, it is
recommended that all incremental additions or changes to Ada
units be promoted before those units are checked in. Errors will
result from attempting to compile the checked-in units that contain
insertion points, because promoting insertion points would require
the modification of checked-in units.
Note that checking in an object that was made controlled without
saving source simply releases the right to update that object; no
text is recorded in the CMVC database.
@node !Commands.Cmvc.Check_Out
procedure Check_Out
(What_Object : String := "<CURSOR>";
Comments : String := "";
Allow_Implicit_Accept_Changes : Boolean := True;
Allow_Demotion : Boolean := False;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State :=
Compilation.Coded;
Expected_Check_In_Time : String := "<TOMORROW>";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Reserves the right to modify the specified controlled object or
objects.
Controlled objects can be modified only while they are checked out.
However, objects need not be checked out in order to be compiled.
When objects are joined across multiple views, they share the same
reservation token, so that only one of the joined objects can be
checked out at a time. Checking out a joined object in one view
renders the corresponding objects in the other views unavailable
for update. (In contrast, objects that do not share the same
reservation token can be checked out and modified independently.)
A new generation of an object is created when it is checked out.
The new generation can be preserved by the Check_In command or
abandoned by the Abandon_Reservation command. When one object in
a join set is checked out and then checked in, the other objects in
the set are rendered at least one generation out of date. Checking
out one of the out-of-date objects automatically updates it to
the latest generation, unless the Allow_Implicit_Accept_Changes
parameter has been set to false, in which case the checkout
operation fails. Setting this parameter to false allows an object
to be checked out only if it is at the latest generation already.
(Note that if an object was made controlled without saving source,
Check_Out can implicitly update it only if an object in some view
actually contains the latest generation; see the Make_Controlled
command.)
If Ada units are compiled against a unit that requires updating,
checking out that unit may require the demotion of the other
dependent units. In this case, the value of the Allow_Demotion
parameter controls whether the command actually performs the
demotion and checks out the unit.
Various commands can be used to determine whether objects are
currently checked out, including Show, Show_All_Checked_Out, Show-
_Checked_Out_In_View, and Show_Checked_Out_By_User. Other related
information, such as the checkout date, time, and user, can be
displayed using the Show_History_By_Generation command.
The reservation obtained by the Check_Out procedure can be
abandoned using the Abandon_Reservation command.
@node !Commands.Cmvc.Copy
procedure Copy
(From_View : String := "<CURSOR>";
New_Working_View : String := ">>SUB/PATH NAME<<";
View_To_Modify : String := "";
View_To_Import : String := "<INHERIT_IMPORTS>";
Only_Change_Imports : Boolean := True;
Join_Views : Boolean := True;
Reservation_Token_Name : String := "<AUTO_GENERATE>";
Construct_Subpath_Name : Boolean := False;
Create_Spec_View : Boolean := False;
Create_Load_View : Boolean := False;
Create_Combined_View : Boolean := False;
Level_For_Spec_View : Natural := 0;
Model : String := "<INHERIT_MODEL>";
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Creates one or more new views by copying the specified view or
views.
By default, the Copy command makes new spec views, new working
load views, or new working combined views, depending on the kinds
of source views named by the From_View parameter. This procedure
also can be used to make views of a specific type, depending on
the values of the Create_Spec_View, Create_Load_View, and Create-
_Combined_View parameters. (At most, only one of these three
parameters can be true.)
The Copy command can be used to make new paths, subpaths, and spec
views, although specialized commands (Make_Path, Make_Subpath,
and Make_Spec_View) exist for this purpose. (Note that all of the
special-purpose commands call the Copy command.)
Objects in new working load or combined views are made controlled
if the corresponding objects were controlled in the source views.
Objects in new spec views are left uncontrolled.
Controlled objects in a new view can, but need not, be joined to
the corresponding objects in the view from which it is copied.
Two views should be joined (using the Join_Views parameter) if
the majority of the controlled objects in them are to be joined.
(Joined objects cannot be checked out and modified independently.)
The controlled objects that need to be modified independently can
be severed subsequently with the Sever command.
A new view should not be joined to the view from which it is
created if most of the controlled objects in these two paths are
to be modified independently. (Note that changes can be propagated
across unjoined objects with the Merge_Changes command.) Although
the new path is not created joined, individual objects in it
subsequently can be joined to the corresponding objects in other
views (see the Join command).
By default, each new view has the same imports as the view from
which it was copied. It is also possible to specify different
imports in the process of creating the new paths by using the View-
_To_Import and Only_Change_Imports parameters. Import adjustments
are subject to the same consistency checking that is performed by
the Import command.
@node !Commands.Cmvc.Create_Empty_Note_Window
procedure Create_Empty_Note_Window (What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
Creates an empty window for the purpose of composing notes for the
specified controlled object. The banner of the created window
identifies it as Notes For followed by the object's name.
The notes for a controlled object are stored the CMVC database. An
object's notes can be used as a scratchpad for arbitrary commentary
to be associated with particular generations.
After the notes window has been edited:
o The Append_Notes command can be used to append the window's
contents to the object's existing notes.
o The Put_Notes command can be used to replace the object's
existing notes with the window's contents.
Modified notes windows retain the * symbol in their window banners,
even after their contents have been entered in the CMVC database
using Append_Notes or Put_Notes. Accordingly, the Quit command
reports these windows as changed images when logout is attempted.
Because these windows cannot be committed, use Common.Abandon to
remove these windows.
The Notes command provides an interactive alternative to
Append_Notes, Create_Empty_Note_Window, and the like. The Notes
command displays a history image (identified by the 'History
attribute following the object name and generation in the window
banner), which allows interactive operations for managing an
object's notes.
@node !Commands.Cmvc.Def
procedure Def (What_Object : String := "<CURSOR>";
In_Place : Boolean := False);
Traverses between various objects managed by the Environment
library system and images managed by the CMVC editor.
In some contexts, the Def command serves as the inverse of the Edit
command:
o Entering Edit from a view or from a controlled object in the view
displays the configuration image for that view.
o Entering Def from the configuration image for a view displays the
view itself or a controlled object in the view (depending on the
location of the cursor within the configuration image).
In other contexts, the Def command serves as the inverse of the
Notes command:
o Entering Notes from a controlled object in a view displays the
history image for the object.
o Entering Def from the history image for a controlled object
displays the object itself.
Finally, Def traverses back and forth between a controlled object
in a view and its current generation image. If images of other
generations are displayed subsequently, Def also displays the
controlled object from any of these other generation images.
A particularly useful application of Def is to use it to display
an object's current generation image and then use Common.Expand to
see the differences between the current generation and the previous
generation.
@node !Commands.Cmvc.Destroy_Subsystem
procedure Destroy_Subsystem (What_Subsystem : String := "<SELECTION>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Destroys the specified subsystem or subsystems.
All views in each subsystem must be destroyed (with the
Destroy_View command) before that subsystem can be destroyed.
@node !Commands.Cmvc.Destroy_System
procedure Destroy_System (What_System : String := "<SELECTION>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Destroys the specified system or systems.
All views in each system must be destroyed (with the Destroy_View
command) before the subsystem can be destroyed.
@node !Commands.Cmvc.Destroy_View
procedure Destroy_View
(What_View : String := "<SELECTION>";
Demote_Clients : Boolean := False;
Destroy_Configuration_Also : Boolean := False;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Destroys the named view or views and all of their subdirectory
structure, including the Ada units in the Units directories.
This procedure destroys views in subsystems and in systems.
All objects are first unfrozen if they are currently frozen, and
then they are deleted and expunged from the directory system. A
view cannot be destroyed in any of the following cases:
o The view contains controlled objects that currently are checked
out.
o The view is currently imported by client views.
o The view is included in a system as a result of operations in the
Cmvc_Hierarchy package.
Destroy_View is the only command that should be used to destroy
a view. In particular, neither the Library.Destroy nor the
Compilation.Destroy command should be used, because these commands
cannot destroy the entire view structure. If an attempt was made
to destroy a view using any command other than Destroy_View, you
can recover as follows:
1. Enter the Cmvc_Maintenance.Check_Consistency command to repair
the partially destroyed view.
2. Enter the Destroy_View command to destroy the view completely.
By default, views are destroyed so that they can be rebuilt using
the Build command. Views can be destroyed permanently by setting
the Destroy_Configuration_Also parameter to true.
@node !Commands.Cmvc.Edit
procedure Edit (View_Or_Config : String := "<CURSOR>";
In_Place : Boolean := False;
Allow_Check_Out : Boolean := True;
Allow_Check_In : Boolean := True;
Allow_Accept_Changes : Boolean := True);
Displays a configuration image for the specified view or
configuration object or for the view enclosing the specified
object.
A configuration image for a view is a library-like display of CMVC
information pertaining to that view.
Every view embodies a specific configuration, where a
configuration is a combination of generations, one for each
controlled object in the view. A configuration image for a view
thus contains an entry for each controlled object in the view,
indicating the generation of the object that is present in the
configuration embodied by the view. Each entry also indicates the
latest generation that exists for that object in any view.
A configuration image for a view provides a convenient way to:
o Check in, check out, and accept changes on controlled objects.
o Determine whether an object is checked out, to whom it is checked
out, whether it is out of date in a given view, and which other
views contain objects in the same join set. (The Common.Expand
command displays increasing levels of information from this
image.)
o Access generation images (textual representations of previous
generations) and history images (the notes stored in the
CMVC database for each controlled object). Note that a given
generation image can be expanded to show differences between that
generation and the previous one. Generation images are available
only for controlled objects for which source is saved.
Note that Edit can be used to display a configuration image for
a configuration object that has no view associated with it (for
example, a configuration release). In this case, the configuration
image provides access to generation images and history images even
for objects that may not still exist outside the CMVC database.
This is a useful means for browsing past generations of objects.
Similarly, the Edit command can be used to display configuration
images for code views, which do not contain source objects.
The Def command traverses from a configuration image for a view to
the view itself (or to an object in that view).
By default, commands from package Common can be used to
perform checkin, checkout, and accept-changes operations in a
configuration image that was created by the Edit command. To
restrict such operations, set the Allow_Check_Out, Allow_Check_In,
and Allow_Accept_Changes parameters to false when you enter the
Edit command.
As an alternative to using the Edit command, configuration images
can be created using commands from package Common. In this case,
checkin, checkout, and accept-changes operations are restricted
automatically. However, the Edit command can be entered from the
configuration image to change these restrictions as specified by
the Allow_Check_Out, Allow_Check_In, and Allow_Accept_Changes
parameters.
@node !Commands.Cmvc.Get_Notes
procedure Get_Notes (To_File : String := "<WINDOW>";
What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
Retrieves the notes for the current generation of the specified
controlled object.
The Get_Notes command retrieves an object's notes from the CMVC
database and displays them in a special-purpose window or writes
them into a file. An object's notes can be used as a scratchpad
for arbitrary commentary to be associated with particular
generations.
Get_Notes is one of a set of file-oriented commands for
managing notes. That is, these commands, including Put_Notes,
Create_Empty_Note_Window, and Append_Notes, are most useful
for managing notes through files. However, these commands also
manage special-purpose notes windows, which are identified in the
banner by the string Notes For followed by the object's name. The
contents of the window can be edited; however, the edited text in
the window can be saved into the CMVC database only as follows:
o The Append_Notes command can be used to append the window's
contents to the object's existing notes.
o The Put_Notes command can be used to replace the object's
existing notes with the window's contents.
Note that modified notes windows retain the * symbol in their
window banners even after their contents have been entered in the
CMVC database using Append_Notes or Put_Notes. Accordingly, the
Quit command reports these windows as changed images when logout
is attempted. Because these windows cannot be committed, use
Common.Abandon to remove these windows.
The Notes command provides an interactive alternative to
Get_Notes, Put_Notes, and the like. The Notes command displays
a history image (identified by the 'History attribute following
the object name and generation in the window banner), which allows
interactive operations for managing an object's notes.
@node !Commands.Cmvc.Import
procedure Import
(View_To_Import : String := "<REGION>";
Into_View : String := "<CURSOR>";
Only_Change_Imports : Boolean := False;
Import_Closure : Boolean := False;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Imports the specified spec or combined views into the designated
view(s).
Some or all of the views specified by the View_To_Import parameter
are imported by a given view, depending on the value of the Only-
_Change_Imports parameter.
The Import command can be used to:
o Add new imports
o Change an existing import by importing a different view from the
same subsystem
o Refresh a view's existing imports after new specifications have
been added to the imported views
Consistency checking is done to ensure that no view directly or
indirectly imports more than one view from the same subsystem. The
import operation checks the closure of the importing view and the
closures of all views that import it. An error results if any new
or changed import would cause an inconsistency.
Furthermore, within spec/load subsystems, circularity checking
is done to ensure that no view directly or indirectly imports
itself. (Circular importing is permitted among views in combined
subsystems, however.)
An import operation succeeds only if the target key of the
importing (client) view is compatible with the target key of the
imported (supplier) view. For example, a view with target key
R1000 cannot import a view with target key Mc68020_Bare.
Importing operations create and manage links among subsystems.
When one view imports another, links are created in the client view
to each of the units in the supplier view. Imports alone enable
links to be managed across paths, subpaths, and releases; links
should never be added individually through commands from package
Links.
An import operation will create links to a subset of the units in
a supplier view if export and import restrictions exist. Users
create export and import restrictions as text files in the supplier
and client views, respectively.
An export restriction file is a text file in the Exports
subdirectory within the supplier view. An export restriction file
defines a subset of the units in the supplier view either through
a list of unit names (one per line) or through naming expressions.
Names in an export restriction file are resolved against the Units
directory within the view. The Exports subdirectory can contain
multiple export restriction files that define alternative subsets
of the view.
An import restriction file is a text file in the Imports
subdirectory within the client view. A given import restriction
file determines which subset to use from a particular supplier
view. A client view may have multiple import restriction files,
one for each of its supplier views. The following rules pertain to
the creation of an import restriction file that corresponds to a
particular supplier view:
o The import restriction file must have the same name as the
subsystem containing the supplier view. Typically the
subsystem's simple name is used; however, a fully qualified
subsystem name can be converted to a filename by omitting
the preceding ! and changing the dots (.) between name
components to underscores (_). For example, an import
restriction file for a supplier view in the subsystem
!Programs.Mail.Mail_Utilities can be named either Mail_Utilities
or Programs_Mail_Mail_Utilities.
o The first line of the file must consist of the string
export_restriction=> followed by the simple name of the desired
export restriction file from the supplier view. No blanks should
appear in this line. Omitting this line implicitly specifies
an export restriction file named Default, if such a file exists;
otherwise, the entire supplier view is used.
o Subsequent lines in the import restriction file can contain
names or naming expressions to specify a further subset of the
units listed in the export restriction file. Links are created
in the client view for the units that are matched by the naming
expressions. If no naming expressions are specified, no links
are created.
Because an import restriction file essentially specifies a set
of link names, only simple Ada names should be used in the naming
expressions. This is true even for names that are qualified
within the export restriction file. Whereas names in an export
restriction file are resolved as library names, names in an
import restriction file are resolved as link names.
Naming expressions can be used to:
---Request links for all units in the export restriction file by
entering @
---Request links for subsets by using wildcard expressions such
as @_pkg
---Exclude links to units by using expressions such as ~Unit_Name
(which should follow an expression such as @)
---Rename links to units by specifying the unit name followed by
the new link name
@node !Commands.Cmvc.Imported_Views
function Imported_Views (Of_View : String := "<CURSOR>";
Include_Import_Closure : Boolean := False;
Include_Importer : Boolean := False;
Response : String := "<WARN>")
return String;
Returns a string that names all the views that are imported by the
specified view.
@node !Commands.Cmvc.Information
procedure Information (For_View : String := "<CURSOR>";
Show_Model : Boolean := True;
Show_Whether_Frozen : Boolean := True;
Show_View_Kind : Boolean := True;
Show_Creation_Time : Boolean := True;
Show_Imports : Boolean := True;
Show_Referencers : Boolean := True;
Show_Unit_Summary : Boolean := True;
Show_Controlled_Objects : Boolean := False;
Show_Last_Release_Numbers : Boolean := False;
Show_Path_Name : Boolean := False;
Show_Subpath_Name : Boolean := False;
Show_Switches : Boolean := False;
Show_Exported_Units : Boolean := False;
Response : String := "<PROFILE>");
Displays various kinds of information about the specified view in
the output window.
Each parameter specifies whether to display a particular kind of
information.
@node !Commands.Cmvc.Initial
procedure Initial
(System_Object : String := ">>SYSTEM OBJECT NAME<<";
Working_View_Base_Name : String := "Rev1";
System_Object_Type : System_Object_Enum := Cmvc.Spec_Load_Subsystem;
View_To_Import : String := "";
Create_Load_View : Boolean := True;
Model : String := "R1000";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Builds a new system or a new subsystem of the specified type---
namely, spec/load or combined.
Subsystems partition a project or application into high-level
components by grouping Ada units or other objects. A system
pulls an application's components together by logically grouping
particular releases from the component subsystems. Operations for
systems are in package Cmvc_Hierarchy.
The new subsystem or system contains an empty working view that
has the specified imports. The Initial command also can be used to
create an empty view in an existing subsystem or system.
The initial view is set up according to the specified model. This
includes the setting of the switches and initial links for the
view. The model also may contain a file named Levels whose integer
contents specify the number of levels for automatic name generation
for released and spec views. Furthermore, the model may contain
user-defined directory structure to be created in the view in
addition to the predefined directories.
The name of the initial view of the subsystem or system is:
[System_Object].[Working_View_Base_Name]_Working
@node !Commands.Cmvc.Join
procedure Join (What_Object : String := "<SELECTION>";
To_Which_View : String := ">>VIEW NAME<<";
Reservation_Token_Name : String := "";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Joins the specified controlled objects to the corresponding
objects in the designated view.
When objects are joined across views, they form a join set.
Objects in a join set have the same pathname within their
respective views and share a single reservation token, so that
only one object in the set can be checked out at a time. Thus,
joining allows synchronized changes to an object when there are
instances of the same object in multiple working views.
The objects to be joined must be textually identical. The Merge-
_Changes command can be used to prepare objects for joining.
There are two alternative ways to specify the join set to which
objects are to be joined. One is to specify a view that contains
an object in the desired join set. The other is to specify the
reservation token associated with the desired join set. (See the
To_Which_View and Reservation_Token_Name parameters, below.)
@node !Commands.Cmvc.Make_Code_View
procedure Make_Code_View (From_View : String := "<CURSOR>";
Code_View_Name : String := "";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Makes a code view from the specified load view.
Code views are copies of views that store executable code in place
of Ada units. Code views thus require the minimum amount of space
necessary to permit execution of the view. The executable code is
stored in an object called Code_Database within the view.
The Units directory of a code view contains a copy of any non-Ada
objects from the original view.
Because Ada units in code views are stored as executable code,
these units cannot be modified or browsed except through
configuration and generation images (see the Cmvc.Edit command).
@node !Commands.Cmvc.Make_Controlled
procedure Make_Controlled
(What_Object : String := "<CURSOR>";
Reservation_Token_Name : String := "<AUTO_GENERATE>";
Join_With_View : String := "<NONE>";
Save_Source : Boolean := True;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Makes the specified object or objects controlled by the CMVC system
and therefore subject to reservation.
Once controlled, an object must be checked out before it can be
modified and it must be checked in before various commands can
access it.
When an object is controlled with the Save_Source parameter set
to true, the textual changes from one generation to the next are
stored in the CMVC database. This permits the reconstruction of
previous generations through, for example, the Revert command or by
rebuilding a view from a configuration object. (Note that because
changed lines are determined textually, changing an Ada unit's
pretty-printing causes all lines to be stored as changed lines.)
When an object is controlled with the Save_Source parameter set to
false, no textual representation is stored in the CMVC database.
This is useful for binary objects that have no ASCII representation
or for very large files (when storage space is an issue). Even
though previous generations cannot be reconstructed when objects
are controlled without saving source, such objects still need to be
checked out before they can be modified. (Generation numbers thus
record the number of times objects were checked out and checked
in.)
Controlling an object associates a reservation token with it.
The Check_In and Check_Out procedures operate by manipulating
reservation tokens, and joined objects share not only the same name
but also a single reservation token.
@node !Commands.Cmvc.Make_Path
procedure Make_Path
(From_Path : String := "<CURSOR>";
New_Path_Name : String := ">>PATH NAME<<";
View_To_Modify : String := "";
View_To_Import : String := "<INHERIT_IMPORTS>";
Only_Change_Imports : Boolean := True;
Create_Load_View : Boolean := False;
Create_Combined_View : Boolean := False;
Model : String := "<INHERIT_MODEL>";
Join_Paths : Boolean := True;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Creates a copy of each of the specified views, starting new
development paths.
A path is a logically connected series of views within a subsystem
or a system. For each view specified, the Make_Path command
creates a new working view that serves as the start of such a
series of views.
A subsystem or a system can contain multiple paths. For example,
if an application has multiple targets, a path can be made for each
target. Similarly, if a new major release of an application must
be developed while the existing release is maintained, a separate
path can be made for the new major release.
A new path can, but need not, be joined to the view (and hence to
the path) from which it is created. Two paths should be joined
(using the Join_Paths parameter) if the majority of the controlled
objects in them are to be joined. (Joined objects cannot be
checked out and modified independently.) The controlled objects
that need to be modified independently can be severed subsequently
with the Sever command. For example, if an application has two
targets, the target-independent code is shared and the target-
dependent code is not. Assuming that a path already exists for one
of the targets, a joined path can be created for the second target
and then the target-dependent units can be severed.
A new path should not be joined to the path from which it is
created if most of the controlled objects in these two paths are
to be modified independently. For example, if a new major release
of an application is developed while the previous major release
is maintained, the objects in the two paths typically need to
be modified independently, so the paths are not joined. (Note
that changes can be propagated across unjoined objects with the
Merge_Changes command.) Although the new path is not joined when
created, individual objects in it subsequently can be joined to the
corresponding objects in other views (see the Join command).
By default, the working view for each new path has the same imports
as the view from which it was copied. It is also possible to
specify different imports in the process of creating the new paths
by using the View_To_Import and Only_Change_Imports parameters.
Import adjustments are subject to the same consistency checking
that is performed by the Import command.
@node !Commands.Cmvc.Make_Spec_View
procedure Make_Spec_View
(From_Path : String := "<CURSOR>";
Spec_View_Prefix : String := ">>PREFIX<<";
Level : Natural := 0;
View_To_Modify : String := "";
View_To_Import : String := "<INHERIT_IMPORTS>";
Only_Change_Imports : Boolean := True;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Creates a new spec view from each of the specified views in a
spec/load subsystem.
Each new spec view is created with only those units named in the
Exports file of the corresponding source view. (This file is
located in the view_name.State directory.) The new spec view
contains a copy of the specifications of those units. If no units
are specified in the Exports file, the new spec view copies the
specifications of all of the units in the source view. Units in
each new spec view are compiled according to the Remake_Demoted-
_Units and Goal parameters.
By default, units in spec views are not made controlled. If these
units are subsequently made controlled for purposes of history
tracking, they should not be joined to their counterparts in
working views.
Portions of each new spec view's name are automatically generated
unless the Spec_View_Prefix and Level parameters specify
otherwise. An automatically generated spec-view name consists
of a spec-view prefix, one or more level numbers that correlate
with a particular numbered release, and the _Spec suffix---for
example, Rev1_1_Spec.
By default, each spec view has the same imports as the view from
which it was copied. It is also possible to specify different
imports in the process of creating the spec views by using the
View_To_Import and Only_Change_Imports parameters. Import
adjustments are subject to the same consistency checking that
is performed by the Import command.
@node !Commands.Cmvc.Make_Subpath
procedure Make_Subpath
(From_Path : String := "<CURSOR>";
New_Subpath_Extension : String := ">>SUBPATH<<";
View_To_Modify : String := "";
View_To_Import : String := "<INHERIT_IMPORTS>";
Only_Change_Imports : Boolean := True;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Creates a copy of each of the specified views in order to start new
development subpaths.
A subpath is a series of working views that constitutes an
extension of a path. Multiple subpaths in a single path support
parallel development within that path, allowing multiple
developers to make and test changes without conflict. Parallel
development can proceed because the controlled objects in each
subpath are automatically joined to the corresponding objects in
the other subpaths and in the parent path. A controlled object
therefore can be checked out and modified in only one subpath view
at a time.
Subpaths share the same model as their parent path, which means
that they share the same target key and initial links.
By default, the working view for each new subpath has the same
imports as the view from which it was copied. It is also possible
to specify different imports in the process of creating the new
subpaths by using the View_To_Import and Only_Change_Imports
parameters. Import adjustments are subject to the same consistency
checking that is performed by the Import command.
Subpaths can be created in systems as well as subsystems.
@node !Commands.Cmvc.Make_Uncontrolled
procedure Make_Uncontrolled (What_Object : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Makes the specified objects uncontrolled, so that change
information about them is no longer collected in the CMVC database.
Existing history for these objects remains in the CMVC database
until the database is expunged using the Cmvc_Maintenance.Expunge-
_Database command. Objects can be made controlled again using
the Make_Controlled command; if the CMVC database has not been
expunged, the history for the recontrolled objects continues where
it stopped.
Because controlled objects cannot be deleted or withdrawn, the
Make_Uncontrolled procedure is used to prepare a controlled object
for deletion. Similarly, an Ada unit's kind cannot be changed (for
example, from procedure to function) while the unit is controlled.
Therefore, the unit must be made uncontrolled and then the database
must be expunged (using Cmvc_Maintenance.Expunge_Database) before
the unit's kind can be changed.
@node !Commands.Cmvc.Merge_Changes
procedure Merge_Changes
(Destination_Object : String := "<SELECTION>";
Source_View : String := ">>VIEW_NAME<<";
Report_File : String := "";
Fail_If_Conflicts_Found : Boolean := False;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Merges two objects that previously were joined and then severed
from each other.
The object named by the Destination_Object parameter is updated
to include any changes that have been made to the corresponding
object located in the view named by the Source_View parameter. The
updated destination object is left in the source state; the source
object is left unchanged.
The Merge_Changes procedure can succeed only if the views named
by the Source_View and Destination_Object parameters were created
from a common view (for example, by commands such as Make_Path).
The configuration object for the common view must still exist.
Merge_Changes uses the common ancestor of the two objects to
determine the changes from the source object that need to be merged
into the destination object.
Merge_Changes compares both the destination object and the source
object with the common ancestor to determine the lines that need
to be merged. Lines that have been added, deleted, or changed in
the source object are correspondingly added, deleted, or changed
in the destination object. Lines that have been added, deleted, or
changed in the destination object are left as is.
Conflicts exist when the same lines have been changed in both
the source and destination objects. When conflicts exist, the
destination object is updated to contain the changed lines from
both the destination and the source objects. These changed lines
are marked with the string "*;". When a unit contains lines
marked with "*;", the unit must be edited to remove these marks
before it can be compiled.
Besides updating the destination object, the Merge_Changes
procedure writes a report containing the text of the Destination-
_Object in which the following conventions indicate the lines that
were affected by the merge:
o Added lines are marked by the + character.
o Deleted lines are redisplayed, marked with the - character.
o Each changed line is indicated as a deleted line followed by an
added line.
o Conflicting lines are bracketed by *** START CONFLICT and *** END
CONFLICT.
Following the + or - symbol is a number or letter indicating the
origin of the modified line:
o The number 1 indicates changes that were merged from the source
object.
o The number 2 indicates changes that existed in the destination
object.
o The letter B indicates changes that were made in both the source
and the destination objects.
The Fail_If_Conflicts_Found parameter can be set to true to cause
the command to produce the merge report without actually updating
the destination object.
The Merge_Changes procedure is used for updating objects that are
not joined---for example, objects in unjoined paths or severed
objects in joined paths. In contrast, the Accept_Changes command
is used for updating objects that are joined.
Merge_Changes can be used to prepare two objects for joining since
objects must be textually identical before they can be joined. To
prepare two objects for joining:
1. Merge the source object into the destination object.
2. Check out and edit the destination object to resolve any
conflicts.
3. Check out the source object and copy the contents of the
destination object into it.
@node !Commands.Cmvc.Notes
procedure Notes (What_Object : String := "<CURSOR>";
In_Place : Boolean := False);
Displays the history image for the current generation of the
specified controlled object.
A history image for a generation contains:
o The history for the generation, which lists the time of checkout
and checkin, the user who performed these operations, and
comments provided to various CMVC commands
o The notes for the generation, which can be used as a scratchpad
for arbitrary commentary to be associated with that generation
History images provide an interactive way to manage notes.
From a history image, new notes can be added and saved using
the Common.Edit and Common.Commit or Common.Promote commands.
Furthermore, operations are available in a history image for
displaying notes from other generations.
The Notes procedure thus provides an interactive alternative to the
set of file-oriented commands (Get_Notes, Create_Empty_Note_Win-
dow, Append_Notes, and Put_Notes). These file-oriented commands
are most useful for retrieving notes directly into files, although
these commands can put notes into special-purpose notes windows.
The window banner for a history image contains the object name
followed by a generation attribute (for example 'G(3)), followed by
the attribute 'History. Furthermore, the window banner contains
the string (cmvc). In contrast, the banner of a notes window
brought up by the Get_Notes or Create_Empty_Note_Window procedures
contains the string Notes for followed by the object name. No
interactive operations are available from a Notes for window.
@node !Commands.Cmvc.Put_Notes
procedure Put_Notes (From_File : String := "<WINDOW>";
What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
Replaces the notes for the specified controlled object with the
contents of the specified file.
The notes for a controlled object are stored the CMVC database. An
object's notes can be used as a scratchpad for arbitrary commentary
to be associated with particular generations.
Put_Notes is one of a set of file-oriented commands for
managing notes. That is, these commands, including Get_Notes,
Create_Empty_Note_Window, and Append_Notes, are most useful
for managing notes through files. However, these commands also
manage special-purpose notes windows (identified by the Notes for
string in the banner) in which the Put_Notes command can be used as
follows:
o If the Get_Notes procedure has been used to display an object's
notes in a notes window, this window can be modified and its
contents saved using the Put_Notes procedure. In this case,
Put_Notes must be entered (with default parameter values) from
a Command window attached to the window that was created by Get-
_Notes.
o If the Create_Empty_Note_Window procedure has been used to
display an empty notes window for an object, Put_Notes can be
used to replace the object's existing notes with any text entered
in this window. In this case, Put_Notes must be entered (with
default parameter values) from a Command window attached to the
window that was created by the Create_Empty_Note_Window command.
Note that modified notes windows retain the * symbol in their
window banners, even after their contents have been entered in the
CMVC database using Append_Notes or Put_Notes. Accordingly, the
Quit command reports these windows as changed images when logout
is attempted. Because these windows cannot be committed, use the
Common.Abandon procedure to remove these windows.
The Notes command provides an interactive alternative to
Get_Notes, Put_Notes, and the like. The Notes command displays
a history image (identified by 'History attribute following the
object name and generation in the window banner), which allows
interactive operations for managing an object's notes.
@node !Commands.Cmvc.Release
procedure Release
(From_Working_View : String := "<CURSOR>";
Release_Name : String := "<AUTO_GENERATE>";
Level : Natural := 0;
Views_To_Import : String := "<INHERIT_IMPORTS>";
Create_Configuration_Only : Boolean := False;
Compile_The_View : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Volume : Natural := 0;
Response : String := "<PROFILE>");
Creates a new released view from each of the specified working
views. Releases can be made in subsystems and in systems.
A released view is a frozen copy of the working view and can serve
as a baseline for testing and execution.
In addition to creating a new released view, the Re-
lease command creates two objects in the directory
(sub)system_name.Configurations. These objects are:
o A configuration object named release_name.
o A state description directory named release_name_State. This
directory contains several files that store switch values, the
names of exported and imported views, the model name, and the
like.
If the newly created view is subsequently destroyed to save space,
it can be reconstructed from these objects.
If saving space is important, the Release command can be used to
create only the configuration object and the state description
directory for each specified working view. Full released views
can be created subsequently from the configuration object using
the Build command. (Note, however, that a configuration object
references only the controlled objects in a view; therefore,
only the controlled objects can be created by the Build command.)
Creating only a configuration is much faster than making a view.
When a released view is created, the controlled objects in it are
automatically joined to the corresponding objects in the working
view and in the previously released views in the same development
path.
@node !Commands.Cmvc.Remove_Import
procedure Remove_Import (View : String := ">>VIEW NAME<<";
From_View : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Removes the links that were created when the view specified by the
View parameter was imported.
This command does not remove an import if there are units compiled
against any of the links it created. However, such an import can
be removed if the units are demoted to the source state.
@node !Commands.Cmvc.Remove_Unused_Imports
procedure Remove_Unused_Imports (From_View : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Removes imports from the specified view or views if none of the
links created by those imports are needed for compilation.
Links are removed only on an import-by-import basis. Thus, if any
of the links from a given import are needed for compilation, then
none of the links created by that import are removed.
A link is needed for compilation if it is referenced in a with
clause in at least one unit that is in the source, installed,
or coded state (archived units are ignored). Compare this with
the Remove_Import command, which is sensitive only to units that
actually are compiled against the link.
@node !Commands.Cmvc.Replace_Model
procedure Replace_Model (New_Model : String := ">>NEW MODEL NAME<<";
In_View : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Replaces the model world for the specified view.
A view's model can be changed to:
o Invoke a new switches file for the view.
o Rebuild the view's links.
o Reset the number of levels for automatic name generation for
released and spec views. (This affects only future releases.)
o Change the view's target key. However, the change must be to a
target key that is compatible with the current target key. For
example, a view with target key R1000 cannot change to a model
with target key Mc68020_Bare.
@node !Commands.Cmvc.Revert
procedure Revert
(What_Object : String := "<SELECTION>";
To_Generation : Integer := -1;
Make_Latest_Generation : Boolean := False;
Allow_Demotion : Boolean := False;
Remake_Demoted_Units : Boolean := True;
Goal : Compilation.Unit_State := Compilation.Coded;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Reverts the specified object or objects to the specified
generation.
This procedure replaces the contents of each object with the
contents of the indicated generation of that object.
The generation to which an object is reverted can be retained as
the latest generation if the Make_Latest_Generation parameter is
true. Otherwise, the reverted object is updated to the latest
generation the next time the object is checked out.
@node !Commands.Cmvc.Sever
procedure Sever (What_Objects : String := "<SELECTION>";
New_Reservation_Token_Name : String := "<AUTO_GENERATE>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Severs the specified objects from their respective join sets.
When an object is severed, it is given a different reservation
token, so that it can be checked out and modified independent of
the objects to which it had previously been joined.
@node !Commands.Cmvc.Show
procedure Show (Objects : String := "<CURSOR>";
Response : String := "<PROFILE>");
Displays checkout and generation information for the specified
controlled objects.
In addition, this procedure lists the views containing objects that
are joined to each specified object.
The display produced by the Show procedure includes the following
fields:
Object Name Generation Where Chkd Out By Whom Expected Check In
============== ========== ============ ======== ======= =================
UNITS.CMVC_TEX 3 of 3 REV1_WORKING Yes SJL June 15, 1988
For each object listed, the fields display the following
information:
Object Name Displays the portion of the object's name that
follows the view name.
Generation Lists a pair of numbers. The first number is the
generation of the object in the current view. The
second number is the number of generations that
exist for that object.
Where Displays a view name. If the object is currently
checked out, this field names the view in which
it is checked out. If the object is currently
checked in, it names the view that contains the
most recent generation.
Chkd Out Indicates whether the object is currently checked
out. If "Yes," the following two fields provide
more information.
By Whom Displays the username of the user who checked out
the object.
Expected Check InDisplays the value that was supplied for the
Expected_Check_In_Time parameter of the Check_Out
command.
The Show command also displays the names of the views to which the
specified objects are joined.
@node !Commands.Cmvc.Show_All_Checked_Out
procedure Show_All_Checked_Out (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
Displays a list of the objects in the specified view that are
checked out.
The objects are listed in the same format used by the Show command.
@node !Commands.Cmvc.Show_All_Controlled
procedure Show_All_Controlled (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
Lists the controlled objects in the specified view or views.
The objects are listed in the same format used by the Show command.
@node !Commands.Cmvc.Show_All_Uncontrolled
procedure Show_All_Uncontrolled (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
Lists all uncontrolled objects in the specified views.
@node !Commands.Cmvc.Show_Checked_Out_By_User
procedure Show_Checked_Out_By_User
(In_View : String := "<CURSOR>";
Who : String := System_Utilities.User_Name;
Response : String := "<PROFILE>");
Lists the objects in the specified view(s) that are checked out by
the specified user.
The objects are listed in the same format used by the Show command.
Objects are listed even if they are controlled in the specified
view but checked out in another view.
@node !Commands.Cmvc.Show_Checked_Out_In_View
procedure Show_Checked_Out_In_View (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
Lists the objects that are checked out in the specified view or
views, regardless of who checked them out.
The objects are listed in the same format used by the Show command.
@node !Commands.Cmvc.Show_History
procedure Show_History (For_Objects : String := "<CURSOR>";
Display_Change_Regions : Boolean := True;
Starting_Generation : String := "<CURSOR>";
Ending_Generation : String := "";
Response : String := "<PROFILE>");
Displays the history for the specified view or object within a
view.
This procedure shows what has changed between two configurations
(or two views) on the same path. For example, the Show_History
command can be used to display the differences between two released
views, between a working view and a previously released view, and
the like. It also can be used to display how a particular object
has changed from one view or configuration to another.
The Show_History procedure provides the following information for
each specified object (if a view is specified, this information is
shown for each controlled object in the view):
o The join set name (the name of the reservation token for the
joined objects)
o The object's history for the generations that were created
between the configurations specified by the Starting_Generation
and Ending_Generation parameters
For each of the requested generations of an object, the history
includes:
o The time and date of the checkout and checkin that created the
generation
o The notes for the object
o The changes that occurred since the previous generation (if
requested by the Display_Change_Regions parameter)
@node !Commands.Cmvc.Show_History_By_Generation
procedure Show_History_By_Generation
(For_Objects : String := "<CURSOR>";
Display_Change_Regions : Boolean := True;
Starting_Generation : Natural := 1
Ending_Generation : Natural := Natural'Last;
Response : String := "<PROFILE>");
Displays the history for one or more controlled objects across the
specified range of generations.
This procedure uses generation numbers to delimit the extent of the
displayed history, whereas the Show_History procedure uses views
or configurations to delimit the display.
The Show_History_By_Generation procedure provides the following
information for each specified object (if a view is specified, this
information is shown for each controlled object in the view):
o The join set name (the name of the reservation token for the
joined objects)
o The object's history for the generations that were created
between the configurations specified by the Starting_Generation
and Ending_Generation parameters
For each of the requested generations of an object, the history
includes:
o The time and date of the checkout and checkin that created the
generation
o The notes for the object
o The changes that occurred since the previous generation (if
requested by the Display_Change_Regions parameter)
@node !Commands.Cmvc.Show_Image_Of_Generation
procedure Show_Image_Of_Generation
(Object : String := "<CURSOR>";
Generation : Integer := -1;
Output_Goes_To : String := "<WINDOW>";
Response : String := "<PROFILE>");
Reconstructs an image of the specified generation of the designated
controlled object.
Successive generations of a controlled object are stored in the
CMVC database as a series of changed increments. This command
reconstructs a textual image of the specified generation. The
reconstructed image is displayed in the output log, unless the
Output_Goes_To parameter specifies a file.
Show_Image_Of_Generation is a report-oriented command that is most
useful for putting the image of a single generation into a file.
As an alternative, the Edit and Def procedures can be used to bring
up generation images from which interactive operations can be
used to display images of other generations and of the differences
between successive generations.
@node !Commands.Cmvc.Show_Out_Of_Date_Objects
procedure Show_Out_Of_Date_Objects (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
Lists the objects in the specified view or views that are not at
the most recent generation.
The objects are listed in the same format used by the Show command.
@node !Commands.Cmvc.System_Object_Enum
type System_Object_Enum is (Spec_Load_Subsystem, Combined_Subsystem,
System);
Defines the types of system objects that can be created, where a
system object is either a system or a subsystem.
There are two types of subsystems. A subsystem's type determines
what kind of views the subsystem can contain---for example,
spec/load views or combined views.
A subsystem's type also determines whether hierarchic importing is
enforced.
Combined_Subsystem
Defines a type of subsystem that can contain only combined views.
Within a Combined subsystem, circular import relations may hold---
that is, a view is permitted to be in its own import closure.
Spec_Load_Subsystem
Defines a type of subsystem that can contain spec, load, or
combined views. Within a Spec_Load subsystem, all imports must
be hierarchic---that is, no view is permitted to be in its own
import closure.
System
Defines a system, which is an optional device for creating logical
groupings of releases from component subsystems in an application.
Operations for systems are in package Cmvc_Hierarchy.
@node !Commands.Cmvc_Hierarchy
When an application consists of multiple subsystems, these
subsystems optionally can be included in an Environment object
called a system. Inclusion in a system is a way of identifying
particular subsystems as components of a given application or
of a major portion of an application. Inclusion in a system
also provides an automated means of tracking the latest release
from each subsystem and building activities that reference those
releases.
A subsystem is included in a system by establishing a parent-child
relationship between the system and the subsystem. Therefore, a
system does not actually contain its component subsystems in the
same way that a subsystem view contains component objects.
Systems have the same internal directory structure as subsystems.
Systems contain views called system views (not spec/load or
combined). As in subsystems, views in systems contain the same
subdirectories found in subsystem views (for example, Units) plus
an additional subdirectory called Paths.
The initial system view is a working view. Within the State
directory of the working system view, you can build a release
activity. A release activity automatically contains entries
that reference the latest release from each child subsystem.
After creating a release activity, you can make a release from
the working system view to preserve that activity as a frozen
object. Every time new releases are made in child subsystems, you
can rebuild the release activity and then make a new release of the
working system view. You can use the Cmvc.Information command to
display the release activity for a given system view.
A system can contain multiple paths that correspond to the paths
in the child subsystems. The release activity in each system path
references releases from the corresponding paths in the child
subsystems.
Setting Up Systems
1. Use the Cmvc.Initial command to create a system. It contains a
working system view.
2. Use the Add_Child command to establish the parent-child
relationship between the desired subsystems and the system.
3. At each major release point, you can run the Build_Activity
command in the working system view to build (or update) a
release activity called Release_Activity that references the
latest releases from child subsystems. Release_Activity is
located in the State directory.
4. Make the release activity the default and execute the
application.
5. If desired, you can edit the release activity using
Build_Activity to change one of the activity entries (do not use
commands from package Activity to modify a release activity).
After a release activity is created, the releases it references
cannot be deleted.
Setting Up Paths
You can use the Cmvc.Make_Path command in a system to create
multiple paths, one for each path in the component subsystems.
Before building a release activity in a given system path, you must
explicitly set up the correspondences between that system path and
the desired paths from the child subsystems. To do this:
1. Locate the Paths directory in the working view of the system
path.
2. In the Paths directory, create a file corresponding to each
child subsystem. The name of each file must be the same as the
name of the subsystem to which it corresponds.
3. In the file for each subsystem, enter a naming expression
that matches the release names in the desired path from that
subsystem.
4. When you build a release activity in a given system path, the
entry for each subsystem will reference the latest release
that matches the naming expression in the Paths file for that
subsystem.
For example, assume that a system called Mail_System has a child
subsystem called Mail_Utilities and that the child contains two
paths whose prefixes are Rev1 and Rev2. Assume further that
Mail_System contains a Rev1 path and that this system path is
to reference releases from the Rev1 path in Mail_Utilities. To
establish the correspondence between the Rev1 system path and the
Rev1 subsystem path:
1. Within the Mail_System.Rev1_Working.Paths directory, create a
file called Mail_Utilities.
2. Edit the file, entering a naming expression that matches the
release names in the Rev1 path of the Mail_Utilities subsystem--
-for example: Rev1@
3. Commit the file.
4. If a Rev2 path is desired in Mail_System, repeat these steps
starting in Mail_System.Rev2_Working.Paths and entering a
naming expression such as Rev2@.
The naming expression in a Paths file can match releases from
more than one path in a given subsystem. In this case, the latest
of the releases from among these paths is entered in the release
activity.
Releasing System Views
You can use the Cmvc.Release command to make releases of
working system views to preserve release activities as frozen
objects. When a system view is released, a subdirectory called
Release_Information is created within the released system view.
The Release_Information directory contains four controlled text
files that can be used to rebuild the release activity and the
views it references from configuration objects.
The Release_Information directory for a released system view is
shown in Figure 12-1.
Assume that you have built a release activity in a working system
view and made a release of that view. Furthermore, assume that
you have destroyed the released system view without deleting
its configuration object and then you have destroyed each of the
releases that were referenced in the release activity, without
deleting their configuration objects. To rebuild the deleted views
and release activity:
1. Use the Cmvc.Build command to rebuild the deleted system-view
release from its configuration object. The system view will be
rebuilt except for the release activity.
2. Locate the Release_Information directory in the rebuilt system
view. Using the Load_Configurations and Spec_Configurations
files as indirect files, use the Cmvc.Build command to rebuild
the views that were referenced in the release activity. (This
step assumes that the child subsystems still exist and contain
configuration objects for those views.)
3. From the Units directory of the rebuilt system view, enter the
Build_Activity command with default parameters to rebuild and
then freeze the release activity. The Build_Activity command
automatically consults the files in the Release_Information
directory.
@node !Commands.Cmvc_Hierarchy.Add_Child
procedure Add_Child (Child : String := ">>SYSTEM/SUBSYSTEM NAME<<";
To_System : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Adds a new child (a subsystem or another system) to the designated
system.
A system provides an automated means of tracking the latest release
from each child and building activities that reference those
releases.
A system cannot directly or indirectly be a child of itself.
@node !Commands.Cmvc_Hierarchy.Build_Activity
procedure Build_Activity (Working_System_View : String := "<CURSOR>";
Views_To_Include : String := "<LATEST>";
Update_Imports : Boolean := True;
Allow_Code_Views : Boolean := False;
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Builds or updates the release activity in the working system view
to include the specified views.
By default, the latest releases of all the children of the system
are included in the release activity. Views are included in
the release activity only if they have been created after the
Build_Activity command was last run on the specified working system
view.
Path restrictions can be used to control which releases are
included.
By default, the working system view imports spec views from all of
the subsystems referenced by the release activity. Updating the
system view's imports allows you to execute test programs from the
system view, if desired. Note that this importing is subject to
the normal compatibility requirements.
By default, code views are overlooked in favor of including the
latest load view in the release activity. However, changing the
Allow_Code_Views parameter to true allows code views to be included
in the release activity.
@node !Commands.Cmvc_Hierarchy.Children
function Children (Of_System : String := "<CURSOR>";
Recursive : Boolean := True;
Response : String := "<WARN>") return String;
Returns a list of designated subsystem's children.
@node !Commands.Cmvc_Hierarchy.Contents
function Contents (Of_System_View : String := "<CURSOR>";
Recursive : Boolean := True;
Response : String := "<WARN>") return String;
Returns the contents of the release activity of the designated
system view.
The function returns a string formatted as a naming expression.
This naming expression contains the fully qualified name of each
view referenced in the release activity. The names are separated
by commas and the entire list is enclosed in brackets.
@node !Commands.Cmvc_Hierarchy.Expand_Activity
procedure Expand_Activity
(New_Activity : String := ">>NEW ACTIVITY NAME<<";
System_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
Makes a dereferenced copy of the release activity in the designated
system view.
That is, in the new release activity, the procedure replaces
the entries for system views with the entries from the release
activities in those system views.
@node !Commands.Cmvc_Hierarchy.Parents
function Parents (Of_Subsystem : String := "<CURSOR>";
Recursive : Boolean := False;
Response : String := "<WARN>") return String;
Returns a list of systems that are parents to the designated
subsystem.
@node !Commands.Cmvc_Hierarchy.Remove_Child
procedure Remove_Child
(Child : String := ">>SYSTEM/SUBSYSTEM NAME<<";
From_System : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
Severs the relationship between a child system or subsystem and its
parent.
This procedure is the opposite of the Add_Child procedure.
@node !Commands.Cmvc_Maintenance
Packages Cmvc_Maintenance defines a set of operations for checking
and restoring the integrity of the various databases associated
with the CMVC system. This package also provides operations for
managing primary and secondary subsystems (copies of subsystems
that support development on multiple R1000s).
Commands Grouped by Topic
The commands in package Cmvc_Maintenance fall into several
functional groups. They are listed here by group for your
convenience. (Note that the reference entries for these commands
are arranged in alphabetical order by command name.)
o Commands for managing the CMVC database:
Check_Consistency Expunge_Database
o Commands for managing the compatibility database (CDB) and
multiple-host development:
Destroy_Cdb Display_Cdb
Make_Primary Make_Secondary
Repair_Cdb Update_Cdb
o Commands for managing code views:
Display_Code_View
@node !Commands.Cmvc_Maintenance.Check_Consistency
procedure Check_Consistency (Views : String := "<CURSOR>";
Response : String := "<PROFILE>");
Checks the consistency of the specified views with respect to the
CMVC database and the Environment library system.
In some cases, corrective action is taken. The specified views can
be in subsystems or in systems.
The CMVC database and the Environment library system both record
various types of information about controlled objects. The Check-
_Consistency command makes sure that information in the database
agrees with the information in the library system. Specifically,
Check_Consistency ensures that:
o There is a configuration object in the Configurations directory
for every configuration represented in the database. Missing
configuration objects are recreated from the database.
o Both the library system and the CMVC database are synchronized
with respect to which objects are controlled. If the library
system and the CMVC database do not agree, the information in
the library system is changed to match the information in the
database.
o The text of each object in the view directories matches the text
stored in the CMVC database for the appropriate generation. Note
that this is a textual comparison, so that differences due to
changed pretty-printer switches will be reported. No action is
taken by Check_Consistency to reconcile the differences; the
Cmvc.Check_Out or Cmvc.Accept_Changes command can be used to get
the latest generation from the database.
The Check_Consistency command also checks the library structure
independently of the CMVC database. The Check_Consistency command
ensures that:
o The directory structure within the specified views or subsystems
is complete. Check_Consistency reconstructs deleted directories
and/or missing objects such as the Subpath_Name and Last-
_Release_Name files in the view.State directory. (Note that
the Last_Release_Name file contains the level numbers of the most
recently released view; when Check_Consistency reconstructs this
file, all the level numbers are set to 0 and the file must be
edited by hand to restore the correct level numbers.)
o The specified views have a model associated with them. Views
that reference deleted models lose that reference; the Cmvc-
.Replace_Model command can be used to provide new models for
those views.
The Check_Consistency command verifies that all imported views
still exist and ensures that, whenever a view is imported by
another view, both views maintain a record of this relationship.
Discrepancies are resolved in favor of the importing view. That
is, if View_1 imports View_2, but View_2 does not list View_1 as a
referencer, then View_2's list of referencers is updated to include
View_1. On the other hand, if View_2 lists View_1 as a referencer,
but View_1 does not list View_2 as an import, View_1 is removed
from View_2's list of referencers.
Finally, the Check_Consistency command makes sure that the
proper links exist for each specified view. Specifically, Check-
_Consistency examines the with clauses within the specified views'
Ada units and reports references for which links do not exist.
Furthermore, Check_Consistency reports unacceptable links---
namely, links that resolve to load views and links that resolve
to unimported spec views. (Typically, such reported links result
from improperly using the Links.Add command instead of the CMVC
importing operations.)
The Check_Consistency command can be used to:
o Reconstruct a configuration object that was deleted by mistake.
o Recover from an attempt to delete a view with commands in package
Library or Compilation. Check_Consistency reconstructs enough
of the view so that it can be deleted successfully with the Cmvc-
.Destroy_View command.
o Reconstruct the directory structure within a view after deleting
directories or objects on which other CMVC commands may depend
(for example, the State, Exports, or Imports directories.)
o Reconcile conflicting reports and error messages---for example,
if error messages indicate that an object is already checked
out, whereas commands such as Cmvc.Show_All_Checked_Out have
indicated that the object is checked in.
@node !Commands.Cmvc_Maintenance.Convert_Old_Subsystem
procedure Convert_Old_Subsystem (Which : String := "<SELECTION>";
Response : String := "<PROFILE>");
Converts the views in one or more subsystems from the Gamma format
to the Delta format so that CMVC operations can be used.
This is not applicable to subsystems created on an R1000
that already has been converted from the Gamma release of the
Environment to a Delta release.
@node !Commands.Cmvc_Maintenance.Delete_Unreferenced_Leading_Generations
procedure Delete_Unreferenced_Leading_Generations
(In_Subsystem : String := "<CURSOR>";
Response : String := "<PROFILE>");
Not yet implemented.
@node !Commands.Cmvc_Maintenance.Destroy_Cdb
procedure Destroy_Cdb (Subsystem : String := "<SELECTION>";
Limit : String := "<WORLDS>";
Effort_Only : Boolean := True;
Response : String := "<PROFILE>");
Destroys the compatibility database for the specified subsystem.
When units are compiled in a subsystem, information from
the compatibility database is incorporated into the DIANA
representation for those units. Therefore, when a compatibility
database is destroyed, all compiled units in the subsystem are
demoted to the source state and all code views are deleted.
When the Effort_Only parameter is true, the compatibility database
is not actually destroyed; instead, a report is generated listing
the units that would be demoted as a result of destroying the
database.
The compatibility database for a subsystem is recreated
automatically the next time units are compiled in that subsystem.
When recreated, however, the compatibility database provides a
new subsystem identification number, effectively severing the
subsystem from any secondary or primary subsystems with which it
was associated. A subsystem is automatically made primary whenever
its compatibility database is destroyed and then recreated.
Destroying a compatibility database may be useful in the following
cases:
o A compatibility database may need to be destroyed if it is
corrupted---for example, if any of the objects in the subsystem-
.State.Compatibility directory are deleted.
o A compatibility database can be destroyed to remove references
to any units that were once compiled in the subsystem but are now
deleted.
@node !Commands.Cmvc_Maintenance.Display_Cdb
procedure Display_Cdb (Subsystem : String := "<CURSOR>";
Show_Units : Boolean := False;
Response : String := "<PROFILE>");
Displays information from the compatibility database for each of
the specified subsystems.
A subsystem contains a compatibility database only after units have
been promoted to the installed or coded state in that subsystem.
The following information is displayed in the output window:
o Whether the subsystem is primary or secondary
o The subsystem identification number
o How many Ada units are represented in the compatibility database
If the Show_Units parameter is true, each unit is listed along
with the number of declarations it contains. Note that every unit
that was ever compiled in a given subsystem is represented in that
subsystem's compatibility database. Therefore, even deleted units
appear in the listing.
@node !Commands.Cmvc_Maintenance.Display_Code_View
procedure Display_Code_View (View : String := "<CURSOR>";
Verbose_Unit_Info : Boolean := False;
Show_Map_Info : Boolean := False;
Response : String := "<PROFILE>");
Displays information about the specified code view.
By default, the command displays a list of units in the code view.
(Recall that code views are created by the Cmvc.Make_Code_View
command.)
If the Verbose_Unit_Info parameter is true, the command displays
the withed units and other compiler information for each unit in
the code view.
If the Show_Map_Info parameter is true, the command displays a
mapping of the code segments and exceptions from the code view to
the original view. Since code views do not support source-level
debugging, setting Show_Map_Info to true can be used as a debugging
aid.
@node !Commands.Cmvc_Maintenance.Expunge_Database
procedure Expunge_Database (In_Subsystem : String := "<CURSOR>";
Response : String := "<PROFILE>");
Expunges the CMVC database, removing stored information and
history about unused configurations or objects.
Expunging the database deletes any configuration represented in
the database for which there is no corresponding configuration
object in the subsystem.Configurations directory.
Expunging the database also deletes any join set represented in
the CMVC database if no configuration references any object in the
set. All generations associated with the join set are deleted,
effectively deleting the history for the unused objects from the
database.
The Expunge_Database command is useful when attempting to delete a
view and then recreate it with the same name. To do this:
1. Enter the Cmvc.Destroy_View command with the Destroy-
_Configuration_Also parameter set to true. (This destroys
the configuration object and the state description directory
along with the view.)
2. Enter the Expunge_Database command to remove references to the
configuration from the CMVC database.
3. Recreate the view.
@node !Commands.Cmvc_Maintenance.Make_Primary
procedure Make_Primary (Subsystem : String := "<SELECTION>";
Moving_Primary : Boolean := False;
Response : String := "<PROFILE>");
Converts the specified secondary subsystem into a primary
subsystem with its own updatable compatibility database.
When development occurs on multiple R1000s, a copy of each
subsystem needs to reside on each machine so that the entire
application can be executed. One copy of a given subsystem,
called the primary subsystem, contains an updatable compatibility
database and thus supports ongoing development. The other copies,
called secondary subsystems, have frozen compatibility databases
and essentially are local copies for execution and test. Every
secondary subsystem is associated with exactly one primary
subsystem and shares its subsystem identification number.
Subsystems created by the Cmvc.Initial command are always created
as primary subsystems. A subsystem also is made primary whenever
its compatibility database is destroyed and then recreated (see
the Destroy_Cdb command). By default, subsystems created by the
Archive.Copy or Archive.Restore commands are secondary subsystems,
even if they were copied from primary subsystems. (Note, however,
that the Options parameter in each of these Archive commands can be
set to Primary to create primary subsystems.)
The Make_Primary command converts secondary subsystems to primary
subsystems and can be used as one step in the process of:
o Creating a a separate, updatable subsystem from an existing
subsystem. To create a new primary subsystem that is not
associated with any other existing subsystems:
1. Make a copy of the existing subsystem using the Archive.Copy
command. If the default value for the Options parameter is
used, a secondary subsystem is created.
2. Convert the secondary subsystem to a primary subsystem using
the Make_Primary command with the Moving_Primary parameter
set to false. The converted subsystem is given a unique
subsystem identification number and so is no longer associated
with any other primary subsystem.
o Relocating a primary subsystem to a different host. To move
a primary subsystem to a location currently occupied by an
associated secondary subsystem:
1. Find or create an associated secondary subsystem on the
desired host.
2. Update the compatibility database in the secondary subsystem
using the Update_Cdb command.
3. Convert the secondary subsystem to a primary subsystem using
the Make_Primary command with the Moving_Primary parameter
set to true. This causes the converted subsystem to retain
its original subsystem identification number and thus its
previous association with other subsystems.
4. Either destroy the original primary subsystem or convert it to
a secondary subsystem with the Make_Secondary command. This
step must be done to prevent corruption of the compatibility
database.
Care must be taken to ensure that the Moving_Primary parameter has
the correct value for the desired operation. In particular, the
value false assigns the subsystem a new identification number,
severing its association from other subsystems, including its
original primary subsystem. The new identification number is
retained, even if the subsystem is made secondary again.
@node !Commands.Cmvc_Maintenance.Make_Secondary
procedure Make_Secondary (Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
Converts the specified primary subsystem into a secondary
subsystem with a read-only compatibility database.
When development occurs on multiple R1000s, a copy of each
subsystem needs to reside on each machine so that the entire
application can be executed. One copy of a given subsystem,
called the primary subsystem, contains an updatable compatibility
database and thus supports ongoing development. The other copies,
called secondary subsystems, have frozen compatibility databases
and essentially are local copies for execution and test. Every
secondary subsystem is associated with exactly one primary
subsystem and shares its subsystem identification number.
By default, secondary subsystems are created by the Archive.Copy
or Archive.Restore commands, even if they were copied from primary
subsystems. (Note, however, that the Options parameter in each of
these Archive commands can be set to create primary subsystems.)
The Make_Secondary command is used in the last step in the process
of moving a primary subsystem:
1. Update the compatibility database in the secondary subsystem
using the Update_Cdb command.
2. Convert the secondary subsystem to a primary subsystem using
the Make_Primary command with the Moving_Primary parameter set
to true. This causes the converted subsystem to retain its
original subsystem identification number and thus its previous
association with other subsystems.
3. Either destroy the original primary subsystem or convert it to
a secondary subsystem with the Make_Secondary command. This
step must be done to prevent corruption of the compatibility
database.
@node !Commands.Cmvc_Maintenance.Repair_Cdb
procedure Repair_Cdb (Subsystem : String := "<SELECTION>";
Verify_Only : Boolean := True;
Delete_Current : Boolean := False;
Response : String := "<PROFILE>");
Verifies that the information in the specified subsystem's
compatibility database is consistent with the DIANA representation
of the subsystem's compiled units.
When the Verify_Only parameter is false, some or all of the
inconsistencies are repaired, depending on the value of the Delete-
_Current parameter.
When units are compiled in a subsystem, information from
the compatibility database is incorporated into the DIANA
representation for those units. If the compatibility database
is corrupted after units have been compiled, it can be repaired
or rebuilt using information from the DIANA representation of the
compiled units. For example, if an object in the subsystem.State-
.Compatibility directory is deleted, the Repair_Cdb command can
rebuild the object.
Note that Repair_Cdb can rebuild a compatibility database only from
the DIANA representation of installed or coded units. Therefore,
Repair_Cdb cannot be used to restore a database destroyed by the
Destroy_Cdb command, because Destroy_Cdb also deletes the DIANA
representation.
As long as there is at least one installed or coded unit in the
subsystem, the database can be rebuilt with the same subsystem
identification number.
@node !Commands.Cmvc_Maintenance.Update_Cdb
procedure Update_Cdb (From_Subsystem : String := "<ASSOCIATED_PRIMARY>";
To_Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
Updates a secondary subsystem's compatibility database by copying
the compatibility database from another subsystem.
The two subsystems must have the same subsystem identification
number, although they can be on different R1000s.
Typically, a compatibility database is copied from a primary
subsystem into an associated secondary subsystem to:
o Compile incremental changes in the secondary subsystem
o Prepare a secondary subsystem to be converted to a primary
subsystem (see the Make_Primary command)
Note that the compatibility database is automatically moved
whenever Archive.Copy is used to copy views or individual units
from one subsystem into another. In contrast, the Update_Cdb
command copies only the compatibility database. Thus, using the
Update_Cdb command is equivalent to entering the Archive.Copy
command with Options => "cdb".
The Update_Cdb command cannot be used to revert a compatibility
database to a previous version. See the Revert_Cdb value of the
Option parameter of the Archive.Copy command.
@node !Commands.Work_Order
This package provides operations for creating, viewing, and
manipulating work orders, work-order lists, and ventures. These
objects can be associated with user sessions (that is, with user
IDs and session names) to collect and convey data about project
management among team members involved in large-system development
using subsystems.
Many characteristics of work orders, work-order lists, and
ventures are controllable with session switches, which are
described in a following section.
Work orders are designed to communicate details about specific
tasks to be accomplished. They may present instructions to a
developer and collect project work data to mark ongoing progress.
A particular work order may address one or more developers, but
typically it is limited in scope; a work order may describe one bug
to be fixed, for example.
Groups of related work orders constitute a work-order list. For
example, a work-order list may relate to a particular module of
code or it may be the set of work orders assigned to an individual
developer.
A larger component of project management is the venture. A venture
is a management tool that contains information about groups of
work orders and work-order lists and controls their use via venture
policy switches. Each work order must have a venture that is its
"parent."
Ventures, work-order lists, and work orders are library objects.
For each project-management object, package Work_Order provides
subprograms to:
o Create, display, and edit the object
o View and set the default object for a user or session
o View and set the textual notes within the object
Although there are editing commands in packages within package
Work_Order for each object, viewing and editing of work orders,
work-order lists, and ventures is perhaps most easily done with
commands from package Common. See the following introductions to
subpackages Editor, List_Editor, and Venture_Editor for sample
displays and specific information about using Common commands for
editing.
Session Switches
Many session switches determine how information in work orders,
work-order lists, and ventures are formatted. See SJM, Session
Switches, for more information on session switches.
The following session switches pertain to project-reporting
objects. Unless otherwise specified, the full name for each
switch begins with Session. For example, the full name for
Cmvc_Break_Long_Lines is Session.Cmvc_Break_Long_Lines.
Cmvc_Break_Long_Lines (default true)
Controls whether lines in work orders, work-order lists, and
ventures that exceed the value of the Cmvc_Line_Length switch
are broken. User-entered strings are never broken.
Cmvc_Capitalize (default true)
Determines whether words, other than those in user-entered
strings, in work orders, work-order lists, and ventures are
capitalized.
Cmvc_Comment_Extent (default 4)
Specifies, as an integer value, the number of comments displayed in
a work order.
Cmvc_Configuration_Extent (default 0)
Specifies, as an integer value, the number of configurations
displayed in a work order.
Cmvc_Field_Extent (default 4)
Specifies, as an integer value, the number of elements of vector
fields that are displayed in a work order.
Cmvc_Indentation (default 2)
Specifies, as an integer value, the number of spaces used for
indentation in work orders, work-order lists, and ventures.
Cmvc_Line_Length (default 80)
Specifies, as an integer value, how long a line in a work order,
work-order list, or venture can be before it is eligible to be
broken.
Cmvc_Shorten_Name (default true)
Shows object names in work orders, work-order lists, and ventures
in a shortened form.
Cmvc_Shorten_Unit_State (default false)
Shows the state of work orders in a shortened form.
Cmvc_Show_Add_Date (default true)
Displays the date an entry is added to a work order.
Cmvc_Show_Add_Time (default true)
Displays the time an entry is added to a work order.
Cmvc_Show_All_Default_Lists (default false)
Displays only the user's default work-order list in a venture.
Cmvc_Show_All_Default_Orders (default false)
Displays only the user's default work order in a venture.
Cmvc_Show_Deleted_Objects (default false)
Shows deleted work orders or work-order lists in a work-order list.
Display of deleted objects is controlled by elision.
Cmvc_Show_Deleted_Versions (default false)
Shows version numbers and information for all versions of a
work order or work-order list. Display of deleted versions is
controlled by elision.
Cmvc_Show_Display_Position (default false)
Shows display position of user-defined work-order fields.
Cmvc_Show_Edit_Info (default false)
Shows edit information for objects displayed in work orders, work-
order lists, or ventures.
Cmvc_Show_Field_Default (default true)
Shows the default value for vector fields. If this switch is true,
vector fields will show the default value of all elements that have
not been assigned.
Cmvc_Show_Field_Max_Index (default false)
Shows the number of entries in a vector field that have been
written.
Cmvc_Show_Field_Type (default false)
Shows the type of field (that is, Boolean, integer, or string) for
all scalar and vector fields.
Cmvc_Show_Frozen (default false)
Shows "Frz" for frozen objects displayed in work orders, work-
order lists, or ventures.
Cmvc_Show_Hidden_Fields (default false)
Displays hidden fields in a venture.
Cmvc_Show_Retention (default false)
Shows the retention count when displaying objects in work orders,
work-order lists, or ventures.
Cmvc_Show_Boolean (default false)
Shows the size of the version, in bytes, when displaying objects in
a work order, work-order list, or venture.
Cmvc_Show_Unit_State (default true)
Shows the state of work orders listed in ventures and work-order
lists (that is, pending, in progress, closed).
Cmvc_Show_Users (default false)
Shows the list of users in the users field of work orders. Display
of users is controlled by elision.
Cmvc_Show_Version_Number (default false)
Shows the version number of objects displayed in work orders,
work-order lists, or ventures.
Cmvc_Uppercase (default false)
Determines whether words, other than those in user-entered
strings, in work orders, work-order lists, and ventures are
displayed in uppercase.
Cmvc_Version_Extent (default 0)
Specifies, as an integer value, the number of versions displayed in
a work order.
Default_Venture
Specifies a filename for the default venture for the session. The
full switch name is Cmvc.Default_Venture.
@node !Commands.Work_Order.Add_To_List
procedure Add_To_List (Order_Names : String := "<IMAGE>";
List_Name : String := "<WORK_LIST>";
Response : String := "<PROFILE>");
Adds one or more work orders to a work-order list.
@node !Commands.Work_Order.Close
procedure Close (Order_Name : String := "<ORDER>";
Response : String := "<PROFILE>");
Sets the status of the specified work order to closed.
Once a work order has been closed, it no longer can be modified.
@node !Commands.Work_Order.Create
procedure Create (Order_Name : String := ">>OBJECT NAME<<";
Notes : String := "";
On_List : String := "<WORK_LIST>";
On_Venture : String := "<VENTURE>";
Make_Default_Work_Order : Boolean := True;
Response : String := "<PROFILE>");
Creates a work order on the specified venture and adds it to a
work-order list.
The new work order is created on the default venture for the
current session unless the On_Venture parameter names a venture.
The string specified in the Notes parameter is entered into the
notes field of the new work order. If the Make_Default_Work_Order
parameter is true, the new work order becomes the default work
order on the parent venture.
@node !Commands.Work_Order.Create_Field
procedure Create_Field
(Field_Name : String := ">>FIELD NAME<<";
Field_Type : String := ">>BOOLEAN|STRING|INTEGER<<";
Is_Vector : Boolean := False;
Is_Controlled : Boolean := False;
Default : String := "";
Display_Position : Natural := Natural'Last;
On_Venture : String := "<VENTURE>";
Propagate : Boolean := True;
Renumber_Fields : Boolean := True;
Response : String := "<PROFILE>");
Creates a new user-defined field with the designated data type in
the specified venture.
This field appears in all work orders subsequently created on
this venture. If the Propagate parameter is true, all work orders
already created on this venture are updated to contain this field.
The new field appears with the initial value specified by the
Default parameter.
@node !Commands.Work_Order.Create_List
procedure Create_List (List_Name : String := ">>OBJECT NAME<<";
Notes : String := "";
On_Venture : String := "<VENTURE>";
Make_Default_List : Boolean := True;
Response : String := "<PROFILE>");
Creates a work-order list on the specified venture.
@node !Commands.Work_Order.Create_Venture
procedure Create_Venture
(Venture_Name : String := ">>OBJECT NAME<<";
Notes : String := "";
Make_Default_Venture : Boolean := True;
Response : String := "<PROFILE>");
Creates a new venture.
@node !Commands.Work_Order.Default
function Default (For_Venture : String := "<VENTURE>";
For_User : String := "<CURRENT_USER>";
Ignore_Garbage : Boolean := True) return String;
Returns the name of the user's default work order in the specified
venture.
@node !Commands.Work_Order.Default_List
function Default_List (For_Venture : String := "<VENTURE>";
For_User : String := "<CURRENT_USER>";
Ignore_Garbage : Boolean := True) return String;
Returns the name of the user's default work-order list in the
specified venture.
@node !Commands.Work_Order.Default_Venture
function Default_Venture (For_User : String := "<CURRENT_USER>";
Ignore_Garbage : Boolean := True) return String;
Returns the pathname of the default venture for a user.
@node !Commands.Work_Order.Delete_Field
procedure Delete_Field (Field_Name : String := ">>FIELD NAME<<";
Venture_Name : String := "<VENTURE>";
Even_If_Data_Present : Boolean := False;
Response : String := "<PROFILE>");
Deletes the named field from the venture.
@node !Commands.Work_Order.Display
procedure Display (Order_Name : String := "<ORDER>";
Options : String := "";
Response : String := "<PROFILE>");
Formats and displays the contents of the specified work order in
the output window.
The format of the display is controlled by the Options parameter.
This display cannot be edited; to edit a work order, see the Edit
command.
@node !Commands.Work_Order.Display_List
procedure Display_List (List_Name : String := "<WORK_LIST>";
Options : String := "";
Response : String := "<PROFILE>");
Formats and displays the contents of the specified work-order list
in the output window.
The format of the display is controlled by the Options parameter.
This display cannot be edited; to edit a work-order list, see the
Edit_List command.
@node !Commands.Work_Order.Display_Venture
procedure Display_Venture (Venture_Name : String := "<VENTURE>";
Options : String := "";
Response : String := "<PROFILE>");
Formats and displays the contents of the specified venture in the
output window.
The format of the display is controlled by the Options parameter.
This display cannot be edited; to edit a venture, see the
Edit_Venture command.
@node !Commands.Work_Order.Edit
procedure Edit (Order_Name : String := "<ORDER>");
Edits the designated work order.
The procedure creates a window in which the designated work order
is displayed. If a window already exists for that work order, the
window is reused. From the window, the work order can be edited
with the operations from package !Commands.Common that apply to
this class of object.
@node !Commands.Work_Order.Edit_List
procedure Edit_List (List_Name : String := "<WORK_LIST>");
Edits the designated work-order list.
The procedure creates a window in which the designated work-order
list is displayed. If a window already exists for that work-order
list, the window is reused. From the window, the work-order list
can be edited with the operations from package !Commands.Common
that apply to this class of object.
@node !Commands.Work_Order.Edit_Venture
procedure Edit_Venture (Venture_Name : String := "<VENTURE>");
Edits the designated venture.
The procedure creates a window in which the designated venture is
displayed. If a window already exists for that venture, the window
is reused. From the window, the venture can be edited with the
operations from package !Commands.Common that apply to this class
of object.
@node !Commands.Work_Order.Notes
function Notes (Order_Name : String := "<ORDER>") return String;
Returns the notes field of the specified work order.
The notes field typically contains descriptive information about a
work order.
@node !Commands.Work_Order.Notes_List
function Notes_List (List_Name : String := "<WORK_LIST>") return String;
Returns the notes field of the specified work-order list.
The notes field typically contains descriptive information about a
work-order list.
@node !Commands.Work_Order.Notes_Venture
function Notes_Venture (Venture_Name : String := "<VENTURE>")
return String;
Returns the notes field for the specified venture.
The notes field typically contains descriptive information about a
venture.
@node !Commands.Work_Order.Remove_From_List
procedure Remove_From_List (Order_Names : String := "<IMAGE>";
List_Name : String := "<WORK_LIST>";
Response : String := "<PROFILE>");
Removes the entry for the specified work order from a work-order
list.
@node !Commands.Work_Order.Set_Default
procedure Set_Default (To_Work_Order : String := "<CURSOR>";
For_Venture : String := "<VENTURE>";
For_User : String := "<CURRENT_USER>";
Response : String := "<PROFILE>");
Sets the specified work order to be the default for a given user
and session whenever the work order's parent venture is the
default.
Each venture contains a list of mappings between user sessions
and work orders. When a user sets a venture as the default in a
given session, the work order mapped to that session in the venture
automatically becomes the user's default work order. This command
modifies the venture by adding or changing the mapping from session
to work order in the specified venture.
@node !Commands.Work_Order.Set_Default_List
procedure Set_Default_List (To_List : String := "<CURSOR>";
For_Venture : String := "<VENTURE>";
For_User : String := "<CURRENT_USER>";
Response : String := "<PROFILE>");
Sets the specified work-order list to be the default for a given
user and session whenever the work-order list's parent venture is
the default.
Each venture contains a list of mappings between user sessions and
work-order lists. When a user sets a venture as the default in a
given session, the work-order list mapped to that session in the
venture automatically becomes the user's default work-order list.
This command modifies the venture by adding or changing the mapping
from session to work-order list in the specified venture.
@node !Commands.Work_Order.Set_Default_Venture
procedure Set_Default_Venture (To_Venture : String := "<CURSOR>";
For_User : String := "<CURRENT_USER>";
Response : String := "<PROFILE>");
Sets the default venture for the specified session.
Setting a venture to be the default automatically sets the default
work order and the default work-order list for the current session,
if such defaults have been specified for that venture.
Setting a default venture with this command automatically sets the
value of the Cmvc.Default_Venture session switch to the specified
venture name.
@node !Commands.Work_Order.Set_Notes
procedure Set_Notes (To_Value : String := ">>New Notes<<";
Order_Name : String := "<ORDER>";
Response : String := "<PROFILE>");
Modifies the notes field for the specified work order.
Any existing notes in the specified work order are replaced by
the new notes. Unlike user-defined fields, the notes field can be
updated multiple times.
The notes field typically is used to provide a brief description of
the work order.
@node !Commands.Work_Order.Set_Notes_List
procedure Set_Notes_List (To_Value : String := ">>New Notes<<";
List_Name : String := "<WORK_LIST>";
Response : String := "<PROFILE>");
Modifies the notes field for the specified work-order list.
Any existing notes in the specified work-order list are replaced by
the new notes.
The notes field typically is used to provide a brief description of
the work-order list.
@node !Commands.Work_Order.Set_Notes_Venture
procedure Set_Notes_Venture (To_Value : String := ">>New Notes<<";
Venture_Name : String := "<VENTURE>";
Response : String := "<PROFILE>");
Modifies the notes field for the specified venture.
Any existing notes in the specified venture are replaced by the new
notes.
The notes field typically is used to provide a brief description of
the venture.
@node !Commands.Work_Order.Set_Venture_Policy
procedure Set_Venture_Policy
(The_Switch : Venture_Policy_Switch;
To_Value : Boolean;
Venture_Name : String := "<VENTURE>";
Effort_Only : Boolean := False;
Response : String := "<PROFILE>");
Sets the specified venture policy switch to the specified value.
This command also can be used to determine the value of a
particular switch for a venture that currently is not displayed.
@node !Commands.Work_Order.Venture_Policy_Switch
type Venture_Policy_Switch is (Require_Current_Work_Order,
Require_Comments_At_Check_In,
Require_Comment_Lines,
Journal_Comment_Lines,
Allow_Edit_Of_Work_Orders);
Defines the policies that can be enforced for a venture.
When a user has a default venture, the policies on that venture
are followed by CMVC commands; errors result if any policies are
violated. For example, if the policy Require_Current_Work_Order
is enforced for the user's default venture, the user must have a
default work order to execute any CMVC commands that would update a
work order, such as Cmvc.Check_In and Cmvc.Check_Out.
Using package !Implementation.Work_Order_Implementation, these
policies can be interrogated and enforced by other user-defined
commands.
Allow_Edit_Of_Work_Orders
Defines a policy in which controlled user-defined fields can
be modified interactively. User-defined fields that are not
controlled can be modified, independent of this policy. Note
that all user-defined fields can be modified only once.
Journal_Comment_Lines
Defines a policy in which comment strings provided to CMVC commands
are recorded in the work-order comments field. It makes no sense
to enforce Require_Comments_At_Check_In or Require_Comment_Lines
without enforcing Journal_Comment_Lines.
Require_Comment_Lines
Defines a policy that requires users to provide a string comment to
all CMVC commands that have a Comments parameter. The null string
will not be accepted.
Require_Comments_At_Check_In
Defines a policy that requires users to provide a string to the
Comments parameter of the Cmvc.Check_In command. The null string
will not be accepted.
Require_Current_Work_Order
Defines a policy that requires users to have a default work order
in order to execute any CMVC commands that have a Work_Order
parameter.
@node !Commands.Work_Order.Editor
The commands in package Work_Order.Editor are used for
interactively editing work orders. Generally, users will not
enter these commands directly but will invoke them through commands
in package !Commands.Common.
The formatted display of a sample work order is shown below.
Following this is a field-oriented list of applicable commands
from package Common.
!Users.Drk.W_1.Order_4 : In_Progress;
-------------------------------------
Notes:
+ "New notes for this work order"
Parent Venture: (!Users.Drk.W_1...)
...A_Venture
Status: In_Progress
Created at 87/04/13 10:40:12 by Drk.S_1
Fields:
"A Vector String Field" 5 Strings =>
2 => "number 2"
3 => "number 3"
4 => "some more values"
5 => "another value"
+ 0 => "a value which hasn't been saved yet"
others => "uninitialized"
= "A Controlled Boolean" => False
Comments: 1 + 1
87/04/27 11:40:03 Drk.S_1 for ">>Element Name<<" => ">>Comment<<"
+ 87/04/28 14:30:23 Drk.S_1 for ">>Element Name<<" =>
+ ">>A New and much longer Comment<<"
Users: 1
Drk.S_1
Versions: 1 (!Users.Drk...)
87/04/28 11:38:48 "A_Venture".1 ...W_1
Configurations: 1
87/04/23 15:18:48 !Machine.Error_Logs
In the following list are brief descriptions of the operations
affected by commands from package Common for each field in the
foregoing work-order display. Commands not listed have no effect
or produce results consistent with the descriptions in the EST
book.
Field Command/Program Action
Notes Delete reverts to old notes, if any; Edit/Insert
prompt in a Command window for new notes.
Fields Definition creates minor window to show detailed
information about all fields; Delete removes a newly
inserted field for which no values have been saved;
Edit/Insert prompt in a Command window for data about
a new field; Expand/Elide show more/less of field
extent; Explain shows maximum index, defaults, and
type for each field.
Comments Definition creates minor window to show all comments;
Delete removes newly inserted comment, if it has not
been saved; Edit/Insert prompt in a Command window
for a new comment; Expand/ Elide show more/less of
comment extent; Explain shows the date and time
comment was added.
Users Definition traverses to session object in user's home
directory; Expand/Elide show/hide list of users.
Versions Definition creates minor window to show all versions;
Delete removes newly inserted version data, if
it has not been saved; Edit/ Insert prompt in a
Command window for information about a new version;
Expand/Elide show more/less of version extent;
Explain shows the date and time version was added.
Configurations Definition creates minor window to show all\r
configurations; Delete removes newly inserted
configuration, if it has not been saved; Edit/Insert
prompt in a Command window for information about a
new configuration; Expand/Elide show more/less about
a configuration; Explain shows the date and time
configuration was added.
When a work order is edited interactively, the object is locked
and the # symbol appears in the window banner. Individual changes
are marked by a + symbol until they are saved using Common.Commit.
Changes can be undone until they are saved.
@node !Commands.Work_Order.Editor.Add_Comment
procedure Add_Comment (The_Comment : String := ">>Comment<<";
The_Element : String := ">>Element Name<<";
The_User : String := "<CURRENT_USER>");
Adds a comment to those recorded in the work order.
Once a comment has been added, it cannot be removed.
@node !Commands.Work_Order.Editor.Add_Configuration
procedure Add_Configuration (The_Configuration : String :=
">>Configuration Name<<");
Adds a configuration to those recorded in the work order.
Once a configuration has been added, it cannot be removed.
@node !Commands.Work_Order.Editor.Add_User
procedure Add_User (The_User : String := "<CURRENT_USER>");
Adds a user session to those recorded in the work order.
Once a user has been added, it cannot be removed.
@node !Commands.Work_Order.Editor.Add_Version
procedure Add_Version
(The_Configuration : String := ">>Configuration Name<<";
The_Element : String := ">>Element Name<<";
The_Generation : Natural := 0);
Adds a version to those recorded in the work order.
Once a version has been added, it cannot be removed.
@node !Commands.Work_Order.Editor.Set_Field
procedure Set_Field (To_Value : Boolean := False;
The_Index : Natural := 0;
The_Field : String := ">>Field Name<<");
Sets the Boolean value of the specified work-order field to the
specified value.
Once a work-order field has been set, it cannot be modified
further.
@node !Commands.Work_Order.Editor.Set_Field
procedure Set_Field (To_Value : Integer := 0;
The_Index : Natural := 0;
The_Field : String := ">>Field Name<<");
Sets the integer value of the specified work-order field to the
specified value.
Once a work-order field has been set, it cannot be modified
further.
@node !Commands.Work_Order.Editor.Set_Field
procedure Set_Field (To_Value : String := ">>Field Value<<";
The_Index : Natural := 0;
The_Field : String := ">>Field Name<<");
Sets the string value of the specified work-order field to the
specified value.
Once a work-order field has been set, it cannot be modified
further.
@node !Commands.Work_Order.Editor.Set_Notes
procedure Set_Notes (Notes : String := ">>New Notes<<");
Sets the notes field of the work order to the specified string.
The specified text will replace the existing text.
@node !Commands.Work_Order.List_Editor
This package provides operations for adding work orders to work-
order lists and setting the notes for a work-order list.
The formatted display of a sample work-order list is shown below.
Following this is a field-oriented list of applicable commands from
package !Commands.Common.
!Users.Drk.W_1.A_List
---------------------
Notes: "Outstanding work orders"
Parent Venture: (!USERS.DRK.W_1...)
...A_Venture
Work Orders: (!USERS.DRK.W_1...)
...Order_1 : In_Progress;
...Order_2 : Pending ;
...Order_3 : ;
In the following list are brief descriptions of the operations
affected by commands from package Common for each field in the
foregoing display. Commands not listed have no effect or produce
results consistent with the descriptions in the EST book.
Field Command/Program Action
Notes Delete reverts to old notes, if any; Edit/Insert
prompt in a Command window for new notes.
Orders Delete removes unsaved insertions; marks an existing
order to be removed from the list.
@node !Commands.Work_Order.List_Editor.Add
procedure Add (Work_Orders : String := ">>Work Order Names<<");
Adds the specified work orders to the local work-order list.
@node !Commands.Work_Order.List_Editor.Set_Notes
procedure Set_Notes (Notes : String := ">>New Notes<<");
Sets the notes field of the work-order list to the specified
string.
The specified text will replace the existing text.
@node !Commands.Work_Order.Venture_Editor
These commands are intended for use when editing ventures. They
will execute only in a Command window attached to a venture;
all operations modify that venture. Many commands are bound to
keys that, when pressed, prompt the user for parameter completion
through a Command window.
The formatted display of a sample venture is shown below. Following this
is a field-oriented list of applicable commands from package
Common.
!Users.Drk.W_1.A_Venture
------------------------
Notes: "Notes for this venture"
Policy_Switches:
Require_Current_Work_Order => False
Require_Comment_At_Check_In => True
Require_Comment_Lines => True
Journal_Comment_Lines => True
Allow_Edit_Of_Work_Orders => False
Fields:
"A Hidden Field" Integer @ 0 => 0
= "A Controlled Hidden Field" Integers @ 0 => -1
= "A Controlled Boolean" Boolean @ 1 => False
"A Vector String Field" Strings @ 2 => "uninitialized"
Work_Orders: (!Users.Drk.W_1...)
...Order_1 : In_Progress;
...Order_2 : Pending ;
...Order_3 : ;
...Order_4 : In_Progress;
Default_Work_Orders: (!Users.Drk.W_1...)
Drk.S_1 => ...Order_2
Drk.S_2 => ...Order_3
Work_Order_Lists: (!Users.Drk.W_1...)
...A_List
Default_Work_Order_Lists: (!Users.Drk.W_1...)
Drk.S_2 => ...A_List
In the following list are brief descriptions of the operations
affected by commands from package Common for each field in the
foregoing display. Commands not listed have no effect or produce
results consistent with the descriptions in the EST book.
Field Command/Program Action
Notes Delete reverts to old notes, if any; Edit/Insert
prompt in a Command window for new notes.
Policy Delete sets the policy to false; Edit toggles current
policy switch; Insert prompts in a Command window for
new policy value.
Fields Delete sets display to begin with field 0; Edit
prompts for new type and position on a field display
line; Expand/Elide show/hide hidden fields; Explain
shows defaults and type for each field; Insert
prompts in a Command window for data about a new
field.
Orders Insert prompts in a Command window to create a new
work order.
Default_Orders Delete sets the default work order to nil;\r
Edit/Insert prompt in a Command window for a new
default work order; Expand/Elide show/hide list of
users.
Lists Insert prompts in a Command window to create a new
work-order list.
Default_Lists Delete sets the default work-order list to nil;
Edit/Insert prompt in a Command window for a new
default work-order list; Expand/Elide show/hide list
of users.
@node !Commands.Work_Order.Venture_Editor.Set_Default_List
procedure Set_Default_List (New_Default : String := "<SELECTION>";
For_User : String := "<CURRENT_USER>");
Sets the default work-order list for a specific user session on the
local venture.
Each user session can have a different default work-order list.
Several commands reference the default work-order list of the
default venture when determining which work-order list to use.
@node !Commands.Work_Order.Venture_Editor.Set_Default_Order
procedure Set_Default_Order (New_Default : String := "<SELECTION>";
For_User : String := "<CURRENT_USER>");
Set the default work order for a specific user session on the local
venture.
Each user session may have a different default work order. Several
commands reference the default work order of the default venture
when determining which work order to use.
@node !Commands.Work_Order.Venture_Editor.Set_Field_Info
procedure Set_Field_Info (Is_Controlled : Boolean := False;
Display_Position : Natural := 1;
The_Field : String := ">>Field Name<<");
Sets the numeric tag of a user-defined field and specifies whether
that field is modifiable.
Numeric tags control the relative display position of the field
within the venture.
@node !Commands.Work_Order.Venture_Editor.Set_Notes
procedure Set_Notes (Notes : String := ">>New Notes<<");
Sets the notes field of the venture to the specified string.
The specified text will replace the existing text.
@node !Commands.Work_Order.Venture_Editor.Set_Policy
procedure Set_Policy (To_Value : Boolean := False;
The_Switch : Venture_Policy_Switch);
Sets the value of the specified venture policy switch to the
specified value.
@node !Commands.Work_Order.Venture_Editor.Spread_Fields
procedure Spread_Fields (Interval : Natural := 10);
Renumbers all user-defined fields, assigning new numeric tags
using the specified interval.
This command is useful for creating a place to insert a new field
between two existing fields that are consecutively numbered.