DataMuseum.dk

Presents historical artifacts from the history of:

Rational R1000/400 Tapes

This is an automatic "excavation" of a thematic subset of
artifacts from Datamuseum.dk's BitArchive.

See our Wiki for more about Rational R1000/400 Tapes

Excavated with: AutoArchaeologist - Free & Open Source Software.


top - download
Index: ┃ P T

⟦b16c6ad6a⟧ TextFile

    Length: 695245 (0xa9bcd)
    Types: TextFile
    Names: »PM_HELP«

Derivation

└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
    └─ ⟦fc9b38f02⟧ »DATA« 
        └─⟦f95d63c89⟧ 
            └─⟦this⟧ 

TextFile


 @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 => ""