|
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 - downloadIndex: ┃ P T ┃
Length: 695245 (0xa9bcd)
Types: TextFile
Names: »PM_HELP«
└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
└─ ⟦fc9b38f02⟧ »DATA«
└─⟦f95d63c89⟧
└─⟦this⟧
@node !Commands.Activity
An activity is a file that 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.
RESOURCES IN PACKAGE ACTIVITY
Creating and viewing activity files:
Create Display
Edit Visit
Manipulating entries in activity files:
Add Change
Insert Merge
Remove Set_Load_View
Set_Spec_View
Writing activities to text files: Write
Setting activities for jobs and sessions: Set, Set_Default
Obtaining information:
Current Enclosing_Subsystem
Enclosing_View The_Current_Activity
The_Enclosing_Subsystem The_Enclosing_View
KEY CONCEPTS FOR PACKAGE ACTIVITY
Each subsystem in a program normally contains multiple views that express
alternative implementations and separate interfaces. Activities are the
means of choosing from among the alternative implementations and
assembling the choices into complete programs.
You can maintain multiple activities that define different versions of
your program. For example, you can use activities to:
* List the implementations that compose the program you are currently
testing
* Record the implementations that compose past releases of the program
* Specify the implementations that compose special-purpose releases of
the program for different customers
Information in Activity Entries
An activity is a table in which each entry specifies both a subsystem and
one of its implementations. For example, the following fragment of an
activity shows an entry that lists the load view Rev1_0_1 for the
subsystem !Programs.Mail.Mail_Utilities:
Subsystem | Spec View | Load View | Context
-----------------------------------------------------------------
. . .
MAIL_UTILITIES | | REV1_0_1 | !PROGRAMS.MAIL
. . .
An activity can contain entries for just the subsystems in a single
program or it can contain entries for subsystems from multiple programs.
An activity can contain at most one entry (and hence specify exactly one
implementation) for a given subsystem.
Activities are most commonly used to tell the Environment which views to
load when you want to execute a program. When used for this purpose, an
activity must contain an entry for each subsystem from which a spec view
has been imported. The entry for each such subsystem must specify a load
view from that subsystem--specifically, a load view that is compatible
with the spec view against which the rest of the program has compiled.
Besides supporting execution, activities are also useful for bookkeeping
purposes--that is, for maintaining a complete list of views that compose
your program. Accordingly, you can specify spec views in subsystem
entries, along with the corresponding load views, so that each entry maps
a subsystem to a specific spec/load-view pair. Likewise, you can create
entries for the subsystems from which combined views have been imported,
mapping each of these subsystems to a specific combined view.
Listing spec views and combined views in an activity has many advantages,
even though this information is ignored during execution:
* An activity containing a complete list of views provides a complete
picture of a particular version of a program and is therefore useful
for record-keeping.
* You can use a complete activity as an indirect file, which you can
specify to Environment commands that operate on sets of views.
* Other Environment facilities consult activities when they need to
choose a particular view from one or more subsystems for some aspect of
their operation (see "Setting Activities to Control Command Operation,"
below).
Setting Activities to Control Program Execution
To make a particular activity available for the Environment to use when
loading a program for execution, you set it as your session default
activity. The session default activity is a component of your session
response profile; the Environment consults this activity when it needs to
find load views to execute a program. You set the session default activity
by using the Activity.Set_Default command or by editing your
Profile.Activity_File session switch.
Although any activity can be set as the session default activity, it is
common practice to use a general-purpose activity that contains:
* Entries for the subsystems in Environment tools and layered products
* Entries for the subsystems in your own and other user-defined programs
that you use frequently
A general-purpose activity can contain all of these entries directly, or
it can contain pointers to entries in other, special-purpose activities.
(See "Modes for Creating Activity Entries," below.) The standard
Environment activity is called !Machine.Current.Release.Activity, and it
contains entries for subsystems in Environment tools and layered products.
Executing a Different Version of a Program
When you want to execute a different version of your program (that is, you
want to load and execute a different set of load views), you can
accomplish this with either of two strategies:
* You can set a different activity to be the session default (either by
editing the Profile.Activity_File session switch or by entering the
Activity.Set_Default command as a separate job from the program you
want to execute). However, if you do this, you must ensure that the new
session default activity contains all the entries required for
Environment tools in addition to the entries needed for your own
program.
* You can keep the same session default activity and simply edit it so
that the appropriate entries reference the desired views (see
Activity.Edit and Activity.Change commands). If the entries in question
are pointers to entries in another activity, you can edit the
appropriate entries in that activity. Edits made to the session default
activity take effect as soon as you save them.
Setting Activities to Control Command Operation
The Environment consults activities for reasons other than program
execution. In particular, Environment commands consult an activity when
they need to:
* Interpret naming expressions containing the 'Spec_View or 'View
attribute following a subsystem name. These attributes expand to the
appropriate kind of view listed for the subsystem in the consulted
activity. For example, the expression My_Subsystem'View.Units resolves
to the Units directory in the load or combined view listed for
My_Subsystem.
* Pre-link, traverse, or otherwise operate on programs written in
subsystems. For example:
- When you use Compilation.Make command to code a program containing
pragma Main, the command consults an activity in order to pre-link
the main program (that is, to verify the program's closure, compute
its elaboration order, and generate the elaboration code).
- When you use the Common.Definition command to traverse from a unit
in a spec view to its counterpart in a load view, the command
consults an activity to determine the appropriate load view.
When a command consults an activity for name resolution or for some other
aspect of its operation, it consults the current activity for the job in
which it is running. (A job is one or more commands executed together.)
Every job has a current activity; it is a component of the job response
profile for the job.
When a job starts, its current activity is initially the same as the
session default activity. For most purposes, the activity you use for
program execution is usually the activity you want for name resolution and
other command operations involving subsystems.
If you want to reference a set of views other than those used for
execution, you can use the Activity.Set command to either set the job's
current activity when you start the job or change the current activity
while the job runs.
For example, assume that:
* You want to code two different main programs (programs containing
pragma Main), each of which reference units that reside in views
* The views in the closure of Main_1 are listed in Activity_1
* The views in the closure of Main_2 are listed in Activity_2
You can execute the following commands from a single command window to
code both main programs as part of a single job:
Activity.Set ("Activity_1");
Comp.Make ("Main_1");
Activity.Set ("Activity_2");
Comp.Make ("Main_2");
Note that setting the current activity has no effect on the session
default activity or on other jobs that may be running at the same time.
For jobs such as the previous example, setting the current activity is
more convenient than changing the session default before the job and then
changing it back afterward.
For more information about jobs and job profiles, see the Session and Job
Management (SJM) book of the Rational Environment Reference Manual.
For more information about main programs, see the Library Management (LM)
book of the Rational Environment Reference Manual.
Modes for Creating Activity Entries
When creating a new activity, or adding new entries to an existing
activity, you can always create the new entries "from scratch" (for
example, use the Activity.Add command and type the appropriate view
names). Another common way to create new entries is to obtain them from
other activities. The Activity.Add, Activity.Create, and Activity.Merge
commands all allow you to derive new entries from entries in a source
activity.
When you derive entries from another activity, you can choose one of the
following three modes for deriving them:
* Differential mode: When an activity entry is created in differential
mode, the entry indirectly references the corresponding entry in the
source activity.
For example, assume you are editing an activity called New_Activity and
you use Activity.Add to create an entry for
!Programs.Mail.Mail_Utilities. Assume also that you create this entry
in differential mode from a source activity called Old_Activity. The
new entry looks like this:
Subsystem | Spec View | Load View | Context
-------------------------------------------------------------------
. . .
MAIL_UTILITIES | | (OLD_ACTIVITY)=> REV1_0_1 |
!PROGRAMS.MAIL
. . .
Note that if you change the entry for Mail_Utilities in Old_Activity,
this change will automatically be reflected in New_Activity.
* Exact_Copy mode: When an activity entry is created in exact-copy mode,
the entry is simply copied from the source activity. If the source
entry contains a view name, the new entry contains that view name. If
the source entry contains an indirect (differential) reference, the new
entry contains the same indirect reference.
* Value_Copy mode: When an activity entry is created in value-copy mode,
the entry is formed as the dereferenced value of the corresponding
source entry. That is, if the source entry contains an indirect
(differential) reference, the new entry contains the view name that
results from dereferencing the source entry.
Differential entries are especially useful because they allow you to
construct a single general-purpose activity that points to any number of
special-purpose activities. The special-purpose activities can be
maintained separately; any changes you make to their entries are
automatically reflected in any differential entries that reference them.
EDITING ACTIVITY FILES
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 COMMON FOR EDITING ACTIVITY FILES
The commands from package !Commands.Common in Table 1 are supported for
editing activity files. Commands from package Common typically are used
through the key combinations to which they are bound. For further
information about these commands, see the Editing Specific Types (EST)
book, package Common.
Table 1 Commands from Package Common for Editing Activity Files
---------------------------------------------------------------
| | |
|Key Bound To ..|Accomplishes ... |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|Common.Commit |Makes permanent any changes made to the |
| |activity. |
---------------------------------------------------------------
| | |
|Common.Create_ |Creates a command window below the current |
|Command |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. |
---------------------------------------------------------------
| | |
|Common. |Finds the definition of the subsystem |
|Definition |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. |
---------------------------------------------------------------
| | |
|Common.Edit |Creates a command window and places in it the |
| |following command, where the parameter prompts |
| |contain the names of the spec view and load |
| |view from the entry containing the cursor: |
| | |
| | Change (Spec_View => "spec view name", |
| | Load_View => "load view name"); |
| | |
| |You can change the values for one or both |
| |parameters, as desired. |
| | |
| |Spec- or load-view entries also can be |
| |specified indirectly through another activity. |
| |You can specify the name of an activity rather |
| |than the name of an actual view to indicate |
| |that the name of the desired view should be |
| |derived from the subsystem's corresponding |
| |entry in the specified activity. |
---------------------------------------------------------------
| | |
|Common.Release |Makes any changes to the activity permanent, |
| |releases control of (unlocks) the activity, and|
| |then destroys the window. |
---------------------------------------------------------------
| | |
|Common.Sort_ |Sorts the activity image according to the |
|Image |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 |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the entry in the activity on which the |
|Child |cursor currently resides. If an entry is |
| |already selected, this command has no effect. |
---------------------------------------------------------------
| | |
|Common.Object. |Deletes the selected entry or the entry on |
|Delete |which the cursor resides. |
---------------------------------------------------------------
| | |
|Common.Object. |Controls the level of detail displayed in the |
|Elide |image of the currentactivity. Successive uses |
| |display successively less information about the|
| |activity entries, proceeding from top to bottom|
| |in the following list: |
| |* All data by subsystem |
| |* Load data by subsystem (indirections are |
| | identified) |
| |* Spec data by subsystem (indirections are |
| | identified) |
| |* Both views by subsystem |
| |* Load views by subsystem (indirections are |
| | not identified) |
| |* Spec views by subsystem (indirections are |
| | not identified) |
| |* Subsystems by subsystem |
---------------------------------------------------------------
| | |
|Common.Object. |Controls the level of detail displayed in the |
|Expand |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. |
---------------------------------------------------------------
| | |
|Common.Object. |Uncompresses a subsystem entry, separating each|
|Explain |component (subsystem name, spec view, and load |
| |view) of the entry onto separate lines. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the first entry of the activity. |
|First_Child | |
---------------------------------------------------------------
| | |
|Common.Object. |Inserts a new activity entry or modifies an |
|Insert |existing one. When the cursor is in the |
| |activity without a selection, this procedure |
| |prompts you to insert a new entry by creating a|
| |command window containing the following |
| |command: |
| | |
| | Insert (Subsystem => "", |
| | Spec_View => "", |
| | Load_View => ""); |
| | |
| |When an existing activity entry is selected, |
| |this procedure displays the same command with |
| |its parameter prompts filled in with names from|
| |the selected entry. |
| | |
| |You can change any or all parameter values, as |
| |desired. You may omit the subsystem name, |
| |allowing it to 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. |
| |You can specify the name of an activity rather |
| |than the name of an actual view to indicate |
| |that the name of the desired view should be |
| |derived from the subsystem's corresponding |
| |entry in the specified activity. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the last entry of the activity. |
|Last_Child | |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the next entry in the activity if an |
|Next |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. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the entry in the activity on which the |
|Parent |cursor currently resides. If an entry is |
| |already selected, the procedure selects all |
| |entries in the activity. Otherwise, the |
| |procedure has no effect. |
---------------------------------------------------------------
| | |
|Common.Object. |Selects the previous entry in the activity if |
|Previous |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;
DESCRIPTION
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>");
DESCRIPTION
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.
PARAMETERS
Subsystem : Subsystem_Name := "<CURSOR>";
Specifies the subsystem name for the new or updated entry. This name is
resolved in the current library. The default is the subsystem name on
which the cursor is located.
Load_Value : View_Or_Activity_Name := Activity.Nil;
Specifies either the name of a load view within the specified subsystem, or
the name of an activity from which the load view can be derived (based on
the Mode parameter).
You can specify a simple load view name, because it is resolved within the
context of the specified subsystem.
The default is the empty activity, indicating no load-view component.
Spec_Value : View_Or_Activity_Name := Activity.Nil;
Specifies either the name of a spec view within the specified subsystem or
the name of the source activity from which the spec view can be derived
(based on the Mode parameter).
You can specify a simple spec view name, because it is resolved within the
context of the specified subsystem.
The default is the empty activity, indicating no spec-view component.
The_Activity : Activity_Name := Activity.The_Current_Activity;
Specifies the activity to which the new entry will be added. The default is
the current activity (the activity associated with the current job, which
is initialized by the session default activity).
Mode : Creation_Mode := Activity.Exact_Copy;
Specifies the mode by which the new entry is derived if either the
Spec_Value or the Load_Value parameter specifies an activity name instead
of a view name.
Set the Mode parameter to Activity.Differential if you want the new entry
to be an indirect reference to the corresponding entry in the source
activity. All subsequent changes to the source entry will then be
automatically reflected in the new activity.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
EXAMPLES
Add (Subsystem_Name => "User_Interface",
Load_Value => "Rev1_0_4",
Spec_Value => "Rev1_0_Spec",
The_Activity => "!Application_Name.Current_Release");
REFERENCES
type Creation_Mode
@node !Commands.Activity.Change
procedure Change (Spec_View : View_Or_Activity_Name := "";
Load_View : View_Or_Activity_Name := "");
DESCRIPTION
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 you with this command. This
command is meaningful only in a command window associated with an
activity.
PARAMETERS
Spec_View : View_Or_Activity_Name := "";
Specifies the name of the desired spec view or the name of an activity that
references the desired spec view.
If you specify an activity name, this command updates the spec view
portion of the entry in differential mode (as an indirect pointer to the
corresponding entry in the specified activity.)
If you specify a simple name, it is resolved relative to the subsystem
whose entry is being changed. If you specify a naming expression beginning
with the context characters $, $$,or ^, this expression is resolved
relative to the current library (the library containing the activity you
are editing).
The default value causes the spec view portion of the entry to remain
unchanged.
Load_View : View_Or_Activity_Name := "";
Specifies the name of the desired load view or the name of an activity that
references the desired load view.
If you specify an activity name, this command updates the load view
portion of the entry in differential mode (as an indirect pointer to the
corresponding entry in the specified activity.)
If you specify a simple name, it is resolved relative to the subsystem
whose entry is being changed. If you specify a naming expression beginning
with the context characters $, $$,or ^, this expression is resolved
relative to the current library (the library containing the activity you
are editing).
The default value causes the load view portion of the entry to remain
unchanged.
EXAMPLES
The following command changes only the load-view component of the
designated entry to Rev1_0_7:
Change (Load_View => "Rev1_0_7");
The following command changes only the spec-view component of the
designated entry to Rev1_1_Spec:
Change (Spec_View => "Rev1_1_Spec");
The following command changes both spec- and load-view components of the
designated entry:
Change (Spec_View => "Rev1_0_Spec", Load_View => "Rev1_0_7");
The following command changes the spec-view component in the designated
entry to be the spec view used in the corresponding entry in the named
activity:
Change (Spec_View => "Some_Activity_Name");
REFERENCES
Editing Specific Types (EST), procedure Common.Edit
@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>");
DESCRIPTION
Creates a new activity.
The created activity may be derived from the source activity based on the
Mode parameter.
PARAMETERS
The_Activity : Activity_Name := >>ACTIVITY NAME<<;
Specifies the name of the new activity. The default parameter placeholder
">>ACTIVITY NAME<<" must be replaced or an error will result.
Source : Activity_Name := Activity.Nil;
Specifies the name of the source activity from which the new activity is to
be created. The default is an empty activity.
Mode : Creation_Mode := Activity.Exact_Copy;
Specifies the mode by which the entries are derived from the source
activity.
Set the Mode parameter to Activity.Differential if you want the new
entries to be indirect references to the corresponding entries in the
source activity. All subsequent changes to the source entry will then be
automatically reflected in the new activity.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
EXAMPLES
The following command creates a new activity with indirect entries for all
subsystems in the source activity !Machine.Release.Current.Activity:
Create (Activity => "My_Private_Activity",
Source => "!Machine.Release.Current.Activity",
Mode => Activity.Differential);
REFERENCES
type Creation_Mode
@node !Commands.Activity.Creation_Mode
type Creation_Mode is (Differential, Exact_Copy, Value_Copy);
DESCRIPTION
Defines three modes for the creation of spec-view and load-view references
for subsystem entries.
Commands such as Activity.Add, Activity.Create, and Activity.Merge allow
you to create new activities (or add new entries to an existing activity)
by deriving the new entries from other source activities. When you derive
entries from another activity, you can choose one of the three creation
modes for deriving them.
ENUMERATIONS
Differential
Indicates that the new entry is to be formed as an indirect reference to
the source activity. The new entry is essentially a pointer to the
corresponding entry in the source activity. Note that the source entry can
itself be a differential entry that references an entry in yet another
view. Changes made to a source entry will be reflected in any differential
entry that references it.
For example, assume you are editing an activity called New_Activity and
you use Activity.Add to create an entry for !Programs.Mail.Mail_Utilities.
Assume also that you create this entry in differential mode from a source
activity called Old_Activity. The new entry looks like this:
Subsystem | Spec View | Load View | Context
__________________________________________________________________
. . .
MAIL_UTILITIES | | (OLD_ACTIVITY)=> REV1_0_1 |
!PROGRAMS.MAIL
. . .
Note that if you change the entry for Mail_Utilities in Old_Activity, this
change will automatically be reflected in New_Activity.
Differential entries are especially useful because they allow you to
construct a single general-purpose activity that points to any number of
special-purpose activities. The special-purpose activities can be
maintained separately; any changes you make to their entries are
automatically reflected in any differential entries that reference them.
Exact_Copy
Indicates that the new entry is to be formed as an exact copy of the entry
in the source activity. If the source entry contains a view name, the new
entry contains that view name. If the source entry contains an indirect
(differential) reference, the new entry contains the same indirect
reference.
Value_Copy
Indicates that the new entry is to be formed as the dereferenced value of
the corresponding source entry. That is, if the source entry contains an
indirect (differential) reference, that entry is dereferenced until an
actual view name is obtained. The new entry is then formed with the
resulting view name.
@node !Commands.Activity.Current
procedure Current (Response : String := "<PROFILE>");
DESCRIPTION
Displays the name of the current activity (the activity that is associated
with the currently executing job).
Note that if no activity has been explicitly associated with the job via
the Set procedure, the current activity is taken from the session default
activity.
For more information about current activities and session default
activities, see "Key Concepts for Package Activity" in the introduction to
this package.
PARAMETERS
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Set
procedure Set_Default
@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>");
DESCRIPTION
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.
PARAMETERS
Subsystem : Subsystem_Name := "?";
Specifies the name of the subsystem entry to be displayed. The default
indicates that all subsystem entries should be displayed.
Spec_View : View_Name := "?";
Specifies a pattern for spec-view entries. Only patterns that match are
displayed. The default indicates that all spec views are acceptable.
Load_View : View_Name := "?";
Specifies a pattern for load-view entries. Only patterns that match are
displayed. The default indicates that all load views are acceptable.
Mode : Creation_Mode := Activity.Value_Copy;
Specifies the mode by which the image of each entry shall be derived from
the activity.
The_Activity : Activity_Name := Activity.The_Current_Activity;
Specifies the name of the activity to be displayed. The default is the
current activity (the activity associated with the current job, which is
initialized by the session default activity).
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
function The_Current_Activity
@node !Commands.Activity.Edit
procedure Edit (The_Activity : Activity_Name := "<ACTIVITY>");
DESCRIPTION
Invokes the activity object editor on the specified activity.
The default is to edit the current activity.
PARAMETERS
The_Activity : Activity_Name := "<ACTIVITY>";
Specifies the name of the activity to be edited.
The default value resolves to the selected activity, if any; otherwise it
resolves to the current activity (the activity associated with the current
job, which is initialized by the session default activity).
@node !Commands.Activity.Enclosing_Subsystem
procedure Enclosing_Subsystem
(View : View_Name := "<IMAGE>";
Response : String := "<PROFILE>");
DESCRIPTION
Displays the name of the subsystem that contains the specified view. The
view may be either a spec or a load view.
PARAMETERS
View : View_Name := "<IMAGE>";
Specifies the name of the view whose enclosing subsystem is desired. When
the default value is used, the current selection or image must resolve to
a view.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Activity.Enclosing_View
procedure Enclosing_View (Unit : Unit_Name := "<IMAGE>";
Response : String := "<PROFILE>");
DESCRIPTION
Displays the name of the view that contains the specified unit.
The default is the currently selected unit or unit image.
PARAMETERS
Unit : Unit_Name := "<IMAGE>";
Specifies the name of the unit for which the enclosing view is desired. The
default is the currently selected unit or unit image.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Activity.Insert
procedure Insert
(Subsystem : Subsystem_Name := ">>SUBSYSTEM NAME<<";
Spec_View : View_Or_Activity_Name := "";
Load_View : View_Or_Activity_Name := "");
DESCRIPTION
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.
PARAMETERS
Subsystem : Subsystem_Name := ">>SUBSYSTEM NAME<<";
Specifies the name of the subsystem for which an entry is to be created or
modified. This name is resolved relative to the current library (the
library containing the activity you are editing).
The default parameter placeholder ">>SUBSYSTEM NAME<<" must be replaced or
an error will result.
Spec_View : View_Or_Activity_Name := "";
Specifies the name of the desired spec view or the name of an activity that
references the desired spec view.
If you specify an activity name, this command creates/updates the spec
view portion of the entry in differential mode (as an indirect pointer to
the corresponding entry in the specified activity.)
If you specify a simple name, it is resolved relative to the specified
subsystem. If you specify a naming expression beginning with the context
characters $, $$,or ^, this expression is resolved relative to the current
library (the library containing the activity you are editing).
The default value causes the spec view portion of the entry to remain
unchanged.
Load_View : View_Or_Activity_Name := "";
Specifies the name of the desired load view or the name of an activity that
references the desired load view.
If you specify an activity name, this command creates/updates the load
view portion of the entry in differential mode (as an indirect pointer to
the corresponding entry in the specified activity.)
If you specify a simple name, it is resolved relative to the specified
subsystem. If you specify a naming expression beginning with the context
characters $, $$,or ^, this expression is resolved relative to the current
library (the library containing the activity you are editing).
The default value causes the load view portion of the entry to remain
unchanged.
EXAMPLES
Example 1
procedure Insert (Subsystem => "User_Interface",
Spec_View => "Rev1_0_Spec",
Load_View => "Rev1_0_5");
Example 2
procedure Insert (Subsystem => "User_Interface",
Spec_View => "",
Load_View => "Current_Release");
where Current_Release is the name of an activity in
!My_Application.User_Interface.
REFERENCES
Editing Specific Types (EST), procedure Common.Object.Insert
@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>");
DESCRIPTION
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.
PARAMETERS
Source : Activity_Name := ">>ACTIVITY NAME<<";
Specifies the name of the activity from which entries are to be copied. The
default parameter placeholder ">>ACTIVITY NAME<<" must be replaced or an
error will result.
Subsystem : Subsystem_Name := "?";
Specifies the subsystem entries to be copied. The default indicates that
all subsystem entries should be copied.
Spec_View : View_Name := "?";
Specifies a pattern for spec-view entries. Only patterns that match are
copied. The default indicates that all spec views are acceptable.
Load_View : View_Name := "?";
Specifies a pattern for load-view entries. Only patterns that match are
copied. The default indicates that all load views are acceptable.
Mode : Creation_Mode := Activity.Exact_Copy;
Specifies the mode by which entries are derived from the source activity.
Set the Mode parameter to Activity.Differential if you want the new
entries to be indirect references to the corresponding entries in the
source activity. All subsequent changes to the source entry will then be
automatically reflected in the new activity.
Target : Activity_Name := "<ACTIVITY>";
Specifies the name of the activity into which the new entries are to be
copied.
The default value resolves to the selected activity, if any; otherwise it
resolves to the current activity (the activity associated with the current
job, which is initialized by the session default activity).
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Activity.Nil
function Nil return Activity_Name;
DESCRIPTION
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>");
DESCRIPTION
Deletes a subsystem entry from the specified activity.
PARAMETERS
Subsystem : Subsystem_Name := "<SELECTION>";
Specifies the name of the subsystem entry to be deleted. The default is the
current selection.
The_Activity : Activity_Name := Activity.The_Current_Activity;
Specifies the name of the activity from which the entry is to be deleted.
The default is the current activity (the activity associated with the
current job, which is initialized by the session default activity).
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Activity.Set
procedure Set (The_Activity : Activity_Name := "<ACTIVITY>";
Response : String := "<PROFILE>");
DESCRIPTION
Sets the current activity to be the specified activity. The current
activity is the activity associated with the currently executing job; it
is a component of the job response profile for the job.
When a job starts, its current activity is initially the same as the
session default activity (see the Set_Default command). You can use the
Set procedure to change the job's current activity without changing the
sessions default activity. The current activity stays in effect until the
job terminates or until it is changed by a subsequent Set command in the
same job. (A job is one or more commands executed together--for example,
promoted in the same command window.)
Changing the current activity within a job affects the operation of
subsequent commands in the same job, if those commands need to:
* Interpret naming expressions containing the 'Spec_View or 'View
attribute following a subsystem name. These attributes expand to the
appropriate kind of view listed for the subsystem in the current
activity. For example, the expression My_Subsystem'View.Units resolves
to the Units directory in the load or combined view listed for
My_Subsystem in the current activity.
* Pre-link, traverse, or otherwise operate on programs written in
subsystems. For example:
- When you use Compilation.Make command to code a program containing
pragma Main, the command consults the current activity in order to
pre-link the main program (that is, to verify the program's closure,
compute its elaboration order, and generate the elaboration code).
- When you use the Common.Definition command to traverse from a unit
in a spec view to its counterpart in a load view, the command
consults the current activity to determine the appropriate load
view.
However, changing the current activity does not affect the loading of
subsequent commands in the same job. (Loading is when the Environment
determines which load views to execute for each command written in
subsystems.) This is because the Environment loads an entire job before
the job begins to execute, and thus before the Set command has a chance to
execute. When loading a job, the Environment consults the session default
activity.
For example, assume that My_Utility is a program written in subsystems, so
that the Environment has to consult an activity to determine which load
views to execute. Assume also that the session default activity is called
Old_Activity.
In the following job, My_Utility is loaded according to Old_Activity
because that is the only activity in effect when the job is initialized.
The Set command has no appreciable effect in this job, because it executes
after My_Utility is loaded:
Activity.Set ("New_Activity");
My_Utility;
In the following job, My_Utility is loaded according to New_Activity
because My_Utility is loaded when the Program.Run command executes (and
not as part of the overall job initialization). The Set command executes
before Program.Run does, so New_Activity is in effect by the time
My_Utility is loaded:
Activity.Set ("New_Activity");
Program.Run ("My_Utility");
For more information about current activities and session default
activities, see "Key Concepts for Package Activity" in the introduction to
this package.
PARAMETERS
The_Activity : Activity_Name := "<ACTIVITY>";
Specifies the activity to be set as the current activity (the activity for
the currently executing job).
The default parameter value resolves to the selected activity, if any;
otherwise it resolves to the current activity.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Set_Default
@node !Commands.Activity.Set_Default
procedure Set_Default
(The_Activity : Activity_Name := "<ACTIVITY>";
Response : String := "<PROFILE>");
DESCRIPTION
Sets the specified activity to be the session default activity. The session
default activity is associated with the current session; it is a component
of the session response profile.
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 preserved across logouts.
For more information about current activities and session default
activities, see "Key Concepts for Package Activity" in the introduction to
this package.
PARAMETERS
The_Activity : Activity_Name := "<ACTIVITY>";
Specifies the activity to be set as the default activity for the current
session.
The default value resolves to the selected activity, if any; otherwise it
resolves to the current activity (the activity associated with the
currently executing job).
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Set
@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>");
DESCRIPTION
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.
PARAMETERS
Load_View : View_Or_Activity_Name := "<CURSOR>";
Specifies the name of the new load-view entry. Name resolution is performed
within the context of the specified subsystem. The default is the load-view
name or activity name on which the cursor is located.
If the Load_View parameter designates a view, that view is associated with
the subsystem that contains it. The value of Load_View must be the simple
name of a load view.
If the Load_View parameter designates an activity, that activity must
contain an entry for the subsystem specified by the Subsystem parameter.
The load view associated with Subsystem in this activity becomes the load
view associated with Subsystem in the activity named by The_Activity.
Subsystem : Subsystem_Name := "";
Specifies the name of the subsystem entry. Name resolution is performed
relative to the current library. The default value ("") resolves to the
current library and therefore can be used only when the current library is
the subsystem that contains the view specified by the Load_View parameter.
Mode : Creation_Mode := Activity.Differential;
Specifies the mode by which the entry is derived if the Load_View parameter
specifies an activity name instead of a view name.
Set the Mode parameter to Activity.Differential if you want the new entry
to be an indirect reference to the corresponding entry in the source
activity. All subsequent changes to the source entry will then be
automatically reflected in the new activity.
The_Activity : Activity_Name := Activity.The_Current_Activity;
Specifies the name of the activity to be modified. The default is the
current activity (the activity associated with the current job, which is
initialized by the session default activity).
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
EXAMPLES
Example 1
Set_Load_View (Load_View => "Rev1_2_4",
Subsystem => "User_Interface",
The_Activity => "Current_Release");
is equivalent to:
Set_Load_View (Load_View => "User_interface.Rev1_2_4",
Subsystem => "",
The_Activity => "Current_Release");
Example 2
Set_Load_View (Load_View => "Working_Activity",
Subsystem => "User_Interface",
Mode => Activity.Value_Copy,
The_Activity => "Current_Release");
This command changes the load view for the User_Interface subsystem in the
Current_Release activity. The command will set the load view to the same
value as that specified for the User_Interface subsystem in
Working_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>");
DESCRIPTION
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.
PARAMETERS
Spec_View : View_Or_Activity_Name := "<CURSOR>";
Specifies the name of the new spec-view entry. Name resolution is performed
within the context of the specified subsystem. The default is the spec-view
name or activity name on which the cursor is located.
If the Spec_View parameter designates a view, that view is associated with
the subsystem that contains it. The value of Spec_View must be the simple
name of a spec view.
If the Spec_View parameter designates an activity, that activity must
contain an entry for the subsystem specified by the Subsystem parameter.
The spec view associated with Subsystem in this activity becomes the spec
view associated with Subsystem in the activity named by The_Activity.
Subsystem : Subsystem_Name := "";
Specifies the name of the subsystem entry. Name resolution is performed
relative to the current library. The default value ("") resolves to the
current library and therefore can be used only when the current context is
the subsystem that contains the view specified by the Spec_View parameter.
Mode : Creation_Mode := Activity.Differential;
Specifies the mode by which the entry is derived if the Spec_View parameter
specifies an activity name instead of a view name.
Set the Mode parameter to Activity.Differential if you want the new entry
to be an indirect reference to the corresponding entry in the source
activity. All subsequent changes to the source entry will then be
automatically reflected in the new activity.
The_Activity : Activity_Name := Activity.The_Current_Activity;
Specifies the name of the activity to be modified. The default is the
current activity (the activity associated with the current job, which is
initialized by the session default activity).
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
EXAMPLES
Example 1
Set_Spec_View (Spec_View => "Rev1_2_Spec",
Subsystem => "User_Interface",
The_Activity => "Current_Release");
is equivalent to:
Set_Spec_View (Spec_View => "User_interface.Rev1_2_Spec",
Subsystem => "",
The_Activity => "Current_Release");
Example 2
Set_Spec_View (Spec_View => "Working_Activity",
Subsystem => "User_Interface",
Mode => Activity.Value_Copy,
The_Activity => "Current_Release");
This command changes the spec view for the User_Interface subsystem in the
Current_Release activity. The command will set the spec view to the same
value as that specified for the User_Interface subsystem in
Working_Activity.
@node !Commands.Activity.Subsystem_Name
subtype Subsystem_Name is String;
DESCRIPTION
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;
DESCRIPTION
Returns the name of the current activity (the activity associated with the
currently executing job). If no activity has been explicitly associated
with the running job (for example, via the Set command), this function
returns the session default activity.
@node !Commands.Activity.The_Enclosing_Subsystem
function The_Enclosing_Subsystem (View : View_Name := "<IMAGE>")
return Subsystem_Name;
DESCRIPTION
Returns the name of the subsystem that contains the specified view. The
view may be either a spec or a load view.
PARAMETERS
View : View_Name := "<IMAGE>";
Specifies the name of the view whose enclosing subsystem is desired. When
the default value is used, the current selection or image must resolve to
a view.
return Subsystem_Name;
Returns the name of the subsystem that contains the specified view.
@node !Commands.Activity.The_Enclosing_View
function The_Enclosing_View (Unit : Unit_Name := "<IMAGE>")
return View_Name;
DESCRIPTION
Returns the name of the view that contains the specified unit.
PARAMETERS
Unit : Unit_Name := "<IMAGE>";
Specifies the name of the unit whose enclosing view is desired. The default
is the currently selected unit or unit 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;
DESCRIPTION
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;
DESCRIPTION
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;
DESCRIPTION
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;
DESCRIPTION
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.
EXAMPLES
Rev1_0_5
Rev2_0_Spec
not:
User_Interface.Rev3_4_7
@node !Commands.Activity.Visit
procedure Visit (The_Activity : Activity_Name := "<ACTIVITY>");
DESCRIPTION
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.
PARAMETERS
The_Activity : Activity_Name := "<ACTIVITY>";
Specifies the name of the activity to be visited.
The default value resolves to the selected activity, if any; otherwise it
resolves to the current activity (the activity associated with the
currently executing job, which is initialized by the session default
activity).
REFERENCES
Editing Specific Types (EST), procedure Common.Edit
@node !Commands.Activity.Write
procedure Write (File : Activity_Name := ">>ACTIVITY<<");
DESCRIPTION
Copies the contents of an activity window into a new activity in the
directory system.
This command is valid only in an activity window.
PARAMETERS
File : Activity_Name := ">>ACTIVITY<<";
Specifies the name of the new activity. The name is resolved relative to
the current library.
The default parameter placeholder ">>ACTIVITY NAME<<" must be replaced or
an error will result.
@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
Reference Manual for the Ada Programming Language, 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;
DESCRIPTION
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.
PARAMETERS
The_Activity : String := "<ACTIVITY>";
Specifies the name of the activity whose spec-view and load-view pairs
should be checked for compatibility.
Menu : Boolean := False;
Specifies whether to display a menu output. This parameter applies only to
the procedure interface.
If True, any incompatible units will be reported in a menu image instead
of in messages in a log file. Traversing to a spec-view unit from this menu
displays the unit with the incompatible declarations underlined. You can
also change the elision level of the menu to display these declarations.
When this parameter is True, no log file is produced unless there are
errors in the command's execution.
If False, a log file is produced as specified by the Response parameter.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Tools.Compatibility.Revn.Units.Check.Code_Views
procedure Code_Views (Code_Views : String := "<CURSOR>";
Response : String := "<PROFILE>");
function Code_Views (Code_Views : String := "<CURSOR>";
Response : String := "<PROFILE>") return Status;
DESCRIPTION
Checks each of the specified code views to verify that every spec view
unit referenced when the code view was created still exists and still
exports the entities used by the code view.
The results of checking code view compatibility are reported in an
Environment output window.
PARAMETERS
Code_Views : String := "<CURSOR>";
Specifies one or more code views to check. Multiple views can be specified
by using wildcards, context characters, special names, set notation, or an
indirect file.
You can specify a naming expression that resolves to any type of view.
However, views other than code views are ignored.
You can specify an activity name, in which case all code views referenced
by the activity are checked.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Tools.Compatibility.Revn.Units.Check.Status
type Status is (Compatible, Incompatible, Error);
DESCRIPTION
Defines the range of possible outcomes of a compatibility check.
ENUMERATIONS
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;
DESCRIPTION
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.
PARAMETERS
Load_View_Units : String := "<CURSOR>";
Specifies one or more units in load views to be checked. Multiple units can
be specified by using wildcards, context characters, set notation, or an
indirect file. (For further information, see "Naming" in the Key Concepts
section of this book.)
Spec_Views : String := "<ACTIVITY>";
Specifies one or more spec views to be used to perform the check. Multiple
views can be specified by using wildcards, context characters, special
names, set notation, or an indirect file. (For further information, see
"Naming" in the Key Concepts section of this book.) Furthermore,
Spec_Views can name an activity as an indirect file, which is equivalent to
naming the spec view associated with each subsystem listed in the
activity.
Menu : Boolean := False;
Specifies whether to display a menu output. This parameter applies only to
the procedure interface.
If True, any incompatible units will be reported in a menu image instead
of in messages in a log file. Traversing to a spec-view unit from this menu
displays the unit with the incompatible declarations underlined. You can
also change the elision level of the menu to display these declarations.
When this parameter is True, no log file is produced unless there are
errors in the command's execution.
If False, a log file is produced as specified by the Response parameter.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
The naming expressions for the Spec_Views parameter must resolve to
subsystem views or an activity and must not specify multiple spec views
from the same subsystem. The naming expressions for the Load_View_Units
parameter must resolve to compilation units. Spec_Views must specify a
spec view for each subsystem that contains one or more of the units
specified by Load_View_Units.
EXAMPLES
In a command window off a window displaying a unit in a working view of a
subsystem, the command:
Check.Units (Load_View_Units => "<CURSOR>",
Spec_Views => "<ACTIVITY>");
will check compatibility of the unit in the working view with the unit in
the spec view as specified in the user's default activity. Using the
default values for the Menu and Response parameters will result in log file
output.
@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;
DESCRIPTION
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.
PARAMETERS
Load_Views : String := "<CURSOR>";
Specifies one or more load views to be checked. Multiple views can be
specified by using wildcards, context characters, special names, set
notation, or an indirect file. (For further information, see "Naming" in
the Key Concepts section of this book.) Furthermore, Load_Views can name
an activity as an indirect file, which is equivalent to naming the load
view associated with each subsystem listed in the activity.
Spec_Views : String := "<ACTIVITY>";
Specifies the spec views used to perform the check. Multiple views can be
specified by using wildcards, context characters, special names, set
notation, or an indirect file. (For further information, see "Naming" in
the Key Concepts section of this book.) Furthermore, Spec_Views can name
an activity as an indirect file, which is equivalent to naming the spec
view associated with each subsystem listed in the activity.
Menu : Boolean := False;
Specifies whether to display a menu output. This parameter applies only to
the procedure interface.
If True, any incompatible units will be reported in a menu image instead
of in messages in a log file. Traversing to a spec-view unit from this menu
displays the unit with the incompatible declarations underlined. You can
also change the elision level of the menu to display these declarations.
When this parameter is True, no log file is produced unless there are
errors in the command's execution.
If False, a log file is produced as specified by the Response parameter.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
The naming expressions for the Spec_Views and Load_Views parameters must
resolve to subsystem views or an activity. The Spec_Views parameter should
not specify multiple spec views of the same subsystem, and it should
specify a spec view for each subsystem that contains one or more of the
views specified by the Load_Views parameter. Combined views named by these
parameters are not considered for checking.
EXAMPLES
In a command window off a window displaying the Rev1_Working view of
My_Subsystem, the command:
Check.Views (Load_Views => "<CURSOR>",
Spec_Views => "<ACTIVITY>");
will check compatibility of units in the spec view for My_Subsystem, as
specified by the user's default activity, with the units in Rev1_Working.
Using the default values for the Menu and Response parameters will result
in log file output.
@node !Commands.Cmvc
Package Cmvc defines a set of operations that support the following
activities of project management:
* Partitioning projects into components using subsystems and managing the
interfaces among these components
* Creating and releasing alternative implementations (views) of
individual project components
* Placing the objects within project components under source control to
record generations of change history and to coordinate the work of
multiple developers
* 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:
* A list of CMVC commands grouped by topic
* A summary of the types of objects you can create and manage through
CMVC commands
* A guide to the images and operations for managing configuration
information interactively
* A list of switches and commands from package Common that pertain to
CMVC
RESOURCES IN PACKAGE CMVC
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.)
* Interactively viewing notes and configuration information:
Def Edit Notes
* Creating and destroying subsystems and systems:
Initial Destroy_Subsystem Destroy_System
* Creating, releasing, destroying, and recreating views:
Build Initial Make_Spec_View
Copy Make_Code_View Make_Subpath
Destroy_View Make_Path Release
* Managing source control:
Abandon_Reservation Check_Out Make_Uncontrolled
Accept_Changes Join Merge_Changes
Check_In Make_Controlled Revert
* Managing subsystem interfaces:
Import Remove_Unused_Imports
Imported_Views Replace_Model
Remove_Import
* Displaying reports in I/O windows:
Information Show_All_Uncontrolled Show_History_By_Generation
Show Show_Checked_Out_By_User Show_Image_Of_Generation
Show_All_Checked_Out Show_Checked_Out_In-View Show_Out_Of_Date
Show_All_Controlled Show_History
* Managing notes:
Append_Notes Create_Empty_Note_Window Get_Notes
Put_Notes
USING CMVC COMMANDS WITH RCI
You can use many of the commands in package Cmvc to manage remote
libraries during development with the Rational Compilation Integrator
(RCI). Each of the relevant Cmvc commands has a a section called "RCI
Behavior" that explains its usage with RCI.
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:
* 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.
* 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:
* A load view contains an implementation of a subsystem. Load views are
specified in activities and are actually used for execution.
* 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.
* 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:
* Which objects are controlled?
* Which objects are checked out and to which views?
* Which objects are joined to objects in other views?
* Which views contain the other objects in the join set?
* 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:
* View images of past generations for the object.
* View the line-by-line differences between two successive generations.
* Find out when a given generation was created.
* Keep a scratchpad of notes recording the changes that were made to each
generation.
* 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 1 shows the configuration image displayed for the view
!Programs.Mail.Mail_Utilities.
!Programs.Mail.Mail_Utilities.Configurations.Rev1_Working
Exports
Subset_1'G(2)
Units
Destinations'G(3)
Destinations'G(4/5)
Lines'G(2)
Lines'G(4)
Messages'G(1/2)
Messages'G(9)
Symbolic_Display'G(1)
Symbolic_Display'G(2)
To_Do'G(8)
Unbounded'G(1)
Figure 1 The First Level of Information in a Configuration Image
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 2.
!Programs.Mail.Mail_Utilities.Configurations.Rev1_Working
Exports : Lib
Subset_1'G(2) : In 91/05/11 16:50:07 ANDERSO
Units : Lib
Destinations'G(3) : In 91/05/11 16:32:48 ANDERSO
Destinations'G(4/5) : * In 91/05/11 16:33:25 ANDERSO
Lines'G(2) : In 92/02/23 11:42:01 ANDERSO
Lines'G(4) : In 92/02/23 11:41:51 ANDERSO
Messages'G(1/2) : * In 92/02/25 10:42:15 ANDERSO
Messages'G(9) : In 92/02/23 11:44:16 ANDERSO
Symbolic_Display'G(1) : In 92/02/23 10:57:31 ANDERSO
Symbolic_Display'G(3) : Out 92/04/20 19:41:59 ANDERSO
*current_view*
To_Do'G(8) : In 92/03/30 11:57:08 ANDERSO
Unbounded'G(1) : In 92/02/23 10:57:32 ANDERSO
Figure 2 The Second Level of Information in a Configuration Image
Each entry in this expanded configuration image contains the following
additional information (from left to right):
* An asterisk indicating whether the object is out of date in the view
* An indication of whether the unit is currently checked out (Out) or
checked in (In); libraries are indicated as Lib
* 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)
* The user who performed the last checkout or checkin
* 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 Figure 3. Each entry now displays the reservation
token associated with each controlled object in the view.
!Programs.Mail.Mail_Utilities.Configurations.Rev1_Working
Exports :
Subset_1'G(2) : REV1
Units :
Destinations'G(3) : REV1
Destinations'G(4/5) : REV1
Lines'G(2) : REV1
Lines'G(4) : REV1
Messages'G(1/2) : REV1
Messages'G(9) : REV1
Symbolic_Display'G(1) : REV1
Symbolic_Display'G(2) : REV1
To_Do'G(8) : REV1
Unbounded'G(1) : REV1
Figure 3 The Third Level of Information in a Configuration Image
Finally, using Common.Expand again displays a fourth level of configuration
information, as shown in Figure 4. At this level, the entry for a given
joined object displays the views containing other objects in the join set.
!Programs.Mail.Mail_Utilities.Configurations.Rev1_Working
Exports :
Subset_1'G(2) : REV1 => Rev1_Working
Units :
Destinations'G(3) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Destinations'G(4/5) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Lines'G(2) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Lines'G(4) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Messages'G(1/2) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Messages'G(9) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Symbolic_Display'G(1) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Symbolic_Display'G(2) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
To_Do'G(8) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Unbounded'G(1) : REV1 => Rev1_Sue_Working Rev1_Larry_Working
Rev1_Wor
Figure 4 The Fourth Level of Information in a Configuration Image
Operations in Configuration Images
At any level of expansion, a configuration image provides a convenient way
to perform the following CMVC operations:
* Check objects in, using the Common.Promote command
* Check objects out, using the Common.Demote command
* Accept changes on objects, using the Common.Complete command
* Access generation and history images, using the Common.Definition and
Common.Explain commands, respectively
* Traverse to the designated object in the associated view, using the
Cmvc.Def command
A complete list of such operations is given in "Commands from Package
!Commands.Common," below.
You can also perform other Environment operations (such as compilation )
from a configuration image. To do so, you use Environment commands with a
special name such as "<CURSOR>" and then designate the desired object in
the configuration image.
For example, assume you are looking at a configuration image that has an
entry for a unit you want to compile. To compile this unit, you can put
the cursor on its entry and enter the following command from a command
window under a configuration image:
Compilation.Make ("<CURSOR>");
This only works in configuration images that are associated with an
existing view.
Restricting Operations in Configuration Images
CMVC 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:
* Within the Configurations directory in a subsystem, put the cursor on
the name of a configuration object and enter the Common.Definition
command.
* 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:
* 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.
* 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 5 shows the result of using
Common.Expand in the generation image for generation 4 of
Destinations'Body.
|with System_Utilities;
|with String_Utilities;
|
|package body Destinations is
|
| procedure Define (New_User : String) is
| begin
| [statement]
| end Define;
|
| function Image (The_User : User) return String is
| begin
-| return Unbounded.Image (Unbounded.Variable_String (The_User));
+| return (Unbounded.Image (Unbounded.Variable_String
+| (The_User.User_Names)));
| end Image;
|
Figure 5 Differences between Generations 3 and 4 of Destinations'Body
Differences are shown on a line-by-line basis:
* A line beginning with the minus sign (-) indicates that the line was
deleted from the previous generation.
* A line beginning with the plus sign (+) indicates that the line was
added to the previous generation.
* 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 6 shows the history image for generation 4
of Destinations'Body.
History for Units.Destinations'Body
Checked-out on 91/05/20 19:41:59 by ANDERSON
Checked-in on 91/05/24 14:58:46 by ANDERSON
Notes for Generation 4
CHECK_OUT: Changing return statement in function Image
CHECK_IN: Change has been tested
-- Notes from 91/05/24 15:06:19 by ANDERSON --
Still need to implement procedure Define.
--
Figure 6 The History Image for Generation 4 of Destinations'Body
The history image for a generation of an object contains:
* The history for the generation, which lists the time of checkout and
checkin and the user who performed these operations
* 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 7 (see hardcopy document), 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 8 (see hardcopy document) 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 COMMON FOR TRAVERSING CMVC OBJECTS
Table 1 Commands from Package Common in Configuration Images
---------------------------------------------------------------
| | |
|Key Bound To ..|Accomplishes ... |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|Common. |Displays the generation image for the current |
|Definition |generation of the object whose entry is |
| |designated in a configuration image. An |
| |In_Place parameter specifies whether the |
| |current frame should be used. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|Common. |Displays the subsystem that contains the |
|Enclosing |configuration represented in the configuration |
| |image. An In_Place parameter specifies whether |
| |the current frame should be used. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|Common.Revert |Updates the configuration image with current |
| |information from the CMVC database. Note that |
| |the configuration image is automatically update|
| |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. |
---------------------------------------------------------------
Table 2 Commands from Package Common in Generation Images
---------------------------------------------------------------
| | |
|Key Bound To ..|Accomplishes ... |
---------------------------------------------------------------
| | |
|Common. |Displays the controlled object associated with |
|Definition |the generation in the generation image |
| |containing the cursor. An In_Place parameter |
| |specifies whether the current frame should be |
| |used. |
---------------------------------------------------------------
| | |
|Common.Elide |Removes from the generation image the |
| |differences that were displayed by the |
| |Common.Expand command. |
---------------------------------------------------------------
| | |
|Common. |Displays the configuration image for the last |
|Enclosing |configuration that was visited. An In_Place |
| |parameter specifies whether the current frame |
| |should be used. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|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.|
---------------------------------------------------------------
| | |
|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.|
---------------------------------------------------------------
Table 3 Commands from Package Common in History Images
---------------------------------------------------------------
| | |
|Key Bound To ..|Accomplishes ... |
---------------------------------------------------------------
| | |
|Common.Commit |Saves the new notes entered through the prompt |
| |given by the Common.Edit command. |
---------------------------------------------------------------
| | |
|Common. |Displays the controlled object associated with |
|Definition |the generation for which history is displayed. |
| |An In_Place parameter specifies whether the |
| |current frame should be used. |
---------------------------------------------------------------
| | |
|Common.Edit |Provides a prompt in the current history image |
| |in which new notes can be entered. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|Common. |Displays the generation image for the |
|Enclosing |generation associated with the current history |
| |image. An In_Place parameter specifies whether |
| |the current frame should be used. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|Common.Format |Updates the history image with current |
| |information from the CMVC database. |
---------------------------------------------------------------
| | |
|Common.Promote |Saves the new notes entered through the prompt |
| |given by the Common.Edit command. |
---------------------------------------------------------------
| | |
|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. |
---------------------------------------------------------------
| | |
|Common.Revert |Updates the history image with current |
| |information from the CMVC database. |
---------------------------------------------------------------
| | |
|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>");
DESCRIPTION
Abandons the reservation on one or more checked-out objects, effectively
canceling the checkout of those objects.
If source is being saved for the checked-out object, any changes made
during the abandoned checkout are discarded. (If source is not being
saved, then changes are retained, even though the checkout is abandoned.)
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.
RCI Behavior
For RCI secondary text files, if the file that is being abandoned is a
secondary text file, then the primary associated with the file is demoted.
The secondary text is unfrozen.
PARAMETERS
What_Object : String := "<SELECTION>";
Specifies the object or objects whose reservations are to be abandoned.
Objects that are not checked out are ignored. The default is the currently
selected object. View names cannot be specified.
Multiple objects must be in the same view. Multiple objects can be
specified by using wildcards, context characters, special names, set
notation, or an indirect file.
Allow_Demotion : Boolean := False;
Specifies whether the Abandon_Reservation procedure is allowed to demote
Ada units in the process of reverting units to the last checked-in
generation.
If the Allow_Demotion parameter is True, the Abandon_Reservation procedure
is permitted to demote Ada units if necessary. If this parameter is False,
the command can proceed only if no demotion is required; otherwise, an
error is reported and the command quits.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted in the process
of reverting units to the last checked-in generation.
If True (the default value), demoted units are recompiled to the state
specified by the Goal parameter. If False, units remain demoted.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The goal can be any of the enumerations of the Compilation.Unit_State
type, except Compilation.Archived. By default, the compilation goal is the
coded state. To set the compilation goal to the installed state, specify
Compilation.Installed. If Compilation.Source is specified, the demoted
units are put in the source state, regardless of the value of the
Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified, and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date on which the
reservation was abandoned, the objects affected, and the username and
session in which the command was entered. If the Comments parameter is
specified, this comment is also entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Check_Out
@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>");
DESCRIPTION
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.
The Accept_Changes procedure can be used to:
* Update each destination object to the latest generation. 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.)
* Synchronize the development of controlled objects that are joined to
objects in views with different target keys.
* "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.
* 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. Note that new objects are not copied if the
destination view already contains uncontrolled objects of the same
name.
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.
RCI Behavior
The following special actions are taken for RCI secondary text files and
secondary referencer files:
* If changes are being accepted into a secondary text file, then the
primary unit associated with the secondary text file is demoted.
Specifying Remake_Demoted_Units as True causes the demoted units to be
promoted.
* Using Accept_Changes on a primary unit specifying both source and
destination views causes the secondary referencers of the source
primary to be copied to the secondary referencers of the destination
primary.
* Using Accept_Changes on a primary unit specifying <LATEST> as the
source does not copy any secondary referencers.
* Using Accept_Changes unfreezes all specified text files in the
destination view.
PARAMETERS
Destination : String := "<CURSOR>";
Specifies one or more objects to be updated. If multiple objects are named,
they must be in the same view. A view name can be used to specify all the
objects in that view. The default is the object on which the cursor is
located.
Destination objects must be controlled. If uncontrolled objects are named,
they are noted in the output log generated by the command. If a
destination object is checked out, it is not updated and a warning message
is issued.
If a destination object was made controlled without saving source, the
object can be updated only if the Source parameter names an object that
exists in some view. (For example, when updating such a destination
object, the Source parameter may not name a configuration object that has
no view associated with it.)
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Source : String := "<LATEST>";
Specifies the object(s) to which the corresponding destination object(s)
are updated. The Source parameter can be the special name "<LATEST>", the
name of one or more objects, a view name, or a configuration name. Note
that subdirectories (for example, Units) are not accepted as object names;
instead, you must use naming expressions that resolve to the contents of
such subdirectories (for example, Units.@).
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
The Source and Destination parameters interact as follows:
* Source =>"<LATEST>"
When the Source parameter is the default special name "<LATEST>", the
Destination parameter can name a set of objects or a view. Each
destination object is updated to the most recently checked-in
generation. If the most recent generation is currently checked out, the
previous generation is used and a warning message appears in the output
log.
* Source => object(s) or view
When the Source and Destination parameters name a set of objects or a
view, each source object must have a more recent generation than the
corresponding destination object. (The source object can, but need not,
have the latest generation.) If the destination is more recent than the
source, the destination is not changed and a warning note appears in
the output log.
As before, if a source object is currently checked out, the most recent
checked-in generation is used, and a warning message appears in the
output log.
The following combinations of Source and Destination parameters are
permitted. Note that when the Source parameter names a set of objects,
the Destination parameter must name a view.
- Source => object(s); Destination => view: If the Source parameter
names a set of objects and the Destination parameter names a view,
the command updates the objects in the destination view that
correspond to the source objects.
If Source names controlled objects that are new, these objects are
copied into the Destination view (provided that the Destination view
does not already contain objects with the same name). The copied
objects are made controlled and joined to the original source
objects.
- Source => view; Destination => object(s): If the Source parameter
names a view and the Destination parameter names a set of objects,
the command updates the destination objects to match the
corresponding objects in the source view.
- Source => view; Destination => view: If the Source and Destination
parameters each name a view, the destination view is made to look
like the source view. Every controlled object in the source view
updates the corresponding object in the destination view. New
controlled objects in the source view are copied into the
destination view. The copied objects are automatically controlled
and joined to the corresponding source-view objects.
* Source => configuration
When the Source parameter names a configuration, the Destination
parameter can name a set of objects or a view. The command causes each
destination object to have the generation of the corresponding object
in the specified configuration. Consequently, naming an older
configuration causes the destination objects to "go back in time" to
earlier generations.
Naming a source configuration is the same as naming a view, except that
naming a view always updates destination objects to more recent
generations, whereas naming a configuration can change the destination
objects to older generations. (The name of a previously released view
cannot be used in place of a configuration in order to go back in time.)
Note that changing a destination object to an older generation does not
cause that generation to become the latest one (see the Revert
command). Checking out such an object updates it to the latest
generation.
Allow_Demotion : Boolean := False;
Specifies whether the Accept_Changes procedure should be allowed to demote
Ada units in order to update the specified destination objects.
If the Allow_Demotion parameter is True, the Accept_Changes procedure is
permitted to demote Ada units if necessary. If this parameter is False,
the command proceeds only if no demotion is required; otherwise, an error
is reported and the command quits.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted in the process
of updating the destination objects.
If True (the default value), demoted units are recompiled to the state
specified by the Goal parameter. If False, units remain demoted.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The goal can be any of the enumerations of the Compilation.Unit_State
type, except Compilation.Archived. By default, the compilation goal is the
coded state. To set the compilation goal to the installed state, specify
Compilation.Installed. If Compilation.Source is specified, the demoted
units are put in the source state, regardless of the value of the
Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified, and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date on which changes
were accepted, the objects affected, and the username and session in which
the command was entered. If the Comments parameter is specified, this
comment is also entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
ERRORS
An error is noted in the output if an attempt is made to accept changes
into a previous generation by naming objects other than a configuration.
REFERENCES
procedure Revert
procedure Show_Out_Of_Date_Objects
@node !Commands.Cmvc.Accept_Changes_Effort
procedure Accept_Changes_Effort
(Destination : String := "<CURSOR>";
Source : String := "<REGION>";
Compare_Both : Boolean := False;
Show_New_Uncontrolled : Boolean := False;
Show_New_Controlled : Boolean := True;
Show_Uncontrolled : Boolean := False;
Show_Severed : Boolean := False;
Show_Modified : Boolean := True;
Show_Equal : Boolean := False;
Ada_Units : Boolean := True;
Files : Boolean := True;
Response : String := "<PROFILE>")
renames Compare;
DESCRIPTION
Reports the effect of accepting changes from the source view into the
destination view, without actually performing the accept-changes
operation.
The report is displayed in the current output window.
This procedure lists the objects that would be affected by executing the
Accept_Changes command to update the specified destination view from the
specified source view or configuration. In particular, the procedure lists:
* New controlled objects that would be copied from the source view or
configuration into the destination view.
* Modified controlled objects whose modifications would be propagated from
the source view or configuration into the destination view.
The Accept_Changes_Effort command renames the Compare command and reports
a subset of the information provided by the Compare command. Note that no
information about uncontrolled objects is reported because the
Accept_Changes command affects only controlled objects.
PARAMETERS
Destination : String := "<CURSOR>";
Specifies the view into which changes will potentially be accepted. The
Destination parameter must name a single view. The default is the view
designated by the cursor.
Source : String := "<REGION>";
Specifies the view or configuration from which changes will potentially be
accepted. The Source parameter must name a single view or configuration.
The default is the highlighted view or configuration.
Compare_Both : Boolean := False;
Specifies whether the comparison should be symmetrical. When False (the
default), the comparison is not symmetrical, so that the procedure reports
new and modified objects only from the source view.
When True, the source view is compared to the destination view and vice
versa. In this case, the procedure reports new and modified objects in both
the destination and source views.
Show_New_Uncontrolled : Boolean := False;
Specifies whether to report new uncontrolled objects. When False (the
default), the report omits the information about uncontrolled objects
(because the accept-changes operation ignores uncontrolled objects). When
True, information about uncontrolled objects is included.
Show_New_Controlled : Boolean := True;
Specifies whether to report new controlled objects. When True (the
default), the report includes the list of controlled objects that are in
the source view but not in the destination view. When False, this list is
omitted.
Show_Uncontrolled : Boolean := False;
Specifies whether to report uncontrolled objects common to both views. When
False (the default), the report omits the information about uncontrolled
objects (because the accept-changes operation ignores uncontrolled
objects). When True, information about uncontrolled objects is included.
Show_Severed : Boolean := False;
Specifies whether to report severed objects. When False (the default), the
report omits the list of controlled objects that are common to both views
but severed. When False, this list is included.
Show_Modified : Boolean := True;
Specifies whether to report modified objects. When True (the default), the
report includes the list of controlled objects that are joined across both
views but have a more up-to-date generation in the source view. When
False, this list is omitted.
Show_Equal : Boolean := False;
Specifies whether to report unmodified objects. When True, the report
includes the list of controlled objects that are joined across both views
and have the same generation in each view. When False (the default), this
list is omitted.
Ada_Units : Boolean := True;
Specifies whether to include information about Ada units in the report.
When True (the default), such information is included. When False, such
information is omitted.
Files : Boolean := True;
Specifies whether to include information about files in the report. When
True (the default), such information is included. When False, such
information is omitted.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Accept_Changes
procedure Compare
@node !Commands.Cmvc.Append_Notes
procedure Append_Notes (Note : String := "<WINDOW>";
What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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:
* 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.
PARAMETERS
Note : String := "<WINDOW>";
Specifies a string to be appended to an object's existing notes. If the
Note parameter names an indirect file, the contents of that file are
appended to the existing notes for the specified controlled object.
If the default special name "<WINDOW>" is used, it refers to the contents
of a notes window created by either the Get_Notes or the
Create_Empty_Note_Window command. When the default value is used,
Append_Notes must be entered from a command window attached to the notes
window. The first line of the notes window contains the name of the object
associated with the notes; therefore, the What_Object parameter is
ignored.
What_Object : String := "<CURSOR>";
Specifies the object whose notes are to be augmented. The specified object
must be both controlled and checked out; otherwise, the command quits.
The What_Object parameter is ignored if the Note parameter's default value
is used.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Create_Empty_Note_Window
procedure Get_Notes
procedure Notes
procedure Put_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>");
DESCRIPTION
Builds views from the specified configuration objects.
The reconstructed views are built with the same subclass as the view from
which the configuration objects were created. For example, if a
configuration object was originally made from a combined view, the rebuilt
view will be a combined view.
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:
* The Release command creates only a configuration object without creating
the corresponding released view if the Create_Configuration_Only
parameter is True.
* 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.
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 subsystem_name.Configurations.
Each configuration object has the same simple name as the view to which it
corresponds.
When building a number of views that import each other, you can build them
in any order and then use the Import command to reestablish the imports.
(See "Where Imports are Recorded," under procedure Import.)
RCI Behavior
when working with RCI views, the following apply:
* Cmvc.Build attempts to set the Ftp.Remote_Machine library switch in the
new view. The value for this switch is obtained by looking in:
- Rci.Custom_Key_Default_Machine switch (one for each registered
target key in a host library) in the host view's enclosing library
compiler switches. The RCI traverses the enclosing libraries until
it finds a nonnull switch value.
- Session_Rci.Custom_Key_Default_Machine (one for each registered
target per session). The RCI uses this value if it does not find a
nonnull value in the library compiler switches.
Cmvc.Build similarly attempts to set the Ftp.Remote_Directory library
switch.
* Values for Ftp.Remote_Machine and Ftp.Remote_Directory can be
explicitly specified by using Rci_Cmvc.Build instead of Cmvc.Build.
* If the following items are true, a remote library is also constructed:
- Remote extensions management is enabled
- The remote username and password are set in the user's session
switches or in the Remote_Passwords file.
- The default switch naming scheme (outlined above) provides values
for Remote_Machine and Remote_Directory.
If any of the above is not true, or if for any other reason the remote
library cannot be built, it is not possible to bring units to the coded
state in the combined view until the remote library is built explicitly
by the user and the other conditions are corrected.
* This library management operation is affected by the values of the
following switches:
- Operation_Mode (to determine Batch or Interactive mode)
- Session_Rci.Auto_Create_Remote_Directory switch (for view creation)
- Rci.Host_Only switch (for existing views)
Operations may also vary depending on values specific to your
extension. See your extension user guide or your customizer for more
information.
PARAMETERS
Configuration : String := ">>CONFIGURATION NAME<<";
Specifies one or more configuration objects from which views are to be
built. If the command is executed in the subsystem library, the
configuration names can be specified using relative naming--for example,
Configurations.Rev1_0_1 names the configuration for which the corresponding
view Rev1_0_1 is built.
Multiple configuration objects can be specified by using wildcards, context
characters, special names, set notation, or an indirect file.
View_To_Import : String := "<INHERIT_IMPORTS>";
Specifies one or more views to be imported by each of the newly built
views. The views specified by this parameter must be spec or combined
views.
If the View_To_Import parameter is the default special name
"<INHERIT_IMPORTS>", imports are determined by information in the state
description directory associated with each configuration object. (State
description directories are created automatically for released views and
are named subsystem.Configurations.release_name_State.)
If the View_To_Import parameter is the null string (""), no views are
imported.
If the View_To_Import parameter specifies one or more views, only the
specified views are imported, and any imports listed in a corresponding
state description directory are ignored.
The Imported_Views function can be used to return another view's imports
as the value of the View_To_Import parameter. This is a convenient way of
setting the newly built view's imports to be the same as another view's
imports.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. Furthermore, the
View_To_Import parameter can name an activity as an indirect file, which is
equivalent to naming the spec view associated with each subsystem listed
in the activity.
Model : String := "<INHERIT_MODEL>";
Specifies a model world for each newly built view. If the specified name
cannot be resolved in the context !Model, the name is resolved relative to
the current context.
If the Model parameter is the default special name "<INHERIT_MODEL>", each
newly built view uses the model that was recorded in the state description
directory associated with the relevant configuration object. (State
description directories are created automatically for released views and
are named subsystem.Configurations.release_name_State.)
Goal : Compilation.Unit_State := Compilation.Installed;
Specifies the state to which units in the view are compiled. The goal can
be any of the enumerations of the Compilation.Unit_State type. By default,
the compilation goal is the installed state. To set the compilation goal
to the coded state, specify Compilation.Coded.
Limit : String := "<WORLDS>";
Specifies the units that can be compiled to the state specified by the Goal
parameter. Because views are worlds, the default special value "<WORLDS>"
means that only units within the newly built views can be compiled. Other
values for this parameter are given as enumerations of the
Compilation.Change_Limit subtype. For example, the string "<ALL_WORLDS>"
permits the compilation of units in other subsystems in order to compile
the units in the newly built views.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified, and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of the build
operation as well as the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to build the views. The default value
specifies that the views should be built on the volume with the most free
space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Destroy_View
procedure Release
@node !Commands.Cmvc.Check_In
procedure Check_In (What_Object : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
What_Object : String := "<CURSOR>";
Specifies one or more objects to be checked in. These objects must be
controlled. If uncontrolled objects are named, they are noted in the
output log generated by the command and ignored.
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Comments : String := "";
Specifies a comment to be stored in the CMVC database with the notes for
the specified object(s). Notes can be displayed using the Get_Notes
command. This comment also appears in the display generated by the
Show_History_By_Generation command.
In addition, the specified comment is logged to the work order specified by
the Work_Order parameter.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment is also
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
The Check_In procedure takes time proportional to the size of the
object(s) being checked in. Large objects may exhaust the job page limit
and fail. In this case, the job page limit must be increased.
REFERENCES
procedure Check_Out
procedure Make_Controlled
@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>");
DESCRIPTION
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.
PARAMETERS
What_Object : String := "<CURSOR>";
Specifies one or more objects to be checked out. If multiple objects are
specified, all must belong to the same view. If a view name is specified,
the Check_Out procedure attempts to check out all the objects in the view.
If the Check_Out procedure encounters an object that is checked out in
another view, an error is reported at that point and the command quits
without looking at any more specified objects. Checkouts made before the
command quits are abandoned.
Objects must be controlled to be checked out. If uncontrolled objects are
named, they are noted in the output log generated by the command.
If multiple objects are specified, they must be in the same view. Multiple
objects can be specified by using wildcards, context characters, special
names, set notation, or an indirect file.
Comments : String := "";
Specifies a comment to be stored in the CMVC database with the notes for
the specified object(s). The notes can be displayed using the Get_Notes
command. This comment also appears in the display generated by the
Show_History_By_Generation command.
In addition, the specified comment is logged to the work order specified by
the Work_Order parameter.
Allow_Implicit_Accept_Changes : Boolean := True;
Specifies whether the Check_Out procedure is allowed to update the specified
objects to the latest generation.
If this parameter is True, the Check_Out procedure is permitted to update
the objects. If it is False, the command proceeds only if the specified
objects are already at the latest generation; otherwise, an error is
reported and the command quits.
Allow_Demotion : Boolean := False;
Specifies whether the Check_Out procedure is allowed to demote Ada units in
order to update the specified objects to the latest generation.
If this parameter is True, the Check_Out procedure is permitted to demote
Ada units if necessary. If it is False, the command proceeds only if no
demotion is required; otherwise, an error is reported and the command
quits.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted in the process
of updating the specified objects to the latest generation.
If True (the default value), demoted units are recompiled to the state
specified by the Goal parameter. If False, units remain demoted.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The goal can be any of the enumerations of the Compilation.Unit_State
type, except Compilation.Archived. By default, the compilation goal is the
coded state. To set the compilation goal to the installed state, specify
Compilation.Installed. If Compilation.Source is specified, the demoted
units are put in the source state, regardless of the value of the
Remake_Demoted_Units parameter.
Expected_Check_In_Time : String := "<TOMORROW>";
Specifies the anticipated date and time at which the objects will be
checked in. The value of this parameter can be any string accepted by the
!Tools.Time_Utilities.Value function (documented in PT). The default
value, "<TOMORROW>", supplies the date and time for the next day. The
expected checkin time can be viewed using commands such as Show.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkout, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment is also
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Abandon_Reservation
procedure Check_In
procedure Show
procedure Show_All_Checked_Out
procedure Show_Checked_Out_By_User
procedure Show_Checked_Out_In_View
procedure Show_History_By_Generation
@node !Commands.Cmvc.Compare
procedure Compare (Destination : String := "<CURSOR>";
Source : String := "<REGION>";
Compare_Both : Boolean := True;
Show_New_Uncontrolled : Boolean := True;
Show_New_Controlled : Boolean := True;
Show_Uncontrolled : Boolean := True;
Show_Severed : Boolean := True;
Show_Modified : Boolean := True;
Show_Equal : Boolean := False;
Ada_Units : Boolean := True;
Files : Boolean := True;
Response : String := "<PROFILE>");
DESCRIPTION
Compares a pair of views and reports various kinds of information about
them.
This procedure is especially useful when you want an overview of the
differences between:
* Two releases made at different times. (Note that configuration releases
can be compared as well as released views.)
* A working view and a release that was made from it.
* Two joined working views in different development paths.
* Two joined working views in the same development path-for example, the
main working view and a subpath. (Note that comparing two working views
can help you assess the impact of accepting changes from one view into
the other. You can use the Accept_Changes_Effort command, which renames
the Compare command, for this purpose.)
By default, this procedure produces a report in the current output window
that lists:
* New objects in each view-that is, the objects (both controlled and
uncontrolled) that exist in one view but not the other.
* Modified objects in each view-that is, the controlled objects that are
joined across both views but have a different generation in each view.
* The controlled objects that are common to both views but severed.
* The uncontrolled objects that are common to both views.
By default, the comparison is symmetrical-that is, the source view is
compared to the destination view and vice versa. In this case, the
procedure reports new and modified objects in the destination view as well
as those in the source view. However, setting the Compare_Both parameter
to False causes the procedure to report only the new and modified objects
in the source view.
By default, information is included in the report about Ada units and
files. However, setting the Ada_Units or Files parameter to False causes
the procedure to ignore Ada units or files, respectively.
By default, the procedure does not report the joined objects that are the
same in both views. However, setting the Show_Equal parameter to True
causes the procedure to include such objects in the report.
The Accept_Changes_Effort command, which renames the Compare procedure,
can be used to assess the effect of accepting changes from a source view
into a destination view.
PARAMETERS
Destination : String := "<CURSOR>";
Specifies the view or configuration against which the source view or
configuration is to be compared. The Destination parameter must name a
single view or configuration. The default is the view or configuration
designated by the cursor.
Source : String := "<REGION>";
Specifies the view or configuration to be compared against the destination
view or configuration. The Source parameter must name a single view or
configuration. The default is the highlighted view or configuration.
Compare_Both : Boolean := True;
Specifies whether the comparison should be symmetrical. When True (the
default), the comparison is symmetrical, so that the source view is
compared to the destination view and vice versa. In this case, the
procedure reports new and modified objects in both the destination and
source views.
When False, the procedure compares the source view against the destination
view and reports only the source view's new and modified objects.
Show_New_Uncontrolled : Boolean := True;
Specifies whether to report new uncontrolled objects. The exact effect of
this parameter depends on the value of the Compare_Both parameter. When
both parameters are True (the default), the report includes the list of
uncontrolled objects that are in one view but not the other. When
Show_New_Uncontrolled is True and Compare_Both is False, the report lists
only the uncontrolled objects in the source view that are not also in the
destination view. When Show_New_Uncontrolled is False, information about
new uncontrolled objects is omitted altogether, regardless of the value of
Compare_Both.
Show_New_Controlled : Boolean := True;
Specifies whether to report new controlled objects. The exact effect of
this parameter depends on the value of the Compare_Both parameter. When
both parameters are True (the default), the report includes the list of
controlled objects that are in one view but not the other. When
Show_New_Controlled is True and Compare_Both is False, the report lists
only the controlled objects in the source view that are not also in the
destination view. When Show_New_Controlled is False, information about new
controlled objects is omitted altogether, regardless of the value of
Compare_Both.
Show_Uncontrolled : Boolean := True;
Specifies whether to report uncontrolled objects common to both views. When
True (the default), the report includes the list of uncontrolled objects
that are common to both views. When False, this list is omitted.
Show_Severed : Boolean := True;
Specifies whether to report severed objects. When True (the default), the
report includes the list of controlled objects that are common to both
views but severed. When False, this list is omitted.
Show_Modified : Boolean := True;
Specifies whether to report modified objects. The exact effect of this
parameter depends on the value of the Compare_Both parameter. When both
parameters are True (the default), the report includes the list of
controlled objects that are joined across both views but have a different
generation in each view. When Show_Modified is True and Compare_Both is
False, the report lists only the joined objects that have a more
up-to-date generation in the source view. When Show_Modified is False,
information about modified objects is omitted altogether, regardless of the
value of Compare_Both.
Show_Equal : Boolean := False;
Specifies whether to report unmodified objects. When True, the report
includes the list of controlled objects that are joined across both views
and have the same generation in each view. When False (the default), this
list is omitted.
Ada_Units : Boolean := True;
Specifies whether to include information about Ada units in the report.
When True (the default), such information is included. When False, such
information is omitted.
Files : Boolean := True;
Specifies whether to include information about files in the report. When
True (the default), such information is included. When False, such
information is omitted.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
EXAMPLES
Assume that you are developing a subsystem called
!Programs.Mail.Mail_Tools and you want an overview of the differences
between the current working view (Rev11_Working) and a configuration
release (Rev11_1_0) that was made from it. The following command, executed
from the context !Programs.Mail.Mail_Tools, accomplishes this:
Cmvc.Compare (Destination => "Configurations.Rev11_1_0",
Source => "Rev11_Working");
This command, which uses the default parameter values, produces the
following report in the current output window:
Comparison of Source View and Destination Configuration
Source : !PROGRAMS.MAIL.MAIL_TOOLS.REV11_WORKING
Destination : !PROGRAMS.MAIL.MAIL_TOOLS.CONFIGURATIONS.REV11_1_0
Controlled New Source Objects Path Name
========== ================== ===========
No Design_Doc Units
There are no new objects in the destination configuration
There are no uncontrolled objects that exist in both views
There are no severed objects
Source Gen Dest Gen Modified Source Objects Path Name
========== ======== ============================== ================
10 9 Access_Control_Checks'Body Units.Acl_Tools
7 6 Access_Control_Checks'Spec Units.Acl_Tools
7 5 Access_Control_Tools'Body Units.Acl_Tools
8 7 Directory_Operations'Body Units
3 2 Subsystem_Operations'Body Units
There are no modified objects in the destination configuration
According to this report, the source view contains one new uncontrolled
object (Design_Doc) that was created since the configuration release was
made. The view and configuration share no uncontrolled objects and no
controlled objects have been severed. Five objects have been modified in
the working view since the release was made; the report lists the current
generation of each modified object. As expected, the configuration release
contains no new or modified objects. Note that objects are listed by their
simple names. A separate field gives the rest of their pathnames within the
view (that is, the name of the subdirectory in the view that contains the
object).
REFERENCES
procedure Accept_Changes_Effort
@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>");
DESCRIPTION
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.
When copying a number of views that import each other, you can copy them
in any order and then use the Import command to reestablish the imports.
(See "Where Imports are Recorded," under procedure Import.)
RCI Behavior
When working with RCI views, the following apply:
* Cmvc.Copy attempts to set the Ftp.Remote_Machine library switch in the
new view. The value for this switch is obtained by looking in:
- Rci.Custom_Key_Default_Machine switch (one for each registered
target key in a host library) in the host view's enclosing library
compiler switches. The RCI traverses the enclosing libraries until
it finds a nonnull switch value.
- Session_Rci.Custom_Key_Default_Machine (one for each registered
target per session). The RCI uses this value if it does not find a
nonnull value in the library compiler switches.
Cmvc.Copy similarly attempts to set the Ftp.Remote_Directory library
switch.
* Values for Ftp.Remote_Machine and Ftp.Remote_Directory can be
explicitly specified by using Rci_Cmvc.Copy instead of Cmvc.Copy.
* If the following items are true, a remote library is also constructed:
- Remote extensions management is enabled
- The remote username and password are set in the user's session
switches or in the Remote_Passwords file.
- The default switch naming scheme (outlined above) provides values
for Remote_Machine and Remote_Directory.
If any of the above is not true, or if for any other reason the remote
library cannot be built, it is not possible to bring units to the coded
state in the combined view until the remote library is built explicitly
by the user and the other conditions are corrected.
* This library management operation is affected by the values of the
following switches:
- Operation_Mode (to determine Batch or Interactive mode)
- Session_Rci.Auto_Create_Remote_Directory switch (for view creation)
- Rci.Host_Only switch (for existing views)
Operations may also vary depending on values specific to your
extension. See your extension user guide or your customizer for more
information.
PARAMETERS
From_View : String := "<CURSOR>";
Specifies the source view or views from which copies are to be made. The
default is the view on which the cursor is located. This parameter can
name:
* Combined, load, or spec views
* Working or released views
All controlled objects in a view named by the From_View parameter must be
checked in. If the parameter names multiple views, a new view is copied
from each of the named views. Each new view is created in the same
subsystem as the view from which it is copied.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. The named views can be in
the same or in different subsystems.
New_Working_View : String := ">>SUB/PATH NAME<<";
Specifies the string to be used in constructing the names of the new views.
The string specified by the New_Working_View parameter is used in several
ways, depending on the values of the Construct_Subpath_Name and
Create_Spec_View parameters:
* If both Create_Subpath_Name and Create_Spec_View are False, the string
specified by New_Working_View is used as a pathname prefix for a working
view--for example, Rev2 in Rev2_Working.
* If Create_Subpath_Name is True, the string specified by New_Working_View
is used as a subpathname extension for a working view--for example,
Anderson in Rev1_Anderson_Working. The new name is constructed using
the pathname (Rev1) from the source view.
* If Create_Subpath_Name is False and the New_Working_View string
contains an underscore, the string specified by New_Working_View is used
as both the pathname prefix and subpath extension--for example,
Rev2_Miyata in Rev2_Miyata_Working.
* If Create_Spec_View is True, the string specified by New_Working_View is
used as a spec view prefix--for example, Rev1 in Rev1_0_Spec.
Other portions of the constructed names, such as _Working and _0_Spec, are
supplied automatically.
If the From_View parameter names multiple views, all of the new views will
use the same name prefix or extension.
New_Working_View can be any string that constitutes a legal Ada identifier.
Note that a string containing an underscore is interpreted as a path prefix
followed by a subpath extension and not merely as a path prefix containing
an underscore. This has consequences for subsequent CMVC operations. For
example, if the New_Working_View parameter specifies the string "Target_2"
and the Construct_Subpath_Extension parameter is False, the Copy command
creates a view named Target_2_Working. If another subpath view is
subsequently created from this view, the string "2" will be replaced by
the new subpath extension.
View_To_Modify : String := "";
Specifies one or more spec, load, or combined views whose imports should be
changed to refer to the new views, provided that those new views are
combined or spec views. The imports of the views specified by this
parameter also are updated using the views named by the View_To_Import
parameter. The View_To_Modify views are updated by View_To_Import views as
if Only_Change_Imports were True, regardless of this parameter's actual
value.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
View_To_Import : String := "<INHERIT_IMPORTS>";
Specifies one or more spec or combined views to be imported by the new
views. The views named by this parameter also are used to update the
imports of the views named by the View_To_Modify parameter.
If View_To_Import specifies the default special name "<INHERIT_IMPORTS>",
each new view uses the same imports as the view from which it was copied.
(However, if the From_View parameter names multiple combined views among
which import relations hold, the imports are automatically adjusted so
that the working views in the new paths reference each other as
appropriate, instead of referencing the working views in the original
paths.)
If View_To_Import specifies the null string ("") or a string consisting of
single space (" "), no views are imported.
If View_To_Import specifies one or more views, the specified views are
imported by the new views in the manner specified by the
Only_Change_Imports parameter.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. Furthermore,
View_To_Import can name an activity as an indirect file, which is
equivalent to naming the spec view associated with each subsystem listed
in the activity.
Only_Change_Imports : Boolean := True;
Specifies the manner in which the views specified by the View_To_Import
parameter are actually used as imports by the new views.
Only_Change_Imports has no effect if View_To_Import specifies
"<INHERIT_IMPORTS>" or the null string.
If this parameter is False, the entire list of views given by
View_To_Import is imported by each new view created by the Copy command.
No imports are inherited.
If the parameter is True (the default value):
* Each new view inherits its imports from the view from which it was
copied.
* The list of views in View_To_Import is compared to the inherited views.
If a View_To_Import view is from the same subsystem as an inherited
view, the View_To_Import view replaces that inherited view.
Thus, if Only_Change_Imports is True, the list of views in View_To_Import
is used to update the inherited imports of each new view. In this way, the
replacement imports for every new view can be specified in a single list
without forcing each new view to import everything in the list.
Join_Views : Boolean := True;
Specifies whether to join each new view to the view from which it was
copied. Only new working views (either load or combined) are joined. (That
is, the value of Join_Views is ignored if the Create_Spec_View parameter
is True.)
If Join_Views is True (the default value), the controlled objects in each
copied working view are joined to the corresponding objects in each source
view named by the From_View parameter. The reservation tokens from the
source views are used. If a source view contains no controlled objects,
then no objects can be joined. Note that Join_Views affects only
controlled objects that exist at the time the Copy command is executed.
Objects created after the new views are made must be controlled explicitly
and joined using the Make_Controlled and Join commands.
If Join_Views is False, new reservation tokens are created for all of the
controlled objects. The value for New_Working_View is used as the
reservation token, unless Reservation_Token_Name specifies a nonnull value.
Reservation_Token_Name : String := "<AUTO_GENERATE>";
Specifies the name of the reservation token to be associated with each
specified object. The value of this parameter is used only if the
Join_Views and Create_Spec_View parameters are False.
The default value "<AUTO_GENERATE>" means that the reservation token is
generated automatically by the Environment. Names of reservation tokens
that are generated automatically are derived from the first portion of the
enclosing view name (up to the first underscore character). For example,
the controlled objects in a view called Rev1_Working would have Rev1 as
their automatically generated token name. (Where necessary, a number is
appended to produce a unique name for the reservation token--for example,
Rev1_1.)
A user-defined token name can be supplied instead to provide subsequent
join sets with more meaningful or mnemonic token names.
Note that supplying an existing token name cannot be used to join the
newly controlled objects to any other objects.
Construct_Subpath_Name : Boolean := False;
Specifies whether each new view should be named as a subpath of the
corresponding source view.
If True, the string specified by the New_Working_View parameter is used as
a subpathname extension in each new view's name. Each new view name is
constructed from the pathname prefix of the source view followed by the
string specified by New_Working_View. The string "_Working" is
automatically added to the name's end. For example, if From_View names a
source view called "Rev1_4_5" and New_Working_View specifies the string
"Anderson", then setting Construct_Subpath_Name to True causes the new
view to be called Rev1_Anderson_Working.
If False (the default value), the string specified by the New_Working_View
parameter is used either as a pathname prefix or (if Create_Spec_View is
True) as a spec-view prefix in the new view names.
The value of Construct_Subpath_Name is ignored if the Create_Spec_View
parameter is True.
Create_Spec_View : Boolean := False;
Specifies whether to create spec views instead of working load or combined
views.
If Create_Spec_View is False (the default value), the type of view created
depends on the values of the Create_Load_View and Create_Combined_View
parameters. If all three parameters are False, each new view is the same
type as the source view from which it was copied.
If Create_Spec_View is True, a new spec view is created from each of the
source views specified by From_View. In this case, the values of
Create_Spec_View and Create_Combined_View must be False. Objects in the
new spec views are uncontrolled.
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.
When Create_Spec_View is True, the string specified by New_Working_View is
used as a spec-view prefix. The name of each new view thus is constructed
from the specified string, followed by one or more release level numbers
(as determined by the Level_For_Spec_View parameter), followed by the
string "_Spec". For example, if From_View names a source view called
"Rev1_Anderson_Working" and New_Working_View specifies the string "Rev2",
then setting Create_Spec_View to True causes the new view to be called
Rev2_n_Spec (where n represents the current release level number).
When Create_Spec_View is True, the values of the Join_Views,
Reservation_Token_Name, and Construct_Subpath_Name parameters are ignored.
The value of Create_Spec_View is ignored when the Copy command is entered
in a system or in a combined subsystem. Systems can contain only system
views and combined subsystems can contain only combined views.
Create_Load_View : Boolean := False;
Specifies whether to create working load views instead of spec views or
working combined views.
If Create_Load_View is False (the default value), the type of view created
depends on the values of the Create_Spec_View and Create_Combined_View
parameters. If all three parameters are False, each new view is the same
type as the source view from which it was copied.
If Create_Load_View is True, a new load view is created from each of the
source views specified by From_View. In this case, the values of
Create_Spec_View and Create_Combined_View must be False.
The value of Create_Load_View is ignored when the Copy command is entered
in a system or in a combined subsystem. Systems can contain only system
views and combined subsystems can contain only combined views.
Create_Combined_View : Boolean := False;
Specifies whether to create working combined views instead of spec views or
working load views.
If Create_Combined_View is False (the default value), the type of view
created depends on the values of the Create_Spec_View and Create_Load_View
parameters. If all three parameters are False, each new view is the same
type as the source view from which it was copied.
If Create_Combined_View is True, a new combined view is created from each
of the source views specified by From_View. In this case, the values of
Create_Spec_View and Create_Load_View must be False.
The value of Create_Combined_View is ignored when the Copy command is
entered in a system. Systems can contain only system views.
Level_For_Spec_View : Natural := 0;
Specifies which level number number to increment when creating spec-view
names. If the value of this parameter is Natural'Last, spec-view names are
generated without level numbers.
Level numbers in a spec-view name are generated from the level numbers in
the name of the most recently released view in that subsystem. Note that a
released-view name contains as many numbers as there are release levels;
the rightmost number is the 0th level. In a spec-view name, the string
"_Spec" replaces the rightmost (0th level) number, so a spec-view name has
one number less than a released-view name.
If Level_For_Spec_View is 0, no release level numbers are incremented,
because the 0th-level number has been replaced. In this case, the
spec-view name contains the same numbers (starting with level 1) as the
most recent release. If Level_For_Spec_View is 1, the first-level number in
the most recent release name is incremented before the appropriate level
numbers are inserted into the spec-view name. The number of levels that
can be incremented is determined by the Levels file within the model world
for the view. The Copy command quits if the value of the
Level_For_Spec_View parameter is a number other than Natural'Last that
exceeds the total number of levels specified by the Levels file.
For example, assume that there are two release levels and the most
recently released view is called Rev1_4_2. If Create_Spec_View is True and
Level_For_Spec_View is 1, the name generated for the new spec view is
Rev1_5_Spec (assuming that the New_Working_View parameter specifies the
string "Rev1").
The value of Level_For_Spec_View is ignored if the Create_Spec_View
parameter is False.
Model : String := "<INHERIT_MODEL>";
Specifies a model world for each new working view. If the specified name
cannot be resolved in the context !Model, the name is resolved relative to
the current context. By default, the new working view uses the same model
as the view from which it was copied.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted by adjusting
imports.
If True (the default value), units are recompiled to the state specified by
the Goal parameter.
If False, any units demoted by adjusting imports are left in the demoted
state.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The goal can be any of the enumerations of the Compilation.Unit_State
type, except Compilation.Archived. By default, the compilation goal is the
coded state. To set the compilation goal to the installed state, specify
Compilation.Installed. If Compilation.Source is specified, all units in the
view are put in the source state, regardless of the value of the
Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date when the new working
view was copied and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to make the new working views. The default
value specifies that the new working views should be created on the volume
with the most free space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Make_Path
procedure Make_Spec_View
procedure Make_Subpath
procedure Merge_Changes
@node !Commands.Cmvc.Create_Empty_Note_Window
procedure Create_Empty_Note_Window
(What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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:
* The Append_Notes command can be used to append the window's contents to
the object's existing notes.
* 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.
PARAMETERS
What_Object : String := "<CURSOR>";
Specifies the object for which an empty notes window is to be created. The
specified object must be controlled.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Append_Notes
procedure Get_Notes
procedure Notes
procedure Put_Notes
@node !Commands.Cmvc.Def
procedure Def (What_Object : String := "<CURSOR>";
In_Place : Boolean := False);
DESCRIPTION
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:
* Entering Edit from a view or from a controlled object in the view
displays the configuration image for that view.
* 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:
* Entering Notes from a controlled object in a view displays the history
image for the object.
* 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.
PARAMETERS
What_Object : String := "<CURSOR>";
Specifies the object or image from which to traverse. Objects must be
controlled. Images include configuration, generation, and history images.
The default is the object or image on which the cursor is currently
located.
In_Place : Boolean := False;
Specifies whether the current frame should be used to display the image.
The default specifies that the least recently used frame should be used.
@node !Commands.Cmvc.Destroy_Subsystem
procedure Destroy_Subsystem
(What_Subsystem : String := "<SELECTION>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
What_Subsystem : String := "<SELECTION>";
Specifies one or more subsystems to be destroyed. There can be no views in
the specified subsystems. By default, the selected subsystem is destroyed.
Multiple subsystems can be specified by using wildcards, context
characters, special names, set notation, or an indirect file.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date when the subsystem
is destroyed and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc.Destroy_System
procedure Destroy_System (What_System : String := "<SELECTION>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
What_System : String := "<SELECTION>";
Specifies one or more systems to be destroyed. There can be no views in the
specified systems. By default, the selected system is destroyed.
Multiple systems can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date the system is
destroyed and the username and session in which the command was entered.
If the Comments parameter is specified, this comment also is entered in the
work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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:
* The view contains controlled objects that currently are checked out.
* The view is currently imported by client views.
* 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.
Using Destroy_View with RDF
You can use the Destroy_View command to destroy views created for use with
the Rational Design Facility (RDF). Destroy_View destroys an RDF view
without going through the RDF policy checks that govern the demotion of
units. To avoid the policy checks, the Destroy_View command essentially
sets the policy portion of the view's target key to R1000.
RCI Behavior
The following comments apply when working with RCI views:
* Cmvc.Destroy_View demotes all units before performing the destroy
operation. If the RCI state file has already been destroyed, preventing
normal demotion, this routine forces the demotion of units in the
indicated view before performing the destroy operation. Use the
Rci.Refresh_View command to rebuild the state file and then reissue the
Destroy_View command.
* If you want to destroy a host view, but not the associated remote
directory, set the Rci.Host_Only library switch to True.
* This library management operation is affected by the values of the
following switches:
- Operation_Mode (to determine Batch or Interactive mode)
- Session_Rci.Auto_Create_Remote_Directory switch (for view creation)
- Rci.Host_Only switch (for existing views)
Operations may also vary depending on values specific to your
extension. See your extension user guide or your customizer for more
information.
PARAMETERS
What_View : String := "<SELECTION>";
Specifies one or more views to be destroyed. The default, "<SELECTION>",
means that the selected view is destroyed. The specified views cannot
contain controlled objects that currently are checked out.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Demote_Clients : Boolean := False;
Specifies whether a view can be destroyed if other views import it. If
False (the default value), the Destroy_View command quits if the specified
view is imported by other views. If True, the specified view is removed
from the imports of any referencing views and then destroyed. Note that
units in the referencing views may be demoted as a result of removing the
import.
Destroy_Configuration_Also : Boolean := False;
Specifies whether to destroy the configuration object associated with each
specified view. If False (the default value), the configuration object is
preserved for each destroyed view. In addition, the state description
directory is preserved for each released view and a state description
directory is created for each spec and working view. (State description
directories exist in the subsystem.Configurations directory along with
configuration objects.)
As a result, any view destroyed while this parameter is False can be
reconstructed using the Build procedure command. (Note that only the
controlled objects in a view can be reconstructed by Build.) Destroying a
view while this parameter is False is useful for saving space without
losing information. Note that as long as the configuration object exists, a
new view with the same name cannot be created in the same subsystem.
If True, the configuration object is expunged from the CMVC database. The
destroyed view cannot be reconstructed, although a new view with the same
name can be created.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date the view is
destroyed and the username and session in which the command was entered.
If the Comments parameter is specified, this comment also is entered in the
work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
A view cannot be destroyed if it contains controlled objects that
currently are checked out, if it is imported by other views, or if it is
included in a system.
@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);
DESCRIPTION
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:
* Check in, check out, and accept changes on controlled objects.
* 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.)
* 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.
PARAMETERS
View_Or_Config : String := "<CURSOR>";
Specifies the view or object for which to display a configuration image. A
configuration object also can be specified, even if the corresponding view
no longer exists. If an object is specified, it must be controlled.
The default is the object or view on which the cursor is currently
located.
In_Place : Boolean := False;
Specifies whether the current frame should be used to display the image.
The default specifies that the least recently used frame should be used.
Allow_Check_Out : Boolean := True;
Specifies whether to permit checkout operations in configuration images. If
True (the default), commands from package Common can be used to check out
objects from a configuration image. If False, checkout operations are not
permitted.
Allow_Check_In : Boolean := True;
Specifies whether to permit checkin operations in configuration images. If
True (the default), commands from package Common can be used to check in
objects from a configuration image. If False, checkin operations are not
permitted.
Allow_Accept_Changes : Boolean := True;
Specifies whether to permit changes to be accepted in configuration images.
If True (the default), commands from package Common can be used to accept
changes into objects from a configuration image. If False, accept-changes
operations are not permitted.
REFERENCES
procedure Def
@node !Commands.Cmvc.Get_Notes
procedure Get_Notes (To_File : String := "<WINDOW>";
What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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:
* The Append_Notes command can be used to append the window's contents to
the object's existing notes.
* 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.
PARAMETERS
To_File : String := "<WINDOW>";
Specifies where to put the retrieved notes. If a new filename is specified, a
file is created and the notes are written into it. If an existing filename
is specified, the contents of that file are replaced with the notes.
If the default special name "<WINDOW>" is used, a window is opened in
which the notes are displayed. Note that this window is not a normal text
file; changes to this window can be saved only by using the Put_Notes
command.
What_Object : String := "<CURSOR>";
Specifies the object whose notes are to be retrieved. Only controlled
objects have notes. The default is the object on which the cursor is
located.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Append_Notes
procedure Create_Empty_Note_Window
procedure Notes
procedure Put_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>");
DESCRIPTION
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:
* Add new imports
* Change an existing import by importing a different view from the same
subsystem
* Refresh a view's existing imports after new specifications have been
added to the imported views
(Note that when working with the RCI, and depending on the specific RCI
extension, this operation may alter the remote program-library state.)
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.
Imports and Links
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 cannot be added individually
through commands from package Links.
When one view imports multiple views, a link-name conflict can arise (for
example, when units in different imported views have the same simple name
and therefore have the same link name). The Import command displays a
message reporting the conflicts. You can resolve a link-name conflict by
assigning the units different link names in an import restriction file
(see below).
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.
Export Restriction Files
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.
Import Restriction Files
An import restriction file is a text file in a client view that filters the
exports from a particular supplier view. The entries in an import
restriction file specify the links that can be created in the client view.
A client view may have multiple import restriction files, one for each of
its supplier views. If no import restriction file exists for a particular
supplier view, then links are created to all units exported from that
supplier view (this is equivalent to having an import restriction file
that contains the single entry@).
To create an import restriction file for a particular supplier view:
1. Create a text file in the Imports subdirectory of the client view. This
file must have the same name as the subsystem containing the supplier
view. You can use the subsystem's simple name for the import
restriction file; however, if subsystems in different directories have
the same simple name, the file will apply to all of them, resulting in
units unexpectedly being absent from the importing view.
To avoid ambiguity, it is recommended that you derive the name of each
import restriction file from the fully qualified subsystem name. To do
this, omit the preceding ! and change 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.
2. (Optional) Enter the following string on the first line of the file:
export_restriction=> simple_name
where simple_name names the desired export restriction file from the
supplier view. No blanks should appear in this line.
You can omit this line if you want to use the entire supplier view (or
an export restriction file named Default, if such a file exists).
3. Enter the desired import-restriction-file entries, one to a line. These
entries further filter the units that are exported from the supplier
view via the specified export restriction file.
Each entry can be a simple name or one of the naming expressions listed
below. Links are created in the client view for the units that are
matched by the names or the naming expressions. "italic(NOTE: If no
names or naming expressions are specified, no links are created.)
* To request links to all of the units exported from the supplier view
via the specified export restriction file, enter @ on a line by
itself:
export_restriction => foo
@
* To request links to most of the exported units, enter the @ entry,
followed by entries for the links to be excluded:
export_restriction => foo
@
~leave_me_out
~me_too
* To request links for a specific set of units, list the simple names
of the desired units (these simple names will be used as the link
names):
export_restriction => foo
simple_name
another_simple_name
Note that simple names must be used in an import restriction file
because these names are resolved as link names, not as library
names.
* To resolve a link-name conflict when requesting links for a specific
set of units, rename the link as follows (see "Imports and Links,"
above):
export_restriction => foo
unit_simple_name new_link_name
* Do not use the 'Spec attribute or any wildcard other than @ on a
line by itself.
Where Imports are Recorded
Operations that create imports create a file called State.Imports_Image in
each importing view. This file is a text file that contains the names of
all of the view's imports. The file is updated each time the view's
imports are changed.
The State.Imports_Image file provides a mechanism that makes it possible
to refresh the imports of released views. This, in turn, makes it possible
to copy releases to another host out of sequence--that is, to copy a
release before you have copied all of the views it imports. Similarly, you
can rebuild views from their configuration objects before rebuilding their
imports. In either case, you can copy or rebuild the import views at your
convenience and use the Cmvc.Import command to reestablish the original
import relationships. Note that you can consult the State.Imports_Image
file to see which imported views still need to be copied or rebuilt.
PARAMETERS
View_To_Import : String := "<REGION>";
Specifies one or more views to be imported by the views named in the
Into_View parameter. The views specified by View_To_Import must be spec or
combined views. If View_To_Import specifies a set of views, these views are
imported in the manner specified by the Only_Change_Imports parameter.
If View_To_Import is the null string (""), the existing imports of
Into_View are refreshed to include any new unit specifications that have
been added.
If both View_To_Import and Into_View name the same set of combined views,
the named views import each other.
The Imported_Views function can be used to return another view's imports
as the value of View_To_Import. This is a convenient way of setting the
imports of Into_View to be the same as another view's imports.
Note that this parameter accepts only view names; export and import
restriction files never need to be specified explicitly.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. Furthermore,
View_To_Import can name an activity as an indirect file, which is
equivalent to naming the spec view associated with each subsystem listed
in the activity.
Into_View : String := "<CURSOR>";
Specifies the view or views to which imports are to be added. The default
is the view on which the cursor is located. Into_View can specify spec,
load, or combined views.
If both the View_To_Import and Into_View parameters name the same set of
combined views, the named views import each other.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Only_Change_Imports : Boolean := False;
Specifies the manner in which the views specified by the View_To_Import
parameter are actually used as imports.
If False (the default value), the entire list of views given by
View_To_Import is imported into each view specified by Into_View. Existing
imports are not affected unless a View_To_Import view is from the same
subsystem as an existing import. In this case, the View_To_Import view
replaces the corresponding existing import.
If True, a View_To_Import view is imported only if it is from the same
subsystem as an existing import. The View_To_Import view then replaces the
existing import. Thus, if Only_Change_Imports is True, the list of views
in View_To_Import is used to update existing imports rather than add new
imports. In this way, all replacement imports can be specified in a single
list without forcing every view to import everything in the list.
Import_Closure : Boolean := False;
Specifies whether to import not only the views named by View_To_Import but
also the views in their closures.
If False (the default value), imports are limited to the views named by
View_To_Import.
If True, imports include the views in the closures of the View_To_Import
views, subject to Only_Change_Imports.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted by the import
operation.
If True (the default value), units are recompiled to the state specified by
the Goal parameter.
If False, any units demoted by the import operation are left in the
demoted state.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The compilation goal can be any of the enumerations of the
Compilation.Unit_State type, except Compilation.Archived. By default, the
compilation goal is the coded state. To compile units to the installed
state, specify Compilation.Installed. If Compilation.Source is specified,
the demoted units are put in the source state, regardless of the value of
the Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. The
command's action is recorded only if the Comments parameter is specified.
In addition to the comment, the work order records the time and date as
well as the username and session in which the command was entered.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
function Imported_Views
@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;
DESCRIPTION
Returns a string that names all the views that are imported by the
specified view.
PARAMETERS
Of_View : String := "<CURSOR>";
Specifies one or more views whose imports are to be returned in a naming
string. If multiple views are specified, the Imported_Views function
returns the union of all the imports of the specified views.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Include_Import_Closure : Boolean := False;
Specifies whether to return the names of the indirectly imported views in
addition to directly imported views.
If False (the default value), only the views directly imported by the
Of_View parameter are listed. If True, the returned naming string lists
all of the views in Of_View's import closure.
Include_Importer : Boolean := False;
Specifies whether to return the names of the views specified by the Of_View
parameter. If False (the default value), only the names of imported views
are listed. If True, the returned naming string includes the names
specified by Of_View as well.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
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>");
DESCRIPTION
Displays various kinds of information about the specified view in the
output window.
Each parameter specifies whether to display a particular kind of
information.
PARAMETERS
For_View : String := "<CURSOR>";
Specifies the view for which information is to be displayed. The default is
the view on which the cursor is located. The specified view can be in a
subsystem or in a system.
Show_Model : Boolean := True;
Specifies whether to display the name of the view's model. If True (the
default value), the name is displayed.
Show_Whether_Frozen : Boolean := True;
Specifies whether to display the view's status with respect to freezing. If
True (the default value), this information is displayed.
Show_View_Kind : Boolean := True;
Specifies whether to display the view's kind--for example, spec, load, or
combined. If True (the default value), the kind is displayed.
Show_Creation_Time : Boolean := True;
Specifies whether to display when the view was created. If True (the
default value), the creation time is displayed.
Show_Imports : Boolean := True;
Specifies whether to display a list of all imported views. If True (the
default value), the imports are displayed.
Show_Referencers : Boolean := True;
Specifies whether to display a list of all subsystems that import this
view. If True (the default value), this information is displayed.
Show_Unit_Summary : Boolean := True;
Specifies whether to display a summary of the compilation states of all
units in the view. If True (the default value), the number of coded units,
installed units, source units, and empty stubs is displayed. If For_View
specifies a system view, this parameter causes the view's release activity
to be displayed.
Show_Controlled_Objects : Boolean := False;
Specifies whether to display a list of all controlled objects in the view.
If False (the default value), this information is not displayed. If True,
the display includes the same information as the Show_All_Controlled
command--namely, the number of generations that exist for each controlled
object, whether the object is checked out, and by whom.
Show_Last_Release_Numbers : Boolean := False;
Specifies whether to display the level numbers that appear in the name of
the most recently released view. These numbers will be incremented if
another released view or spec view is created. If False (the default
value), this information is not displayed.
Show_Path_Name : Boolean := False;
Specifies whether to display the string within the view's name that serves
as the pathname. If False (the default value), this information is not
displayed.
Show_Subpath_Name : Boolean := False;
Specifies whether to display the string within the view's name that serves
as the subpathname. If False (the default value), this information is not
displayed.
Show_Switches : Boolean := False;
Specifies whether to display the settings for all switches associated with
the view. If True, switch settings are displayed, along with the view's
target key. If False (the default value), this information is not
displayed.
Show_Exported_Units : Boolean := False;
Specifies whether to display a list of all exported units. If False (the
default value), this information is not displayed.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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. If you specify an existing subsystem or system, the
Initial procedure creates a new empty view of the appropriate type.
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
To create a new system or subsystem, you must have RCO access to the
enclosing library and RW default access to that library.
RCI Behavior
When working with RCI views, the following apply:
* Cmvc.Initial attempts to set the Ftp.Remote_Machine library switch in
the new view. The value for this switch is obtained by looking in:
- Rci.Custom_Key_Default_Machine switch (one for each registered
target key in a host library) in the host view's enclosing library
compiler switches. The RCI traverses the enclosing libraries until
it finds a nonnull switch value.
- Session_Rci.Custom_Key_Default_Machine (one for each registered
target per session). The RCI uses this value if it does not find a
nonnull value in the library compiler switches.
Cmvc.Initial similarly attempts to set the Ftp.Remote_Directory library
switch.
* Values for Ftp.Remote_Machine and Ftp.Remote_Directory can be
explicitly specified by using Rci_Cmvc.Initial instead of Cmvc.Initial.
* In addition to creating a new view, this routine initializes the view's
RCI state.
* If the following items are true, a remote library is also constructed:
- Remote extensions management is enabled
- The remote username and password are set in the user's session
switches or in the Remote_Passwords file.
- The default switch naming scheme (outlined above) provides values
for Remote_Machine and Remote_Directory.
If any of the above is not true, or if for any other reason the remote
library cannot be built, it is not possible to bring units to the coded
state in the combined view until the remote library is built explicitly
by the user and the other conditions are corrected.
* This library management operation is affected by the values of the
following switches:
- Operation_Mode (to determine Batch or Interactive mode)
- Session_Rci.Auto_Create_Remote_Directory switch (for view creation)
- Rci.Host_Only switch (for existing views)
Operations may also vary depending on values specific to your
extension. See your extension user guide or your customizer for more
information.
PARAMETERS
System_Object : String := ">>SYSTEM OBJECT NAME<<";
Specifies the name of the subsystem or system to be created. The default
parameter placeholder ">>SYSTEM OBJECT NAME<<" must be replaced or an
error will result.
If you specify the name of an existing subsystem or system, the Initial
procedure creates a new view of the appropriate type in that subsystem or
system. In this case, the System_Object_Type parameter is ignored; the
Create_Load_View parameter is looked at only if the existing subsystem is
a spec/load subsystem.
Working_View_Base_Name : String := "Rev1";
Specifies the base name of the initial view in the subsystem or system. If
the default value is used, the initial view is named Rev1_Working.
The string given for Working_View_Base_Name can be any legal Ada
identifier. By convention, if this string contains no underscores, it
serves as a pathname prefix; if the string contains an underscore, it
serves as a pathname prefix followed by a subpathname extension.
System_Object_Type : System_Object_Enum := Cmvc.Spec_Load_Subsystem;
Specifies whether to create a system or one of two types of
subsystem--namely, spec/load or combined. This parameter is ignored if the
System_Object parameter names an existing subsystem or system.
Systems are an optional device for creating logical groupings of releases
from component subsystems in an application. Operations for systems are in
package Cmvc_Hierarchy.
Subsystems partition applications into high-level components. The two
types of subsystem determine the kinds of views that can be created as
well as whether hierarchic importing is enforced. The default value,
Cmvc.Spec_Load_Subsystem, causes the Initial procedure to build a
subsystem that can contain either spec/load or combined views. Within such
a subsystem, all imports must be hierarchic, in that no view is permitted
to be in its own import closure. If Cmvc.Combined_Subsystem is specified,
the Initial procedure builds a subsystem that can contain only combined
views, among which circular import relations may hold.
View_To_Import : String := "";
Specifies one or more views to be imported by the new working view. The
views specified by View_To_Import must be spec or combined views.
If View_To_Import is the null string (""), the default value, no views are
imported.
The Imported_Views function can be used to return another view's imports
as the value of View_To_Import. This is a convenient way of setting the
new working view's imports to be the same as another view's imports.
Note that if export and import restrictions will be needed, it is
recommended that you do not use this parameter to create imports. Instead,
after the subsystem is created, you can create the export/import
restriction files and use the Cmvc.Import command to perform the import
operation.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. Furthermore,
View_To_Import can name an activity as an indirect file, which is
equivalent to naming the spec view associated with each subsystem listed
in the activity.
Create_Load_View : Boolean := True;
Specifies whether to create a load view for the initial working view. If
True, the initial working view is a load view. If False, the initial
working view is a combined view.
The value of this parameter is used only when the System_Object_Type
parameter has the value Cmvc.Spec_Load_Subsystem or when the System_Object
parameter names an existing spec/load subsystem. Otherwise, this parameter
is ignored. (When a combined subsystem is created, the initial view is a
combined view; when a system is created, the initial view is a system
view.)
Model : String := "R1000";
Specifies a model world for the initial view in the subsystem. If the
specified name cannot be resolved in the context !Model, the name is
resolved relative to the current context. By default, the view uses the
model !Model.R1000.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, if the Comments parameter is specified, the work order records
the time and date when the subsystem was created, the username and session
in which the command was entered, the specified comment, and the creation
of the release history file.
If the Comments parameter is not specified, only the creation of the
release history file is logged.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to make the new subsystem. The default value
specifies that the new subsystem should be created on the volume with the
most free space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
type System_Object_Enum
@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>");
DESCRIPTION
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.
Note that if What_Object names an object that already belongs to a join
set, the Join command implicitly severs that object from its original join
set before joining the object to the new join set. That is, the following
Join command:
Cmvc.Join (What_Object => "Foo",
To_Which_View => "Rev_Tom_Working");
is equivalent to:
Cmvc.Sever("Foo");
Cmvc.Join (What_Object => "Foo",
To_Which_View => "Rev_Tom_Working");
Consequently, if you want to add a new unit to an existing join set, you
should name the new unit in the What_Object parameter. (That is, join
"new" to "old" rather than joining "old" to "new," to avoid inadvertantly
severing "old" from the join set it's already in.)
PARAMETERS
What_Object : String := "<SELECTION>";
Specifies one or more controlled objects to be joined to their counterparts
(if any) in the view named by the To_Which_View parameter.
If What_Object specifies a view name, then all of the controlled objects
in that view are joined to their counterparts (if any) in the view named
by the To_Which_View parameter.
The text of the specified objects must be identical to the text of the
objects to which they are to be joined. The Merge_Changes command can be
used to prepare objects for joining.
If What_Object names an object that already belongs to a join set, the
Join command implicitly severs that object from its original join set
before joining the object to the new join set. Consequently, if you want
to add a new unit to an existing join set, you should name the new unit in
the What_Object parameter. (That is, join "new" to "old" rather than
joining "old" to "new," to avoid inadvertantly severing "old" from the
join set it's already in.)
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
To_Which_View : String := ">>VIEW NAME<<";
Specifies the view containing the objects to which the specified objects are
to be joined. Objects in the specified view must be checked in.
The default parameter placeholder ">>VIEW NAME<<" must be replaced unless
a value is given for the Reservation_Token_Name parameter.
Reservation_Token_Name : String := "";
Specifies the reservation token of the join set to which the specified
objects are to be joined. This parameter is used only if no value is
specified for the To_Which_View parameter.
Reservation tokens are displayed in expanded configuration images (see the
Cmvc.Edit command).
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
ERRORS
When multiple objects are specified and individual failures are
encountered, the command continues to make as many objects joined as it
can. The command's output log will list objects that could not be made
joined.
@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>");
DESCRIPTION
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.
Code views are identified by an empty file called
State.This_Is_A_Code_View. User-defined tools can check for this file to
determine whether a view is a code view.
The Units directory of a code view contains a copy of any non-Ada objects
from the original view. Links for code views are deleted.
Because Ada units in code views are stored as executable code, you cannot
modify or browse these units except through configuration and generation
images (see the Cmvc.Edit command). However, you can debug a code view
using the full capabilities of the Rational debugger, provided that the
original Ada units still exist in the same location and have not been
recompiled since the code view was created.
PARAMETERS
From_View : String := "<CURSOR>";
Specifies one or more views from which code views are to be made. The named
views must be load views. The default is the view on which the cursor is
located.
All units in the named views must be coded and must contain bodies for all
specifications that require them. All controlled units in the named views
must be checked in.
If multiple views are named, they must be in different subsystems.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Code_View_Name : String := "";
Specifies the simple name of the new code view. No part of a code-view name
is automatically generated, so the string specified by Code_View_Name
constitutes the entire name.
If multiple views in different subsystems are named, each will have the
name specified by Code_View_Name. The name can be any legal Ada identifier.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date when the code view
is created and the username and session in which the command was entered.
If the Comments parameter is specified, this comment also is entered in the
work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to make the new code views. The default value
specifies that the new views should be created on the volume with the most
free space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
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.
Any kind of file or Ada unit controlled, except for:
* Objects in the State subdirectory of a view
* Derived objects resulting from cross-target development (the names of
such objects are enclosed in angle brackets in directory displays)
* Ada stubs (new or withdrawn Ada units that have temporary names
beginning with an underscore--for example, _Ada_8_)
Saving Source
When you make an object controlled, you can choose whether or not to save
its textual source in the CMVC database:
* When you choose to save the source (by setting Save_Source to True),
the CMVC database stores textual changes from one generation to the
next. Consequently, you can reconstruct previous generations using the
Revert, Abandon_Reservation, and Build commands; furthermore, when
source is saved for joined objects, you can update out-of-date objects
with the Accept_Changes and Check_Out commands.
You may save source only for Text, Postscript, Log, or Markup files.
The CMVC database accepts line lengths of about 1000 characters long,
not counting leading blanks.
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 you choose not to save the source, 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,
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.)
However, when source is not saved for a controlled object, previous
generations cannot be reconstructed or reverted to--for example, when
rebuilding a view from a configuration object or abandoning a
reservation. Furthermore, the Accept_Changes and Check_Out commands
will update such a controlled object to the latest generation only if
an object in some view actually contains that generation.
If instances of an object exist in multiple views, all of the controlled
instances of the object must save source or else none of them can save
source.
Making Objects Recontrolled
After you have made an object controlled, you can make it uncontrolled to
discontinue the collection of history information in the CMVC database.
Until the CMVC database is expunged, however, it keeps the history
information that was gathered while the object was controlled.
You can use the Make_Controlled command to recontrol a formerly controlled
object. By default, the new change history starts over, ignoring the
original history.
To make the new change history continue from where the original history
left off, you must specify the Reservation_Token_Name parameter with name
of the reservation token under which the object was originally controlled.
(By default, a new reservation token is generated when you recontrol the
object.)
PARAMETERS
What_Object : String := "<CURSOR>";
Specifies one or more objects to be controlled. A view name can be
specified. If a named object is already controlled, a note appears in the
output log. Before a subunit can be controlled, its parent must be
controlled.
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. If multiple objects are
specified, all must be in the same subsystem. Naming multiple views not
only controls those views but also effectively joins them under a single
reservation token.
You may not control objects in the State subdirectory of a view, derived
objects resulting from cross-target development (objects whose names are
enclosed in angle brackets in directory displays), or Ada stubs (new or
withdrawn Ada units with temporary names such as _Ada_8_).
Reservation_Token_Name : String := "<AUTO_GENERATE>";
Specifies the name of the reservation token to be associated with each
specified object. This is useful for associating mnemonic names of
reservation tokens with particular join sets. Note that an existing name
of a reservation token can be used to implicitly join the newly controlled
objects to other objects.
The value of Reservation_Token_Name is used only if the Join_With_View
parameter has its default value "<NONE>".
The default special name "<AUTO_GENERATE>" means that the reservation
token is generated by the Environment.
When recontrolling a formerly controlled object, you must specify the
original reservation token associated with the object if you want the new
change history to continue from where the original history left off.
Join_With_View : String := "<NONE>";
Specifies a view to which the specified objects are joined. That is, if
Join_With_View names a view, the objects named by What_Object are joined
to the corresponding objects in the named view, and the reservation token
name for the objects is taken from that view. (In this case, the
Reservation_Token_Name parameter is ignored.)
To be joined, the objects named by What_Object must be identical in
content to the corresponding objects in the view named by Join_With_View.
Furthermore, the corresponding objects in the view named by Join_With_View
must already be controlled.
The default special name "<NONE>" means that the newly controlled objects
are not joined to any objects in any other views. (In this case, the
Reservation_Token_Name parameter determines the reservation token name.)
Save_Source : Boolean := True;
Specifies whether source is saved in the CMVC database for a controlled
object (see "Saving Source," above).
If True (the default value), the textual changes from one generation to
the next are stored in the CMVC database. You may save source only for
Text, Postscript, Log, or Markup files.
If False, no textual representation is stored in the CMVC database,
although objects must still be checked out before they can be modified.
This parameter is typically set to False when controlling binary objects
that have no ASCII representation or when controlling very large objects
(when storage space is an issue).
If instances of an object exist in multiple views, all of the controlled
instances of the object must save source or else none of them can save
source.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date when the objects
were controlled, the object affected, and the username and session in
which the command was entered. If the Comments parameter is specified, this
comment also is entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
The Make_Controlled procedure cannot join the specified objects with the
view named by the Join_With_View parameter unless the specified objects are
identical in content to the corresponding objects in the view.
The Make_Controlled procedure fails if you try to control a new object in
a view without saving the source, and the CMVC database for that view is
already saving source for an element of the same name. You must destroy
all configuration containing the old element, uncontrol the old element in
any existing views, and expunge the database before you will be able to
control the new element.
ERRORS
When multiple objects are specified and individual failures are
encountered, the command continues to make as many objects controlled as
it can. This is particularly important when the Save_Source parameter is
set to True and some of the specified objects are binary (and therefore
incapable of being saved in the CMVC database). The command's output log
will list objects that could not be made controlled.
@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>");
DESCRIPTION
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.
RCI Behavior
When working with RCI views, the following apply:
* When a new path is built from an existing view, a new remote directory
must be used to prevent two views in the same subsystem from
overwriting the same remote library. Make_Path checks that the
Remote_Directory value specified by default switches is not used by any
of the views within the subsystem of the new path.
* If the specified remote library does not exist, or exists on the
specified remote machine and is not referenced by any other view in the
same subsystem, that library is associated with the new view.
* If the new path is being built from an R1000 view, a new model world
and new imports appropriate to the RCI must be specified.
* Imports must be from other combined views with the same target key as
the new path.
* In addition to building a new path, this command initializes the RCI
state for the new view.
* Cmvc.Make_Path attempts to set the Ftp.Remote_Machine library switch in
the new view. The value for this switch is obtained by looking in:
- Rci.Custom_Key_Default_Machine switch (one for each registered
target key in a host library) in the host view's enclosing library
compiler switches. The RCI traverses the enclosing libraries until
it finds a nonnull switch value.
- Session_Rci.Custom_Key_Default_Machine (one for each registered
target per session). The RCI uses this value if it does not find a
nonnull value in the library compiler switches.
Cmvc.Make_Path similarly attempts to set the Ftp.Remote_Directory
library switch.
* If any of the following is not true, or if for any other reason the
remote library cannot be built, it is not possible to bring units to
the coded state in the combined view until the remote library is built
explicitly by the user and the other conditions are corrected.
- Remote extensions management is enabled
- The remote username and password are set in the user's session
switches or in the Remote_Passwords file.
- The default switch naming scheme (outlined above) provides values
for Remote_Machine and Remote_Directory.
* Values for Ftp.Remote_Machine and Ftp.Remote_Directory can be
explicitly specified by using Rci_Cmvc.Make_Path instead of
Cmvc.Make_Path.
* This library management operation is affected by the values of the
following switches:
- Operation_Mode (to determine Batch or Interactive mode)
- Session_Rci.Auto_Create_Remote_Directory switch (for view creation)
- Rci.Host_Only switch (for existing views)
Operations may also vary depending on values specific to your
extension. See your extension user guide or your customizer for more
information.
PARAMETERS
From_Path : String := "<CURSOR>";
Specifies the view or views that are to be copied as the beginning(s) of
new path(s). The default is the view on which the cursor is located. The
From_Path parameter can name:
* Combined, load, or spec views
* Either working or released views
All controlled objects in a From_Path view must be checked in. If
From_Path names multiple views, a new path is made from each of the named
views. Multiple views can be in the same or in different (sub)systems,
creating a family of new paths across multiple (sub)systems.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
New_Path_Name : String := ">>PATH NAME<<";
Specifies the pathname prefix to be used in constructing the names of the
views in the new paths. Because the Make_Path procedure creates new
working views, the names of these views are constructed from New_Path_Name
and the "_Working" suffix. For example, if New_Path_Name has the value
"Rev2", the working view created for the new path is "Rev2_Working" (the
underscore is supplied automatically). If the From_Path parameter names
multiple views, all of the new paths will have the same pathname prefix.
The New_Path_Name parameter can be any string that constitutes a legal Ada
identifier and therefore can contain one or more underscore characters.
However, other CMVC operations (such as generating reservation tokens or
creating subpaths) conventionally consider a view's pathname prefix to be
the portion of a view name up to (but not including) the first underscore
in the name. Therefore, if the New_Path_Name string contains an underscore
(for example "Target_2"), only the first portion of that string ("Target")
is actually considered to be the pathname. If a subpath is created from
this path, the "2" will be replaced with the subpathname.
View_To_Modify : String := "";
Specifies one or more spec, load, or combined views whose imports should be
changed to refer to the new working views, provided that the new working
views are combined views.
The imports of the views specified by View_To_Modify are also updated using
the views named by the View_To_Import parameter. The View_To_Modify views
are updated by View_To_Import views as if the Only_Change_Imports
parameter were True, regardless of this parameter's actual value.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
View_To_Import : String := "<INHERIT_IMPORTS>";
Specifies one or more spec or combined views to be imported by the new
working views. The views named by View_To_Import are also used to update
the imports of the views named by the View_To_Modify parameter.
If View_To_Import specifies the default special name "<INHERIT_IMPORTS>",
each new working view uses the same imports as the view from which it was
copied. (However, if the From_Path parameter names multiple combined views
among which import relations hold, the imports are automatically adjusted
so that the views in the new paths reference each other as appropriate,
instead of referencing the views in the original paths.)
If View_To_Import specifies the null string ("") or a string consisting of
single space (" "), no views are imported.
If the View_To_Import parameter specifies one or more views, the specified
views are imported by the new working views in the manner specified by
Only_Change_Imports.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. Furthermore,
View_To_Import can name an activity as an indirect file, which is
equivalent to naming the spec view associated with each subsystem listed
in the activity.
Create_Load_View : Boolean := False;
Specifies whether to create working load views instead of working combined
views.
If Create_Load_View is False (the default value), the type of view created
depends on the value of the Create_Combined_View parameter. However, if
both parameters are False, a new combined view is created from each
combined view specified by From_Path, and a new load view is created from
each load or spec view specified by From_Path.
If Create_Load_View is True, a new load view is created from each of the
source views specified by From_View. In this case, the value of
Create_Combined_View must be False.
The value of Create_Load_View is ignored when the Make_Path command is
entered in a system or in a combined subsystem. Systems can contain only
system views and combined subsystems can contain only combined views.
Create_Combined_View : Boolean := False;
Specifies whether to create working combined views instead of working load
views.
If Create_Combined_View is False (the default value), the type of view
created depends on the value of the Create_Load_View parameter. However,
if both parameters are False, a new combined view is created from each
combined view specified by From_Path, and a new load view is created from
each load or spec view specified by From_Path.
If Create_Combined_View is True, a new combined view is created from each
of the source views specified by From_View. In this case, the value of
Create_Load_View must be False.
The value of Create_Combined_View is ignored when the Make_Path command is
entered in a system. Systems can contain only system views.
Only_Change_Imports : Boolean := True;
Specifies the manner in which the views specified by the View_To_Import
parameter are actually used as imports by the new working views.
Only_Change_Imports has no effect if View_To_Import specifies
"<INHERIT_IMPORTS>" or the null string.
If this parameter is False, the entire list of views given by
View_To_Import is imported by each new working view created by the
Make_Path procedure. No imports are inherited.
If the parameter is True (the default value):
* Each new working view inherits its imports from the view from which it
was copied.
* The list of views in View_To_Import is compared to the inherited views.
If a View_To_Import view is from the same subsystem as an inherited
view, the View_To_Import view replaces that inherited view.
Thus, if Only_Change_Imports is True, the list of views in View_To_Import
is used to update the inherited imports of each new working view. In this
way, the replacement imports for every new working view can be specified in
a single list without forcing each new view to import everything in the
list.
Model : String := "<INHERIT_MODEL>";
Specifies a model world for the views in the new path. If the specified name
cannot be resolved in the context !Model, the name is resolved relative to
the current context. By default, the new working view uses the same model
as the view from which it was copied.
Join_Paths : Boolean := True;
Specifies whether to join each new working view to the view from which it
was copied.
If True (the default value), the controlled objects in each From_Path view
are joined to the corresponding objects in the copied working view. The
reservation token from the From_Path view is used. If a From_Path view
contains no controlled objects, then no objects can be joined. Note that
Join_Paths affects only controlled objects that exist at the time the
Make_Path command is executed. Objects created after the path is made must
be controlled explicitly and joined using the Make_Controlled and Join
commands.
If False, new reservation tokens are created for all of the controlled
objects. The value for New_Path_Name is used as the reservation token.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted by adjusting
imports.
If True (the default value), units are recompiled to the state specified by
the Goal parameter.
If False, any units demoted by adjusting imports are left in the demoted
state.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The compilation goal can be any of the enumerations of the
Compilation.Unit_State type, except Compilation.Archived. By default, the
compilation goal is the coded state. To set the compilation goal to the
installed state, specify Compilation.Installed. If Compilation.Source is
specified, all units in the view are put in the source state, regardless of
the value of the Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date the path was made
and the username and session in which the command was entered. If the
Comments parameter is specified, this comment also is entered in the work
order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to make the new paths. The default value
specifies that the new paths should be created on the volume with the most
free space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Join
procedure Merge_Changes
procedure Sever
@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>");
DESCRIPTION
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. Note that:
* 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.
* If you want to export units that reside in a different subdirectory
than the Units subdirectory, you must specify these units in the
State.Exports file using an appropriate fully qualified or relative
pathname. Because names in the State.Exports file are resolved relative
to the Units directory, you can use a relative pathname of the form
^.Subdirectory_Name.Simple_Name.
The units in each new spec view are compiled according to the
Remake_Demoted_Units and Goal parameters.
If a new spec view is created from another spec view that contains
controlled objects, the objects in the new spec view are made controlled
and joined to their counterparts in the source view. In contrast, if a new
spec view is created from a working or released view that contains
controlled objects, the objects in the new spec view are left
uncontrolled. If these objects 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.
RCI Behavior
When working with RCI views, the Ftp.Remote_Machine and
Ftp.Remote_Directory library switches in the new spec view are set when
the source view's library switch file is copied. Alternate values for
Ftp.Remote_Machine and Ftp.Remote_Directory can be specified by using
Rci_Cmvc.Make_Spec_View instead of Cmvc.Make_Spec_View.
PARAMETERS
From_Path : String := "<CURSOR>";
Specifies the view or views from which spec views are to be made. The
default is the view on which the cursor is located. The From_Path
parameter can name any view in a spec/load subsystem:
* Either load, spec, or combined views
* Either working or released views
* Views belonging to paths or views belonging to subpaths
All controlled objects in a From_Path view must be checked in. If
From_Path names multiple views, a new spec view is made from each of the
named views. Multiple views can be in the same or in different subsystems.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Spec_View_Prefix : String := ">>PREFIX<<";
Specifies the string that replaces both the path and subpath portion of the
names listed in the From_Path parameter. For example, if From_Path
specifies the string "Rev1_Anderson_Working", the value of Spec_View_Prefix
replaces "Rev1_Anderson" in the name of the new spec view.
The default parameter placeholder ">>PREFIX<<" must be replaced or an
error will result.
Level : Natural := 0;
Specifies which level number to increment within each spec view's name. The
automatic insertion of level numbers can be suppressed by setting Level to
Natural'Last.
Level numbers in a spec-view name are generated from the level numbers in
the name of the most recently released view. Note that a released-view
name contains as many numbers as there are release levels; the rightmost
number is the 0th level. In a spec-view name, the string "_Spec" replaces
the rightmost (0th level) number, so a spec-view name has one number less
than a released-view name.
If Level is 0, no release level numbers are incremented, because the
0th-level number has been replaced. In this case, the spec-view name
contains the same numbers (starting with level 1) as the most recent
release. If Level is 1, the first-level number in the most recent release
name is incremented before the appropriate level numbers are inserted into
the spec-view name. The number of levels that can be incremented is
determined by the Levels file within the model world for the view. The
Make_Spec_View command quits if the value of the Level parameter exceeds
the total number of levels specified by the Levels file.
For example, assume that there are two release levels and the most
recently released view is called Rev1_4_2. If a new spec view is created
and Level is 1, the name generated for the spec view is Rev1_5_Spec
(assuming that the Spec_View_Prefix parameter specifies the string "Rev1").
View_To_Modify : String := "";
Specifies one or more spec, load, or combined views whose imports should be
changed to refer to the new spec views. The imports of the views specified
by View_To_Modify are also updated using the views named by the
View_To_Import parameter. The View_To_Modify views are updated by
View_To_Import views as if the Only_Change_Imports parameter were True,
regardless of this parameter's actual value.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
View_To_Import : String := "<INHERIT_IMPORTS>";
Specifies one or more spec or combined views to be imported by the new spec
views. The views named by View_To_Import are also used to update the
imports of the views named by the View_To_Modify parameter.
If View_To_Import specifies the default special name "<INHERIT_IMPORTS>",
each new spec view uses the same imports as the view from which it was
copied.
If View_To_Import specifies the null string ("") or a string consisting of
single space (" "), no views are imported.
If View_To_Import specifies one or more views, the specified views are
imported by the new spec views in the manner specified by the
Only_Change_Imports parameter.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. Furthermore,
View_To_Import can name an activity as an indirect file, which is
equivalent to naming the spec view associated with each subsystem listed
in the activity.
Only_Change_Imports : Boolean := True;
Specifies the manner in which the views specified by the View_To_Import
parameter are actually used as imports by the new spec views.
Only_Change_Imports has no effect if View_To_Import specifies
"<INHERIT_IMPORTS>" or the null string.
If this parameter is False, the entire list of views given by
View_To_Import is imported by each new view created by the Make_Spec_View
command. No imports are inherited.
If the parameter is True (the default value):
* Each new spec view inherits its imports from the view from which it was
copied.
* The list of views in View_To_Import is compared to the inherited views.
If a View_To_Import view is from the same subsystem as an inherited
view, the View_To_Import view replaces that inherited view.
Thus, if Only_Change_Imports is True, the list of views in View_To_Import
is used to update the inherited imports of each new spec view. In this
way, the replacement imports for every new spec view can be specified in a
single list without forcing each new view to import everything in the
list.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted by adjusting
imports.
If True (the default value), units are recompiled to the state specified by
the Goal parameter.
If False, any units demoted by adjusting imports are left in the demoted
state.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The compilation goal can be any of the enumerations of the
Compilation.Unit_State type, except Compilation.Archived. By default, the
compilation goal is the coded state. To set the compilation goal to the
installed state, specify Compilation.Installed. If Compilation.Source is
specified, all units in the view are put in the source state, regardless of
the value of the Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date when the spec view
was made and the username and session in which the command was entered. If
the Comments parameter is specified, this comment also is entered in the
work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to make the new spec views. The default value
specifies that the new views should be created on the volume with the most
free space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
RCI Behavior
When working with an RCI view, the subpath is a combined view.
The following additional actions take place when working with RCI views:
* Cmvc.Make_Subpath attempts to set the Ftp.Remote_Machine library switch
in the new view. The value for this switch is obtained by looking in:
- Rci.Custom_Key_Default_Machine switch (one for each registered
target key in a host library) in the host view's enclosing library
compiler switches. The RCI traverses the enclosing libraries until
it finds a nonnull switch value.
- Session_Rci.Custom_Key_Default_Machine (one for each registered
target per session). The RCI uses this value if it does not find a
nonnull value in the library compiler switches.
Cmvc.Make_Subpath similarly attempts to set the Ftp.Remote_Directory
library switch.
* Values for Ftp.Remote_Machine and Ftp.Remote_Directory can be
explicitly specified by using Rci_Cmvc.Make_Subpath instead of
Cmvc.Make_Subpath.
* If the following items are true, a remote library is also constructed:
- Remote extensions management is enabled
- The remote username and password are set in the user's session
switches or in the Remote_Passwords file.
- The default switch naming scheme (outlined above) provides values
for Remote_Machine and Remote_Directory.
If any of the above is not true, or if for any other reason the remote
library cannot be built, it is not possible to bring units to the coded
state in the combined view until the remote library is built explicitly
by the user and the other conditions are corrected.
* This library management operation is affected by the values of the
following switches:
- Operation_Mode (to determine Batch or Interactive mode)
- Session_Rci.Auto_Create_Remote_Directory switch (for view creation)
- Rci.Host_Only switch (for existing views)
Operations may also vary depending on values specific to your
extension. See your extension user guide or your customizer for more
information.
PARAMETERS
From_Path : String := "<CURSOR>";
Specifies the view or views that are to be copied as the beginning(s) of
new subpath(s). The default is the view on which the cursor is located.
The From_Path parameter can name:
* Combined or load views only (not spec views).
* Either working or released views.
* Views belonging to paths or views belonging to subpaths. However, if
From_Path names a subpath, the new subpaths are created at the same
level, not as "subsubpaths."
All controlled objects in a From_Path view must be checked in. If
From_Path names multiple views, a new subpath (with the same subpathname
extension) is made from each of the named views. Multiple views can be in
the same or in different (sub)systems.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
New_Subpath_Extension : String := ">>SUBPATH<<";
Specifies the subpathname extension to be used in constructing the names of
the views in the new subpaths. Because the Make_Subpath procedure creates
new working views, the names of these views are constructed by inserting
New_Subpath_Extension between the pathname prefix and the "_Working" suffix.
For example, if the From_Path parameter specifies a view called
"Rev2_Working" and New_Subpath_Extension has the value "Anderson", the
working view created for the new subpath is "Rev2_Anderson_Working". If
From_Path names multiple views, all of the new paths will have the same
subpathname extension.
The New_Subpath_Extension parameter can be any string that constitutes a
legal Ada identifier and therefore can contain one or more underscore
characters. However, the underscores preceding and following the
subpathname extension are inserted automatically.
The New_Subpath_Extension is inserted after a pathname prefix, which, by
convention, is the portion of a view name up to the first underscore in the
name. The New_Subpath_Extension thus replaces any characters between the
first underscore and the "_Working" suffix. For example, if From_Path is
"Target_2_Working" and New_Subpath_Extension is "Anderson", the
subpathname is "Target_Anderson_Working".
View_To_Modify : String := "";
Specifies one or more spec, load, or combined views whose imports should be
changed to refer to the new working views, if those new views are combined
views. The imports of the views specified by View_To_Modify are also
updated using the views named by the View_To_Import parameter. The
View_To_Modify views are updated by View_To_Import views as if the
Only_Change_Imports parameter were True, regardless of this parameter's
actual value.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
View_To_Import : String := "<INHERIT_IMPORTS>";
Specifies one or more spec or combined views to be imported by the new
working views. The views named by View_To_Import are also used to update
the imports of the views named by the View_To_Modify parameter.
If View_To_Import specifies the default special name "<INHERIT_IMPORTS>",
each new working view uses the same imports as the view from which it was
copied. (However, if the From_Path parameter names multiple combined views
among which import relations hold, the imports are automatically adjusted
so that the working views in the new subpaths reference each other as
appropriate, instead of referencing the working views in the original
paths.)
If View_To_Import specifies the null string ("") or a string consisting of
single space (" "), no views are imported.
If View_To_Import specifies one or more views, the specified views are
imported by the new working views in the manner specified by the
Only_Change_Imports parameter.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file. Furthermore,
View_To_Import can name an activity as an indirect file, which is
equivalent to naming the spec view associated with each subsystem listed
in the activity.
Only_Change_Imports : Boolean := True;
Specifies the manner in which the views specified by the View_To_Import
parameter are actually used as imports by the new working views.
Only_Change_Imports has no effect if View_To_Import specifies
"<INHERIT_IMPORTS>".
If this parameter is False, the entire list of views given by
View_To_Import is imported by each new working view created by the
Make_Subpath command. No imports are inherited.
If the parameter is True (the default value):
* Each new working view inherits its imports from the working view from
which it was copied.
* The list of views in View_To_Import is compared to the inherited views.
If a View_To_Import view is from the same subsystem as an inherited
view, the View_To_Import view replaces that inherited view.
Thus, if Only_Change_Imports is True, the list of views in View_To_Import
is used to update the inherited imports of each new working view. In this
way, the replacement imports for every new working view can be specified in
a single list without forcing each new view to import everything in the
list.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted by adjusting
imports. If True (the default value), units are recompiled to the state
specified by the Goal parameter. If False, any units demoted by adjusting
imports are left in the demoted state.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The compilation goal can be any of the enumerations of the
Compilation.Unit_State type, except Compilation.Archived. By default, the
compilation goal is the coded state. To set the compilation goal to the
installed state, specify Compilation.Installed. If Compilation.Source is
specified, all units in the view are put in the source state, regardless of
the value of the Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date when the subpath was
made and the username and session in which the command was entered. If the
Comments parameter is specified, this comment also is entered in the work
order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to make the new subpaths. The default value
specifies that the new subpaths should be created on the volume with the
most free space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc.Make_Uncontrolled
procedure Make_Uncontrolled (What_Object : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
DESCRIPTION
Makes the specified objects uncontrolled, so that change information about
them is no longer collected in the CMVC database.
Existing history for a formerly controlled object remains in the CMVC
database until you expunge the database using the
Cmvc_Maintenance.Expunge_Database command. You can access this history if
you recontrol the object using the Make_Controlled command with the
object's original reservation token specified (the recontrolled object's
history will continue where the original history left off).
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.
PARAMETERS
What_Object : String := "<CURSOR>";
Specifies the object(s) to be made uncontrolled. Multiple objects can be
specified by using wildcards, context characters, special names, set
notation, or an indirect file.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Make_Controlled
procedure Cmvc_Maintenance.Expunge_Database
@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>");
DESCRIPTION
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:
* Added lines are marked by the + character.
* Deleted lines are redisplayed, marked with the - character.
* Each changed line is indicated as a deleted line followed by an added
line.
* 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:
* The number 1 indicates changes that were merged from the source object.
* The number 2 indicates changes that existed in the destination object.
* 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.
PARAMETERS
Destination_Object : String := "<SELECTION>";
Specifies the object into which changes are to be merged. If a member of a
join set, the specified object must be at the most recent generation (that
is, all changes must already be accepted from the other objects in the
join set). If the object named by the Destination_Object parameter
currently is checked out, the Merge_Changes command automatically checks
it in.
The default is the currently selected object.
Source_View : String := ">>VIEW_NAME<<";
Specifies the view containing the object whose changes are to be merged
into the destination object. The object in the designated view must be
checked in.
Report_File : String := "";
Specifies the name for the report file generated by the merge operation. The
default value ("") allows the command to generate the filename by appending
the string _Merging_Report to the simple name of the destination object.
The file is created in the same library as the destination object.
Fail_If_Conflicts_Found : Boolean := False;
Specifies whether the command should fail to update the destination object
if conflicting changes are found.
If True, the command produces the report file without actually updating the
destination object. If False (the default value), the command both updates
the destination object and produces the report file even if conflicts are
found.
Comments : String := "";
Specifies a comment to be stored in the CMVC database with the notes for
the specified object(s). This comment appears in the display generated by
the Show_History_By_Generation command.
In addition, the specified comment is logged in the work order indicated by
the Work_Order parameter.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Accept_Changes
@node !Commands.Cmvc.Notes
procedure Notes (What_Object : String := "<CURSOR>";
In_Place : Boolean := False);
DESCRIPTION
Displays the history image for the current generation of the specified
controlled object.
A history image for a generation contains:
* 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
* 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_Window, 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.
PARAMETERS
What_Object : String := "<CURSOR>";
Specifies the view or object for which to display the history image. A
configuration object also can be specified, even if the corresponding view
no longer exists. If an object is specified, it must be controlled and it
can be checked out.
The default is the object or view on which the cursor is currently
located.
In_Place : Boolean := False;
Specifies whether the current frame should be used to display the image.
The default specifies that the least recently used frame should be used.
@node !Commands.Cmvc.Put_Notes
procedure Put_Notes (From_File : String := "<WINDOW>";
What_Object : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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:
* 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.
* 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.
PARAMETERS
From_File : String := "<WINDOW>";
Specifies where to find the new notes for the specified object. If this
parameter names a file, the contents of that file replace the existing notes
for the specified controlled object.
If the default special name "<WINDOW>" is used, it refers to the contents
of a notes window created by either the Get_Notes or the
Create_Empty_Note_Window command. When the default value is used,
Put_Notes must be entered from a command window attached to the notes
window. The first line of the notes window contains the name of the object
associated with the notes; therefore, the What_Object parameter is
ignored.
What_Object : String := "<CURSOR>";
Specifies the object whose notes are to be replaced. The specified object
must be both controlled and checked out; otherwise, the command quits.
The What_Object parameter is ignored if the From_File parameter's default
value is used.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Append_Notes
procedure Create_Empty_Note_Window
procedure Get_Notes
procedure 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>");
DESCRIPTION
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 Release command creates
two objects in the directory (sub)system_name.Configurations. These objects
are:
* A configuration object named release_name.
* 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.
RCI Behavior
When operating on an RCI view with Create_Configuration_Only set to False,
this command performs the following additional operations:
* Releases the associated remote library
* Releases secondary referencers
* Cmvc.Release attempts to set the Ftp.Remote_Machine library switch in
the released view. The value for this switch is obtained by looking in:
- Rci.Custom_Key_Default_Machine switch (one for each registered
target key in a host library) in the host view's enclosing library
compiler switches. The RCI traverses the enclosing libraries until
it finds a nonnull switch value.
- Session_Rci.Custom_Key_Default_Machine (one for each registered
target per session). The RCI uses this value if it does not find a
nonnull value in the library compiler switches.
Cmvc.Release similarly attempts to set the Ftp.Remote_Directory library
switch.
* Values for Ftp.Remote_Machine and Ftp.Remote_Directory can be
explicitly specified by using Rci_Cmvc.Release instead of Cmvc.Release.
* If the following items are true, a remote library is also constructed:
- Remote extensions management is enabled
- The remote username and password are set in the user's session
switches or in the Remote_Passwords file.
- The default switch naming scheme (outlined above) provides values
for Remote_Machine and Remote_Directory.
If any of the above is not true, or if for any other reason the remote
library cannot be built, it is not possible to bring units to the coded
state in the combined view until the remote library is built explicitly
by the user and the other conditions are corrected.
* This library management operation is affected by the values of the
following switches:
- Operation_Mode (to determine Batch or Interactive mode)
- Session_Rci.Auto_Create_Remote_Directory switch (for view creation)
- Rci.Host_Only switch (for existing views)
Operations may also vary depending on values specific to your
extension. See your extension user guide or your customizer for more
information.
PARAMETERS
From_Working_View : String := "<CURSOR>";
Specifies one or more working views from which released views are to be
created. Multiple working views can be in the same or in different
(sub)systems. From_Working_View can specify either combined or load views.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Release_Name : String := "<AUTO_GENERATE>";
Specifies the simple name of the new released view(s).
The default special name "<AUTO_GENERATE>" allows new release names to be
generated automatically. An automatically generated name consists of the
path or subpathname (the portion of the view name up to "_Working")
followed by "_n_m", where n and m represent automatically incremented
level numbers. (The Level parameter controls how these numbers are
incremented. The number of levels that can be incremented is determined by
the Levels file within the model world for the view.)
If the From_Working_View parameter names multiple views and Release_Name
has a nondefault value, all of the new released views will have the same
simple name. In contrast, if Release_Name has the default value, the name
of each new released view is generated individually.
Level : Natural := 0;
Specifies which level number to increment within each released view's name.
The Level parameter is ignored if a nondefault value of the Release_Name
parameter is specified.
The default Level value (0) means that the rightmost number is
incremented. If Level is 1, the next-to-rightmost number is incremented
and so on. Level numbers to the right of the incremented number are reset
to 0.
For example, assume that the previously released view was called Rev1_4_2.
If a new release is created from Rev1_Working and Level is 0, the name
generated for the next release is Rev1_4_3. If a subsequent release is
created from Rev1_Working and Level is 1, the name generated for this next
release is Rev1_5_0. (Note that the portion of the name up to "_Working"
is fixed, so the "1" in "Rev1" is not subject to being incremented.)
The number of levels that can be incremented is determined by the Levels
file within the model world for the view. The Release command quits if the
value of the Level parameter exceeds the total number of levels specified
by the Levels file.
Views_To_Import : String := "<INHERIT_IMPORTS>";
Specifies one or more spec or combined views for the new releases to
import. The default special name "<INHERIT_IMPORTS>" means that each new
released view will have the same imports as the working view from which it
was released.
Note that if the From_Working_View parameter names multiple combined views
among which import relations hold, the imports are automatically adjusted
so that the new releases reference each other as appropriate, instead of
referencing the working views.
Imports can be changed during the release operation by specifying a
nondefault value for Views_To_Import. However, care must be taken to
import views that allow the released views to compile.
Views_To_Import can name an activity as an indirect file; if so, the new
releases will import the spec view associated with each subsystem, as
listed in the activity.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Create_Configuration_Only : Boolean := False;
Specifies whether to save space by creating only the configuration object
and the associated state description directory for each specified working
view.
If True, only the configuration object and directory are created. A full
released view is not created at this time; if desired, the view must be
built by a subsequent Build operation. (Note, however, that a configuration
object references only the controlled objects in a view; therefore, Build
can recreate only the controlled objects for which source has been saved.)
Creating only a configuration is much faster than making a view.
If False (the default value), a full released view is created in addition
to the configuration object and directory.
Whether or not a view is created in addition to the configuration object,
the contents of a configuration can be viewed through a configuration image
(see the Edit command).
Compile_The_View : Boolean := True;
Specifies whether to compile all the units in the specified released views
before freezing these views.
If True (the default value), an attempt is made to compile the units to
the state specified by the Goal parameter. For example, setting
Compile_The_View to True recompiles any units that were demoted by
changing imports (that is, by specifying a nondefault value for the
Views_To_Import parameter). The views are subsequently frozen even if
compilation fails.
If False, units remain demoted.
Unless you are making a configuration-only release, it is recommended that
this parameter be left as True to guarantee that released views can be
executed.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which units are compiled when the Compile_The_View
parameter is True. The compilation goal can be any of the enumerations of
the Compilation.Unit_State type. By default, the compilation goal is the
coded state. To compile units to the installed state, specify
Compilation.Installed. If Compilation.Source or Compilation.Archived is
specified, all units in the view are put into this state, regardless of the
value of the Compile_The_View parameter.
Comments : String := "";
Specifies a comment to be stored in the CMVC database. In particular, the
comment is stored with the notes for the history files that are associated
with the specified working views. The history file for each view is called
view_name.State.Release_History. The notes can be viewed with the
Get_Notes command.
The comment is also logged in the work order indicated by the Work_Order
parameter. The comment appears with the checkin of the history file.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records when the history files were checked out
and in, the name of the new release, and the username and session in which
the command was entered. If the Comments parameter is specified, this
comment also is entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Volume : Natural := 0;
Specifies the volume on which to create the new releases. The default value
specifies that the releases should be created on the volume with the most
free space.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
RCI Behavior
For RCI operations, this command removes an import from the host view and
from the view's associated remote library. This operation also may affect
the remote program-library state, depending on the specific RCI extension.
PARAMETERS
View : String := ">>VIEW NAME<<";
Specifies one or more views to be removed from the imports of the view
specified by the From_View parameter. The default parameter placeholder
must be replaced or an error will result.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
From_View : String := "<CURSOR>";
Specifies one or more views from which the specified imports are to be
removed. Imports cannot be removed from code views. The default is the
view designated by the cursor.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Remove_Unused_Imports
@node !Commands.Cmvc.Remove_Unused_Imports
procedure Remove_Unused_Imports
(From_View : String := "<CURSOR>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
To determine whether a link is required for compilation in a view, the
Remove_Unused_Imports procedure scans the with clauses in the units of
that view. This procedure skips over all units in the archived state; in a
spec view, this procedure skips over the with clauses that occur after
pragma Private_Eyes_Only.
A link is required for compilation if it is referenced in a with clause in
at least one unit that is in the source, installed, or coded state.
Compare this with the Remove_Import command, which is sensitive only to
units that actually are compiled against the link.
PARAMETERS
From_View : String := "<CURSOR>";
Specifies one or more views from which unused imports are to be removed.
Imports cannot be removed from code views. The default is the view
designated by the cursor.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Remove_Import
@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>");
DESCRIPTION
Replaces the model world for the specified view.
A view's model can be changed to:
* Invoke a new switches file for the view.
* Rebuild the view's links. Note that if the new model introduces links
that conflict with existing links created by imports, the conflicts are
resolved in favor of the the existing, import-created links.
* Reset the number of levels for automatic name generation for released
and spec views. (This affects only future releases.)
* 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.
PARAMETERS
New_Model : String := ">>NEW MODEL NAME<<";
Specifies the name of the world to be used as the model for the view. The
context for the resolution of this name is the world !Model, although a
model in another world can be specified by using a fully qualified name.
The default parameter placeholder ">>NEW MODEL NAME<<" must be replaced or
an error will result.
In_View : String := "<CURSOR>";
Specifies the view whose model is to be replaced. The default is the view
designated by the cursor.
All units in the view must be in the source state.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
RCI Behavior
For the RCI, if the file that is being reverted is a secondary text file,
then the primary associated with the file is demoted.
PARAMETERS
What_Object : String := "<SELECTION>";
Specifies the object or objects to be reverted. Only controlled and sourced
objects can be reverted. (An error is reported if you try to revert an
object that was made controlled without saving source.) An object that is
currently checked out cannot be reverted, and this is reported in the
output log. By default, the selected object is reverted.
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
To_Generation : Integer := -1;
Specifies the generation to which the specified object is reverted. A
positive integer expresses a particular generation number (each generation
is numbered, starting from 0). A negative integer expresses a previous
generation, counting back from the object's current generation; for
example, the default value of -1 indicates the object's previous
generation.
If multiple objects are specified and the To_Generation parameter has a
positive value, the Revert procedure attempts to change all objects to the
same generation. If multiple objects are specified and To_Generation has a
negative value, the generation of each object is calculated individually.
Make_Latest_Generation : Boolean := False;
Specifies whether to retain To_Generation as the latest generation. If
True, To_Generation becomes the latest generation, from which subsequent
development can proceed. (In this case, the Revert procedure is equivalent
to checking out an object, copying the specified generation into the
object, and checking it in.)
If False, To_Generation does not become the latest generation.
Consequently, a reverted object can be inspected or compiled against other
units; however, the next time the object is checked out, it is updated to
the latest generation. (In this case, the Revert procedure is equivalent
to using the Accept_Changes command to update an object from a
configuration containing the specified generation.)
Allow_Demotion : Boolean := False;
Specifies whether the Revert procedure is allowed to demote Ada units in
order to revert the specified objects to the specified generation.
If this parameter is True, the Revert procedure is permitted to demote Ada
units if necessary. If it is False, the command proceeds only if no
demotion is required; otherwise, an error is reported and the command
quits.
Remake_Demoted_Units : Boolean := True;
Specifies whether to recompile any units that were demoted in the process
of reverting the specified objects.
If True (the default value), demoted units are recompiled to the state
specified by the Goal parameter. If False, units remain demoted.
Goal : Compilation.Unit_State := Compilation.Coded;
Specifies the state to which demoted units are recompiled when the
Remake_Demoted_Units parameter is True.
The goal can be any of the enumerations of the Compilation.Unit_State
type, except Compilation.Archived. By default, the compilation goal is the
coded state. To set the compilation goal to the installed state, specify
Compilation.Installed. If Compilation.Source is specified, the demoted
units are put in the source state, regardless of the value of the
Remake_Demoted_Units parameter.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date, the unit reverted,
and the username and session in which the command was entered. If the
Comments parameter is specified, this comment also is entered in the work
order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc.Sever
procedure Sever
(What_Object : String := "<SELECTION>";
New_Reservation_Token_Name : String := "<AUTO_GENERATE>";
Comments : String := "";
Work_Order : String := "<DEFAULT>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
What_Object : String := "<SELECTION>";
Specifies one or more objects to be severed. By default, the selected
object is severed. If a view is specified, all the objects in the view are
severed.
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
New_Reservation_Token_Name : String := "<AUTO_GENERATE>";
Specifies the name of the reservation token to be associated with each
newly severed object.
The default special name "<AUTO_GENERATE>" means that the reservation
token is generated automatically by the Environment. Automatically
generated names of reservation tokens are derived from the first portion of
the enclosing view name (up to the first underscore character). For
example, the severed objects in a view called Rev1_Working would have
"Rev1" as the automatically generated name of the reservation token.
However, if "Rev1" is currently in use, then "Rev1_1" is generated.
A user-defined token name can be supplied instead to provide subsequent
join sets with more meaningful or mnemonic token names.
Note that supplying an existing reservation token name cannot be used to
implicitly join the newly controlled objects to any other objects.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. More
specifically, the work order records the time and date of checkin, the
objects affected, and the username and session in which the command was
entered. If the Comments parameter is specified, this comment also is
entered in the work order.
The special name "<DEFAULT>" refers to the default work order for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc.Show
procedure Show (Objects : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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
Source Saved
============
Yes
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 In Displays the value that was
supplied for the
Expected_Check_In_Time parameter
of the Check_Out command.
Source Saved Indicates whether or not source is
being saved in the CMVC database
for the object (see the
Make_Controlled command).
The Show command also displays the names of the views to which the
specified objects are joined.
PARAMETERS
Objects : String := "<CURSOR>";
Specifies the objects for which information is displayed. If a view is
specified, information is displayed for the objects in the Units directory
as well as for the Release_History file in the State directory.
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc.Show_All_Checked_Out
procedure Show_All_Checked_Out (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
In_View : String := "<CURSOR>";
Specifies one or more views whose checked-out objects are to be listed.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Show
@node !Commands.Cmvc.Show_All_Controlled
procedure Show_All_Controlled (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
Lists the controlled objects in the specified view or views.
The objects are listed in the same format used by the Show command.
PARAMETERS
In_View : String := "<CURSOR>";
Specifies one or more views whose controlled objects are to be listed.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Show
@node !Commands.Cmvc.Show_All_Uncontrolled
procedure Show_All_Uncontrolled (In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
Lists all uncontrolled objects in the specified views.
PARAMETERS
In_View : String := "<CURSOR>";
Specifies one or more views.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
PARAMETERS
In_View : String := "<CURSOR>";
Specifies one or more views to be searched for objects checked out by the
specified user.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Who : String := "System_Utilities.User_Name";
Specifies the username whose checked-out objects are to be listed.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Show
@node !Commands.Cmvc.Show_Checked_Out_In_View
procedure Show_Checked_Out_In_View
(In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
In_View : String := "<CURSOR>";
Specifies one or more views whose checked-out objects are to be listed.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Show
@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>");
DESCRIPTION
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):
* The join set name (the name of the reservation token for the joined
objects)
* 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:
* The time and date of the checkout and checkin that created the
generation
* The notes for the object
* The changes that occurred since the previous generation (if requested
by the Display_Change_Regions parameter)
PARAMETERS
For_Objects : String := "<CURSOR>";
Specifies the object or objects whose history is to be displayed. This
parameter can specify one or more views or one or more controlled objects
within a view. The default is the object on which the cursor is located.
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Display_Change_Regions : Boolean := True;
Specifies whether to display the differences between a given generation and
the one before it.
If True (the default value), the text of the changes is displayed in the
same format as that produced by the
!Commands.File_Utilities.Difference(Compressed_Output=>\
True) procedure (see the LM book of the Rational Environment Reference
Manual). If False, no changes are displayed.
Starting_Generation : String := "<CURSOR>";
Specifies the view or configuration that serves as the starting point for
the displayed history. The specified view or configuration must contain some
generation of each of the objects designated by the For_Objects parameter.
The Show_History procedure displays the history for each object, starting
with changes to the generation contained in the specified view or
configuration.
The default is the view or configuration on which the cursor is located. If
the null string ("") is used, the display starts at generation 1.
Ending_Generation : String := "";
Specifies the view or configuration that serves as the ending point for the
displayed history. The specified view or configuration must contain some
generation of each of the objects designated by the For_Objects parameter.
The history displayed for each object ends with the generation contained
in the specified view or configuration.
The default value ("") specifies that history is displayed up to the latest
generation.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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):
* The join set name (the name of the reservation token for the joined
objects)
* 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:
* The time and date of the checkout and checkin that created the
generation
* The notes for the object
* The changes that occurred since the previous generation (if requested
by the Display_Change_Regions parameter)
PARAMETERS
For_Objects : String := "<CURSOR>";
Specifies the object or objects whose history is to be displayed. This
parameter can specify one or more views or one or more controlled objects
within a view. The default is the object on which the cursor is located.
Multiple objects can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Display_Change_Regions : Boolean := True;
Specifies whether to display the differences between a given generation and
the one before it.
If True (the default value), the text of the changes is displayed in the
same format as that produced by the
!Commands.File_Utilities.Difference(Compressed_Output=> True) procedure
(see the Library Management (LM) book of the Rational Environment
Reference Manual). If False, no changes are displayed.
Starting_Generation : Natural := 1;
Specifies the number of the generation to serve as the starting point for
the displayed history. The default value (1) causes history to be
displayed from generation 1 of the specified objects.
If the For_Objects parameter specifies multiple objects, the displayed
history of each object begins with the same generation number, as specified
by Starting_Generation.
Ending_Generation : Natural := Natural'Last;
Specifies the number of the generation to serve as the ending point for the
displayed history. The default value (Natural'Last) causes history to be
displayed up to the most recent generation of the specified objects.
If the For_Objects parameter specifies multiple objects, the displayed
history of each object ends with the same generation number, as specified
by Ending_Generation.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
PARAMETERS
Object : String := "<CURSOR>";
Specifies the object for which a previous generation is displayed. The
default is the object on which the cursor is located.
Generation : Integer := -1;
Specifies the generation of the specified object that is to be
reconstructed. The default value specifies the generation before the
current generation of Object.
A negative number specifies a previous generation relative to the object's
current generation. For example, a value of -3 displays the third
generation back from the current one.
A positive number specifies an actual generation number.
Output_Goes_To : String := "<WINDOW>";
Specifies where to put the text of the reconstructed generation. If a new
filename is specified, a file is created and the text is written into it. If
an existing filename is specified, the contents of that file are replaced.
If the default special name "<WINDOW>" is used, the reconstructed
generation is displayed in the window containing the output log.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc.Show_Out_Of_Date_Objects
procedure Show_Out_Of_Date_Objects
(In_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
In_View : String := "<CURSOR>";
Specifies one or more views whose out-of-date objects are to be listed.
Multiple views can be specified by using wildcards, context characters,
special names, set notation, or an indirect file.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Show
@node !Commands.Cmvc.System_Object_Enum
type System_Object_Enum is (Spec_Load_Subsystem,
Combined_Subsystem,
System);
DESCRIPTION
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.
ENUMERATIONS
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.
REFERENCES
procedure Initial
@node !Commands.Cmvc_Access_Control
Package Cmvc_Access_Control provides commands for applying access control
to objects in systems, subsystems, and views. With these commands, a
project leader or subsystem owner can specify who can visit, import,
create, modify, or destroy such objects. Furthermore, these commands can
be used to restrict the use of operations from packages Cmvc,
Cmvc_Maintenance, and Cmvc_Hierarchy.
The commands in package Cmvc_Access_Control are intended for either
interactive or programmatic use. Package Operator provides operations for
defining groups for access control (see SMU, package Operator). Finally,
package Access_List provides operations for managing access control
outside of subsystems (see LM, package Access_List).
RESOURCES IN PACKAGE CMVC_ACCESS_CONTROL
The commands in package Cmvc_Access_Control fall into several functional
groups. They are listed here for your convenience.
Managing CMVC access classes: Add_Group, Display, Has_Access,
Remove_Group
Utilities for managing CMVC access classes: Check, Get_Access, Group_Name,
Initialize, Is_Consistent
Managing individual execution rights: Add_Right, Has_Right, Remove_Right
Managing tables of execution rights: Get_Rights, Set_Rights
KEY CONCEPTS FOR PACKAGE CMVC_ACCESS_CONTROL
Developing a project under CMVC enables you to partition the project into
subsystems, track changes to the objects in each subsystem, record
development history along with these changes, and maintain multiple
working and released views within each subsystem. Package
Cmvc_Access_Control provides support for another important aspect of
project management--namely, the ability to restrict access to the
subsystems and views in the project.
An essential requirement for many projects is for each development team to
have relatively restricted access to other teams' work, while having
relatively unrestricted (or even unlimited) access to its own work. For
example, the following scenarios illustrate typical access-control needs:
* Two teams (A and B) are developing two subsystems and Team A's
subsystem needs to import a spec view from Team B's subsystem. The
project manager wants to give Team A enough access to import the
desired spec view but wants to prevent Team A from being able to modify
any of the views in the imported subsystem.
* A subsystem development team consists of two developers and a subsystem
integrator, and each of these three team members works in his or her
own development path within the subsystem. The project manager wants to
allow each team member to check out, edit, and check in objects in his
or her own path, without being able to modify anything in the other
paths. Furthermore, the project manager wants the subsystem
integrator--but not the other developers--to be able to accept changes
from the developers' paths into the main path and then make releases
from that path.
The basic access-control capability defined in package Access_List is not
powerful enough to completely support scenarios such as those described
above. At best, basic access control can be used to set the access lists
(ACLs) of objects in a subsystem individually. However, managing access at
the level of individual objects is impractical and error-prone due to the
complex structure of subsystems. Improperly set ACLs within subsystems can
cause CMVC commands to fail with confusing error messages. Finally,
package Access_List has no way to restrict or permit the execution of
individual CMVC commands such as Cmvc.Accept_Changes.
In contrast, scenarios like the preceding can be implemented using the
facilities in package Cmvc_Access_Control. These facilities extend basic
access control so that access can be managed at the level of subsystems
and views. That is, CMVC access control provides an automated way of
setting the proper ACLs for the objects in a subsystem or view, both for
user-created objects (such as Ada units) and for Environment-created
objects (such as those containing CMVC information used by the
Environment). Furthermore, these ACL settings are coordinated to support
each of four kinds of access that groups can have to specific views and
subsystems. CMVC access control also provides tools for ensuring that all
of the ACLs within a subsystem or view maintain the proper settings.
Finally, package Cmvc_Access_Control provides a means of tailoring each
group's ability to apply individual CMVC commands to specific subsystems or
views.
It is important to note that CMVC access control is an extension of basic
access control and is built on basic mechanisms like ACLs, access rights,
and groups. (See package Access_List, LM, for a description of these
mechanisms.) CMVC access control thus does not replace or circumvent these
basic access-control mechanisms, but rather manages them, in much the same
way that CMVC importing manages links. Consequently, the ACL settings
provided by CMVC access control affect non-CMVC operations (such as
archiving and compilation) in addition to CMVC-specific operations.
Structures That Can Be Controlled
Applications developed under CMVC exist in a hierarchy of Environment
structures. Such applications are partitioned into subsystems, which
typically contain multiple views. In addition, subsystems may be children
of systems, as described in package Cmvc_Hierarchy.
Putting applications under CMVC access control means granting groups
various kinds of access to individual views, subsystems, and systems.
Although these structures are related hierarchically, they are independent
with respect to CMVC access-control operations. That is, granting a group
access to a subsystem does not automatically grant access to any of the
views within it. Similarly, granting a group access to a system does not
automatically grant access to the subsystems that are its children.
The next sections cover basic information about CMVC access control for
views and subsystems. CMVC access control for systems is handled
separately in "CMVC Access Control and Systems," below. In general, the
information given below about subsystems applies to systems, and the
information about views applies to system views.
Access Classes
CMVC access control supports four kinds of access that groups can have to
views and subsystems. These kinds of access--called access
classes--correspond to four general ways in which groups participate in
project development under CMVC. As such, the four access classes support a
hierarchy of roles in the development process, where higher roles have
greater levels of responsibility and authority as well as greater numbers
of permitted operations. In brief:
* The Reader access class is for groups that must be able to inspect and
execute objects in views and subsystems.
* The Client access class is for groups that must be able to import views
from other subsystems.
* The Developer access class is for groups that must be able to check in,
check out, edit, and compile objects in views and subsystems.
* The Owner access class is for groups that must have complete control
over views and subsystems, including the ability to create, destroy,
change imports, and change the access to these structures.
A group must belong to one of these access classes for each view or
subsystem to which access is required. When a group belongs to an access
class for a view or subsystem, the group is granted specific access
rights--such as read (R) or read and write (RW) access--to the individual
objects in that structure. Taken together, the access rights to the
objects in a view or subsystem limit the set of operations--both general
and CMVC-related--that the group can apply to that view or subsystem. (See
the reference entry for type Access_Class for the specific sets of access
rights granted by each access class.)
Within the general limits imposed by the assigned access rights, further
optional controls called execution rights are available for restricting
the CMVC-specific operations. Execution rights constitute explicit
permission for a group to apply individual commands from packages Cmvc,
Cmvc_Hierarchy, and Cmvc_Maintenance to a given view or subsystem. By
default, a group is granted all of the execution rights allowed by its
access class; however, it is possible to revoke one or more individual
execution rights in order to restrict the group's CMVC capability. Thus,
while every group in a given access class has the same basic Environment
access to the objects in a given view or subsystem, the ability to execute
CMVC commands can be further restricted on a group-by-group basis. (See
the reference entry for type Execution_Right for a complete list of
execution rights; for lists of execution rights granted by each access
class, see the "Reference Summary for Package Cmvc_Access_Control" at the
end of this package introduction.)
A Basic Scenario
The following scenario illustrates the relationship between groups, access
classes, and structures like views and subsystems.
Assume that two users, Fred and Mary, are developing an application that
demonstrates planetary motion, which is calculated using various
algorithms. The application is partitioned into two subsystems called Demo
and Algorithms, both of which contain spec and load views. The spec and
load views from the Demo subsystem will need to import the spec view from
the Algorithms subsystem.
The development methodology for this application makes Fred responsible
for the Demo subsystem and Mary responsible for the Algorithms subsystem.
Their responsibilities require the following capabilities:
* Each developer must be able to check out, edit, check in, and compile
units within his or her own subsystem.
* Each developer must be able to inspect objects in the other subsystem
without being able to modify them.
* Both developers must be able to make releases, spec views, paths,
subpaths, and code views in their own subsystem; they must also be able
to check the consistency of or destroy these views.
* Fred must be able to perform import operations between the two
subsystems.
To obtain these capabilities, each developer must belong to one of the
four access classes for each subsystem and view in the application. Figure
1 summarizes the access-class assignments that support the desired
capabilities. (In this and the following figures, names like Fred and Mary
are group names; recall that every username also names a correponding
group with that user as a member.)
In particular, Figure 1 shows that Fred, who needs complete control over
the Demo subsystem, belongs to the Owner class for the Demo subsystem as
well as for each of the views in that subsystem. Mary, on the other hand,
belongs to the Reader class for the Demo subsystem and each of its views.
Furthermore, Figure 1 shows that Mary, who needs complete control over the
Algorithms subsystem, belongs to the Owner access class for that subsystem
and for each of its views. Fred, in turn, belongs to the Client access
class for this subsystem and for its views, so that he can import spec
views from this subsystem without being able to modify anything in it.
Demo
Owner: Fred
Reader: Mary
----------------------------------------------------
| |
| --------------------- |
| | Rev1_0_Spec | |
| | Owner: Fred | |
| | Reader: Mary | |
| | | |
| --------------------- |
| | |
| | --------------------- |
| | | | |
| | --------------------- | |
| | | | | |
| | --------------------- | | |
| | | Rev1_0_Working | |-- |
| | | Owner: Fred | | |
| | | Reader: Mary |-- |
| | | | |
| | --------------------- |
| | / |
---------------|---------/--------------------------
| /
Algorithms | /
Owner: Mary | /
Client: Fred | /
---------------|----/-------------------------------
| V V |
| --------------------- |
| | Rev1_0_Spec | |
| | Owner: Mary | |
| | Client: Fred | |
| | | |
| --------------------- |
| |
| --------------------- |
| | | |
| --------------------- | |
| | | | |
| --------------------- | | |
| | Rev1_Working | |-- |
| | Owner: Mary | | |
| | Client: Fred |-- |
| | | |
| --------------------- |
| |
----------------------------------------------------
Figure 1. Access_Class Assignments for Fred and Mary
As a result of these access-class assignments, specific access rights are
granted to Fred and Mary for the individual objects in these subsystems
and views. For example, because Fred has Owner access and Mary has Reader
access to Demo.Rev1_0_Spec, the access list (ACL) of each object in that
view contains the entries "Fred=>RW, Mary=>R".
In contrast, the entry "Mary=>RW" appears in the ACLs of all the objects
in Algorithms.Rev1_0_Spec, which Mary owns. Furthermore, because Fred has
Client access to this view, the ACLs of all but one object also contain
the entry "Fred=>R". The one exception is the view's State.Referencers
file, which is automatically updated whenever the view is imported. Client
access gives Fred read and write access to this file ("Fred=>RW"), so that
it can be updated by any import operation he executes.
It is important to note that Fred needs both Owner access to the views in
Demo and Client access to the views in Algorithms in order to import the
latter into the former. Owner access allows Fred to add, remove, or change
the imports of Demo's spec and working views; Client access allows Fred to
name Algorithm's spec view in an import operation. In addition, because he
has Client access to Algorithm's working view, Fred will automatically
have Client access to any spec views that are subsequently made from it.
(New views that are created from existing views inherit their access-class
assignments from the existing views.) However, with respect to the working
view itself (which cannot be imported), Client access is equivalent to
Reader access.
A Developer with Restricted Access
Now assume that a junior programmer, Tom, joins Mary to develop part of
the Algorithms subsystem. Tom is to work in his own subpath, where he will
develop and test his own units. When Tom has reached his development
milestones, Mary will accept changes from his subpath into the main
integration path (Rev1_Working), which she owns. When she has tested Tom's
work along with hers, she will make releases from the Rev1_Working path
(under this development methodology, no releases will be made from Tom's
subpath). Tom's capabilities are defined as follows:
* Tom must be able to check out, edit, check in, and compile units within
his subpath.
* He must be able to inspect (but not modify) objects in the main
integration path and in the spec view of the Algorithms subsystem.
* He must not be able to make releases or other kinds of views, such as
spec views, code views, paths, and the like. Nor should he be allowed
to destroy any views, including his own.
* He must not be able to inspect or modify objects in any of the views in
the Demo subsystem.
Figure 2 (see hardcopy document) shows the access-class assignments that
support these capabilities. As shown, Tom belongs to the Developer access
class for his subpath (Rev1_Tom_Working) and to the Developer access class
for the Algorithms subsystem. Furthermore, Tom belongs to the Reader access
class for the other views in Algorithms--namely, the main integration path,
its releases, and the spec view.
This combination of access-class assignments permits Tom to develop
controlled objects in his subpath, while limiting what he can do to the
subpath itself or to other views. In particular, Tom's Developer access to
both the subpath and the subsystem gives him just enough access to create,
edit, and perform CMVC operations on individual objects in his subpath.
However, to perform operations that affect the entire subpath (such as
changing its model or its import), Tom would need Owner access to the
subpath. Similarly, for operations affecting the contents of the
subsystem, such as creating or destroying views, Tom would need Owner
access to the subsystem as well.
Figure 2 shows that Tom has no access to the Demo subsystem or its views.
He is therefore unable to inspect or execute any objects in Demo. Because
of this lack of access, Tom can only perform unit-testing in his own
subpath; in particular, he cannot test his work against the entire
application. In order to do this, he would need at least Reader access to
any load or code view from Demo that is named in the application's
activity. Under the current access-class assignments, Mary and Fred are
the only ones able to execute the entire application.
Note that Fred is given no access to Tom's subpath. No direct access to
this subpath is needed, because Tom's work will always be integrated into
the working view of the main path. Furthermore, no releases or spec views
will be made from Tom's subpath, so no access classes need be set up for
such views to inherit.
Further Restrictions on Specific CMVC Operations
With Developer access both to the Algorithms subsystem and to his subpath,
Tom can check out objects in his subpath, check them in, make new objects
controlled, accept changes into his subpath, and so on. In fact, Tom's
Developer access to these structures allows him to perform the complete
range of CMVC operations that apply to individual objects in the subpath,
including operations that could result in loss of development history,
such as severing objects or making them uncontrolled.
Assume that Mary has decided to enforce a restrictive development
methodology in her subsystem. Under this methodology, Tom must be
prevented from executing the Cmvc.Sever and Cmvc.Make_Uncontrolled
commands in his subpath. This is achieved by revoking Tom's execution
rights for the Cmvc.Sever and Cmvc.Make_Uncontrolled commands. Recall from
above that execution rights are a mechanism for fine-tuning CMVC capability
within a basic access class. In this case, revoking the two execution
rights fine-tunes Tom's basic Developer access to his subpath. (Note that
it would not work to simply assign Tom to a less powerful access class
such as Client for either the subsystem or his subpath, because he still
needs Developer access to perform the desired CMVC operations in his
subpath.)
Setting Up the Basic Scenario
Assume that you are the project leader and that you are responsible for
setting up the application described above with the proper CMVC access
control. Assume also that the project library for this application is the
world !Programs.Planetary_Motion, which is currently empty. Finally,
assume that, in addition to the access-class assignments illustrated in
Figure 2, you as the project leader are to belong to the Owner access
class for all of the subsystems and views.
The following steps create the Algorithms and Demo subsystems with the
desired CMVC access-class assignments. These steps illustrate that new
subsystems (and their initial working views) derive their initial
access-class assignments from the ACL of the enclosing world:
1. Review the ACL of the world !Programs.Planetary_Motion, using commands
from package Access_List. Make sure that you have complete access to
this world; for example, if you belong to a group called
Project_Leader, the ACL of this world should contain an entry like
Project_Leader=>RCOD. Furthermore, the Project_Leader group must have
RW default access to this world. For simplicity in this example, no
other groups have access to this world.
2. In the !Projects.Planetary_Motion world, use the Cmvc.Initial command
to create the Algorithms subsystem and its main working view,
Rev1_Working. Access-class assignments to each of these structures are
derived automatically as follows:
* Groups with O access to the enclosing world are assigned to the
Owner access class for the new subsystem and the working view. Thus,
your group (Project_Leader) is assigned to the Owner class for
Algorithms and Algorithms.Rev1_Working.
* Groups with R access to the enclosing world are assigned to the
Reader access class for the new subsystem and the working view. (C
and D access to the enclosing world are ignored by this operation.)
Because no one else has access to !Projects.Planetary_Motion, no
other access-class assignments have been made for Algorithms and
Algorithms.Rev1_Working.
3. Use the Cmvc_Access_Control.Add_Group command to assign groups to
access classes for the Algorithms subsystem and the
Algorithms.Rev1_Working view. You will need to enter this command once
for each of the six access-class assignments listed below:
Mary Fred Tom
Algorithms Owner Client Developer
.Rev1_Working Owner Client Reader
For example, the following instance of the Add_Group command assigns
Mary to the Owner access class for the view Algorithms.Rev1_Working
(assume the command is entered from the context
!Projects.Planetary_Motion.Algorithms):
Cmvc_Access_Control.Add_Group
(The_Group => "Mary",
In_Class => Cmvc_Access_Control.Owner,
View_Or_Subsystem => "Rev1_Working");
4. In the Algorithms subsystem, create the spec view Rev1_0_Spec from
Rev1_Working. The new spec view initially has the same access-class
assignments as the view from which it was created. Since these are the
desired assignments, no further assignments are necessary.
Note that the subsystem owner Mary also has sufficient capability to
perform this step; methodologies may differ with respect to who makes
spec views and when they are made.
5. In the Algorithms subsystem, create the subpath Rev1_Tom_Working from
Rev1_Working. Again, the new view initially has the same access-class
assignments as the view from which it was created. However, at this
point, only Mary has the desired access to this subpath; Tom needs
Developer access instead of Reader access, and Fred should have no
access at all. To correct this:
a. Use the Cmvc_Access_Control.Remove_Group command to remove Fred from
the Client access class for Rev1_Tom_Working.
b. Use the Cmvc_Access_Control.Add_Group command to add Tom to the
Developer access class for Rev1_Tom_Working. This command also
automatically removes Tom from the Reader access class for this
subpath.
Note that the subsystem owner Mary also has sufficient capability to
perform this step; methodologies may differ with respect to who makes
subpaths and when they are made.
6. Restrict Tom's CMVC capability in his subpath by revoking his execution
rights to the Cmvc.Sever and Cmvc.Make_Uncontrolled commands. Use the
Cmvc_Access_Control.Remove_Right command to revoke each execution
right.
Note that execution rights are defined as a series of constants in
package Cmvc_Access_Control (see the reference entry for type
Execution_Right). In general, execution rights have the same name as
the commands to which they correspond. For example, the following
command revokes Cmvc_Access_Control.Sever, which is the execution right
that controls the Cmvc.Sever command:
Cmvc_Access_Control.Remove_Right
(For_Group => "Tom",
The_Right => Cmvc_Access_Control.Sever,
View_Or_Subsystem => "Rev1_Tom_Working");
7. Use steps 2 through 4 as a guide for creating and assigning CMVC access
to the Demo subsystem, its initial working view, and its spec view. In
addition, you can set up the initial imports between the views in Demo
and the spec view in Algorithms. (Note that Fred also has sufficient
capability to set up these imports; methodologies may differ with
respect to who performs the initial imports and when they are
performed.)
8. If desired, verify that the correct access-class assignments have been
made for each view and subsystem by entering the
Cmvc_Access_Control.Display command. For example, applying this command
to the working view in Demo should yield the following display:
Access Control Group List for View !PROJECTS.PLANETARY_MOTION
.DEMO.REV1_WORKING
PROJECT_LEADER : OWNER
FRED : OWNER
MARY : READER
By default, the Display command shows only access-class assignments; by
changing the default value of the Execution_Rights parameter, you can
request that each group's execution rights be displayed as well.
Ongoing Development in the Basic Scenario
Now that the basic structures and access-class assignments are set up,
Mary and Fred have sufficient access to manage subsequent development. For
example:
* If Mary creates a new spec view from an existing spec view (or from the
working view), the new spec view inherits the access-class assignments
from the source view. Fred's Client access to the new view allows him
to import the new spec view when he needs to.
* If Mary makes design changes by adding new units to an existing spec
view, Fred's Client access to this view allows him to refresh his
imports to take advantage of the new units.
* Mary can propagate changes between Tom's subpath and the main path in
Algorithms.
* When Mary makes new releases from the main integration path in
Algorithms, each new release inherits the access-class assignments from
the working view. With Client access to these releases, Fred can
execute the application using an activity that specifies any release.
Furthermore, Fred and Mary are able to accommodate changes within their
teams by adjusting the access-class assignments and execution rights that
pertain to their respective subsystems. Such changes can be made at any
time during the course of development; they take effect immediately. For
example, if Mary discovers that Tom needs to be able to sever units after
all, she can use the Add_Right command to reinstate Tom's execution right
for that operation. From that point on, Tom will be able to execute the
Cmvc.Sever command in his subpath.
As a second example, assume that a new developer named Bob joins Fred's
team. Fred has sufficient access to create a new subpath in Demo, set up
the imports between this subpath and the Algorithms spec view, and assign
Bob to the appropriate access classes (to the Developer access class for
the subsystem and the subpath and to the Reader access class for the
remaining views). Note that only Fred and the project leader have
sufficient access to add or remove imports for the new subpath, because Bob
has Developer, not Owner, access to it.
In addition, Mary (or the project leader) must grant Bob either Reader or
Client access to the Algorithms subsystem and its views. Either kind of
access will allow him to compile his subpath against the imported spec
view. Strictly speaking, only Reader access is required; Client access is
necessary only for users who will actually perform the import operations.
However, Client access may serve as a reminder that Bob's subpath is a
client of the spec view, even if Bob himself doesn't actually perform the
operations.
Note that Mary can also change Fred's access to the Algorithms subsystem
and its views. For example, she could decide for some reason to reassign
Fred to the Reader access class for Algorithms' spec view, removing him
from the Client access class for that view. Such a change would have no
effect on existing imports; however, from this point on, Fred would be
unable to execute the commands to refresh these imports or to import a new
spec view that has the same access-class assignment.
This example illustrates an important point: because a subsystem Owner can
change an access-class assignment within his or her own subsystem, some
level of cooperation must be assumed among subsystem owners and the
project leader. The ability to change access-class assignments cannot be
taken away without also taking away the ability to make releases, spec
views, and new paths in a subsystem. Project leaders can use the
Cmvc_Access_Control.Display command to verify that groups have the correct
access to the appropriate structures.
Extending the Basic Scenario: Import Networks
Assume that the application structure presented in the basic scenario is
augmented by a new higher-level subsystem called Demo_Tests, to be
developed by a subsystem owner named Sally. As shown in Figure 3 (see
hardcopy document), Test has a spec view and a working view; each of these
views imports the spec view from the Demo subsystem.
At first glance, the following access-class assignments might seem
sufficient to accommodate this change in program structure:
* Assign Sally to the Owner access class for the Demo_Tests subsystem and
for each of its views.
* Assign Sally to the Client access class for the Demo subsystem and each
of its views.
Although these access-class assignments are sufficient in a basic import
scenario (with only two subsystems), they are not enough to support import
operations in a larger network of imports, where import relationships
exist among three or more subsystems. This is because such operations need
to check for consistency and circularity throughout the entire import
network, and therefore they need access to more than just the directly
imported views. (See "Developing Applications Using Multiple Subsystems"
in the Key Concepts of this book for a discussion of circularity and
consistency in imports.)
For example, suppose Sally wants her spec and working views to import a
newly created spec view in the Demo subsystem called Rev1_1_Spec. She
enters the Cmvc.Import command, which checks to make sure she has Owner
access to the importing views and Client access to Demo.Rev1_1_Spec. In
addition, however, the import operation requires that she also have at
least Reader access to the spec view in Algorithms that is imported by
Demo.Rev1_1_Spec. Reader access to this view is required so that the
operation can verify the consistency of the entire import network.
As a second example, suppose Fred wants to change the imports of his spec
and working views. As before, the import operation he executes will check
that he has Owner access to the importing views and Client access to the
imported view in the Algorithms subsystem. In addition, he needs at least
Reader access to the views in the Demo_Tests subsystem that import his
spec view. Once again, this is because the import operation needs access
to the entire import network in order to verify its consistency.
Figure 3 summarizes the access-class assignments discussed above. These
access-class assignments reflect the following rule: If you are a user who
performs import operations (as part of commands like Cmvc.Make_Path and
Cmvc.Release as well as Cmvc.Import), you need some level of access to all
views in the import network, specifically:
* Owner access to the importing view
* Client access to any directly imported views
* Reader access to any indirectly imported views (spec views that are
imported by the views you're importing)
* Reader access to the views "above" you in the import network (any spec
or load view that imports your view)
Strategy for Simplifying Access-Class Assignments
This extended scenario shows that even simple import networks can greatly
increase the number of access-class assignments in a project. A large
number of access-class assignments can mean a lot of work for subsystem
owners each time a change is made in personnel or program structure.
Furthermore, a large number of access-class assignments may not even be
possible, because at most seven groups at a time can have access of any
kind to each view or subsystem. (In fact, in the extended scenario, as
many as six groups--counting Project_Leader--already need access to some
structures.)
Rather than treating each user as a separate group, it is recommended that
one or more groups be created containing meaningful (sub)sets of project
members. Then each of these larger groups can be assigned to access
classes in place of several smaller groups. (Note that operator capability
is required for creating and maintaining groups.)
For example, assume again that you are the project leader in the above
scenario and that you have operator capability. The simplest way to give
everyone the access they need is to:
1. Create a group that contains everyone working on the project. In this
example, you can create a group called Project_Members that contains
Sally, Fred, Bob, Mary, and Tom.
2. Remove everyone from the Reader and Client access classes throughout
the project.
3. Assign the Project_Members group to the Client access class for every
subsystem, every spec view, and every main working view, as shown in
Figure 4 (see hardcopy document).
As a result of this strategy, everyone on the project has Client access to
all of the project's structures. With this strategy, the following
requirements are met:
* Only the subsystem owners and project leader have sufficient access to
execute commands that involve import operations.
* All users have sufficient access to compile their views against their
imports and to execute the entire application.
* No user can modify any objects outside their own subsystem;
furthermore, the junior developers Tom and Bob cannot modify objects
outside their own subpaths.
This simplified strategy assumes a more open development methodology in
which any user can inspect any object in the application, although each
user's ability to modify objects is restricted appropriately. The
simplified strategy also permits subsystem owners to import more views than
are called for by the application's design. For example, consider the
Demo_Tests subsystem owner (Sally), who now has Client access to views in
all subsystems, including Algorithms. With this level of access, Sally can
import a spec view from Algorithms into Demo_Tests, although such an
import is not part of the design. Some level of cooperation must be
assumed among view owners to preserve application design.
Note that none of the junior team members have enough access to perform
their own imports. For example, Bob, the junior member of the Demo
subsystem team, has Client access to views in other subsystems and so
would appear to be able to import these views into his subpath. However,
he is unable to do so because he has insufficient access to his subpath
(Developer rather than Owner). He will still have to rely on Fred or the
Project_Leader to adjust his imports.
If a more restrictive methodology is desired, a project can define smaller
groups that have access to fewer structures. In the scenario above, Bob
can be removed from Project_Members and put into a group that has Reader
or Client access to only the spec views in Algorithms. This will prevent
him from inspecting or executing the entire application, while still
allowing him to compile against his subpath's imports.
Setting Up CMVC Access Control: General Guidelines
The following general guidelines summarize the steps in the basic and
extended scenarios presented above. It is recommended that you use these
guidelines in addition to the normal steps for planning and setting up
subsystems (see "Setting Up Subsystems: A Second Look" in "Developing
Applications Using Multiple Subsystems" in the Key Concepts of this book).
1. Identify the major structures in the application. What are the expected
subsystems, paths, subpaths, spec views, and so on?
2. Identify the required access-class assignments for each development
path and subpath in each subsystem:
a. Identify the users that need access to the working, spec, and
released views in the path or subpath. List the capabilities that
each user needs for each view.
b. Based on the required capabilities, determine the access class to
which each user must belong for each view in the path. As a guide,
use the reference tables in "Minimum Access-Class Assignments" at
the end of this package introduction.
A recommended approach is for the main working view in a development
path to have all of the access-class assignments that are required
for the spec views and releases in the same path. This approach
takes advantage of the fact that new views created from existing
views inherit their access-class assignments from the existing
views. Thus, the access granted for the working view will be
inherited by any spec view, release, or configuration release made
from it. (This approach was used in the scenarios presented above.)
c. Also based on the required capabilities, determine the access class
to which each user must belong for the enclosing subsystems. As a
guide, use the reference tables in "Minimum Access-Class
Assignments" at the end of this package introduction.
A simple approach that works for most methodologies is to assign
each user to the same access class for the enclosing subsystem as
for his or her own working view (path or subpath). (This approach
was used in the scenarios presented above.)
d. Note which users, if any, should be prevented from executing
CMVC-specific commands; list the execution rights that will need to
be revoked. As a guide to the execution rights that are granted with
each access class, use the reference tables in "Execution Rights" at
the end of this package introduction.
e. For easy reference, make a chart showing access-class assignments.
3. Create groups for users with common needs. The members of each group
should be users that must belong to the same access class for a specific
view or subsystem.
Setting up groups is important for minimizing the number of groups that
have access to each structure; a maximum of seven groups can have
access to a given view or subsystem. Note that operator capability is
required for setting up groups.
4. Review the ACL of the project library (the world in which the
subsystems are to be created) to verify that it has the correct ACLs.
Groups with O access to this world will automatically be assigned to
the Owner access class for the subsystems created in it. These groups
will also be Owners of the initial working view in each of these
subsystems.
5. Use Cmvc.Initial to create the desired subsystems (and their initial
working views). Note that you need to have read access (R) to the model
world named in the command, as well as to the switch file associated
with the model world.
6. Adjust the access-class assignments for each subsystem and initial
working view.
a. Set up subsystem owners.
b. Set up teams within each subsystem (developers who need access to
the various paths and subpaths).
c. Set up users who need to import, compile against, or execute the
views from other subsystems.
7. When subpaths, additional paths, spec views, and releases are created
during development, they will inherit their access-class assignments
from the source view. Adjust these assignments as necessary during
ongoing development. (Depending on methodology, this may be the
responsibility of subsystem owners.)
Miscellaneous Topics
Initializing Existing Subsystems
In the basic scenario presented above, CMVC access control was set up for
new subsystems. It is also possible to set up CMVC access control for
subsystems that were created in earlier releases of the Environment
(earlier than D_11_1_3).
To prepare an application for CMVC access control, you first must enter the
Cmvc_Access_Control.Initialize command for each subsystem in the
application. This command causes all groups that currently have owner
access (O) to a given subsystem to be assigned to the Owner access class
for that subsystem. All groups with read access (R) are assigned to the
Reader access class. (This procedure ignores create (C) and delete (D)
access.)
Within these subsystems, you must then use the Initialize command again to
initialize each view. You can use a naming expression such as the
following to initialize all the views in a given subsystem:
Cmvc_Access_Control.Initialize
(View_Or_Subsystem => "@'c(spec_view,load_view,comb_view)");
As a result, all groups that currently have owner access (O) to each named
view are assigned to the Owner access class for that view. All groups with
read access (R) are assigned to the Reader access class. (This procedure
ignores create (C) and delete (D) access.)
If subsystems and views are not initialized, CMVC operations will continue
to operate as in releases prior to D_11_1_3.
Special Control for CDB Capability
Sites that develop applications on multiple hosts need a group that can
perform operations that affect the compatibility databases (CDBs) of
primary and secondary subsystems. In general, such groups can perform
CDB-related operations if they have Owner access to the subsystems in
question.
However, because of the sensitive nature of CDB-related operations, some
sites may want additional control over who can perform them. If your site
wants to invoke special control over CDB capability, you can create a file
called !Machine.Cdb_Capability. Groups must have write access (W) to this
file in addition to Owner access to a subsystem in order to name that
subsystem in the Cmvc_Maintenance.Make_Primary,
Cmvc_Maintenance.Make_Secondary, or Cmvc_Maintenance.Destroy_Cdb command.
The special control over CDB capability also controls whether a group can
use the Primary and Revert_Cdb options in the Archive.Restore and
Archive.Copy commands.
Checking for Access Inconsistencies
Even when CMVC access control is in effect, it is possible for users with
Owner access to use operations from packages Access_List and
Access_List_Tools to set the ACLs of individual objects within views and
subsystems. Resetting individual ACLs can cause a group to have more or
less access than is warranted by its access class. (Insufficient access to
individual objects can cause CMVC commands to fail without diagnosing
access as the problem.)
Project leaders can run the Check command before key releases or other
milestones to ensure that individual object ACLs in a view or subsystem
are consistent with that structure's access-class assignments. The Check
command can be used merely to identify inconsistencies or to repair them
as well.
A Closer Look at Access Classes and ACLs
Assigning groups to CMVC access classes affects the ACLs of objects in
views and subsystems. Understanding how access-class assignments affect
particular objects can help you to understand why each access class
supports the capabilities that it does and why separate access is required
to views and subsystems. (See the reference entry for type Access_Class
for the specific access rights granted by each access class.)
When a group belongs to an access class for a view, an entry for that
group is inserted into the ACL of every object in the view. The objects of
interest for this discussion are the user-created objects in the view and
the view's State.Referencers file. The effect of access-class assignments
on these objects is summarized below:
* User-created objects include all Ada and text objects in the Units
directory and in any user-created directory in the view. The Reader and
Client access classes grant read access (R) to every user-created
object in a view. The Developer or Owner access classes grant read and
write access (RW) to every user-created object in a view.
Note that user-created objects are treated uniformly with respect to
access rights; CMVC access control does not support setting access
rights on an object-by-object or even a subdirectory-by-subdirectory
basis within a view.
* A view's State.Referencer file is an Environment-created object
containing state information about the view; in particular, it records
the view's clients and is updated each time the view is imported by
another view. The Client, Developer, and Owner access classes grant
read and write access (RW) to this file, which permits a group to import
the view into another view.
When a group belongs to an access class for a subsystem, an entry for that
group is inserted into the ACL of all objects in the subsystem that are
not part of any view. Objects of special interest are the CMVC database,
the compatibility database (CDB) and the Configurations directory. These
objects are common to the entire subsystem and to all the views in it.
Although these objects are not themselves part of any view, a group needs
access to them to perform operations that affect individual views. The
effect of access-class assignments on these objects is summarized below:
* A subsystem's CMVC database contains information about all the
controlled objects in each view in the subsystem. This database is
updated whenever controlled objects are checked in and out, joined,
severed, and so on. Developer or Owner access to a subsystem is
required to update the CMVC database; Reader and Client access permit a
group to use the CMVC editor to browse the controlled objects in any of
the subsystem's views.
* A subsystem's CDB collects compilation information about views that are
compiled in the subsystem. The CDB is updated whenever a new unit
specification in any view is compiled for the first time. Developer or
Owner access to a subsystem is required to update the CDB; Reader and
Client access permit only limited compilation within views (only bodies
and existing specifications can be compiled).
* A subsystem's configuration objects constitute "condensed"
representations of each view in the subsystem; they contain sufficient
information to enable views to be reconstructed from the history stored
in the CMVC database. Owner access to a subsystem is required for a
group to perform operations that delete or otherwise affect
configuration objects, such as expunging the CMVC database, destroying
views along with their corresponding configuration objects, or
rebuilding views from configuration objects.
Editor Locks, Versions, and Access Classes
Commands that change access-class assignments (such as Add_Group and
Remove_Group) change the ACLs of individual objects in views and
subsystems. Therefore, such commands are sensitive to read locks and write
locks on these individual objects. More specifically, certain kinds of
locks prevent ACLs from being changed on files or Ada units. Furthermore,
other kinds of locks allow ACLs to be changed but cause new versions to be
created in the process. For simplicity, it is recommended that you enter
commands such as Add_Group and Remove_Group only when no users are viewing
or editing any of the individual objects in the view or subsystem.
However, the following discussion may help you diagnose lock-related
errors that arise when entering these commands.
As a general rule:
* You can change access-class assignments when you or other users hold
read locks on individual text or Ada objects.
* You can change access-class assignments when you hold write locks on
individual text or Ada objects.
* You cannot change access-class assignments when other users hold write
locks on individual text or Ada objects.
Changing access-class assignments has some side effects when locks are
held on individual Ada units. Specifically, if you change an access-class
assignment while you hold a read or a write lock on an Ada unit, a new
version of that unit is created on which the new ACL is set. Furthermore,
your read or write lock will automatically transfer to the new version;
the previous version with the old ACL becomes a deleted version.
Similarly, if you change an access-class assignment while another user
holds a read lock on an Ada unit, a new version is created on which the
new ACL is set. However, the other user continues to view the previous
version, which automatically becomes a deleted version.
The existence of deleted versions occasionally causes commands to fail
unexpectedly because of the out-of-date ACLs on those versions. One
workaround is to use the Library.Expunge command to destroy deleted
versions; this method may fail if you have insufficient access to the
deleted versions or if the deleted versions themselves have read locks on
them. Another workaround is to use the Cmvc_Access_Control.Check command
to reset the ACLs of the deleted versions. You should enter this command
only when there are no read or write locks on individual objects in the
view or subsystem in question.
Configuration Objects and Access Classes
The CMVC access-class assignments for each view are recorded in the state
description directory for the configuration object corresponding to that
view. Thus, if you rebuild a view from its configuration object, the
rebuilt view will have the saved access-class assignments.
Configuration objects can be used as the source for the Cmvc.Accept_Changes
command, provided that you have Reader access to the enclosing subsystem.
However, if the view that corresponds to the named configuration object
still exists, then access to the view is checked, as if the view itself
were named in the command. (At a minimum, Reader access to the view and
Developer access to the enclosing subsystem are required to accept changes
from that view into another.)
Implications for Multiple-Host Development
Developing an application on multiple hosts involves using commands from
package Archive to save, restore, or copy subsystems and views from one
R1000 to another. These archive operations are sensitive to CMVC access
control; that is, the identity of the job or archive server must have the
appropriate kind of CMVC access to complete.
The Archive.Save and Archive.Copy commands require Reader access when
saving or copying views and subsystems:
* To save/copy objects that reside in a view, the identity of the job or
archive server must belong to a group that has at least Reader access
to the view and to the enclosing subsystem.
* To save/copy an entire view, the identity of the job or archive server
must belong to a group that has at least Reader access to the view and
to the enclosing subsystem.
* To save/copy a subsystem (including the views in it), the identity of
the job or archive server must belong to a group that has at least
Reader access to the subsystem and to each of its views.
The Archive.Restore command and the restore portion of the Archive.Copy
command require more powerful access (such as Developer or Owner) to
views, subsystem, and worlds:
* To restore/copy objects into a view, the identity of the job or archive
server must belong to a group that has at least Developer access to the
view and to the enclosing subsystem.
* To restore/copy an entire view into an existing subsystem, the identity
of the job or archive server must belong to a group that has at least
Owner access to the subsystem.
* To restore/copy an entire view into a subsystem that does not exist, or
to restore/copy an entire subsystem, the job or archive server must
belong to one or more groups that collectively have:
- RCO access to the world into which the subsystem will be created,
restored, or copied
- RW default access to this world
By default, the identity of an archive server that performs part of a Copy
command on a remote machine is Network_Public. If Network_Public does not
belong to a group with sufficient access to perform the required save or
restore operations on the desired objects, you can use a remote-passwords
file to reset the identity of the remote archive server to be a username
that belongs to a group with appropriate access. You must know the
password for the specified username. See "Changing Archive Server
Identities" in the introduction to package Archive for details.
CMVC Access Control and Systems
The subsystems in an application (or a major portion of an application)
can be identified as such by making them children of a system. Besides
providing a way of identifying groups of related subsystems, a system also
provides an automated mechanism for tracking the latest release from each
child subsystem and building activities that reference those releases.
Operations pertaining to systems are performed with commands from package
Cmvc_Hierarchy.
Systems and the system views they contain are structures that can be put
under CMVC access control. Assume that you are the system integrator who
is responsible for adding children to and making release activities in a
system called System_1. Then you need:
* Owner access to System_1 and to each of its views
* Client access to each child subsystem and its views
Owner access to a system allows you to create new views in it and to add
children to it. Client access to a subsystem allows you to make it a child
of a system. Client access to the individual views within each child
subsystem allows you to use the Cmvc_Hierarchy.Build_Activity command to
build a release activity. Strictly speaking, you need Client access only
to the releases and spec views that will be included in the release
activity. However, the Cmvc_Hierarchy.Build_Activity command also requires
at least Reader access to all other working views (including subpaths) in
order to examine these views for inclusion in the release activity.
Note that you can use the Cmvc_Hierarchy.Build_Activity command to import
spec views from the child subsystems into the working system view. (This
is useful if you have test programs as well as release activities in the
working system view.) In this case, you need Client access to all imported
spec views and Reader access to the remaining views in the import network.
Using Programs to Set CMVC Access
Tools for handling CMVC access control can use structures of type
Execution_Table to specify complete sets of execution rights for groups.
Site-specific sets of execution rights can be derived from the default sets
for each access class using the constants of type Execution_Table that are
defined in this package (see the reference entry for type Execution_Table).
Overriding CMVC Access Control
Members of a special predefined group called Privileged can perform any
operation on any object regardless of access-class assignments and
execution rights. To activate this capability, a member of this group must
first execute the Operator.Enable_Privileges command, which is documented
in SMU. In the standard Environment, username Operator is a member of the
Privileged group.
Enabling privileges is sufficient to allow you to access any object
through jobs that execute under your identity. However, enabling
privileges alone does not allow you to bring up a display for an object to
which you normally do not have access. To display such an object, you must
first use privileged mode to change its ACL.
REFERENCE SUMMARY FOR PACKAGE CMVC_ACCESS_CONTROL
The following sections present information about access classes and
execution rights in tabular form for easy reference.
Minimum Access-Class Assignments
The tables in this section provide a short guide to the minimum access
classes that are required for various capabilities. Designated users such
as project managers can use these tables to help them decide the access
classes to which to assign their groups.
The first table lists various things that a group may need to do to a view.
For each capability, the table lists the minimum access classes to which
the group must belong, both for the view and for the subsystem enclosing
the view. The second table lists various things that a group may need to
do to a subsystem and gives the minimum access class required for each of
these capabilities.
The capabilities listed below are supported by the specified access classes
only for groups who have the default set of execution rights. Note that
the capabilities supported by a given access class can be restricted by
selectively revoking individual execution rights for a particular group.
Table 1 Minimum Access for View-Related Capabilities
---------------------------------------------
| | | |
| | |Minimum |
| |Minimum |Access |
|Desired Capability |Access |to |
| |to View |Enclosing |
| | |Subsystem |
---------------------------------------------
| | | |
|Browse a view using |Reader |Reader |
|Common.Definition or | | |
|Cmvc.Edit | | |
---------------------------------------------
| | | |
|Execute a view, |Reader |Reader |
|including load views | | |
|named in activities | | |
---------------------------------------------
| | | |
|Execute operations | | |
|that import one view |Client |Reader |
|into another |Owner |Reader |
| Access to imported|Reader |Reader |
|view | | |
| Access to | | |
|importing view | | |
| Access to other | | |
|views in import | | |
|network | | |
---------------------------------------------
| | | |
|Accept changes from | | |
|source view into |Reader |Developer |
|destination view |Developer |Developer |
| Access to source | | |
|view | | |
| Access to | | |
|destination view | | |
---------------------------------------------
| | | |
|Edit uncontrolled |Developer |Reader |
|objects in view; | | |
|compile bodies | | |
---------------------------------------------
| | | |
|Use CMVC operations |Developer |Developer |
|on individual objects| | |
|in view (check out, | | |
|check in, abandon | | |
|reservation, join, | | |
|sever, revert, make | | |
|controlled, make | | |
|uncontrolled) as well| | |
|as editing and | | |
|unlimited compilation| | |
---------------------------------------------
| | | |
|Release or make |Developer |Owner |
|copies (e.g., paths, | | |
|subpaths, code views,| | |
|spec views) of view | | |
---------------------------------------------
| | | |
|Change view's imports|Owner |Reader |
|and model | | |
---------------------------------------------
| | | |
|Change view's imports|Owner |Developer |
|and model; also use | | |
|CMVC operations (like| | |
|check in and out) on | | |
|view's objects | | |
---------------------------------------------
| | | |
|Check consistency of |Owner |Owner |
|a view | | |
---------------------------------------------
| | | |
|Destroy a view |Owner |Owner |
---------------------------------------------
Table 2 Minimum Access for Subsystem-Related Capabilities
---------------------------------
| | |
| |Minimum |
|Desired Capability |Access |
| |to |
| |Subsystem |
---------------------------------
| | |
|Make a subsystem a |Client |
|child of a system | |
---------------------------------
| | |
|Build or destroy a |Owner |
|configuration object | |
---------------------------------
| | |
|Check consistency of |Owner |
|subsystem | |
---------------------------------
| | |
|Expunge subsystem's |Owner |
|CMVC database | |
---------------------------------
| | |
|Destroy subsystem |Owner |
---------------------------------
| | |
|Change subsystem from|Owner |
|primary to secondary | |
|or from secondary to | |
|primary | |
---------------------------------
Table 3 Required Access for Changing Access-Class Assignments
-----------------------------------------------
| | |
|Desired Capability |Required Access |
-----------------------------------------------
| | |
|Change access to a |Owner access (O) to the |
|subsystem |enclosing world or Owner |
| |access to the subsystem |
| |itself |
-----------------------------------------------
| | |
|Change access to a |Owner access to the |
|view |enclosing subsystem or |
| |Owner access to the view |
| |itself |
-----------------------------------------------
Execution Rights, Listed by Command
Execution rights provide control over the primitive operations in the
commands from packages Cmvc, Cmvc_Maintenance, and Cmvc_Hierarchy. A
primitive operation is a distinct portion of a command that applies to
(references or affects) a particular view, subsystem or system.
Accordingly, a command has one primitive operation associated with each
parameter that names a view, subsystem, or system. For example, the
Cmvc.Accept_Changes command has two primitive operations, one that applies
to the view named by the Source parameter and one that applies to the view
named by the Destination parameter.
Execution rights, defined under type Execution_Right, are the mechanism
that permits a group to apply a particular primitive operation to a
particular view, subsystem, or system. Thus, to execute a given CMVC
command, a group must have the appropriate execution right to each
structure that is affected by the command's primitive operations. For
example, a group must have the Check_In and Check_Out execution rights to
a view to perform checkin and checkout operations in that view. Similarly,
if the group is to accept changes from one view to another, it must have
the Accept_Changes_Source and Accept_Changes_Destination execution rights
to the source and destination views, respectively.
Execution rights that allow primitive operations to affect views are
called view execution rights. Similarly, execution rights that allow
primitive operations to affect subsystems or systems are called subsystem
execution rights and system execution rights, respectively.
The following tables list the view, subsystem, and/or system execution
rights that are checked for each command in packages Cmvc,
Cmvc_Maintenance, and Cmvc_Hierarchy. When a command has multiple
primitive operations corresponding to multiple parameters, the table lists
one execution right for each such parameter.
Table 4 Required Execution Rights for Commands in Package Cmvc
--------------------------------------------------------------
| | | |
|Command |Parameters |Required Execution Right|
--------------------------------------------------------------
| | | |
|Abandon_ |What_Object |Abandon_Reservation for |
|Reservation | |view |
--------------------------------------------------------------
| | | |
|Accept_Changes |Destination |Accept_Changes_ |
| |Source |Destination for view |
| | |Accept_Changes_Source |
| | |for view |
--------------------------------------------------------------
| | | |
|Append_Notes |What_Object |Modify_Notes for view |
--------------------------------------------------------------
| | | |
|Build |View_To_Import |Import_From for views |
| | |Build for enclosing |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Check_In |What_Object |Check_In for view |
--------------------------------------------------------------
| | | |
|Check_Out |What_Object |Check_Out for view |
--------------------------------------------------------------
| | | |
|Compare |Destination |Query_View for view |
| |Source |Query_View for view |
--------------------------------------------------------------
| | | |
|Copy |From_View |Copy for source view |
| |View_To_Import |Import_From for imported|
| |View_To_Modify |view |
| | |Import_Into for |
| | |importing view |
--------------------------------------------------------------
| | | |
|Create_Empty_Note_|What_Object |(No rights are required)|
|Window | | |
--------------------------------------------------------------
| | | |
|Def |What_Object |Query_View for view |
--------------------------------------------------------------
| | | |
|Destroy_Subsystem |What_Subsystem |Destroy_Subsystem for |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Destroy_System |What_Subsystem |Destroy_Subsystem for |
| | |system |
--------------------------------------------------------------
| | | |
|Destroy_View |What_View |Destroy_View for view |
| | |Destroy_Config for |
| | |enclosing subsystem |
--------------------------------------------------------------
| | | |
|Edit |View_Or_Config |Query_View for view, if |
| | |view is named; |
| | |Query_Subsystem for |
| | |subsystem, |
| | |if configuration is name|
--------------------------------------------------------------
| | | |
|Get_Notes |What_Object |Query_View for view |
--------------------------------------------------------------
| | | |
|Import |View_To_Import |Import_From for imported|
| |Into_View |view |
| | |Import_Into for |
| | |importing view |
--------------------------------------------------------------
| | | |
|Imported_Views |Of_View |Query_View for view |
--------------------------------------------------------------
| | | |
|Information |For_View |Query_View for view |
--------------------------------------------------------------
| | | |
|Initial |System_Object |Initial for subsystem |
| |View_To_Import |Import_From for view |
--------------------------------------------------------------
| | | |
|Join |What_Object |Join_What for view |
| |To_Which_View |Join_To for view being |
| | |joined to |
--------------------------------------------------------------
| | | |
|Make_Code_View |From_View |Make_Code_View for view |
--------------------------------------------------------------
| | | |
|Make_Controlled |What_Object |Make_Controlled for view|
| |Join_With_View |Join_To for view joined |
| | |to, if specified |
--------------------------------------------------------------
| | | |
|Make_Path |From_Path |Make_Path for source |
| |View_To_Import |view |
| |View_To_Modify |Import_From for imported|
| | |view |
| | |Import_Into for |
| | |importing view |
--------------------------------------------------------------
| | | |
|Make_Spec_View |From_Path |Make_Spec_View for |
| |View_To_Import |source view |
| |View_To_Modify |Import_From for imported|
| | |view |
| | |Import_Into for |
| | |importing view |
--------------------------------------------------------------
| | | |
|Make_Subpath |From_Path |Make_Subpath for source |
| |View_To_Import |view |
| |View_To_Modify |Import_From for imported|
| | |view |
| | |Import_Into for |
| | |importing view |
--------------------------------------------------------------
| | | |
|Make_Uncontrolled |What_Object |Make_Uncontrolled for |
| | |view |
--------------------------------------------------------------
| | | |
|Merge_Changes |Destination_Object|Merge_Changes_ |
| |Source_View |Destination for view |
| | |Merge_Changes_Source for|
| | |view |
--------------------------------------------------------------
| | | |
|Notes |What_Object |Query_View for view |
| | |Edit_Notes for view if |
| | |editing notes |
--------------------------------------------------------------
| | | |
|Put_Notes |What_Object |Modify_Notes for view |
--------------------------------------------------------------
| | | |
|Release |From_Working_View |Release for working view|
| |Views_To_Import |Import_From for imported|
| | |views |
--------------------------------------------------------------
| | | |
|Remove_Import |From_View |Remove_Import for |
| | |importing view |
| | |(Client access to |
| | |removed imports) |
--------------------------------------------------------------
| | | |
|Remove_Unused_ |From_View |Remove_Import for |
|Import | |importing view |
| | |(Client access to |
| | |removed imports) |
--------------------------------------------------------------
| | | |
|Replace_Model |In_View |Replace_Model for view |
--------------------------------------------------------------
| | | |
|Revert |What_Object |Revert for view |
--------------------------------------------------------------
| | | |
|Sever |What_Object |Sever for view |
--------------------------------------------------------------
| | | |
|Show |Objects |Query_View for view |
--------------------------------------------------------------
| | | |
|Show_All_Checked_ |In_View |Query_View for view |
|Out | | |
--------------------------------------------------------------
| | | |
|Show_All_ |In_View |Query_View for view |
|Controlled | | |
--------------------------------------------------------------
| | | |
|Show_All_ |In_View |Query_View for view |
|Uncontrolled | | |
--------------------------------------------------------------
| | | |
|Show_Checked_Out_ |In_View |Query_View for view |
|By_User | | |
--------------------------------------------------------------
| | | |
|Show_Checked_Out_ |In_View |Query_View for view |
|In_View | | |
--------------------------------------------------------------
| | | |
|Show_History |For_Objects |Query_View for view |
--------------------------------------------------------------
| | | |
|Show_History_By_ |For_Objects |Query_View for view |
|Generation | | |
--------------------------------------------------------------
| | | |
|Show_Image_Of_ |Object |Query_View for view |
|Generation | | |
--------------------------------------------------------------
| | | |
|Show_Out_Of_Date_ |In_View |Query_View for view |
|Objects | | |
--------------------------------------------------------------
Table 5 Required Execution Rights for Commands in Package
Cmvc_Maintenance
--------------------------------------------------------------
| | | |
|Command |Parameters |Required Execution Right|
--------------------------------------------------------------
| | | |
|Check_Consistency |Views |Check_Consistency, if |
| | |applied to views; |
| | |Subsystem_Check_ |
| | |Consistency, if applied |
| | |to subsystem |
--------------------------------------------------------------
| | | |
|Destroy_Cdb |Subsystem |Destroy_Cdb for |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Display_Cdb |Subsystem |Query_Subsystem for |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Display_Code_View |View |Query_View for view |
--------------------------------------------------------------
| | | |
|Expunge_Database |In_Subsystem |Expunge_Database for |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Make_Primary |Subsystem |Make_Primary for |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Make_Secondary |Subsystem |Make_Secondary for |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Update_Cdb |From_Subsystem |No check |
| |To_Subsystem |Update_Cdb |
--------------------------------------------------------------
Table 6 Required Execution Rights for Commands in Package Cmvc_Hierarchy
--------------------------------------------------------------
| | | |
|Command |Parameters |Required Execution Right|
--------------------------------------------------------------
| | | |
|Add_Child |Child |Add_Child_Child for |
| |To_System |subsystem |
| | |Add_Child_Parent for |
| | |system |
--------------------------------------------------------------
| | | |
|Build_Activity |Working_System_ |Build_Activity_In for |
| |View |view containing activity|
| |Views_To_Include |Build_Activity_From for |
| | |views in activity |
--------------------------------------------------------------
| | | |
|Children |Of_System |Query_Subsystem for |
| | |system |
--------------------------------------------------------------
| | | |
|Contents |Of_System_View |Query_View for system |
| | |view |
--------------------------------------------------------------
| | | |
|Expand_Activity |System_View |Expand_Activity for view|
--------------------------------------------------------------
| | | |
|Parents |Of_Subsystem |Query_Subsystem for |
| | |subsystem |
--------------------------------------------------------------
| | | |
|Remove_Child |Child |(Client access to child)|
| |From_System |Remove_Child for system |
--------------------------------------------------------------
Execution Rights, Listed by Access Class
The following tables list the view, subsystem, and system execution rights
that are granted by default when a group is added to a given access class.
These tables are to be read cumulatively, so that, on a given table, the
set of rights for each access class includes the rights for the preceding
access classes. For example, the set of rights granted by the Developer
access class includes the sets of rights granted by the Client Reader
access classes.
Note that operations that affect views check both the access class to the
view and the access class to the subsystem enclosing the view. Therefore,
for each view execution right, the table lists the required access class
to the view's enclosing subsystem.
Table 7 View Execution Rights, Listed by Access Class
-----------------------------------------------
| | | |
| | |Required Access |
|View Access|View Execution |Class |
|Class |Rights |to Enclosing |
| | |Subsystem |
-----------------------------------------------
| | | |
|Reader |Accept_Changes_ |Developer |
| |Source |Reader |
| |Expand_Activity |Developer |
| |Join_To |Developer |
| |Merge_Changes_ |Reader |
| |Source | |
| |Query_View | |
-----------------------------------------------
| | | |
|Client |Build_Activity_ |Reader |
| |From |Reader |
| |Import_From | |
-----------------------------------------------
| | | |
|Developer |Abandon_ |Developer |
| |Reservation |Developer |
| |Accept_Changes_ |Reader |
| |Destination |Developer |
| |Build_Activity_In|Developer |
| |Check_In |Owner |
| |Check_Out |Developer |
| |Copy |Owner |
| |Join_What |Developer |
| |Make_Code_View |Owner |
| |Make_Controlled |Owner |
| |Make_Path |Owner |
| |Make_Spec_View |Developer |
| |Make_Subpath |Developer |
| |Make_Uncontrolled|Developer |
| |Merge_Changes_ |Owner |
| |Destination |Developer |
| |Modify_Notes |Developer |
| |Release | |
| |Revert | |
| |Sever | |
-----------------------------------------------
| | | |
|Owner |Check_Consistency|Owner |
| |Destroy_View |Owner |
| |Import_Into |Reader |
| |Remove_Import |Reader |
| |Replace_Model |Reader |
-----------------------------------------------
Table 8 Subsystem Execution Rights, Listed by Access Class
-----------------------------------------------
| | |
|Subsystem Access |Subsystem Execution Rights |
|Class | |
-----------------------------------------------
| | |
|Reader |Query_Subsystem |
-----------------------------------------------
| | |
|Client |Add_Child_Child |
-----------------------------------------------
| | |
|Developer |Edit_Notes |
| |Update_Cdb |
-----------------------------------------------
| | |
|Owner |Build |
| |Destroy_Cdb |
| |Destroy_Config |
| |Destroy_Subsystem |
| |Expunge_Database |
| |Initial |
| |Make_Primary |
| |Make_Secondary |
| |Subsystem_Check_Consistency |
-----------------------------------------------
Table 9 System Execution Rights, Listed by Access Class
-----------------------------------------------
| | |
|System Access |System Execution Rights |
|Class | |
-----------------------------------------------
| | |
|Reader |Query_Subsystem |
-----------------------------------------------
| | |
|Client |Add_Child_Child |
-----------------------------------------------
| | |
|Developer |Add_Child_Parent |
| |Edit_Notes |
| |Remove_Child |
| |Update_Cdb |
-----------------------------------------------
| | |
|Owner |Build |
| |Destroy_Cdb |
| |Destroy_Config |
| |Destroy_Subsystem |
| |Expunge_Database |
| |Initial |
| |Make_Primary |
| |Make_Secondary |
| |Subsystem_Check_Consistency |
-----------------------------------------------
@node !Commands.Cmvc_Access_Control.Access_Class
type Access_Class is (Reader, Client, Developer, Owner);
DESCRIPTION
Defines the four access classes to which groups can be assigned--namely,
the Reader, Client, Developer, and Owner access classes.
These access classes define the kinds of access that groups can have to
objects in projects managed under CMVC. As such, they support four general
ways in which groups participate in project development:
* The Reader class is for groups that must be able to inspect and execute
objects in views, subsystems, and systems.
* The Client class is for groups that must be able to import views into
other views.
* The Developer class is for groups that must be able to check in, check
out, edit, and compile objects in views, subsystems, and systems.
* The Owner class is for groups that must have complete control over
views, subsystems, and systems, including the ability to create,
destroy, and change the access to them.
Access classes support these project-development roles by automatically
managing the access lists (ACLs) of the objects in views, subsystems, or
systems. The settings in these ACLs are coordinated to allow groups to
perform certain classes of operations. Access classes also provide a means
of further restricting the execution of CMVC operations even beyond the
limits imposed by the ACL settings.
For a given view, subsystem, or system, a group can be assigned to one of
the four access classes via the Add_Group command. When a group is
assigned to an access class, an entry for the group is automatically added
to the ACL for each of the objects in the view, subsystem, or system. For
objects that are worlds, an entry for the group is also added to the
default ACL. Taken together, the ACL entries for each class grant a
coordinated set of access rights that limit operations on user-created
objects (such as Ada units) as well as on Environment-defined objects (such
as those that manage CMVC state).
Assigning a group to an access class also defines the set of possible
execution rights that can be granted to the group (see type
Execution_Right). Execution rights determine the CMVC operations that can
be performed by members of the group upon a view, subsystem, or system.
Note that a group belonging to a particular access class does not have any
of the permitted execution rights unless these rights have been explicitly
granted (for example, using the Add_Group, Add_Right, or Set_Rights
command).
The four access classes form a hierarchy from Owner (at the top) to
Developer, Client, and Reader (at the bottom). The access provided by a
lower access class is a proper subset of the access provided by the next
higher class.
The four access classes are described below. Each description includes a
list of the access rights that are assigned for objects in views,
subsystems, and systems. For views (including system views), access rights
are assigned for all user- and Environment-managed objects within the
view. The Environment-defined State.Referencers file in a view is of special
interest; the access rights assigned to it determine whether or not the
view can be imported. Note that user-created objects in a view are treated
uniformly with respect to access rights--that is, CMVC access control does
not support setting access rights on an object-by-object or even a
subdirectory-by-subdirectory basis within a view. Thus, a group belonging
to the Reader or Client access class for a view is granted read access (R)
to every user-created object in the view. Similarly, a group belonging to
the Developer or Owner access class for a view is granted read and write
access (RW) to every user-created object in the view. The ACLs of
individual objects must not be changed from their predefined settings (the
Check command can be used to ensure that ACL settings remain as determined
by access classes).
For subsystems, access rights are assigned for all objects in the
subsystem that are not part of any view--for example, the CMVC database,
the compatibility database (CDB), and objects in the Configurations
directory:
* Read access to the CMVC database allows you to browse the controlled
objects in a view, even if you don't have direct access to the view
itself.
* Write access to the CMVC database allows you to check objects in and
out.
* Write access to the CDB allows you to compile new unit specifications in
the subsystem's views (with less than write access, you can recompile
only new bodies and existing specifications).
* Write access to configurations is required to destroy views and expunge
the CMVC database.
For systems, access rights are assigned for all objects that are not part
of any system view. This includes the system's CMVC database (which
controls any programs that are maintained in the system) as well as the
State.Children file (which allows children to be added to the system).
ENUMERATIONS
Reader
Grants read access to objects in a view, subsystem, or system. For a view,
the Reader access class grants sufficient access to display objects in the
view and to execute any compiled units in it. For a subsystem, this access
class grants sufficient access to use the CMVC editor to browse the
controlled objects in any of the subsystem's views, regardless of whether
access has been granted to the view itself.
When a group is assigned to the Reader access class for a view, the
following access rights are granted to the group:
-------------------------------------
| | |
|View Objects |Reader Access |
| |Rights |
| | |
|View (World) |R access, R |
| |default access |
| | |
| |R access |
|.State.Referencers | |
|(File) | |
| | |
| All other objects|R access |
|in view | |
-------------------------------------
When a group is assigned to the Reader access class for a subsystem or
system, the following access rights are granted to the group:
-------------------------------------
| | |
|Subsystem/System |Reader Access |
|Objects |Rights |
| | |
|Subsystem/System |R access, R |
|(World) |default access |
| | |
| .Configurations | |
|(Directory) | |
| | |
| All objects |R access |
|in directory | |
| | |
| .State | |
|(Directory) | |
| | |
| .Compatibility|R access, R |
|(World) |default access |
| | |
| All |R access |
|objects in world | |
| | |
| .Cmvc_Database|R access |
|(File) | |
| | |
| .Parents |R access |
|(File) | |
| | |
| .Children |R access |
|(File) | |
| | |
| All other |R access |
|objects in directory | |
| | |
|All other objects in |R access |
|(sub)system | |
-------------------------------------
Client
Superset of Reader access class. For a view, the Client access class
grants sufficient access to allow the view to be imported into other views.
Note that Client access to a view is required only for those groups whose
users actually need to add the view to (or remove the view from) the
imports of other views.
For a subsystem, this access class grants sufficient access to allow the
subsystem to be made a child of a system.
When a group is assigned to the Client access class for a view, the
following access rights are granted to the group:
-------------------------------------
| | |
|View Objects |Client Access |
| |Rights |
| | |
|View (World) |R access, R |
| |default access |
| | |
| |RW access |
|.State.Referencers | |
|(File) | |
| | |
| All other objects|R access |
|in view | |
-------------------------------------
When a group is assigned to the Client access class for a subsystem or
system, the following access rights are granted to the group:
-------------------------------------
| | |
|Subsystem/System |Client Access |
|Objects |Rights |
| | |
|Subsystem/System |R access, R |
|(World) |default access |
| | |
| .Configurations | |
|(Directory) | |
| | |
| All objects |R access |
|in directory | |
| | |
| .State | |
|(Directory) | |
| | |
| .Compatibility|R access, R |
|(World) |default access |
| | |
| All |R access |
|objects in world | |
| | |
| .Cmvc_Database|R access |
|(File) | |
| | |
| .Parents |RW access |
|(File) | |
| | |
| .Children |R access |
|(File) | |
| | |
| All other |R access |
|objects in directory | |
| | |
|All other objects in |R access |
|(sub)system | |
-------------------------------------
Developer
Superset of Client access class. For a view, the Developer access class
grants sufficient additional access to allow objects in the view to be
modified and to allow new objects to be created. For a subsystem, this
access class grants sufficient additional access to allow compatibility
objects and the CMVC database to be modified.
Note that you must have Developer access to a subsystem to check out
objects in the subsystem's views, because checkin and checkout operations
modify the CMVC database.
When a group is assigned to the Developer access class for a view, the
following access rights are granted to the group:
--------------------------------------
| | |
|View Objects |Developer Access|
| |Rights |
| | |
|View (World) |RC access, RW |
| |default access |
| | |
| |RW access |
|.State.Referencers | |
|(File) | |
| | |
| All other objects|RW access |
|in view | |
--------------------------------------
When a group is assigned to the Developer access class for a subsystem or
system, the following access rights are granted to the group:
--------------------------------------
| | |
|Subsystem/System |Developer Access|
|Objects |Rights |
| | |
|Subsystem/System |R access, R |
|(World) |default access |
| | |
| .Configurations | |
|(Directory) | |
| | |
| All objects |R access |
|in directory | |
| | |
| .State | |
|(Directory) | |
| | |
| .Compatibility|RC access, RW |
|(World) |default access |
| | |
| All |RW access |
|objects in world | |
| | |
| .Cmvc_Database|RW access |
|(File) | |
| | |
| .Parents |RW access |
|(File) | |
| | |
| .Children |RW access |
|(File) | |
| | |
| All other |R access |
|objects in directory | |
| | |
|All other objects in |RW access |
|(sub)system | |
--------------------------------------
Owner
Superset of Developer access class. For a view, the Owner access class
provides all possible access to the view and the objects in it. You must
have Owner access to a view in order to change its imports or destroy it.
To change a view's access-control characteristics, you must have either
Owner access to the view or Owner access to the subsystem enclosing it.
For a subsystem, the Owner access class provides all possible access to
the subsystem and the objects in it. You must have Owner access to a
subsystem to create new views in it or to destroy it. To change a
subsystem's access-control characteristics, you must have either Owner
access to the subsystem or the owner access right (O) to the world
enclosing the subsystem.
When a group is assigned to the Owner access class for a view, the
following access rights are granted to the group:
-------------------------------------
| | |
|View Objects |Owner Access |
| |Rights |
| | |
|View (World) |RCOD access, RW|
| |default access |
| | |
| |RW access |
|.State.Referencers | |
|(File) | |
| | |
| All other objects|RW access |
|in view | |
-------------------------------------
When a group is assigned to the Owner access class for a subsystem or
system, the following access rights are granted to the group:
-------------------------------------
| | |
|Subsystem/System |Owner Access |
|Objects |Rights |
| | |
|Subsystem/System |RCOD access, RW|
|(World) |default access |
| | |
| .Configurations | |
|(Directory) | |
| | |
| All objects |RW access |
|in directory | |
| | |
| .State | |
|(Directory) | |
| | |
| .Compatibility|RCOD access, RW|
|(World) |default access |
| | |
| All |RW access |
|objects in world | |
| | |
| .Cmvc_Database|RW access |
|(File) | |
| | |
| .Parents |RW access |
|(File) | |
| | |
| .Children |RW access |
|(File) | |
| | |
| All other |RW access |
|objects in directory | |
| | |
|All other objects in |RW access |
|(sub)system | |
-------------------------------------
@node !Commands.Cmvc_Access_Control.Add_Group
procedure Add_Group
(The_Group : String := "NETWORK_PUBLIC";
In_Class : Access_Class :=
Cmvc_Access_Control.Reader;
View_Or_Subsystem : String := "<SELECTION>";
Add_Execution_Rights : Boolean := True;
Response : String := "<PROFILE>");
DESCRIPTION
Adds a group to the specified access class for the designated view,
subsystem, or system; up to seven groups can have access to a given view,
subsystem, or system at any one time.
If the specified group already belongs to an access class for the
designated view, subsystem, or system, the group is automatically removed
from its old access class and assigned to the new one.
Access classes define the kinds of access that groups can have to objects
in projects developed under CMVC. When a group is assigned to an access
class for a given view, subsystem, or system, that group is granted
specific access rights as described in the reference entry for type
Access_Class. Access rights are granted by automatically inserting an
entry for the group into each object's ACL. The four access classes and
the specific access rights they grant are described under type
Access_Class.
Each access class also defines the set of possible execution rights that
can be granted to the group for the specified view, subsystem, or system.
(The execution rights permitted by each access class are listed under
"Reference Summary for Package Cmvc_Access_Control" in the introduction to
this package.) By default, the Add_Group command causes all of the
permitted execution rights to be granted to the group. Once granted,
individual execution rights can be removed subsequently using the
Remove_Right command.
Alternatively, the Add_Execution_Rights parameter can be set to False so
that no execution rights are granted when a group is added to an access
class. Individual execution rights can be granted subsequently using the
Add_Right procedure.
When this command removes a group from one access class in order to add it
to another, the access lists (ACLs) for the affected objects are adjusted
appropriately, and all inappropriate execution rights are automatically
removed, regardless of the value of the Add_Execution_Rights parameter.
PARAMETERS
The_Group : String := "NETWORK_PUBLIC";
Specifies the name of the group to be added to the specified access class.
Only one group can be named. The default group is Network_Public.
In_Class : Access_Class := Cmvc_Access_Control.Reader;
Specifies the access class to which the specified group is assigned. One of
four access classes can be specified--namely, Reader, Client, Developer, or
Owner. The default is the Reader access class, which provides the least
amount of access.
View_Or_Subsystem : String := "<SELECTION>";
Specifies one or more views, subsystems, or systems to which the specified
group is granted access. Multiple views, subsystems, or systems can be
specified using wildcards, context characters, set notation, indirect files,
and attributes. The default is the highlighted view, subsystem, or system,
provided that the highlight contains the cursor.
Add_Execution_Rights : Boolean := True;
Specifies whether the execution rights permitted by the specified access
class are to be granted. When True (the default), all permitted execution
rights are granted to the specified group. When False, none of the
permitted execution rights are granted to the specified group.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To add a group to an access class for a view, you must have either Owner
access to the view or Owner access to the subsystem enclosing it.
To add a group to an access class for a subsystem, you must have either
Owner access to the subsystem or the owner access right (O) to the world
enclosing the subsystem.
ERRORS
The Add_Group command must obtain write locks on the objects whose ACLs
are to be set. This command will fail if it cannot obtain all of the
necessary write locks (for example, if someone is currently editing one of
the affected objects). As a result, the group is not added to the access
class and no ACLs are changed.
EXAMPLES
Assume that you have Owner access for a subsystem called Algorithms and
you want to add a group called Client_Of_Algorithms to the Client access
class for every view in the subsystem. Assume further that you want this
group to have all of the available execution rights. The following
command, executed from the context Algorithms, accomplishes this:
Cmvc_Access_Control.Add_Group
(The_Group => "read_all",
In_Class => cmvc_access_control.client,
View_Or_Subsystem => "@'c(spec_view,load_view)");
Assume that you have Owner access for the subsystem Algorithms and you
want to add a group called Read_All to the Reader access class for a new
view called Algorithms.Rev2_0_Spec. Assume further that you do not want
this group to have any of the available execution rights. The following
command accomplishes this, assuming that you have selected the library
entry for Rev2_0_Spec:
Cmvc_Access_Control.Add_Group
(The_Group => "read_all",
In_Class => cmvc_access_control.reader,
View_Or_Subsystem => "<SELECTION>",
Add_Execution_Rights => False);
REFERENCES
type Access_Class
procedure Add_Right
procedure Remove_Group
procedure Remove_Right
@node !Commands.Cmvc_Access_Control.Add_Right
procedure Add_Right
(For_Group : String := "NETWORK_PUBLIC";
The_Right : Execution_Right :=
Cmvc_Access_Control.All_Rights;
View_Or_Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
Grants the specified execution right to the specified group for the
designated view, subsystem, or system.
An execution right can be granted only if it is permitted by the access
class to which the group belongs. (See "Reference Summary for Package
Cmvc_Access_Control" in the introduction to this package for the list of
execution rights permitted by each access class for views, subsystems, and
systems.) By default, this procedure grants a group all of the permitted
execution rights.
PARAMETERS
For_Group : String := "NETWORK_PUBLIC";
Specifies the name of the group to which an execution right is to be
granted. Only one group can be named. The default group is Network_Public.
The_Right : Execution_Right := Cmvc_Access_Control.All_Rights;
Specifies the execution right to be granted to the group. By default, the
procedure grants all rights that are permitted by the access class to
which the group belongs. If the default value is not used, only a single
execution right can be specified.
View_Or_Subsystem : String := "<SELECTION>";
Specifies the views, subsystems, or systems to which the specified execution
right(s) apply. Multiple views, subsystems, or systems can be specified
using wildcards, context characters, set notation, indirect files, and
attributes. The default is the highlighted view, subsystem, or system,
provided that the highlight contains the cursor.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To grant an execution right to a group for a view, you must have Owner
access to the view.
To grant an execution right to a group for a subsystem, you must have
Owner access to the subsystem.
EXAMPLES
Assume that a group called Read_All belongs to the Reader access class for
a view but has been granted none of the execution rights for that class.
Assume further that you, the view's Owner, want members of this group to
be able to obtain information about the view using the Cmvc.Edit command.
To do this, you must grant this group the Query_View execution right. The
following command accomplishes this, provided that the appropriate view is
selected:
Cmvc_Access_Control.Add_Right
(For_Group => "Read_All",
The_Right => Cmvc_Access_Control.Query_View,
View_Or_Subsystem => "<SELECTION>");
REFERENCES
type Execution_Right
function Has_Right
procedure Remove_Right
@node !Commands.Cmvc_Access_Control.Check
procedure Check
(View_Or_Subsystem : String := "<SELECTION>";
Repair_Inconsistencies : Boolean := False;
Response : String := "<PROFILE>");
DESCRIPTION
Checks whether:
* Objects in the specified views, subsystems, or systems have access lists
(ACLs) that are consistent with the current CMVC access-class
assignments.
* The groups that have access to these views, subsystems, or systems
still exist.
This command optionally repairs any ACL inconsistencies and expunges any
deleted groups.
When groups are assigned to CMVC access classes for views, subsystems, and
systems, ACLs for the individual objects are set. However, a user with
Owner access or operator capability can subsequently use operations in
packages Access_List and Access_List_Tools to reset the ACLs of individual
objects. Resetting individual ACLs can cause a group to have more or less
access than is warranted by its access class. Insufficient access causes
the desired CMVC operations to fail. By default, the Check procedure quits
after finding the first ACL inconsistency, displaying:
* A warning message if the group's actual access is greater than is
warranted by its access class.
* An error message if the group's actual access is less than is warranted
by its access class.
Similarly, a user with operator capability can delete a group after it has
been assigned to an CMVC access class. The Check procedure displays an
error message if it encounters a deleted group among access-class
assignments.
If the Repair_Inconsistencies parameter is set to True:
* All deleted groups are removed from access-class assignments. It is
recommended that you execute this command every time a group is deleted
from the Environment.
* All inconsistent ACLs are reset so that the correct access rights are
assigned to each group. (See the Access_Class type for the access
rights associated with each access class.)
You must have Owner access to the views, subsystems, or systems in which
inconsistencies are repaired. Alternatively, you can enable privileges.
A related function, Is_Consistent, performs the same checks, returning a
Boolean value. It does not produce messages or attempt to repair ACLs.
PARAMETERS
View_Or_Subsystem : String := "<SELECTION>";
Specifies one or more views, subsystems, or systems whose ACLs are to be
checked. Multiple views, subsystems, or systems can be specified using
wildcards, context characters, set notation, indirect files, and
attributes. The default is the highlighted view, subsystem, or system,
provided that the highlight contains the cursor.
Repair_Inconsistencies : Boolean := False;
Specifies whether to repair inconsistent ACLs and remove deleted groups in
the specified views, subsystems, or systems. When False (the default), no
action is taken other than displaying error or warning messages. When
True, deleted groups are removed from ACLs and ACLs are changed so that
the groups in each access class have the correct access rights to the
relevant objects.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To repair inconsistencies in a view, you must have either Owner access to
the view or Owner access to the subsystem enclosing it. To repair
inconsistencies in a subsystem, you must have either Owner access to the
subsystem or the owner access right (O) to the world enclosing the
subsystem. Alternatively, you may perform either operation with privileges
enabled.
ERRORS
To repair inconsistencies, the Check command must obtain write locks on
the objects whose ACLs are to be reset. This command will fail if it
cannot obtain all of the necessary write locks (for example, if someone is
currently editing one of the affected objects). As a result,
inconsistencies in the view, subsystem, or system are not repaired and no
ACLs are changed.
REFERENCES
function Is_Consistent
Library Management (LM), package Access_List
Library Management (LM), package Access_List_Tools
@node !Commands.Cmvc_Access_Control.Display
procedure Display (For_Group : String := "<ALL>";
View_Or_Subsystem : String := "<CURSOR>";
Execution_Rights : Boolean := False;
Response : String := "<PROFILE>");
DESCRIPTION
Displays the current access-control information pertaining to the specified
group for the designated view, subsystem, or system; the information is
displayed in an Environment output window.
By default, this procedure displays the access classes for all groups that
have access to the specified view, subsystem, or system. If the
Execution_Rights parameter is set to True, then the procedure also
displays the execution rights that have been granted to these groups.
PARAMETERS
For_Group : String := "<ALL>";
Specifies the group for which access-control information is to be
displayed. The default special value "<ALL>" causes information to be
displayed for all groups that have access to the specified view, subsystem,
or system. If the default value is not used, only a single group name can
be specified.
View_Or_Subsystem : String := "<CURSOR>";
Specifies the view, subsystem, or system for which access-control
information is to be displayed. Multiple views, subsystems, or systems can
be specified using wildcards, context characters, set notation, indirect
files, and attributes. The default is the view, subsystem, or system
indicated by the cursor.
Execution_Rights : Boolean := False;
Specifies whether to display the execution rights that have been granted to
the specified group for the specified view, subsystem, or system. When False
(the default), the execution rights are not displayed.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To display the access-control information for a view or subsystem, you
must have at least Reader access to that view or subsystem.
EXAMPLES
Assume that you want to find out who has access to the view Rev1_Working in
the subsystem !Projects.Planetary_Motion.Demo. The following command,
entered with default values, accomplishes this, provided that the cursor
is on the desired view:
Cmvc_Access_Control.Display;
As a result, the following appears in an Environment output window:
Access Control Group List for View !PROJECTS.PLANETARY_MOTION
.DEMO.REV1_WORKING
PROJECT_LEADER : OWNER
FRED : OWNER
MARY : READER
Assume that you only want to know what access Mary has to this view.
Furthermore, you want to know what execution rights she has. The following
command accomplishes this:
Cmvc_Access_Control.Display (For_Group => "Mary",
View_Or_Subsystem => "<CURSOR>",
Execution_Rights => True);
As a result, the following appears in an Environment output window:
Access Control Group List for View !PROJECTS.PLANETARY_MOTION
.DEMO.REV1_WORKING
MARY : READER
ACCEPT_CHANGES_SOURCE
JOIN_TO
MERGE_CHANGES_SOURCE
QUERY_VIEW
EXPAND_ACTIVITY
@node !Commands.Cmvc_Access_Control.Execution_Right
type Execution_Right is new Natural range 0 .. 127;
DESCRIPTION
Defines the execution rights that can be granted to groups for views,
subsystems, or systems.
Execution rights determine the CMVC operations that can be performed by
members of the group upon a view, subsystem, or system. Each execution
right is represented by a constant of this type; these constants are
listed below.
Execution rights provide control over the primitive operations in the
commands from packages Cmvc, Cmvc_Maintenance, and Cmvc_Hierarchy. A
primitive operation is a distinct portion of a command that applies to
(references or affects) a particular view, subsystem, or system.
Accordingly, a command has one primitive operation associated with each
parameter that names a view, subsystem, or system. For example, the
Cmvc.Accept_Changes command has two primitive operations, one that applies
to the view named by the Source parameter and one that applies to the view
named by the Destination parameter.
Execution rights are the mechanism that permits a group to apply a
particular primitive operation to a particular view, subsystem, or system.
Thus, to execute a given CMVC command, a group must have the appropriate
execution right to each structure that is affected by the command's
primitive operations. For example, a group must have the Check_In and
Check_Out execution rights to a view to perform checkin and checkout
operations in that view. Similarly, if the group is to accept changes from
one view to another, it must have the Accept_Changes_Source and
Accept_Changes_Destination execution rights to the source and destination
views, respectively. Because there is an execution right corresponding to
each primitive operation, a given group typically has a set of execution
rights for each view, subsystem, or system to which it has access.
The access class to which a group belongs defines the set of possible
execution rights that can be granted to the group. ("Reference Summary for
Package Cmvc_Access_Control" in the introduction to this package lists the
execution rights that are permitted by each access class.) However, a
group has only those execution rights that have been explicitly granted to
it. You can grant a group the entire set of eligible execution rights when
you use the Add_Group command to add the group to an access class.
Alternatively, you can grant a group a subset of the eligible execution
rights using the Add_Right or Set_Rights command, and you can revoke
individual execution rights using the Remove_Right command.
The constants that represent execution rights are listed in alphabetical
order below. In general, the name of each execution right is the same as
the name of the primitive operation it governs. (The name of a primitive
operation is formed by concatenating the name of the associated command
with the name of the relevant parameter, if there is one.)
The description for each execution right indicates whether the execution
right applies to a view, a subsystem, or a system. Execution rights that
control primitive operations on views are called view execution rights.
Similarly, execution rights that apply to subsystems and systems are
called subsystem execution rights and system execution rights,
respectively.
Also specified in each description is the minimum access class to which a
group must belong to be eligible for that execution right. Note that an
execution right pertaining to a view requires not only a minimum access
class to that view, but also a minimum access class for the subsystem that
encloses the view. The access class for the view is checked at the time
the execution right is granted; the access class for the subsystem is
checked only when you execute a command that applies the relevant
primitive operation.
Constants
Abandon_Reservation : constant Execution_Right := 5;
View execution right. Permits a group to use the Cmvc.Abandon_Reservation
command on objects in a view.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Accept_Changes_Destination : constant Execution_Right := 3;
View execution right. Permits a group to accept changes into a view (that
is, to name the view as the destination of the Cmvc.Accept_Changes
command).
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Accept_Changes_Source : constant Execution_Right := 4;
View execution right. Permits a group to accept changes from a view (that
is, to name the view or objects in it in the Source parameter of the
Cmvc.Accept_Changes command).
Minimum access class for view: Reader
Minimum access class for enclosing subsystem: Developer
Add_Child_Child : constant Execution_Right := 44;
Subsystem/system execution right. Permits a group to make a subsystem or
system a child of another system (that is, to name the subsystem or system
in the Child parameter of the Cmvc_Hierarchy.Add_Child command).
Minimum access class for subsystem/system: Developer
Add_Child_Parent : constant Execution_Right := 43;
System execution right. Permits a group to make a system a parent of a
subsystem or another system (that is, to name the system in the To_System
parameter of the Cmvc_Hierarchy.Add_Child command).
Minimum access class for system: Developer
All_Rights : constant Execution_Right := 0;
Grants a group all execution rights that are appropriate, given the access
class for which the group belongs.
Build : constant Execution_Right := 34;
Subsystem/system execution right. Permits a group to build views from
configurations within a subsystem or system (that is, to name a
configuration from the subsystem or system in the Cmvc.Build command).
Minimum access class for subsystem/system: Owner
Build_Activity_From : constant Execution_Right := 29;
View execution right. Permits a group to include a view in the release
activity of a system view (that is, to name the view in the
Views_To_Include parameter of the Cmvc_Hierarchy.Build_Activity command).
Minimum access class for view: Client
Minimum access class for enclosing subsystem: Reader
Build_Activity_In : constant Execution_Right := 28;
View execution right. Permits a group to build a release activity in a
system view (that is, to name the system view in the Working_System_View
parameter of the Cmvc_Hierarchy.Build_Activity command).
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Reader
Check_Consistency : constant Execution_Right := 27;
View execution right. Permits a group to check the consistency of a view
(that is, to name the view in the Views parameter of the
Cmvc_Maintenance.Check_Consistency command).
Minimum access class for view: Owner
Minimum access class for enclosing subsystem: Owner
Check_In : constant Execution_Right := 2;
View execution right. Permits a group to check in objects in a view using
the Cmvc.Check_In command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Check_Out : constant Execution_Right := 1;
View execution right. Permits a group to check out objects in a view using
the Cmvc.Check_Out command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Copy : constant Execution_Right := 16;
View execution right. Permits a group to copy a view using the Cmvc.Copy
command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Owner
Destroy_Cdb : constant Execution_Right := 42;
Subsystem/system execution right. Permits a group to destroy a subsystem's
or system's compatibility database using the Cmvc_Maintenance.Destroy_Cdb
command.
Minimum access class for subsystem/system: Owner
Destroy_Config : constant Execution_Right := 32;
Subsystem/system execution right. Permits a group to destroy a
configuration object in a subsystem or system using the Cmvc.Destroy_View
command.
Minimum access class for subsystem/system: Owner
Destroy_Subsystem : constant Execution_Right := 33;
Subsystem/system execution right. Permits a group to destroy a subsystem
or system using the Cmvc.Destroy_Subsystem command.
Minimum access class for subsystem/system: Owner
Destroy_View : constant Execution_Right := 24;
View execution right. Permits a group to destroy a view using the
Cmvc.Destroy_View command. Note that the Destroy_Config execution right to
the subsystem is also required to destroy a view's configuration object as
well.
Minimum access class for view: Owner
Minimum access class for enclosing subsystem: Owner
Edit_Notes : constant Execution_Right := 36;
Subsystem/system execution right. Permits a group to modify notes in a
subsystem or system using the CMVC editor.
Minimum access class for subsystem/system: Developer
Expand_Activity : constant Execution_Right := 30;
View execution right. Permits a group to expand a system view's release
activity using the Cmvc_Hierarchy.Expand_Activity command.
Minimum access class for view containing source activity: Reader
Minimum access class for view to contain expanded activity: Developer
Minimum access class for enclosing subsystem: Reader
Expunge_Database : constant Execution_Right := 37;
Subsystem/system execution right. Permits a group to expunge a subsystem's
or system's CMVC database using the Cmvc_Maintenance.Expunge_Database
command.
Minimum access class for subsystem/system: Owner
Import_From : constant Execution_Right := 20;
View execution right. Permits a group to import a view (that is, to name
the view in the View_To_Import parameter in commands such as Cmvc.Import,
Cmvc.Copy, Cmvc.Make_Path, and so on).
Minimum access class for imported view: Client
Minimum access class for enclosing subsystem: Reader
Import_Into : constant Execution_Right := 21;
View execution right. Permits a group to change a view's imports (that is,
to name the view in the Into_View parameter of the Cmvc.Import command or
in the View_To_Modify parameter in commands such as Cmvc.Copy,
Cmvc.Make_Path, and so on).
Minimum access class for view: Owner
Minimum access class for enclosing subsystem: Reader
Initial : constant Execution_Right := 31;
Subsystem/system execution right. Permits a group to create an empty view
in a subsystem or system using the Cmvc.Initial command.
Minimum access class for subsystem/system: Owner
Join_To : constant Execution_Right := 12;
View execution right. Permits a group to name a view in the To_Which_View
parameter of the Cmvc.Join command.
Minimum access class for view: Reader
Minimum access class for enclosing subsystem: Developer
Join_What : constant Execution_Right := 11;
View execution right. Permits a group to name objects in a view in the
What_Object parameter of the Cmvc.Join command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Make_Code_View : constant Execution_Right := 25;
View execution right. Permits a group to create a code view from a view
using the Cmvc.Make_Code_View command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Owner
Make_Controlled : constant Execution_Right := 8;
View execution right. Permits a group to make objects in a view controlled
using the Cmvc.Make_Controlled command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Make_Path : constant Execution_Right := 17;
View execution right. Permits a group to copy a view to make a new
development path, using the Cmvc.Make_Path command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Owner
Make_Primary : constant Execution_Right := 40;
Subsystem/system execution right. Permits a group to convert a secondary
subsystem or system into a primary subsystem or system, using the
Cmvc_Maintenance.Make_Primary command.
Minimum access class for subsystem/system: Owner
Make_Secondary : constant Execution_Right := 41;
Subsystem/system execution right. Permits a group to convert a primary
subsystem or system into a secondary subsystem or system, using the
Cmvc_Maintenance.Make_Secondary command.
Minimum access class for subsystem/system: Owner
Make_Spec_View : constant Execution_Right := 19;
View execution right. Permits a group to make a spec view from a view
using the Cmvc.Make_Spec_View command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Owner
Make_Subpath : constant Execution_Right := 18;
View execution right. Permits a group to make a subpath from a view using
the Cmvc.Make_Subpath command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Owner
Make_Uncontrolled : constant Execution_Right := 9;
View execution right. Permits a group to make objects in a view
uncontrolled using the Cmvc.Make_Uncontrolled command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Merge_Changes_Destination : constant Execution_Right := 13;
View execution right. Permits a group to merge changes into an object in a
view (that is, to name the object in the Destination_Object parameter of
the Cmvc.Merge_Changes command).
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Merge_Changes_Source : constant Execution_Right := 14;
View execution right. Permits a group to merge changes from an object in a
view (that is, to name the object in the Source_Object parameter of the
Cmvc.Merge_Changes command).
Minimum access class for view: Reader
Minimum access class for enclosing subsystem: Developer
Modify_Notes : constant Execution_Right := 7;
View execution right. Permits a group to modify the notes of objects in a
view using the Cmvc.Put_Notes or Cmvc.Append_Notes command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Query_Subsystem : constant Execution_Right := 35;
Subsystem/system execution right. Permits a group to obtain information
about a subsystem or system using the Cmvc_Maintenance.Display_Cdb
command. This execution right also permits a group to obtain information
from a configuration in a subsystem using the Cmvc.Edit command. Finally,
this execution right permits a group to obtain information about a system
using the Cmvc_Hierarchy.Children and Cmvc_Hierarchy.Parents commands.
Minimum access class for subsystem/system: Reader
Query_View : constant Execution_Right := 26;
View execution right. Permits a group to obtain various kinds of
information about a view using commands from package Cmvc such as
Get_Notes, Imported_Views, Information, Edit, Notes, Def, Compare, and all
the commands beginning with Show_ (for example, Show_History). This
execution right also permits a group to name a view in the
Cmvc_Maintenance.Display_Code_View command and to name a system view in
the Cmvc_Hierarchy.Contents command.
Minimum access class for view: Reader
Minimum access class for enclosing subsystem: Reader
Release : constant Execution_Right := 15;
View execution right. Permits a group to create a release from a view
using the Cmvc.Release command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Owner
Remove_Child : constant Execution_Right := 45;
System execution right. Permits a group to remove a child from a system
(that is, to name the system in the From_System parameter of the
Cmvc_Hierarchy.Remove_Child command).
Minimum access class for system: Developer
Remove_Import : constant Execution_Right := 22;
View execution right. Permits a group to remove an import from a view
using the Cmvc.Remove_Import or Cmvc.Remove_Unused_Import command.
Minimum access class for view: Owner
Minimum access class for enclosing subsystem: Reader
Replace_Model : constant Execution_Right := 23;
View execution right. Permits a group to replace a view's model using the
Cmvc.Replace_Model command.
Minimum access class for view: Owner
Minimum access class for enclosing subsystem: Reader
Revert : constant Execution_Right := 6;
View execution right. Permits a group to revert objects in a view to a
previous generation using the Cmvc.Revert command.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Sever : constant Execution_Right := 10;
View execution right. Permits a group to use the Cmvc.Sever command to
sever objects in a view from the objects to which they are joined.
Minimum access class for view: Developer
Minimum access class for enclosing subsystem: Developer
Subsystem_Check_Consistency : constant Execution_Right := 38;
Subsystem/system execution right. Permits a group to check the consistency
of all of the views in a subsystem or all the system views in a system
(that is, to name the subsystem or system in the
Cmvc_Maintenance.Check_Consistency command).
Minimum access class for subsystem/system: Owner
Update_Cdb : constant Execution_Right := 39;
Subsystem/system execution right. Permits a group to update the
compatibility database of a secondary subsystem or system using the
Cmvc_Maintenance.Update_Cdb command.
Minimum access class for subsystem/system: Developer
REFERENCES
procedure Add_Group
procedure Add_Right
function Has_Right
procedure Remove_Right
procedure Set_Rights
@node !Commands.Cmvc_Access_Control.Execution_Table
type Execution_Table is array (Execution_Right) of Boolean;
DESCRIPTION
Defines a structure called an execution table, which can be used to specify
a complete set of execution rights for a group.
Execution tables allow execution rights to be granted as sets rather than
individually. The Set_Rights command can be used to grant the rights
specified in an execution table.
Execution tables are intended for use in site-specific tools that manage
CMVC access control. Such tools might define constants of type
Execution_Table to represent site-specific policies regarding execution
rights. Note, however, that execution tables are subject to the access
permitted by access classes, so that site-specific tools can grant only the
execution rights that are appropriate to a group's access class.
The sets of execution rights that are permitted by each access class are
listed in the introduction to this package. Each set is also represented
by a predefined constant of type Execution_Table. These constants are
documented on their own reference-entry pages. One group of constants
represents the execution rights for subsystems and systems. Two groups of
constants represent the execution rights for views, because view execution
rights check for access to a view as well as to the subsystem enclosing
the view.
The following constants represent the subsystem (and system) execution
rights that are permitted by each access class:
Subsystem_Reader_Rights
Subsystem_Client_Rights
Subsystem_Developer_Rights
Subsystem_Owner_Rights
The following constants represent the view execution rights permitted by
access classes for views and their enclosing subsystems:
View_Reader_Rights Subsystem_Reader_View_Rights
View_Client_Rights Subsystem_Client_View_Rights
View_Developer_Rights Subsystem_Developer_View_Rights
View_Owner_Rights Subsystem_Owner_View_Rights
REFERENCES
type Execution_Right
function Get_Rights
procedure Set_Rights
constant Subsystem_Client_Rights
constant Subsystem_Client_View_Rights
constant Subsystem_Developer_Rights
constant Subsystem_Developer_View_Rights
constant Subsystem_Owner_Rights
constant Subsystem_Owner_View_Rights
constant Subsystem_Reader_Rights
constant Subsystem_Reader_View_Rights
constant View_Client_Rights
constant View_Developer_Rights
constant View_Owner_Rights
constant View_Reader_Rights
@node !Commands.Cmvc_Access_Control.Get_Access
function Get_Access
(The_Group : String := "NETWORK_PUBLIC";
View_Or_Subsystem : String := "<CURSOR>";
Response : String := "<WARN>")
return Access_Class;
DESCRIPTION
Returns the specified group's access class for the designated view,
subsystem, or system.
If the group does not belong to an access class for the designated object,
the No_Access exception is raised.
This function is intended for use in site-specific tools that manage CMVC
access control.
PARAMETERS
The_Group : String := "NETWORK_PUBLIC";
Specifies the group whose access class is to be returned. Only one group
can be named.
View_Or_Subsystem : String := "<CURSOR>";
Specifies the view, subsystem, or system for which the specified group's
access class is to be returned. Wildcards, context characters, and
attributes may be used, provided that the name resolves to a single view,
subsystem, or system. The default is the view, subsystem, or system
indicated by the cursor.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return Access_Class;
Returns the specified group's access class for the designated view,
subsystem, or system. If the group does not belong to an access class for
the designated object, the No_Access exception is raised.
REFERENCES
exception No_Access
@node !Commands.Cmvc_Access_Control.Get_Rights
function Get_Rights
(For_Group : String := "NETWORK_PUBLIC";
View_Or_Subsystem : String := "<CURSOR>";
Response : String := "<WARN>")
return Execution_Table;
DESCRIPTION
Returns the set of execution rights that have been granted to a group for
the designated view, subsystem, or system.
If the group has no execution rights for the designated object, the
No_Access exception is raised.
This function is intended for use in site-specific tools that manage CMVC
access control.
PARAMETERS
For_Group : String := "NETWORK_PUBLIC";
Specifies the group whose execution rights are to be returned. Only one
group can be named.
View_Or_Subsystem : String := "<CURSOR>";
Specifies the view, subsystem, or system for which the specified group's
execution rights are to be returned. Wildcards, context characters, and
attributes may be used, provided that the name resolves to a single view,
subsystem, or system. The default is the view, subsystem, or system
indicated by the cursor.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return Execution_Table;
Returns the set of execution rights that have been granted to a group for
the designated view, subsystem, or system. If the group has no execution
rights for the designated object, the No_Access exception is raised.
REFERENCES
type Execution_Table
exception No_Access
@node !Commands.Cmvc_Access_Control.Group_Index
type Group_Index is range 0 .. 6;
DESCRIPTION
Defines a means of referencing the groups that have access to a particular
view, subsystem, or system.
When a group is assigned to an access class for a view, subsystem, or
system, the group name is recorded internally in an indexed list. Because
up to seven groups can have access to a view, subsystem, or system, the
index ranges from 0 through 6. The Group_Name function returns the name of
the group at the specific index in the list.
Group indexes are intended for use in site-specific tools that manage CMVC
access control. One possible use for indexes is to allow a tool to iterate
through the list of groups.
REFERENCES
function Group_Name
@node !Commands.Cmvc_Access_Control.Group_Name
function Group_Name
(The_Index : Group_Index := 0;
View_Or_Subsystem : String := "<CURSOR>";
Response : String := "<WARN>")
return String;
DESCRIPTION
Returns the name of the group at the specified index for the designated
view, subsystem, or system.
When a group is assigned to an access class for a view, subsystem, or
system, the group name is recorded internally in an indexed list. The
list's index provides a means of referencing these groups, especially in
site-specific tools that manage CMVC access control. Such tools can iterate
through the indexes in a list of groups and use the Group_Name function to
convert each index into a group name.
Group names are indexed consecutively, starting with 0. If no group is at
the specified index, the function returns the null string (""). If an index
n is empty, then the index n+1 is also empty.
PARAMETERS
The_Index : Group_Index := 0;
Specifies the index for which to return a group name. This parameter
accepts an integer from 0 through 6.
View_Or_Subsystem : String := "<CURSOR>";
Specifies the view, subsystem, or system for which to return the indexed
group name. Wildcards, context characters, and attributes may be used,
provided that the name resolves to a single view, subsystem, or system.
The default is the view, subsystem, or system indicated by the cursor.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return String;
Returns the name of the group at the specified index for the designated
view, subsystem, or system. If no group is at the specified index, the
function returns the null string ("").
REFERENCES
type Group_Index
@node !Commands.Cmvc_Access_Control.Has_Access
function Has_Access
(User_Or_Group : String := "<USER>";
In_Class : Access_Class := Cmvc_Access_Control.Reader;
View_Or_Subsystem : String := "<CURSOR>";
Group_Only : Boolean := False;
Response : String := "<WARN>") return Boolean;
DESCRIPTION
Returns True if the specified user or group belongs to the specified access
class (or to a more inclusive access class) for the designated view,
subsystem, or system.
If the User_Or_Group parameter specifies a group, that group is checked for
the specified access. If the User_Or_Group parameter specifies a username,
then all groups that include that username are checked for the specified
access.
When set to True, the Group_Only parameter causes the value of
User_Or_Group to be interpreted as a group name, even if a user exists
with the same name.
PARAMETERS
User_Or_Group : String := "<USER>";
Specifies the name of the user or group whose access is to be checked. Only
one name can be specified. The default special value "<USER>" specifies the
current user.
If a group is specified, the function checks whether the group belongs to
the specified access class for the designated view, subsystem, or system.
If a username is specified, the function checks whether any group
containing the user belongs to the desired access class. Note that the
interpretation of this parameter can be restricted by the Group_Only
parameter.
In_Class : Access_Class := Cmvc_Access_Control.Reader;
Specifies the access class in which to check the specified user's or group's
membership. One of four access classes can be specified--namely, Reader,
Client, Developer, or Owner. The default is the Reader access class.
View_Or_Subsystem : String := "<CURSOR>";
Specifies the view, subsystem, or system for which access is to be checked.
Multiple views, subsystems, or systems can be specified using wildcards,
context characters, set notation, indirect files, and attributes. The
default is the view, subsystem, or system indicated by the cursor.
Group_Only : Boolean := False;
Specifies whether the value of the User_Or_Group parameter is restricted to
group names. When False (the default), the User_Or_Group parameter can
name users or groups. When True, the value of the User_Or_Group parameter
is interpreted only as a group name, even if a user exists with the same
name.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return Boolean;
Returns True if the specified user or group belongs to the specified access
class (or to a more inclusive access class) for the designated view,
subsystem, or system.
If the View_Or_Subsystem parameter names multiple objects, then this
function returns True only if the user or group has the specified access
for all of the named objects.
@node !Commands.Cmvc_Access_Control.Has_Right
function Has_Right
(User_Or_Group : String := "<USER>";
The_Right : Execution_Right :=
Cmvc_Access_Control.All_Rights;
View_Or_Subsystem : String := "<CURSOR>";
Group_Only : Boolean := False;
Response : String := "<WARN>")
return Boolean;
DESCRIPTION
Returns True if the specified user or group has the specified execution
right for the designated view, subsystem, or system.
By default, this function checks whether all permitted rights have been
granted.
When the function is to check for all permitted rights, the User_Or_Group
parameter must specify a group name. If a username is specified, it is
interpreted as a group name.
When the function is to check for a single execution right, the
User_Or_Group parameter can specify either a username or a group name:
* If a username is specified, the function checks all groups containing
that username.
* If a group name is specified, the function checks only the specified
group.
The Group_Only parameter can be used to restrict the interpretation of the
User_Or_Group parameter, even when the function is to check for a single
execution right. When the value of the Group_Only parameter is True, the
User_Or_Group parameter is interpreted as a group name even if a user
exists with the same name.
PARAMETERS
User_Or_Group : String := "<USER>";
Specifies the name of the user or group whose execution rights are to be
checked. Only one name can be specified. The default special value "<USER>"
specifies the current user.
If the The_Rights parameter has its default value, or if the Group_Only
parameter is set to True, then the value of the User_Or_Group parameter is
interpreted as a group name, even if a user exists with the same name.
The_Right : Execution_Right := Cmvc_Access_Control.All_Rights;
Specifies the execution right for which to check. The possible execution
rights are listed under the Execution_Right type. By default, the function
checks whether all permitted rights have been granted. If the default
value is not used, only a single execution right can be specified.
View_Or_Subsystem : String := "<CURSOR>";
Specifies the view, subsystem, or system for which execution rights are to
be checked. Multiple views, subsystems, or systems can be specified using
wildcards, context characters, set notation, indirect files, and
attributes. The default is the view, subsystem, or system indicated by the
cursor.
Group_Only : Boolean := False;
Specifies whether the value of the User_Or_Group parameter is restricted to
group names. When False (the default), the User_Or_Group parameter can
name users or groups. When True, the value of the User_Or_Group parameter
is interpreted only as a group name, even if a user exists with the same
name. Note that if the The_Right parameter has its default value, the
User_Or_Group parameter is understood as a group name, regardless of the
value of the Group_Only parameter.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return Boolean;
Returns True if the specified user or group has the specified execution
right for the designated view, subsystem, or system.
If the View_Or_Subsystem parameter names multiple objects, then this
function returns True only if the user or group has the specified rights
for all of the named objects.
@node !Commands.Cmvc_Access_Control.Initialize
procedure Initialize (View_Or_Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
Initializes the specified view, subsystem, or system so that its access
control can be managed with operations in this package.
The Initialize command is useful primarily for setting up CMVC access
control in views, subsystems, or systems that were created under previous
releases of the Environment.
Initializing a view, subsystem, or system causes groups to be assigned to
CMVC access classes based on the access rights given in the object's
current ACL:
* All groups with owner access (O) are assigned to the Owner access class
for the view, subsystem, or system.
* All groups with read access (R) are assigned to the Reader access class
for the view, subsystem, or system. (This procedure ignores create (C)
and delete (D) access.)
Each group is granted all execution rights permitted by the access class
to which it was assigned.
The Initialize procedure also creates an object called Access_Control in
the State directory of the intialized view, subsystem, or system. This
object stores CMVC access-control information and causes CMVC commands to
check for appropriate access classes and execution rights.
If this procedure is applied to a view, subsystem, or system that is
already managed by CMVC access control, the effect is to reset the
access-control information to the initialized state. All groups currently
in the Owner access class remain in that class; all groups currently in
other access classes are assigned to the Reader access class.
PARAMETERS
View_Or_Subsystem : String := "<SELECTION>";
Specifies the view, subsystem, or system to be initialized. Multiple views,
subsystems, or systems can be specified using wildcards, context
characters, set notation, indirect files, and attributes. The default is
the highlighted view, subsystem, or system, provided that the highlight
contains the cursor.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To initialize a view, you must have either Owner access to the view or
Owner access to the subsystem enclosing it.
To initialize a subsystem, you must have either Owner access to the
subsystem or the owner access right (O) to the world enclosing the
subsystem.
ERRORS
The Initialize command must obtain write locks on the objects whose ACLs
are to be set. This command will fail if it cannot obtain all of the
necessary write locks (for example, if someone is currently editing one of
the affected objects). As a result, the view, subsystem, or system is not
initialized and no ACLs are changed.
EXAMPLES
Assume that you have already initialized a subsystem and that you now want
to initialize all the views in it. You can do this by entering the
following command from the context of the subsystem:
Cmvc_Access_Control.Initialize
(View_Or_Subsystem => "@'c(spec_view,load_view,comb_view)");
@node !Commands.Cmvc_Access_Control.Is_Consistent
function Is_Consistent
(View_Or_Subsystem : String := "<CURSOR>";
Response : String := "<WARN>")
return Boolean;
DESCRIPTION
Returns True if both of the following are True:
* Objects in the specified views, subsystems, or systems have access lists
(ACLs) that are consistent with the current CMVC access-class
assignments.
* The groups that have access to these views, subsystems, or systems
still exist.
When groups are assigned to CMVC access classes for views, subsystems, and
systems, ACLs for the individual objects are set. However, a user with
Owner access or operator capability can subsequently use operations in
packages Access_List and Access_List_Tools to reset the ACLs of individual
objects. Resetting individual ACLs can cause a group to have more or less
access than is warranted by its access class. The Is_Consistent function
can be used to query whether such operations have in fact been performed.
Similarly, a user with operator capability can delete a group after it has
been assigned to an CMVC access class. The Check procedure displays an
error message if it encounters a deleted group among access-class
assignments.
The Check procedure performs the same checks, optionally repairing any
inconsistent ACLs.
PARAMETERS
View_Or_Subsystem : String := "<CURSOR>";
Specifies one or more views, subsystems, or systems whose ACLs are to be
checked. Multiple views, subsystems, or systems can be specified using
wildcards, context characters, set notation, indirect files, and
attributes. The default is the view, subsystem, or system indicated by the
cursor.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return Boolean;
Returns True if objects in the specified views, subsystems, or systems have
ACLs that are consistent with the current CMVC access-class assignments.
Returns False if inconsistent ACLs are found, if access-class assignments
reference deleted groups, if access-control information does not exist, or
if the current user does not have sufficient access to inspect the objects'
ACLs.
RESTRICTIONS
You must have Reader access to a view, subsystem, or system to query the
ACLs of objects in it.
REFERENCES
procedure Check
@node !Commands.Cmvc_Access_Control.Nil_Rights
Nil_Rights : constant Execution_Table := (others => False);
DESCRIPTION
Represents an execution table containing no execution rights.
Setting a group's execution rights to this constant prevents the group
from executing any CMVC commands for a given view, subsystem, or system.
REFERENCES
type Execution_Table
procedure Set_Rights
@node !Commands.Cmvc_Access_Control.No_Access
No_Access : exception;
DESCRIPTION
Is raised by the Get_Access or Get_Rights function to indicate that a
group has no access to the specified view, subsystem, or system.
REFERENCES
function Get_Access
function Get_Rights
@node !Commands.Cmvc_Access_Control.Remove_Group
procedure Remove_Group
(The_Group : String := "<ALL>";
View_Or_Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
Revokes the specified group's access to the designated view, subsystem, or
system.
This procedure removes the group from the access class to which it
belongs. By default, all groups with access to the specified view,
subsystem, or system are removed from their respective access classes.
Removing a group from an access class removes the group from the access
lists (ACLs) of the objects in the affected view, subsystem, or system.
Furthermore, the removed group loses all execution rights to the affected
view, subsystem, or system.
PARAMETERS
The_Group : String := "<ALL>";
Specifies the group whose access to the specified view, subsystem, or system
is to be revoked. The default special value "<ALL>" causes access to the
specified view, subsystem, or system to be revoked for all groups. If the
default value is not used, only a single group can be specified.
View_Or_Subsystem : String := "<SELECTION>";
Specifies the view, subsystem, or system for which the specified group's
access is to be revoked. Multiple views, subsystems, or systems can be
specified using wildcards, context characters, set notation, indirect files,
and attributes. The default is the highlighted view, subsystem, or system,
provided that the highlight contains the cursor.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To remove a group from an access class for a view, you must have either
Owner access to the view or Owner access to the subsystem enclosing it.
To remove a group from an access class for a subsystem, you must have
either Owner access to the subsystem or the owner access right (O) to the
world enclosing the subsystem.
EXAMPLES
Assume that you want to remove all groups from all access classes for a
release called !Projects.Planetary_Motion.Demo.Rev1_0_1. You can do this
by selecting that release in the context of the Demo subsystem and then
entering the following command:
Cmvc_Access_Control.Remove_Group;
A message is displayed in an Environment output window listing the groups
whose access has been cleared. Now that no one has access to the release,
only an Owner of the enclosing subsystem can use the Add_Group command to
set new access-class assignments for it.
REFERENCES
type Access_Class
procedure Add_Group
@node !Commands.Cmvc_Access_Control.Remove_Right
procedure Remove_Right
(For_Group : String := "<ALL>";
The_Right : Execution_Right :=
Cmvc_Access_Control.All_Rights;
View_Or_Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
Removes the specified execution right from the specified group for the
designated view, subsystem, or system.
By default, all groups lose all execution rights to the view, subsystem,
or system.
PARAMETERS
For_Group : String := "<ALL>";
Specifies the name of the group from which execution rights are to be
removed. The default special value "<ALL>" causes execution rights to be
removed from all groups that have access to the specified view, subsystem,
or system. If the default value is not used, only a single group name can
be specified.
The_Right : Execution_Right := Cmvc_Access_Control.All_Rights;
Specifies the execution right to be removed from the specified group. By
default, the procedure removes a group's entire set of execution rights
for the specified view, subsystem, or system. If the default value is not
used, only a single execution right can be specified.
View_Or_Subsystem : String := "<SELECTION>";
Specifies the view, subsystem, or system for which an execution right is to
be removed. Multiple views, subsystems, or systems can be specified using
wildcards, context characters, set notation, indirect files, and
attributes. The default is the highlighted view, subsystem, or system,
provided that the highlight contains the cursor.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To revoke an execution right for a view, you must have Owner access to the
view.
To revoke an execution right for a subsystem, you must have Owner access
to the subsystem.
EXAMPLES
Assume that a group called Tom has Developer access to a view, and you
want to revoke all but three of the group's execution rights to that view.
To do this:
1. Select the view and enter the following command to remove the entire
set of execution rights to that view:
Cmvc_Access_Control.Remove_Right (For_Group => "Tom");
2. Use the Add_Right command to restore each of the desired execution
rights.
REFERENCES
procedure Add_Right
@node !Commands.Cmvc_Access_Control.Set_Rights
procedure Set_Rights
(For_Group : String := "NETWORK_PUBLIC";
The_Rights : Execution_Table :=
Cmvc_Access_Control.Nil_Rights;
View_Or_Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
Grants the specified set of execution rights to the specified group for the
designated view, subsystem, or system.
Within the specified set of execution rights, individual rights can be set
only if they are permitted by the group's access class. Warning messages
are produced for inappropriate rights.
This procedure is intended for use in site-specific tools that manage CMVC
access control. Note that a group can be granted the entire set of
permitted execution rights when it is added to an access class (see the
Add_Group command). Furthermore, the Add_Right procedure can be used to
set individual execution rights interactively.
PARAMETERS
For_Group : String := "NETWORK_PUBLIC";
Specifies the group to which execution rights are to be granted. Only one
group can be named.
The_Rights : Execution_Table := Cmvc_Access_Control.Nil_Rights;
Specifies the execution table containing the set of execution rights to be
granted. By default, no rights are set, so that the specified group cannot
apply any CMVC commands to the specified view, subsystem, or system.
View_Or_Subsystem : String := "<SELECTION>";
Specifies the view, subsystem, or system for which execution rights are to
be granted. Multiple views, subsystems, or systems can be specified using
wildcards, context characters, set notation, indirect files, and
attributes. The default is the highlighted view, subsystem, or system,
provided that the highlight contains the cursor.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
To grant a set of execution rights for a view, you must have Owner access
to the view.
To grant a set of execution rights for a subsystem, you must have Owner
access to the subsystem.
REFERENCES
type Execution_Table
@node !Commands.Cmvc_Access_Control.Subsystem_Client_Rights
Subsystem_Client_Rights : constant Execution_Table :=
Execution_Table'(Add_Child_Child => True, others => False)
or Subsystem_Reader_Rights;
DESCRIPTION
Represents the set of subsystem and system execution rights that can be
granted to groups with Client access to the subsystem (or system).
REFERENCES
type Execution_Table
constant Subsystem_Developer_Rights
constant Subsystem_Owner_Rights
constant Subsystem_Reader_Rights
@node !Commands.Cmvc_Access_Control.Subsystem_Client_View_Rights
Subsystem_Client_View_Rights : constant Execution_Table :=
Subsystem_Reader_View_Rights;
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Client access to the subsystem (or system) enclosing the view.
REFERENCES
type Execution_Table
constant Subsystem_Developer_View_Rights
constant Subsystem_Owner_View_Rights
constant Subsystem_Reader_View_Rights
@node !Commands.Cmvc_Access_Control.Subsystem_Developer_Rights
Subsystem_Developer_Rights : constant Execution_Table :=
Execution_Table'(Edit_Notes => True,
Add_Child_Parent => True,
Remove_Child => True,
Update_Cdb => True,
others => False)
or Subsystem_Client_Rights;
DESCRIPTION
Represents the set of subsystem and system execution rights that can be
granted to groups with Developer access to the subsystem (or system).
REFERENCES
type Execution_Table
constant Subsystem_Client_Rights
constant Subsystem_Owner_Rights
constant Subsystem_Reader_Rights
@node !Commands.Cmvc_Access_Control.Subsystem_Developer_View_Rights
Subsystem_Developer_View_Rights : constant Execution_Table :=
Execution_Table'(Check_Out => True,
Check_In => True,
Accept_Changes_Source => True,
Accept_Changes_Destination => True,
Abandon_Reservation => True,
Revert => True,
Modify_Notes => True,
Make_Controlled => True,
Make_Uncontrolled => True,
Sever => True,
Join_What => True,
Join_To => True,
Merge_Changes_Destination => True,
Merge_Changes_Source => True,
others => False)
or Subsystem_Client_View_Rights;
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Developer access to the subsystem (or system) enclosing the view.
REFERENCES
type Execution_Table
constant Subsystem_Client_View_Rights
constant Subsystem_Owner_View_Rights
constant Subsystem_Reader_View_Rights
@node !Commands.Cmvc_Access_Control.Subsystem_Owner_Rights
Subsystem_Owner_Rights : constant Execution_Table :=
Execution_Table'(Initial => True,
Destroy_Config => True,
Destroy_Subsystem => True,
Build => True,
Subsystem_Check_Consistency => True,
Expunge_Database => True,
Make_Primary => True,
Make_Secondary => True,
Destroy_Cdb => True,
others => False)
or Subsystem_Developer_Rights;
DESCRIPTION
Represents the set of subsystem and system execution rights that can be
granted to groups with Owner access to the subsystem (or system).
REFERENCES
type Execution_Table
constant Subsystem_Client_Rights
constant Subsystem_Developer_Rights
constant Subsystem_Reader_Rights
@node !Commands.Cmvc_Access_Control.Subsystem_Owner_View_Rights
Subsystem_Owner_View_Rights : constant Execution_Table :=
Execution_Table'(Release => True,
Copy => True,
Make_Path => True,
Make_Subpath => True,
Make_Spec_View => True,
Make_Code_View => True,
Destroy_View => True,
Check_Consistency => True,
others => False)
or Subsystem_Developer_View_Rights;
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Owner access to the subsystem (or system) enclosing the view.
REFERENCES
type Execution_Table
constant Subsystem_Client_View_Rights
constant Subsystem_Developer_View_Rights
constant Subsystem_Reader_View_Rights
@node !Commands.Cmvc_Access_Control.Subsystem_Reader_Rights
Subsystem_Reader_Rights : constant Execution_Table :=
Execution_Table'(Query_Subsystem => True,
others => False);
DESCRIPTION
Represents the set of subsystem and system execution rights that can be
granted to groups with Reader access to the subsystem (or system).
REFERENCES
type Execution_Table
constant Subsystem_Client_Rights
constant Subsystem_Developer_Rights
constant Subsystem_Owner_Rights
@node !Commands.Cmvc_Access_Control.Subsystem_Reader_View_Rights
Subsystem_Reader_View_Rights : constant Execution_Table :=
Execution_Table'(Import_From => True,
Import_Into => True,
Remove_Import => True,
Replace_Model => True,
Query_View => True,
Build_Activity_In => True,
Build_Activity_From => True,
Expand_Activity => True,
others => False);
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Reader access to the subsystem (or system) enclosing the view.
REFERENCES
type Execution_Table
constant Subsystem_Client_View_Rights
constant Subsystem_Developer_View_Rights
constant Subsystem_Owner_View_Rights
@node !Commands.Cmvc_Access_Control.View_Client_Rights
View_Client_Rights : constant Execution_Table :=
Execution_Table' (Import_From => True,
Build_Activity_From => True,
others => False)
or View_Reader_Rights;
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Client access to the view.
REFERENCES
type Execution_Table
constant View_Developer_Rights
constant View_Owner_Rights
constant View_Reader_Rights
@node !Commands.Cmvc_Access_Control.View_Developer_Rights
View_Developer_Rights : constant Execution_Table :=
Execution_Table'(Check_Out => True,
Check_In => True,
Accept_Changes_Destination => True,
Abandon_Reservation => True,
Revert => True,
Modify_Notes => True,
Make_Controlled => True,
Make_Uncontrolled => True,
Sever => True,
Join_What => True,
Release => True,
Make_Path => True,
Make_Subpath => True,
Make_Code_View => True,
Copy => True,
Make_Spec_View => True,
Merge_Changes_Destination => True,
Build_Activity_In => True,
others => False)
or View_Client_Rights;
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Developer access to the view.
REFERENCES
type Execution_Table
constant View_Client_Rights
constant View_Owner_Rights
constant View_Reader_Rights
@node !Commands.Cmvc_Access_Control.View_Owner_Rights
View_Owner_Rights : constant Execution_Table :=
Execution_Table'(Import_Into => True,
Remove_Import => True,
Replace_Model => True,
Destroy_View => True,
Check_Consistency => True,
others => False)
or View_Developer_Rights;
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Owner access to the view.
REFERENCES
type Execution_Table
constant View_Client_Rights
constant View_Developer_Rights
constant View_Reader_Rights
@node !Commands.Cmvc_Access_Control.View_Reader_Rights
View_Reader_Rights : constant Execution_Table :=
Execution_Table'(Accept_Changes_Source => True,
Join_To => True,
Merge_Changes_Source => True,
Query_View => True,
Expand_Activity => True,
others => False);
DESCRIPTION
Represents the set of view execution rights that can be granted to groups
with Reader access to the view.
REFERENCES
type Execution_Table
constant View_Client_Rights
constant View_Developer_Rights
constant View_Owner_Rights
@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 1.
!Users.Rational.Test_System.Rev1_0_1.Release_Information : Directory;
Load_Configurations : File;
Load_Views : File;
Spec_Configurations : File;
Spec_Views : File;
Figure 1 The Release_Information Directory
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_Con figurations 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>");
DESCRIPTION
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.
PARAMETERS
Child : String := ">>SYSTEM/SUBSYSTEM NAME<<";
Specifies one or more systems or subsystems to be added as children of a
system.
Multiple systems and subsystems can be specified by using wildcards,
context characters, special names, set notation, or an indirect file. (For
further information, see "Naming" in the Key Concepts in this book.)
To_System : String := "<CURSOR>";
Specifies the system to which children are to be added.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. If the
Comments parameter is specified, this comment also is entered in the work
order.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
PARAMETERS
Working_System_View : String := "<CURSOR>";
Specifies one or more working system views in which release activities are
to be built or updated. By default, the working system view designated by
the cursor is used.
Multiple systems and subsystems can be specified by using wildcards,
context characters, special names, set notation, or an indirect file. (For
further information, see "Naming" in the Key Concepts in this book.)
Views_To_Include : String := "<LATEST>";
Specifies one or more views to be included in the release activity. These
views must be in subsystems that are children of the system containing the
designated system view.
If the default value, "<LATEST>", is specified, then the latest releases of
all the children of the system are included in the release activity.
Nondefault values for this parameter are especially useful when using the
Build_Activity procedure to change entries in an existing release
activity.
Multiple systems and subsystems can be specified by using wildcards,
context characters, special names, set notation, or an indirect file. (For
further information, see "Naming" in the Key Concepts in this book.)
Update_Imports : Boolean := True;
Specifies whether or not the working system view imports spec views from
the subsystems referenced by the release activity.
If True, the default, the working system view imports spec views from all
of the subsystems referenced by the release activity. Views are imported
as specified by the Views_To_Include parameter. 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.
If False, no spec views are imported.
Allow_Code_Views : Boolean := False;
Specifies whether to include code views in a release activity.
If False, the default, code views are overlooked in favor of including the
latest load view in the release activity.
If True, code views are included in the release activity.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. If the
Comments parameter is specified, this comment also is entered in the work
order.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Hierarchy.Children
function Children
(Of_System : String := "<CURSOR>";
Recursive : Boolean := True;
Response : String := "<WARN>") return String;
DESCRIPTION
Returns a list of designated subsystem's children.
PARAMETERS
Of_System : String := "<CURSOR>";
Specifies the system whose children are to be listed.
Recursive : Boolean := True;
Specifies whether to list children recursively when the designated system
includes other systems as children. If True, the default, child systems
are expanded so that their children are listed.
If False, child systems are listed simply as systems.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return String;
Returns a list of system children.
@node !Commands.Cmvc_Hierarchy.Contents
function Contents (Of_System_View : String := "<CURSOR>";
Recursive : Boolean := True;
Response : String := "<WARN>")
return String;
DESCRIPTION
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.
PARAMETERS
Of_System_View : String := "<CURSOR>";
Specifies the system view that contains the release activity whose contents
are to be displayed. By default, the system view designated by the cursor
is used.
Recursive : Boolean := True;
Specifies whether to display release activity contents recursively when a
release activity includes references to system views. If True, the default
value, references to system views are expanded so that the contents of
their release activities are returned.
If False, the contents of release activities are not expanded.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
return String;
Returns the contents of the release activity of the designated system
view.
@node !Commands.Cmvc_Hierarchy.Expand_Activity
procedure Expand_Activity
(New_Activity : String := ">>NEW ACTIVITY NAME<<";
System_View : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
New_Activity : String := ">>NEW ACTIVITY NAME<<";
Specifies the name for the new release activity.
System_View : String := "<CURSOR>";
Specifies the system view whose release activity is to be copied.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Hierarchy.Parents
function Parents (Of_Subsystem : String := "<CURSOR>";
Recursive : Boolean := False;
Response : String := "<WARN>")
return String;
DESCRIPTION
Returns a list of systems that are parents to the designated subsystem.
PARAMETERS
Of_Subsystem : String := "<CURSOR>";
Specifies the subsystem whose parents are to be listed.
Recursive : Boolean := False;
Specifies whether to list parent systems recursively. If True, the default,
all parents, grandparents, and so on, are listed.
If False, only direct parent systems are listed.
Response : String := "<WARN>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command perseveres at errors, without raising an exception; logs only
negative, warning, error, and exception messages (++*, !!!, ***, %%%); and
uses other response characteristics, as specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
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>");
DESCRIPTION
Severs the relationship between a child system or subsystem and its
parent.
This procedure is the opposite of the Add_Child procedure.
PARAMETERS
Child : String := ">>SYSTEM/SUBSYSTEM NAME<<";
Specifies one or more child systems or subsystems to be removed.
Multiple systems and subsystems can be specified by using wildcards,
context characters, special names, set notation, or an indirect file. (For
further information, see "Naming" in the Key Concepts in this book.)
From_System : String := "<CURSOR>";
Specifies the system from which the specified children are to be removed. By
default, the system designated by the cursor is used.
Comments : String := "";
Specifies a comment to be logged in the work order indicated by the
Work_Order parameter. If no work order is specified and if there is no
default work order, the comment is discarded.
Work_Order : String := "<DEFAULT>";
Specifies the work order in which the command's action is recorded. If the
Comments parameter is specified, this comment also is entered in the work
order.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Maintenance
Packages Cmvc_Maintenance defifines 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).
RESOURCES IN PACKAGE CMVC_MAINTENANCE
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.)
Managing the CMVC database: Check_Consistency,
Expunge_Database
Managing the compatibility database (CDB)
and multiple-host development:
Destroy_Cdb Make_Secondary
Display_Cdb Update_Cdb
Make_Primary
Managing code views: Display_Code_View
CDB CAPABILITY
Many of the commands in this package affect the compatibility databases
(CDBs) of primary and secondary subsystems. In general, users can execute
these commands if they belong to a group that has Owner access to the
subsystems in question (for a description of Owner access, see package
Cmvc_Access_Control).
Because of the sensitive nature of CDB-related operations, some sites may
want additional control over who can perform them. This special control,
called CDB capability, can be granted to one or more groups that already
have Owner access to the relevant subsystems. Whereas Owner access is
always required to execute CDB-related commands, CDB capability provides
an additional control for sites that choose to use it.
To put CDB capability into effect, you must first create a file called
!Machine.Cdb_Capability. You can then grant CDB capability to individual
groups by granting them write access (W) to this file. A group must have
Owner access to a given subsystem and write access to the
!Machine.Cdb_Capability file to name that subsystem in the Make_Primary,
Make_Secondary, or Destroy_Cdb commands.
@node !Commands.Cmvc_Maintenance.Check_Consistency
procedure Check_Consistency (Views : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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:
* There is a configuration object in the Configurations directory for every
configuration represented in the database. Missing configuration objects
are recreated from the database.
* 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.
* 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:
* 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.)
* 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:
* Reconstruct a configuration object that was deleted by mistake.
* 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.
* 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.)
* 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.
PARAMETERS
Views : String := "<CURSOR>";
Specifies the views whose consistency is to be checked. The default is the
view designated by the cursor. If a subsystem or system is specified, all
of the views in that (sub)system are checked, along with the directory
structure at the (sub)system level.
Multiple views, subsystems, or systems can be specified by using wildcards,
context characters, special names, set notation, or an indirect file. (For
further information, see "Naming" in the Key Concepts in this book.)
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Maintenance.Convert_Old_Subsystem
procedure Convert_Old_Subsystem
(Which : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
Which : String := "<SELECTION>";
Specifies the subsystem whose views are to be converted. The default is the
current selection.
Multiple subsystems can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Maintenance.Delete_Unreferenced_Leading_Generations
procedure Delete_Unreferenced_Leading_Generations
(In_Subsystem : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
Not yet implemented.
PARAMETERS
In_Subsystem : String := "<CURSOR>";
Not yet implemented.
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>");
DESCRIPTION
Destroys the compatibility database for the specified subsystem.
To execute this command, a user must belong to a group that has Owner
access to the subsystem (and, at sites requiring CDB capability, write
access to the !Machine.Cdb_Capability file also).
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:
* 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.
* A compatibility database can be destroyed to remove references to any
units that were once compiled in the subsystem but are now deleted.
PARAMETERS
Subsystem : String := "<SELECTION>";
Specifies one or more subsystems whose compatibility databases are to be
destroyed. The default is the selected subsystem.
Multiple subsystems can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
Limit : String := "<WORLDS>";
Specifies which units can be demoted as a side effect of destroying the
compatibility database of each specified subsystem.
The default special value "<WORLDS>" means that demotion is limited to the
units in the views of the specified subsystems. Other values for this
parameter are given as enumerations of the Compilation.Change_Limit
subtype. For example, the string "<ALL_WORLDS>" permits the demotion of
units in other subsystems in order to demote the units in the specified
subsystems.
Effort_Only : Boolean := True;
Specifies whether to report the effort required without actually destroying
any compatibility databases.
When True (the default value), a report is generated listing the units
that would be demoted as a result of destroying the compatibility
database. The database is not actually destroyed. The effort rating
reported is a relative measure of the amount of work involved.
When False, the compatibility database is destroyed.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Maintenance.Display_Cdb
procedure Display_Cdb (Subsystem : String := "<CURSOR>";
Show_Units : Boolean := False;
Response : String := "<PROFILE>");
DESCRIPTION
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:
* Whether the subsystem is primary or secondary
* The subsystem identification number
* 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.
PARAMETERS
Subsystem : String := "<CURSOR>";
Specifies one or more subsystems whose compatibility database information
is to be displayed. The default is the subsystem designated by the cursor.
Multiple subsystems can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
Show_Units : Boolean := False;
Specifies whether to list the units represented in the compatibility
database for the specified subsystems. If True, each unit is listed,
followed by the number of declarations it contains. If False (the
default), only the total number of units is displayed.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
PARAMETERS
View : String := "<CURSOR>";
Specifies one or more code views about which to display information. The
default is the code view designated by the cursor.
Multiple code views can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
Verbose_Unit_Info : Boolean := False;
Specifies whether to display a full report for each unit in the specified
code views. If True, the command displays the withed units and other
compiler information for each unit in the code view. By default, a full
report is not displayed.
Show_Map_Info : Boolean := False;
Specifies whether to display the code segment mapping between each specified
code view and the load view from which it was generated. By default, the
mapping is not displayed.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Maintenance.Expunge_Database
procedure Expunge_Database (In_Subsystem : String := "<CURSOR>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
In_Subsystem : String := "<CURSOR>";
Specifies the subsystem whose CMVC database is to be expunged. The default
is the subsystem designated by the cursor. A system name can be specified
for this parameter as well.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Cmvc_Maintenance.Make_Primary
procedure Make_Primary (Subsystem : String := "<SELECTION>";
Moving_Primary : Boolean := False;
Response : String := "<PROFILE>");
DESCRIPTION
Converts the specified secondary subsystem into a primary subsystem with
its own updatable compatibility database.
To execute this command, a user must belong to a group that has Owner
access to the subsystem (and, at sites requiring CDB capability, write
access to the !Machine.Cdb_Capability file also).
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:
* Creating 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.
* 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.
PARAMETERS
Subsystem : String := "<SELECTION>";
Specifies one or more secondary subsystems to be converted to primary
subsystems. The default is the selected subsystem.
If the specified subsystem is already a primary subsystem, this command has
no effect.
If the specified subsystem contains views with target keys other than
R1000, the units in these views cannot be in the coded state.
Multiple subsystems can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
Moving_Primary : Boolean := False;
Specifies whether the converted subsystem is to retain its original
subsystem identification number.
When False (the default), the converted subsystem is given a new subsystem
identification number and so is no longer associated with its original
primary subsystem.
When True, the converted subsystem retains its original subsystem
identification number and preserves its previous association with other
subsystems. This is intended for moving a primary subsystem to a new
location.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
RESTRICTIONS
If the specified subsystem contains views with target keys other than
R1000, the units in these views cannot be in the coded state.
REFERENCES
procedure Destroy_Cdb
procedure Make_Secondary
procedure Update_Cdb
Library Management (LM), procedure Archive.Copy
@node !Commands.Cmvc_Maintenance.Make_Secondary
procedure Make_Secondary (Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
Converts the specified primary subsystem into a secondary subsystem with a
read-only compatibility database.
To execute this command, a user must belong to a group that has Owner
access to the subsystem (and, at sites requiring CDB capability, write
access to the !Machine.Cdb_Capability file also).
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.
PARAMETERS
Subsystem : String := "<SELECTION>";
Specifies one or more primary subsystems to be converted to secondary
subsystems. The default is the selected subsystem.
If the specified subsystem is already a secondary subsystem, this command
has no effect.
Multiple subsystems can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Make_Primary
procedure Update_Cdb
Library Management (LM), procedure Archive.Copy
Library Management (LM), procedure Archive.Restore
@node !Commands.Cmvc_Maintenance.Repair_Cdb
procedure Repair_Cdb (Subsystem : String := "<SELECTION>";
Verify_Only : Boolean := True;
Delete_Current : Boolean := False;
Response : String := "<PROFILE>");
DESCRIPTION
This command is no longer available. If you want to verify information in
the CDB, use the
!Tools.Compatibility'Spec_View.Units.Cdb_Maintenance.Verify command
instead. For details, see the comments in the specification of this
procedure.
@node !Commands.Cmvc_Maintenance.Update_Cdb
procedure Update_Cdb
(From_Subsystem : String := "<ASSOCIATED_PRIMARY>";
To_Subsystem : String := "<SELECTION>";
Response : String := "<PROFILE>");
DESCRIPTION
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:
* Compile incremental changes in the secondary subsystem
* 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.
PARAMETERS
From_Subsystem : String := "<ASSOCIATED_PRIMARY>";
Specifies the subsystem whose compatibility database is to be copied. The
compatibility database in From_Subsystem must be more recent than the
compatibility database in To_Subsystem.
The default special name "<ASSOCIATED_PRIMARY>" designates the primary
subsystem associated with the secondary subsystem specified by the
To_Subsystem parameter. The default value gets the name of the associated
primary subsystem from the subsystem.State.Compatibility.State file within
the secondary subsystem. Note that if the primary subsystem has been
moved, this file may be out of date. If so, the file must be edited to
supply the correct pathname for the associated primary subsystem;
otherwise, the name of the associated primary must be specified as the
value for the From_Subsystem parameter.
To_Subsystem : String := "<SELECTION>";
Specifies the secondary subsystem whose compatibility database is to be
updated. The default is the selected subsystem.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Make_Primary
Library Management (LM), procedure Archive.Copy
@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:
* Create, display, and edit the object
* View and set the default object for a user or session
* 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>");
DESCRIPTION
Adds one or more work orders to a work-order list.
PARAMETERS
Order_Names : String := "<IMAGE>";
Specifies one or more work orders to be added to the list. The default
special name "<IMAGE>" designates the currently selected work order if the
cursor is in the selection; otherwise, it designates the work order in the
current image.
Multiple work-order names can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
List_Name : String := "<WORK_LIST>";
Specifies the work-order list to which work orders will be appended. The
default special name "<WORK_LIST>" specifies the default work-order list
for the current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
ERRORS
An error will result if the work order(s) specified by the Order_Names
parameter were not created on the same venture as the work-order list
specified by the List_Name parameter.
REFERENCES
procedure Remove_From_List
@node !Commands.Work_Order.Close
procedure Close (Order_Name : String := "<ORDER>";
Response : String := "<PROFILE>");
DESCRIPTION
Sets the status of the specified work order to closed.
Once a work order has been closed, it no longer can be modified.
PARAMETERS
Order_Name : String := "<ORDER>";
Specifies the work order to be closed. The default special name "<ORDER>"
specifies the default work order for the current session. The null string
("") is interpreted to mean "<CURSOR>".
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
Creates a work order on the specified venture and adds it to a work-order
list. If you specify the name of an existing work order, the newly created
work order will overwrite the existing one.
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.
PARAMETERS
Order_Name : String := ">>OBJECT NAME<<";
Specifies the name for the new work order. The default parameter
placeholder ">>OBJECT NAME<<" must be replaced or an error will result.
Note: If you specify the name of an existing work order, the newly created
work order will overwrite the existing one.
Notes : String := "";
Specifies a string to be saved in the notes field of the work order. Notes
typically are used to provide a brief description of the work order.
On_List : String := "<WORK_LIST>";
Specifies a work-order list to which the new work order is appended. The
default special name "<WORK_LIST>" specifies the default work-order list
for the current session. If the current session has no default work-order
list, a warning message appears in the output log. If the value of this
parameter is the null string (""), the work order is not added to any
work-order list.
On_Venture : String := "<VENTURE>";
Specifies the venture for which the work order is created. The default
special name "<VENTURE>" specifies the default venture for the current
session.
Make_Default_Work_Order : Boolean := True;
Specifies whether to set the new work order as the session default. If True
(the default value), the new work order becomes the default work order on
the specified venture.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
ERRORS
An error will result if the work-order list specified by the On_List
parameter was not created on the venture specified by the On_Venture
parameter.
REFERENCES
function Default
procedure Set_Default
@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>");
DESCRIPTION
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.
PARAMETERS
Field_Name : String := ">>FIELD NAME<<";
Specifies the name for the user-defined field. The default parameter
placeholder ">>FIELD NAME<<" must be replaced or an error will result.
Field_Type : String := ">>BOOLEAN|STRING|INTEGER<<";
Specifies the data type for the new field. Fields can be created that
contain Boolean, string, or integer data. The default parameter
placeholder ">>BOOLEAN|STRING|INTEGER<<" must be replaced or an error will
result.
Is_Vector : Boolean := False;
Specifies whether the field accepts an array of values or a single value. If
False (the default value), the field accepts a single scalar value.
If True, the field accepts an array of values. The range of array indexes
is 1..Positive'Last. Because each value of a user-defined field can be
modified only once, the field should be created as a vector if its value
will need to be updated. Successive elements in the array then can be
modified. In this way, a history of changes to this field is provided.
Is_Controlled : Boolean := False;
Specifies whether the new field is controlled by the
Allow_Edit_Of_Work_Orders policy switch.
If True, the field can be edited interactively only if the
Allow_Edit_Of_Work_Orders policy switch is True in the venture. If False
(the default value), the field can be edited interactively regardless of
the value of the Allow_Edit_Of_Work_Orders policy switch.
Default : String := "";
Specifies an initial value for the field. The initial value will appear on
new work orders and in existing work orders if the field is propagated.
Display_Position : Natural := Natural'Last;
Specifies the display position of the field in the work order. If this is
set to 0, the field will not be visible when the work order is displayed
with the editor.
On_Venture : String := "<VENTURE>";
Specifies the name of the venture to which the new field is added. The
default special name "<VENTURE>" specifies the default venture for the
current session.
Propagate : Boolean := True;
Specifies, if True, that the field will be added to all existing work orders
on the venture.
Renumber_Fields : Boolean := True;
Specifies, if True, that the fields will be reordered if this is necessary
to make the new field have the Display_Position ordinal.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
Creates a work-order list on the specified venture.
PARAMETERS
List_Name : String := ">>OBJECT NAME<<";
Specifies the name of the new work-order list. The default parameter
placeholder ">>OBJECT NAME<<" must be replaced or an error will result.
Notes : String := "";
Specifies a string to be saved in the notes field of the work-order list.
Notes typically are used to provide a brief description of the work-order
list.
On_Venture : String := "<VENTURE>";
Specifies the name of the venture to which the new work-order list is
added. The default special name "<VENTURE>" specifies the default venture
for the current session.
Make_Default_List : Boolean := True;
Specifies whether to set the new work-order list as the session default. If
True (the default value), the new list becomes the new default work-order
list in the specified venture.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Set_Default_List
@node !Commands.Work_Order.Create_Venture
procedure Create_Venture
(Venture_Name : String := ">>OBJECT NAME<<";
Notes : String := "";
Make_Default_Venture : Boolean := True;
Response : String := "<PROFILE>");
DESCRIPTION
Creates a new venture.
PARAMETERS
Venture_Name : String := ">>OBJECT NAME<<";
Specifies the name of the new venture. The default parameter placeholder
">>OBJECT NAME<<" must be replaced or an error will result.
Notes : String := "";
Specifies a string to be saved in the notes field of the venture. Notes
typically are used to provide a brief description of the venture.
Make_Default_Venture : Boolean := True;
Specifies whether to set the new venture as the default. If True (the
default value), the new venture becomes the default venture for the
current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Set_Default_Venture
@node !Commands.Work_Order.Default
function Default (For_Venture : String := "<VENTURE>";
For_User : String := "<CURRENT_USER>";
Ignore_Garbage : Boolean := True) return String;
DESCRIPTION
Returns the name of the user's default work order in the specified venture.
PARAMETERS
For_Venture : String := "<VENTURE>";
Specifies the name of the venture to reference. The default special name
"<VENTURE>" specifies the default venture for the current session.
For_User : String := "<CURRENT_USER>";
Specifies the username for which the default work order is requested. If
only a username is supplied, session S_1 is assumed. If the user has
multiple sessions with default work orders in the venture, both the
username and the session name must be specified when the default work order
for a session other than S_1 is desired. The default special name
"<CURRENT_USER>" specifies the current session.
Ignore_Garbage : Boolean := True;
Specifies how to present results in case the once-valid default work order
is missing. If True (the default), the function result is "<>". If False,
the contents of the function result are unpredictable. When function
results are to be used directly in CMVC commands, it is recommended that
Ignore_Garbage is True.
return String;
Returns the pathname of the default work order.
EXAMPLES
The command:
Text_Io.Put_Line(Work_Order.Default)
displays the name of the default work order for the current user's current
session in the default venture.
The command:
Text_Io.Put_Line(Work_Order.Default (For_Venture => "My_Venture",
For_User => "User1"));
displays the name of the default work order for user User1, session S_1,
in My_Venture.
The command:
Text_Io.Put_Line(Work_Order.Default (For_Venture => "My_Venture",
For_User => "User1.Working"));
displays the name of the default work order for user User1, session
Working, in My_Venture.
REFERENCES
procedure Set_Default
@node !Commands.Work_Order.Default_List
function Default_List
(For_Venture : String := "<VENTURE>";
For_User : String := "<CURRENT_USER>";
Ignore_Garbage : Boolean := True) return String;
DESCRIPTION
Returns the name of the user's default work-order list in the specified
venture.
PARAMETERS
For_Venture : String := "<VENTURE>";
Specifies the name of the venture to reference. The default special name
"<VENTURE>" specifies the default venture for the current session.
For_User : String := "<CURRENT_USER>";
Specifies the username for which the default work-order list is requested.
If only a username is supplied, session S_1 is assumed. If the user has
multiple sessions with default work-order lists in the venture, the
username and the session name must be specified when the default work-order
list for a session other than S_1 is desired. The default parameter
"<CURRENT_USER>" specifies the current session.
Ignore_Garbage : Boolean := True;
Specifies how to present results in case the once-valid default work-order
list is missing. If True (the default), the function result is "<>". If
False, the contents of the function result are unpredictable. When
function results are to be used directly in CMVC commands, it is
recommended that Ignore_Garbage is True.
return String;
Returns the pathname of the default work-order list.
EXAMPLES
The command:
Text_Io.Put_Line(Work_Order.Default_List)
displays the name of the default work-order list for the current user's
current session in the default venture.
The command:
Text_Io.Put_Line(Work_Order.Default_List (For_Venture => "My_Venture",
For_User => "User1"));
displays the name of the default work-order list for user User1, session
S_1, in My_Venture.
The command:
Text_Io.Put_Line(Work_Order.Default_List (For_Venture => "My_Venture",
For_User =>
"User1.Working"));
displays the name of the default work-order list for user User1, session
Working, in My_Venture.
REFERENCES
procedure Set_Default_List
@node !Commands.Work_Order.Default_Venture
function Default_Venture
(For_User : String := "<CURRENT_USER>";
Ignore_Garbage : Boolean := True) return String;
DESCRIPTION
Returns the pathname of the default venture for a user.
PARAMETERS
For_User : String := "<CURRENT_USER>";
Specifies the username for which the default venture is requested. If only
a username is used, session S_1 is assumed. If the user has multiple
sessions and wants the default venture for a session other than S_1, the
session name must be specified. The default special name "<CURRENT_USER>"
specifies the current session.
Ignore_Garbage : Boolean := True;
Specifies how to present results in case the once-valid default venture is
missing. If True (the default), the function result is "<>". If False, the
contents of the function result are unpredictable. When function results
are to be used directly in CMVC commands, it is recommended that
Ignore_Garbage is True.
return String;
Returns the pathname of the default venture.
EXAMPLES
The command:
Text_Io.Put_Line(Work_Order.Default_Venture (For_User => "User1"));
displays the name of the default venture for user User1, session S_1.
The command:
Text_Io.Put_Line(Work_Order.Default_Venture (For_User =>
"User1.Working"));
displays the name of the default venture for user User1, session Working.
REFERENCES
procedure Set_Default_Venture
@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>");
DESCRIPTION
Deletes the named field from the venture.
PARAMETERS
Field_Name : String := ">>FIELD NAME<<";
Specifies the name of the field to be deleted.
Venture_Name : String := "<VENTURE>";
Specifies the name of the venture from which the field is deleted. The
default parameter "<VENTURE>" specifies the default venture for the current
session.
Even_If_Data_Present : Boolean := False;
Specifies whether to delete the field despite the presence of data in this
field for existing work orders. If False (the default value), the field is
not deleted when data would be lost.
If True, the field is deleted from the specified venture and any data in
that field of work orders is lost.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Create_field
@node !Commands.Work_Order.Display
procedure Display (Order_Name : String := "<ORDER>";
Options : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
Order_Name : String := "<ORDER>";
Specifies the name of the work order to be displayed. The default special
name "<ORDER>" specifies the default work order for the current session.
The null string ("") is interpreted to mean "<CURSOR>".
Options : String := "";
Specifies the format of the display. Valid options include names and values
for any of the session switches described at the beginning of package
Work_Order. When using these switch names as options, omit "Cmvc_" in the
switch name.
The following special options exist:
<TERSE> the default, specifies an abbreviated display
<DEFAULT> specifies use of current session-switch values
<VERBOSE> specifies an explanatory display
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Edit
@node !Commands.Work_Order.Display_List
procedure Display_List (List_Name : String := "<WORK_LIST>";
Options : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
List_Name : String := "<WORK_LIST>";
Specifies the name of the work-order list to be displayed. The default
special name "<WORK_LIST>" specifies the default work-order list for the
session. The null string ("") is interpreted to mean "<CURSOR>".
Options : String := "";
Specifies the format of the display. Valid options include names and values
for any of the session switches described at the beginning of package
Work_Order. When using these switch names as options, omit "Cmvc_" in the
switch name.
The following special options exist:
<TERSE> the default, specifies an abbreviated display
<DEFAULT> specifies use of current session-switch values
<VERBOSE> specifies an explanatory display
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Edit_List
@node !Commands.Work_Order.Display_Venture
procedure Display_Venture (Venture_Name : String := "<VENTURE>";
Options : String := "";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
Venture_Name : String := "<VENTURE>";
Specifies the name of the venture to be displayed. The default special name
"<VENTURE>" specifies the default venture for the current session. The null
string ("") is interpreted to mean "<CURSOR>".
Options : String := "";
Specifies the format of the display. Valid options include names and values
for any of the session switches described at the beginning of package
Work_Order. When using these switch names as options, omit "Cmvc_" in the
switch name.
The following special options exist:
<TERSE> the default, specifies an abbreviated display
<DEFAULT> specifies use of current session-switch values
<VERBOSE> specifies an explanatory display
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
procedure Edit_Venture
@node !Commands.Work_Order.Edit
procedure Edit (Order_Name : String := "<ORDER>");
DESCRIPTION
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.
PARAMETERS
Order_Name : String := "<ORDER>";
Specifies the name of the work order to be edited. The default special name
"<ORDER>" specifies the default work order for the current session. The
null string ("") is interpreted to mean "<CURSOR>".
@node !Commands.Work_Order.Edit_List
procedure Edit_List (List_Name : String := "<WORK_LIST>");
DESCRIPTION
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.
PARAMETERS
List_Name : String := "<WORK_LIST>";
Specifies the name of the work-order list to be edited. The default special
name "<WORK_LIST>" specifies the default work-order list for the current
session. The null string ("") is interpreted to mean "<CURSOR>".
REFERENCES
package Editor
@node !Commands.Work_Order.Edit_Venture
procedure Edit_Venture (Venture_Name : String := "<VENTURE>");
DESCRIPTION
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.
PARAMETERS
Venture_Name : String := "<VENTURE>";
Specifies the name of the venture to be edited. The default special name
"<VENTURE>" specifies the default venture for the current session. The null
string ("") is interpreted to mean "<CURSOR>".
REFERENCES
package List_Editor
@node !Commands.Work_Order.Notes
function Notes (Order_Name : String := "<ORDER>") return String;
DESCRIPTION
Returns the notes field of the specified work order.
The notes field typically contains descriptive information about a work
order.
PARAMETERS
Order_Name : String := "<ORDER>";
Specifies the work order whose notes field is to be displayed. The default
special name "<ORDER>" specifies the default work order for the current
session. The null string ("") is interpreted to mean "<CURSOR>".
return String;
Returns the notes field of the specified work order.
REFERENCES
package Venture_Editor
@node !Commands.Work_Order.Notes_List
function Notes_List (List_Name : String := "<WORK_LIST>")
return String;
DESCRIPTION
Returns the notes field of the specified work-order list.
The notes field typically contains descriptive information about a
work-order list.
PARAMETERS
List_Name : String := "<WORK_LIST>";
Specifies the work-order list whose notes field is to be displayed. The
default special name "<WORK_LIST>" specifies the default work-order list
for the current session. The null string ("") is interpreted to mean
"<CURSOR>".
return String;
Returns the notes field of the specified work-order list.
@node !Commands.Work_Order.Notes_Venture
function Notes_Venture (Venture_Name : String := "<VENTURE>")
return String;
DESCRIPTION
Returns the notes field for the specified venture.
The notes field typically contains descriptive information about a venture.
PARAMETERS
Venture_Name : String := "<VENTURE>";
Specifies the venture whose notes field is to be displayed. The default
special name "<VENTURE>" specifies the default venture for the current
session. The null string ("") is interpreted to mean "<CURSOR>".
return String;
Returns the notes field for the specified venture.
@node !Commands.Work_Order.Remove_From_List
procedure Remove_From_List (Order_Names : String := "<IMAGE>";
List_Name : String := "<WORK_LIST>";
Response : String := "<PROFILE>");
DESCRIPTION
Removes the entry for the specified work order from a work-order list.
PARAMETERS
Order_Names : String := "<IMAGE>";
Specifies one or more work orders to be deleted from the specified
work-order list. The default special name "<IMAGE>" designates the
currently selected work order if the cursor is in the selection;
otherwise, it designates the work order in the current image.
Multiple work-order names can be specified by using wildcards, context
characters, special names, set notation, or an indirect file. (For further
information, see "Naming" in the Key Concepts in this book.)
List_Name : String := "<WORK_LIST>";
Specifies the work-order list from which the work orders are deleted. The
default special name "<WORK_LIST>" specifies the default work-order list
for the current session.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@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>");
DESCRIPTION
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.
PARAMETERS
To_Work_Order : String := "<CURSOR>";
Specifies the new default work order for the specified venture. The default
value for this parameter is the work order on which the cursor is located.
Setting the To_Work_Order parameter to either "<>" or "" causes there to
be no default work order on the specified venture for the specified user and
session.
For_Venture : String := "<VENTURE>";
Specifies the venture for which the default work order is to be set. The
default special name "<VENTURE>" specifies the default venture for the
current session.
For_User : String := "<CURRENT_USER>";
Specifies the user and session for which the default work order is to be
set. This parameter can be a username (for example, Anderson) or a
username and session name (for example, Anderson.S_2). If only a username
is supplied, session S_1 is assumed. The default special name
"<CURRENT_USER>" specifies the current session for the current user.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
ERRORS
An error occurs if the To_Work_Order parameter names a work order that was
not created from the venture named by the For_Venture parameter.
REFERENCES
function Default
@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>");
DESCRIPTION
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.
PARAMETERS
To_List : String := "<CURSOR>";
Specifies the new default work-order list for the specified venture. The
default for this parameter is the work-order list on which the cursor is
located.
Setting the To_List parameter to either "<>" or "" causes there to be no
default work-order list on the specified venture for the specified user and
session.
For_Venture : String := "<VENTURE>";
Specifies the venture for which the default work-order list is to be set.
The default special name "<VENTURE>" specifies the default venture for the
current session.
For_User : String := "<CURRENT_USER>";
Specifies the user and session for which the default work-order list is to
be set. This parameter can be a username (for example, Anderson) or a
username and session name (for example, Anderson.S_2). If only a username
is supplied, session S_1 is assumed. The default special name
"<CURRENT_USER>" specifies the current session for the current user.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
function Default_List
@node !Commands.Work_Order.Set_Default_Venture
procedure Set_Default_Venture
(To_Venture : String := "<CURSOR>";
For_User : String := "<CURRENT_USER>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
To_Venture : String := "<CURSOR>";
Specifies the name of the new default venture. The default for this
parameter is the venture on which the cursor is located.
Setting the To_Venture parameter to either "<>" or "" causes there to be
no default venture for the specified user and session.
For_User : String := "<CURRENT_USER>";
Specifies the user and session for which the default venture is to be set.
This parameter can be a username (for example, Anderson) or a username and
session name (for example, Anderson.S_2). If only a username is supplied,
session S_1 is assumed. The default special name "<CURRENT_USER>" specifies
the current session for the current user.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
@node !Commands.Work_Order.Set_Notes
procedure Set_Notes (To_Value : String := ">>New Notes<<";
Order_Name : String := "<ORDER>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
To_Value : String := ">>New Notes<<";
Specifies the new notes. The default parameter placeholder ">>New Notes<<"
must be replaced or an error will result.
Order_Name : String := "<ORDER>";
Specifies the work order whose notes field is to be updated. The default
special name "<ORDER>" specifies the default work order for the current
session. The null string ("") is interpreted to mean "<CURSOR>".
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
function Notes
@node !Commands.Work_Order.Set_Notes_List
procedure Set_Notes_List (To_Value : String := ">>New Notes<<";
List_Name : String := "<WORK_LIST>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
To_Value : String := ">>New Notes<<";
Specifies the new notes. The default parameter placeholder ">>New Notes<<"
must be replaced or an error will result.
List_Name : String := "<WORK_LIST>";
Specifies the work-order list whose notes field is to be updated. The
default special name "<WORK_LIST>" specifies the default work-order list
for the current session. The null string ("") is interpreted to mean
"<CURSOR>".
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
function Notes_List
@node !Commands.Work_Order.Set_Notes_Venture
procedure Set_Notes_Venture
(To_Value : String := ">>New Notes<<";
Venture_Name : String := "<VENTURE>";
Response : String := "<PROFILE>");
DESCRIPTION
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.
PARAMETERS
To_Value : String := ">>New Notes<<";
Specifies the new notes. The default parameter placeholder ">>New Notes<<"
must be replaced or an error will result.
Venture_Name : String := "<VENTURE>";
Specifies the venture whose notes field is to be updated. The default
special name "<VENTURE>" specifies the default venture for the current
session. The null string ("") is interpreted to mean "<CURSOR>".
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
function Notes_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>");
DESCRIPTION
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.
PARAMETERS
The_Switch : Venture_Policy_Switch;
Specifies the venture policy switch to be modified or queried. This must be
the fully qualified name of the object--for example,
Work_Order.Require_Comment_Lines.
To_Value : Boolean;
Specifies the new value for the venture policy switch--either True or
False.
Venture_Name : String := "<VENTURE>";
Specifies the venture whose policy switch is to be modified or queried. The
default special name "<VENTURE>" specifies the default venture for the
current session. The null string ("" is interpreted to mean "<CURSOR>".
Effort_Only : Boolean := False;
Specifies whether to simply determine the value of the specified policy
switch, without actually changing that value. If True, the current value
of the policy switch is displayed in the output window and the switch is
not modified.
Response : String := "<PROFILE>";
Specifies how to respond to errors, where to send log messages, and what
activity to use during the execution of this command. By default, this
command uses the response characteristics specified in the job response
profile for the current job. For other values accepted by this parameter,
see Parameter-Value Conventions in the Reference Summary (RS) book.
REFERENCES
type Venture_Policy_Switch
@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);
DESCRIPTION
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.
ENUMERATIONS
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.
REFERENCES
procedure Set_Venture_Policy
@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
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>");
DESCRIPTION
Adds a comment to those recorded in the work order.
Once a comment has been added, it cannot be removed.
PARAMETERS
The_Comment : String := ">>Comment<<";
Specifies the text of the comment to be added. The default parameter
placeholder ">>Comment<<" must be replaced or an error will result. This
is an Ada string, which cannot span multiple lines.
The_Element : String := ">>Element Name<<";
Specifies the name of the object to which the comment applies. The default
parameter placeholder ">>Element Name<<" must be replaced or an error will
result.
The_User : String := "<CURRENT_USER>";
Specifies the name of a user session. If only a username is given, session
S_1 is assumed.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
EXAMPLES
Editor.Add_Comment (The_Comment => "This is a comment",
The_Element => "An_Element_Name",
The_User => "Sue");
@node !Commands.Work_Order.Editor.Add_Configuration
procedure Add_Configuration
(The_Configuration : String :=
">>Configuration Name<<");
DESCRIPTION
Adds a configuration to those recorded in the work order.
Once a configuration has been added, it cannot be removed.
PARAMETERS
The_Configuration : String := ">>Configuration Name<<";
Specifies the pathname of the configuration. The default parameter
placeholder ">>Configuration Name<<" must be replaced or an error will
result.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
EXAMPLES
Editor.Add_Configuration (The_Configuration =>
"!Project.User_Interface.Rev1_2_1");
@node !Commands.Work_Order.Editor.Add_User
procedure Add_User (The_User : String := "<CURRENT_USER>");
DESCRIPTION
Adds a user session to those recorded in the work order.
Once a user has been added, it cannot be removed.
PARAMETERS
The_User : String := "<CURRENT_USER>";
Specifies the name of a user session. If only a username is given, session
S_1 is assumed.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
EXAMPLES
Example command:
Editor.Add_User (The_User => "Bill");
Example user field in a work order:
Users: 2
Sue.Devel
Bill.S_1
@node !Commands.Work_Order.Editor.Add_Version
procedure Add_Version
(The_Configuration : String := ">>Configuration Name<<";
The_Element : String := ">>Element Name<<";
The_Generation : Natural := 0);
DESCRIPTION
Adds a version to those recorded in the work order.
Once a version has been added, it cannot be removed.
PARAMETERS
The_Configuration : String := ">>Configuration Name<<";
Specifies the name of the configuration containing the version. The default
parameter placeholder ">>Configuration Name<<" must be replaced or an
error will result.
The_Element : String := ">>Element Name<<";
Specifies the name of the object for which a version entry is to be added.
The default parameter placeholder ">>Element Name<<" must be replaced or
an error will result.
The_Generation : Natural := 0;
Specifies which generation of the object to add.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
EXAMPLES
Editor.Add_Version
(The_Configuration => "!Project.User_Interface.Rev1_2_1",
The_Element => "An_Element_Name",
The_Generation => 0);
@node !Commands.Work_Order.Editor.Set_Field
procedure Set_Field (To_Value : Boolean := False;
The_Index : Natural := 0;
The_Field : String := ">>Field Name<<");
DESCRIPTION
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.
PARAMETERS
To_Value : Boolean := False;
Specifies the Boolean value for the field.
The_Index : Natural := 0;
Specifies which element of a vector field to modify. If the field is a scalar
field, this parameter is ignored.
The_Field : String := ">>Field Name<<";
Specifies the name of the field to modify. The default parameter placeholder
">>Field Name<<" must be replaced or an error will result.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
@node !Commands.Work_Order.Editor.Set_Field
procedure Set_Field (To_Value : Integer := 0;
The_Index : Natural := 0;
The_Field : String := ">>Field Name<<");
DESCRIPTION
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.
PARAMETERS
To_Value : Integer := 0;
Specifies the integer value for the field.
The_Index : Natural := 0;
Specifies which element of a vector field to modify. If the field is a scalar
field, this parameter is ignored.
The_Field : String := ">>Field Name<<";
Specifies the name of the field to modify. The default parameter placeholder
">>Field Name<<" must be replaced or an error will result.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
@node !Commands.Work_Order.Editor.Set_Field
procedure Set_Field (To_Value : String := ">>Field Value<<";
The_Index : Natural := 0;
The_Field : String := ">>Field Name<<");
DESCRIPTION
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.
PARAMETERS
To_Value : String := ">>Field Value<<";
Specifies the string value for the field. The default parameter placeholder
">>Field Value<<" must be replaced or an error will result.
The_Index : Natural := 0;
Specifies which element of a vector field to modify. If the field is a scalar
field, this parameter is ignored.
The_Field : String := ">>Field Name<<";
Specifies the name of the field to modify. The default parameter placeholder
">>Field Name<<" must be replaced or an error will result.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
@node !Commands.Work_Order.Editor.Set_Notes
procedure Set_Notes (Notes : String := ">>New Notes<<");
DESCRIPTION
Sets the notes field of the work order to the specified string.
The specified text will replace the existing text.
PARAMETERS
Notes : String := ">>New Notes<<";
Specifies the text that will be placed in the notes field of the work order.
The default parameter placeholder ">>New Notes<<" must be replaced or an
error will result.
RESTRICTIONS
This command must be executed in a command window attached to a work
order.
@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<<");
DESCRIPTION
Adds the specified work orders to the local work-order list.
PARAMETERS
Work_Orders : String := ">>Work Order Names<<";
Specifies which work orders to add to the local work-order list. The
default parameter placeholder ">>Work Order Names<<" must be replaced or
an error will result.
Wildcards can be used to add multiple work orders with a single command.
RESTRICTIONS
This command must be executed in a command window attached to a work-order
list.
@node !Commands.Work_Order.List_Editor.Set_Notes
procedure Set_Notes (Notes : String := ">>New Notes<<");
DESCRIPTION
Sets the notes field of the work-order list to the specified string.
The specified text will replace the existing text.
PARAMETERS
Notes : String := ">>New Notes<<";
Specifies the text that will be placed in the notes field of the work-order
list. The default parameter placeholder ">>New Notes<<" must be replaced
or an error will result.
RESTRICTIONS
This command must be executed in a command window attached to a work-order
list.
@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
!Commands.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; 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>");
DESCRIPTION
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.
PARAMETERS
New_Default : String := "<SELECTION>";
Specifies which work-order list shall be made the default for the local
venture. The default special name "<SELECTION>" specifies the currently
selected work-order list.
For_User : String := "<CURRENT_USER>";
Specifies the user session for which the default is set. If only a username
is provided, session S_1 is assumed.
RESTRICTIONS
This command must be executed in a command window attached to a venture.
EXAMPLES
Assume that a venture has two work-order lists associated with it, as
follows:
Work_Order_Lists: (!Users.Sue.Development...)
...Task_List
...New_Tasks
The user enters the following command, selecting the work-order list
Task_List and specifying the session Sue.S_1:
Venture_Editor.Set_Default_List
(New_Default => "<SELECTION>", For_User => "Sue.S_1");
As a result, the following entry appears in the venture's list of default
work-order lists:
Default_Work_Order_Lists: (!Users.Sue.Development...)
Sue.S_1 => ...Task_List
@node !Commands.Work_Order.Venture_Editor.Set_Default_Order
procedure Set_Default_Order
(New_Default : String := "<SELECTION>";
For_User : String := "<CURRENT_USER>");
DESCRIPTION
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.
PARAMETERS
New_Default : String := "<SELECTION>";
Specifies which work order shall be made the default for the local venture.
The default special name "<SELECTION>" specifies the currently selected
work order.
For_User : String := "<CURRENT_USER>";
Specifies the user session for which the default is set. If only a username
is provided, session S_1 is assumed.
RESTRICTIONS
This command must be executed in a command window attached to a venture.
EXAMPLES
Assume that a venture has two work orders associated with it, as follows:
Work_Orders: (!Users.Sue.Development...)
...Update_L1 : Pending ;
...Update_R1 : Pending ;
The user enters the following command, selecting the work-order name
Update_L1 and specifying the session Sue.S_1:
Venture_Editor.Set_Default_Order
(New_Default => "<SELECTION>", For_User => "Sue.S_1");
As a result, the following entry appears in the venture's list of default
work orders:
Default_Work_Orders: (!Users.Sue.Development...)
Sue.S_1 => ...Update_L1
@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<<");
DESCRIPTION
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.
PARAMETERS
Is_Controlled : Boolean := False;
Specifies whether the field should be made controlled. Controlled fields are
subject to interactive modification only if the Allow_Edit_Of_Work_Orders
venture policy switch is True.
Display_Position : Natural := 1;
Specifies the numeric tag of the field.
The_Field : String := ">>Field Name<<";
Specifies the name of the field whose numeric tag and controlled flag shall
be modified. The default parameter placeholder ">>Field Name<<" must be
replaced or an error will result.
RESTRICTIONS
This command must be executed in a command window attached to a venture.
EXAMPLES
Given the following user's fields in the venture:
Fields:
"Completion_Date" String @ 5 => ""
"Problem_Description" String @ 10 => ""
"Project" String @ 20 => ""
the following command will move the "Completion_Date" field between the
"Problem_Description" and "Project" fields:
Venture_Editor.Set_Field_Info (Is_Controlled => False,
Display_Position => 15,
The_Field => "Completion_Date");
@node !Commands.Work_Order.Venture_Editor.Set_Notes
procedure Set_Notes (Notes : String := ">>New Notes<<");
DESCRIPTION
Sets the notes field of the venture to the specified string.
The specified text will replace the existing text.
PARAMETERS
Notes : String := ">>New Notes<<";
Specifies the text that will be placed in the notes field of the venture.
The default parameter placeholder ">>New Notes<<" must be replaced or an
error will result.
RESTRICTIONS
This command must be executed in a command window attached to a venture.
@node !Commands.Work_Order.Venture_Editor.Set_Policy
procedure Set_Policy (To_Value : Boolean := False;
The_Switch : Venture_Policy_Switch);
DESCRIPTION
Sets the value of the specified venture policy switch to the specified
value.
PARAMETERS
To_Value : Boolean := False;
Specifies, if True, that the policy shall be enforced by the CMVC system.
The_Switch : Venture_Policy_Switch;
Specifies which policy switch to modify.
RESTRICTIONS
This command must be executed in a command window attached to a venture.
REFERENCES
type Venture_Policy_Switch
@node !Commands.Work_Order.Venture_Editor.Spread_Fields
procedure Spread_Fields (Interval : Natural := 10);
DESCRIPTION
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.
PARAMETERS
Interval : Natural := 10;
Specifies the interval between numeric tags for all fields.
RESTRICTIONS
This command must be executed in a command window attached to a venture.
EXAMPLES
Given the following fields:
Fields:
"Problem_Description" String @ 1 => ""
"Completion_Date" String @ 2 => ""
"Project" String @ 3 => ""
the command:
Venture_Editor.Spread_Fields (Interval => 5);
will result in:
Fields:
"Problem_Description" String @ 5 => ""
"Completion_Date" String @ 10 => ""
"Project" String @ 15 => ""