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: ┃ L T

⟦691ef969e⟧ TextFile

    Length: 817831 (0xc7aa7)
    Types: TextFile
    Names: »LM_HELP«

Derivation

└─⟦5f3412b64⟧ Bits:30000745 8mm tape, Rational 1000, ENVIRONMENT 12_6_5 TOOLS 
    └─ ⟦91c658230⟧ »DATA« 
        └─⟦f6fec0485⟧ 
            └─⟦this⟧ 

TextFile


 @node !Commands.Access_List

 Package Access_List provides commands for controlling access to
 Environment objects. With these commands, users can specify who has the
 right to view, change, delete, or create particular objects. Access
 control is especially useful for system managers and project leaders, as
 well as individual users.

 The commands in package Access_List are intended for interactive use.
 Package Access_List_Tools provides operations for programmatic access
 control--see package Access_List_Tools in this book. Package Operator
 provides operations for defining groups for access control--see System
 Management Utilities (SMU), package Operator. Finally, package
 Cmvc_Access_Control provides operations for managing access control in
 subsystems and views--see Project Management (PM), package
 Cmvc_Access_Control.


 RESOURCES IN PACKAGE ACCESS_LIST

 The commands in package Access_List fall into several functional groups,
 which are listed here along with the access-rights constants defined in
 this package:

 Access rights for files and Ada units: Read, Write

 Access rights for worlds:              Create, Delete, Owner, Read

 Setting access rights:                 Set, Set_Default

 Removing access rights:                Remove, Remove_Default

 Granting additional access rights:     Add, Add_Default

 Displaying access rights:              Display, Default_Display


 KEY CONCEPTS FOR PACKAGE ACCESS_LIST

 This section contains information about access to Environment library
 objects. Specifically, it contains information about:

 *  Access control

 *  Access-control lists (ACLs)

 *  Groups

 *  Access rights for files, Ada units, worlds, and directories

 *  ACLs for new objects

 *  Editor locks, versions, and ACLs

 *  Implications of access control on various Environment facilities


 Access Control

 Controlling access to an object means granting various access rights to
 specific groups of users. Access rights restrict the kinds of operations
 that are permitted on an object. For example, the Read access right (or
 simply read access) allows an object to be viewed and, if the object is an
 Ada unit, executed. However, read access by itself does not allow the
 object to be modified in any way (write access is required for that).

 Granting an access right to a group permits the users in that group to
 perform the operations allowed by the right. A group does not have access
 to an object unless the required access rights are explicitly granted.
 Thus, access control is a means of preventing unauthorized users from
 viewing or changing specific Environment objects.


 Access-Control Lists

 Access control is maintained through access-control lists (ACLs). Every
 world, file, and Ada unit has an ACL associated with it. An object's ACL
 contains entries of the form group_name=>access_rights. Each entry assigns
 one or more access rights to the members of a given group. For example,
 the entry "Engineering=>RW" assigns read and write access to members of
 the group named Engineering.

 An object's ACL can contain up to seven entries and up to 512 characters.
 Multiple entries are separated by commas. For example, the ACL
 "Engineering=>RW, Public=>R" assigns read and write access to members of
 Engineering but makes the object read-only to members of the group Public.

 Only three types of objects have ACLs: worlds, files, and Ada units. Access
 to directories is controlled by the ACL of the closest enclosing world.

 You can use the Set command to specify the entire ACL for an object; the
 Add command is useful for adding one or more entries to an ACL. The
 Display command displays the ACL in an Environment output window.


 Groups

 A group is a set of one or more usernames to which access rights can be
 granted. Every user automatically belongs to at least one group, which has
 the same name as the user. For example, the username John defines a group
 called John. This allows access rights to be granted to individual users
 straightforwardly, as in the ACL entry "John=>R".

 In addition, the usernames for all users are added by default to two
 predefined groups--namely, Public and Network_ Public. Granting access
 rights to either of these groups effectively gives all users access to a
 given object.

 User-defined groups are created and maintained by operations in package
 Operator. Groups cannot reference other groups, although there is no
 limit to the number of usernames that can belong to a group.
 Furthermore, there is no limit to the number of groups to which a username
 can belong. For example, user John may be a member of groups John, Public,
 Network_Public, and Engineering. Up to 1,000 user-defined groups can exist
 on a single R1000 at a time.

 A job is granted access to an object if the user initiating the job is a
 member of an appropriate group. That is, every job (command or program)
 has an access-control identity, which determines the access-control groups
 to which the job belongs. By default, the access-control identity is the
 username of the user who initiated the job. A job can operate on an object
 only if the job's access-control identity includes a group to which the
 required access rights have been granted. (Note that when a job is
 initiated by the !Commands.Program.Create_Job or !Commands-
 .Program.Run_Job command, the access-control identity can be set in the
 Options parameter. A job can change its access-control identity by calling
 the !Commands.Program.Change_Identity command.)


 Access Rights

 Access rights for files and Ada units differ from those for worlds. These
 differences are described below.


 Files and Ada Units

 Files and Ada units can have one or both of the following access rights:

 *  Read (R): Permits the current contents of an object to be inspected;
    permits Ada units to be executed.

 *  Write (W): Permits an object to be opened for editing or deleted;
    permits Ada units to be promoted or demoted.

 A message is displayed if you attempt to view or execute an object to
 which you do not have read access or if you attempt to modify an object to
 which you do not have write access.

 Note that to have read access to a file or an Ada unit, you must also have
 read access to every world that encloses it. Furthermore, to edit a file or
 an Ada unit, you must have write access to it as well as create access to
 the world enclosing it (see "Worlds," below). Write access to the object
 is required to open the object for editing, and create access to the
 enclosing world is required to create new versions of the object.


 Worlds

 Worlds can have one or more of the following access rights:

 *  Read (R): Permits the contents of a world to be viewed; permits names
    within a world to be resolved.

 *  Create (C): Permits new objects to be created in a world; permits new
    versions of existing objects to be created in a world.

 *  Delete (D): Permits a world to be deleted.

 *  Owner (O): Permits a world's links, library-switch associations, and
    ACL to be changed; permits the ACLs of objects in the world to be
    changed and permits objects in the world to be frozen or unfrozen; also
    permits subsystems to be created in world (must also have R and C
    access).

 A message is displayed if you attempt to view a world to which you do not
 have read access or if you attempt an operation on an object for which you
 do not have the appropriate create, delete, or owner access. Furthermore,
 if you attempt to reference an object in a world to which you do not have
 read access, the Environment acts as if the object does not exist.

 To view a world, you must have read access to that world and to every
 world that encloses it. Furthermore, you must have read access to the
 switch file associated with the world.


 Directories

 For access-control purposes, directories are ignored. Changes to
 directories are controlled by the ACL of the enclosing world:

 *  Creating a new object in a directory requires create access to the
    directory's enclosing world.

 *  Changing the ACL for an object in a directory requires owner access to
    the enclosing world.


 Mixing Access Rights

 When an ACL is specified for an object, the Set or Add commands ignore any
 access rights that are not applicable to that type of object. For example,
 the following ACL contains a mixture of access rights: "Public=>RWCOD".
 If this ACL is specified for a file or Ada unit, the Set or Add command
 ignores the world-related rights C, O, and D. If this ACL is specified for
 a world, the Set or Add command ignores the nonworld access right W. This
 allows you to use a single command to set access rights for multiple
 objects of various kinds.

 As a further convenience, the delete and write access rights are
 interchangeable. Thus, if write access (W) is specified for a world, it is
 converted to delete access (D); if delete access (D) is specified for a file
 or Ada unit, it is converted to write access (W).


 Overriding Access Rights

 Members of a special predefined group called Privileged can access any
 object regardless of its ACL. To activate this capability, a member of
 this group must first execute the !Commands.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.

 Note that privileged mode should not be confused with operator capability,
 which is described in the introduction to package Operator in SMU.


 ACLs for New Objects

 Worlds determine the ACLs for new objects created within them. In
 particular, a world's ACL is given to any new worlds created within it.
 Furthermore, in addition to its own ACL, every world has a default ACL
 associated with it. The default ACL is given to new files and Ada units
 created within the world. In sum:

 *  New worlds inherit the ACL of the enclosing world.

 *  New files and Ada units inherit the default ACL of the enclosing world.
    (However, a new version of a file or Ada unit inherits its ACL from
    the previous version of that object.)

 If you have owner access to the enclosing world, you can modify the ACLs
 that were inherited by the new objects, in addition to any other ACLs in
 the world.

 You can use the Set_Default command to specify the entire default ACL for
 a world; the Add_Default command is useful for adding one or more entries
 to the default ACL. The Default_Display command displays a world's default
 ACL in an Environment output window.


 Editor Locks, Versions, and ACLs

 Commands that change ACLs (such as Set and Add) are sensitive to read
 locks and write locks. In particular, 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. As a general rule:

 *  You can change the ACL of a text or Ada object when you or other users
    hold a read lock on that object.

 *  You can change the ACL of a text or Ada object when you hold the write
    lock on that object.

 *  You cannot change the ACL of a text or Ada object when another user
    holds the write lock on that object.

 Changing the ACL of a locked Ada unit has some side effects. Specifically,
 if you change the ACL of an Ada unit on which you hold a read or a write
 lock, 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 the ACL of an Ada unit on which another
 user holds a read lock, 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. A
 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.


 Implications of Access Control

 Access control interacts with various aspects of the Environment, as
 described below.


 Name Resolution

 When you specify an object name as a parameter value to a command, the
 Environment resolves the name by determining the object it references.
 The Environment cannot resolve a name to an object unless you have read
 access to the world that contains the object. This is especially important
 for naming expressions that contain wildcards.

 For example, assume that you have read access to the current library,
 which contains worlds called Public and Private. Assume further that you
 have read access to the world called Public but not to the world called
 Private. Then the following command lists the fully qualified name for
 Public, along with the fully qualified names for each object in Public:

   Library.Resolve("Public?")

 In contrast, the following command lists only the fully qualified name for
 Private, without listing the names of any of the objects in Private:

   Library.Resolve("Private?")

 Resolving an object name through a searchlist requires read access to the
 appropriate object and its containing world. Without the required
 access, the name will appear to be undefined.


 Links, Compilation, and Execution

 Adding a link from a world to an Ada unit requires read access to the unit
 and owner access to the world.

 Promoting an Ada unit requires write access to that unit and read access
 to any unit it withs. Promoting a unit and its closure requires write
 access to every unit whose state must be changed. (A unit's closure is the
 set of units that directly or indirectly with it.)

 Demoting an Ada unit requires write access to the unit. However, no access
 rights are required to any of the units in the closure.

 Executing commands or programs from a command window requires read access
 to all units named in the window. Similarly, when executing the
 !Commands.Program.Run_Job, !Commands.Program.Run, or
 !Commands.Program.Create_Job command, read access is required to any
 files named as input, output, or error files in the command's Options
 parameter.


 Networking

 Operations provided by Rational Networking--TCP/IP are governed by access
 control. An FTP operation succeeds only if the identity specified in the
 operation's parameter list has the appropriate access to the appropriate
 objects.

 When RPC servers are established on a machine, they are given the identity
 of the job or user that initiated them. For example, RPC servers
 established by !Machine.Initialization software are given the identity
 Network_Public. When a client program makes a request of a server, the
 server's identity is used to determine the client's access rights.

 To ensure adequate access rights, a client can optionally specify a new
 identity for the server to assume for the duration of the request. To do
 this, the client must pass a valid username and password to the server,
 and the server must use the !Commands.Program.Change_Identity command to
 adopt the username as its new access-control identity. Note that a server
 can have only one identity at a time. To process simultaneous requests
 specifying different identities, the server starts a separate job for each
 request. See the Rational Networking--TCP/IP Reference Manual for further
 information.


 CMVC and Subsystems

 When a project is managed by CMVC, access control must be managed by
 operations in package !Commands.Cmvc_Access_Control instead of
 operations in package Access_List. Cmvc_Access_Control operations
 automatically adjust access rights for the various subobjects within
 subsystems and views; furthermore, these operations can be used to grant
 execution rights for various commands in package !Commands.Cmvc. See the
 Project Management (PM) book for information about package
 Cmvc_Access_Control.


 Archive Commands

 When objects are saved with procedures from package Archive, the string
 form of each object's ACL is saved with it. You can restore objects with
 the saved ACLs; alternatively, you can specify new ACLs through options on
 the restore operation. These options also permit restored objects to
 retain the ACLs of any objects they overwrite or to inherit their ACLs
 from the context into which they are restored. Note that when objects are
 restored into views, ACLs are always inherited; this occurs because CMVC
 access control must manage the ACLs of objects in views.


 @node !Commands.Access_List.Acl

 subtype Acl is String;

 DESCRIPTION

 Defines the form of access-control lists (ACLs).

 An ACL is a string that specifies, for a given object, the various access
 rights that are granted to various groups of users. Each world, file, or
 Ada unit has an ACL associated with it.

 An ACL consists of a list of entries, where each entry is of the form
 group_name =>access_rights. Each entry assigns one or more access rights
 to the members of a given group. For example, the entry "Engineering=>RW"
 assigns read and write access to members of the group named Engineering.
 If a group is not explicitly listed in the ACL for an object, that group
 is granted no access.

 An object's ACL can contain multiple entries separated by commas. For
 example, the ACL "Engineering=>RW, Public=>R" assigns read and write
 access to members of Engineering but makes the object read-only to members
 of the group Public. A maximum of seven entries and 512 characters are
 allowed in an ACL.

 A job is granted access to an object based on the identity of the user who
 initiates it. For the job to obtain access, the user initiating it must be
 a member of a group granted the required access listed in the ACL.


 EXAMPLES

 The following ACL for a world grants members of two groups (GZC and
 Public) different access rights to that world. Group GZC has create,
 owner, and delete access to that world, whereas group Public has only read
 access:

   "GZC=>RCOD,Public=>R"

 The following ACL for a file or an Ada unit grants read and write access to
 a single group called GZC:

   "GZC=>RW"


 @node !Commands.Access_List.Add

 procedure Add (To_List    : Acl    := "Network_Public => RWCOD";
                For_Object : Name   := "<SELECTION>";
                Response   : String := "<PROFILE>");

 DESCRIPTION

 Adds one or more entries to the ACL(s) for the specified object(s).

 Modifying an object's ACL requires owner access to the object itself (if
 the object is a world) or to the nearest world enclosing the object (if
 the object is a file or an Ada unit).

 When more than one object is specified by the For_Object parameter, log
 messages report the success or failure of each operation and the number
 of objects whose ACLs have been successfully or unsuccessfully set. By
 default, log messages are sent to an Environment output window.


 PARAMETERS

 To_List : Acl := "Network_Public => RWCOD";

 Specifies one or more ACL entries, each of the form
 group_name=>access_rights. Multiple entries must be separated by commas.
 The default is to give all access rights to members of group
 Network_Public.


 For_Object : Name := "<SELECTION>";

 Specifies one or more objects whose ACL is to be modified. Multiple objects
 can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. The default is the selected object.


 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 Display
 procedure Remove
 procedure Set



 @node !Commands.Access_List.Add_Default

 procedure Add_Default
              (To_List   : Acl    := "Network_Public => RW";
               For_World : Name   := "<SELECTION>";
               Response  : String := "<PROFILE>");

 DESCRIPTION


 Adds one or more entries to the default ACL(s) for the specified world(s).

 A world's default ACL is used to initialize the ACLs of new Ada units and
 files created in the world. Modifying a world's ACL requires owner access
 to that world.

 When more than one world is specified by the For_World parameter, log mes-
 sages report the number of worlds whose default ACLs have been
 successfully or unsuccessfully set. Log messages also indicate the number
 of objects that were skipped because they were not worlds. By default, log
 messages are sent to an Environment output window.


 PARAMETERS

 To_List : Acl := "Network_Public => RW";

 Specifies one or more entries to be added to the default ACL(s) of the
 specified world(s). Each entry is of the form group_name=>access_rights.
 Multiple entries must be separated by commas. The default gives read and
 write access to members of group Network_Public.


 For_World : Name := "<SELECTION>";

 Specifies one or more worlds whose default ACL is to be modified. Multiple
 worlds can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. If nonworld objects are matched by this
 parameter, they are skipped. The default is the selected world.


 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 Default_Display
 procedure Remove_Default
 procedure Set_Default



 @node !Commands.Access_List.Create

 Create : constant Character := 'C';

 DESCRIPTION


 Defines the Create access right, which applies only to worlds.

 Create access permits new objects to be created in a world. Create access
 also permits new versions of existing objects to be created in a world.
 Note that create access to a world applies to all directories within the
 world, although this access right does not extend into any subworlds.

 See "References," below, for other access rights.


 REFERENCES

 constant Delete
 constant Owner
 constant Read
 constant Write



 @node !Commands.Access_List.Default_Display

 procedure Default_Display (For_World : Name := "<CURSOR>");

 DESCRIPTION


 Displays the default access-control list (ACL) associated with the
 specified world or worlds.

 A world's default ACL is used to initialize the ACLs of new Ada units and
 files created in the world.

 The job display is sent to Current_Output (by default, an Environment
 output window). Errors are reported in log messages, which, by default,
 are also sent to the output window.


 PARAMETERS

 For_World : Name := "<CURSOR>";

 Specifies one or more worlds whose default ACLs are to be displayed. The
 default is the world indicated by the cursor. Multiple worlds can be
 specified using wildcards, context characters, set notation, indirect
 files, and attributes. If nonworld objects are matched by this parameter,
 they are skipped.


 EXAMPLES

 The following command displays the default ACL for the world !Users.Gzc:

   Access_List.Default_Display (For_World => "!Users.Gzc");

 The command produces the following display in an Environment output
 window, indicating that, by default, users in group GZC are granted read
 and write access and users in group Network_Public are granted read access
 to objects in !Users.Gzc:

   !USERS.GZC : GZC=>RW, NETWORK_PUBLIC=>R
                 

 REFERENCES

 procedure Set_Default



 @node !Commands.Access_List.Delete

 Delete : constant Character := 'D';

 DESCRIPTION


 Defines the Delete access right, which applies only to worlds.

 Delete access permits a world to be deleted. Delete access is
 interchangeable with write access (defined by the constant Write).

 See "References," below, for other access rights.


 REFERENCES

 constant Create
 constant Owner
 constant Read
 constant Write



 @node !Commands.Access_List.Display

 procedure Display (For_Object : Name := "<CURSOR>");


 DESCRIPTION

 Displays the access-control list (ACL) for the specified object or objects.

 ACLs can be displayed for worlds, files, and Ada units.

 The job display is sent to Current_Output (by default, an Environment
 output window). Errors are reported in log messages, which, by default,
 are also sent to the output window.


 PARAMETERS

 For_Object : Name := "<CURSOR>";

 Specifies one or more objects whose ACL is to be displayed. The default is
 the object indicated by the cursor. Multiple objects can be specified using
 wildcards, context characters, set notation, indirect files, and
 attributes.


 EXAMPLES

 The following command displays the ACL for the object !Users.Gzc.File_1:

   Access_List.Display (For_Object => "!Users.Gzc.File_1");

 This command produces the following display in an Environment output
 window, indicating that users in group GZC have been granted read and
 write access to File_1:

   !USERS.GZC.FILE_1 : GZC=>RW

 The following command displays the ACLs for all objects in the world
 !Users.Gzc:

   Access_List.Display (For_Object => "!Users.Gzc??");

 The list of ACLs is displayed in an Environment output window, as follows:


   Context: !USERS
   GZC                         : GZC=>RCOD,NETWORK_PUBLIC=>R
   GZC.DIRECTORY_1             : This object has no ACL
   GZC.DIRECTORY_1.FILE_1'V(1) : GZC=>RW,NETWORK_PUBLIC=>R
   GZC.GROUP_PHONE_LIST'V(2)   : GZC=>RW,GROUP_MEMBERS=>RW,NETWORK_PUBLIC=>R
   GZC.MY_PHONE_LIST'V(1)      : GZC=>RW
   GZC.S_1'V(1)                : This object has no ACL
   GZC.S_1_SWITCHES'V(1)       : GZC=>RW,NETWORK_PUBLIC=>R
   GZC.UNIT_1'V(4)             : GZC=>RW,NETWORK_PUBLIC=>R
   GZC.UNIT_1'BODY'V(7)        : GZC=>RW,NETWORK_PUBLIC=>R
   GZC.WORLD_1                 : GZC=>RCOD,NETWORK_PUBLIC=>R
   GZC.WORLD_1.DIRECTORY_1     : This object has no ACL
   GZC.WORLD_1.SUB_WORLD       : GZC=>RCOD,GROUP_MEMBERS=>RC,NETWORK_PUBLIC=>R
   GZC.WORLD_1.SUB_WORLD.UNIT'V(1)
                               : GZC=>RW,GROUP_MEMBERS=>RW,NETWORK_PUBLIC=>R
   GZC.WORLD_1.SUB_WORLD.UNIT'BODY'V(1)
                               : GZC=>RW,GROUP_MEMBERS=>RW,NETWORK_PUBLIC=>R
   GZC.WORLD_1.TO_DO_FILE'V(2) : GZC=>RW,GROUP_MEMBERS=>RW,NETWORK_PUBLIC=>R
                                 

 REFERENCES

 procedure Set



 @node !Commands.Access_List.Name

 subtype Name is String;

 DESCRIPTION

 Defines the subtype for names of objects used by procedures in this
 package.

 This subtype allows the use of wildcards, special names, context
 characters, set notation, indirect files, attributes, and substitution
 characters. See the Parameter-Value Conventions tabbed section in the
 Reference Summary (RS) book for more information about naming.



 @node !Commands.Access_List.Owner

 Owner  : constant Character := 'O';

 DESCRIPTION

 Defines the Owner access right, which applies only to worlds.

 Owner access to a world permits:

 *  Changing the access-control list (ACL) of the world itself or of
    objects in the world

 *  Changing the default ACL associated with the world

 *  Changing the links in the world

 *  Changing the library switch file associated with the world

 *  Freezing and unfreezing objects in the world

 Note that more than one user can have owner access to a given world. Owner
 access to a world applies to all directories within the world, although
 this access right does not extend into any subworlds.

 See "References," below, for other access rights.


 REFERENCES

 constant Create
 constant Delete
 constant Read
 constant Write



 @node !Commands.Access_List.Read

 Read : constant Character := 'R';

 DESCRIPTION

 Defines the Read access right, which applies to worlds, Ada units, and
 files.

 For files and Ada units, read access permits:

 *  Viewing the object (for example, using the !Commands.Common.Definition
    command)

 *  Opening the object for In_File mode

 *  Manipulating the object using certain Rational debugger commands

 *  Executing Ada units

 For worlds, read access permits:

 *  Viewing the world's contents

 *  Resolving the names of objects in the world

 Read access to a world applies to all directories within the world,
 although this access right does not extend into any subworlds.

 See "References," below, for other access rights.


 ERRORS

 In I/O operations, read access is required for In_File mode. In other
 words, a user who wants to open a file to read it must have read access to
 the file. The !Io.Io_Exceptions.Use_Error exception is raised for access
 failures from Io packages.


 REFERENCES

 constant Create
 constant Delete
 constant Owner
 constant Write



 @node !Commands.Access_List.Remove

 procedure Remove (Group      : String := ">>SIMPLE NAME<<";
                   For_Object : Name   := "<SELECTION>";
                   Response   : String := "<PROFILE>");

 DESCRIPTION

 Removes the specified group from the access list of each of the specified
 objects.

 Modifying an object's ACL requires owner access to the object itself (if
 the object is a world) or to the nearest world enclosing the object (if
 the object is a file or an Ada unit).

 When more than one object is specified by the For_Object parameter, log
 messages report the success or failure of each operation and the number
 of objects whose ACLs have been successfully or unsuccessfully set. By
 default, log messages are sent to an Environment output window.


 PARAMETERS

 Group : String := ">>SIMPLE NAME<<";

 Specifies the group to be removed from the access list of each of the
 specified objects.


 For_Object : Name := "<SELECTION>";

 Specifies one or more objects whose ACL is to be modified. Multiple objects
 can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. The default is the selected object.


 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 Add
 procedure Display
 procedure Set



 @node !Commands.Access_List.Remove_Default

 procedure Remove_Default
                  (Group      : String := ">>SIMPLE NAME<<";
                   For_World  : Name   := "<SELECTION>";
                   Response   : String := "<PROFILE>");

 DESCRIPTION

 Removes the specified group from the default access list of each of the
 specified worlds.

 A world's default ACL is used to initialize the ACLs of new Ada units and
 files created in the world. Modifying a world's ACL requires owner access
 to that world.

 When more than one object is specified by the For_World parameter, log mes-
 sages report the success or failure of each operation and the number of
 objects whose default ACLs have been successfully or unsuccessfully set.
 By default, log messages are sent to an Environment output window.


 PARAMETERS

 Group : String := ">>SIMPLE NAME<<";

 Specifies the group to be removed from the default access list of each of
 the specified worlds.


 For_World : Name := "<SELECTION>";

 Specifies one or more worlds whose default ACL is to be modified. Multiple
 worlds can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. If nonworld objects are matched by this
 parameter, they are skipped. The default is the selected world.


 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 Add_Default
 procedure Default_Display
 procedure Set_Default



 @node !Commands.Access_List.Set

 procedure Set (To_List    : Acl    := "Network_Public => RWCOD";
                For_Object : Name   := "<SELECTION>";
                Response   : String := "<PROFILE>");

 DESCRIPTION

 Sets the access-control list (ACL) for the specified object or objects.

 Setting an object's ACL requires owner access to the nearest world
 enclosing the object.

 When more than one object is specified, log messages report the success or
 failure of each operation, the number of objects whose ACLs have been
 successfully set, and the number of objects for which ACLs could not be
 set. By default, log messages are sent to an Environment output window.

 Note that setting a world's ACL does not require owner access to the world
 itself, provided that you have owner access to its parent world. This
 allows you to change the ACL of a world when no one has owner access to
 it.


 PARAMETERS

 To_List : Acl := "Network_Public => RWCOD";

 Specifies the ACL to be set for the specified objects. An ACL consists of
 multiple entries, each of the form group_name=>access_rights. Multiple
 entries must be separated by commas. The default is to give all access
 rights to members of group Network_Public.


 For_Object : Name := "<SELECTION>";

 Specifies one or more objects whose ACL is to be set. Multiple objects can
 be specified using wildcards, context characters, set notation, indirect
 files, and attributes. The default is the selected object.


 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 changes the ACL for the file named Text, so that the
 only group to have read or write access to that file is GZC:

   Access_List.Set (To_List    => "Gzc=>RW",
                    For_Object => "Text",
                    Response   => "<PROFILE>");

 REFERENCES

 procedure Add
 procedure Display
 procedure Remove



 @node !Commands.Access_List.Set_Default

 procedure Set_Default
              (To_List   : Acl    := "Network_Public => RW";
               For_World : Name   := "<SELECTION>";
               Response  : String := "<PROFILE>");

 DESCRIPTION

 Sets the default access-control list (ACL) for the specified world or
 worlds.

 Setting a world's ACL requires owner access to that world. A world's
 default ACL is used to initialize the ACLs of new Ada units and files
 created in the world.

 When more than one world is specified by the For_World parameter, log
 messages report the number of worlds whose default ACLs have been
 successfully or unsuccessfully set. Log messages also indicate the
 number of objects that were skipped because they were not worlds. By
 default, log messages are sent to an Environment output window.


 PARAMETERS

 To_List : Acl := "Network_Public => RW";

 Specifies the ACL to be set for the specified worlds. An ACL is a list of
 entries of the form group_name=>access_rights. Multiple entries must be
 separated by commas. The default gives read and write access to members
 of group Network_Public.


 For_World : Name := "<SELECTION>";

 Specifies one or more worlds whose default ACL is to be set. Multiple
 worlds can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. If nonworld objects are matched by this
 parameter, they are skipped. The default is the selected world.


 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

 Assuming that the selected object is a world, the following command
 changes the ACL for that world, so that the only group to have read or
 write access to new objects created in that world is GZC:

   Access_List.Set_Default (To_List   => "Gzc=>RW",
                            For_World => "<SELECTION>",
                            Response  => "<PROFILE>");

 REFERENCES

 procedure Add_Default
 procedure Default_Display
 procedure Remove_Default



 @node !Commands.Access_List.Write

 Write  : constant Character := 'W';

 DESCRIPTION

 Defines the Write access right, which applies to Ada units and files.

 Write access permits operations that change the value of an object, such
 as editing, deleting, promoting, and demoting. Write access is synonymous
 with delete access (defined by the constant Delete).

 Note that editing a file or an Ada unit requires create access to the
 enclosing world in addition to write access to the object itself. Whereas
 write access is required to open the object for editing, create access to
 the enclosing world is required to create new versions of the object.

 See "References," below, for other access rights.


 ERRORS

 In I/O operations, write access is required for Inout_File and Out_File
 modes. In other words, if a user wants to open a file for Read/Write or
 Write mode, the user must have write access to the file. The
 !Io.Io_Exceptions.Use_Error exception is raised for access failures from
 Io packages.


 REFERENCES

 constant Create
 constant Delete
 constant Owner
 constant Read



 @node !Tools.Access_List_Tools

 Package Access_List_Tools provides operations for programmatically
 controlling access to Environment objects. With these operations, users
 can build their own tools to specify who has the right to view, change,
 delete, or create particular objects. Access-control tools are
 especially useful for system managers and project leaders.

 The operations in package Access_List_Tools are intended for use in
 programs. Package Access_List provides commands for interactive access
 control (see package Access_List in this book). Package Operator
 provides operations for defining groups for access control; see System
 Management Utilities (SMU), package Operator.


 RESOURCES IN PACKAGE ACCESS_LIST_TOOLS

 The procedures and functions in package Access_List_Tools fall into
 several functional groups, which are listed here along with the
 access-rights constants defined in this package:

 Access rights for files and Ada units:   Read, Write

 Access rights for worlds:               Create, Delete, Owner, Read

 Retrieving access rights:               Get, Get_Default

 Setting or removing access rights:      Remove, Set, Set_Default

 Granting additional access rights:      Amend

 Checking whether access has been granted: Check, Grants, Is_In_Group

 Ensuring well-formed access lists:      Check_Validity, Is_Valid_Group,
                                         Normalize

 Querying for operator capability        Has_Operator_Capability


 KEY CONCEPTS FOR PACKAGE ACCESS_LIST_TOOLS

 See the introduction to package Access_List for a discussion of basic
 access-control concepts.


 @node !Tools.Access_List_Tools.Access_Class

 subtype Access_Class is String;

 DESCRIPTION


 Defines the form of access classes.

 Access classes consist of one or more of the following characters: R, W,
 C, O, and D. These characters can be upper- or lowercase. The characters
 stand for, respectively, the following access rights: read, write,
 create, owner, and delete.


 REFERENCES

 constant Create
 constant Delete
 constant Owner
 constant Read
 constant Write



 @node !Tools.Access_List_Tools.Access_Tools_Error

 Access_Tools_Error : exception;

 DESCRIPTION


 Defines the exception raised when an error condition occurs as the result
 of executing a procedure in this package.

 When an error occurs as the result of executing a procedure in this
 package, an error condition and a message describing the error are
 returned in the Status parameter.



 @node !Tools.Access_List_Tools.Acl

 subtype Acl is String;

 DESCRIPTION

 Defines the form of access-control lists (ACLs).

 An ACL is a string that specifies, for a given object, the various access
 rights that are granted to various groups of users. Each world, file, or
 Ada unit has an ACL associated with it.

 An ACL consists of a list of entries, where each entry is of the form
 group_name =>access_rights. Each entry assigns one or more access rights
 to the members of
 a given group. For example, the entry "Engineering=>RW" assigns read and
 write access to members of the group named Engineering. If a group is not
 explicitly listed in the ACL for an object, that group is granted no
 access.

 An object's ACL can contain multiple entries separated by commas. For
 example, the ACL "Engineering=>RW, Public=>R" assigns read and write
 access to members of Engineering but makes the object read-only to members
 of the group Public. A maximum of seven entries and 512 characters are
 allowed in an ACL.

 A job is granted access to an object based on the identity of the user who
 initiates it. For the job to obtain access, the user initiating it must be
 a member of a group granted the required access listed in the ACL.


 EXAMPLES

 The following ACL for a world grants members of two groups (GZC and
 Public) different access rights to that world. Group GZC has read, create,
 owner, and delete access to that world, whereas group Public has create
 access only:

   "GZC=>RCOD, Public=>C"

 The following example of an ACL for a file or an Ada unit grants read and
 write access to a group called GZC:

   "GZC=>RW"


 @node !Tools.Access_List_Tools.Amend

 function Amend (Initial_Acl : Acl;
                 New_Group   : Name;
                 Desired     : Access_Class) return Acl;

 DESCRIPTION


 Returns an amended access-control list (ACL).

 If a username is already granted access because of membership in a group
 in the initial ACL, the new group will not be appended to the initial ACL.

 If the addition of a new entry to the ACL causes the ACL to exceed the
 maximum of seven entries, the rightmost entry is removed.


 PARAMETERS

 Initial_Acl : Acl;

 Specifies the initial ACL, before it is amended.


 New_Group : Name;

 Specifies the new group to be added to the ACL. Context prefixes and
 wildcards can be used, provided they resolve to a single group.


 Desired : Access_Class;

 Specifies one or more access rights to be granted to the new group. Access
 rights are specified using one or more of the following characters, in
 upper- or lowercase: R (read), W (write), C (create), O (owner), or D
 (delete).


 return Acl;

 Returns an amended ACL.


 ERRORS

 The Access_Tools_Error exception is raised if an error occurs.

 Common errors include an illegal ACL for the Initial_Acl parameter and an
 illegal name for the New_Group parameter.


 EXAMPLES

 The following example illustrates how the Amend function can be used in
 conjunction with other procedures in this package to update the ACL for
 an object:

   with Log, Simple_Status, Access_List_Tools;
   procedure Amend_Example (Filename             : String;
                            Added_Group          : String;
                            Desired_Group_Access : String) is
       Status : Simple_Status.Condition;
   begin
   ...

   -- Add a group to the access list, supplied by the user.
       Access_List_Tools.Set
          (Filename,
           (Access_List_Tools.Amend
               (Access_List_Tools.Get (Filename),
                Added_Group,
                Desired_Group_Access)),
           Status);
       Log.Put_Condition (Status);
   -- Display the results of adding the group.
   ...
   end Amend_Example;
   

 REFERENCES

 subtype Acl
 function Get
 procedure Get
 procedure Set



 @node !Tools.Access_List_Tools.Check

 function Check (User_Name : String := "";
                 Object_Id : Directory.Version;
                 Desired   : Access_Class) return Boolean;

 function Check (User_Name   : String := "";
                 Object_Name : String;
                 Desired     : Access_Class) return Boolean;

 function Check (User_Id   : Directory.Version;
                 Object_Id : Directory.Version;
                 Desired   : Access_Class) return Boolean;

 function Check (Job       : Machine.Job_Id;
                 Object_Id : Directory.Version;
                 Desired   : Access_Class) return Boolean;

 DESCRIPTION

 Returns True if the specified user or job has the desired access to the
 specified object.

 The value True is also returned if an object that does not have an access
 list is referenced.

 This function returns False if an error is detected during the test or if
 the user or job does not have the desired access.


 PARAMETERS

 User_Name : String := "";

 Specifies the username whose access rights are to be checked. All of the
 groups
 to which the username is a member are used for the test. Context
 characters and wildcards can be used, provided they resolve to a single
 username. Use of the null string specifies the identity of the calling job.


 User_Id : Directory.Version;

 Specifies the directory version of the user identifier.


 Job : Machine.Job_Id;

 Specifies the directory version of the job identifier.


 Object_Id : Directory.Version;

 Specifies the directory version of the object for which access rights are
 to be checked.


 Object_Name : String;

 Specifies the name of the object for which access rights are to be checked.
 Context characters, wildcards, and attributes can be used, provided they
 resolve to a single object.


 Desired : Access_Class;

 Specifies one or more access rights to be checked for. Access rights are
 specified using one or more of the following characters, in upper- or
 lowercase: R (read), W (write), C (create), O (owner), or D (delete).


 return Boolean;

 Returns True if the specified user or job has the desired access to the
 specified object or if an object that does not have an access-control list
 is referenced. This function returns False if an error is detected during
 the test or if the job does not have the desired access.


 ERRORS

 The Access_Tools_Error exception is raised if an error occurs.

 Common errors include illegal values for the Desired parameter and
 references to objects that do not exist.


 EXAMPLES

 The following example shows a simple procedure that uses the Check
 function to determine whether a user has the desired access to a
 particular object:

   with Io, Access_List_Tools;
   procedure Check_Example
                (User         : String;
                 Which_Object : String;
                 What_Access  : String) is
   begin
       if Access_List_Tools.Check
             (User, Which_Object, What_Access) then
           Io.Put ("The user has the requested access.");
       else
           Io.Put
              ("The user does not have the requested access.");
       end if;
   end Check_Example;
   

 REFERENCES

 subtype Access_Class
 function Grants
 function Is_In_Group



 @node !Tools.Access_List_Tools.Check_Validity

 procedure Check_Validity
                (For_List :        Acl;
                 Status   : in out Simple_Status.Condition);

 DESCRIPTION

 Checks the validity of the specified access-control list (ACL).


 PARAMETERS

 For_List : Acl;

 Specifies the ACL whose validity is to be checked.


 Status : in out Simple_Status.Condition;

 Returns a condition indicating whether the procedure has executed
 correctly. If there is an error, this procedure returns a message
 indicating the type of error.


 ERRORS

 If an error occurs, this procedure returns the Status parameter containing
 a condition and a message indicating the type of error.


 EXAMPLES

 The following procedure takes as a parameter the name of an object whose
 ACL is to be checked for validity. If there is an error in the ACL, a
 display indicates the error. If there is no error, a display indicates
 that the ACL is valid.

   with Log, Io, Access_List_Tools, Simple_Status;
   procedure Check_Validity
                (Which_Objects_Access_List : String) is
       Status : Simple_Status.Condition;
   begin
       Access_List_Tools.Check_Validity
          (Access_List_Tools.Get (Which_Objects_Access_List),
           Status);
       if Simple_Status.Error (Status) then
           -- Display the error generated by the Simple_Status package.
           Log.Put_Condition (Status);
       else
           Io.Put_Line ("The access list is valid.");
       end if;
   end Check_Validity;
   

 REFERENCES

 subtype Acl
 function Is_Valid_Group
 function Normalize
 Programming Tools (PT), type Simple_Status.Condition



 @node !Tools.Access_List_Tools.Create

 Create : constant Character := 'C';

 DESCRIPTION

 Defines the Create access right, which applies only to worlds.

 Create access permits new objects to be created in a world. Create access
 also permits new versions of existing objects to be created in a world.
 Note that create access to a world applies to all directories within the
 world, although this access right does not extend into any subworlds.

 See "References," below, for other access rights.


 REFERENCES

 constant Delete
 constant Owner
 constant Read
 constant Write



 @node !Tools.Access_List_Tools.Delete

 Delete : constant Character := 'D';

 DESCRIPTION

 Defines the Delete access right, which applies only to worlds.

 Delete access permits a world to be deleted. Delete access is
 interchangeable with write access (defined by the constant Write).

 See "References," below, for other access rights.


 REFERENCES

 constant Create
 constant Owner
 constant Read
 constant Write



 @node !Tools.Access_List_Tools.Get

 function Get (For_Object : Name) return Acl;

 function Get (For_Object : Directory.Version) return Acl;

 DESCRIPTION

 Returns the access-control list (ACL) for the specified object.

 Objects that have ACLs are worlds, files, and Ada units.


 PARAMETERS

 For_Object : Name;

 Specifies the name of the object whose ACL is to be retrieved. Context
 characters, wildcards, and attributes can be used, provided they resolve
 to a single object.


 For_Object : Directory.Version;

 Specifies the directory version of the object whose ACL is to be retrieved.


 return Acl;

 Returns the ACL for the specified object.


 ERRORS

 The Access_Tools_Error exception is raised if an error occurs. If the user
 wants to determine which error has occurred, the procedural version of the
 function should be called. It returns a Status parameter indicating the
 error.


 EXAMPLES

 The following simple procedure copies an ACL from one object to another.
 It uses the Get function to retrieve the ACL that is to be copied
 (specified in the Object_To_Get_Acl_From parameter) and then uses the Set
 procedure to set the ACL (specified in the Object_To_Set_Acl_For
 parameter).

   with Log, Simple_Status, Access_List_Tools;
   procedure Copy_Acl (Object_To_Get_Acl_From : String;
                       Object_To_Set_Acl_For  : String) is
       Status : Simple_Status.Condition;
   begin
       Access_List_Tools.Set
          (Object_To_Set_Acl_For,
          (Access_List_Tools.Get (Object_To_Get_Acl_From)),
           Status);
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       end if;
   end Copy_Acl;
   

 REFERENCES

 exception Access_Tools_Error
 subtype Acl
 procedure Get
 procedure Set



 @node !Tools.Access_List_Tools.Get

 procedure Get
        (For_Object :        Name;
         List       :    out Bounded_String.Variable_String;
         Status     : in out Simple_Status.Condition);

 procedure Get
        (For_Object :        Directory.Version;
         List       :    out Bounded_String.Variable_String;
         Status     : in out Simple_Status.Condition);

 DESCRIPTION

 Gets the access-control list (ACL) for the specified object and returns it
 in the List parameter.


 PARAMETERS

 For_Object : Name;

 Specifies the name of the object whose access list is to be retrieved.
 Context characters, wildcards, and attributes can be used, provided they
 resolve to a single object.


 For_Object : Directory.Version;

 Specifies the directory version of the object whose ACL is to be retrieved.


 List : out Bounded_String.Variable_String;

 Returns the ACL for the specified object. The constraint for this parameter
 is the Max_Acl_Length constant. If the ACL returned does not fit in the
 List parameter, the resulting ACL is truncated and the Status parameter is
 set to indicate this error.


 Status : in out Simple_Status.Condition;

 Returns a condition indicating that the procedure has executed correctly.
 If there is an error, this procedure returns a condition and a message
 indicating the type of error.


 ERRORS

 If an error is encountered, a condition and a message indicating the type
 of error are returned in the Status parameter.


 EXAMPLES

 The following simple procedure uses the procedural form of the Get
 procedure to retrieve the ACL of a file. It then sets the ACL of a second
 file to the ACL that has been retrieved.

   with Log, Io, Simple_Status;
   with Bounded_String, Access_List_Tools;
   procedure Copy_Acl (Object_To_Get_Acl_From : String;
                       Object_To_Set_Acl_For  : String) is
       Status : Simple_Status.Condition;
       List   : Bounded_String.Variable_String
                   (Access_List_Tools.Max_Acl_Length);
   begin
       Access_List_Tools.Get
          (Object_To_Get_Acl_From, List, Status);
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       else
           Access_List_Tools.Set (Object_To_Set_Acl_For,
                                  Bounded_String.Image (List),
                                  Status);
           if Simple_Status.Error (Status) then
               Log.Put_Condition (Status);
           else
               Io.Put_Line
                  ("The access list has been set for " &
                   Object_To_Set_Acl_For);
           end if;
       end if;
   end Copy_Acl;
           

 REFERENCES

 function Get
 constant Max_Acl_Length
 procedure Set
 Programming Tools (PT), package Simple_Status



 @node !Tools.Access_List_Tools.Get_Default

 function Get_Default (For_World : Name) return Acl;

 DESCRIPTION

 Returns the default access-control list (ACL) associated with the specified
 world.

 A world's default ACL is used to initialize the ACLs of new Ada units and
 files created in the world.


 PARAMETERS

 For_World : Name;

 Specifies the world whose default ACL is to be retrieved. Context
 characters, wildcards, and attributes can be used, provided they resolve
 to a single object.


 return Acl;

 Returns the default ACL for the specified world.


 ERRORS

 The Access_Tools_Error exception is raised if an error occurs. If the user
 wants to determine which error occurred, the procedural form of the
 Get_Default function returns an error condition and a message in the
 Status parameter.


 EXAMPLES

 The following program shows the use of the Get_Default function to
 retrieve the default ACL for new objects created in a world. The default
 is then used to set the default ACL for new objects created in another
 world.

   with Log, Io, Simple_Status, Access_List_Tools;
   procedure Copy_Default_Example
                (World_To_Get_Acl_From : String;
                 World_To_Set_Acl_For  : String) is
       Status : Simple_Status.Condition;
   begin
       Access_List_Tools.Set_Default
          (World_To_Set_Acl_For,
          (Access_List_Tools.Get_Default (World_To_Get_Acl_From)),
           Status);
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       else
           Io.Put_Line ("The ACL has been set for world " &
                        World_To_Set_Acl_For);
       end if;
   end Copy_Default_Example;
           

 REFERENCES

 exception Access_Tools_Error
 subtype Acl
 procedure Get_Default
 constant Max_Acl_Length



 @node !Tools.Access_List_Tools.Get_Default

 procedure Get_Default
         (For_World :        Name;
          List      :    out Bounded_String.Variable_String;
          Status    : in out Simple_Status.Condition);

 DESCRIPTION

 Gets the default access-control list (ACL) associated with the specified
 world and returns the default ACL in the List parameter.

 A world's default ACL is used to initialize the ACLs of new Ada units and
 files created in the world.


 PARAMETERS

 For_World : Name;

 Specifies the world whose default ACL is to be retrieved. Context
 characters, wildcards, and attributes can be used, provided they resolve
 to a single object.


 List : out Bounded_String.Variable_String;

 Returns the default ACL for the specified world. The constraint for this
 parameter is the Max_Acl_Length constant. If the default ACL does not fit
 in the List parameter, the resulting ACL is truncated and the Status
 parameter is set to indicate this error.


 Status : in out Simple_Status.Condition;

 Returns a condition indicating that the procedure has executed correctly.
 If there is an error, the procedure returns a condition and a message
 indicating the type of error.


 ERRORS

 If an error is encountered, a condition and a message indicating the type
 of error are returned in the Status parameter.


 EXAMPLES

 This example shows how the procedural form of the Get_Default procedure
 can be used to retrieve the default ACL of new objects created within a
 world. The default ACL is then used to set the default ACL for new objects
 created in another world.

   with Log, Io, Simple_Status;
   with Access_List_Tools, Bounded_String;
   procedure Copy_Default_Acl
                (World_To_Get_Acl_From : String;
                 World_To_Set_Acl_For  : String) is
       Status : Simple_Status.Condition;
       List   : Bounded_String.Variable_String
                   (Access_List_Tools.Max_Acl_Length);
   begin
       Access_List_Tools.Get_Default
          (World_To_Get_Acl_From, List, Status);
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       else
           Access_List_Tools.Set_Default
              (World_To_Set_Acl_For,
               Bounded_String.Image (List),
               Status);
       end if;
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       else
           Io.Put_Line
              ("The default ACL for new objects is set for world" &
               World_To_Set_Acl_For);
       end if;
   end Copy_Default_Acl;
           

 REFERENCES

 subtype Acl
 function Get_Default
 Programming Tools (PT), package Simple_Status
 String Tools (ST), package Bounded_String



 @node !Tools.Access_List_Tools.Grants

 function Grants (For_List  : Acl;
                  Desired   : Access_Class;
                  User_Name : String := "") return Boolean;

 DESCRIPTION

 Returns a Boolean value indicating whether the specified access-control
 list grants the specified username the desired access rights. This function
 is useful for restricting jobs that normally have unlimited access, such
 as servers and other *SYSTEM jobs. For example, you can use this function
 to cause a job or program to operate on objects only if members of the
 group Network_Public are permitted the appropriate access to those
 objects.


 PARAMETERS

 For_List : Acl;

 Specifies the name of the access-control list to be checked for the
 specified username and desired access. Accepted values are of subtype
 Access_List.Acl (see package Access_List in this book).


 Desired : Access_Class;

 Specifies the access right desired for the username. Accepted access rights
 include Read, Write, Owner, Delete, and Create.


 User_Name : String := "";

 Specifies the username for which the access rights are to be checked. The
 name must be a literal string; wildcard characters and other naming
 expressions are not allowed. Only one username can be specified. The null
 string specifies the username or identity under which this function is
 called.


 return Boolean;

 Returns True if the specified user has the desired access according to the
 specified access-control list. This function returns False if the user does
 not have the desired access.


 ERRORS

 This function raises Access_Tools_Error if the value supplied to the
 For_List, Desired, or User_Name parameter is illegal.


 REFERENCES

 function Check
 function Is_In_Group



 @node !Tools.Access_List_Tools.Has_Operator_Capability

 function Has_Operator_Capability return Boolean;

 
 DESCRIPTION

 Returns True if the calling job has operator capability; otherwise, the
 function returns False.

 To have operator capability, the identity initiating the job must meet one
 of the following conditions:

 *  Be a member of group Operator

 *  Have write access to !Machine.Operator_Capability

 *  Be a member of group Privileged and have privileges enabled
                                                                           

 EXAMPLES

 The following simple procedure determines whether the identity initiating
 the job has operator capability:

   with Io, Access_List_Tools;
   procedure Has_Operator_Capability_Example is
   begin
       if Access_List_Tools.Has_Operator_Capability then
           Io.Put ("This job has operator capability.");
       else
           Io.Put
              ("This job does not have operator capability.");
       end if;
   end Has_Operator_Capability_Example;
           

 REFERENCES

 System Management Utilities (SMU), package Operator



 @node !Tools.Access_List_Tools.Is_In_Group

 function Is_In_Group (User_Name  : String;
                       Group_Name : String) return Boolean;

 DESCRIPTION

 Returns a Boolean value indicating whether the specified username is a
 member of the specified access-control group.

 This function returns True if the specified user is a member of the
 specified access-control group.

 This function returns False if an error is detected during the test or if
 the user is not a member of the specified access-control group.


 PARAMETERS

 User_Name : String;

 Specifies the username whose membership in the access-control group is to
 be checked. The name must be a literal string; wildcard characters and
 other naming expressions are not allowed. Only one username can be
 specified.


 Group_Name : String;

 Specifies the name of the access-control group to be checked for the
 username. The name must be a literal string; wildcard characters and other
 naming expressions are not allowed. Only one group name can be specified.


 return Boolean;

 Returns True if the specified user is a member of the specified
 access-control group. This function returns False if an error is detected
 during the test or if the user is not a member of the group.


 REFERENCES

 function Check
 function Grants
 function Is_Valid_Group



 @node !Tools.Access_List_Tools.Is_Valid_Group

 function Is_Valid_Group (Name : String) return Boolean;

 DESCRIPTION

 Returns a Boolean value indicating whether the specified name is a valid
 access-control group.


 PARAMETERS

 Name : String;

 Specifies the name of an access-control group to be checked for validity.
 The name must be a literal string; wildcard characters and other naming
 expressions are not allowed. Only one name can be specified.


 return Boolean;

 Returns True if the specified name is a valid access-control group. This
 function returns False if an error is detected during the test or if the
 user is not a member of the group.


 ERRORS

 This function returns False if an error is detected during the test.


 REFERENCES

 procedure Check_Validity
 function Is_In_Group
 function Normalize



 @node !Tools.Access_List_Tools.Max_Acl_Length

 Max_Acl_Length : constant := 512;

 DESCRIPTION

 Specifies the maximum number of characters in an access-control list (ACL).

 This constant is used as a constraint for the List parameter in the Get
 and Get_Default procedures.



 @node !Tools.Access_List_Tools.Name

 subtype Name is String;

 DESCRIPTION

 Defines the subtype for names of objects used by procedures in this
 package.

 This subtype allows the use of wildcards, special names, context
 characters, set notation, indirect files, attributes, and substitution
 characters. See the Parameter-Value Conventions tabbed section in the
 Reference Summary (RS) book for more information about naming.



 @node !Tools.Access_List_Tools.Normalize

 function Normalize (Initial_Acl : Acl) return Acl;

 DESCRIPTION

 Returns a revised access-control list (ACL).

 This function scans the specified ACL and removes entries for groups that
 do not currently exist.


 PARAMETERS

 Initial_Acl : Acl;

 Specifies the ACL to be normalized.


 return Acl;

 Returns a revised ACL.


 ERRORS

 The Access_Tools_Error exception is raised if an error occurs.


 EXAMPLES

 This example illustrates the use of the Normalize function in conjunction
 with other procedures and functions in this package. Assume that you have
 deleted several of the groups that had access to My_Object. The following
 procedure removes the deleted groups from the ACL of My_Object. (To use
 this procedure, you must be the owner of the world containing My_Object.)

   with Log, Io, Access_List_Tools, Simple_Status;
   procedure Normalize_Example (My_Object : String) is
       Status : Simple_Status.Condition;
   begin
       Access_List_Tools.Set
          (My_Object,
           Access_List_Tools.Normalize
              (Access_List_Tools.Get (My_Object)),
           Status);
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       else
           Io.Put_Line ("The access list for ");
           Io.Put_Line (My_Object);
           Io.Put_Line (" has been normalized.");
       end if;
   end Normalize_Example;
           

 REFERENCES

 subtype Acl



 @node !Tools.Access_List_Tools.Owner

 Owner : constant Character := 'O';

 DESCRIPTION

 Defines the Owner access right, which applies only to worlds.

 Owner access to a world permits:

 *  Changing the access-control list (ACL) of the world itself or of
    objects in the world

 *  Changing the links in the world

 *  Changing the compiler switch-file associations in the world

 *  Freezing and unfreezing objects in the world

 Note that more than one user can have owner access to a given world. Owner
 access to a world applies to all directories within the world, although
 this access right does not extend into any subworlds.

 See "References," below, for other access rights.


 REFERENCES

 constant Create
 constant Delete
 constant Read
 constant Write



 @node !Tools.Access_List_Tools.Read

 Read : constant Character := 'R';

 DESCRIPTION

 Defines the Read access right, which applies to worlds, Ada units, and
 files.

 For files and Ada units, read access permits:

 *  Viewing the object (for example, using the !Commands.Common.Definition
    command)

 *  Opening the object for In_File mode

 *  Manipulating the object using certain Rational debugger commands

 *  Executing Ada units

 For worlds, read access permits:

 *  Viewing the world's contents

 *  Resolving the names of objects in the world

 Read access to a world applies to all directories within the world,
 although this access right does not extend into any subworlds.

 See "References," below, for other access rights.


 ERRORS

 In I/O operations, read access is required for In_File mode. In other
 words, if a user wants to open a file to read it, the user must have read
 access to the file. The !Io.Io_Exceptions.Use_Error exception is raised for
 access failures from Io packages.


 REFERENCES

 constant Create
 constant Delete
 constant Owner
 constant Write



 @node !Tools.Access_List_Tools.Remove

 procedure Remove
               (Group       :     String;
                Initial_Acl :     Bounded_String.Variable_String;
                New_Acl     : out Bounded_String.Variable_String;
                Group_Found : out Boolean);

 DESCRIPTION

 Removes the entry for the specified group from the specified access-control
 list.


 PARAMETERS

 Group : String;

 Specifies the name of the access-control group to be removed. The name must
 be a literal string; wildcard characters and other naming expressions are
 not allowed. Only one group name can be specified.


 Initial_Acl : Bounded_String.Variable_String;

 Specifies the access-control list from which the group is to be removed.


 New_Acl : out Bounded_String.Variable_String;

 Returns the new access-control list, after the group has been removed.


 Group_Found : out Boolean;

 Returns a Boolean value indicating whether the group specified was found in
 the initial ACL. This parameter returns True if the group was found; it
 returns False if the group was not found.


 REFERENCES

 procedure Normalize



 @node !Tools.Access_List_Tools.Set

 procedure Set (For_Object :        Name;
                To_List    :        Acl;
                Status     : in out Simple_Status.Condition);

 procedure Set (For_Object :        Directory.Version;
                To_List    :        Acl;
                Status     : in out Simple_Status.Condition);

 procedure Set (For_Object :        Directory.Version;
                To_List    :        Acl;
                Status     : in out Simple_Status.Condition;
                Action_Id  :        Action.Id);

 DESCRIPTION

 Sets the access-control list (ACL) for the specified object.

 Setting an object's ACL requires owner access to the nearest world
 enclosing the object.

 Note that setting a world's ACL does not require owner access to the world
 itself, provided that you have owner access to its parent world. This
 allows you to change the ACL of a world when no one has owner access to
 it.


 PARAMETERS

 For_Object : Name;

 Specifies the object whose ACL is to be set. Context characters, wildcards,
 and attributes can be used, provided they resolve to a single object.


 For_Object : Directory.Version;

 Specifies the directory version of the object whose ACL is to be set.


 To_List : Acl;

 Sets the new ACL for the object. An ACL consists of multiple entries, each
 of the form group_name=>access_rights. Multiple entries must be separated
 by commas.


 Status : in out Simple_Status.Condition;

 Returns a condition indicating that the procedure has executed correctly.
 If there is an error, this procedure returns a condition and a message
 indicating the type of error.


 Action_Id : Action.Id;

 Specifies an action ID. For information about action IDs, see your Rational
 technical representative.


 ERRORS

 If an error is encountered, a condition and a message indicating the type
 of error are returned in the Status parameter.


 EXAMPLES

 The following simple procedure uses the Set procedure to copy the ACL from
 one object to another. It uses the Get function to retrieve the ACL of the
 object whose ACL is to be copied.

   with Log, Simple_Status, Access_List_Tools;
   procedure Set_Example (Object_To_Get_Acl_From : String;
                          Object_To_Set_Acl_For  : String) is
       Status : Simple_Status.Condition;
   begin
       Access_List_Tools.Set
          (Object_To_Set_Acl_For,
           (Access_List_Tools.Get (Object_To_Get_Acl_From),
            Status));
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       end if;
   end Set_Example;
           

 REFERENCES

 procedure Amend
 procedure Get
 Programming Tools (PT), package Simple_Status



 @node !Tools.Access_List_Tools.Set_Default

 procedure Set_Default
               (For_World :        Name;
                To_List   :        Acl;
                Status    : in out Simple_Status.Condition);

 procedure Set_Default (For_World :        Name;
                        To_List   :        Acl;
                        Status    : in out Simple_Status.Condition;
                        Action_Id :        Action.Id);

 DESCRIPTION

 Sets the default access-control list (ACL) for the specified world or
 worlds.

 Setting a world's ACL requires owner access to that world. A world's
 default ACL is used to initialize the ACLs of new Ada units and files
 created in the world.

 This procedure does not modify the ACLs of already existing objects whose
 ACLs were set by the previous default ACL.


 PARAMETERS

 For_World : Name;

 Specifies the world whose default ACL is to be set. Context characters,
 wildcards, and attributes can be used, provided they resolve to a single
 object.


 To_List : Acl;

 Sets the new default ACL for the specified world. An ACL is a list of
 entries of the form group_name=>access_rights. Multiple entries must be
 separated by commas.


 Status : in out Simple_Status.Condition;

 Returns a condition indicating that the procedure has executed correctly.
 If there is an error, this procedure returns a condition and a message
 indicating the type of error.


 Action_Id : Action.Id;

 Specifies an action ID. For information about action IDs, see your Rational
 technical representative.


 ERRORS

 If an error is encountered, a condition and a message indicating the type
 of error are returned in the Status parameter.


 EXAMPLES

 This example shows how the Set_Default procedure can be used in
 conjunction with the Get_Default procedure. The following procedure
 retrieves the default ACL from one world and then uses that default ACL to
 set the default ACL of another world.

   with Log, Io, Simple_Status;
   with Access_List_Tools, Bounded_String;
   procedure Get_Default_Procedure_Example
                (World_To_Get_Acl_From : String;
                 World_To_Set_Acl_For  : String) is
       Status : Simple_Status.Condition;
       List   : Bounded_String.Variable_String
                   (Access_List_Tools.Max_Acl_Length);
   begin
       Access_List_Tools.Get_Default
          (World_To_Get_Acl_From, List, Status);
       if Simple_Status.Error (Status) then
           Log.Put_Condition (Status);
       else
           Access_List_Tools.Set_Default
              (World_To_Get_Acl_From,
               World_To_Set_Acl_For, Status);
           if Simple_Status.Error (Status) then
               Log.Put_Condition (Status);
           else
               Io.Put
                  ("The default ACL for new objects is set " &
                   "for world " & World_To_Set_Acl_For);
           end if;
       end if;
   end Get_Default_Procedure_Example;
           

 REFERENCES

 procedure Get_Default



 @node !Tools.Access_List_Tools.Write

 Write : constant Character := 'W';

 DESCRIPTION

 Defines the Write access right, which applies to Ada units and files.

 Write access permits operations that change the value of an object, such
 as editing, deleting, promoting, and demoting. Write access is
 interchangeable with delete access (defined by the constant Delete).

 Note that editing a file or an Ada unit requires create access to the
 enclosing world in addition to write access to the object itself. Whereas
 write access is required to open the object for editing, create access to
 the enclosing world is required to create new versions of the object.

 See "References," below, for other access rights.


 ERRORS

 In I/O operations, write access is required for Inout_File and Out_File
 modes. In other words, if a user wants to open a file for Read/Write or
 Write mode, the user must have write access to the file. The
 !Io.Io_Exceptions.Use_Error exception is raised for access failures from
 Io packages.


 REFERENCES

 constant Create
 constant Delete
 constant Owner
 constant Read



 @node !Commands.Archive

 With the procedures in package Archive, you can save and restore one or
 more objects on one or more R1000s. The Archive procedures can handle
 objects such as worlds, directories, Ada units, text files, data files,
 switch files, activities, subsystems, and subsystem views. The Archive
 procedures also handle user binary files, transferring the bits unaltered
 and uninterpreted.

 The Archive facilities differ from system backups. Whereas system backups
 save and restore the entire Environment, the commands in package Archive
 can be used selectively to save and restore individual objects, as well as
 to move objects from one R1000 to another.

 You can use the Save and Restore procedures to transfer objects between
 R1000s using tape. As a convenient, one-step alternative, you can use the
 Copy procedure to transfer objects between R1000s using Rational
 Networking--TCP/IP. The Copy procedure is also useful for copying objects
 to different locations on the same R1000.


 RESOURCES IN PACKAGE ARCHIVE

 Package Archive contains the following procedures:

 *  Copy: Copies one or more objects from one location to another, either
    on the same R1000 or between two R1000s that are connected through
    Rational Networking--TCP/IP. This procedure also permits changing
    access-control lists (ACLs) and many other options.

 *  List: Lists the names of the objects on a tape or library generated by
    the Save procedure.

 *  Restore: Reads some or all objects from a tape (or library) generated
    by the Save procedure and rebuilds the original hierarchical structure
    from which they were saved. For Ada units, the Restore procedure
    optionally promotes the units to the states they were in when they were
    saved. This procedure also permits changing the ACLs of restored
    objects.

 *  Save: Writes one or more objects onto a tape (or library), preserving
    hierarchical structure. The Save procedure records each object's ACL,
    its last update time, and its compilation state, if any.

 *  Server: Is used by system initialization software to start the archive
    server. This procedure should never be entered by users.

 *  Status: Prints information about the status of an archive job.


 OVERVIEW OF SAVE, RESTORE, AND COPY COMMANDS

 The Save, Restore, and Copy commands use parameters to control the various
 aspects of archiving. Of particular interest is the Options parameter,
 through which you can specify the desired properties of the objects to be
 archived, the compilation state to which archived Ada units are
 restored, the ACLs to assign restored objects, and special handling for
 loaded main programs and subsystems. Read the following subsections
 ("Save," "Restore," and "Copy") for brief descriptions of how the most
 frequently used parameters and options interact. Then look at the "Exam-
 ples" section at the end of this package introduction, which shows these
 parameters and options in use.


 Save Command

 The Save procedure allows you to save a set of objects that can later be
 restored with the Restore procedure. The Save procedure copies the objects
 into an Environment library or onto a tape, as specified through the
 Device parameter.

 When copying onto tape, you can:

 *  Specify the Format and Label options to control how the tape is written

 *  Specify the Starting_At option to delay the starting time of the save
    operation

 *  Specify the Unload option to determine whether to unload the tape after
    it is rewound (leaving the tape online is useful for performing
    subsequent list operations)


 What Objects Are Saved

 With the Save procedure, you can archive worlds, directories, Ada units,
 text files, data files, switch files, activities, subsystems, subsystem
 views, and user binary files. When you archive Ada units, files, and worlds,
 the following information is saved with each: its ACL, last update time,
 retention count, unit state (for Ada units), and whether the object is
 frozen.

 The Objects parameter specifies the objects to be saved. By default, all of
 the specified objects are saved. In addition:

 *  Libraries and Ada units are saved recursively (that is, all their
    subobjects are saved as well).

 *  Links and switch-file associations are saved along with worlds.

 *  Compatibility databases are saved along with subsystems, views, or
    units in subsystems.

 You can use the Options parameter to filter the objects to be saved, as
 shown in Table 1.

          Table 1   Options for Specifying the Objects to Be Saved
                ------------------------------------------ 
               |       |                                  |
               |Option |           Description            |
                ------------------------------------------ 
               |       |                                  |
               |After  |Saves only objects that were      |
               |       |changed after a specified time.   |
                ------------------------------------------ 
               |       |                                  |
               |Nonrecu|Saves only the objects that are   |
               |rsive  |explicitly named in the Objects   |
               |       |parameter, without saving all     |
               |       |their subobjects as well.         |
                ------------------------------------------ 



 To verify that the Objects and Options parameters combine to specify the
 correct objects, you can also specify the Effort_Only option. Executing
 the Save procedure with the Effort_Only option displays a list of the
 specified objects without actually saving them.

 Whether objects are saved on tape or in a library, the Save procedure
 writes all objects into a single file called Data. A file called Index is
 also created, which describes the name of each object in the Data file,
 the size of the object, and its unit state if it is an Ada unit. During
 the restore operation, information from the Index file is used to rebuild
 objects from the Data file and place them in the appropriate states.

 If the amount of data you are saving to tape is very large (for example,
 if it might exceed the capacity of a single tape), you can use the Format
 option in the Save command to cause the Data and Index files to be written
 onto separate volume sets. A subsequent restore operation (with the same
 Format option) can then consult the Index file directly, without having
 to scan over the entire Data file first.


 Other Options

 Options exist for certain special-purpose save operations. For example,
 you can specify the Links option to save (and later restore) only the
 links for the specified world. Saving and restoring with the Links option
 provides a more powerful alternative to using the Links.Copy command,
 which copies links only among worlds on the same R1000. In contrast,
 archiving with the Links option allows you to copy links between R1000s.

 Other options, namely Cdb and Ignore_Cdb, exist for saving and restoring
 subsystems and their contents. See "Archive and Multiple-Host
 Development," page nn.


 Restore Command

 The Restore procedure allows you to restore a set of objects that were
 saved by the Save procedure. The Device parameter specifies whether to
 restore from tape or from a library. Through the Options parameter, you
 can specify the Format, Label, and Unload options to control restoration
 from a tape.


 What Objects Are Restored

 The Objects parameter specifies the objects to be restored. By default, the
 entire set of saved objects is restored as follows:

 *  The exact contents of text and binary files are restored.

 *  Ada units other than loaded main programs are restored in the source
    state; loaded main programs are restored in the coded state along with
    their code segments.

 *  Libraries and Ada units are restored recursively (that is, all their
    subobjects are restored as well).

 *  Objects that were frozen when saved are frozen when they are restored.

 *  Worlds are restored with their links and switch-file associations.
    However, if the units to which links refer do not exist, errors occur
    and the links are not created. Similarly, if the associated switch files
    do not exist, errors occur and the associations are not created.

 *  When a user world is restored, a corresponding user is created if the
    restorer has operator capability. The password is the same as the saved
    user's password.

 *  Entries in an activity file are restored only if the load and spec views
    they reference exist.

 *  Compatibility databases are restored along with subsystems, views, or
    individual units within subsystems.

 You can restore a subset of the saved objects by specifying a restricted
 naming expression or an indirect file for the Objects parameter (see the
 reference entry for the Restore procedure or the Parameter-Value
 Conventions tabbed section in the Reference Summary). When a naming
 expression is specified, the restore operation restores only the objects
 whose names are matched.

 You can use the Options parameter to further filter the objects named by
 the Objects parameter. The Nonrecursive option for the Restore command
 is the same as that for the Save command; the remaining options filter
 objects based on whether the restore operation would overwrite existing
 objects of the same name (see Table 2).

          Table 2   Options for Specifying Objects to Be Restored
              --------------------------------------------- 
             |         |                                   |
             | Option  |            Description            |
              --------------------------------------------- 
             |         |                                   |
             |Nonrecurs|Restores only the objects that are |
             |ive      |explicitly named in the Objects    |
             |         |parameter, without restoring all   |
             |         |their subobjects as well.          |
              --------------------------------------------- 
             |         |                                   |
             |Changed_ |Restores only new objects and      |
             |Objects  |updated objects (see below in this |
             |         |table).                            |
              --------------------------------------------- 
             |         |                                   |
             |Different|Restores only objects that will    |
             |_Objects |overwrite existing objects and that|
             |         |have a different update time       |
             |         |(whether earlier or later) than the|
             |         |objects they will overwrite.       |
              --------------------------------------------- 
             |         |                                   |
             |Existing_|Restores only objects that will    |
             |Objects  |overwrite existing objects.        |
              --------------------------------------------- 
             |         |                                   |
             |New_     |Restores only objects that will not|
             |Objects  |overwrite existing objects.        |
              --------------------------------------------- 
             |         |                                   |
             |Updated_ |Restores only objects that will    |
             |Objects  |overwrite existing objects and that|
             |         |were modified more recently than th|
             |         |objects they will overwrite.       |
              --------------------------------------------- 




 Names of Restored Objects

 By default, objects are restored under the names with which they were
 saved. Two parameters, Use_Prefix and For_Prefix, allow you to change the
 names of the restored objects. With these parameters, you can replace a
 portion of the original object names with the specified string of name
 components. You can use these parameters to change not only the simple
 names of the restored objects but also the qualifying name components,
 thereby relocating the objects in the Environment library hierarchy.
 (You can test the effect of these parameters with the Effort_Only
 option, which lists the names of restored objects without actually restor-
 ing them.) See "Specifying Destination Names" for more information about
 the Use_Prefix and For_Prefix parameters.

 Regardless of the names under which objects are restored, the restore
 operation by default creates any missing hierarchical library structure
 that is required to restore the objects under the desired names. The
 restore operation can create any number of nested worlds and directories;
 subsystems are created only if they are needed to restore entire views.
 However, the Require_Parents option can be specified to prevent
 restoration unless the required context already exists.


 Overwriting Objects

 By default, a restore operation attempts to overwrite existing objects
 that have the same name. The Replace option permits existing objects to be
 overwritten even if they are frozen, compiled, and/or controlled and
 checked in. To this end, the Replace option automatically unfreezes,
 demotes, and checks out the necessary objects for the duration of the
 operation; if the Remake option is specified, the objects are repromoted at
 the end of the operation. Overwriting can be prevented by specifying the
 New_Objects option.


 State of Restored Ada Units

 By default, Ada units (other than loaded main programs) are restored in
 the source state. Such units can be compiled during the restore operation,
 as specified by the options shown in Table 3.

     Table 3   Options for Controlling Compilation of Restored Objects
              ---------------------------------------------- 
             |     |                                        |
             |Optio|              Description               |
             |  n  |                                        |
              ---------------------------------------------- 
             |     |                                        |
             |Goal_|Promotes restored units to the specified|
             |State|state.                                  |
              ---------------------------------------------- 
             |     |                                        |
             |Promo|Promotes restored units to the state    |
             |te   |they were in when saved.                |
              ---------------------------------------------- 
             |     |                                        |
             |Remak|Promotes restored units to their        |
             |e    |original states along with any          |
             |     |dependents that were demoted by the     |
             |     |Replace option.                         |
              ---------------------------------------------- 



 Loaded main programs, each consisting of an Ada-unit specification and a
 set of code segments, are always restored in the coded state. However, if
 a restored loaded main program overwrites an existing one, the
 specification of the existing program is demoted, along with any units that
 depend on it. You can prevent such demotion by specifying the Code option,
 which causes only the code segments to be restored, provided that the
 specification is unchanged.


 ACLs of Restored Objects

 The default assignment of access-control lists (ACLs) depends on where
 objects are restored:

 *  Objects restored into views always inherit their ACLs from the context
    into which they are restored, according to the standard ACL inheritance
    rules. This preserves the ACLs assigned by CMVC access control.

 *  Whole views and subsystems are restored with the ACLs they had when
    saved; furthermore, they are restored with their CMVC access-class
    assignments.

 *  Objects restored outside subsystems keep the ACLs with which they were
    saved, unless they overwrite existing objects. In this case, the
    restored objects are given the ACLs of the objects they overwrite.

    For objects restored outside subsystems, you can override the default
    behavior with one or more of the options shown in Table 4.

 Note that if an ACL entry references a group that does not exist on the
 destination R1000, that ACL entry is omitted.

           Table 4   Options for Setting ACLs of Restored Objects
               -------------------------------------------- 
              |         |                                  |
              | Option  |           Description            |
               -------------------------------------------- 
              |         |                                  |
              |Become_  |Modifies the ACLs of all restored |
              |Owner    |objects so that the restorer is   |
              |         |granted owner (O) access to them. |
               -------------------------------------------- 
              |         |                                  |
              |Default_ |Specifies the default ACL for all |
              |Acl      |restored worlds.                  |
               -------------------------------------------- 
              |         |                                  |
              |Object_  |Specifies the ACL for all restored|
              |Acl      |files and Ada units.              |
               -------------------------------------------- 
              |         |                                  |
              |World_Acl|Specifies the ACL for all restored|
              |         |worlds.                           |
               -------------------------------------------- 




 State of Restored Subsystems

 By default, the Restore command assumes that subsystems are normally
 restored in the context of multiple-host development. That is, by default,
 restoring a subsystem creates a secondary subsystem, whose purpose is to
 represent the original subsystem on other R1000 hosts. Secondary
 subsystems do not support ongoing primary development activities,
 including the compilation of new declarations.

 If a restored subsystem is to be used for primary development (and not as
 part of a multiple-host scenario), you must override the default by
 specifying the Primary option in the Options parameter. This is especially
 important when restoring primary subsystems from archives that are used
 as backups.

 This is only one of a number of issues to be considered when restoring
 subsystems. See "Archive and Multiple-Host Development," page nn, for a
 discussion of these issues.


 Other Options

 Like the Save command, the Restore command has a Links option; this option
 causes just the links for the specified worlds to be restored. (This option
 does not need to be specified during the restore operation if it was
 specified during the save operation.) Saving and restoring with the Links
 option provides a more powerful alternative to using the Links.Copy
 command, which copies links among worlds on the same R1000. In contrast,
 archiving with the Links option allows you to copy links between R1000s.

 Other options, namely Cdb and Ignore_Cdb, exist for saving and restoring
 subsystems and their contents. See "Archive and Multiple-Host
 Development," page nn.


 Copy Command

 The Copy command is equivalent to a save operation followed by a restore
 operation, and it uses Rational Networking--TCP/IP as the medium instead
 of tapes. The Copy command is a convenient, one-step alternative to using
 Save and Restore, and it can be used to transfer objects between R1000s
 or to copy objects to different locations on the same R1000. Because
 objects are transferred directly from source to destination, no
 intermediate Data and Index files are created.

 The Copy command has the same parameters as the Restore command, but with-
 out the Device parameter. Furthermore, the Copy command accepts all of the
 save and restore options for filtering objects, controlling compilation,
 setting ACLs, and

 handling links, loaded main programs, and subsystems. In addition, the
 Copy command accepts options for resetting the identity used for access
 control when the command accesses objects on remote R1000s. For obvious
 reasons, the Copy command does not accept the options associated with
 tapes.

 Note that Rational Networking--TCP/IP, and, as a result, the Copy command,
 requires that the names and TCP/IP addresses of the source and destination
 machines be in the !Machine.Transport_Name_Map file of both machines.

 The Copy command is frequently used to copy subsystems. See "Archive and
 Multiple-Host Development," page nn, for a discussion of the issues
 surrounding copying subsystems.


 Response Parameter

 The Copy, Restore, and Save commands each have a Response parameter that
 specifies how the command should respond to errors, what kind of messages
 it should put in its output log, the format of the output log, and the
 activity it should use. The default for the Response parameter in many
 commands is "<PROFILE>". This value causes the command to use the current
 job response profile if you have set one; otherwise, the command will use
 the session response profile (set in your session switches). If you have no
 session profile, the command will use the Environmentwide default profile.

 Other values for the Response parameter are listed in the Parameter-Value
 Conventions tabbed section in the Reference Summary (RS). You can use
 these values to change the way Archive commands respond to errors, put out
 messages, and so on. For example, if you want an Archive command to raise
 an exception when an error is encountered, you can specify the Response
 parameter as follows:

   Response => "Raise_Error, <PROFILE>"

 In fact, for Archive commands, this is the only safe way to request
 exception-raising, because it allows the commands to continue until they
 terminate gracefully. In contrast, the values "<Raise_Exception>"
 (abbreviated "<Raise>") and "Propagate, <PROFILE>" should not be used,
 because they cause Archive commands to leave copy and restore operations
 in an indeterminate state.

 For more information about the Response parameter, see the Parameter-Value
 Conventions tabbed section in the Reference Summary (RS) or the Key
 Concepts in the Session and Job Management (SJM) book. For more complete
 information on profiles, see SJM, package Profile.


 Summary of Archive Options

 Table 5 summarizes the options that are available for the Copy, Restore,
 and Save commands. For a full description of each option, see the
 reference entry for the relevant commands. For general information about
 specifying options (for example, how to specify multiple options), see the
 Parameter-Value Conventions tabbed section in the Reference Summary (RS).

                   Table 5    Summary of Archive Options
                       ---------------------------- 
                      |          |     |     |     |
                      |  Option  |Copy |Resto|Save |
                      |          |     | re  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |After     |  X  |     |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Become_   |  X  |  X  |     |
                      |Owner     |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Cdb       |  X  |  X  |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Changed_  |  X  |  X  |     |
                      |Objects   |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Code      |  X  |  X  |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Default_  |  X  |  X  |     |
                      |Acl       |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Delta1    |     |     |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Different_|  X  |  X  |     |
                      |Objects   |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Effort_   |  X  |  X  |  X  |
                      |Only      |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Enable_   |  X  |     |     |
                      |Privileges|     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Existing_ |  X  |  X  |     |
                      |Objects   |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Format    |     |  X  |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Goal_State|  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Ignore_Cdb|  X  |  X  |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Label     |     |  X  |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Links     |  X  |  X  |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |New_      |  X  |  X  |     |
                      |Objects   |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Nonrecursi|  X  |  X  |  X  |
                      |ve        |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Object_Acl|  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Password  |  X  |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Prefix    |     |     |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Primary   |  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Promote   |  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Remake    |  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Replace   |  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Require_  |  X  |  X  |     |
                      |Parents   |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Revert_Cdb|  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Starting_ |     |     |  X  |
                      |At        |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Trailing_ |  X  |  X  |     |
                      |Blanks    |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Uncontrol |  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Unload    |     |  X  |  X  |
                       ---------------------------- 
                      |          |     |     |     |
                      |Updated_  |  X  |  X  |     |
                      |Objects   |     |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |User      |  X  |     |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Verbose   |  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |Volume    |  X  |  X  |     |
                       ---------------------------- 
                      |          |     |     |     |
                      |World_Acl |  X  |  X  |     |
                       ---------------------------- 




 SPECIFYING SOURCE NAMES

 The Save, Restore, and Copy commands all have an Objects parameter through
 which you specify the names of the source objects (the objects you want to
 save, restore, or copy).

 All three commands allow you to specify any number of source objects for a
 single archive operation:

 *  If you want to archive a single object, you specify the pathname of
    that object.

 *  If you want to archive a library and its contents (including
    sublibraries and their contents), you specify the pathname of that
    library (archive commands are recursive by default).

 *  If you want to archive any other set of objects, you specify a naming
    expression that matches that set of objects.

 The naming expressions that are accepted by the Objects parameter differ
 slightly depending on the command:

 *  In the Save and Copy commands, the value of the Objects parameter is
    resolved against the Environment library hierarchy--that is, it
    references one or more actual Environment objects. Therefore, the
    Objects parameter in these commands accepts any valid Environment
    naming expression.

 *  In the Restore command, the value of the Objects parameter is resolved
    against a list of pathnames that was stored by the Save command--that
    is, it matches a pattern of strings. Therefore, the Objects parameter
    in this command accepts a restricted subset of Environment naming
    expressions.

 This difference reflects the fact that the Restore command must always
 follow a Save command, whereas the Copy command is used by itself.

 The following subsections summarize the naming expressions that are
 accepted by the Objects parameter in the Save, Copy, and Restore commands.
 For complete details about Environment naming conventions, see the
 Parameter-Value Conventions tabbed section in the Reference Summary
 (RS).


 Specifying Source Objects for Save and Copy Operations

 The Objects parameter in the Save and Copy commands accepts any naming ex-
 pression that references one or more objects in the Environment library
 hierarchy. These naming expressions can include:

 *  Context characters

 *  Wildcard characters

 *  Set notation

 *  Indirect files

 *  Attributes

 If you use set notation or indirect files, it is recommended that you
 separate the individual names with semicolons so that the command will
 quit if unresolvable names are reported. (When commas are used, the
 operation copies what it can and ignores unresolvable names.)

 The accepted characters for wildcards and set notation are shown in Table
 6.

              Table 6    Wildcard Characters and Set Notation
              ---------------------------------------------- 
             |      |                                       |
             |Charac|              Description              |
             | ter  |                                       |
              ---------------------------------------------- 
             |      |                                       |
             |  #   |Matches a single character. T####      |
             |      |matches Tools.                         |
              ---------------------------------------------- 
             |      |                                       |
             |  @   |Matches zero or more characters.       |
             |      |!U@.@.Tools matches                    |
             |      |!Users.Anderson.Tools.                 |
              ---------------------------------------------- 
             |      |                                       |
             |  ?   |Matches zero or more nonworld name     |
             |      |components. !Users.Anderson? matches   |
             |      |!Users.Anderson and all objects except |
             |      |worlds in !Users.Anderson.             |
              ---------------------------------------------- 
             |      |                                       |
             |  ??  |Matches zero or more name components,  |
             |      |including worlds and their contents.   |
             |      |!Users?? matches !Users, the home      |
             |      |worlds for all users, and the contents |
             |      |of those worlds.                       |
              ---------------------------------------------- 
             |      |                                       |
             |  []  |Encloses a set of names.               |
             |      |[!Users.Anderson?;!Users.Miyata?]      |
             |      |matches everything in the home worlds  |
             |      |for Anderson and Miyata.               |
              ---------------------------------------------- 
             |      |                                       |
             |  ~   |Indicates that something should not be |
             |      |matched. [@,~Tools] matches everything |
             |      |in a library except Tools.             |
              ---------------------------------------------- 




 Example: Saving an Ada Unit

 The following command saves both the spec and the body of the Sort
 procedure:

   Archive.Save (Objects => "!Users.Anderson.Statistics.Tools.Sort");


 Example: Saving a Library and Its Contents

 Because archive commands are recursive by default, the following command
 saves the library !Users.Anderson and all of its contents:

   Archive.Save (Objects => "!Users.Anderson");

 In contrast, the following command saves !Users.Anderson and all objects
 in it except worlds:

   Archive.Save (Objects => "!Users.Anderson?",
                 Options => "Nonrecursive");

 Note that you must specify the Nonrecursive option because ? matches zero
 or more name components. When ? matches zero name components, the Objects
 parameter matches the library name !Users.Anderson. If Save operates
 recursively, all of this library's contents are saved, including worlds;
 if Save operates nonrecursively, only the explicitly specified objects
 (namely, the library and its nonworld contents) are saved.


 Example: Saving the Library's Contents without the Library

 The following command saves the contents of !Users.Anderson, but not the
 library itself:

   Archive.Save (Objects => "!Users.Anderson.@");

 Note that if the Nonrecursive option were specified, this command would
 save only the immediate contents of Anderson's home world, without saving
 the contents of any libraries or directories in it.


 Examples: Saving an Arbitrary Set of Objects

 The following command saves the home worlds (and recursively, their
 contents) of all users whose usernames begin with A, B, or C:

   Archive.Save (Objects => "!Users.[A@,B@,C@]");

 The following command saves just the Login procedures from every user's
 home world:

   Archive.Save (Objects => "!Users.@.Login");

 The following command saves several project libraries and their contents:

   Archive.Save (Objects => "[!Project_1,!Project_2,!Local.Tools]");


 Example: Saving Objects through an Indirect File

 Sometimes it is time-consuming to formulate precisely the right naming
 expression to match the set of objects you want. If you have an expression
 that is close, you can:

 1. Expand the expression using the Library.Resolve command.

 2. Copy the resulting list of names into a file (called, for example,
    Objects_To_Save).

 3. Edit the list to add, delete, or modify pathnames as necessary.

 4. Specify the file as an indirect file to the Save command:

      Archive.Save (Objects => "_Objects_To_Save");

 It is recommended that you use fully qualified pathnames in indirect files.


 Specifying Source Objects for Restore

 The Objects parameter of the Restore command accepts a naming expression
 that is resolved against the names of saved objects. By specifying the
 appropriate Objects value, you can restore all of the saved objects or a
 subset of the saved objects. Because this value is resolved against a
 list of pathname strings and not against the library hierarchy, only the
 following restricted subset of naming expressions is accepted:

 *  Set notation

 *  Indirect files

 *  Three of the four wildcards--namely, *, @, and ?, but not ??. Because
    resolution is done against pathname strings, the ? character matches
    any name component without distinguishing between world and nonworld
    components.

 If you use set notation or indirect files, it is recommended that you
 separate the individual names with semicolons so that the command will
 quit if unresolvable names are reported. (When commas are used, the
 operation copies what it can and ignores unresolvable names.)

 Note that naming conventions such as attributes are meaningless here
 because they reference information that cannot be obtained from a list of
 pathnames.

 Restricted naming expressions are summarized in Table 7.

                  Table 7    Restricted Naming Expressions
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  #   |Matches a single character other than a |
            |      |period. T#### matches Tools.            |
             ----------------------------------------------- 
            |      |                                        |
            |  @   |Matches zero or more characters not     |
            |      |containing a period. !U@.@.Tools matches|
            |      |!Users.Anderson.Tools.                  |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches zero or more name components.   |
            |      |!Users.Anderson? matches !Users.Anderson|
            |      |and everything in it.                   |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Encloses a set of names.                |
            |      |[!Users.Anderson?,!Users.Miyata?]       |
            |      |matches everything in the home worlds of|
            |      |Anderson and Miyata.                    |
             ----------------------------------------------- 
            |      |                                        |
            |  ~   |Indicates that something should not be  |
            |      |matched. [@,~Tools] matches everything  |
            |      |in a library except Tools.              |
             ----------------------------------------------- 




 Example: Restoring an Entire Set of Saved Objects

 To restore the entire set of saved objects from a given device, you use
 the default Objects parameter value (?), which matches all the name
 components of all the saved pathnames:

   Archive.Restore (Objects => "?");

 You can use this expression without knowing the names of the saved
 objects. Note that ? matches the name components of worlds as well as
 nonworlds when used in the Restore command.


 Example: Restoring a Library and Its Contents

 Assume that you have saved the home worlds for all users whose usernames
 begin with A, B, or C, and that you want to restore just the home world
 (and its contents) for user Anderson. The following command accomplishes
 this:

   Archive.Restore (Objects => "!Users.Anderson");


 Example: Restoring an Arbitrary Subset

 Assume that each saved home world contains a status file whose name is of
 the form Username_Status. The following command restores just the status
 files of the users whose names start with A and B:

   Archive.Restore (Objects => "!Users.[A@,B@].@_Status");


 Example: Restoring through an Indirect File

 Assume that you want to restore a subset of the objects you saved through
 an indirect file. You can copy the file (say, into a file called
 Objects_To_Restore), edit it, and then specify the edited copy as an
 indirect file:

   Archive.Restore (Objects => "_Objects_To_Restore");

 It is recommended that you use fully qualified pathnames in indirect files.


 SPECIFYING DESTINATION NAMES

 The Restore and Copy commands use a combination of three
 parameters--namely, Objects, Use_Prefix, and For_Prefix--to specify the
 names of the destination objects (the objects you want to create as a
 result of the restore or copy). Because an object's name reflects its
 location in the Environment library hierarchy, the destination name
 specified by these parameters determines the location of the copied/re-
 stored object.

 You can specify various combinations of strings for the Objects,
 Use_Prefix, and For_Prefix parameters to:

 *  Copy or restore objects under their original names/locations

 *  Copy or restore objects under different names/locations

 Note that you can copy objects under their original names/locations only
 if you are copying them onto another R1000 (see "Transferring Data between
 R1000s").

 The following subsections describe how these parameters interact and how
 you can use them to copy or restore one or more objects under their
 original names or under new names.

 In addition to the examples below, there are further examples at the end
 of this package introduction and at the end of the reference entries for
 the Copy, Restore, and Save commands.


 Copying or Restoring Objects under Their Original Names

 To restore an object under its original name, you use the default value
 for the Use_Prefix and For_Prefix parameters. The default value for these
 parameters is the asterisk character (*).

 For example, the following command restores
 !Users.Anderson.Statistics.Tools.Sort under the same name:

   Archive.Restore
            (Objects    => "!Users.Anderson.Statistics.Tools.Sort",
             Use_Prefix => "*",
             For_Prefix => "*");

 When copying, you can use the default Use_Prefix value only if the Objects
 parameter specifies objects from another R1000 (see "Transferring Data
 between R1000s"). The following command copies the library !Project_1 and
 its contents from an R1000 called M2, copying them onto the current R1000
 under their original names:

   Archive.Copy (Objects    => "!!M2!Project_1",
                 Use_Prefix => "*",
                 For_Prefix => "*");


 Copying or Restoring Objects under Different Names

 To copy or restore an object under a different name, you need to
 understand how the Copy and Restore commands construct new destination
 names. Basically, these commands allow you to substitute a new string (the
 Use_Prefix) for an existing string (the For_Prefix) in the original object
 name (thus, "use this prefix for that prefix"). The substituted strings are
 prefixes in that they represent sets of consecutive name components
 starting with the leftmost component.


 Example: Restoring an Object in a New Location

 Assume that you have saved the procedure
 !Users.Anderson.Statistics.Tools.Sort and now you want to restore it into
 user Miyata's Tools directory. The following command creates the
 destination object !Users.Miyata.Tools.Sort:

   Archive.Restore
            (Objects    => "!Users.Anderson.Statistics.Tools.Sort",
             Use_Prefix => "!Users.Miyata",
             For_Prefix => "!Users.Anderson.Statistics");

 To construct the destination name, this command:

 1. Starts with the Objects name (!Users.Anderson.Statistics.Tools.Sort)

 2. Removes the portion matched by the For_Prefix
    (!Users.Anderson.Statistics)

 3. Inserts the string specified by the Use_Prefix (!Users.Miyata) in its
    place

 Note that if !Users.Miyata did not already contain a library called Tools,
 this command would create such a library so that Sort could be created in
 it.


 Example: Restoring under a New Simple Name

 You can specify a destination name that includes a new simple name by
 using the default value of the For_Prefix parameter--namely, the asterisk
 character (*). This character causes the For_Prefix to match the entire
 Objects name, including the simple name. When the entire Objects name is
 matched, the Use_Prefix value becomes the entire destination name of the
 copied or restored value.

 For example, the following command restores procedure Sort as
 !Users.Miyata.Tools.Anderson_Sort:

   Archive.Restore
            (Objects    => "!Users.Anderson.Statistics.Tools.Sort",
             Use_Prefix => "!Users.Miyata.Tools.Anderson_Sort",
             For_Prefix => "*");

 Thus, in this case, the Use_Prefix parameter specifies all of the
 destination name, as determined by the For_Prefix parameter.


 Example: Copying into Another Library

 Assume that you want to copy a document from Anderson's home library into
 Miyata's home library. If you enter the Copy command from !Users.Anderson,
 you can use the context character $ in the For_Prefix value to specify that
 the pathname of the current library is the prefix to be replaced. Thus,
 the following command, entered from !Users.Anderson, creates the
 destination object !Users.Miyata.Sort_Document:

   Archive.Copy (Objects    => "Sort_Document",
                 Use_Prefix => "!Users.Miyata",
                 For_Prefix => "$");


 Using Copy or Restore to Reorganize Objects

 By specifying the appropriate naming expressions for the For_Prefix and
 Use_Prefix parameters, you can:

 *  Restore or copy a set of objects from one library into another

 *  Restore or copy objects from many libraries into a single library

 *  Restore or copy objects from many libraries into a parallel set of
    different libraries


 Example: Copying a Set of Objects into Another Library

 You can copy a set of objects from one library into another by replacing a
 prefix that is common to all of these objects with another prefix. That is,
 the For_Prefix specifies a single common prefix that is replaced by the value
 of Use_Prefix.

 For example, the following command copies all objects except Notes from
 Anderson's Statistics library into Miyata's New_Projects library:

   Archive.Copy
            (Objects    => "!Users.Anderson.Statistics.[@,~Notes]",
             Use_Prefix => "!Users.Miyata.New_Project",
             For_Prefix => "!Users.Anderson.Statistics");


 Example: Copying from Many Libraries into One Library

 Besides specifying a single prefix, the For_Prefix value can be a naming
 expression that expands to a set of prefixes.

 This naming expression is resolved against the list of source pathnames
 that results from expanding the Objects parameter. Because it matches
 strings instead of resolving against the library hierarchy, the
 For_Prefix (like the Objects parameter) accepts only the wildcard and
 set-notation characters described in Table 7 above.

 When the For_Prefix specifies multiple prefixes, each prefix is compared to
 the first source name specified by the Objects parameter. When a prefix is
 matched in the source name, the Use_Prefix value is substituted to create
 the new name, and the next source name is considered.


 Example: Using Set Notation

 Assume you have two directories (!Users.Lee.Tools.Test1 and
 !Users.Phillips.Test2) that contain test data, and that you want to copy
 these directories into a common world, !Project_Name.Test_Results. The
 following command accomplishes this:

   Archive.Copy
        (Objects    => "!Users.[Lee.Tools.Test1; Phillips.Test2]",
         Use_Prefix => "!Project_Name.Test_Results",
         For_Prefix => "!Users.[Lee.Tools,Phillips]");

 When you use set notation in the For_Prefix parameter:

 *  You must use the comma (not the semicolon) to separate the individual
    names.

 *  You must include a period to delimit name components, context
    characters, or wildcards that precede or follow the set.

 *  If you use fully qualified names (as in this example), you must put at
    least the ! character outside the brackets. (If you start the For_Prefix
    value with a bracket, the command automatically assumes you are using
    relative pathnames.)


 Example: Using Wildcards and Substitution Characters

 The For_Prefix value may contain wildcards (#, @, or ?) that match portions
 of the Objects parameter. If a For_Prefix wildcard matches a string that is
 to be preserved in the destination name, the Use_Prefix value must contain
 a corresponding instance of the @ substitution character. Substitution
 characters in the Use_Prefix value are mapped from right to left onto the
 For_Prefix value. The Environment then expands the Use_Prefix value by
 replacing each substitution character with the string that is matched by
 the corresponding wildcard in the For_Prefix. If the For_Prefix parameter
 contains wildcards, both the For_Prefix and the Use_Prefix value must
 account for the entire object name, not just a prefix.

 For example, assume again that you want to copy Test1 and Test2 from
 !Users.Lee.Tools and !Users.Phillips, respectively, and consolidate them
 in the world !Project_Name.Test_Results. The following command
 accomplishes this:

   Archive.Copy
        (Objects    => "!Users.[Lee.Tools.Test1; Phillips.Test2]",
         Use_Prefix => "!Project_Name.Test_Results.@",
         For_Prefix => "?.@");

 To construct the destination names, this command expands the Objects
 parameter to two source pathnames: !Users.Lee.Tools.Test1 and
 !Users.Phillips.Test2.

 For the first of these pathnames, the @ wildcard character in the For_Prefix
 value expands to "Test1" and the ? wildcard character expands to the
 remaining name components ("!Users.Lee.Tools"). Thus, the full For_Prefix
 matches the entire source pathname.

 In constructing the destination name for the first object, the Use_Prefix
 replaces the @ substitution character with the expanded contents of the
 rightmost For_Prefix wildcard ("Test1"). Thus, the full Use_Prefix becomes
 "!Project_Name.Test_Results.Test1".

 This Use_Prefix string replaces the portion of the source pathname that is
 matched by the For_Prefix string (here, the entire pathname). Thus, Test1
 is copied into !Project_Name.Test_Results.Test1.

 In the same manner, !Users.Phillips.Test2 is copied into
 !Project_Name.Test_Results.Test2.


 TRANSFERRING DATA BETWEEN R1000S

 With the Copy command, you can copy objects to or from other R1000s,
 either preserving their original names or giving them new names.

 With the Save and Restore commands, you can save objects from the current
 R1000 onto a remote device and you can restore objects onto the current
 R1000 from a remote device.

 Note that Rational Networking--TCP/IP, and, as a result, the Copy command,
 requires that the names and TCP/IP addresses of the source and destination
 machines be in the !Machine.Transport_Name_Map file of both machines.


 Copying Objects onto Another R1000

 You can copy objects onto another R1000 on the same network by prepending
 the name of the destination R1000 to the Use_Prefix value. An R1000 name
 has the form !!Name, where Name denotes the R1000's machine name.

 For example, in the following command, the Use_Prefix parameter causes the
 command to copy the library !Project_1 from the current R1000 onto an
 R1000 called M2, creating a library called !!M2!Project_1:

   Archive.Copy (Objects    => "!Project_1",
                 Use_Prefix => "!!M2",
                 For_Prefix => "*");

 Note that, to preserve the object's original name, you omit the asterisk
 character in the Use_Prefix value when that value contains a machine name.


 Distributing Objects onto Multiple R1000s

 You can distribute objects onto multiple R1000s by specifying multiple
 destination R1000 names enclosed in brackets. For example, in the
 following command, the Use_Prefix parameter causes the command to
 distribute the library !Playground (calling it !Workspace) onto each of
 three R1000s:

   Archive.Copy (Objects    => "!Playground",
                 Use_Prefix => "[!!M1,!!M2,!!M3]!Workspace"
                 For_Prefix => "*");

 Another way to specify multiple R1000s is to create a file containing the
 destination R1000 names (one per line) and then specify the file using
 indirect-file notation. For example, assume a file called Targets exists
 on the current R1000 and that Targets contains the names !!M1, !!M2, and
 !!M3 on separate lines. Then the following command is equivalent to the
 command in the previous example:

   Archive.Copy (Objects    => "!Playground",
                 Use_Prefix => "_Targets!Workspace"
                 For_Prefix => "*");


 Copying Objects from Another R1000

 You can copy objects from another R1000 on the same network by prepending
 the name of the source R1000 to the Objects value.

 For example, the following command copies the library !Project_1 from an
 R1000 called M2 onto the current R1000:

   Archive.Copy (Objects    => "!!M2!Project_1",
                 Use_Prefix => "*",
                 For_Prefix => "*");


 Copying Objects between Two Remote R1000s

 You can copy objects from one remote R1000 onto another remote R1000 by
 prepending the source and destination R1000s to the Objects and
 Use_Prefix parameters, respectively.

 For example, assume that you are logged into an R1000 called M1. The
 following command (entered on M1) copies the library !Project_1 from M2
 onto M3:

   Archive.Copy (Objects    => "!!M2!Project_1",
                 Use_Prefix => "!!M3",
                 For_Prefix => "*");


 Saving onto a Remote Device

 You can save objects onto a tape drive or library on a different R1000 by
 prepending the name of the remote R1000 to the value of the Device
 parameter of the Save command.

 For example, the following command saves the library !Project_1 onto a
 tape mounted on the machine !!M2:

   Archive.Save (Objects => "!Project_1",
                 Options => "R1000",
                 Device  => "!!M2!MACHINE.DEVICES.TAPE_0");

 In contrast to the Objects parameter in the Copy command, the Objects
 parameter in the Save command can specify only objects that reside on the
 current R1000. To save objects that reside on another R1000, you must
 enter the Save command from that machine.


 Restoring from a Remote Device

 You can restore objects from a tape drive or library on a different R1000
 by prepending the name of the remote R1000 to the value of the Device
 parameter of the Restore command.

 For example, the following command restores the library !Project_1 from a
 tape mounted on the machine !!M2:

   Archive.Restore (Objects    => "!Project_1",
                    Use_Prefix => "*",
                    For_Prefix => "*",
                    Options    => "R1000",
                    Device     => "!!M2!MACHINE.DEVICES.TAPE_0");

 In contrast to the Objects parameter in the Copy command, the Objects
 parameter in the Restore command can specify only objects that reside on
 the current R1000. To restore objects onto an R1000 other than the current
 one, you must enter the Restore command from that machine.


 ARCHIVE AND ACCESS REQUIREMENTS

 The Copy, Save, and Restore commands are subject to access control as
 follows:

 *  The Save command must have sufficient access to read the objects to be
    saved.

 *  The Restore command must have sufficient access to create restored
    objects in the specified location and to overwrite existing objects if
    necessary.

 *  The Copy command must have sufficient access to read the objects that
    are to be copied, to create the destination objects in the specified
    location, and to overwrite existing objects if necessary.

 Depending on the location of the archived objects, Archive commands are
 subject either to basic access control (as defined by package Access_List)
 or to CMVC access control (as defined by package Cmvc_Access_Control). The
 following subsections discuss how access is determined for Archive
 commands and list the access rights or access-class assignments that are
 required.


 Archive Identities

 An Environment command's access to objects is determined by the group to
 which the command's identity belongs:

 *  A Save or Restore command has a single identity, which is the username
    that entered the command.

 *  A Copy command has two identities, one for the save portion and one for
    the restore portion of the command. The identity for a given portion of
    the command depends on where it takes place:

    -  When the Copy command saves or restores objects on the current R1000
       (the R1000 on which the command is entered), the identity for the
       relevant portion of the command is the username that entered the
       command.

    -  When the Copy command saves or restores objects on a remote R1000
       (via Rational Networking--TCP/IP), the identity for the relevant
       portion of the command is the identity of the RPC server that
       performs the operation on the remote R1000. (An RPC server that
       performs a portion of the Copy command on a remote machine is called
       an archive server.)

    Note that the Copy command's two identities are the same if both
    portions of the operation take place on the same R1000.

 Regardless of whether Archive command identities are established by
 usernames or archive servers, these identities must belong to groups that
 have sufficient access to perform the necessary operations. The specific
 access required by each kind of archive identity is summarized in "Archive
 and Basic Access Control" and "Archive and CMVC Access Control," below.

 If an Archive command's identity (or identities) is insufficient to access
 the desired objects, you can:

 *  Override access control by enabling privileges, if your username
    belongs to group Privileged (see "Overriding Access Requirements,"
    below)

 *  Change the identity of an archive server so that it has sufficient
    access, if you are attempting to copy objects to or from a remote
    machine (see "Changing Remote Copy Identities," below)


 Archive and Basic Access Control

 When applied to objects outside subsystems, Archive commands are subject
 to basic access control (see package Access_List). That is, the groups
 containing the relevant identities must appear in the access-control lists
 (ACLs) of the affected objects, where they must be assigned the
 appropriate access rights. In particular:

 *  For the Save command and the save portion of the Copy command, the
    identity of the job or archive server must belong to a group that has
    read (R) access to the specified objects.

 *  For the Restore command and the restore portion of the Copy command,
    the identity of the job or archive server must belong to a group that
    has:

    -  RCO access to the world into which objects will be restored/copied

    -  RW default access to this world

    -  RW access to any existing objects that will be overwritten or
       recompiled by the operation


 Archive and CMVC Access Control

 When applied to subsystems, views, or objects in views, Archive commands
 are subject to CMVC access control (see PM, package Cmvc_Access_Control).
 The groups containing the job or archive server identities must belong to
 the appropriate access classes (for example, Reader, Developer, and
 Owner) for the affected objects.

 The Save command and the save portion of the Copy command require Reader
 access to 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 an entire 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 specified subsystem and to each of its
    views.

 The Restore command and the restore portion of the Copy command require
 more powerful access (such as Developer or Owner) to views, subsystems,
 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 identity of the job or
    archive server must belong to a group that has:

    -  RCO access to the world into which the subsystem will be created,
       restored, or copied

    -  RW default access to this world

 Several of the options available to the Restore and Copy commands are also
 subject to particular access classes and execution rights:

 *  When the Replace, Uncontrol, Goal, Promote, or Remake option is
    specified, the identity of the job or archive server must belong to a
    group that has Developer access to both the subsystem and the view
    enclosing the affected objects. Options such as Replace and
    Uncontrol, which invoke CMVC operations, are subject to execution
    rights, as well.

 *  When the Primary or Revert_Cdb option is specified, the identity of the
    job or archive server must belong to a group that has Owner access to
    the subsystem, as well as any additional CDB capability that is in use
    (see the introduction to package Cmvc_Access_Control in the Project
    Management (PM) book).

 Note that several options have no effect when archiving into subsystems.
 These are the options that allow you to change ACLs during an archive
 operation--namely, Object_Acl, Default_Acl, World_Acl, and Become_Owner.


 Overriding Access Requirements

 Users whose usernames belong to the Privileged group can override both
 basic access control and CMVC access control by enabling privileges for
 Archive commands. Overriding access requirements is useful if you are
 restoring or copying objects into several libraries to which you or the
 relevant archive server may or may not have sufficient access. To enable
 privileges for the Restore command,
 you must execute the Operator.Enable_Privileges command as part of the
 same job. To enable privileges for the Copy command and its archive
 servers, you must specify the Enable_Privileges option through the Copy
 command's Options parameter.


 Changing Archive Server Identities

 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 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.)

 Depending on how much security you require and how often you need to
 access remote machines using the Copy command, you can set a new identity
 for remote archive servers by either:

 *  Specifying the User and Password options in the Copy command

 *  Invoking a remote-passwords file


 User and Password Options

 You can provide a new identity for a remote archive server by specifying
 the User and Password options in the Options parameter of the Archive.Copy
 command. Using these options is a security risk, because the password you
 specify is visible as clear text both in the command window and in the
 Copy command's message log.

 For example, assume that user Anderson is copying a view from Machine_1 to
 Machine_2 and that he is entering the Copy command from Machine_2. Because
 Network_Public does not have the correct access to the view he is copying,
 he wants the archive server on Machine_1 to use his username as its
 identity.

 Security is not an issue at his site, so user Anderson enters the
 following command on Machine_2, specifying the username and password with
 which he logs onto Machine_1:

   Archive.Copy
       (Objects    => "!!Machine_1!Projects.Interface.Rev1_0_1",
        Use_Prefix => "*",
        For_Prefix => "*",
        Options    => "User=Anderson,Password=Not_A_Secret",
        Response   => "<PROFILE>");

 Note that Anderson's password is now visible on the screen in both the
 command window and the output window containing the message log.


 Remote-Passwords File

 A more secure way to provide a new identity for a remote archive server is
 to invoke a remote-passwords file. A remote-passwords file is a general
 mechanism for storing the usernames and passwords that networking commands
 are to use when accessing specific remote R1000s. Using a remote-passwords
 file provides better security because:

 *  You can use access control to limit access to the file

 *  You can store encrypted passwords in the file

 *  You can request that commands prompt you for the password when they
    consult the file

 For details about creating, adding entries to, and encrypting passwords in
 a remote-passwords file, see the introduction to package
 !Commands.Remote_Passwords in the Session and Job Management (SJM) book.

 For example, assume that user Anderson is copying a view from Machine_1 to
 Machine_2 and that he is entering the Copy command from Machine_2.
 Because Network_Public does not have the correct access to the view he
 is copying, he wants the archive server on Machine_1 to use his username
 as its identity. Security is important at this site, so he wants the
 command to prompt him for the password.

 To achieve this, Anderson:

 1. Creates a text file called My_Passwords that contains (at least) this
    entry:

      Machine_1   anderson   <PROMPT>

 2. Uses the !Commands.Remote_Passwords.Set_Default command to set this file
    to be the default remote-passwords file. As a result, the filename
    becomes the value of the Profile.Remote_Passwords session switch, making
    it part of Anderson's session response profile.

 3. Enters the Copy command:

      Archive.Copy
          (Objects    => "!!Machine_1!Projects.Interface.Rev1_0_1",
           Use_Prefix => "*",
           For_Prefix => "*");

    The command automatically consults the default remote-passwords file and
    prompts him for the password in an I/O window.

 4. Enters the required password at the prompt, which does not echo the
    characters to the screen.

 As an alternative to setting a default remote-passwords file, Anderson can
 invoke a remote-passwords file by naming it as an option within the
 Response parameter:

   Archive.Copy
       (Objects    => "!!Machine_1!Projects.Interface.Rev1_0_1",
        Use_Prefix => "*",
        For_Prefix => "*",
        Options    => "",
        Response   => "Remote_Passwords=>My_Passwords,<Profile>");

 The file's simple name can be used when the command is entered from the
 library that contains it.

 Note that if a remote-passwords file contains multiple entries for the same
 R1000, you can select the entry for a particular username by specifying
 the User option in the Options parameter of the Copy command.


 ARCHIVE AND MULTIPLE-HOST DEVELOPMENT

 Commands from package Archive play an important role in multiple-host
 development. When multiple hosts are used, the primary development of
 each subsystem in an application is conducted on a different host R1000.
 Commands from package Archive are used to create copies of the application
 on each host and to distribute releases and propagate changes among the
 hosts. The following subsections focus on the role of Archive commands;
 for a more complete discussion of multiple-host development, see
 "Developing Applications Using Multiple Hosts" in the Project Management
 (PM) book.

 Note in the following subsections that "copying" refers to using the
 Archive.Copy command or to using the Archive.Save and Archive.Restore
 commands as a pair. Archive.Copy can be used to copy objects between
 R1000s that are on the same network or to copy objects to another location
 on the same R1000. Archive.Save and Archive.Restore can be used to copy
 objects on tape.


 Primary and Secondary Subsystems

 When an application is developed on multiple-host R1000s, a complete copy
 of the application resides on each host. Consequently, every subsystem in
 the application has as many copies as there are hosts. Only one copy of
 each subsystem can support ongoing primary development; this copy is the
 primary subsystem. The remaining copies of that subsystem are created as
 secondary subsystems; these exist for the purpose of compiling, executing,
 and testing the other primaries in the application.

 Setting up multiple-host development thus involves creating primary
 subsystems and their associated secondaries:

 *  Use the Cmvc.Initial command to create each primary subsystem directly
    on the desired host.

 *  Use commands from package Archive to copy each primary subsystem to the
    other hosts, thereby creating the associated secondary subsystems. (By
    default, when subsystems are copied using Archive commands, secondary
    subsystems are created.)

 Note that you can use the Primary option to override default behavior;
 this option causes subsystems to be copied as primaries rather than as
 secondaries. The Primary option enables you to restore primary
 subsystems from archives used as backups. This option can also be used
 when rehosting the primary development of a subsystem (see "Moving a
 Primary Subsystem to Another Host," page nn).


 Updating Secondary Subsystems

 As development proceeds in a primary subsystem, its associated secondaries
 periodically need to be brought up to date. Two general strategies exist
 for propagating changes from a primary to a secondary; both strategies
 involve commands from package Archive. The first strategy is to use Archive
 commands to copy whole views (typically new releases or code views) from
 the primary to the secondary. This strategy is especially appropriate
 for providing updated implementations to secondary subsystems that
 contain spec and load views.

 The second strategy is to update views in the secondary subsystem directly--for
 example, by copying new or changed units from the primary, making
 incremental changes to units in the secondary, and/or deleting unwanted
 units from the secondary. This strategy is especially appropriate for
 updating views such as spec views or working combined views, either of
 which can be imported into other subsystems. Updating individual units in
 an imported view minimizes recompilation, limiting it to the updated
 units and their dependents. In contrast, if changes to spec or combined
 views were propagated by copying whole new spec views
 or releases, every view that needed to import the copied views would
 require recompilation.

 Under this second strategy, Archive commands are used to copy new or
 changed units into the secondary subsystem and optionally to prepare the
 secondary subsystem so that incremental changes can be made there. Note,
 however, that Archive commands do not perform the remaining type of update
 operation--namely, deleting unwanted objects from the secondary.
 Therefore, more comprehensive tools may be written against package
 Archive and other Environment packages so that views can be updated
 programmatically.

 Regardless of whether you use Archive commands to copy views, to copy
 individual units, or to prepare views for incremental operations, it is
 useful for you to understand how Archive commands handle objects that are
 compiled and/or controlled in the primary subsystem. The following
 subsections discuss various compilation-related and CMVC-related issues.


 Copying Compiled Objects

 Propagating changes to a secondary subsystem often involves copying
 objects that have been compiled (promoted to the coded state) in the
 primary subsystem. When compiled objects are copied using Archive
 commands, the copies are transferred and then left in the source state,
 unless an option such as Promote or Remake is specified. These options
 cause the copied units to be recompiled in the secondary subsystem.

 The Promote option should be specified when you copy entire released views
 (as in the first strategy described above). This option causes the copied
 units to be promoted to their original states. For example, assume you
 want to copy a compiled release called Rev1_2_0 from a primary subsystem
 on Machine_1 into an associated secondary subsystem (with the same name)
 on Machine_2. The following command, executed from the context of the
 primary subsystem, accomplishes this:

   Archive.Copy (Objects    => "Rev1_2_0",
                 Use_Prefix => "!!Machine_2",
                 For_Prefix => "*",
                 Options    => "Promote");

 The Remake option should be specified when you copy individual units (as in
 the second strategy described above). This option promotes copied units to
 their original states and additionally repromotes any other units that
 were demoted by the operation. Such units are demoted when you use the
 Replace option to allow copied units to overwrite compiled units that have
 dependents. The Remake option not only promotes the copied units but
 also repromotes the dependents of the overwritten units.

 For example, assume you are developing an application in combined views
 and you want to copy individual compiled units from a working combined
 view in a primary subsystem into a working combined view in an associated
 secondary. As before, the primary and secondary subsystems have the same
 name and are on Machine_1 and Machine_2, respectively. Assume further that
 you want to copy only new and updated units, and that the updated units
 will overwrite existing compiled units in the secondary. The following
 command, executed from the context of the primary subsystem, accomplishes
 this (note that the Units subdirectory is specified so that objects in
 the State subdirectory will not be copied; see "Implications of
 Overwriting Views," page nn):

   Archive.Copy (Objects    => "Rev2_Working.Units",
                 Use_Prefix => "!!Machine_2",
                 For_Prefix => "*",
                 Options    => "Changed_Objects,Replace,Remake");

 Regardless of whether entire views or individual units are copied,
 recompilatio in the secondary is made possible because Archive commands 
 also copy current compilation information from the primary. That is, whenever
 Archive commands copy units (or views containing units), they
 automatically copy the primary subsystem's compatibility database (CDB)
 as well. This allows the copied objects to be recompiled in the secondary
 using compilation information that was generated in the primary.

 More specifically, the CDB in a primary subsystem assigns a unique label to
 every declaration in every unit specification in the subsystem. This
 information is used for a variety of purposes, including maintaining
 compilation consistency between spec and load views in a subsystem. The
 information in a primary subsystem's CDB is updated whenever a unit
 specification containing a new declaration is compiled in any of the
 subsystem's views. In contrast, a secondary subsystem's CDB cannot be
 updated through compilation within the subsystem. Rather, a secondary's
 CDB can be updated only by overwriting it with a copy of the associated

 primary's CDB. Thus, by copying the primary's CDB, Archive commands
 automatically update the secondary's CDB and enable copied units
 containing new declarations to be compiled there.


 Preparing to Propagate Incremental Changes

 Whereas a secondary subsystem's CDB is updated automatically when you copy
 whole views or units, you must perform such an update as a separate,
 explicit operation before you can propagate incrementally compiled
 changes. One way of updating a secondary subsystem's CDB is to use Archive
 commands with the Cdb option to copy the primary subsystem's CDB without
 actually copying any units.

 For example, assume you want to copy the CDB from a primary subsystem
 called Mail_Utilities on Machine_1 to a secondary subsystem with the same
 name on Machine_2. Then the following command, executed from the project
 library containing the primary subsystem, accomplishes this:

   Archive.Copy (Objects    => "Mail_Utilities",
                 Use_Prefix => "!!Machine_2",
                 For_Prefix => "*",
                 Options    => "Cdb");

 After the CDB has been copied, you can make the desired incremental
 changes in the secondary subsystem.

 An equivalent alternative to copying with the Cdb option is to use the
 Cmvc_Maintenance.Update_Cdb command. Note, however, that this command
 requires that the R1000s containing the subsystems reside on the same
 network. If the R1000s are not on the same network, you must use the
 Archive.Save and Archive.Restore commands with the Cdb option to copy the
 CDB using tape.


 Other CDB-Related Options

 Besides the Cdb option, Archive commands accept two other options that
 provide further control over the CDB during copy operations:

 *  The Ignore_Cdb option causes the specified views or units to be copied
    without copying the CDB. Ignoring the CDB saves time when source code
    is copied between unrelated subsystems (subsystems that are not
    associated as primaries and secondaries). Copying units between
    unrelated subsystems typically is done when units from one subsystem
    are to serve as templates for developing units in the other subsystem.

    The Ignore_Cdb option serves only to optimize the copy operation so
    that no time is spent saving or transferring the CDB from the source
    subsystem. Note that no harm is done if this option is omitted,
    however, because a copied CDB can never actually overwrite the CDB from
    an unrelated subsystem.

 *  The Revert_Cdb option allows you to copy an older version of a CDB over
    a newer version. This option overrides the default behavior of archive
    operations (by default, a CDB can be overwritten only by a more
    recently updated CDB). You should use this option only under
    supervision of Rational support personnel; if used incorrectly, this
    option can result in loss of compatibility among the spec and load
    views in a subsystem.


 Copying Controlled Objects

 Under most development methodologies, objects in a primary subsystem are
 put under CMVC in order to coordinate development activity and to record
 change

 history in the subsystem. In contrast, objects in a secondary subsystem
 are generally not put under CMVC, because secondaries typically have no
 development activity to coordinate and no independent change history to
 record. In accordance with such methodologies, Archive commands do not
 transfer any of the CMVC information that is associated with the objects
 they copy. In particular, when Archive commands copy controlled objects
 (or views containing controlled objects), the copies are left uncontrolled
 in the secondary and no change history is copied with them.

 However, some projects adopt development methodologies under which objects
 in secondary subsystems are put under CMVC. Under such methodologies, the
 steps for propagating changes become slightly more complex. In particular:

 *  New objects that are copied into a secondary subsystem must be made
    controlled as a separate step after the copy operation (if they are
    to be made controlled at all--note that objects in spec views
    typically are not controlled, even in the primary).

 *  Existing objects that are controlled in the secondary subsystem must be
    checked out before they can be overwritten by copied objects. You can
    either:

    -  Check out the necessary objects as a separate operation before the
       copy is performed, or

    -  Specify the Replace option in the relevant Archive command to check
       out the necessary objects for the duration of the operation. Note
       that the Replace option will fail to check out objects that are
       already checked out in other views; these objects will not be
       overwritten.

 *  Controlled objects in the secondary subsystem must be checked out
    before they can be incrementally updated.


 Copying the CMVC Database

 Under some development methodologies, it is feasible to propagate CMVC
 information from a primary subsystem to a secondary by explicitly
 copying the primary's CMVC database. A subsystem's CMVC database records
 which objects are controlled in the subsystem and maintains change history
 for each of the controlled objects. Primary and secondary subsystems
 alike have CMVC databases, although the CMVC database in a secondary is
 empty if no objects are made controlled there. Copying the CMVC database
 from a primary to a secondary makes the primary's change history available
 in the secondary, as well as making copied objects controlled in the
 secondary if the originals were controlled in the primary.

 In practice, however, the advantages of copying the CMVC database to a
 secondary can be realized only in limited situations. In the first place,
 it is often inappropriate for change history to be available in a
 secondary subsystem. For example, the developers of a primary subsystem
 may propagate changes in the form of code-only releases in order to permit
 execution without making program source code available. To copy the CMVC
 database would defeat this purpose, because textual images of the program
 source code can be browsed through the CMVC editor.

 In the second place, copying the CMVC database to a secondary produces
 valid change history only when the secondary is an exact copy of the
 primary--that is, when changes are propagated by using frozen releases
 and/or updating individual uncontrolled objects (as in spec views). When a
 secondary is updated any other way--that is, by checking out controlled
 objects, overwriting or incrementally modifying them, and then checking
 them in again--the change history that is

 recorded in the secondary can potentially diverge from that of the
 primary. Any divergent change history is lost whenever you copy the
 primary's CMVC database, because the copied CMVC database overwrites that
 of the secondary.

 If you do want to copy a primary's CMVC database into a secondary along
 with released views, you must specify it explicitly as follows:

   Objects => [State.Cmvc_Database, view names]

 Note that you do not need to specify the CMVC database explicitly when you
 copy an entire subsystem, because the database is copied automatically
 along with the rest of the subsystem's contents.


 Moving a Primary Subsystem to Another Host

 Primary subsystems are usually created directly on the desired host R1000.
 However, it is occasionally necessary to move a primary subsystem to a
 different host, usually because of space considerations. You can use
 either of two strategies to rehost a primary subsystem:

 *  You can create the new primary subsystem as a copy of the existing
    primary subsystem.

 *  You can convert an existing secondary subsystem into a primary
    subsystem.

 In both strategies, the old primary must subsequently be frozen, deleted,
 or turned into a secondary subsystem using the
 Cmvc_Maintenance.Make_Secondary command. The following subsections show
 how Archive commands are used in each strategy.


 Creating a New Primary Subsystem

 You can create a new primary subsystem on the desired host by using
 Archive commands with the Primary option to copy the original primary
 subsystem. The Primary option causes the resulting copy to be created as a
 primary subsystem; omitting this option causes the subsystem to be copied
 as a secondary. Because the original primary subsystem is automatically
 copied along with its CDB and CMVC databases, the new primary subsystem
 contains the correct compilation information and change history;
 furthermore, the same objects are controlled in the new primary as were
 controlled in the old one.

 After making a copy with the Primary option, you must freeze, delete, or
 convert the original primary subsystem into a secondary subsystem (using
 the Cmvc_Maintenance.Make_Secondary command).


 Converting an Existing Secondary Subsystem

 If a secondary subsystem already exists on the desired host, you can convert 
 it into the new primary system. To prepare the designated secondary subsystem
 for conversion:

 *  Use Archive commands to update the contents of the secondary subsystem.
    Be sure to copy any objects, views, or configurations that are in the
    existing primary but not yet in the secondary to be converted.

 *  Use the Archive commands to copy the CMVC database from the existing
    primary subsystem into the secondary subsystem.

 *  Use Archive commands with the Cdb option (or use the Cmvc_Maintenance-
    .Update_Cdb command) to update the secondary's compilation information.

 Now you can convert the prepared secondary to a primary using the
 Cmvc_Maintenance.Make_Primary command, setting the Moving_Primary
 parameter to True.

 After the secondary has been converted, you must freeze, delete, or
 convert the original primary subsystem into a secondary subsystem (using
 the Cmvc_Maintenance.Make_Secondary command).


 Copying Applications into New Project Libraries

 Sometimes you need to reorganize your work by moving an application into a
 different project library. For example, assume that your application
 consists of multiple subsystems that import each other, and that these
 subsystems currently reside in a world called !Users.Anderson.My_Project.
 Now you want these subsystems to reside in a world called !Local_Tools,
 instead.

 The basic steps for moving your application to the desired location are:

 1. Copy the subsystems into the new location using Archive.Copy with
    appropriate Use_Prefix and For_Prefix values; be sure to specify the
    Primary option:

      Archive.Copy(Objects    => "!Users.Anderson.My_Project.??",
                   Use_Prefix => "!Local_Tools",
                   For_Prefix => "!Users.Anderson.My_Project",
                   Options    => "Primary");  

 2. Use commands from package Cmvc to delete the original subsystems from
    the old location.

 Note that you can copy the entire set of subsystems in a single operation
 or you can copy them in multiple operations that use the same Use_Prefix
 and For_Prefix parameters.

 When the multiple, interdependent subsystems are copied into a new
 location, the Imports and Referencers objects of all full views are
 automatically adjusted to reflect the new components in the subsystems'
 names. However, the copy operation cannot adjust the import information
 for configuration-only releases. This will be
 a problem if you try to build full views from these releases. You can
 correct this problem by editing the Imports text file in the configuration
 object's State directory before you attempt to rebuild the configuration.


 Consistency Checking and Format Switches

 When you use Archive commands to copy or restore views or subsystems, the
 Cmvc_Maintenance.Check_Consistency command is automatically executed at
 the end of the operation. Among other things, this command determines
 whether the CMVC database was also copied or restored and, if so, checks
 that the images of controlled objects in the destination subsystem are
 consistent with the copied or restored CMVC database.

 The effect of the Cmvc_Maintenance.Check_Consistency command becomes ap-
 parent in the following situation:

 *  A subsystem contains views in which controlled Ada units are formatted
    (prettyprinted) according to certain switch values.

 *  These switch values are subsequently changed.

 *  The images of these Ada units are left as is (that is, they are not
    updated using the Library.Reformat_Image command).

 *  The subsystem is archived onto tape and then restored.

 The restore operation rebuilds the controlled units using the current
 switch values for the restored views. Consequently, the images of these
 newly formatted units will not match the images found in the restored CMVC
 database. Thus, when the Cmvc_Maintenance.Check_Consistency operation
 executes at the end of the restore operation, it will report errors for
 the reformatted units, even though the actual contents of the units have
 not changed.

 You can make the CMVC database match the new images of these units by
 checking the units out and checking them back in.


 Implications of Overwriting Views

 Views contain a number of Environment-defined objects that maintain state
 information. Such objects record a view's imports, referencers, CMVC
 access-control assignments, compiler switches, and so on. Copying a view
 automatically copies its state objects along with the user-defined objects
 in it. Because views are copied with their state, it is recommended that
 you avoid copying views that will overwrite existing views in a
 secondary subsystem. Overwriting an existing view causes not only
 user-defined objects to be overwritten, but its state objects as well. This
 can cause problems when the state of the copied view differs from the
 state of the overwritten view, as when imports or CMVC access control
 differ from host to host.

 For example, assume that:

 *  A primary subsystem called Utilities is the lowest-level subsystem in
    an application and is being developed in isolation on a host R1000
    called Machine_1.

 *  A secondary copy of Utilities exists on Machine_2, the host on which
    other, higher-level subsystems in the application reside.

 *  Views from the higher-level subsystems on Machine_2 import a combined
    view called Rev1_Working from the secondary Utilities subsystem. (In
    contrast, the corresponding view in the primary Utilities subsystem has
    no clients on Machine_1.)

 Now assume that all the user-defined objects in Rev1_Working have been
 changed in the primary subsystem and that you must propagate these changes
 to the corresponding view in the secondary. You might consider doing
 this by copying the whole Rev1_Working view from the primary subsystem,
 using a command such as the following:

   Archive.Copy (Objects    => "Rev1_Working",
                 Use_Prefix => "!Machine_2",
                 For_Prefix => "*",
                 Options    => "Replace, Remake");

 However, although this command would overwrite the user-defined objects as
 desired, it would also leave the overwritten Rev1_Working in an
 inconsistent state. In particular, the copy operation would overwrite the
 view's Referencers object with the corresponding object copied from the
 primary. But the Referencers object copied from the primary is empty,
 because Rev1_Working in the primary subsystem has no clients (indeed,
 none of the higher-level subsystems in the application
 even exist on Machine_1). Thus, the overwritten view on Machine_2 loses
 its referencers information, essentially "forgetting" which views have
 imported it.
                                                                           

 To avoid such state inconsistencies when you want to copy a view's
 user-defined objects, it is recommended that you use a naming expression
 that matches the user-defined objects while excluding the state objects.
 For example, if all of the user-defined objects in Rev1_Working are in the
 Units directory, you can use the following command to copy them:

   Archive.Copy (Objects    => "Rev1_Working.Units",
                 Use_Prefix => "!Machine_2",
                 For_Prefix => "*",
                 Options    => "Replace, Remake");

 Note that these considerations apply even when you specify options such as
 Changed_Objects, New_Objects, and so on. Thus, if you wanted to copy just
 the new objects from Rev1_Working's Units and Tools subdirectories, you
 could enter a command such as the following:

   Archive.Copy (Objects    => "Rev1_Working.[Units,Tools]",
                 Use_Prefix => "!Machine_2",
                 For_Prefix => "*",
                 Options    => "New_Objects, Replace, Remake");


 Summary: Archive and Multiple-Host Development

 Following is a summary of Archive usage in multiple-host development:

 *  Archive commands automatically copy a primary subsystem's CDB whenever
    you copy Ada units (or views containing Ada units) from a primary to a
    secondary. The only time you need to explicitly copy a CDB is when
    you are preparing a secondary view for incremental changes.

 *  Archive commands do not automatically copy a primary subsystem's CMVC
    database along with controlled objects, because under most
    methodologies, objects in primary subsystems are controlled, whereas
    objects in secondary subsystems are left uncontrolled. Although it is
    possible to copy a CMVC database to obtain a local copy of the
    primary's change history, to do so is feasible in only limited
    situations.

 *  Applications developed for the R1000 are usually developed in spec and
    load views. When such applications are developed using multiple hosts,
    changes are usually propagated by copying entire code views and by
    updating individual units in spec views.

 *  Applications developed for targets other than the R1000 are usually
    developed in combined views. When such applications are developed using
    multiple hosts, changes are usually propagated by updating individual
    units in the secondary's combined views.


 EXAMPLES

 This section contains examples that illustrate the use of the operations
 in this package. It is recommended that you read the reference entries for
 each of the commands in this package before reading these examples.

 The world shown in Figure 1 is used in all of the following examples.

  !Users.Phil.Tools : World;
    Cg_Switches              : C Pack_Spec 91/03/12 12:40:51 Phil    7263;
    Cg_Switches              : C Pack_Body 91/03/12 12:40:11 Phil    7499;
      .Scanner               : C Proc_Body 91/03/12 12:41:08 Phil    7283;
    Copyright_1991_Rational  :   Text      91/02/26 21:48:13 Phil     279;
    Find_Null_Acls           : C Proc_Spec 91/02/10 16:04:30 Phil    7460;
    Find_Null_Acls           : C Proc_Body 91/03/09 10:27:46 Phil   23826;
    Fix_Images               : C Proc_Spec 91/02/10 16:04:38 Phil    7485;
    Fix_Images               : C Proc_Body 91/03/12 12:38:48 Phil    7512;
    Restricted_Rights_Legend :   Text      91/02/26 21:48:14 Phil     517;
    Setup_Acls               : C Load_Proc 91/03/09 17:04:13 Phil    7304;
    Set_Universe_Acls        : C Proc_Spec 91/02/10 16:04:40 Phil    7223;
    Set_Universe_Acls        : C Main_Body 91/03/09 16:49:06 Phil   32525;
   Figure 1   World !Users.Phil.Tools


 Many of the following examples illustrate the use of the Copy procedure.
 Note that a copy operation is equivalent to a save followed by a restore.


 Example 1

 Assume you want to copy a world from one location to another on the same
 machine, repromote the Ada units within the world, and replace already
 existing objects with the same name as those being copied. The following
 command accomplishes this:

   Archive.Copy (Objects    => "!Users.Phil.Tools",
                 Use_Prefix => "!Users.Phil.Test_Area",
                 For_Prefix => "*",
                 Options    => "Promote,Replace",
                 Response   => "<PROFILE>");

 *  The Objects parameter specifies the name of the world to be copied.

 *  The Use_Prefix parameter specifies the location for the copy of that
    world and its contents.

 *  The For_Prefix parameter ("*") causes the Use_Prefix name to replace the
    entire name specified in the Objects parameter.

 *  The Replace option is included because you may want to execute this
    Copy procedure more than once, replacing installed or coded units that
    were already in !Users.Phil.Test_Area. Without this option, the Copy
    procedure would not overwrite an Ada unit in !Users.Phil.Test_Area
    unless it was in the source state.

 *  The Promote option causes units to be restored to their original (in
    this case, coded) state.


 Example 2

 Assume you want to copy updates made in !Users.Phil.Tools to
 !Users.Phil.Test_Area. In particular, you want to copy any units that
 appear in both !Users.Phil.Tools and !Users.Phil.Test_Area that have a
 more recent update time in !Users.Phil.Tools. You do not want to copy
 units that exist only in !Users.Phil.Tools. The following command
 accomplishes this, provided that the current context is !Users-
 .Phil.Tools:

   Archive.Copy (Objects    => "?",
                 Use_Prefix => "!Users.Phil.Test_Area",
                 For_Prefix => "$",
                 Options    => "Updated_Objects, Replace",
                 Response   => "<PROFILE>");

 *  The Objects parameter specifies all objects enclosed by the current
    context recursively (including nested directories and subunits of Ada
    units).

 *  The Use_Prefix parameter specifies the new library in which to place the
    units.

 *  The For_Prefix parameter specifies that the name of the current context
    should be replaced by the Use_Prefix string.

 Note that For_Prefix => "*" will not work in this case because Objects =>
 "?" does not specify a unique prefix. The $ wildcard provides the name of
 the current library as the prefix that is to be replaced.


 Example 3

 Assume you want to copy the links and switch-file associations from one
 world to another. Specifically, you want to copy links and other
 world-associated information from the current world (!Users.Phil.Tools)
 to the world !Users.Phil.Test_Area. The following command accomplishes
 this:

   Archive.Copy (Objects    => "$$",
                 Use_Prefix => "!Users.Phil.Test_Area",
                 For_Prefix => "*",
                 Options    => "Nonrecursive",
                 Response   => "<PROFILE>");

 *  The For_Prefix => "*" parameter is appropriate here because the Objects
    parameter specifies a unique object whose name will be changed to the
    Use_Prefix string during the copy.

 *  The Nonrecursive option causes only the objects named exactly by the
    Objects parameter to be moved, excluding any enclosed objects. Thus,
    only the world is copied. Moving the world causes the links and
    associations to be copied.


 Example 4

 Assume you want to copy units from !Users.Phil.Tools to
 !Users.Phil.Test_Area_2 and change their names so that each unit and file
 has the prefix Sim_. The following command accomplishes this:

   Archive.Copy (Objects    => "!Users.Phil.Tools.@",
                 Use_Prefix => "!Users.Phil.Test_Area_2.Sim_@",
                 For_Prefix => "!Users.Phil.Tools.@",
                 Options    => "",
                 Response   => "<PROFILE>");

 *  The Objects parameter specifies just units in the Tools library. Since
    the world Tools itself is not to be renamed, it must be excluded from
    the objects to be saved. If it is necessary to copy links and switch
    associations for the world, this must be done in a separate command.

 *  The Use_Prefix and For_Prefix parameters specify the prefix string to be
    replaced and substituted. Note the use of the (@) wildcard in the
    For_Prefix parameter and the @ substitution character in the Use_Prefix
    parameter.

 Note that the Ada source for the renamed units will be changed to the new
 unit names. Other references to the old names within the units will not be
 changed, which may cause a unit to fail to promote.

 The resulting world is displayed in Figure 2.

 !Users.Phil.Test_Area_2 : World;
    Sim_Cg_Switches             : S Pack_Spec 91/03/12 12:40:51 Phil  7263 ;
    Sim_Cg_Switches             : S Pack_Body 91/03/12 12:40:11 Phil  7499 ;
    Sim_Copyright_1991_Rational :   Text      91/02/26 21:48:13 Phil   279 ;
    Sim_Find_Null_Acls          : S Proc_Spec 91/02/10 16:04:30 Phil  7460 ;
    Sim_Find_Null_Acls          : S Proc_Body 91/03/09 10:27:46 Phil 23826 ;
    Sim_Fix_Images              : S Proc_Spec 91/02/10 16:04:38 Phil  7485 ;
    Sim_Fix_Images              : S Proc_Body 91/03/12 12:38:48 Phil  7512 ;
    Sim_Restricted_Rights_Legen :   Text      91/02/26 21:48:14 Phil   517 ;
    Sim_Set_Acls                : C Load_Proc 91/03/09 17:04:13 Phil  7304 ;
    Sim_Set_Universe_Acls       : S Proc_Spec 91/02/10 16:04:40 Phil  7223 ;
    Sim_Set_Universe_Acls       : S Main_Body 91/03/09 16:49:06 Phil 32525 ;
   Figure 2   World !Users.Phil.Test_Area_2



 Example 5

 Assume you want to copy a set of objects from the current library into the
 library !Users.Phil. The following command accomplishes this:

   Archive.Copy (Objects    => "[Fix_Images'Spec,Copy@]",
                 Use_Prefix => "!Users.Phil",
                 For_Prefix => "$",
                 Options    => "",
                 Response   => "<PROFILE>");

 *  The Objects parameter uses naming set notation and a wildcard to name
    the specification of Fix_Images and any objects in the current library
    that have a name with the prefix Copy.

 *  The $ wildcard provides the name of the current library as the prefix
    that is
    to be replaced. Note that For_Prefix => "*" will not work in this case
    because Objects => "?" does not specify a unique prefix.


 Example 6

 Assume you want to copy objects onto another R1000, using Rational
 Networking --TCP/IP. Furthermore, you want the objects to retain their
 original names. The following command accomplishes this:

   Archive.Copy (Objects    => "!Users.Phil.Test_Area",
                 Use_Prefix => "!!Zebra",
                 For_Prefix => "*",
                 Options    => "",
                 Response   => "<PROFILE>");

 *  The Objects parameter specifies the objects to be copied.

 *  The Use_Prefix parameter specifies only the destination R1000 name
    (Zebra); no library name is specified. Therefore, the copied objects
    have the same name on Zebra as on the source R1000.

 Note that links are created to point to same-named units on Zebra.


 Example 7

 Assume you want to copy objects into another library on another R1000,
 using Rational Networking--TCP/IP. The objects will be renamed on the
 destination R1000. The following command accomplishes this:

   Archive.Copy (Objects    => "!Users.Phil.Test_Area",
                 Use_Prefix => "!!Zebra!Delta_Project.Tools",
                 For_Prefix => "*",
                 Options    => "",
                 Response   => "<PROFILE>");

 *  The Use_Prefix parameter specifies both the destination R1000 name and
    the new library name.

 *  If libraries named in the Use_Prefix parameter need to be created, they
    are created as worlds. In this case, if Delta_Project did not exist,
    it would be created.


 Example 8

 Assume you want to save objects as a form of backup. Specifically, you want
 to save the contents of !Users.Phil.Tools, including all subobjects. The
 following command makes an archive-save file in the directory
 !Users.Phil.Backups:

   Archive.Save (Objects  => "!Users.Phil.Tools",
                 Options  => "R1000",
                 Device   => "!Users.Phil.Backups.Tools_91_03_09",
                 Response => "<PROFILE>");

 *  The Objects parameter specifies the objects to be saved.

 *  The Device parameter specifies the directory to be created to contain
    the save.

 The Restore procedure can be used later to restore individual objects or
 all objects saved.


 Example 9

 Assume you want to copy the changed objects from the view
 !Commands.Internal.Maintenance.Rev9_0_Spec to a corresponding view on
 another R1000 named Shelby. Changed objects include both updated objects
 and new objects. The following command accomplishes this:

   Archive.Copy
       (Objects    => "!Commands.Internal.Maintenance.Rev9_0_Spec",
        Use_Prefix => "!!Shelby",
        For_Prefix => "*",
        Options    => "After=03/01/91, Replace,
                       Changed_Objects, Promote",
        Response   => "<PROFILE>");

 *  The After option specifies that only objects modified after 3/1/91 are to
    be considered.

 *  The Replace option allows Ada units in other than the source state to
    be overwritten.

 *  The Changed_Objects option causes only the changed objects on Shelby to
    be copied.

 *  The Promote option causes moved objects to be promoted to their
    original unit state.

 *  Compatibility information needed for any objects is automatically
    copied as well.


 Example 10

 Assume you have two subsystems: !Project.Archival_Release.Test_1 and
 !Project.Archival_Release.Accuracy_Tests.Test_1. In each of these
 subsystems, you have a Rev1_0_Spec view. You want to copy all of the units
 in the Rev1_0_Spec view into a new view called Dest_0_Spec. The following
 command accomplishes this:

   Archive.Copy
       (Objects    =>
          "!Project.Archival_Release.??.Test_1.Rev1_0_Spec.Units?",
        Use_Prefix =>
          "!Project.Archival_Release.@.Test_1.Dest_0_Spec.Units@",
        For_Prefix =>
          "!Projects.Archival_Release.?.Test_1.Rev1_0_Spec.Units?",
        Options    => "",
        Response   => "<PROFILE>");


 @node !Commands.Archive.Copy

 procedure Copy (Objects    : String := "<IMAGE>";
                 Use_Prefix : String := "*";
                 For_Prefix : String := "*";
                 Options    : String := "";
                 Response   : String := "<PROFILE>");

 DESCRIPTION

 Copies one or more objects from one location to another, either on the
 same R1000 or between two R1000s connected through Rational
 Networking--TCP/IP.

 The Copy procedure leaves the original source objects in place, creating a
 copy in the location indicated by the Use_Prefix parameter. The Copy
 procedure also:

 *  Preserves the objects' hierarchical structure, reconstructing libraries
    as necessary. Subsystems are reconstructed only if they are needed to
    restore entire views.

 *  Optionally promotes Ada units to the states they were in when they were
    copied or to any other specified goal state.

 *  Changes the location of objects as specified in the Use_Prefix and
    For_Prefix parameters.

 *  Rebuilds the links for copied worlds and reassociates copied libraries
    with their switch files.

 *  Permits the user to change the access-control lists (ACLs) of objects
    copied outside subsystems.

 By default, the Copy procedure copies all of the objects named by the
 Objects parameter, including their sublibraries and subunits. You can
 further filter the specified objects by specifying one or more of the
 following options through the Options parameter: After, Nonrecursive,
 New_Objects, Existing_Objects, Updated_Objects, Changed_Objects, and
 Different_Objects.

 Also by default, copied objects overwrite existing Environment objects of
 the same name, unless the existing objects are frozen, checked in, or in
 the installed or coded state with dependents. You can allow such objects
 to be overwritten by specifying the Replace option through the Options
 parameter.

 Note that objects can alternatively be moved between R1000s by saving
 objects onto tape with the Save procedure on one R1000 and then using the
 Restore procedure to read the tape on the other R1000.


 PARAMETERS

 Objects : String := "<IMAGE>";

 Specifies one or more objects to be copied. These objects can include
 worlds, directories, Ada units, text files, data files, switch files,
 activities, subsystems, subsystem views, and user binary files. By
 default, the procedure copies all the specified objects and the objects
 they contain (you can override this default behavior with the Nonrecursive
 option).

 By default, the current image is copied, unless there is a selection in that 
 image, in which case the selected object is copied. The parameter accepts any
 naming expression; multiple objects can be specified using wildcards,
 context characters, set notation, indirect files, and attributes. If you
 use set notation or indirect files, it is recommended that you separate the
 individual names with semicolons so that the command will quit if
 unresolvable names are reported. (When commas are used, the operation
 copies what it can and ignores unresolvable names.) For further
 information, see the Parameter-Value Conventions tabbed section in the
 Reference Summary (RS).

 You can specify objects that reside on another R1000 on the network by
 prepending the name of that R1000 to the fully qualified pathnames of the
 objects. An R1000 name has the form !!Name, where Name denotes the R1000's
 machine name. For example, the following Objects parameter causes the
 command to copy all the objects in the library !Users.Anderson.Statistics
 on an R1000 called M1:

   Objects => "!!M1!Users.Anderson.Statistics.@"

 You can omit the R1000 name if the objects to be copied already reside on
 the current R1000. Furthermore, you can copy objects between two R1000s
 using a command entered on a third R1000; this is accomplished by
 specifying the source and destination R1000 names in the Objects and
 Use_Prefix parameters, respectively.


 Use_Prefix : String := "*";

 Specifies all or part of the destination names under which objects are to
 be copied. The value of this parameter thus determines, at least in part,
 where to rebuild the copied objects.

 The default value "*" causes the copied objects to keep their original
 names. Note that this value is useful only when copying objects from
 another R1000 into an identical library structure on the current R1000;
 otherwise, the default value would merely cause objects to overwrite
 themselves.

 A nondefault Use_Prefix value consists of one or more consecutive name
 components forming a pathname. (A fully qualified pathname is recommended
 because it is more explicit; if a relative pathname is used, it is
 resolved relative to the current library.) When the Use_Prefix parameter
 has a nondefault value, it combines with the values of the Objects and
 For_Prefix parameters to specify new destination names for the copied
 objects.

 In particular, the Archive.Copy command derives each destination name by
 inserting the Use_Prefix value in place of the shortest portion of the
 Objects name that is matched by the For_Prefix value. For example, the
 following command creates a copy called !Users.Miyata.Tools.Sort by taking
 the Objects name (!Users.Anderson.Statistics.Tools.Sort), removing the
 portion matched by the For_Prefix (!Users.Anderson.Statistics), and
 putting the string specified by Use_Prefix (!Users.Miyata) in its place:

   Archive.Copy
            (Objects    => "!Users.Anderson.Statistics.Tools.Sort",
             Use_Prefix => "!Users.Miyata",
             For_Prefix => "!Users.Anderson.Statistics");

 Thus, the Use_Prefix parameter essentially specifies a fully qualified name
 that replaces part or all of the name specified by the Objects parameter,
 as determined by the For_Prefix parameter:

 *  If the For_Prefix value matches the entire Objects name, then the
    Use_Prefix value becomes the entire destination name of the copied
    object.

 *  If the For_Prefix value matches a prefix other than the entire name
    (where a prefix is a set of consecutive name components starting with
    the leftmost component), then the Use_Prefix value names a library
    that is to enclose the copied object at some level in the library
    hierarchy.

 *  If the For_Prefix parameter does not match any prefix of the Objects
    name, a warning message is generated and the specified object is not
    copied.

 You can copy objects onto another R1000 on the same network by prepending
 the name of the destination R1000 to the Use_Prefix value. An R1000 name
 has the form !!Name, where Name denotes the R1000's machine name. (The
 machine name of an R1000 is typically displayed in the banner under the
 message window.) For example, the following Use_Prefix parameter causes the
 command to copy objects into the library !Project_1 on an R1000 called M2:

   Use_Prefix => "!!M2!Project_1"

 You can distribute copied objects to multiple R1000s by specifying
 multiple destination R1000 names enclosed in brackets. For example, the
 following Use_Prefix parameter causes the command to distribute objects to
 the !Project_1 library on each of three R1000s:

   Use_Prefix => "[!!M1,!!M2,!!M3]!Project_1"

 Another way to specify multiple R1000s is to create a file containing the
 destination R1000 names (one per line) and then specify the file using
 indirect-file notation. For example, assume a file called Targets exists
 on the current R1000 and that Targets contains the names !!M1, !!M2, and
 !!M3 on separate lines. The following Use_Prefix parameter distributes
 objects to the !Project_1 library on each of the desired R1000s:

   Use_Prefix => "_Targets!Project_1"

 You can omit the R1000 name if the command is entered on the destination
 R1000. Combinations of Objects and Use_Prefix values control whether and
 how objects are copied between R1000s, as described below:

 *  To copy objects into a different location on the same R1000, omit the
    R1000 name in both the Objects and Use_Prefix values. (The Use_Prefix
    parameter must have a nondefault value.)

 *  To copy objects from another R1000 (for example, M1) onto the current
    R1000, specify the source R1000 name (!!M1) as part of the Objects
    value and omit the destination R1000 name in the Use_Prefix value. (The
    Use_Prefix parameter can have the default value "*" to preserve the
    original object names.)

 *  To copy objects from the current R1000 onto another R1000 (for example,
    M2), omit the source R1000 name from the Objects value and specify the
    destination R1000 name (!!M2) as part of the Use_Prefix value. (You can
    use just the destination R1000 name as the entire Use_Prefix value to
    preserve the original object names on that R1000; for example,
    Use_Prefix => "!!M2".)

 *  To copy objects between two R1000s (for example, M1 and M2), neither of
    which is the current R1000, specify the appropriate R1000 name in the
    values for Objects and Use_Prefix.

 If the For_Prefix value contains wildcards, then both the For_Prefix and the
 Use_Prefix value must account for the entire object name, not just a
 prefix. The Use_Prefix value can contain a substitution character
 corresponding to each wildcard.

 The Use_Prefix parameter accepts only the @ substitution character. The @
 substitution character expands to the string matched by a wildcard in
 the For_Prefix. When you specify a Use_Prefix containing one or more @
 substitution characters, these characters are mapped, from right to left,
 onto the wildcards in the For_Prefix value. The Environment then expands
 the destination name by replacing each substitution character with the
 corresponding string from the For_Prefix. For further information, see
 "Specifying Destination Names" in the introduction to this package.


 For_Prefix : String := "*";

 Combines with the Objects and Use_Prefix parameters to specify the
 destination names for the copied objects. The For_Prefix parameter
 determines how much of the Objects name is to be replaced by the Use_Prefix
 value to produce each destination name. When the default value "*" is
 used, the For_Prefix parameter allows the Use_Prefix value to replace the
 entire Objects name.

 A nondefault For_Prefix value must be a naming expression that matches a
 prefix of the Objects name, where a prefix is one or more consecutive name
 components starting with the name's leftmost component. For example, if
 the Objects name is !Users.Anderson.Statistics.Tools, its prefixes include: 
 !Users, !Users.Anderson, !Users.Anderson.Statistics, and
 !Users.Anderson.Statistics.Tools. Note that the entire name can be specified
 as a prefix; the default For_Prefix value "*" is a shortcut for this.

 When the For_Prefix parameter has a nondefault value, the destination name
 is derived from the original Objects name by replacing the shortest prefix
 matched by the For_Prefix parameter with the value of the Use_Prefix
 parameter. (See the Use_Prefix parameter for an example.) If the For_Prefix
 parameter does not match any prefix in an Objects name, a warning message
 is generated and the specified objects are not copied. Note that the
 For_Prefix parameter is ignored when the Use_Prefix parameter has the
 special value "*".

 You can copy multiple objects under different names by matching portions
 of the Objects name with wildcards or other restricted naming expressions
 in the For_Prefix parameter. When For_Prefix contains wildcards, the
 Use_Prefix parameter can match each wildcard with a substitution character.
 For further information and a list of accepted wildcard characters, see
 "Specifying Destination Names" in the introduction to this package.


 Options : String := "";

 Specifies the options to be used during the copy operation. The Options
 parameter allows you to specify, among other things, a particular subset
 of objects to copy, the compilation state of the copied objects, and the
 ACLs for the copied objects. You can specify more than one option. For
 further information about specifying options, see the Parameter-Value
 Conventions tabbed section in the Reference Summary (RS).

 The following list summarizes the options accepted by the Archive.Copy
 command. Descriptions of each option are given after this list:

 After                      Become_Owner          Cdb
 Changed_Objects            Code                  Compatibility_Database
 Default_Acl                Different_Objects     Effort_Only
 Enable_Privileges          Existing_Objects      Goal_State
 Ignore_Cdb                 Links                 New_Objects
 Nonrecursive               Object_Acl            Password


 Primary                    Promote               Remake
 Replace                    Require_Parents       Revert_Cdb
 Trailing_Blanks            Uncontrol             Updated_Objects
 User                       Verbose               Volume
 World_Acl


 *  After = time

    Copies only objects that have been changed more recently than the
    specified time, which can be a date, a time of day, or both, and can be
    written in any of the styles defined by the
    !Tools.Time_Utilities.Date_Format type and the !Tools-
    .Time_Utilities.Time_Format type. For example, specifying the following
    value for the Options parameter copies only those objects named by the
    Objects parameter that were updated after June 11, 1991, at noon:

      Options => "After=(06/11/91 12:00)"

 *  Become_Owner

    A Boolean option. When True, causes the ACLs of all copied worlds to be
    modified so that the copying username is given owner access to the
    copied worlds. This option has no effect on copied views.

    If a group specified in the ACL for an object does not exist on the
    machine onto which the object is copied, the ACL entry for that group
    is removed from the object's ACL.

 *  Cdb [= subsystems]

    Abbreviated form of the Compatibility_Database option.


 *  Changed_Objects

    A Boolean option. When True, causes new and updated objects to be
    copied. This is equivalent to specifying both the New_Objects and
    Updated_Objects options.


 *  Code [= loaded main programs]

    Copies only the code segments for the specified loaded main programs,
    when these programs will overwrite existing ones. Loaded main programs
    consist of an Ada-unit specification and a set of code segments. By
    default, the Ada-unit specification is copied in the coded state.
    However, if a copied loaded main program overwrites an existing one,
    the specification of the existing program is demoted, along with any
    units that depend on it. Specifying the Code option prevents such
    demotion by causing only the code segments to be copied.

    This option can be used only if an existing loaded main program will be
    overwritten and if the specification of the copied program has the
    same parameter profile as the specification of the overwritten program
    (they need not have the same name). No segments are copied unless both
    of these conditions are met.

    If the option name is specified by itself (that is, if the loaded main
    programs portion of the option is omitted), then the command copies the
    code segments of all loaded main programs specified by the Objects
    parameter. An error is generated if the Objects parameter specifies no
    loaded main programs. For example, the following command copies just
    the code segments from a remote program called
    !Users.Anderson.Search_For, overwriting the code segments of a loaded
    main program with the same name on the current R1000:

      Archive.Copy (Objects => "!!M2!Users.Anderson.Search_For",
                    Options => "Code");

    To copy other objects along with the code segments from one or more
    loaded main programs, you can specify the names of the loaded main
    programs as the value to the Code option:

      Archive.Copy (Objects => "other objects",
                    Options => "Code=loaded main programs");

    In this case, other objects specifies objects that are probably disjoint
    from loaded main programs.


 *  Compatibility_Database [= subsystems]

    Specifies that the command is to copy only the compatibility database
    (CDB) for each of the specified subsystems, without copying the
    subsystems themselves. This option is useful for updating the CDB in a
    secondary subsystem before propagating incremental changes from a
    primary subsystem. Note that copying with this option is an alternative
    to using the Cmvc_Maintenance.Update_Cdb command. (For further
    information about primary and secondary subsystems and their
    compatibility databases, see the Project Management (PM) book.)

    The Compatibility_Database option can be abbreviated as Cdb. If the
    option name is specified by itself (that is, if the subsystems portion
    of the option is omitted), then the command copies the CDBs of all
    subsystems specified by the Objects parameter. An error is generated if
    the Objects parameter specifies no subsystems. For example, the
    following command copies the CDB from a remote subsystem called
    !Projects.Mail_Utilities into a subsystem with the same name on the
    current R1000:

      Archive.Copy (Objects => "!!M2!Projects.Mail_Utilities",
                    Options => "Cdb");

    To copy other objects along with the CDB from one or more subsystems,
    you can specify the subsystem names as the value to the Cdb option:

      Archive.Copy (Objects => "other objects",
                    Options => "Cdb=subsystems");

    In this case, other objects specifies objects that are probably disjoint
    from subsystems.


 *  Default_Acl = new acl

    Specifies the new default ACL to be given to each destination world. A
    world's default ACL is the ACL that is assigned to new files and Ada
    units created in that world. This option has no effect on copied views.

    The value for this option can be a specific ACL. The specified ACL must
    follow the syntax rules for ACLs (see the introduction to package
    Access_List in this book). For example, the following Options parameter
    gives John (only John) complete default access to all the worlds
    resulting from the copy operation:

      Options => "Default_Acl=(John=>RW)"

    The Default_Acl option also accepts any one of the literal values
    listed below. Each of these values causes some existing default ACL to
    be assigned to the destination worlds:

    Archived           Assigns each destination world the default ACL of
                       the corresponding source world.

    Inherit            Assigns each destination world a default ACL
                       according to the standard inheritance rules for
                       new worlds. That is, a destination world inherits
                       its default ACL from the world into which it is
                       copied.

    Retain             Assigns each destination world the default ACL of
                       the world it has overwritten. If no world was
                       overwritten, the destination world is assigned the
                       default ACL of the source world from which it was
                       copied.

    If you omit the Default_Acl option entirely, the Copy command behaves
    as if you specified the Retain value.

    Note that if a group specified in the ACL for an object does not exist
    on the machine onto which the object is copied, the ACL entry for that
    group is removed from the object's ACL.


 *  Different_Objects

    A Boolean option. When True, allows objects to be copied only if they
    will overwrite existing objects and if they have a different update
    time (whether earlier or later) than the objects they will overwrite.
    Specifying this option prevents objects from being overwritten by
    objects with the same update time.


 *  Effort_Only

    A Boolean option. When True, displays a list of the objects to be
    copied without actually copying them. This option is useful for testing
    the effect of a particular combination of values for the Objects and
    Options parameters.


 *  Enable_Privileges

    A Boolean option. When True, causes the copy operation to attempt to
    enable privileges. Enabling privileges allows the command to override
    access control when reading and creating objects. Privileges can be
    enabled only if the copying username belongs to the predefined group
    called Privileged.

    Note that this option enables privileges for all of the identities
    associated with the command, including the identities of any archive
    servers that are invoked on other machines. In contrast, entering the
    Operator.Enable_Privileges command enables privileges only for the
    initiating username on the current machine.


 *  Existing_Objects

    A Boolean option. When True, allows objects to be copied only if they
    will overwrite existing objects, regardless of their update times.
    Specifying this option prevents new objects from being copied.


 *  Goal_State = Ada unit state

    Attempts to promote all of the copied Ada units to the specified
    compilation state. Any one of the following states can be specified as
    values to this option: Archived, Source, Installed, or Coded.

    This option overrides the default command behavior, which is to leave
    the copied Ada units in the source state. The Promote and Remake
    options are alternatives to the Goal_State option; only one of these
    three options can be specified.

    The copied Ada units can be promoted to the installed or coded state
    only if the necessary links exist in the destination context. To ensure
    the existence of the proper links, you can copy the world enclosing the
    desired Ada units along with the Ada units themselves; the links are
    copied along with the world. Note, however, that the copied links can
    be rebuilt only if the units to which they refer exist and have the
    same source name. (That is, objects that depend on missing units cannot
    be promoted.)


 *  Ignore_Cdb

    A Boolean option. When True, copies the specified views or units from
    views without also copying the enclosing subsystem's compatibility
    database (CDB). Ignoring the CDB saves time when source code is copied
    between unrelated subsystems (subsystems that are not associated as
    primaries and secondaries). Copying units between unrelated subsystems
    is typically done when units from

    one subsystem are to serve as templates for developing units in the
    other subsystem.

    The Ignore_Cdb option serves only to optimize the copy operation so
    that no time is spent saving or transferring the CDB from the source
    subsystem. Note that no harm is done if this option is omitted,
    however, because a copied CDB can never actually overwrite the CDB from
    an unrelated subsystem.


 *  Links [= worlds]

    Specifies that the command is to copy only the links for each of the
    specified worlds, without copying the worlds themselves. Copying with
    the Links option is a more powerful alternative to using the Links.Copy
    command, which copies links among worlds on the same R1000. In
    contrast, copying with the Links option allows you to copy links
    between R1000s.

    If the option name is specified by itself (that is, if the worlds
    portion of the option is omitted), then the command copies the links
    of all worlds specified by the Objects parameter. An error is generated
    if the Objects parameter specifies no worlds. For example, the following
    command copies the links from a remote world called
    !Users.Anderson.Statistics to a world with the same name on the current
    R1000:

      Archive.Copy (Objects => "!!M2!Users.Anderson.Statistics",
                    Options => "Links");

    To copy other objects along with the links from one or more worlds, you
    can specify the world names as the value to the Links option:

      Archive.Copy (Objects => "other objects",
                    Options => "Links=worlds");

    In this case, other objects specifies objects that are probably disjoint
    from worlds.


 *  New_Objects

    A Boolean option. When True, allows only new objects to be copied,
    where new objects are objects that will not overwrite existing objects.
    Specifying this option prevents existing objects from being
    overwritten, while permitting objects to be copied under new names or
    in new locations.


 *  Nonrecursive

    A Boolean option. When True, copies only the objects that are actually
    named by the Objects parameter. This option overrides default command
    behavior, so sublibraries and subunits within the named objects are not
    copied unless they are explicitly specified in the Objects parameter.
    The Nonrecursive option allows you to copy libraries and their links
    and switch associations without automatically copying the objects in
    those libraries as well. Furthermore, this option permits you to copy
    a library and a subset of its contents without copying the entire
    library. For example, the following command copies the world !Users-
    .Anderson along with only those subobjects whose names begin with
    Test_:

      Archive.Copy
           (Objects => "!!M2[!Users.Anderson,!Users.Anderson.Test_@]",
            Options => "Nonrecursive");

    To better understand the effect of the Nonrecursive option, compare the
    preceding command with the following:

      Archive.Copy (Objects => "!!M2!Users.Anderson.Test_@");

    Like the first command, this second command copies the objects in
    !Users.Anderson whose names begin with Test_. The difference is that
    the first command also copies the library !Users.Anderson along with 
    its links and switch-file associations, whereas the second command does 
    not. Instead, the second command merely creates a library named 
    !Users.Anderson if such a library does not already exist on the 
    destination R1000; no links or switch-file
    associations are copied from the original library.


 *  Object_Acl = new acl

    Specifies the new ACL to be given to each of the copied files and Ada
    units. An object's ACL determines which users can view or modify that
    object. This option has no effect on objects copied into views.

    The value for this option can be a specific ACL. The specified ACL must
    follow the syntax rules for ACLs (see the introduction to package
    Access_List in this book). For example, the following Options parameter
    gives John (and only John) complete access to all the destination files
    and Ada units resulting from the copy operation:

      Options => "Object_Acl=(John=>RW)"

    The Object_Acl option also accepts any one of the literal values listed
    below. Each of these values causes some existing ACL to be assigned to
    the destination files and Ada units:

    Archived           Assigns each destination file or Ada unit the ACL of
                       the original file or Ada unit from which it was
                       copied.

    Inherit            Assigns each destination file or Ada unit an ACL
                       according to the standard inheritance rules for new
                       objects. That is, each destination object gets its
                       ACL from the default ACL of the world into which it
                       was copied.

    Retain             Assigns each destination file or Ada unit the ACL of
                       the object it has overwritten. If no object was
                       overwritten, the destination object is assigned the
                       ACL of the original object from which it was copied.

    If you omit the Object_Acl option entirely, the Copy command behaves as
    if you specified the Retain value.

    Note that if a group specified in the ACL for an object does not exist
    on the machine onto which the object is copied, the ACL entry for
    that group is removed from the object's ACL.


 *  Password = password

    Specifies the password to be used along with the username specified by
    the User option. Using the Password option is a security risk, because
    the password you specify is visible as clear text both in the command
    window and in the Copy command's message log. As an alternative to
    using this option, you can invoke a remote-passwords file (see "Archive
    and Access Requirements," in the introduction to this package).


 *  Primary

    A Boolean option. When True, causes the specified subsystems to be
    copied as primary subsystems rather than as secondary subsystems.
    Primary subsystems permit ongoing development because their
    compatibility databases (CDBs) can be updated. After a copy has been
    made with the Primary option, you must freeze, delete, or convert the
    original primary subsystem into a secondary subsystem using the
    Cmvc_Maintenance.Make_Secondary command. This option is subject to CDB
    capability, as described in the introduction to package Cmvc-
    _Access_Control. For further information on subsystems and CDBs, see
    the Project Management (PM) book.


 *  Promote

    A Boolean option. When True, attempts to promote copied Ada units to
    their original states (installed or coded). This option overrides the
    default command

    behavior, which is to leave the copied Ada units in the source state.
    The Remake and Goal_State options are alternatives to the Promote
    option; only one of these three options can be specified.

    The copied Ada units can be promoted only if the necessary links exist
    in the destination context. To ensure the existence of the proper
    links, you can copy the world enclosing the desired Ada units along
    with the units themselves; the links are copied along with the world.
    Note, however, that the copied links can be rebuilt only if the units
    to which they refer exist and have the same source name. (That is,
    objects that depend on missing units cannot be promoted.)


 *  Remake [= No_Mains]

    Attempts to promote all of the copied Ada units to their original
    states, along with any dependent units that were demoted by the Replace
    option. That is, this option is like the Promote option, except that it
    also "repairs" the compilation effects of the Replace option. The
    Remake option overrides the default command behavior, which is to
    leave the copied Ada units in the source state. The Goal_State and
    Promote options are alternatives to the Remake option; only one of
    these three options can be specified.

    If the option name is specified by itself (that is, the literal value
    No_Mains is omitted), an attempt is made to remake all of the specified
    Ada units. If the literal value No_Mains is specified, then no attempt
    is made to remake dependent main programs.

    The copied Ada units can be promoted only if the necessary links exist
    in the destination context. To ensure the existence of the proper
    links, you can copy the world enclosing the desired Ada units along
    with the units themselves; the links are copied along with the world.
    Note, however, that the copied links can be rebuilt only if the units
    to which they refer exist and have the same source name. (That is,
    objects that depend on missing units cannot be promoted.)


 *  Replace

    A Boolean option. When True, permits existing objects to be overwritten
    even if they are frozen, compiled, and/or controlled and checked in. In
    particular, this option performs the following operations as necessary:

    -  Unfreezes frozen objects for the duration of the operation. This
       includes any parent libraries into which objects are being copied.
       The unfrozen objects are automatically made frozen again at the end
       of the operation.

    -  Demotes installed or coded Ada units to source, along with their
       clients.
       (To do this, the option invokes the Compilation.Demote procedure
       with "<ALL_WORLDS>" specified in the Limit parameter.) The demoted
       units are repromoted only if the Remake option is also specified.

    -  Attempts to check out any controlled objects that are not already
       checked out in the destination view. These objects are automatically
       checked in again at the end of the operation. Note that the checkout
       attempt will fail if the objects are already checked out in
       another view. In this case, the objects in question are not
       overwritten. To guarantee that controlled objects are overwritten,
       you can specify the Uncontrol option in addition to the Replace op-
       tion; however, uncontrolling the objects will cause their change
       history to be lost.

    This option is subject to CMVC access control.


 *  Require_Parents

    A Boolean option. When True, prevents objects from being copied unless
    the required destination context already exists. This option overrides
    the default command behavior, which is to create any missing 
    hierarchical structure (for example, nested libraries) that is 
    required to copy the objects under the desired names.


 *  Revert_Cdb

    A Boolean option. When True, permits a less recently updated version of
    a compatibility database (CDB) to overwrite a more recently updated
    version. This option overrides the default behavior of the Copy command
    (by default, a CDB can be overwritten only by a more recently updated
    CDB). You should use this option only under supervision of Rational
    support personnel; if used incorrectly, this option can result in loss
    of compatibility among the spec and load views in a subsystem. This
    option is subject to CDB capability, as described in the introduction
    to package Cmvc_Access_Control. For further information on subsystems
    and CDBs, see the Project Management (PM) book.


 *  Trailing_Blanks = integer

    Preserves some or all of the user-inserted line breaks in copied Ada
    units. Line breaks are preserved only in lines that end in more than
    the specified number of trailing blank characters. Otherwise, the copied
    units are reformatted in the destination context and line breaks are
    inserted by the pretty-printer there.


 *  Uncontrol

    A Boolean option. When True, permits controlled objects to be
    overwritten by making them uncontrolled in the destination view for the
    duration of the copy operation. (The overwritten objects are
    automatically made controlled again at the end of the operation.) This
    option has no effect unless the Replace option is also specified.

    Specifying the Uncontrol option guarantees that controlled objects are
    overwritten. However, making the objects uncontrolled severs them
    from the objects to which they are joined. Furthermore, when these
    objects are recontrolled, they are given new reservation tokens, so
    that their change history is effectively lost. Note that when the
    Replace option is used without the Uncontrol option, an attempt is made
    to check out the objects in question, thereby preventing loss of
    history.

    The Uncontrol option is subject to CMVC access control.


 *  Updated_Objects

    A Boolean option. When True, allows only updated objects to be copied.
    An object is considered updated if it will overwrite an existing object
    and if it has been modified more recently than the object it will
    overwrite. This option is especially useful when there is parallel
    development on multiple R1000s and you need to copy updated objects
    from one R1000 to another.


 *  User = username

    Specifies the username to be used as the identity of the archive server
    on a remote R1000. When you specify a username, you must also specify a
    password, using either the Password option or a remote-passwords file
    (see "Archive and Access Requirements," in the introduction to this
    package).

    Note that using the Password option is a security risk, because the
    password you specify is visible as clear text both in the command
    window and in the Copy command's message log.


 *  Verbose

    A Boolean option. When True, specifies that extra log messages are to be
    generated describing more fully the steps of the copy operation.


 *  Volume = volume id

    Specifies the disk volume on which to create destination worlds. Each
    disk volume is identified by an integer between 1 and 31; for example,
    a four-disk system has disks 1, 2, 3, and 4. Omitting this option is
    equivalent to specifying the value 0, which instructs the operation to
    pick the disk volume with the most free space.


 *  World_Acl = new acl

    Specifies the new ACL to be given to each destination world. A world's
    ACL determines which users can view, create objects in, delete, or
    change the ACLs of objects in that world. This option has no effect on
    copied views.

    The value for this option can be a specific ACL. The specified ACL must
    follow the syntax rules for ACLs (see the introduction to package
    Access_List in this book). For example, the following Options parameter
    gives John (and only John) complete access to all the worlds resulting
    from the copy operation:

      Options => "World_Acl=(John=>RCOD)"

    The World_Acl option also accepts any one of the literal values listed
    below. Each of these values causes some existing ACL to be assigned to
    the destination worlds:

    Archived           Assigns each destination world the ACL of the
                       corresponding source world.

    Inherit            Assigns each destination world an ACL according to
                       the standard inheritance rules for new worlds. That
                       is, a destination world inherits its ACL from the
                       world into which it was copied.

    Retain             Assigns each destination world the ACL of the world
                       it has overwritten. If no world was overwritten,
                       the destination world is assigned the ACL of the
                       source world from which it was copied.

    If you omit the World_Acl option entirely, the Copy command behaves as
    if you specified the Retain value.

    Note that if a group specified in the ACL for an object does not exist
    on the machine onto which the object is copied, the ACL entry for that
    group is removed from the object's ACL.


 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

 Note that Rational Networking--TCP/IP, and, as a result, the Copy
 procedure, requires that the names and TCP/IP addresses of the source and
 destination machines be in the !Machine.Transport_Name_Map file of both
 machines.


 EXAMPLES

 Assume you are on an R1000 called Jazmo, and you want to copy a unit from
 an R1000 named Logo onto Jazmo. The following command accomplishes this,
 creating !Users.Chavez.Tools.Sort on Jazmo:

   Archive.Copy
      (Objects    => "!!Logo!Users.Anderson.Statistics.Tools.Sort",
       Use_Prefix => "!Users.Chavez",
       For_Prefix => "!Users.Anderson.Statistics");

 Assume you want to copy a world from the current R1000 (Jazmo) onto Logo.
 Assume further that you want the copied world to preserve its original
 name. The following command copies the world along with all of its
 contents:

   Archive.Copy (Objects    => "!Project_1.Tools",
                 Use_Prefix => "!!Logo");

 Assume you want to copy the home world for user Doyle from an R1000 called
 Logo onto an R1000 called Eusebius. The following command, entered from a
 third R1000 called Jazmo, accomplishes this:

   Archive.Copy (Objects    => "!!Logo!Users.Doyle",
                 Use_Prefix => "!!Eusebius");

 In this example, the world and its contents are copied under their
 original names. If you have operator capability, the Environment also
 attempts to create a user called Doyle, if such a user does not already
 exist.

 Assume that you want to copy two directories from an R1000 called Logo
 into a different location on the current R1000. The following command
 copies the specified directories from Anderson's home world on Logo,
 creating !Project_1.Tools and !Project.Utils on the current R1000:

   Archive.Copy (Objects    => "!!Logo!Users.Anderson[Tools, Utils]",
                 Use_Prefix => "!Project_1",
                 For_Prefix => "!Users.Anderson");

 Note that if !Project_1 does not already exist on the current R1000, it is
 created as a world.

 See the introduction to this package for more examples.



 @node !Commands.Archive.List

 procedure List (Objects  : String := "?";
                 Options  : String := "R1000";
                 Device   : String := "MACHINE.DEVICES.TAPE_0";
                 Response : String := "<PROFILE>");

 DESCRIPTION

 Produces a listing of the objects that were saved on the specified tape or
 library.

 When listing an archive that was saved in R1000_Long format, you must set
 the Format option to R1000_Long in the Options parameter.

 When listing an archive that was saved to tape, you can use the Unload
 option to specify whether to unload the tape after it is rewound. Leaving
 the tape online is useful for performing a subsequent restore operation.

 By default, the listing is put in the Current_Output file, which typically
 appears as a window on your screen.


 PARAMETERS

 Objects : String := "?";

 Specifies the objects that should appear in the listing. The default value
 (?) causes all of the saved objects to be listed. The Objects parameter
 accepts:

 *  One or more fully qualified pathnames. Multiple pathnames must be
    enclosed in set-notation brackets; for example:

      Objects => "[!Users.Doyle.Tools, !Project_1.Utils]"

 *  An indirect file containing the fully qualified pathnames.

 *  A restricted naming expression that matches one or more fully qualified
    pathnames. Restricted naming expressions permit three of the four
    naming wildcards plus set notation, as shown in Table 8; see also the
    Parameter-Value Conventions tabbed section in the Reference Summary
    (RS).

                  Table 8   Restricted Naming Expressions
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  #   |Matches a single character other than a |
            |      |period. T#### matches Tools.            |
             ----------------------------------------------- 
            |      |                                        |
            |  @   |Matches zero or more characters not     |
            |      |containing a period. !U@.@.Tools matches|
            |      |!Users.Anderson.Tools.                  |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches zero or more name components.   |
            |      |!Users.Anderson? matches !Users.Anderson|
            |      |and everything in it.                   |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Encloses a set of names.                |
            |      |[!Users.Anderson?,!Users.Miyata?]       |
            |      |matches everything in the home worlds of|
            |      |Anderson and Miyata.                    |
             ----------------------------------------------- 
            |      |                                        |
            |  ~   |Indicates that something should not be  |
            |      |matched. [@,~Tools] matches everything  |
            |      |in a library except Tools.              |
             ----------------------------------------------- 



 Options : String := "R1000";

 Specifies options to be used in listing objects. You can specify more than
 one option. For further information about specifying options, see the
 Parameter-Value Conventions tabbed section in the Reference Summary (RS).


 *  Format = literal

    Specifies the format that was used to save the Index and Data files to
    tape. The Format option is ignored if the Device parameter specifies a
    library.

    When objects are saved to tape, one of three formats is specified. This
    same format must be specified when the tape is listed. Thus, when the
    List command's Device parameter specifies a tape, the Format option
    must have one of the following literal values:

    R1000                Lists an archive that required only one tape. More
                         specifically, R1000 format allows you to list from
                         a volume set called *DATA_SHORT* that is
                         formatted in chained ANSI. *DATA_SHORT* consists
                         of a single tape that contains the Data file
                         followed by the Index file.

    R1000_Long           Lists an archive that was saved with the Format
                         option set to R1000_Long. Archives that were saved
                         with R1000_Long format consist of two volume sets.
                         The first volume set, called *DATA_LONG*,
                         consists of one or more tapes that contain the
                         Data file. The second, called *INDEX*, consists of
                         a single tape that contains the Index file.

    Ansi                 Lists an archive from a tape that was made for a
                         non-R1000 machine that accepts ANSI tapes. (If
                         you require this capability, see your Rational
                         technical representative.) Ansi format allows you
                         to list from a volume set with no name that was
                         created using ANSI facilities. This volume set
                         consists of a single tape that contains the Data
                         file followed by the Index file.


 *  Label = string

    Specifies a string, used for identification purposes, that must be
    present on a tape before a listing can be produced from that tape. This
    string (called a label) is not the same as the volume identifier or the
    volume set name; rather, it typically records the tape owner's name,
    the date, and so on. Labels are written to archive tapes by specifying
    the Label option of the Save command.

    The label specified by the Label option of the List command is compared
    to the label, if any, on the tape. The comparison is not
    case-sensitive. If the label does not match (or there is no label on
    the tape), the tape is rejected as if it were the wrong volume.

    The label can be a single text line of arbitrary length. You must
    enclose a label in parentheses if its text contains commas, semicolons,
    or characters used as option delimiters (such as the equals symbol).
    For example, a label containing comma (,) characters is specified as
    "Label=(MONDAY, JUNE 3, 1991)".

    For further information on specifying strings in an Options parameter,
    see the Parameter-Value Conventions tabbed section in the Reference
    Summary (RS).


 *  Nonrecursive

    A Boolean option. When True, lists only the objects that are actually
    named by the Objects parameter. This option overrides default command
    behavior, so that sublibraries and subunits within the named objects
    are not listed unless they are explicitly specified in the Objects
    parameter. This option permits you to list a
    library and a subset of its contents without listing the entire
    library. For example, the following command lists the world
    !Users.Anderson along with only those subobjects whose names begin with
    "Test_":

      Archive.List
               (Objects => "[!Users.Anderson,!Users.Anderson.Test_@]",
                Options => "Nonrecursive");

 *  Unload

    A Boolean option. When True (the default), causes the tape to be
    rewound and unloaded after the operation is complete.

    When False, this option causes the tape to be rewound to the beginning
    and to remain online and available for subsequent requests. This is
    useful when you want to perform a list operation followed by a restore
    operation, or if you want to perform several restore operations in a
    row. Note that, because the tape is rewound, successive save operations
    will overwrite each other.

    When the tape is left online, subsequent requests send a tape-mount
    request
    to the operator's console, which must be answered before the tape can
    be accessed.


 Device : String := "MACHINE.DEVICES.TAPE_0";

 Specifies the name of the device from which the archived objects are to be
 accessed. The default value for Device reads from tape. If the objects
 are saved in a library rather than on tape, you can supply a library name.


 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 Save
 System Management Utilities (SMU), package Tape



 @node !Commands.Archive.Restore

 procedure Restore
                (Objects    : String := "?";
                 Use_Prefix : String := "*";
                 For_Prefix : String := "*";
                 Options    : String := "R1000";
                 Device     : String := "MACHINE.DEVICES.TAPE_0";
                 Response   : String := "<PROFILE>");

 DESCRIPTION

 Reads a tape or library that was created by the Save procedure and
 restores the specified object or objects.

 The tape or library (which may be on another R1000 on the same network) is
 specified by the Device parameter. When restoring an archive that was saved
 in R1000_Long format, you must set the Format option to R1000_Long in the
 Options parameter.

 When restoring from tape, you can use the Unload option to specify whether
 to unload the tape after it is rewound. Leaving the tape online is useful
 for performing subsequent restore operations.

 The Restore procedure:

 *  Restores the saved objects in their original hierarchical structure,
    reconstructing libraries as necessary. Subsystems are reconstructed
    only if needed to restore entire views.

 *  Optionally promotes Ada units to the states they were in when they were
    saved or to any other specified goal state.

 *  Changes the location of objects as specified in the Use_Prefix and
    For_Prefix parameters.

 *  Rebuilds the links for restored worlds and reassociates restored
    libraries with their switch files.

 *  Permits the restorer to change the ACLs of objects restored outside
    subsystems.

 By default, the Restore procedure restores all of the objects named by the
 Objects parameter, including their sublibraries and subunits. You can use
 the Objects parameter to specify a subset of the saved objects;
 furthermore, you can use the Options parameter to filter the specified
 objects according to various criteria. (The relevant options include:
 After, Nonrecursive, New_Objects, Existing_Objects, Updated_Objects,
 Changed_Objects, and Different_Objects.)

 Also by default, restored objects overwrite existing Environment objects
 of the same name, unless the existing objects are frozen, checked in, or
 in the installed or coded state with dependents. You can cause even
 frozen, checked in, or compiled objects to be overwritten by specifying
 the Replace option.


 PARAMETERS

 Objects : String := "?";

 Specifies the objects to be restored from the tape or library. The default
 value (?) causes all of the saved objects to be restored. The Objects
 parameter accepts:

 *  One or more fully qualified pathnames. Multiple pathnames must be
    enclosed in set-notation brackets; for example:

      Objects => "[!Users.Doyle.Tools; !Project_1.Utils]"

 *  An indirect file containing the fully qualified pathnames.

 *  A restricted naming expression that matches one or more fully qualified
    pathnames. Restricted naming expressions permit three of the four
    naming wildcards plus set notation, as shown in Table 9; see also the
    Parameter-Value Conventions tabbed section in the Reference Summary
    (RS).

                  Table 9   Restricted Naming Expressions
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  #   |Matches a single character other than a |
            |      |period. T#### matches Tools.            |
             ----------------------------------------------- 
            |      |                                        |
            |  @   |Matches zero or more characters not     |
            |      |containing a period. !U@.@.Tools matches|
            |      |!Users.Anderson.Tools.                  |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches zero or more name components.   |
            |      |!Users.Anderson? matches !Users.Anderson|
            |      |and everything in it.                   |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Encloses a set of names.                |
            |      |[!Users.Anderson?,!Users.Miyata?]       |
            |      |matches everything in the home worlds of|
            |      |Anderson and Miyata.                    |
             ----------------------------------------------- 
            |      |                                        |
            |  ~   |Indicates that something should not be  |
            |      |matched. [@,~Tools] matches everything  |
            |      |in a library except Tools.              |
             ----------------------------------------------- 



 By default, the procedure copies the specified objects along with any
 objects they contain. You can override this default behavior with options
 such as After, Nonrecursive, New_Objects, Existing_Objects,
 Updated_Objects, Changed_Objects, and Different_Objects.

 If you use set notation or indirect files, it is recommended that you
 separate the individual names with semicolons so that the command will
 quit if unresolvable names are reported. (When commas are used, the
 operation copies what it can and ignores unresolvable names.)


 Use_Prefix : String := "*";

 Specifies all or part of the names under which the archived objects are to
 be restored. Thus, the value of this parameter determines, at least in
 part, where to rebuild the copied objects.

 The default value ("*") causes the archived objects to be restored under
 their original names. This value is useful when restoring objects into
 an identical library structure on another R1000.

 A nondefault Use_Prefix value consists of one or more consecutive name
 components forming a pathname. (A fully qualified pathname is recommended
 because it is more explicit; if a relative pathname is used, it is
 resolved relative to the current library.) When the Use_Prefix parameter
 has a nondefault value, it combines with the original names of the saved
 objects and with the value of the For_Prefix parameter to specify the new
 names for the restored objects.

 In particular, the name for each restored object is derived from its
 original name by inserting the Use_Prefix value in place of the shortest
 portion matched by the For_Prefix value. For example, the following command
 restores an object under the name !Users.Miyata.Tools.Sort. This name is
 derived by taking the original name
 (!Users.Anderson.Statistics.Tools.Sort), removing the portion matched by
 the For_Prefix (!Users.Anderson.Statistics), and putting the string
 specified by Use_Prefix (!Users.Miyata) in its place:

   Archive.Restore
             (Objects    => "!Users.Anderson.Statistics.Tools.Sort",
              Use_Prefix => "!Users.Miyata",
              For_Prefix => "!Users.Anderson.Statistics");

 Thus, the Use_Prefix parameter essentially specifies a fully qualified name
 that replaces part or all of each object's original name, as determined by
 the For_Prefix parameter:

 *  If the For_Prefix value matches the entire original name, the Use_Prefix
    value constitutes the entire name of the restored object.

 *  If the For_Prefix value matches a prefix other than the entire name
    (where a prefix is a set of consecutive name components starting with
    the leftmost component), the Use_Prefix value names a library that is
    to enclose the restored object at some level in the library hierarchy.

 *  If the For_Prefix parameter does not match any prefix of the original
    name, a warning message is generated and the specified object is not
    restored.

 If the For_Prefix value contains wildcards, then both the For_Prefix and the
 Use_Prefix value must account for the entire object, not just a prefix.
 The Use_Prefix value can contain a substitution character corresponding to
 each wildcard. The Use_Prefix parameter accepts only the @ substitution
 character. The @ substitution character expands to the string matched by a
 wildcard in For_Prefix. When you specify a Use_Prefix containing one or more
 @ substitution characters, these characters are mapped, from right to
 left, onto the wildcards in the For_Prefix value. The Environment then
 expands the destination name by replacing each substitution character
 with the corresponding string from For_Prefix. For further information,
 see "Specifying Destination Names" in the introduction to this package.


 For_Prefix : String := "*";

 Combines with the Use_Prefix parameter to specify the names under which the
 archived objects will be restored. The For_Prefix parameter determines how
 much of each object's original name is to be replaced by the Use_Prefix
 value to produce each new name.

 The value of the For_Prefix parameter is either the default special value
 "*" (discussed below) or a naming expression that matches a prefix of the
 restored objects' original names. A prefix is one or more consecutive
 name components starting with the name's leftmost component. For example,
 the name !Users.Anderson.Statistics.Tools has the following possible
 prefixes: !Users, !Users.Anderson, !Users.Anderson.Statistics, and
 !Users.Anderson.Statistics.Tools. Note that the entire name can be
 specified as a prefix.

 Each name used for restoration is derived from an original name by
 replacing the shortest prefix matched by the For_Prefix parameter with the
 value of the Use_Prefix parameter (see the Use_Prefix parameter for an
 example):

 *  If the For_Prefix value matches the entire original name, the Use_Prefix
    value becomes the object's new name.

 *  If the For_Prefix value matches a prefix other than the entire name, the
    Use_Prefix value replaces just that prefix.

 *  If the For_Prefix value does not match any of the original name, a
    warning message is generated and the specified objects are not copied.

 Note that the For_Prefix parameter is ignored when Use_Prefix has the
 default value "*", because the default Use_Prefix value causes objects to
 be restored under their original names.

 The default value ("*") of the For_Prefix parameter allows you to restore
 objects under different names without knowing the objects' original names.
 The default For_Prefix value causes the Restore command to retrieve the
 prefix that was saved with the archived objects and to use this prefix in
 the derivation of new object names. The prefix that is retrieved is the
 value that was specified for the Prefix option of the Save command. Note
 that if no Prefix value was explicitly specified during the save, that
 option defaults to a naming expression that matches all of the archived
 objects' original names.

 You can restore multiple objects under different names by matching
 portions of the original names with wildcards or other restricted naming
 expressions in the For_Prefix parameter. When the For_Prefix contains
 wildcards, then both the For_Prefix and the Use_Prefix value must account
 for the entire object, not just a prefix. The Use_Prefix parameter can
 match each wildcard with a substitution character. It is recommended
 that you do not mix set notation (for example, [a,b,c]) with substitution
 characters in the For_Prefix and Use_Prefix parameters. For further in-
 formation and a list of accepted wildcard characters, see "Specifying
 Destination Names" in the introduction to this package.

 It is recommended that you use the Effort_Only option to test combinations
 of For_Prefix and Use_Prefix values that contain restricted naming
 expressions to ensure that they match.


 Options : String := "R1000";

 Specifies the options to be used during the restore operation. The Options
 parameter allows you to specify, among other things, a particular subset
 of objects to restore, the compilation state of the restored objects, and
 the access-control lists (ACLs) for the restored objects. You can specify
 more than one option. For further information about specifying options,
 see the Parameter-Value Conventions tabbed section in the Reference
 Summary (RS).

 The following list summarizes the options accepted by the Archive.Restore
 command. Descriptions of each option are given after this list:

 Become_Owner           Cdb                       Changed_Objects
 Code                   Compatibility_Database    Default_Acl
 Different_Objects      Effort_Only               Existing_Objects
 Format                 Goal_State                Ignore_Cdb
 Label                  Links                     New_Objects
 Nonrecursive           Object_Acl                Primary
 Promote                Remake                    Replace
 Require_Parents        Revert_Cdb                Trailing_Blanks
 Uncontrol              Updated_Objects           Verbose
 Volume                 World_Acl


 *  Become_Owner

    A Boolean option. When True, causes the ACLs of all restored worlds to
    be modified so that the restoring username is given owner access to the
    restored worlds. This option has no effect on restored views.

    If a group specified in the ACL for an object does not exist on the
    machine onto which the object is restored, the ACL entry for that group
    is removed from the object's ACL.


 *  Cdb [= subsystems]

    Abbreviated form of the Compatibility_Database option.


 *  Changed_Objects

    A Boolean option. When True, causes new and updated objects to be
    restored. This is equivalent to specifying both the New_Objects and
    Updated_Objects options.


 *  Code [= loaded main programs]

    Restores only the code segments for the specified loaded main programs,
    when these programs will overwrite existing ones. Loaded main programs
    consist of an Ada-unit specification and a set of code segments. By
    default, the Ada-unit specification is restored in the coded state.
    However, if a restored loaded main program overwrites an existing one,
    the specification of the existing program is demoted, along with any
    units that depend on it. Specifying the Code option prevents such
    demotion by causing only the code segments to be restored.

    This option can be used only if an existing loaded main program will be
    overwritten and if the specification of the restored program has the
    same parameter profile as the specification of the overwritten program
    (they need not have the same name). No segments are restored unless
    both of these conditions are met.

    If the option name is specified by itself (that is, if the loaded main
    programs portion of the option is omitted), then the command restores
    the code segments of all loaded main programs specified by the Objects
    parameter. An error is generated if the Objects parameter specifies no
    loaded main programs. For example, the following command restores
    just the code segments from a program called
    !Users.Anderson.Search_For, overwriting the code segments of a loaded
    main program with the same name on the current R1000:

      Archive.Restore (Objects => "!Users.Anderson.Search_For",
                       Options => "Code");

    To restore other objects along with the code segments from one or more
    loaded main programs, you can specify the names of the loaded main
    programs as the value to the Code option:

      Archive.Restore (Objects => "other objects",
                       Options => "Code=loaded main programs");

    In this case, other objects specifies objects that are probably disjoint
    from loaded main programs.


 *  Compatibility_Database [= subsystems]

    Specifies that the command is to restore only the compatibility database
    (CDB) for each of the specified subsystems, without restoring the
    subsystems themselves. This option is useful for updating the CDB in
    a secondary subsystem before propagating incremental changes from a
    primary subsystem. Note that restoring with this option is an
    alternative to using the Cmvc_Maintenance.Update_Cdb command. (For
    further information about primary and secondary subsystems and their
    compatibility databases, see the Project Management (PM) book.)

    The Compatibility_Database option can be abbreviated as Cdb. If the
    option name is specified by itself (that is, if the subsystems portion
    of the option is omitted), then the command restores the CDBs of all
    subsystems specified by the Objects parameter. An error is generated if
    the Objects parameter specifies no subsystems. For example, the
    following command restores the CDB from a subsystem called
    !Projects.Mail_Utilities into a subsystem with the same name on the
    current R1000:

      Archive.Restore (Objects => "!Projects.Mail_Utilities",
                       Options => "Cdb"); 

    To restore other objects along with the CDB from one or more
    subsystems, you can specify the subsystem names as the value to the Cdb
    option:

      Archive.Restore (Objects => "other objects",
                       Options => "Cdb=subsystems");

    In this case, other objects specifies objects that are probably disjoint
    from subsystems.


 *  Default_Acl = new acl

    Specifies the new default access-control list (ACL) to be given to each
    restored world. A world's default ACL is the ACL that is assigned to
    new files and Ada units created in that world. This option has no effect
    on restored views.

    The value for this option can be a specific ACL. The specified ACL must
    follow the syntax rules for ACLs (see the introduction to package
    Access_List in this book). For example, the following Options parameter
    gives John (and only John) complete default access to all worlds
    resulting from the restore operation:

      Options => "Default_Acl=(John=>RW)"

    The Default_Acl option also accepts any one of the literal values
    listed below. Each of these values causes some existing default ACL to
    be assigned to the restored worlds:

    Archived           Assigns each restored world the default ACL that was
                       saved with it.

    Inherit            Assigns each restored world a default ACL according
                       to the standard inheritance rules for new worlds.
                       That is, a restored world inherits its default ACL
                       from the world into which it is restored.

    Retain             Assigns each restored world the default ACL of the
                       world it has overwritten. If no world was
                       overwritten, the restored world is assigned the
                       default ACL that was saved with it.

    If you omit the Default_Acl option entirely, the Restore command
    behaves as if you specified the Retain value.

    Note that if a group specified in the ACL for an object does not exist
    on the machine onto which the object is restored, the ACL entry for
    that group is removed from the object's ACL.


 *  Different_Objects

    A Boolean option. When True, allows objects to be restored only if they
    will overwrite existing objects and if they have a different update
    time (whether earlier or later) than the objects they will overwrite.
    Specifying this option prevents objects from being overwritten by
    objects with the same update time.


 *  Effort_Only

    A Boolean option. When True, displays a list of the objects to be
    restored without actually restoring them. This option is useful for
    testing the effect of a particular combination of values for the
    Objects, Use_Prefix, For_Prefix, and Options parameters.


 *  Existing_Objects

    A Boolean option. When True, allows objects to be restored only if they
    will overwrite existing objects, regardless of their update times.
    Specifying this option prevents new objects from being restored.


 *  Format = literal

    Specifies the format that was used to save the Index and Data files to
    tape. The Format option is ignored if the Device parameter specifies a
    library.

    When objects are saved to tape, one of three formats is specified. This
    same format must be specified during the restore operation. Thus, when
    the Restore command's Device parameter specifies a tape, the Format
    option must have one of the following literal values:

    R1000                Restores an archive that required only one tape.
                         More specifically, R1000 format restores from a
                         volume set called *DATA_SHORT* that is formatted
                         in chained ANSI. *DATA_SHORT* consists of a single
                         tape that contains the Data file followed by the
                         Index file.

    R1000_Long           Restores an archive that was saved with the Format
                         option set to R1000_Long. Archives that were saved
                         with R1000_Long format consist of two volume sets.
                         The first volume set, called *DATA_LONG*,
                         consists of one or more tapes that contain the
                         Data file. The second, called *INDEX*, consists of
                         a single tape that contains the Index file.

    Ansi                 Restores an archive from a tape that was made for
                         a non-R1000 machine that accepts ANSI tapes. (If
                         you require this capability, see your Rational
                         technical representative.) Ansi format restores
                         from a volume set with no name that was created
                         using ANSI facilities. This volume set consists of
                         a single tape that contains the Data file followed
                         by the Index file.


 *  Goal_State = Ada unit state

    Attempts to promote all of the restored Ada units to the specified
    compilation state. Any one of the following states can be specified as
    values to this option: Archived, Source, Installed, or Coded.

    This option overrides the default command behavior, which is to leave
    the restored Ada units in the source state. The Promote and Remake
    options are alternatives to the Goal_State option; only one of these
    three options can be specified.

    The restored Ada units can be promoted to the installed or coded state
    only if the necessary links exist where the units are restored. To
    ensure the existence
    of the proper links, you can restore the world enclosing the desired
    Ada units along with the Ada units themselves; the links are restored
    along with the world. Note, however, that the restored links can be
    rebuilt only if the units to which they refer exist and have the same
    source name. (That is, objects that depend on missing units cannot be
    promoted.)


 *  Ignore_Cdb

    A Boolean option. When True, restores the specified views or units from
    views without also restoring the enclosing subsystem's compatibility
    database (CDB). Ignoring the CDB saves time when source code is
    restored into an unrelated subsystem (a subsystem that is not
    associated as a secondary). Restoring units between unrelated
    subsystems is typically done when units from one subsystem are to serve
    as templates for developing units in the other subsystem.

    The Ignore_Cdb option serves only to optimize the restore operation so
    that no time is spent reading the CDB from the archived subsystem. Note
    that no harm is done if this option is omitted, however, because a
    restored CDB can never actually overwrite the CDB from an unrelated
    subsystem.


 *  Label = string

    Specifies a string, used for identification purposes, that must be
    present on a tape before objects can be restored from that tape. This
    string (called a label ) is not the same as the volume identifier or the
    volume set name; rather, it typically records the tape owner's name,
    the date, and so on. Labels are written to archive tapes by
    specifying the Label option of the Save command.

    The label specified by the Label option of the Restore command is
    compared to the label, if any, on the tape. The comparison is not
    case-sensitive. If the label does not match (or there is no label on
    the tape), the tape is rejected as if it were the wrong volume.

    The label can be a single text line of arbitrary length. You must
    enclose a label in parentheses if its text contains commas, semicolons,
    or characters used as option delimiters (such as the equals symbol).
    For example, a label containing comma (,) characters is specified as
    "Label=(MONDAY, JUNE 3, 1991)".

    For further information on specifying strings in an Options parameter,
    see the Parameter-Value Conventions tabbed section in the Reference
    Summary (RS).


 *  Links [= worlds]

    Specifies that the command is to restore only the links for each of the
    specified worlds, without restoring the worlds themselves. Archiving
    with the Links option is a more powerful alternative to using the
    Links.Copy command, which copies links among worlds on the same R1000.
    In contrast, saving and then restoring with the Links option allows you
    to copy links between R1000s.

    If the option name is specified by itself (that is, if the worlds
    portion of the option is omitted), the command restores the links of
    all worlds specified by the Objects parameter. An error is generated if
    the Objects parameter specifies no worlds. For example, the following
    command restores the links from a world called
    !Users.Anderson.Statistics to a world with the same name on the current
    R1000:

      Archive.Restore (Objects => "!Users.Anderson.Statistics",
                       Options => "Links"); 

    To restore other objects along with the links from one or more worlds,
    you can specify the world names as the value to the Links option:

      Archive.Restore (Objects => "other objects",
                       Options => "Links=worlds");

    In this case, other objects specifies objects that are probably disjoint
    from worlds.


 *  New_Objects

    A Boolean option. When True, allows only new objects to be restored,
    where new objects are objects that will not overwrite existing objects.
    Specifying this option prevents existing objects from being
    overwritten, while permitting objects to be restored under new names or
    in new locations.


 *  Nonrecursive

    A Boolean option. When True, restores only the objects that are
    actually named by the Objects parameter. This option overrides default
    command behavior, so that sublibraries and subunits within the named
    objects are not restored unless they are explicitly specified in the
    Objects parameter. The Nonrecursive option allows you to restore
    libraries and their links and switch associations without automatically
    restoring the objects in those libraries as well. Furthermore, this
    option permits you to restore a library and a subset of its contents
    without restoring the entire library. For example, the following
    command restores the world !Users.Anderson along with only those
    subobjects whose names begin with Test_:

      Archive.Restore
               (Objects => "[!Users.Anderson,!Users.Anderson.Test_@]",
                Options => "Nonrecursive");

    To better understand the effect of the Nonrecursive option, compare the
    preceding command with the following:

      Archive.Restore (Objects => "!Users.Anderson.Test_@");

    Like the first command, this second command restores the objects in
    !Users.Anderson whose names begin with Test_. The difference is that
    the first command also restores the library !Users.Anderson along with
    its links and switch-file associations, whereas the second command does
    not. Instead, the second command merely creates a library named
    !Users.Anderson if such a library does not already exist on the
    destination R1000; no links or switch-file associations are restored
    from the original library.


 *  Object_Acl = new acl

    Specifies the new access-control list (ACL) to be given to each of the
    restored files and Ada units. An object's ACL determines which users can
    view or modify that object. This option has no effect on objects
    restored into views.

    The value for this option can be a specific ACL. The specified ACL must
    follow the syntax rules for ACLs (see the introduction to package
    Access_List in this book). For example, the following Options parameter
    gives John (and only John) complete access to all the restored files and
    Ada units:

      Options => "Object_Acl=(John=>RW)"

    The Object_Acl option also accepts any one of the literal values listed
    below. Each of these values causes some existing ACL to be assigned to
    the restored files and Ada units:

    Archived           Assigns each restored file or Ada unit the default
                       ACL with which it was saved.

    Inherit            Assigns each restored file or Ada unit an ACL
                       according to the standard inheritance rules for
                       new objects. That is, each object gets its ACL from
                       the default ACL of the world into which it was
                       restored.

    Retain             Assigns each restored file or Ada unit the default
                       ACL of the object it has overwritten. If no object
                       was overwritten, the restored object is assigned the
                       ACL with which it was saved.

    If you omit the Object_Acl option entirely, the Restore command behaves
    as if you specified the Retain value.

    Note that if a group specified in the ACL for an object does not exist
    on the machine onto which the object is restored, the ACL entry for
    that group is removed from the object's ACL.


 *  Primary

    A Boolean option. When True, causes the specified subsystems to be
    restored as primary subsystems rather than as secondary subsystems.
    Primary subsystems permit ongoing development because their
    compatibility databases (CDBs) can be updated. The Primary option is
    useful when you are restoring a subsystem from an archive that was used
    as a backup. (Unless the Primary option is specified, the subsystem
    will be restored as a secondary, even if it was originally a primary.)

    The Primary option is also useful when you are using the Restore
    command in the process of rehosting a primary subsystem. Note that
    after the subsystem has been restored with the Primary option on the
    new host, you must freeze, delete, or convert the original primary
    subsystem into a secondary subsystem using the
    Cmvc_Maintenance.Make_Secondary command. This option is subject to CDB
    capability, as described in the introduction to package
    Cmvc_Access_Control. For further information on subsystems and CDBs,
    see the Project Management (PM) book.


 *  Promote

    A Boolean option. When True, attempts to promote restored Ada units to
    their original states (installed or coded). This option overrides the
    default command behavior, which is to leave the restored Ada units in
    the source state. The Remake and Goal_State options are alternatives
    to the Promote option; only one of these three options can be specified.

    The restored Ada units can be promoted only if the necessary links
    exist in the destination context. To ensure the existence of the proper
    links, you can restore the world enclosing the desired Ada units along
    with the units themselves; the links are restored along with the world.
    Note, however, that the restored links can be rebuilt only if units to
    which they refer exist and have the same source name. (That is, objects
    that depend on missing units cannot be promoted.)


 *  Remake [= No_Mains]

    Attempts to promote all of the restored Ada units to their original
    states, along with any dependent units that were demoted by the Replace
    option. That is, this option is like the Promote option, except that it
    also "repairs" the compilation effects of the Replace option. The
    Remake option overrides the default command behavior, which is to
    leave the restored Ada units in the source state. The Goal_State and
    Promote options are alternatives to the Remake option; only one of
    these three options can be specified.

    If the option name is specified by itself (that is, the literal value
    No_Mains is omitted), an attempt is made to remake all of the specified
    Ada units. If the literal value No_Mains is specified, then no attempt
    is made to remake dependent main programs.

    The restored Ada units can be promoted only if the necessary links
    exist in the destination context. To ensure the existence of the proper
    links, you can restore the world enclosing the desired Ada units along
    with the units themselves; the links are restored along with the world.
    Note, however, that the restored links can be rebuilt only if units to
    which they refer exist and have the same source name. (That is, objects
    that depend on missing units cannot be promoted.)


 *  Replace

    A Boolean option. When True, permits existing objects to be overwritten
    even if they are frozen, compiled, and/or controlled and checked in. In
    particular, this option performs the following operations as necessary:

    -  Unfreezes frozen objects for the duration of the operation. This
       includes any parent libraries into which objects are being restored.
       The unfrozen objects are automatically frozen again at the end of
       the operation.

    -  Demotes installed or coded Ada units to source, along with their
       clients.
       (To do this, the option invokes the Compilation.Demote procedure
       with "<ALL_WORLDS>" specified in the Limit parameter.) The demoted
       units are repromoted only if the Remake option is also specified.

    -  Attempts to check out any controlled objects that are not already
       checked out in the destination view. These objects are automatically
       checked in again at
       the end of the operation. Note that the checkout attempt will fail
       if the objects are already checked out in another view. In this
       case, the objects in question are not overwritten. To guarantee that
       controlled objects are overwritten, you can specify the Uncontrol
       option in addition to the Replace option; however, uncontrolling the
       objects will cause their change history to be lost.

    This option is subject to CMVC access control.


 *  Require_Parents

    A Boolean option. When True, prevents objects from being restored
    unless the required destination context already exists. This option
    overrides the default command behavior, which is to create any missing
    hierarchical structure (for example, nested libraries) that is required
    to restore the objects under the desired names.


 *  Revert_Cdb

    A Boolean option. When True, permits a less recently updated version of
    a compatibility database (CDB) to overwrite a more recently updated
    version. This option overrides the default behavior of the Restore
    command (by default, a CDB can be overwritten only by a more recently
    updated CDB). You should use this option only under supervision of
    Rational support personnel; if used incorrectly, this option can
    result in loss of compatibility among the spec and load views in a
    subsystem. This option is subject to CDB capability, as described in
    the introduction to package Cmvc_Access_Control. For further
    information on subsystems and CDBs, see the Project Management (PM)
    book.


 *  Trailing_Blanks = integer

    Preserves some or all of the user-inserted line breaks in restored Ada
    units. Line breaks are preserved only in lines that end in more than
    the specified number of trailing blank characters. Otherwise, the
    restored units are reformatted in the destination context and line
    breaks are inserted by the pretty-printer there.


 *  Uncontrol

    A Boolean option. When True, permits controlled objects to be
    overwritten by making them uncontrolled in the destination view for the
    duration of the restore operation. (The overwritten objects are
    automatically made controlled again at the end of the operation.) This
    option has no effect unless the Replace option is also specified.

    Specifying the Uncontrol option guarantees that controlled objects are
    overwritten. However, making the objects uncontrolled severs them
    from the objects to which they are joined. Furthermore, when these
    objects are recontrolled, they are given new reservation tokens, so
    that their change history is effectively lost. Note that when the
    Replace option is used without the Uncontrol option, an attempt is made
    to check out the objects in question, thereby preventing loss of
    history.

    The Uncontrol option is subject to CMVC access control.


 *  Unload

    A Boolean option. When True (the default), causes the tape to be
    rewound and unloaded after the operation is complete.

    When False, this option causes the tape to be rewound to the beginning
    and to remain online and available for subsequent requests. This is
    useful when you want to perform a list operation followed by a restore
    operation, or if you want to perform several restore operations in a
    row. Note that, because the tape is rewound, successive save operations
    will overwrite each other.

    When the tape is left online, subsequent requests send a tape-mount
    request
    to the operator's console, which must be answered before the tape can
    be accessed.


 *  Updated_Objects

    A Boolean option. When True, allows only updated objects to be
    restored. An object is considered updated if it will overwrite an
    existing object and if it has been modified more recently than the
    object it will overwrite. This option is especially useful when there
    is parallel development on multiple R1000s and you need to copy updated
    objects from one R1000 to another.


 *  Verbose

    A Boolean option. When True, specifies that extra log messages are to be
    generated describing more fully the steps of the restore operation.


 *  Volume = volume id

    Specifies the disk volume on which to create restored worlds. Each disk
    volume is identified by an integer between 1 and 31; for example, a
    four-disk system has disks 1, 2, 3, and 4. Omitting this option is
    equivalent to specifying the value 0, which instructs the operation to
    pick the disk volume with the most free space.


 *  World_Acl = new acl

    Specifies the new access-control list (ACL) to be given to each restored
    world. A world's ACL determines which users can view, create objects
    in, delete, or change the ACLs of objects in that world. This option
    has no effect on restored views.

    The value for this option can be a specific ACL. The specified ACL must
    follow the syntax rules for ACLs (see the introduction to package
    Access_List in this book). For example, the following Options parameter
    gives John (and only John) complete access to all the worlds resulting
    from the restore operation:

      Options => "World_Acl=(John=>RCOD)"

    The World_Acl option also accepts any one of the literal values listed
    below. Each of these values causes some existing ACL to be assigned to
    the restored worlds:

    Archived           Assigns each restored world the default ACL with
                       which it was saved.

    Inherit            Assigns each restored world an ACL according to the
                       standard inheritance rules for new worlds. That
                       is, a restored world inherits its ACL from the world
                       into which it was restored.

    Retain             Assigns each restored world the ACL of the world it
                       has overwritten. If no world was overwritten, the
                       restored world is assigned the ACL with which it was
                       saved.

    If you omit the World_Acl option entirely, the Restore command behaves
    as if you specified the Retain value.

    Note that if a group specified in the ACL for an object does not exist
    on the machine onto which the object is restored, the ACL entry for
    that group is removed from the object's ACL.


 Device : String := "MACHINE.DEVICES.TAPE_0";


 Specifies the name of the device from which the Data and Index files are to
 be read. The default is to read from tape. If you supply a library name,
 the objects are read from the Data and Index files in that library.

 This parameter can be used to specify remote devices, such as a library or
 a tape drive on another R1000. For example, assume you are logged into an
 R1000 called M_1, which is the machine onto which objects are to be
 restored. Assume further that the tape drive you want to use is on an
 R1000 called M_2, which is connected to M_1 over the network. Then you can
 use the following Device parameter to specify the desired drive:

   Device => "!!M_2!MACHINE.DEVICES.TAPE_0"

 Note that if you insert the remote R1000 name in front of the default
 Device value (MACHINE.DEVICES.TAPE_0), you must also insert an exclamation
 mark (!) between the R1000 name and that value.

 If there is more than one tape drive, a drive other Tape_0 can be specified
 (for example, !Machine.Devices.Tape_1). However, specifying a drive
 through this parameter merely serves to suggest a particular tape drive
 to the operator. The actual tape drive to be used is determined by the
 operator's response to the tape-mount request on the system console. Note
 that if no device exists with the specified logical name, a library is
 created with that name.


 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 have saved an object called !Project_1.Utils.Counter and
 now want to restore it under the same name. The following command
 accomplishes this. Note that the For_Prefix and Use_Prefix parameters have
 default values:

   Archive.Restore (Objects => "!Project_1.Utils.Counter");

 Assume that you want to restore all of the archived error log files from
 April 1991 and that you want these files to be restored in a library called
 !Users.Operator.Error_Logs. The following command accomplishes this by
 substituting the Use_Prefix value (!Users.Operator) for the For_Prefix
 value (!Machine) in the original names of the archived objects. Note that
 if !Users.Operator.Error_Logs does not already exist, it will be created:

   Archive.Restore (Objects    => "!Machine.Error_Logs.Log_91_04_@",
                    Use_Prefix => "!Users.Operator",
                    For_Prefix => "!Machine");

 Assume that you have saved two objects, !Users.Doyle.Tools and
 !Project_1.Utils, and that you want to restore these objects into a single
 library--namely, !Users.Anderson. The restored objects are to keep the
 same simple names. The following command accomplishes this, restoring
 the objects as !Users.Anderson.Tools and !Users.Anderson.Utils. Note
 that the For_Prefix uses set notation to match a prefix in each of the names
 listed by the Objects parameter:

   Archive.Restore
              (Objects    => "[!Users.Doyle.Tools,!Project_1.Utils]",
               Use_Prefix => "!Users.Anderson",
               For_Prefix => "[!Users.Doyle,!Project_1]");

 Assume that you want to restore the contents of the world
 !Users.Doyle.Tools into the world !Users.Anderson. However, you want only
 new objects to be restored (objects that !Users.Anderson does not already
 contain). The following command accomplishes this:

   Archive.Restore (Objects    => "!Users.Doyle.Tools.@",
                    Use_Prefix => "!Users.Anderson",
                    For_Prefix => "!Users.Doyle.Tools",
                    Options    => "R1000, New_Objects");

 See the introduction to this package for more examples.


 REFERENCES

 procedure Save



 @node !Commands.Archive.Save

 procedure Save (Objects  : String := "<IMAGE>";
                 Options  : String := "R1000";
                 Device   : String := "MACHINE.DEVICES.TAPE_0";
                 Response : String := "<PROFILE>");

 DESCRIPTION

 Writes zero or more objects specified by the Objects and the Options
 parameters onto tape or into a library.

 The tape or library (which may be on another R1000 on the same network) is
 specified by the Device parameter.

 When saving onto a tape:

 *  You can specify the Starting_At option to delay the starting time of
    the save operation.

 *  You can set the Format option to R1000_Long in the Options parameter to
    cause the Index file to be saved to a separate volume set. This will
    simplify the restore operation if the amount of data you are saving is
    very large (for example, if it might exceed the capacity of a single
    tape).

 *  You can use the Unload option to determine whether to unload the tape
    after it is rewound. Leaving the tape online is useful for performing a
    subsequent list operation.

 The Save procedure:

 *  Preserves the library structure among multiple objects and records the
    unit state of Ada units.

 *  Saves objects recursively unless otherwise specified (see the Options
    parameter, below). That is, by default, saving a library saves its
    subobjects as well (including sublibraries and their contents).
    Similarly, saving an Ada unit saves any of its subunits, too.

 *  Saves the links associated with worlds and saves the name of the switch
    file associated with each archived library. However, the switch files
    themselves are saved only if specified.

 The Save procedure writes all objects into a single file called Data. A file
 called Index is also created, which describes the name of each object in
 the Data file, the size of the object, and its unit state if it is an Ada
 unit. The Restore procedure uses the Index file to rebuild objects and
 place them in the appropriate states.


 PARAMETERS

 Objects : String := "<IMAGE>";

 Specifies one or more objects to be saved. These objects can include
 worlds, directories, Ada units, text files, data files, switch files,
 activities, subsystems, subsystem views, and user binary files.

 By default, the current image is copied, unless there is a selection in
 that image, in which case the selected object is copied. The parameter
 accepts any naming expression; multiple objects can be specified using
 wildcards, context characters, set notation, indirect files, and
 attributes. If you use set notation or indirect files, it is recommended
 that you separate the individual names with semicolons so that the command
 will quit if unresolvable names are reported. (When commas are used, the
 operation saves what it can and ignores unresolvable names.) For further
 information, see the Parameter-Value Conventions tabbed section in the
 Reference Summary (RS).

 By default, the procedure saves all the specified objects and the objects
 they contain (you can override this default behavior with the
 Nonrecursive option).


 Options : String := "R1000";

 Specifies the options to be used during the save operation. The Options
 parameter allows you to specify, among other things, a particular subset
 of objects to save and various tape-related information. You can specify
 more than one option. For further information about specifying options,
 see the Parameter-Value Conventions tabbed section in the Reference
 Summary (RS).)

 The following list summarizes the options accepted by the Archive.Save
 command. Descriptions of each option are given after this list:

 After                           Cdb        Code
 Compatibility_Database          Delta1     Effort_Only
 Format                          Ignore_Cdb Label
 Links                           Nonrecursive Prefix


 *  After = time

    Saves only objects that have been changed more recently than the
    specified time, which can be a date, a time of day, or both, and can be
    written in any of the styles defined by the
    !Tools.Time_Utilities.Date_Format type and the !Tools-
    .Time_Utilities.Time_Format type. For example, specifying the following
    value for the Options parameter saves only those objects named by
    Objects that were updated after June 11, 1991, at noon:

      Options => "After=(06/11/91 12:00)"

 *  Cdb [= subsystems]

    Abbreviated form of the Compatibility_Database option.


 *  Code [= loaded main programs]

    Saves only the code segments for the specified loaded main programs,
    when these programs will overwrite existing ones. Loaded main programs
    consist of an Ada-unit specification and a set of code segments. By
    default, the Ada-unit specification is saved (and later restored) in the
    coded state. However, if a saved loaded main program will be restored
    so that it overwrites an existing one, the specification of the existing
    program is demoted, along with any units that depend on it.
    Specifying the Code option prevents such demotion by causing only the
    code segments to be saved.

    If this option is specified during the save operation, it need not be
    specified again during the restore operation.

    If the option name is specified by itself (that is, if the loaded main
    programs portion of the option is omitted), then the command saves the
    code segments of all loaded main programs specified by the Objects
    parameter. An error is generated if the Objects parameter specifies no
    loaded main programs. For example,
    the following command saves just the code segments from a program
    called !Users.Anderson.Search_For:

      Archive.Save (Objects => "!Users.Anderson.Search_For",
                    Options => "Code");

    To save other objects along with the code segments from one or more
    loaded main programs, you can specify the names of the loaded main
    programs as the value to the Code option:

      Archive.Save (Objects => "other objects",
                    Options => "Code=loaded main programs");

    In this case, other objects specifies objects that are probably disjoint
    from loaded main programs.


 *  Compatibility_Database [= subsystems]

    Specifies that the command is to save only the compatibility database
    (CDB) for each of the specified subsystems, without saving the
    subsystems themselves. This option is useful for updating the CDB in a
    secondary subsystem before propagating incremental changes from a
    primary subsystem. Note that saving with this option is an alternative
    to using the Cmvc_Maintenance.Update_Cdb command. (For further
    information about primary and secondary subsystems and their
    compatibility databases, see the Project Management (PM) book.)

    The Compatibility_Database option can be abbreviated as Cdb. If the
    option name is specified by itself (that is, if the subsystems portion
    of the option is omitted), then the command saves the CDBs of all
    subsystems specified by the Objects parameter. An error is generated if
    the Objects parameter specifies no subsystems. For example, the
    following command saves the CDB from a subsystem called
    !Projects.Mail_Utilities:

      Archive.Save (Objects => "!Projects.Mail_Utilities",
                    Options => "Cdb");

    To save other objects along with the CDB from one or more subsystems,
    you can specify the subsystem names as the value to the Cdb option:

      Archive.Save (Objects => "other objects",
                    Options => "Cdb=subsystems");

    In this case, other objects specifies objects that are probably disjoint
    from subsystems.


 *  Delta1

    A Boolean option. When True, writes a tape that can be restored on an
    R1000 that is still running the "Delta1" (D_10_20_0) release of the
    Environment. Setting this option to True is necessary only if the tape
    will contain loaded main programs or code views. Because Environment
    releases are upward-compatible, a tape made with this option can also
    be restored on R1000s with later Environment releases. This option is
    useful at customer sites with multiple R1000s that are not all at the
    same release level.
                                                                           

 *  Effort_Only

    A Boolean option. When True, displays a list of the objects to be saved
    without actually saving them. This option is useful for testing the
    effect of a particular combination of values for the Objects and
    Options parameters.


 *  Format = literal

    Specifies one of three formats for writing the Index and Data files on a
    tape. The Format parameter is ignored if the Device parameter specifies
    a library. When the Device parameter specifies a tape, the Format option
    must have one of the following literal values:

    R1000                Writes the archive onto a single tape. More
                         specifically, R1000 format produces a volume set
                         called *DATA_SHORT* that is formatted in chained
                         ANSI. *DATA_SHORT* consists of a single tape that
                         contains the Data file followed by the Index file.

    R1000_Long           Writes the archive onto two volume sets, both
                         formatted in chained ANSI. The first, called
                         *DATA_LONG*, consists of one or more tapes that
                         contain the Data file. The second, called *INDEX*,
                         consists of a single tape that contains the Index
                         file. Putting the Index file on a separate volume
                         set allows the subsequent restore operation to
                         consult this file directly, without having to scan
                         over the entire Data file first.

    Ansi                 Writes the archive to tape for use on non-R1000
                         machines that accept ANSI tapes. (If you require
                         this capability, see your Rational technical
                         representative.) When Ansi format is specified, the
                         Save command writes the data into a temporary file
                         and then writes the Data file followed by the Index
                         file onto a single tape using ANSI tape facilities.
                         The resulting volume set has no name.


 *  Ignore_Cdb

    A Boolean option. When True, saves the specified views or units from
    views without also saving the enclosing subsystem's compatibility
    database (CDB). Ignoring the CDB saves time when source code is to be
    archived between unrelated subsystems (subsystems that are not
    associated as primaries and secondaries). Copying units between
    unrelated subsystems is typically done when units from one subsystem
    are to serve as templates for developing units in the other subsystem.
    Note that the Ignore_Cdb option serves only to optimize the save
    operation so that no time is spent processing the CDB from the source
    subsystem.


 *  Label = string

    Specifies the string, used for identification purposes, to be written
    onto the tape in front of the Index file. This label is not the same as
    the volume identifier or the volume set name; rather, it is typically
    used to record the tape owner's name, the date, and so on. The Restore
    procedure can be requested to verify the label on the tape. If the
    label does not match, the tape is rejected as if it were the wrong
    volume. (Note that the verification is not case-sensitive.)

    The label can be a single text line of arbitrary length. You must
    enclose a label in parentheses if its text contains commas, semicolons,
    or characters used as option delimiters (such as the equals symbol).
    For example, a label containing comma (,) characters is specified as
    "Label=(MONDAY, JUNE 3, 1991)".

    For further information on specifying strings in an Options parameter,
    see the Parameter-Value Conventions tabbed section in the Reference
    Summary (RS).


 *  Links [= worlds]

    Specifies that the command is to save only the links for each of the
    specified worlds, without saving the worlds themselves. Saving and
    restoring with the Links option is a more powerful alternative to using
    the Links.Copy command, which copies links among worlds on the same
    R1000. In contrast, archiving with the Links option allows you to copy
    links between R1000s.

    If the option name is specified by itself (that is, if the worlds
    portion of the option is omitted), then the command saves the links
    of all the worlds specified by the Objects parameter. An error is
    generated if the Objects parameter specifies no worlds. For example, the
    following command saves the links from a world called
    !Users.Anderson.Statistics:

      Archive.Save (Objects => "!Users.Anderson.Statistics",
                    Options => "Links");

    To save other objects along with the links from one or more worlds, you
    can specify the world names as the value to the Links option:

      Archive.Save (Objects => "other objects",
                    Options => "Links=worlds");

    In this case, other objects specifies objects that are probably disjoint
    from worlds.


 *  Nonrecursive

    A Boolean option. When True, saves only the objects that are actually
    named by the Objects parameter. This option overrides default command
    behavior, so that sublibraries and subunits within the named objects
    are not copied unless they are explicitly specified in the Objects
    parameter. The Nonrecursive option allows you to save libraries and
    their links and switch associations without automatically saving the
    objects in those libraries as well. Furthermore, this option permits
    you to save a library and a subset of its contents without saving the
    entire library. For example, the following command saves the world
    !Users.Anderson along with only those subobjects whose names begin
    with Test_:

      Archive.Save
               (Objects => "[!Users.Anderson,!Users.Anderson.Test_@]",
                Options => "Nonrecursive");

    To better understand the effect of the Nonrecursive option, compare the
    preceding command with the following:

      Archive.Save (Objects => "!Users.Anderson.Test_@");

    Like the first command, this second command saves the objects in
    !Users.Anderson whose names begin with Test_. The difference is that
    the first command also saves the library !Users.Anderson along with its
    links and switch-file associations, whereas the second command does
    not. Instead, the second command merely saves a subset of the library's
    contents; when the saved objects are restored, the restore operation
    will have to create a library named !Users.Anderson if such a library
    does not exist at the time of restoration. Note that this newly created
    library would not have the links or switch-file associations from the
    original library.


 *  Prefix = naming pattern

    Specifies a naming pattern that is saved with the archived objects.
    During the restore operation, this saved pattern can optionally be used
    as the value of the For_Prefix parameter in the Restore command.
    Therefore, if an appropriate Prefix value has been saved, the restorer
    can restore objects to a new place without knowing the objects'
    original names.

    Omitting this option causes the value of the Objects parameter to be
    saved as the Prefix value. The saved value is thus a naming pattern that
    references all of the archived objects. If this pattern is used as the
    For_Prefix during the restore operation, then all of the objects will be
    restored under entirely new names. Before the Objects parameter value
    is saved, it is normalized--that is, any context characters such as ^
    and $ are expanded, any indirect file references are expanded, and all
    attributes are removed.


 *  Starting_At = time

    Delays the save operation until the specified time, which can be a date,
    a time of day, or both, and can be written in any of the styles defined
    by the !Tools.Time_Utilities.Date_Format type and the
    !Tools.Time_Utilities.Time_Format type. The save operation starts only
    if the tape-mount request has been answered.


 *  Unload

    A Boolean option. When True (the default), causes the tape to be
    rewound and unloaded after the operation is complete.

    When False, this option causes the tape to be rewound to the beginning
    and to remain online and available for subsequent requests. This is
    useful when you want to perform a list operation followed by a restore
    operation, or if you want to perform several restore operations in a
    row. Note that, because the tape is rewound, successive save operations
    will overwrite each other.

    When the tape is left online, subsequent requests send a tape-mount
    request
    to the operator's console, which must be answered before the tape can
    be accessed.


 Device : String := "MACHINE.DEVICES.TAPE_0";

 Specifies the name of the device onto which the Data and Index files are to
 be written. The default is to write onto tape.

 A library name can be specified instead of a tape device. In this case, the
 files are written into the specified library. If this library does not
 exist, it is created. A world is created outside a subsystem; a directory
 is created inside a subsystem.

 This parameter can be used to specify remote devices, such as a library or
 a tape drive on another R1000. For example, assume you are logged into an
 R1000 called M_1, which contains the objects that you need to archive.
 Assume further that the tape drive you want to use is on an R1000 called
 M_2, which is connected to M_1 on the network. Then you can use the
 following Device parameter to specify the desired drive:

   Device => "!!M_2!MACHINE.DEVICES.TAPE_0"

 Note that you can use the Save command only to specify a remote device,
 not remote objects. Note also that if you insert the remote R1000 name in
 front of the default Device value (MACHINE.DEVICES.TAPE_0), you must also
 insert an exclamation mark (!) between the R1000 name and that value.

 If there is more than one tape drive, a drive other Tape_0 can be specified
 (for example, !Machine.Devices.Tape_1). However, specifying a drive
 through this parameter merely serves to suggest a particular tape drive to
 the operator. The actual tape drive to be used is determined by the
 operator's response to the tape-mount request on the system console. Note
 that if no device exists with the specified logical name, then a library
 is created with that name.


 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 library structure is used in these examples:

   !Example : Library;
     Source    : Library;
     Libraries : Library;
     Logs      : Library;
     Tools     : Library;
     Move_List : File;

   !Example.Source : Library;
     File_One_Ada : File;

   !Example.Libraries : Library;
     Utils   : Library;
     Misc    : Library;
     Example : Library;
     ...

   !Example.Logs : Library;
     Parse_Log   : File;
     Make_Log    : File;

   !Example.Tools : Library;
     Build     : Ada;
     Build     : Ada (Proc_Body);
     Parse_All : Ada;
     Parse_All : Ada (Proc_Body);
     ...

 Assume you want to save the world !Example and all of its contents onto
 tape and then restore it in the library !Users.Anderson under the name
 New_Example. The following two commands, entered from any context,
 accomplish this. Note that if !Users.Anderson does not exist, it is
 created by the Restore command; furthermore, if the initiating user has
 operator capability, the user Anderson is created:

   Archive.Save (Objects => "!Example");

   Archive.Restore (Objects    => "!Example",
                    Use_Prefix => "!Users.Anderson.New_Example",
                    For_Prefix => "!Example");

 In the preceding Restore command, the Use_Prefix value replaces the
 For_Prefix value in the original name. Because the For_Prefix value specifies
 the entire original name, the Use_Prefix value
 (!Users.Anderson.New_Example) becomes the new name.

 Now assume that you want to transfer the libraries !Example.Libraries and
 !Example.Logs to another R1000 using tape. These libraries are to be
 restored into the world !Users.Anderson. The following two commands
 accomplish this. Note that
 if !Users.Anderson does not already exist, it is created; furthermore, if
 the initiating user has operator capability, the user Anderson is
 created.

 *  On the first R1000, from any context:

      Archive.Save (Objects => "!Example.l@");

 *  On the second R1000, from any context:

      Archive.Restore (Objects    => "!Example.l@",
                       Use_Prefix => "!Users.Anderson",
                       For_Prefix => "!Example");

 Now assume that you want to transfer the same libraries as in the previous
 example (namely, !Examples.Libraries and !Examples.Logs) and that these
 libraries are to be restored into the world !Users.Anderson on another
 R1000. However, this time, assume that !Users.Anderson exists and already
 contains libraries called Libraries and Logs. The following pair of
 commands transfers the desired libraries and merges their contents with
 the existing libraries !Users.Anderson.Libraries and !Users.Anderson.Logs.
 Note that the New_Objects option has been specified in the Restore command
 to prevent any existing objects from being overwritten.

 *  On the first R1000, from any context:

      Archive.Save (Objects => "!Example.l@");

 *  On the second R1000, from any context:

      Archive.Restore (Objects    => "!Example.l@",
                       Use_Prefix => "!Users.Anderson",
                       For_Prefix => "!Example",
                       Options    => "R1000, New_Objects");

 Now assume that you want to save and restore recently updated objects in
 two libraries. The libraries are to be named using an indirect file called
 !Example.Move_List, which contains these entries:

   !Example.Libraries.Utils
   !Example.Libraries.Misc

 Only objects that were modified after June 11, 1991, are to be saved, as
 specified by the Options parameter of the Save procedure. Furthermore,
 these objects are restored only if they will overwrite less recent
 versions, as specified by the Options parameter in the Restore procedure.
 The following pair of commands accomplishes this, restoring the
 appropriate objects into !Users.Anderson.

 *  On the first machine, from the context !Example:

      Archive.Save (Objects => "_Move_List",
                    Options => "R1000, After=06/11/91);

 *  On the second machine, from any context:

      Archive.Restore
                    (Objects    => "?",
                     Use_Prefix => "!Users.Anderson",
                     For_Prefix => "!Example.Libraries",
                     Options    => "R1000, Updated_Objects, Replace");

 See the introduction to this package for more examples.



 @node !Commands.Archive.Server

 procedure Server;

 DESCRIPTION

 Starts the archive server.

 This command is run by system initialization software and should never be
 executed by users.



 @node !Commands.Archive.Status

 procedure Status (For_Job : Machine.Job_Id);

 DESCRIPTION

 Displays information about the status of the specified archive job.


 PARAMETERS

 For_Job : Machine.Job_Id;

 Specifies the number of the archive job for which information is to be
 displayed. The number can reference an archive server or a user-initiated
 Archive.Copy, Archive.Save, or Archive.Restore job. To determine the
 number for a job, use the What.Users command.



 @node !Commands.Compilation

 Package Compilation provides commands for promoting, demoting, and
 deleting Ada units and for checking dependencies between Ada units.
 Although these commands can be used on single units, they are designed
 for use on multiple units, groups of interdependent units, or all the
 units in a program. For operations on single units, use commands from
 Editing Specific Types (EST), package Ada or package Common.

 Package Compilation also provides commands for managing target keys, which
 specify the processor on which application software is intended to
 execute, and for creating Ada units from text files containing Ada source
 code (uploaded from another machine).

 As with most commands in the !Commands world, these commands can be exe-
 cuted from programs but are tailored for use as interactive commands.


 RESOURCES IN PACKAGE COMPILATION

 The commands in package Compilation fall into several functional groups.
 Types and constants are not in this list.

 Changing unit states:              Demote, Make, Promote

 Deleting units:                    Atomic_Destroy, Delete, Destroy

 Managing target keys:              Get_Target_Key, Set_Target_Key,
                                    Show_Target_Key

 Listing dependencies:              Dependents

 Creating Ada units from text files: Compile, Parse

 Prelinking during compilation:     Load


 KEY CONCEPTS FOR PACKAGE COMPILATION

 This section focuses on using commands from package Compilation. For an
 introduction to building and compiling an Ada program in the
 Environment, see the Rational Environment User's Guide. For a more
 complete overview of compilation in the Environment, see the Key Concepts
 of this book.


 Using the Promote and Make Procedures

 Package Compilation contains two commands for promoting Ada units:

 *  Promote

 *  Make

 The Make procedure renames the Promote procedure with different default
 parameter values. These differences are discussed in the following
 subsections. First, however, it is useful to understand the basic way in
 which these procedures operate.

 The Promote and Make procedures are designed for promoting multiple units
 or groups of interdependent units. Promote and Make are especially useful
 for promoting all (or a specified subset) of the units in a program to
 verify dependencies in the program or to prepare it for execution. Promote
 and Make are more powerful than promote commands from packages Ada and
 Common (see the Editing Specific Types (EST) book), which are intended for
 use on single units.

 Promote and Make operate recursively on the named unit and on any related
 units implied by the Scope parameter. The scope of the promotion may
 include units that are explicitly referenced in with clauses by the
 specified units, units that are implicitly related to the named units (such
 as the specifications of named bodies), and any units withed by these
 units.

 You can use the Limit parameter to specify that related units in certain
 locations in the library hierarchy not be promoted, even if they are
 included in the Scope. By default, Make and Promote promote only units in
 the same world as a specified unit. The commands fail if any units outside
 the specified limit must be promoted. The values that are accepted by the
 Scope and Limit parameters are discussed in "Controlling the Extent of
 Compilation Commands," page nn.

 Note that to promote a unit, you must have write access to that unit and
 read access to any unit it withs. For example, to promote unit Test,
 which withs units Driver and Data, you must have write access to Test
 and read access to Driver and Data.

 The default parameter values and suggested uses of Promote and Make are
 discussed below.


 Promote Procedure

 The Promote procedure is designed for integrating a system of units. For
 this reason, by default, Promote raises the specified units to the
 installed state. In the installed state, interunit dependencies are
 established, but executable code is not generated. Thus, you can build and
 verify a system of Ada dependencies without incurring the overhead of
 generating executable code for the units.

 Because integrating a system of units does not require promoting all the
 units that would be needed for execution, the default scope includes only
 those units that must be promoted in order to check dependencies.
 Specifically, it includes:

 *  The named units

 *  Necessary implicitly related units, such as the corresponding
    specification of named unit bodies

 *  Subunits of named unit bodies

 *  The specifications of all units withed by the named units

 These units are promoted provided they are within the specified limit and
 are not already at or above the goal state. Units at or above the goal
 state are not affected.


 Make Procedure

 The Make procedure should be used when you want to unit-test part of a
 program or execute an entire program.

 By default, the Make procedure promotes the specified units to the coded
 state, generating executable code. Thus, the default scope includes all
 the units related to the named units. Specifically, the Make procedure
 promotes:

 *  The named units

 *  All implicitly related units, including the specification, body, and
    subunits of every unit promoted

 *  The specification, body, and subunits of units withed by the named units
    and all the units in their closures

 As with the Promote procedure, these units are promoted provided that they
 are within the specified limit and are not already at or above the goal
 state. Units already at the coded state are not affected.


 Using the Demote Procedure

 The Demote procedure is designed for demoting multiple units or units in
 an interdependent system. It is especially useful for demoting unit
 specifications that have dependents that also must be demoted to maintain a
 semantically consistent network. Thus, it is more powerful than demote
 commands in packages Ada and Common (see the Editing Specific Types (EST)
 book), which are designed for use on single units or unit bodies.

 The Demote procedure maintains semantic consistency by first finding the
 dependents of the specified unit and all of the dependents of those units
 until the entire transitive closure of the dependents of the specified unit
 is known. The procedure then demotes the named units and all their
 dependents in the appropriate order (see Chapter 2, "Compiling Programs in
 the Environment," for information about compilation order). Dependents
 that are demoted always include both units that explicitly with the named
 units and units that implicitly depend on the named units, such as the
 bodies of named specifications. The Dependents procedure can be used to
 check dependencies before attempting to demote a unit.

 As with Promote and Make, the set of related units included in the
 operation can be controlled using the Limit parameter. By default, only
 units in the same world as a specified unit can be demoted. The values that
 can be specified for the Limit parameter are discussed in "Controlling the
 Extent of Compilation Commands," page nn. If any of the dependents outside
 the specified limit must be demoted, the operation fails.

 By default, the Demote procedure places the specified units in the source
 state. To demote units to the installed or archived state, you can change
 the Goal parameter. (Note that to demote units to the archived state,
 you must use this command; Common.Demote does not demote units to the
 archived state.) If the current state of the unit or any of its dependents
 is the same as or lower than the goal state, Demote has no effect on that
 unit.

 Bear in mind that to demote a unit, you must have write access to that
 unit, but you need no access to units that with it. For example, to demote
 unit Test, which is withed by Test_Driver, you must have write access to
 Test, but you require no access to Test_Driver.


 Using the Delete, Destroy, and Atomic_Destroy Procedures

 Package Compilation contains three commands for deleting Ada units:

 *  Delete

 *  Destroy

 *  Atomic_Destroy

 These commands are more powerful than !Commands.Common.Delete because they
 take dependencies into account by demoting or destroying units that depend
 on the specified units. These commands are more powerful than !Commands.Li-
 brary.Delete because they can operate on units outside the current
 library. By default, they operate on units in the current world; using
 the Limit parameter, you can specify the locations in the library
 hierarchy in which the procedures can operate (see "Controlling the
 Extent of Compilation Commands," page nn).

 Two characteristics differentiate the Delete, Destroy, and Atomic_Destroy
 procedures. The first is whether the removed objects can be recovered.
 Deleting an object removes the object's default version from the library
 system. However, if the retention count for the enclosing library is at
 least 1, the deleted default version is retained and can be undeleted with
 the Library.Undelete command. If the retention count for the enclosing
 library is 0, the delete operation is unrecoverable and the object is
 expunged as well as deleted.

 Destroying an object is a more powerful means of deletion. Destroying an
 object permanently deletes and expunges all versions of the specified
 object, regardless of the retention count for the enclosing library. A
 destroyed object has no entry in the library display and cannot be
 recovered. For this reason, you should use the Destroy and Atomic_Destroy
 procedures only when you are certain that you will not need to recover the
 destroyed units.

 The second characteristic that differentiates the Delete, Destroy, and
 Atomic_Destroy procedures is how they affect units that depend on the
 unit or units being removed. The following subsections discuss the
 particular behavior of each command.


 Delete Procedure

 The Delete command deletes any subordinate units and demotes to the source
 state any units that depend on the specified units. Specifically, it:

 *  Deletes the named units

 *  Deletes the corresponding subunits when unit bodies are named

 *  Deletes the corresponding body and subunits when unit specifications are
    named

 *  Demotes any units that with the named units

 *  Demotes any units that depend on the demoted units


 Destroy Procedure

 The Destroy procedure operates on the subordinate units and dependents of
 the specified units in the same way as the Delete procedure. Thus, it:

 *  Destroys the named units

 *  Destroys the corresponding subunits when unit bodies are named

 *  Destroys the corresponding body and subunits when unit specifications
    are named

 *  Demotes any units that with the named units

 *  Demotes any units that depend on the demoted units

 Because destroyed units are unrecoverable, the Destroy procedure has an
 additional parameter that allows you to specify the maximum number of
 units per named unit to destroy. If the number of the units to destroy is
 greater than the value specified for the Threshold parameter, the
 procedure abandons all destructions.

 For example, if you inadvertently specify a wildcard expression that
 matches a library you do not want to destroy, and the default threshold of
 1 is used, the operation is abandoned because the library includes more
 units than are included by the threshold. The procedure can be executed
 again with a new threshold or with a more precise naming expression.


 Atomic_Destroy Procedure

 The Atomic_Destroy procedure is a special case of the Destroy procedure.
 When the Destroy procedure cannot destroy a particular unit (for example,
 if that unit is controlled), the Destroy procedure continues to destroy
 the other named units. In contrast, the Atomic_Destroy procedure destroys
 either all the units named by the procedure or none of the units. If one
 unit cannot be destroyed, then none of the specified units are destroyed.

 Note that Atomic_Destroy contains special parameters and should not be
 used without consulting your Rational technical representative.


 Controlling the Extent of Compilation Commands

 The behavior of compilation commands is controlled by various parameters
 that can be specified when invoking the commands. Two of these parameters,
 Scope and Limit, control which units, in addition to the specified units,
 the procedure will operate on. Another parameter, Effort_Only, allows you
 to verify the effect of a procedure without actually performing the
 operation. The Effort_Only parameter is especially useful for verifying
 that the Scope and Limit parameters will cause the procedure to operate on
 the desired units.

 The following subsections discuss the Scope and Limit parameters. Examples
 using the parameters follow the discussions.


 Scope Parameter

 The Make and Promote procedures contain a Scope parameter. The Scope
 parameter uses the relationship between units to define which units, in
 addition to the units specifically named, are to be promoted. The related
 units implied by the scope are promoted whether or not the promotions are
 necessary to satisfy the compilation dependencies.

 The five possible values for the Scope parameter are described in Table 1.

                 Table 1    Values for the Scope Parameter
             ------------------------------------------------ 
            |       |                                        |
            | Value |              Description               |
             ------------------------------------------------ 
            |       |                                        |
            |Single_|Specifies that only the named units be  |
            |Unit   |promoted. If a unit body is named, its  |
            |       |corresponding specification also is     |
            |       |promoted.                               |
             ------------------------------------------------ 
            |       |                                        |
            |Unit_  |Specifies that the named units and the  |
            |Only   |specifications of any units they with be|
            |       |promoted. If a unit body is named, its  |
            |       |corresponding specification is also     |
            |       |promoted.                               |
             ------------------------------------------------ 
            |       |                                        |
            |Subunit|Specifies that the named units and the  |
            |s_Too  |specifications of any units they with be|
            |       |promoted. If a unit body is named, its  |
            |       |subunits and corresponding              |
            |       |specification are also promoted.        |
             ------------------------------------------------ 
            |       |                                        |
            |All_   |Specifies that the specification, body, |
            |Parts  |and subunits of the named units and any |
            |       |units they with be promoted.            |
             ------------------------------------------------ 
            |       |                                        |
            |Load_  |Specifies that all units in the load vie|
            |Views  |associated with an imported spec view be|
            |       |promoted. The associated load view for a|
            |       |spec view is determined by the default  |
            |       |activity. All parts of the units in the |
            |       |load views are promoted.                |
             ------------------------------------------------ 



 Normally, you should use the smallest applicable scope. The smallest
 applicable scope for an operation is the one that includes all the related
 units that need to be promoted but includes the fewest units that are
 already at or above the goal state. However, when preparing to execute a
 program, you should use the largest applicable scope (All_Parts or
 Load_Views) to ensure that code is generated for all the units in the
 program. Additional guidelines for using the scope values are:

 *  When the named units do not depend on other units or when you know that
    the units they with are already promoted (such as when repromoting unit
    bodies that have been demoted for editing), use Single_Unit.

 *  When you want to promote a set of related units to verify dependencies
    or when you are repromoting unit specifications that have been demoted
    to allow editing, use Unit_Only or Subunits_Too.

 *  When you want to promote all the units necessary for execution, not
    including units in load views of other subsystems, use All_Parts.

 *  When you are working on a program that spans multiple subsystems and
    want to promote all the units necessary for execution, use Load_Views.

 Note that the scope Load_Views must be used with either the "<ACTIVITY>"
 or "<ALL_WORLDS>" limit. Other scopes can be used with any limit. See
 "Limit Parameter," below, for further information about limits.


 Limit Parameter

 Whereas the Scope parameter defines the additional units that are to be
 promoted, the Limit parameter defines the locations in the library
 hierarchy in which a command can operate. The Limit parameter guarantees
 that units in other locations are not inadvertently modified. Units in
 other locations are not affected, even if they are included in the scope.

 The Limit parameter can be specified using any string name that references
 a library or an Ada unit. Wildcards, set notations, attributes, indirect
 files, and context prefixes are accepted. The Limit parameter also can be
 specified using special values of the Change_Limit subtype. These special
 values are described in Table 2.

             Table 2    Special Values for the Limit Parameter
             ----------------------------------------------- 
            |           |                                   |
            |  Special  |            Description            |
            |   Value   |                                   |
             ----------------------------------------------- 
            |           |                                   |
            |"<UNITS>"  |Modifies only the specified units. |
             ----------------------------------------------- 
            |           |                                   |
            |"<SUBUNITS>|Modifies the specified units and th|
            |"          |subunits of specified bodies.      |
             ----------------------------------------------- 
            |           |                                   |
            |"<         |Modifies the specified units and an|
            |DIRECTORIES|units immediately within the same  |
            |>"         |library (world or directory) as a  |
            |           |specified unit.                    |
             ----------------------------------------------- 
            |           |                                   |
            |"<WORLDS>" |Modifies the specified units and an|
            |           |units in the same world as a       |
            |           |specified unit. This limit includes|
            |           |units in nested directories that   |
            |           |share the same enclosing world.    |
             ----------------------------------------------- 
            |           |                                   |
            |"<ACTIVITY>|Modifies the specified units and an|
            |"          |units in views specified by the    |
            |           |default activity file. Note that to|
            |           |use this limit, the default        |
            |           |activity file must contain         |
            |           |references for the desired         |
            |           |subsystem views.                   |
             ----------------------------------------------- 
            |           |                                   |
            |"<ALL_     |Modifies the specified units and   |
            |WORLDS>"   |units in any world or view.        |
             ----------------------------------------------- 



 You should use the smallest limit applicable for your operation. Table 2
 is organized with the most restrictive limit, "<UNITS>", at the top and
 the least restrictive limit, "<ALL_WORLDS>", at the bottom. The default
 limit for all the commands in package Compilation is "<WORLDS>".

 Note that to use the "<ACTIVITY>" limit, the default activity must contain
 references to the appropriate spec views and load views. The procedure fails 
 if units to be operated on exist in a spec or load view not listed in 
 the default activity.


 Examples

 The following examples refer to a procedure for displaying the sums of
 complex numbers. The program's main procedure, Display_Complex_Sums, uses
 resources from three packages: Complex, Complex_Utilities, and
 List_Generic. Package Complex_Utilities has a subunit called Image. The
 structure of this program is depicted in Figure 1, in which arrows are
 used to represent the dependencies introduced by with clauses. Unit
 specifications are represented by boxes in the foreground; units bodies are
 represented by boxes in the background.

                   ------------------------
                   | Display_Complex_Sums |
                   |        (proc)        |--
                   ------------------------ |
                     ------------------------
                         /          \
                        /            \
                       v              v
       -----------------           ---------------------
       | Complex (pkg) |           | Complex_Utilities |
       |               |--         |      (pkg)        |--
       ----------------- |        /--------------------- |
         -----------------       /   ---------------------
                                /                |
                               v             -------------
                      ----------------       |   Image   |
                      | List_Generic |       | (subunit) |
                      |  (gen pkg)   |--     -------------
                      ---------------- |
                        ----------------
   
   Figure 1   Dependencies among Units in Display_Complex_Sums Program


 The units in Figure 1 are contained in three different libraries,
 !Users.Anderson, World_A, and Directory_B, as displayed in Figure 2.

     -------------------------------------------------------
     |                !USERS.ANDERSON (world)              |
     |                                                     |
     |   ------------------------                          |
     |   | Display_Complex_Sums |                          |
     |   ------------------------                          |
     |                                                     |
     |   ---------------       -------------------------   |
     |   |   WORLD_A   |       |      DIRECTORY_B      |   |
     |   |             |       |                       |   |
     |   | ----------- |       | --------------------- |   |
     |   | | Complex | |       | | Complex_Utilities | |   |
     |   | ----------- |       | --------------------- |   |
     |   |             |       | ---------             |   |
     |   |             |       | | Image |             |   |
     |   ---------------       | ---------             |   |
     |                         | ----------------      |   |
     |                         | | List_Generic |      |   |
     |                         | ----------------      |   |
     |                         -------------------------   |
     -------------------------------------------------------
   
   Figure 2   The World !Users.Anderson


 Example 1: Suppose you want to verify dependencies between
 Complex_Utilities and the units on which it depends. In this case, you
 want to promote the specification, body, and subunits of
 Complex_Utilities, and any units they reference in with clauses (in
 particular, List_Generic), to the installed state using the following
 command:

   Compilation.Promote (Unit        => "Complex_Utilities",
                        Scope       => Compilation.Subunits_Too,
                        Goal        => Compilation.Installed,
                        Limit       => "<DIRECTORIES>",
                        Effort_Only => False,
                        Response    => "<PROFILE>");

 The limit "<DIRECTORIES>" is sufficient because all the units to be
 promoted are in the same library. Because you are only checking
 dependencies, you only need to promote the specifications of withed units,
 using the scope Subunits_Too. As a result, the body of List_Generic is not
 promoted.

 Example 2: Now suppose you want to test procedures in package Display_Com-
 plex_Sums. You need to promote the specification and body of
 Display_Complex_Sums and the specifications, bodies, and subunits of all
 the units referenced in with clauses to the coded state. In particular,
 the following units all need to be promoted: Complex'Spec, Complex'Body,
 Complex_Utilities'Spec, Complex_Utilities'Body, Image'Body,
 List_Generic'Body, and List_Generic'Spec.

 The scope All_Parts is the only scope that promotes the subordinate units
 of withed units and, therefore, the only scope that incudes all the
 necessary units. Because two worlds are involved (!Users.Anderson and
 World_A), you need to use the limit "<ALL_WORLDS>". (Remember that the
 limit "<WORLDS>" includes only the current world, not nested worlds.) The
 following command promotes all the necessary units:

   Compilation.Make (Unit        => "Display_Complex_Sums",
                     Scope       => Compilation.All_Parts,
                     Goal        => Compilation.Coded,
                     Limit       => "<ALL_WORLDS>",
                     Effort_Only => False,
                     Response    => "<PROFILE>");

 Example 3: Suppose that after testing the program, you want to make
 changes to the body of Complex_Utilities. To demote Complex_Utilities'Body
 for editing, you also need to demote its subunit, Image. To avoid
 inadvertently demoting any other units, you use the smallest applicable
 limit, "<SUBUNITS>":

   Compilation.Demote (Unit        => "Complex_Utilities'Body",
                       Goal        => Compilation.Source,
                       Limit       => "<SUBUNITS>",
                       Effort_Only => False,
                       Response    => "<PROFILE>");

 Example 4: While editing the body of Complex_Utilities, you decide to make
 changes to its specification as well. To demote Complex_Utilities'Spec, the
 body of Display_Complex_Sums, which withs Complex_Utilities, also has to
 be demoted. Because the units share the same enclosing world, you can use
 the "<WORLDS>" limit:

   Compilation.Demote (Unit        => "Complex_Utilities'Spec",
                       Goal        => Compilation.Source,
                       Limit       => "<WORLDS>",
                       Effort_Only => False,
                       Response    => "<PROFILE>");

 If Complex_Utilities'Body and Image had not already been demoted, the
 procedure would have demoted them as well.

 Note that the specification of Display_Complex_Sums does not need to be de-
 moted because the with clause referencing Complex_Utilities is contained
 in Display_Complex_Sums'Body, and bodies can be demoted without
 affecting the corresponding specification.

 Example 5: Suppose now that the program has been created in two
 subsystems, Subsystem_A and Subsystem_B, with Display_Complex_Sums in
 Subsystem_A and the units it references in Subsystem_B, as shown in Figure
 3.

     ----------------------------   -------------------------
     |       SUBSYSTEM_A        |   |      SUBSYSTEM_B      |
     |                          |   |                       |
     |  ----------------        |   |  ----------------     |
     |  | Spec_View_A  |        |   |  | Spec_View_B  |     |
     |  ----------------        |   |  |--------------|     |
     |                          |   |  | Complex      |     |
     |                          |   |  | C_Utiliities |     |
     |                          |   |  ----------------     |
     |                          |   |                       |
     |  ----------------        |   |  ----------------     |
     |  | Load_View_A1 |        |   |  | Load_View_B1 |     |
     |  |--------------|---     |   |  |--------------|---  |
     |  | D_C_Sums     |A2|     |   |  | Complex      |B2|  |
     |  |              |--|---  |   |  | C_Utilities  |--|  |
     |  |              |  |A3|  |   |  | List_Generic |  |  |
     |  |              |  |--|  |   |  |              |  |  |
     |  |              |  |  |  |   |  |              |  |  |
     |  |              |  |  |  |   |  |              |  |  |
     |  ----------------  |  |  |   |  ----------------- |  |
     |    -----------------  |  |   |    -----------------  |
     |      ------------------  |   |                       |
     ----------------------------   -------------------------
   Figure 3   Subsystems Containing the Display_Complex_Sums Program


 In the current activity, Spec_View_A is associated with Load_View_A1, and
 Spec_View_B is associated with Load_View_B2. Assume that the necessary
 imports and exports have been established.

 To prepare Display_Complex_Sums for execution, you need to promote all the
 parts of Display_Complex_Sums and all the parts of the units it references
 to the coded state. This means you need to promote not only the
 specifications of the units in Spec_View_B, but also the implementation
 contained in Load_View_B2 using the Load_Views scope. Because all the
 views are named in the current activity, you can use the "<ACTIVITY>"
 limit. Thus, the following command promotes the units necessary to execute
 Display_Complex_Sums:

   Compilation.Make (Unit        => "Display_Complex_Sums",
                     Scope       => Compilation.Load_Views,
                     Goal        => Compilation.Coded,
                     Limit       => "<ACTIVITY>",
                     Effort_Only => False,
                     Response    => "<PROFILE>");

 When the command is executed, the Environment finds with clauses in
 Display_Complex_Sums that reference Complex and Complex_Utilities. The
 Environment then:

 *  Checks the imports of Subsystem_A and the exports of Subsystem_B for
    Complex and Complex_Utilities

 *  Checks the default activity file to determine the load view associated
    with Spec_View_B

 *  Promotes all the units in Load_View_B2 (whether or not they are used by
    Display_Complex_Sums) to the coded state


 Creating Ada Units from Text Files

 Generally, Ada units are created and compiled directly in the Environment.
 Occasionally, however, Ada source code may be created on another host
 and need to be transported to the R1000. In such cases, the source code
 from the host is written first into text files in a library in the
 Environment. Next, Environment Ada units (with a structured
 representation) must be created from the source text files, using the Parse
 procedure defined in this package.

 The Parse procedure scans the contents of the named file, searching for
 compilation units. The procedure determines the correct parsing order of
 those units, builds the unit declarations in the context, and then parses
 the subunits. The newly created units are of class Ada and thus have the
 underlying structured (DIANA) representation characteristic of units in
 the Environment. The original text file remains unchanged.

 Note that the image of each named file must be Ada source for compilation
 as defined by the Reference Manual for the Ada Programming Language (Ada
 LRM), Section 10.1. If no unit name can be determined from the input, a
 unit is created with a temporary name. If a file contains any syntactic or
 semantic error, no Ada unit is created.


 Managing Target Keys

 Compilation for processors other than the R1000 is made possible by
 Rational's families of Cross-Development Facility (CDF) and Universal
 Compiler Integration (UCI) products. The UCI products, which allow the
 Rational Environment to be

 used with virtually any Ada compiler from any vendor, include the
 Compilation Integrator (RCI) and Target Build Utility (TBU).

 Target keys, associated with each world or view, contain information about
 the processor for which units in that world or view are to be compiled.
 Specifically, the target key for a world or view determines:

 *  The target processor for which the Ada units are to be compiled.
    Because each target processor's compilation requirements are different,
    the target key ensures that promoting a unit to the coded state invokes
    the appropriate compilation steps for that target.

 *  The programming design language (PDL), if any, to be enforced in the
    world. A PDL consists of annotations and other Ada constructs that
    embody a set of design and implementation rules.

 A complete description of target keys and the compilation characteristics
 they affect is contained in Chapter 3, "Tailoring the Compilation
 Setting." For further information about compiling for other targets, see
 the applicable RCI, TBU, or CDF manual. The remainder of this section
 discusses the operations on target keys that can be performed using
 commands in this package.


 Determining the Target Key for a World or View

 The target-key setting for a particular world or view can be obtained by
 using the Get_Target_Key function or Show_Target_Key procedure, both
 defined in this package. Get_Target_Key returns the value of the target key
 and is intended for programmatic use. Show_Target_Key displays the target
 key in the message window; it is intended for interactive use.


 Obtaining a List of Available Target Keys

 Information about the target keys that are registered and available on the
 system can be obtained by executing the Set_Target_Key procedure with the
 default values.


 Changing an Existing Target Key

 Because changing the target key for an existing world or view could
 require recompilation of all the units in that world or view, you
 usually cannot change an existing target key. Thus, copying the units to a
 new world or view that has been created with the desired target key is the
 primary means of changing the target for which certain units are compiled.

 Under certain circumstances, however, you can change the target key for an
 existing world or view using the Set_Target_Key procedure defined in this
 package. The following restrictions apply:

 *  The world or view must be one that has no links and in which no units
    have been semanticized or installed. This restriction occurs because
    the target key is set implicitly the first time a link is added, a unit
    is semanticized, or a unit is installed. A set target key cannot be
    changed.

 *  The target key can be changed only to a compatible target key. A
    compatible target key specifies the same target with a different PDL.
    (For example, Rational_2167A_Mc68020_Bare and Mc68020_Bare are
    compatible, whereas neither of these is compatible with R1000.)


 Creating Loaded Main Programs

 A loaded main program is an executable program that does not depend on its
 source code; that is, a loaded main program does not become obsolete if
 the source code from which it was created is modified. Loaded main programs
 are useful for frequently used tools and programs. They also are useful
 for transporting programs between R1000s, because they can be moved
 without having to move and recompile the associated source code.

 Loaded main programs are created from coded main programs. (A coded main
 program is a subprogram containing pragma Main that has been promoted to
 the coded state.) You can create a loaded main program from a coded main
 program using the Load procedure from this package. The resulting loaded
 main program (Load_Proc or Load_Func) comprises a valid Ada specification
 (that can be utilized by other programs) and a separate, self-contained
 copy of the main program's code segments, similar to an executable module
 on other computer systems. The Load procedure automatically inserts the
 Loaded_Main pragma in place of the Main pragma in the newly created Ada
 specification.

 Note that because loaded main programs have a valid Ada specification, you
 should use care when saving, copying, or restoring them. In particular, if
 the Ada specification contains with clauses that reference other packages,
 those packages must be visible (through links or imports) from any
 location to which the loaded main program is copied or restored.

 Also note that because its code segments are independent from its source
 code, a loaded main program is unaffected by demoting, and even changing,
 the source code. Thus, consistency between a loaded main program and its
 source code may be lost. Furthermore, loaded main programs, like code
 views, can be debugged using the Rational debugger only if the same
 version of the original source code still exists in the same location on
 the same R1000 and is still in the coded state.

 For further information about coded main programs and loaded main
 programs, see Appendix F for the R1000 Target in the Ada LRM or Chapter 4,
 "Compiling and Executing Main Programs," in this book.


 SWITCHES THAT CONTROL COMPILATION

 Certain aspects of the R1000 compiler's behavior are controlled by
 Environment switches. These controls are divided between library switches
 and session switches.

 Library switches determine compiler behavior on a library-by-library
 basis. For this reason, they control features that can be adjusted for a
 particular project, such as the generation of compiler listings and the
 response to certain types of errors. In general, library switches that
 control compilation have the processor name (prefix) R1000_Cg, Semantics,
 or Directory.

 Session switches determine compiler behavior on a session-by-session
 basis. They control features that can be adjusted for a particular user,
 independent of a particular project, such as the format of error logs.
 Session switches that affect compilation have the processor name
 Command_Cg, Profile, or Session. If products that allow compilation for
 non-R1000 targets, such as Rational's CDF, exist on the machine, they
 may provide additional session switches with other prefixes, such as
 Cross_Cg, to control compilation.

 The particular switches and the compilation features they control are
 discussed in Chapter 3, "Tailoring the Compilation Setting." For
 information about editing switch files, see package Switches in this book.


 @node !Commands.Compilation.All_Worlds

 All_Worlds : constant Change_Limit := "<ALL_WORLDS>";

 DESCRIPTION

 Defines a constant that serves as a value for the Limit parameter.

 This constant is retained for compatibility with previous releases and is
 equivalent to the special value "<ALL_WORLDS>".

 "<ALL_WORLDS>" and the All_Worlds constant allow procedures to change the
 state of units in any world or view.


 REFERENCES

 subtype Change_Limit



 @node !Commands.Compilation.Atomic_Destroy

 procedure Atomic_Destroy
                 (Unit      :     Unit_Name;
                  Success   : out Boolean;
                  Action_Id :     Action.Id    := Action.Null_Id;
                  Limit     :     Change_Limit := "<WORLDS>";
                  Response  :     String       := "<PROFILE>");

 DESCRIPTION

 Deletes and expunges the named unit or units and any dependent units.

 This procedure is a special case of the Destroy procedure. Whereas the
 Destroy procedure destroys units individually (if one unit fails, only
 that unit fails), this procedure destroys the named units as a group. If
 one of the named units cannot be destroyed, then no units are destroyed.

 This procedure should not be used without consultation with your Rational
 technical representative. Use the Destroy procedure instead.


 REFERENCES

 procedure Destroy



 @node !Commands.Compilation.Change_Limit

 subtype Change_Limit is String;

 DESCRIPTION

 Defines the locations in the library hierarchy in which a command is
 allowed to operate.

 Many of the commands in this package have a parameter of the Change_Limit
 subtype. The Limit parameter restricts the units an operation can modify
 based on their locations in the library hierarchy. If a procedure attempts
 to operate on any units outside the specified limit, errors are reported
 and the procedure fails. Thus, the Limit parameter serves as a final check
 to control the extent of an operation.

 The value for a parameter of the Change_Limit subtype is a string name
 that designates a world, directory, view, or activity. Multiple worlds,
 directories, views, or activities can be specified using wildcards, context
 characters, set notation, indirect files, and attributes.

 The Change_Limit subtype also has six predefined special values, described
 in Table 3.

                         Table 3    Special Values
             ----------------------------------------------- 
            |           |                                   |
            |  Special  |            Description            |
            |   Value   |                                   |
             ----------------------------------------------- 
            |           |                                   |
            |"<UNITS>"  |Modifies only the specified units. |
             ----------------------------------------------- 
            |           |                                   |
            |"<SUBUNITS>|Modifies the specified units and th|
            |"          |subunits of specified bodies.      |
             ----------------------------------------------- 
            |           |                                   |
            |"<         |Modifies the specified units and an|
            |DIRECTORIES|units immediately within the same  |
            |>"         |library (world or directory) as a  |
            |           |specified unit.                    |
             ----------------------------------------------- 
            |           |                                   |
            |"<WORLDS>" |Modifies the specified units and an|
            |           |units in the same world as a       |
            |           |specified unit. This limit includes|
            |           |units in nested directories that   |
            |           |share the same enclosing world.    |
             ----------------------------------------------- 
            |           |                                   |
            |"<ACTIVITY>|Modifies the specified units and an|
            |"          |units in views specified by the    |
            |           |default activity file. Note that to|
            |           |use this limit, the default        |
            |           |activity file must contain         |
            |           |references for the desired         |
            |           |subsystem views.                   |
             ----------------------------------------------- 
            |           |                                   |
            |"<ALL_     |Modifies the specified units and   |
            |WORLDS>"   |units in any world or view.        |
             ----------------------------------------------- 



 Any unique prefix of the special value enclosed in quotation marks and
 brackets ("<>") is recognized. Thus "<W>", "<WORLD>", and "<WORLDS>" are
 all valid equivalent ways of specifying "<WORLDS>". Furthermore, the
 special name "<DIRECTORY>" can be used for "<DIRECTORIES>".

 It is recommended that you use the smallest limit appropriate for your
 desired operation. Table 3 is organized with the most restrictive limit,
 "<UNITS>", at the top and the least restrictive limit, "<ALL_WORLDS>", at
 the bottom. For example, if all the units and all the units they with that
 you want promoted are in the same library, use the limit "<DIRECTORIES>".
                                                                           
 Note: Procedures that have both Scope and Limit parameters will modify
 only units that are within both the scope and limit specified (see subtype
 Promote_Scope).


 EXAMPLES

 For examples of the effects of the Limit parameter, see "Controlling the
 Extent of Compilation Commands," in the introduction to this package.


 REFERENCES

 constant All_Worlds
 constant Current_Directory
 constant Same_Directories
 constant Same_World
 constant Same_Worlds



 @node !Commands.Compilation.Compile

 procedure Compile
         (File_Name      : Name         := "<REGION>";
          Library        : Name         := "$";
          Goal           : Unit_State   := Compilation.Installed;
          List           : Boolean      := False;
          Source_Options : String       := "";
          Limit          : Change_Limit := "<WORLDS>";
          Response       : String       := "<PROFILE>");

 DESCRIPTION

 Creates Environment Ada units from Ada source code contained in the
 specified text file or files and promotes the newly created units to the goal
 state.

 This procedure is designed for Rational internal use only. To create Ada
 units from Ada source code contained in a text file, use the Parse
 procedure.


 REFERENCES

 procedure Make
 procedure Parse
 procedure Promote



 @node !Commands.Compilation.Current_Directory

 Current_Directory : constant Change_Limit := Same_Directories;

 DESCRIPTION

 Defines a constant that serves as a value for the Limit parameter.

 This constant is retained for compatibility with previous releases and is
 equivalent to the special value "<DIRECTORIES>" and the constant
 Same_Directories.

 The Current_Directory constant specifies that the state may be changed for
 units in the same library as the unit named to the procedure.


 REFERENCES

 subtype Change_Limit
 constant Same_Directories



 @node !Commands.Compilation.Delete

 procedure Delete (Unit     : Unit_Name    := "<SELECTION>";
                   Limit    : Change_Limit := "<WORLDS>";
                   Response : String       := "<PROFILE>");

 DESCRIPTION

 Deletes the specified unit or units and any subordinate units.

 This procedures deletes the default version of the specified units. Any
 subordinate units are also deleted. For example, if a unit specification is
 named, its corresponding body and subunits are also deleted. Likewise,
 if a unit body is named, its subunits are deleted.

 To maintain semantic consistency, the procedure demotes to the source
 state any units that depend on the specified unit. The units that are
 demoted include units that explicitly reference the named units in with
 clauses, units that implicitly depend on the named units (such as the
 bodies of named specifications), and units that with these dependents.

 The units that are demoted to allow the deletion can be controlled using
 the Limit parameter. By default, only dependent units in the same world as
 a specified unit can be demoted. If the deletion of the specified units or
 any subordinate units would make units outside the specified limit
 obsolete, the operation fails.

 Deleted units can be recovered provided the retention count for the
 enclosing library is at least 1. In this case, the default version of the
 deleted unit is retained and can be undeleted with the Library.Undelete
 command. If the retention count for the enclosing library is 0, the delete
 operation is unrecoverable and the object is expunged as well as deleted.
 Deleted units are stored in the archived state and appear in the expanded
 library display in brackets--for example, {Factorial}.

 To permanently delete and expunge all versions of a unit, use the Destroy
 procedure. A destroyed object has no entry in the library display and
 cannot be recovered.

 To check for dependent units before attempting to delete a unit, use the
 Dependents procedure.


 PARAMETERS

 Unit : Unit_Name := "<SELECTION>";

 Specifies the Ada unit or units to be deleted. Multiple units can be
 specified using wildcards, indirect files, context prefixes, set notation,
 and attributes. If a world or directory is named, that world or directory
 and all the units it contains are deleted. If an activity is named, all
 units in views referenced by that activity are deleted. If a view is
 named, errors result; views should be deleted using the Cmvc.Destroy-
 _View procedure (see the Project Management (PM) book). The default is the
 current selection.


 Limit : Change_Limit := "<WORLDS>";

 Specifies which Ada units can be demoted to permit the specified deletion.
 By default, units can be demoted only if they are in the same world as a
 unit specified in the Unit parameter. For the values that can be specified
 for this parameter, see subtype Change_Limit.


 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

 Common errors include specification of a Limit parameter that does not
 include all units that must be demoted.

 A Lock_Error can be caused by editing a unit that needs to be demoted.

 Access errors can be caused by the job not having the proper class of
 access for an object. To delete a unit, you must have write access to the
 unit to be deleted. To demote a dependent unit, you must have write access
 to that unit.


 EXAMPLES

 Assume you want to delete a package called Complex. This package is withed
 by the body of procedure Display_Complex_Sums. These units are contained
 in the same world and are in the installed state.

 If the Common.Delete procedure were attempted to delete Complex, it would
 fail because Display_Complex_Sums'Body depends on Complex. To avoid this
 problem, execute the following command:

   Compilation.Delete (Unit     => "Complex",
                       Limit    => "<WORLDS>",
                       Response => "<PROFILE>");

 The command first demotes the body of Display_Complex_Sums to the source
 state because it depends on Complex and is within the Limit "<WORLDS>".
 The command then deletes the body and specification of Complex. (Note that,
 because no attribute is used to specify whether the body or specification
 of Complex is to be deleted, the command deletes both units.)


 REFERENCES

 subtype Change_Limit
 procedure Destroy
 subtype Unit_Name



 @node !Commands.Compilation.Demote

 procedure Demote
               (Unit        : Unit_Name    := "<SELECTION>";
                Goal        : Unit_State   := Compilation.Source;
                Limit       : Change_Limit := "<WORLDS>";
                Effort_Only : Boolean      := False;
                Response    : String       := "<PROFILE>");

 DESCRIPTION


 Demotes the specified unit or units and any dependent units to the specified
 goal state.

 This procedure lowers the state of the specified units to the specified goal
 state. To maintain semantic consistency, the procedure also demotes any
 units that depend on the specified units. Specifically, units that
 explicitly reference the named units in with clauses, units that with
 these dependents, and units that implicitly depend on the named units
 (such as the bodies of named specifications) are also demoted. If the
 current state of a unit is the same as or lower than the goal state, the
 procedure has no effect on that unit.

 The units that are demoted to allow the specified demotion can be controlled
 using the Limit parameter. By default, only dependent units in the same world
 as a specified unit can be demoted. If the demotion of the specified units or
 any dependent units would make units outside the specified limit
 obsolete, the operation fails.

 The procedure can also be used to estimate the amount of work necessary to
 accomplish a specified demotion. When the Effort_Only parameter is True,
 the procedure produces a list of the specific demotions that would be
 required and an effort rating of the amount of work those operations would
 involve without actually performing the demotion.

 To check for dependent units before attempting to demote a unit, use the
 Dependents procedure.


 PARAMETERS

 Unit : Unit_Name := "<SELECTION>";

 Specifies the Ada unit or units to be demoted. Multiple units can be
 specified using wildcards, indirect files, context prefixes, set notation,
 and attributes. If a library is named, all units contained by that library
 are demoted. If an activity is named, all units in views referenced by
 that activity are demoted. The default is the current selection.


 Goal : Unit_State := Compilation.Source;

 Specifies the desired state of the units. By default, the units are demoted
 to the source state. If a unit is in a state lower than that specified,
 that unit is not affected by this procedure.


 Limit : Change_Limit := "<WORLDS>";

 Specifies which Ada units can be demoted to allow the specified demotion. By
 default, units can be demoted only if they are in the same world as units
 specified in the Unit parameter. For the values that can be specified for
 this parameter, see subtype Change_Limit.


 Effort_Only : Boolean := False;

 Specifies whether the procedure checks for the effort required to do the
 demotion or actually performs the demotion. When the value is True, the
 procedure produces a list of the operations that would be performed and
 an effort rating of the amount of work each would involve. The default
 value (False) causes the procedure to do the demotion.


 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

 Common errors include specification of a Limit parameter that does not
 include all of the units that must be demoted.

 A Lock_Error can be caused by editing a unit that needs to be demoted.

 Access errors can be caused by the job not having the proper class of
 access for an object. To demote a unit, you must have write access to that
 unit, but you need no access to its dependents.


 EXAMPLES

 Assume you want to demote the specification of a package called Complex.
 This package is withed by the body of procedure Display_Complex_Sums.
 These units are contained in the same world and are in the installed
 state.

 If a Common.Demote procedure were attempted to demote Complex, it would
 fail because Display_Complex_Sums'Body depends on Complex. To avoid this
 problem, execute the following command:

   Compilation.Demote (Unit        => "Complex'Spec",
                       Goal        => Compilation.Source,
                       Limit       => "<WORLDS>",
                       Effort_Only => False,
                       Response    => "<PROFILE>");

 The command first demotes Display_Complex_Sums'Body to the source state
 because it depends on Complex'Spec and is within the Limit "<WORLDS>". To
 maintain semantic consistency, the command also demotes Complex'Body
 before demoting Complex'Spec.

 If Complex had contained with clauses referencing other units, those units
 would not be affected.


 REFERENCES

 subtype Change_Limit
 constant Source
 subtype Unit_Name
 type Unit_State



 @node !Commands.Compilation.Dependents

 procedure Dependents (Unit       : Unit_Name := "<IMAGE>";
                       Transitive : Boolean   := False;
                       Response   : String    := "<PROFILE>");

 DESCRIPTION

 Displays the units that depend on the specified unit or units.

 This procedure produces a list of the units that depend on the specified
 units. The procedure is useful for checking dependencies before deleting
 or demoting a unit.

 In short, dependents are those units that must be compiled after the
 specified unit (see Chapter 2, "Compiling Programs in the Environment").
 The list produced by this command includes both units that implicitly
 depend on the named units, such as the specifications of named bodies, and
 units that explicitly reference the named units in with clauses. The
 Transitive parameter allows you to specify that the list include the
 transitive closure of dependents--that is, the units that depend on the
 direct dependents of the specified units.

 The resulting list of dependents is placed in Current_Output, which is, by
 default, an Environment output window. When multiple units are specified,
 the display lists the dependents by the specified units on which they
 depend. When the transitive closure is listed, the level of dependency
 is also displayed.


 PARAMETERS

 Unit : Unit_Name := "<IMAGE>";

 Specifies the Ada unit or units whose dependents are desired. Multiple
 units can be specified using wildcards, indirect files, context prefixes, set
 notation, and attributes. If a library is named, the dependents of all
 the units contained by that library are listed. If an activity is named,
 the dependents of all units in views referenced by that activity are
 listed. The default is the current selection or, if there is no selection,
 the current image.


 Transitive : Boolean := False;

 Specifies whether dependents of dependents are to be computed recursively
 and displayed in the output. The default is to display only the direct
 dependents. Direct dependents are those units that reference the
 specified units in a with clause or that implicitly depend on the specified
 units (for example, the specifications of named bodies).


 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 specified unit and its dependents must be in the installed or coded
 state. Dependents that are in the source state are not listed.


 EXAMPLES

 Assume that you have a procedure in !Users.Your_Username.Complex_Numbers
 that displays the sums of complex numbers and that this procedure uses
 resources from three packages: Complex, Complex_Utilities, and
 List_Generic. Package Complex_Utilities has a separate subunit (Image).
 The structure of this program is depicted in Figure 4, in which arrows
 are used to represent dependencies introduced by with clauses. Unit
 specifications are represented by the boxes in the foreground; unit bodies
 are represented by the boxes in the background.

                   ------------------------
                   | Display_Complex_Sums |
                   |        (proc)        |--
                   ------------------------ |
                     |                      |
                     ------------------------
                         /          \
                        /            \
                       v              v
       -----------------           ---------------------
       | Complex (pkg) |           | Complex_Utilities |
       |               |--         |      (pkg)        |--
       ----------------- |         --------------------- |
         |               |        /  |                   |
         -----------------       /   ---------------------
                                /                |
                               v             -------------
                      ----------------       |   Image   |
                      | List_Generic |       | (subunit) |
                      |  (gen pkg)   |--     -------------
                      ---------------- |
                        |              |
                        ----------------
   Figure 4   Dependencies in Display_Complex_Sums Program


 Notice which part of the units are attached by dependency arrows. The body
 of Display_Complex_Sums contains with clauses that reference Complex and
 Complex_Utilities. In turn, the specification of Complex_Utilities
 contains a with clause that references List_Generic. With clauses always
 reference the specification of the named unit.

 Suppose you want to demote both the specification and the body of
 List_Generic for editing. First, you want to check dependencies on
 List_Generic to find out which other units will have to be demoted. Execute
 the following command:

   Compilation.Dependents (Unit       => "List_Generic",
                           Transitive => True,
                           Response   => "<PROFILE>");

 The command produces the following display in an Environment output
 window, listing all the units that depend either directly or indirectly on
 List_Generic and the level of dependency:

 90/11/28 17:15:53 ::: [Compilation.Dependents ("List_Generic", TRUE,
 90/11/28 17:15:53 ... PERSEVERE);].
 !USERS.YOUR_USERNAME.COMPLEX_NUMBERS.LIST_GENERIC'SPEC'V(1) has the
    following dependents:
 !USERS.YOUR_USERNAME.COMPLEX_NUMBERS.LIST_GENERIC'BODY'V(1)
 !USERS.YOUR_USERNAME.COMPLEX_NUMBERS.COMPLEX_UTILITIES'SPEC'V(1)
  (Level 1):!USERS.YOUR_USERNAME.COMPLEX_NUMBERS.COMPLEX_UTILITIES'BODY'V(1)
  (Level 2):!USERS.YOUR_USERNAME.COMPLEX_NUMBERS.COMPLEX_UTILITIES.IMAGE'
     BODY'V(1)
  (Level 1):!USERS.YOUR_USERNAME.COMPLEX_NUMBERS.DISPLAY_COMPLEX_SUMS'BODY'V(1)

  90/11/28 17:15:54 --- !USERS.YOUR_USERNAME.COMPLEX_NUMBERS.LIST_GENERIC'BODY'V(1)
  90/11/28 17:15:54 ... has no dependents.
  90/11/28 17:15:54 ::: [End of Compilation.Dependents Command].

 All of the units in this list have to be demoted before List_Generic can
 be demoted or deleted. Notice that the spec and body of Complex_Utilities
 are listed as dependents of varying levels. Complex_Utilities'Spec is a
 direct dependent because it contains the with clause that references
 List_Generic, Complex_Utilities'Body is a first-level dependent because
 Complex_Utilities'Spec depends on it, and Image'Body is a second-level
 dependent because Complex_Utilities'Body depends on it.

 In contrast, notice that only the body of Display_Complex_Sums is listed
 as a dependent of List_Generic, because the with clause is contained in
 the body, and the body has no dependents.


 REFERENCES

 subtype Unit_Name



 @node !Commands.Compilation.Destroy

 procedure Destroy (Unit      : Unit_Name    := "<SELECTION>";
                    Threshold : Natural      := 1;
                    Limit     : Change_Limit := "<WORLDS>";
                    Response  : String       := "<PROFILE>");

 DESCRIPTION

 Destroys the specified unit or units and any subordinate units.

 This procedure deletes and expunges all versions of the specified units.
 Any subordinate units are also destroyed. For example, if a unit
 specification is named, its corresponding body and subunits are also
 destroyed. Likewise, if a unit body is named, its subunits are destroyed.
 To maintain semantic consistency, the procedure demotes to the source
 state any units that depend on the specified units.

 The units that are demoted to allow the destruction can be controlled
 using the Limit parameter. By default, only dependent units in the same
 world as a specified unit can be demoted. If the destruction of the
 specified units or any subordinate units would make units outside the
 specified limit obsolete, the operation will fail.

 The procedure provides for a threshold number of units per specified unit
 that can be destroyed. If the threshold is exceeded, the procedure
 abandons all destructions. The threshold serves as a safeguard against
 destroying too many objects. For example, if you inadvertently specify a
 wildcard expression that matches a library you do not want to destroy, and
 the default threshold of 1 is used, the operation is abandoned because the
 library includes more units than are permitted by the default threshold.
 The procedure can be executed again with a new threshold or with a more
 precise naming expression.

 Units that have been deleted and expunged with this procedure cannot be
 recovered; recoverable deletions can be made with the Delete procedure.

 To check for dependent units before attempting to destroy a unit, use the
 Dependents procedure.


 PARAMETERS

 Unit : Unit_Name := "<SELECTION>";

 Specifies the Ada unit or units to be destroyed. Multiple units can be
 specified using wildcards, indirect files, context prefixes, set notation,
 and attributes. If a library is named, that library and all the units it
 contains are destroyed. If an activity is named, all units in views
 referenced by that activity are destroyed. If a view is named, errors
 result; views should be destroyed using the Cmvc.Destroy_View procedure
 (see the Project Management (PM) book). The default is the current
 selection.


 Threshold : Natural := 1;

 Specifies the number of units per named unit that can be destroyed before
 the procedure fails. The default permits only the named units--not
 including dependents or subordinates--to be destroyed. If the number of
 units to destroy is greater than the threshold, the procedure abandons all
 destructions.


 Limit : Change_Limit := "<WORLDS>";

 Specifies which Ada units can be demoted to permit the destruction. By
 default, units can be demoted only if they are in the same world as a unit
 specified in the Unit parameter. For the values that can be specified for
 this parameter, see subtype Change_Limit.


 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

 Common errors include specification of a Limit parameter that does not
 include all units that must be demoted and incorrect specification of the
 Threshold parameter.

 A Lock_Error can be caused by editing a unit that needs to be destroyed.

 Access errors can be caused by the job not having the proper class of
 access for a unit. To destroy a unit, you must have write access to that
 unit. To demote a dependent unit, you must have write access to that
 unit.


 EXAMPLES

 Assume you have a package called Complex. This package is withed by
 Display_Complex_Sums'Body. These units are contained in the same world
 and are in the installed state.

 You have decided you will not need package Complex in the future, so you
 choose to expunge it as well as delete it, using the Destroy procedure:

   Compilation.Destroy (Unit      => "Complex'Spec",
                        Threshold => 2,
                        Limit     => "<WORLDS>",
                        Response  => "<PROFILE>");

 The command first demotes Display_Complex_Sums'Body to the source state be-
 cause it depends on Complex and is within the Limit "<WORLDS>". The
 command then destroys the body and specification of Complex. The procedure
 succeeds because the threshold (2) is high enough to include both parts
 of Complex; if the threshold had been less than 2, the procedure would
 have failed. If the procedure had failed, no units would have been
 destroyed. Note that these destructions are irreversible.


 REFERENCES

 subtype Change_Limit
 subtype Unit_Name



 @node !Commands.Compilation.Get_Target_Key

 function Get_Target_Key (For_World : String := "<IMAGE>")
                                            return String;

 DESCRIPTION

 Returns the image of the target key for the specified world.

 This function is intended for programmatic use. To have the target key
 reported in the message window, use the Show_Target_Key procedure.


 PARAMETERS

 For_World : String := "<IMAGE>";

 Specifies the name of the world for which the target key is to be returned.
 The default is the world displayed in the current window.


 return String;;

 Returns the image of the target key for the specified world.


 REFERENCES

 procedure Set_Target_Key
 procedure Show_Target_Key



 @node !Commands.Compilation.Load

 procedure Load (From     : String := ">>MAIN_PROGRAM NAME<<";
                 To       : String := ">>LOADED_MAIN NAME<<";
                 Response : String := "<PROFILE>");

 DESCRIPTION

 Creates a loaded main program from the specified coded main program.

 A loaded main program is an executable program that does not depend on its
 source code; that is, a loaded main program does not become obsolete if
 the source code from which it was created is modified. Furthermore, a
 loaded main program can be moved between R1000s without having to move and
 recompile its source code.

 Loaded main programs are created from coded main programs, which are main
 subprograms that contain pragma Main and that have been promoted to the
 coded state. The resulting loaded main program comprises a valid Ada
 specification (that can be utilized by other programs) and a separate,
 self-contained copy of the main program's code segments, similar to an
 executable module on other computer systems. The Load procedure
 automatically inserts the Loaded_Main pragma in place of the Main pragma
 in the newly created Ada specification. Furthermore, this procedure
 converts the object's subclass from Main_Proc, Main_Func, or Main_Body
 to Load_Proc or Load_Func.

 Note that because loaded main programs have a valid Ada specification, you
 should use care when saving, copying, or restoring them. In particular, if
 the Ada specification contains with clauses that reference other packages,
 those packages must be visible (through links or imports) from any
 location to which the loaded main program is copied or restored.

 Also note that because its code segments are independent of its source
 code, a loaded main program is unaffected by demoting, and even changing,
 the source code. Thus, consistency between a loaded main program and its
 source code may be lost. Furthermore, loaded main programs, like code
 views, can be debugged using the Rational debugger only if the same
 version of the original source code still exists in the same location on
 the same R1000 and is still in the coded state.

 See Chapter 4, "Compiling and Executing Main Programs," and Appendix F for
 the R1000 Target in the Ada LRM for more information about pragma
 Loaded_Main and pragma Main.


 PARAMETERS

 From : String := ">>MAIN_PROGRAM NAME<<";

 Specifies the name of the coded main program from which the loaded main
 program is to be created. The default parameter placeholder
 ">>MAIN_PROGRAM NAME<<" must be replaced or an error will result. The
 specified main program must be in the coded state.


 To : String := ">>LOADED_MAIN NAME<<";

 Specifies the name of the loaded main program to be created. The default
 parameter placeholder ">>LOADED_MAIN NAME<<" must be replaced or an
 error will result.


 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

 Chapter 4, "Compiling and Executing Main Programs"
 Reference Manual for the Ada Programming Language, Appendix F for the
 R1000 Target, pragma Loaded_Main



 @node !Commands.Compilation.Make

 procedure Make
           (Unit        : Unit_Name     := "<IMAGE>";
            Scope       : Promote_Scope := Compilation.All_Parts;
            Goal        : Unit_State    := Compilation.Coded;
            Limit       : Change_Limit  := "<WORLDS>";
            Effort_Only : Boolean       := False;
            Response    : String        := "<PROFILE>")
                                                 renames Promote;

 DESCRIPTION

 Promotes the specified unit or units and the related units implied by the
 Scope parameter to the specified goal state.

 This procedure renames the Promote procedure with different default
 parameter values. It is typically used to prepare a program for execution.
 When checking a program for semantic consistency (and not executing), use
 the Promote procedure.

 By default, this procedure promotes units to the coded state. If a unit is
 at or above the goal state, this procedure has no effect on that unit.

 This procedure promotes, by default, the named units; implicitly related
 units (specification, body, and subunits); and the specifications, bodies,
 and subunits of any units they reference in with clauses. To change the 
 related units that are included in the promotion, use the Scope parameter.

 The units that are promoted can be restricted using the Limit parameter.
 By default, only units in the same world as a specified unit are
 promoted. If the promotion of the specified units or any related units
 requires the promotion of units outside the specified Limit, the
 operation fails.

 To have this procedure estimate the amount of work necessary to accomplish
 a specified promotion without actually promoting any units, set the
 Effort_Only parameter to True. When the Effort_Only parameter is True,
 this procedure produces a list of the specific promotions that would
 occur and an effort rating of the amount of work those operations would
 involve, without promoting any units.

 This procedure promotes units individually. Each promotion of a unit is a
 separate action. If the unit is to be promoted by more than one state (from
 source to coded), the promotion from one state to the next is done as a
 separate action (source to installed, then installed to coded). If the
 promotion of a particular unit fails because of semantic errors or other
 reasons, the promotion of any other units may not be affected, depending
 on the error reaction specified.


 PARAMETERS

 Unit : Unit_Name := "<IMAGE>";

 Specifies the Ada unit or units to be promoted. Multiple units can be
 specified using wildcards, indirect files, context prefixes, set notation,
 and attributes. If a library is named, all the units contained by that
 library are promoted. If an activity is named, all units in views
 referenced by that activity are promoted. The default is the current
 selection or, if there is no selection, the current image.


 Scope : Promote_Scope := Compilation.All_Parts;

 Specifies the additional Ada units, related directly or indirectly to the
 units named in the Unit parameter, that are included in the operation. By
 default, the specification, body, and subunits of the named unit and
 recursively the specification, body, and subunits of all units referenced
 in with clauses of those units are promoted.


 Goal : Unit_State := Compilation.Coded;

 Specifies the desired state of the units. By default, the units are
 promoted to the coded state. If a unit is in a state higher than that
 specified, it is not affected by this procedure.


 Limit : Change_Limit := "<WORLDS>";

 Specifies which Ada units can be promoted based on their location in the
 library hierarchy. By default, units can be promoted only if they are in
 the same world as a unit specified in the Unit parameter. For the values
 that can be specified for this parameter, see subtype Change_Limit.


 Effort_Only : Boolean := False;

 Controls whether the procedure checks for the effort required to do the
 promotion or actually does the promotion. When the value is True, the
 procedure produces a list of the operations that would be performed and an
 effort rating of the amount of work those operations would involve. The
 default value (False) causes the procedure to do the promotion.


 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

 Common errors include specification of a Limit or Scope parameter that does
 not include all the related units that must be promoted before the
 specified units.

 A Lock_Error may be encountered when attempting to promote a unit that is
 being edited.

 Access errors can be caused by the job not having the proper class of
 access for an object. To promote a unit, you must have write access to
 that unit and write access to any unit it withs.

 The procedure does not lock any units before promoting them. Thus, if one
 job is promoting some units and another job is demoting some of the same
 units, one or the other job will have errors. If two jobs are promoting
 the same units, the first job may fail while the second job succeeds.

 If the promotion of a particular unit fails because of semantic errors or
 other reasons, the promotion of any other units may not be affected,
 depending on the error reaction specified.


 EXAMPLES

 Assume that you have a procedure that displays the sums of complex numbers
 and that this procedure uses resources from three packages: Complex,
 Complex_Utilities, and List_Generic. Package Complex_Utilities has a
 separate subunit (Image).

 Suppose you want to execute the program. To promote the specifications,
 bodies, and subunits of all the units in the program to the coded state,
 from which you can execute them, you can use the following command:

   Compilation.Make (Unit        => "Display_Complex_Sums",
                     Scope       => Compilation.All_Parts,
                     Goal        => Compilation.Coded,
                     Limit       => "<WORLDS>",
                     Effort_Only => False,
                     Response    => "<PROFILE>");

 If any of these units are outside the specified limit (the current world),
 the procedure fails.


 REFERENCES

 subtype Change_Limit
 procedure Promote
 subtype Unit_Name
 type Unit_State



 @node !Commands.Compilation.Name

 subtype Name is String;

 DESCRIPTION

 Defines the names of non-Ada objects to be used as parameters in procedures
 in this package.

 This subtype allows string names, special names, special values,
 wildcards, context characters, indirect files, set notation, and
 attributes. These naming conventions are discussed in the Parameter-Value
 Conventions tabbed section in the Reference Summary (RS).



 @node !Commands.Compilation.Parse

 procedure Parse (File_Name      : Name    := "<REGION>";
                  Directory      : Name    := "$";
                  List           : Boolean := False;
                  Source_Options : String  := "";
                  Response       : String  := "<PROFILE>");

 DESCRIPTION


 Parses the Ada source code in the specified file or files and creates
 corresponding Ada units.

 This procedure scans the contents of the named files, searching for
 compilation units, and creates those units. The newly created units are of
 class Ada and therefore have the underlying structured (DIANA)
 representation characteristic of units in the Environment. The units are
 created in the source state.

 The specified files can contain any number of Ada-unit specifications and/or
 bodies. However, the image of each file must be Ada source for compilation
 as defined by Section 10.1 of the Reference Manual for the Ada Programming
 Language. If no unit name can be determined from the input, the unit is
 created with a temporary name. If a specified file contains any syntactic or
 semantic error, no Ada unit is created.

 Existing Ada units that have the same name as a newly created unit are
 made obsolete and are deleted from the library. The original text file
 remains unchanged.

 This procedure is useful when transporting Ada source code from another
 host to the Rational Environment. In that case, source code is loaded into
 text files in a directory in the Environment. These files are then
 transformed into parsed Ada units using this procedure.


 PARAMETERS

 File_Name : Name := "<REGION>";

 Specifies the text file that contains Ada units to be parsed. Multiple units
 can be specified using wildcards, context prefixes, indirect files, set
 notation, and attributes. The default is the selected region.


 Directory : Name := "$";

 Specifies the library (directory or world) in which to create the parsed
 Ada units. Wildcards, attributes, and context characters can be used in
 this name if the name resolves unambiguously to a single location. The
 default is the current library.


 List : Boolean := False;

 Specifies whether to list each unit, as parsed, in the log file. The default
 is not to list the units.


 Source_Options : String := "";

 No options currently are implemented for this command. This parameter is
 reserved for future development.


 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

 If the name of the source text file is identical to the name of the Ada
 unit it contains, an error will occur because two objects of the same
 name cannot exist in a library. A suggested strategy is to keep text files
 in one library and compile Ada units into another library.


 EXAMPLES

 Assume that you have in your home world a text file called Complex that
 contains the Ada source code for the package specification and body of a
 unit called Complex. To use the procedures defined in package Complex,
 you need to create Environment Ada units from the source code in the
 text file.

 Because the text file and the Ada package have the same name, you decide to
 parse the units into !Users.Your_Username.Utilities, using the following
 command:

   Compilation.Parse
           (File_Name      => "Complex_Source",
            Directory      => "!Users.Your_Username.Utilities",
            List           => False,
            Source_Options => "",
            Response       => "<PROFILE>");

 When executed from your home world, this command creates two new Ada
 units, Complex'Spec and Complex'Body, and places them in
 !Users.Your_Username.Utilities. Note that the original text file from
 which the Ada units were created, Complex_Source, remains intact in your
 home world.


 REFERENCES

 subtype Name



 @node !Commands.Compilation.Promote

 procedure Promote
        (Unit        : Unit_Name     := "<IMAGE>";
         Scope       : Promote_Scope := Compilation.Subunits_Too;
         Goal        : Unit_State    := Compilation.Installed;
         Limit       : Change_Limit  := "<WORLDS>";
         Effort_Only : Boolean       := False;
         Response    : String        := "<PROFILE>");

 DESCRIPTION

 Promotes the specified unit or units and any units implied by the Scope
 parameter to the specified goal state.

 This procedure is useful when checking a system of units for semantic
 consistency. When preparing a system for execution, use the Make
 procedure, which has different default parameter values.

 This procedure raises the state of the specified units to the goal state,
 which is, by default, the installed state. It also raises the state of any
 units implied by the Scope parameter that are related (either implicitly
 or explicitly) to the specified units. By default, this procedure promotes
 the specified units and the specifications of any units they reference in
 with clauses. To maintain semantic consistency, if the named unit is a
 body, the corresponding specification and any subunits are also promoted.
 If a unit is at or above the goal state, this procedure has no effect on
 that unit.

 The units that are promoted can be controlled using the Limit parameter.
 By default, only units in the same world as a specified unit are
 promoted. If the promotion of the specified units or any related units
 requires the promotion of units outside the specified limit, the
 operation fails.

 To have this procedure estimate the amount of work necessary to accomplish
 a specified promotion without actually promoting any units, set the
 Effort_Only parameter to True. When the Effort_Only parameter is True,
 this procedure produces a list of the specific promotions that would
 occur and an effort rating of the amount of work those operations would
 involve, without promoting any units.

 This procedure promotes units individually. Each promotion of a unit is a
 separate action. If the unit is to be promoted by more than one state
 (from source to coded), the promotion from one state to the next is done
 as a separate action (source to installed, then installed to coded). If
 the promotion of a particular unit fails because of semantic errors or
 other reasons, the promotion of any other units may not be affected,
 depending on the error reaction specified.


 PARAMETERS

 Unit : Unit_Name := "<IMAGE>";

 Specifies the Ada unit or units to be promoted. Multiple units can be
 specified using wildcards, indirect files, context prefixes, set notation,
 and attributes. If a library is named, all the units contained by library
 are promoted. If an activity is named, all units in views referenced by
 that activity are promoted. The default is the current selection or, if
 there is no selection, the current image.


 Scope : Promote_Scope := Compilation.Subunits_Too;

 Specifies the additional Ada units, related directly or indirectly to the
 units named by the Unit parameter, that are included in the Promote
 operation. By default, the named units and the specifications of any
 units they reference in with clauses are promoted. Units that depend
 implicitly on the named units (such as
 the specifications of named bodies) are also promoted. For the values that
 can be specified for this parameter, see type Promote_Scope.


 Goal : Unit_State := Compilation.Installed;

 Specifies the desired state of the units. By default, the units are
 promoted to the installed state. If a unit is in a state higher than that
 desired, that unit is not affected by this procedure.


 Limit : Change_Limit := "<WORLDS>";

 Specifies which Ada units can be promoted based on their location in the
 library hierarchy. By default, units can be promoted only if they are in
 the same world as a unit specified in the Unit parameter. For the values
 that can be specified for this parameter, see subtype Change_Limit.


 Effort_Only : Boolean := False;

 Specifies whether the procedure checks for the effort required to do the
 promotion or actually does the promotion. When the value is True, the
 procedure produces a list of the operations that would be performed and
 an effort rating of the amount of work those operations would involve. The
 default value (False) causes the procedure to do the promotion.


 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

 Common errors include specification of a Limit or Scope parameter that does
 not include all the related units that must be promoted before the
 specified units.

 A Lock_Error can be caused by editing a unit that needs to be promoted.

 Access errors can be caused by the job not having the proper class of
 access for an object. To promote a unit, you must have write access to
 that unit and write access to any unit it withs.

 The procedure does not lock any units before promoting them. Thus, if one
 job is promoting some units and another job is demoting some of the same
 units, one or the other job will have errors. If two jobs are promoting
 the same units, the first job may fail while the second job succeeds.

 If the promotion of a particular unit fails because of semantic errors or
 other reasons, the promotion of any other units may not be affected,
 depending on the error reaction specified.


 EXAMPLES

 Assume that you have a procedure that displays the sums of complex numbers
 and that this procedure uses resources from three packages: Complex,
 Complex_Utilities, and List_Generic. Package Complex_Utilities has a
 separate subunit (Image). The structure of this program is depicted in
 Figure 5, in which arrows are used to represent dependencies introduced by
 with clauses. The specifications of units are represented by the boxes in
 the foreground; the bodies of units are represented by the boxes in the
 background.

                   ------------------------
                   | Display_Complex_Sums |
                   |        (proc)        |--
                   ------------------------ |
                     |                      |
                     ------------------------
                         /          \
                        /            \
                       v              v
       -----------------           ---------------------
       | Complex (pkg) |           | Complex_Utilities |
       |               |--         |      (pkg)        |--
       ----------------- |         --------------------- |
         |               |        /  |                   |
         -----------------       /   ---------------------
                                /                |
                               v             -------------
                      ----------------       |   Image   |
                      | List_Generic |       | (subunit) |
                      |  (gen pkg)   |--     -------------
                      ---------------- |
                        |              |
                        ----------------
   Figure 5   Display_Complex_Sums Program


 Suppose you want to verify the dependencies of Display_Complex_Sums by
 promoting Display_Complex_Sums and all the units it withs to the
 installed state. To do this, use the Promote procedure:

   Compilation.Promote (Unit        => "Display_Complex_Sums",
                        Scope       => Compilation.Subunits_Too,
                        Goal        => Compilation.Installed,
                        Limit       => "<WORLDS>",
                        Effort_Only => False,
                        Response    => "<PROFILE>");

 The procedure first checks for dependencies and promotes the specifications
 of the withed units Complex and Complex_Utilities. To promote
 Complex_Utilities'Spec, the specification of List_Generic also is
 promoted. Finally, the specification and body of Display_Complex_Sums are
 promoted. The scope Subunits_Too does not promote the bodies and subunits
 of the withed units.


 REFERENCES

 subtype Change_Limit
 procedure Make
 subtype Name
 type Unit_State



 @node !Commands.Compilation.Promote_Scope

 type Promote_Scope is (Single_Unit, Unit_Only, Subunits_Too,
                        All_Parts, Load_Views);

 DESCRIPTION

 Defines the units, related directly or indirectly to the specified unit(s),
 that are included in a promote operation.

 The number of units involved in a promotion increases with increasing
 Promote_Scope values. At the minimum (Single_Unit), only the specified
 units are promoted. At the maximum (All_Parts), the specified units;
 their corresponding parts (both specification and body); their subunits;
 and the specification, body, and subunits of the units they with are
 promoted. The scope Load_Views is available to facilitate development in
 multiple subsystems.


 ENUMERATIONS
     

 Single_Unit

 Specifies that only the named unit be promoted. If the named unit is a unit
 body, the corresponding specification is also promoted; however, if a
 specification is named, its corresponding body is not promoted. Subunits of
 the named unit and units withed by the named unit are not promoted. Use
 this scope if you know that all of the withed units are already at or
 above the goal state.


 Unit_Only

 Specifies that the named unit and the specifications of any units it withs
 be promoted. If the named unit is a unit body, the corresponding
 specification is also promoted; however, if a specification is named, the
 corresponding body is not promoted. Subunits are not promoted.


 Subunits_Too

 Specifies that the named unit and the specifications of any units it withs
 be promoted. If the named unit is a unit body, its subunits and the
 corresponding specification are also promoted; however, if a specification
 is named, the corresponding body and subunits are not promoted.


 All_Parts

 Specifies that the named unit, its corresponding units, and all parts of
 any units they with be promoted. Whether the named unit is a body or a
 specification, its corresponding part is promoted. In all cases, subunits
 are promoted as well. If the unit has other units in its with clause, the
 specifications, bodies, and subunits of those other units are promoted
 also.


 Load_Views

 Specifies that related units in load views be promoted. Normally, when a
 unit in one subsystem references a unit in another subsystem, operations
 on the withing unit affect only the withed unit's specification in the
 exporting spec view. The Load_Views scope causes operations on the calling
 unit to also affect the withed unit's implementation in the associated
 load view. The associated load view is determined by the default activity
 file. Thus, the default activity must contain the appropriate references in
 at least the subsystem and load-view columns.

 All units in the associated load view are potentially affected whether or
 not they are needed to maintain the compilation order. If the load-view
 units have other units in their with clauses, the visible parts, bodies,
 and subunits of those other units are promoted also.


 RESTRICTIONS

 The units to be promoted must also be within the specified limit. Units
 outside the limit are not promoted even if they are within the specified
 scope. See subtype Change_Limit for further information.

 To use the scope Load_Views, the default activity must contain appropriate
 references in both the spec-view and the load-view columns. References
 in the subsystem and load-view columns are not sufficient.


 EXAMPLES

 For examples of the effects of the Scope parameter, see "Controlling the
 Extent of Compilation Commands," in the introduction to this package.


 REFERENCES
                                                                           
 procedure Make
 procedure Promote



 @node !Commands.Compilation.Same_Directories

 Same_Directories : constant Change_Limit := "<DIRECTORIES>";

 
 DESCRIPTION

 Defines a constant that serves as a value for the Limit parameter.

 This constant is retained for compatibility with previous releases and is
 equivalent to the special value "<DIRECTORIES>" and the constant
 Current_Directory.

 The Same_Directories constant specifies that the state may be changed for
 units in the same library as a unit named to the procedure.


 REFERENCES

 subtype Change_Limit
 constant Current_Directory



 @node !Commands.Compilation.Same_World

 Same_World : constant Change_Limit := Same_Worlds;

 DESCRIPTION

 Defines a constant that serves as a value for the Limit parameter.

 This constant is retained for compatibility with previous releases and is
 equivalent to the special value "<WORLDS>" and the constant Same_Worlds.

 The Same_World constant specifies that the state can be changed for units
 in the same world as a unit named to the procedure.


 REFERENCES

 subtype Change_Limit
 constant Same_Worlds



 @node !Commands.Compilation.Same_Worlds

 Same_Worlds : constant Change_Limit := "<WORLDS>";

 DESCRIPTION

 Defines a constant that serves as a value for the Limit parameter.

 This constant is retained for compatibility with previous releases and is
 equivalent to the special value "<WORLDS>" and the constant Same_World.

 The Same_Worlds constant specifies that the state can be changed for units
 in the same world as a unit named to the procedure.


 REFERENCES

 subtype Change_Limit
 constant Same_World



 @node !Commands.Compilation.Set_Target_Key

 procedure Set_Target_Key (The_Key  : String := "?";
                           To_World : String := "<IMAGE>";
                           Response : String := "<PROFILE>");

 DESCRIPTION

 Assigns the specified target key to the specified world.

 If default parameter values are used, this procedure displays a table of
 information about the target keys that are registered and available on the
 system. The first column, "Composite Name," lists the names of the
 available target keys. The remaining columns are of interest only to
 Rational personnel. The table is sent to Current_Output, which is, by
 default, an Environment output window.

 This procedure can be used to assign any registered target key to a newly
 created world that has no links. However, after a target key has been
 assigned to the world either explicitly or implicitly, that target key can
 be changed only to a compatible target key. (A compatible target key
 specifies the same target with a different programming design language
 (PDL); Rational_2167A_Mc68020_Bare and Mc68020_Bare are compatible,
 whereas neither of these is compatible with R1000.) In a newly created
 world, a target key is set implicitly the first time a link is added or a
 unit is semanticized.

 Methods other than this procedure are recommended for changing target keys
 in existing worlds and views. To change the compiler used in a world, you
 can copy the world, specifying a predefined model world that has the
 desired target key. To change the compiler used in a view, you can create
 a new path, specifying an appropriate model world. To change the PDL
 used in a world or view, you can use commands from package Design or
 Design_Implementation.

 For further information about target keys, see the introduction to this
 package and Chapter 3, "Tailoring the Compilation Setting," in this book.
 See the introduction to package Library or the Key Concepts of the Project
 Management (PM) book for a discussion of model worlds. See the family of
 Rational Design Facility manuals for information about PDLs.


 PARAMETERS

 The_Key : String := "?";

 Specifies the name of the target key to which the world is to be set. The
 default, "?", causes a list of all available keys to be displayed.


 To_World : String := "<IMAGE>";

 Specifies the name of the world for which the target key is to be set. The
 default is the current selection or, if no selection exists, the world
 enclosing the current 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.


 RESTRICTIONS

 After a target key has been explicitly or implicitly set for a world, it
 can be changed only to a compatible target key. A policy error is
 displayed if you attempt to change the target key to an incompatible
 target key. A compatible target key specifies the same target with a
 different PDL.


 REFERENCES

 procedure Get_Target_Key
 procedure Show_Target_Key



 @node !Commands.Compilation.Show_Target_Key

 procedure Show_Target_Key (For_World : String := "<IMAGE>";
                            Response  : String := "<PROFILE>");

 DESCRIPTION

 Displays in the message window the target key for the specified world.

 This procedure is intended for interactive use. To obtain the value of the
 target key for programmatic use, see function Get_Target_Key.


 PARAMETERS

 For_World : String := "<IMAGE>";

 Specifies the name of the world whose target key is to be displayed. The
 name specified must resolve to a single world. The default is the world
 displayed in the current window.


 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 Get_Target_Key
 procedure Set_target_Key



 @node !Commands.Compilation.Unit_Name

 subtype Unit_Name is String;

 DESCRIPTION

 Defines the name for an Ada unit or set of units to be used in the Unit
 parameter in procedures in this package.

 A parameter of the Unit_Name subtype may designate Ada units, worlds,
 directories, views, or activities. If a world, directory, or view is
 named, all units contained by that world or directory are operated on. If
 an activity is named, all units in views referenced by that activity are
 operated on. Multiple units can be specified using wildcards, indirect
 files, context prefixes, set notation, and attributes.

 Note that if the operation is a delete or destroy operation and a world or
 directory is specified, that world or directory is also deleted or
 destroyed. You should not specify a view for a parameter of the Unit_Name
 subtype in delete or destroy operations. Views and their contents should
 be removed using the Cmvc.Destroy_View procedure (see the Project
 Management (PM) book).

 See the Parameter-Value Conventions tabbed section in the Reference
 Summary (RS) for more information about referencing Environment objects.



 @node !Commands.Compilation.Unit_State

 type Unit_State is (Archived, Source, Installed, Coded);

 DESCRIPTION

 Defines the compilation states of an Ada unit.

 This type defines four states: archived, source, installed, and coded.
 These states are ordered from low to high, with archived being the lowest
 and coded being the highest. The archived state is available for compact
 storage of units that are not of current interest. The next three states
 (source, installed, and coded) represent three distinct phases in the
 compilation of Ada units. A unit must be promoted from source (or
 archived) through installed to coded before it can execute.

 In addition to reflecting the degree to which that unit is compiled and
 ready for execution, unit states also determine what editing operations
 are allowed on the unit and whether the unit can be referenced in with
 clauses of other units.

 The state of an Ada unit can be changed using procedures from this
 package, package Ada, and package Common (packages Ada and Common are
 contained in the Editing Specific Types (EST) book).

 For further information about unit states and their role in compiling Ada
 units, see Chapter 2, "Compiling Programs in the Environment."


 ENUMERATIONS


 Archived

 Defines a unit state. Units in this state are saved in a text-only format
 and therefore are more compact in size than units in other states.
 Archived units are not necessarily syntactically correct or semantically
 consistent, cannot be edited, cannot be referenced by any other units, and
 do not have the definition capability and structure-oriented highlighting
 that is available to units in the source, installed, and coded states.


 Coded

 Defines a unit state. A unit in this state is completely compiled and ready
 to be executed. The unit can be referenced by any other unit according to
 Ada visibility rules. Thus, it can be deleted, moved, renamed, or demoted
 only if no semantic dependencies are affected.

 Arbitrary editing operations are not allowed on coded units. Coded-unit
 specifications can be modified only by using incremental operations, which
 check for dependencies to prevent the invalidation of the Ada system.
 Coded-unit bodies must be demoted to the installed state for editing. See
 Editing Specific Types (EST), Ada Images, for more information about
 editing Ada units.

 A coded unit must be syntactically correct and semantically consistent
 (that is, it must be capable of being installed); however, it need not be
 complete. That is, a coded unit can contain [statement], [declaration], or
 [expression] prompts such as those inserted by Ada.Create_Body and 
 Common.Format operations. Coding a unit that contains prompts 
 causes the compiler to raise
 warnings such as Prompt encountered on statement list, and it causes the
 code generator to generate code that will raise Program_Error when the
 prompt is encountered during execution.

 Coding the specification of a unit does not have the same effect as coding
 its body. Specifically, coding a body generates code for that unit and code
 to elaborate declarations in the corresponding specification. Coding a
 specification for the R1000 target results in information being computed
 about the specification that allows its dependents to be coded but does
 not generate executable code. (Note that this may not apply when using
 Rational's family of Cross-Development Facility (CDF), Rational
 Compilation Integrator (RCI), or Target Build Utility (TBU) products. See
 the appropriate CDF, RCI, or TBU manual for details about coding units
 using those products.)


 Installed

 Defines a unit state. Installing a unit establishes dependencies between
 that unit and units it withs. Installing a unit also allows other units to
 reference it in with clauses without incurring semantic errors. Because
 their dependencies have been established, installed units can be deleted,
 moved, renamed, or demoted only if no semantic dependencies are affected.

 Arbitrary editing operations are not allowed on installed units. Installed
 units can be modified only by using incremental operations, which check for
 dependencies to prevent the invalidation of the Ada system. For a list of
 the incremental operations that can be performed on installed units, see
 Editing Specific Types (EST), Ada Images, or Appendix F for the R1000
 Target in the Reference Manual for the Ada Programming Language (Ada LRM).

 An installed unit need not be complete. That is, a unit can contain
 [statement], [declaration], or [expression] prompts such as those inserted
 by the Ada.Create_Body and Common.Format operations.

 Installing a unit for the first time performs two special operations:

 *  Installing a unit replaces the temporary name assigned by the
    Environment (for example, _Ada_8_ ) with the unit's Ada name (for
    example, Factorial). The Ada name then remains in the library even if
    you demote the unit to source again.

 *  By default, if the unit is a subprogram body for which a specification
    does not exist, installing the unit automatically creates its
    specification. (This practice is controlled by the
    Directory.Create_Subprogram_Specs library switch.)

 Note that when you promote the body of a library-level subprogram to the
 installed state after changing the parameter profile, a new subprogram
 specification is created and promoted. In the new specification, pragmas and
 full-line comments from the existing specification are preserved, whereas
 comments to the right of context clauses or the parameter profile are lost.
 This practice reduces the number of steps it takes to make changes to
 the parameter profile of a subprogram. Note that if the existing
 specification is frozen or checked in, the existing specification is
 retained; a new specification is not created.


 Source

 Defines a unit state. At creation, Ada units are in the source state. The
 source state is used for entering most of the code. Thus, a unit in this
 state may or may not be syntactically correct or semantically consistent.

 In the source state, arbitrary editing is allowed using text editing
 operations. In addition, Ada-specific editing operations can be used to
 interactively detect and correct syntactic and semantic errors such as
 missing punctuation, misspelled keywords, improper references to other
 units (for example, incorrect parameter types), and unresolved Ada
 identifiers.

 A source unit is not semantically known to other units. This means that
 none of the types, procedures, and functions that are exported from this
 unit can be used or called by any other units. Source units cannot be
 referenced in with clauses by units in higher states. Furthermore, changes
 to units in the source state do not affect other units in the system;
 source units can be copied, deleted, or moved without making other units
 obsolete.

 When created, units appear in the library under a temporary name assigned
 by the Environment. This temporary name has the form _Ada_n_, where n is
 some integer. When a unit is promoted to the installed state for the
 first time, its Ada name (for example, Factorial) is listed in the
 enclosing library, replacing the temporary name. After the Ada name has
 been entered in the library, that name remains in the library even when
 the unit is demoted back to the source state. For this reason, source
 units that have never been installed can be renamed arbitrarily, but
 source units that have been installed can be renamed only by withdrawing
 them from the library (see information about changing the name of a unit
 in Rational Environment Basic Operations).



 @node !Commands.File_Utilities

 Package File_Utilities provides a set of commands for comparing,
 examining, and/ or manipulating the contents of various Environment
 objects. These commands operate on text files, Ada units, and libraries
 (any objects that can be opened for text input and output).


 RESOURCES IN PACKAGE FILE_UTILITIES

 The commands in package File_Utilities fall into several functional
 groups. Types and constants are not included in this list.

 Determining whether two objects are different or the same: Compare, Equal

 Listing the differences between two objects:               Difference

 Combining the contents of two objects:                  Append, Merge, Strip

 Searching the contents of an object:                    Find, Found

 Displaying the hexadecimal representation of an object: Dump

 Sorting an object's contents:                           Sort


 KEY CONCEPTS FOR PACKAGE FILE_UTILITIES

 Package File_Utilities contains commands that compare two objects (Compare
 and Equal) and commands that search objects for strings (Find and Found).
 These four commands can use either of two types of matching to compare
 Environment objects. Specifically, you can specify that these commands
 use literal string matching or pattern matching.


 Literal String Matching

 By default, the Compare, Equal, Find, and Found commands involve matching
 literal strings. The Compare procedure and the Equal function compare the
 contents of two objects line by line; objects are considered equal only
 if corresponding lines are literally identical. Similarly, the Find
 procedure and the Found function compare a literal string against an
 object's contents; the string is found only if it literally matches a
 string in the object.


 Pattern Matching

 The comparison and search commands also provide an option that permits
 pattern matching. When pattern matching is used, two strings are
 considered equal if one string matches the general form or pattern
 specified by the other. Rather than requiring literal
 character-for-character identity, pattern matching tolerates certain
 differences between strings that are judged to be equal.

 The pattern-matching option in the Compare or Equal command makes it
 possible to set up a template object against which to compare other
 objects. For example, assume that you are running tests and you want to
 make sure that these tests are generating the correct log messages. You
 can do this by setting up a template file against which each log file is to
 be compared. The template file contains the literal text for the desired
 log messages with patterns substituted for the literal dates and times. In
 this way, the actual date and time stamp in each log message is disre-
 garded when the log message is compared to the template.

 The patterns in template objects and strings are defined by combinations of
 literal characters and wildcard characters. Wildcard characters are
 specially interpreted characters that stand for particular classes of
 characters or for particular locations in a string. The wildcards that are
 available for constructing patterns are listed in Table 1. Note that the
 wildcard characters that can be used in file utilities differ from the
 wildcard characters that can be used when specifying pathnames as
 parameter values.

             Table 1   Wildcard Characters for Pattern Matching
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches any single character.           |
             ----------------------------------------------- 
            |      |                                        |
            |  %   |Matches any single character that is    |
            |      |legal in an Ada identifier.             |
             ----------------------------------------------- 
            |      |                                        |
            |  $   |Matches Ada delimiters: & ' ( ) * + , - |
            |      |. / : ; < = > | When used outside       |
            |      |set-delimiter brackets ([]), $ matches  |
            |      |beginning and end of line as well.      |
             ----------------------------------------------- 
            |      |                                        |
            |  \   |Quotes the next wildcard character,     |
            |      |causing it to have a literal (not a     |
            |      |wild- card) interpretation. \ must      |
            |      |immediately precede the wildcard it     |
            |      |quotes.                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  {   |Allows the pattern to match strings only|
            |      |if they start at the beginning of a     |
            |      |line. { must appear at the beginning of |
            |      |the pattern; otherwise, it has a literal|
            |      |meaning.                                |
             ----------------------------------------------- 
            |      |                                        |
            |  }   |Allows the pattern to match strings only|
            |      |if they terminate at the end of a line. |
            |      |} must appear at the end of the pattern;|
            |      |otherwise, it has a literal meaning.    |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Defines a set of characters, of which an|
            |      |one may be matched. The set             |
            |      |can be an explicit list (for example,   |
            |      |[ABCDE]) or a range (for example,       |
            |      |[A-Z]).                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  ^   |Excludes the next character or set of   |
            |      |characters; ^a matches any character    |
            |      |other than a, and ^[abc] or [^abc]      |
            |      |matches any character other than a, b,  |
            |      |or c.                                   |
             ----------------------------------------------- 
            |      |                                        |
            |  *   |Matches zero or more occurrences of the |
            |      |previous character or set of characters.|
             ----------------------------------------------- 



 For example, assume that the output of a program should contain two
 three-letter usernames, each followed by a two-digit integer greater than
 50. The two entries must be at the beginning of two separate lines. To
 check the validity of a given output file, you can use the Compare
 procedure or the Equal function to compare the output file to a template
 file containing the following pattern:

   {[A-Z][A-Z][A-Z][5-9][0-9]
   {[A-Z][A-Z][A-Z][5-9][0-9]

 This template file will match an output file that has the following
 contents:

   GZC52
   SJL99

 However, differences will be found between this template file and any
 output file containing lowercase letters, numbers lower than 50 or higher
 than 99, or entries that are indented.


 @node !Commands.File_Utilities.Append

 procedure Append (Source : Name := "";
                   Target : Name := "<SELECTION>");

 DESCRIPTION

 Appends one or more source files to the target file.

 This procedure can operate only on text files. The contents of the source
 file(s) are inserted at the end of the target file, modifying the target
 file. The source file is not changed.


 PARAMETERS

 Source : Name := "";

 Specifies the file or files to append to the target file. Multiple objects can
 be specified using wildcards, context characters, set notation, indirect
 files, and attributes. The default null string resolves to the current
 library image, so it should be
 replaced.


 Target : Name := "<SELECTION>";

 Specifies the name of the file to which the source file(s) are to be
 appended. Only a single file can be specified. The default is the currently
 selected file. If the file does not exist, it is created. If the target file
 already exists, a new version is created. Because the target file is
 modified, you must have write access to it.


 ERRORS

 Common errors include specification of a source file that does not exist.


 EXAMPLES

 The following command appends the contents of File_1 to the end of File_2.
 The original contents of File_2 remain at the beginning of the file and are
 followed by the contents of File_1. File_1 itself is not modified.

   File_Utilities.Append ("File_1","File_2");


 @node !Commands.File_Utilities.Compare

 procedure Compare (File_1      : Name    := "<REGION>";
                    File_2      : Name    := "<IMAGE>";
                    Subobjects  : Boolean := False);
                    Ignore_Case : Boolean := False);
                    Options     : String  := "");

 DESCRIPTION

 Reports whether two objects are the same or different.

 The job report is sent to Current_Output (by default, an Environment
 output window). Errors are indicated in log messages, which, by default,
 are also sent to the output window.

 By default, the Compare procedure considers two objects to be the same
 only if they are literally identical. Alternatively, the Options parameter
 can be set to permit pattern matching. When the File_2_Has_Wildcards
 option is used, File_2 can contain wildcards to define a pattern or template 
 against which File_1 is compared. See the introduction to this package for 
 information on pattern matching. The wildcard characters that can be used 
 in File_2 are listed in Table 2.


             Table 2   Wildcard Characters for Pattern Matching
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches any single character.           |
             ----------------------------------------------- 
            |      |                                        |
            |  %   |Matches any single character that is    |
            |      |legal in an Ada identifier.             |
             ----------------------------------------------- 
            |      |                                        |
            |  $   |Matches Ada delimiters: & ' ( ) * + , - |
            |      |. / : ; < = > | When used outside       |
            |      |set-delimiter brackets ([]), $ matches  |
            |      |beginning and end of line as well.      |
             ----------------------------------------------- 
            |      |                                        |
            |  \   |Quotes the next wildcard character,     |
            |      |causing it to have a literal (not a     |
            |      |wildcard) interpretation. \ must      |
            |      |immediately precede the wildcard it     |
            |      |quotes.                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  {   |Allows the pattern to match strings only|
            |      |if they start at the beginning of a     |
            |      |line. { must appear at the beginning of |
            |      |the pattern; otherwise, it has a literal|
            |      |meaning.                                |
             ----------------------------------------------- 
            |      |                                        |
            |  }   |Allows the pattern to match strings only|
            |      |if they terminate at the end of a line. |
            |      |} must appear at the end of the pattern;|
            |      |otherwise, it has a literal meaning.    |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Defines a set of characters, of which an|
            |      |one may be matched. The set             |
            |      |can be an explicit list (for example,   |
            |      |[ABCDE]) or a range (for example,       |
            |      |[A-Z]).                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  ^   |Excludes the next character or set of   |
            |      |characters; ^a matches any character    |
            |      |other than a, and ^[abc] or [^abc]      |
            |      |matches any character other than a, b,  |
            |      |or c.                                   |
             ----------------------------------------------- 
            |      |                                        |
            |  *   |Matches zero or more occurrences of the |
            |      |previous character or set of characters.|
             ----------------------------------------------- 



 PARAMETERS

 File_1 : Name := "<REGION>";

 Specifies the first object or set of objects to be compared. Text files, Ada
 units, or libraries can be specified. The default is the currently
 highlighted object. Multiple objects can be specified using wildcards,
 context characters, set notation, indirect files, and attributes.


 File_2 : Name := "<IMAGE>";

 Specifies the second object or set of objects to be compared. The default
 is the object whose image contains the cursor. Substitution characters can
 be used to specify multiple objects. If you specify multiple File_1
 objects and a single File_2 object, every File_1 object is compared to the
 File_2 object. If you specify multiple File_1 objects and multiple File_2
 objects, each File_1 object is compared to the corresponding File_2
 object.

 When the File_2_Has_Wildcards option is set, the object(s) named by File_2
 can contain patterns defined by wildcards. (Wildcards for pattern matching
 are listed in "Description," above.) In this case, File_2 acts as a
 template against which File_1 is compared.


 Subobjects : Boolean := False;

 Specifies whether to include any subobjects of the two named objects in the
 comparison. The default is not to compare any subobjects.


 Ignore_Case : Boolean := False;

 Specifies whether to consider case when comparing the two objects. When the
 value is False (the default), the words "Package" and "package" are
 considered different. When True, these words are considered to be the
 same.


 Options : String := "";

 Specifies the options to be used. These two options cannot be used
 together. The default null string specifies that no options will be used.


 *  File_2_Has_Wildcards

    Specifies that pattern matching is used. Thus, File_2 can contain the
    wildcards described in "Description," above.


 *  Ignore_Blank_Lines

    Allows matching even though one file contains blank lines and the other
    does not contain blank lines.


 ERRORS

 Common errors are specifying a file that does not exist or specifying an
 invalid option.


 EXAMPLES

 Assume that File_1 is a proper subset of File_2. That is, File_1 contains
 the following two lines:

   GZC52
   SJL99

 and File_2 contains the following three lines:

   GZC52
   SJL99
   CRW77

 Then the following command produces the output below:

   File_Utilities.Compare ("File_1","File_2");

   !USERS.RJB.FILE_1 is a prefix of !USERS.RJB.FILE_2

 Assume that File_1 and File_2 conflict. That is, File_1 contains the
 following:

   GZC52
   SJLxxx

 whereas File_2 contains the following:

   GZC52
   SJL99

 Then the following command produces the output below:

   File_Utilities.Compare ("File_1","File_2");

   !USERS.RJB.FILE_1 and !USERS.RJB.FILE_2 differ at line 2, byte 11.

 REFERENCES

 procedure Difference



 @node !Commands.File_Utilities.Current_Output

 Current_Output : constant Name := "";

 DESCRIPTION

 Defines a constant to represent the current output file.

 This constant is used by many commands in this package that direct output
 to Current_Output. By default, this file is an Environment output window.

 The value of this constant is the same as that defined in Io.Current_Output
 and Text_Io.Current_Output.



 @node !Commands.File_Utilities.Difference

 procedure Difference (File_1            : Name    := "<REGION>";
                       File_2            : Name    := "<IMAGE>";
                       Result            : Name    := "";
                       Compressed_Output : Boolean := False;
                       Subobjects        : Boolean := False);

 DESCRIPTION

 Lists the differences between two objects.

 By default, the job report is sent to Current_Output (by default, an
 Environment output window). You can redirect the job report using the
 Result parameter. Errors are indicated in log messages, which, by default,
 are also sent to the output window. Log messages are not affected by the
 Result parameter.

 By default, the output is uncompressed--that is, every line from each
 object appears in the output. Setting the Compressed_Output parameter to
 True causes the procedure to show only the differences, omitting lines
 that are the same in both objects.

 In both compressed and uncompressed output, the origin of each line is
 indicated by a character in column 1. A line that appears only in the first
 object has a 1 in column 1. Likewise, a line that appears only in the
 second object has a 2 in column 1. In uncompressed output, a line that
 is identical in both objects has a space in column 1. For legibility, all
 lines have a space in column 2 regardless of origin. The actual text of
 each input line begins in column 3 of the output file.

 Besides listing the lines in which File_1 and File_2 differ, compressed
 output contains a list of instructions for converting File_1 to File_2.
 Each instruction begins with an asterisk in column 1. There are three
 kinds of instructions:

 *  Insertions specify a line number in File_1 and a set of lines from
    File_2. To convert File_1 into File_2, you would insert the specified
    set of lines into File_1 following the line with the specified number.

 *  Deletions specify a series of line numbers in File_1. To convert File_1
    into File_2, you would delete the specified lines from File_1.

 *  Changes specify a series of line numbers and a set of lines from File_1
    to be changed to a set of lines from File_2. The two sets of lines are
    separated by dashes.

 The line numbers used in insertion, deletion, and change instructions
 refer to the original files. They do not reflect changes in numbering that
 may result from actually following the instructions.

 Either of the input objects can be reconstructed directly from a file
 containing uncompressed output. To reconstruct File_1, you can delete
 every line in the output file that begins with a 2 and then delete the first
 two columns of every remaining line. Likewise, to reconstruct File_2, you
 can delete every line in the output file that begins with a 1 and then
 delete the first two columns of every remaining line. The Strip procedure
 defined in this package is useful for automating this process.


 PARAMETERS

 File_1 : Name := "<REGION>";

 Specifies the name of the first object or set of objects to be compared.
 Text files, Ada units, or libraries can be specified. Multiple objects can
 be specified using wildcards, context characters, set notation, indirect
 files, and attributes. The default is the currently highlighted object.


 File_2 : Name := "<IMAGE>";

 Specifies the name of the second object or set of objects to be compared.
 The default is the object whose image contains the cursor. Substitution
 characters can be used to specify multiple objects. If you specify
 multiple File_1 objects and a single File_2 object, every File_1 object is
 compared to the File_2 object. If you specify multiple File_1 objects and
 multiple File_2 objects, each File_1 object is compared to the
 corresponding File_2 object.


 Result : Name := "";

 Specifies the file to which to direct the job report. The default is to
 write to Current_Output (by default, an Environment output window).

 Note that errors are reported as log messages, which are not redirected by
 this parameter. To redirect both log messages and the job report, leave
 the Result parameter with its default value and enter the
 !Commands.Log.Set_Output procedure in the same command window as the
 Difference procedure, specifying the location to which to direct output.


 Compressed_Output : Boolean := False;

 Specifies the use of the compressed form of output. The default is not to
 use the compressed form.


 Subobjects : Boolean := False;

 Specifies whether to include any subobjects of the two named objects in the
 comparison. The default is not to compare any subobjects.


 ERRORS

 Common errors include specification of a file that does not exist.


 EXAMPLES

 The following display shows uncompressed output:

   91/03/27 12:48:33 ::: [File_Utilities.Difference ("<REGION>", "<C>", "",
   91/03/27 12:48:33 ... FALSE, FALSE)].
   * Object 1: !USERS.JAF.FILE_1
   * Object 2: !USERS.JAF.FILE_2

     In uncompressed output, all lines from both files
     appear in the output
     in one of three forms:
     This line is common to both files.
   1 This line appears only in the first file.
   2 This line appears only in the second file.

   91/03/27 12:48:34 ::: [end of File_Utilities.Difference].

 Below is an example of compressed output:

   91/03/27 12:47:31 ::: [File_Utilities.Difference ("<REGION>", "<C>", "",
   91/03/27 12:47:31 ... TRUE, FALSE)].
   * Object 1: !USERS.JAF.FILE_3
   * Object 2: !USERS.JAF.FILE_4
   * Delete 1..4
   1 In compressed output only the lines
   1 that are particular to a specific
   1 file are included in the output.
   1

   * Insert after 6
   2
   2 Lines that are inserted
   2 come after the instruction
   2 and their line numbers.

   * Change 8..10
   1 When lines have been changed,
   1 both the original lines and
   1 the new lines are shown
   -----
   2 separated by dashes.

   * Delete 12..13
   1 The lines that are deleted
   1 come after the description.
   91/03/27 12:47:32 ::: [end of File_Utilities.Difference].

 REFERENCES

 procedure Compare
 function Equal
 Session and Job Management (SJM), procedure Log.Set_Output



 @node !Commands.File_Utilities.Dump

 procedure Dump (File        : Name     := "<SELECTION>";
                 Page_Number : Natural  := 0;
                 Word_Number : Natural  := 0;
                 Word_Count  : Positive := 64);

 DESCRIPTION

 Displays the hexadecimal representation of the specified file.

 This procedure displays the specified number of 128-bit words beginning at
 the specified word number (0 through 3F hexadecimal per page) in the
 specified page of the file. Each word is displayed as eight 16-bit sections. 
 The address of the word is displayed to the left of the word. The ASCII
 equivalent of that word is displayed in the righthand column. 
 Nonprintable characters are displayed as vertical bars (|).


 PARAMETERS

 File : Name := "<SELECTION>";

 Specifies the name of the file to be displayed. The name must resolve to a
 single file. The default is the current selection, provided that it
 contains the cursor. Any kind of file can be specified; however, if the name
 specifies an object other than a file, an error occurs.


 Page_Number : Natural := 0;

 Specifies the first page to be displayed. Pages are numbered from 0 and each
 page consists of 64 (40 hex) 128-bit words. The default is page 0 (the
 beginning of the file).


 Word_Number : Natural := 0;

 Specifies the first word to be displayed. The default is word 0 (the first
 word of the page).


 Word_Count : Positive := 64;

 Specifies the number of words to be displayed. The default is 64 words or
 one page.


 ERRORS

 Errors can occur if the file does not end on a byte boundary. An error
 occurs only when an attempt is made to display that last partial byte.


 EXAMPLES

 The following command produces the display below and sends it to an
 Environment output window:

   File_Utilities.Dump ("Attributes",1,16#2b#,4);

   Page 1
     2B0  2020 203A 2054 5255 450A 5245 434F 5645     : TRUE|RECOVE
     2C0  5259 5F4C 4F43 414C 4954 5920 2020 203A  RY_LOCALITY    |
     2D0  2020 3132 0A44 4546 4155 4C54 5F45 4C49    12|DEFAULT_ELI
     2E0  5349 4F4E 2020 2020 2020 3A20 5452 5545  SION      | TRUE


 @node !Commands.File_Utilities.Equal

 function Equal (File_1      : Name    := "<REGION>";
                 File_2      : Name    := "<IMAGE>";
                 Subobjects  : Boolean := False;
                 Ignore_Case : Boolean := False;
                 Options     : String  := "")     return Boolean;

 DESCRIPTION

 Indicates whether two objects are the same or different.

 This function returns True if the two objects are the same and False if
 they are different.

 By default, the Equal function considers two objects to be the same only
 if they are textually identical. Alternatively, the Options parameter can
 be set to permit pattern matching. When the File_2_Has_Wildcards option is
 used, File_2 can contain wildcards to define a pattern or template
 against which File_1 is compared. See the introduction to this package for
 information on pattern matching. The wildcard characters that can be used
 in File_2 are listed in Table 3.

             Table 3   Wildcard Characters for Pattern Matching
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches any single character.           |
             ----------------------------------------------- 
            |      |                                        |
            |  %   |Matches any single character that is    |
            |      |legal in an Ada identifier.             |
             ----------------------------------------------- 
            |      |                                        |
            |  $   |Matches Ada delimiters: & ' ( ) * + , - |
            |      |. / : ; < = > | When used outside       |
            |      |set-delimiter brackets ([]), $ matches  |
            |      |beginning and end of line as well.      |
             ----------------------------------------------- 
            |      |                                        |
            |  \   |Quotes the next wildcard character,     |
            |      |causing it to have a literal (not a     |
            |      |wild- card) interpretation. \ must      |
            |      |immediately precede the wildcard it     |
            |      |quotes.                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  {   |Allows the pattern to match strings only|
            |      |if they start at the beginning of a     |
            |      |line. { must appear at the beginning of |
            |      |the pattern; otherwise, it has a literal|
            |      |meaning.                                |
             ----------------------------------------------- 
            |      |                                        |
            |  }   |Allows the pattern to match strings only|
            |      |if they terminate at the end of a line. |
            |      |} must appear at the end of the pattern;|
            |      |otherwise, it has a literal meaning.    |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Defines a set of characters, of which an|
            |      |one may be matched. The set             |
            |      |can be an explicit list (for example,   |
            |      |[ABCDE]) or a range (for example,       |
            |      |[A-Z]).                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  ^   |Excludes the next character or set of   |
            |      |characters; ^a matches any character    |
            |      |other than a, and ^[abc] or [^abc]      |
            |      |matches any character other than a, b,  |
            |      |or c.                                   |
             ----------------------------------------------- 
            |      |                                        |
            |  *   |Matches zero or more occurrences of the |
            |      |previous character or set of characters.|
             ----------------------------------------------- 



 PARAMETERS

 File_1 : Name := "<REGION>";

 Specifies the first object or set of objects to be compared. Text files, Ada
 units, or libraries can be specified. The default is the currently
 highlighted object. Multiple objects can be specified using wildcards,
 context characters, set notation, indirect files, and attributes.


 File_2 : Name := "<IMAGE>";

 Specifies the second object or set of objects to be compared. The default
 is the object whose image contains the cursor. Substitution characters can
 be used to specify multiple comparison objects.

 If you specify multiple File_1 objects and a single File_2 object, every
 File_1 object is compared to the File_2 object. If you specify multiple
 File_1 objects and multiple File_2 objects, each File_1 object is compared
 to the corresponding File_2 object.

 When the File_2_Has_Wildcards option is set, the object named by File_2
 can contain patterns defined by wildcards. (Wildcards for pattern matching
 are listed in "Description," above.) In this case, File_2 acts as a
 template against which File_1 is compared.


 Subobjects : Boolean := False;

 Specifies whether to include any subobjects of the two named objects in the
 comparison. The default is not to compare any subobjects.


 Ignore_Case : Boolean := False;

 Specifies whether to consider case when comparing the two objects. When the
 value is False (the default), the words "Package" and "package" are
 considered different. When True, these words are considered to be the
 same.


 Options : String := "";

 Specifies the options to be used. These two options cannot be used
 together. The default null string specifies that no options will be used.


 *  File_2_Has_Wildcards

    Specifies that pattern matching is used. Thus, File_2 can contain the
    wildcards listed in "Description," above.


 *  Ignore_Blank_Lines

    Allows matching even though one file contains blank lines and the other
    does not.


 return Boolean;

 Returns True if the two objects are the same. If multiple File_1 objects
 are compared to one or more File_2 objects, each pair of objects must be
 evaluated as equal for this function to return True. Otherwise, the
 function returns False.


 ERRORS

 Common errors include specification of a file that does not exist or
 specification of an invalid option.


 EXAMPLES

 Consider the following sample section of a procedure:

   declare
       Is_Equal : Boolean := False;
   begin
       Is_Equal := File_Utilities.Equal
                     (File_1     => "foo", File_2 => "bar",
                      Subobjects => False, Ignore_Case => True,
                      Options    => "Ignore_Blank_Lines");

 The Is_Equal variable will be set to True if files Foo and Bar are
 identical, with the following two qualifications: case will not be
 considered as a factor in the match, and blank lines will be ignored in
 making the match.


 REFERENCES

 procedure Compare



 @node !Commands.File_Utilities.Find

 procedure Find (Pattern     : String  := "";
                 File        : Name    := "<IMAGE>";
                 Wildcards   : Boolean := False;
                 Ignore_Case : Boolean := True;
                 Result      : Name    := "");

 DESCRIPTION

 Searches the specified object for strings that match the specified pattern.

 This procedure displays each line that contains a match. By default, the
 job report is sent to Current_Output (by default, an Environment output
 window). You can redirect the job report using the Result parameter.
 Errors are indicated in log messages, which, by default, are also sent
 to the output window. Log messages are not affected by the Result
 parameter.

 By default, the Find procedure searches for the literal string specified by
 the Pattern parameter. If the Wildcards parameter is set to True,
 wildcards can be used in the Pattern parameter to define a pattern to be
 matched. See the introduction to this package for information on pattern
 matching. The wildcard characters that can be used in the Pattern
 parameter are listed in Table 4.

             Table 4   Wildcard Characters for Pattern Matching
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches any single character.           |
             ----------------------------------------------- 
            |      |                                        |
            |  %   |Matches any single character that is    |
            |      |legal in an Ada identifier.             |
             ----------------------------------------------- 
            |      |                                        |
            |  $   |Matches Ada delimiters: & ' ( ) * + , - |
            |      |. / : ; < = > | When used outside       |
            |      |set-delimiter brackets ([]), $ matches  |
            |      |beginning and end of line as well.      |
             ----------------------------------------------- 
            |      |                                        |
            |  \   |Quotes the next wildcard character,     |
            |      |causing it to have a literal (not a     |
            |      |wildcard) interpretation. \ must      |
            |      |immediately precede the wildcard it     |
            |      |quotes.                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  {   |Allows the pattern to match strings only|
            |      |if they start at the beginning of a     |
            |      |line. { must appear at the beginning of |
            |      |the pattern; otherwise, it has a literal|
            |      |meaning.                                |
             ----------------------------------------------- 
            |      |                                        |
            |  }   |Allows the pattern to match strings only|
            |      |if they terminate at the end of a line. |
            |      |} must appear at the end of the pattern;|
            |      |otherwise, it has a literal meaning.    |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Defines a set of characters, of which an|
            |      |one may be matched. The set             |
            |      |can be an explicit list (for example,   |
            |      |[ABCDE]) or a range (for example,       |
            |      |[A-Z]).                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  ^   |Excludes the next character or set of   |
            |      |characters; ^a matches any character    |
            |      |other than a, and ^[abc] or [^abc]      |
            |      |matches any character other than a, b,  |
            |      |or c.                                   |
             ----------------------------------------------- 
            |      |                                        |
            |  *   |Matches zero or more occurrences of the |
            |      |previous character or set of characters.|
             ----------------------------------------------- 



 PARAMETERS

 Pattern : String := "";

 Specifies the pattern for which to search. The pattern can consist of any
 string. When the Wildcards parameter is False, the pattern is interpreted
 literally. When the Wildcards parameter is True, the pattern can contain
 wildcards.


 File : Name := "<IMAGE>";

 Specifies the object in which to search for the pattern. This parameter can
 specify a file, an Ada unit, or a library. Multiple objects can be specified
 using wildcards, context characters, set notation, indirect files, and
 attributes. The default is the object whose image contains the cursor.


 Wildcards : Boolean := False;

 Specifies whether to interpret certain characters in the Pattern parameter
 as wildcard characters (see "Description," above). When the value is
 False (the default), those characters are not interpreted as wildcard
 characters, and the procedure searches for a literal string. When True,
 wildcard characters are interpreted as described above.


 Ignore_Case : Boolean := True;

 Specifies whether to consider case when searching for a match. When the
 value is True (the default), the words "Package" and "package" are
 considered to be a match. When False, these words do not match.


 Result : Name := "";

 Specifies the file to which to direct the job report. The default is to
 write to Current_Output (by default, an Environment output window).

 Note that errors are indicated in log messages, which are not redirected
 by this parameter. To redirect both log messages and the job report, leave
 the Result parameter with its default value and enter the
 !Commands.Log.Set_Output procedure in the same command window as the
 Find procedure, specifying the location to which to direct output.


 ERRORS

 A common error is incorrect specification of the pattern for which to
 search.


 EXAMPLES

 The following command finds the string "section 3" in a file called Test:

   Find ("section 3","test");

 The following command matches anything except the characters A, B, and C
 in a file called Test:

   Find ("[^abc]","test",true);
                            

 REFERENCES

 function Found
 Session and Job Management (SJM), procedure Log.Set_Output



 @node !Commands.File_Utilities.Found

 function Found (Pattern     : String  := "";
                 File        : Name    := "<IMAGE>";
                 Wildcards   : Boolean := False;
                 Ignore_Case : Boolean := True) return Natural;

 DESCRIPTION

 Searches the specified object and reports the number of lines that contain
 matches of the specified pattern.

 By default, the Found function searches for the literal string specified by
 the Pattern parameter. If the Wildcards parameter is set to True,
 wildcards can be used in the Pattern parameter to define a pattern to be
 matched. See the introduction to this package for information on pattern
 matching. The wildcard characters that can be used in the Pattern
 parameter are listed in Table 5.

             Table 5   Wildcard Characters for Pattern Matching
             ----------------------------------------------- 
            |      |                                        |
            |Charac|              Description               |
            | ter  |                                        |
             ----------------------------------------------- 
            |      |                                        |
            |  ?   |Matches any single character.           |
             ----------------------------------------------- 
            |      |                                        |
            |  %   |Matches any single character that is    |
            |      |legal in an Ada identifier.             |
             ----------------------------------------------- 
            |      |                                        |
            |  $   |Matches Ada delimiters: & ' ( ) * + , - |
            |      |. / : ; < = > | When used outside       |
            |      |set-delimiter brackets ([]), $ matches  |
            |      |beginning and end of line as well.      |
             ----------------------------------------------- 
            |      |                                        |
            |  \   |Quotes the next wildcard character,     |
            |      |causing it to have a literal (not a     |
            |      |wild- card) interpretation. \ must      |
            |      |immediately precede the wildcard it     |
            |      |quotes.                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  {   |Allows the pattern to match strings only|
            |      |if they start at the beginning of a     |
            |      |line. { must appear at the beginning of |
            |      |the pattern; otherwise, it has a literal|
            |      |meaning.                                |
             ----------------------------------------------- 
            |      |                                        |
            |  }   |Allows the pattern to match strings only|
            |      |if they terminate at the end of a line. |
            |      |} must appear at the end of the pattern;|
            |      |otherwise, it has a literal meaning.    |
             ----------------------------------------------- 
            |      |                                        |
            |  []  |Defines a set of characters, of which an|
            |      |one may be matched. The set             |
            |      |can be an explicit list (for example,   |
            |      |[ABCDE]) or a range (for example,       |
            |      |[A-Z]).                                 |
             ----------------------------------------------- 
            |      |                                        |
            |  ^   |Excludes the next character or set of   |
            |      |characters; ^a matches any character    |
            |      |other than a, and ^[abc] or [^abc]      |
            |      |matches any character other than a, b,  |
            |      |or c.                                   |
             ----------------------------------------------- 
            |      |                                        |
            |  *   |Matches zero or more occurrences of the |
            |      |previous character or set of characters.|
             ----------------------------------------------- 



 PARAMETERS

 Pattern : String := "";

 Specifies the pattern for which to search. The pattern can consist of any
 string. When the Wildcards parameter is False, the pattern is interpreted
 literally. When the Wildcards parameter is True, the pattern can contain
 wildcards.


 File : Name := "<IMAGE>";

 Specifies the object in which to search for the pattern. This parameter can
 specify a file, an Ada unit, or a library. Multiple objects can be specified
 using wildcards, context characters, set notation, indirect files, and
 attributes. The default is the object whose image contains the cursor.


 Wildcards : Boolean := False;

 Specifies whether to interpret certain characters in the Pattern parameter
 as wildcard characters (see "Description," above). When the value is
 False (the default), those characters are not interpreted as wildcard
 characters, and the function searches for literal matches. When True,
 wildcard characters are interpreted as described above.


 Ignore_Case : Boolean := True;

 Specifies whether to consider case when searching for a match. When the
 value is True (the default), the words "Package" and "package" are
 considered to be a match. When False, these words do not match.


 return Natural;

 Returns the number of lines in the file that contain matches of the
 pattern.


 ERRORS

 A common error is incorrect specification of the pattern.


 EXAMPLES

 The following function returns the number of lines that contain the string
 "section 3" in the specified file:

   Found ("section 3","test");

 The following function returns the number of lines that contain anything
 except the characters A, B, and C:

   Found ("[^abc]","test",true);
   

 REFERENCES

 procedure Find



 @node !Commands.File_Utilities.Merge

 procedure Merge (Original : Name := "";
                  File_1   : Name := "";
                  File_2   : Name := "";
                  Result   : Name := "");

 DESCRIPTION

 Merges the contents of two objects.

 By default, the job report is sent to Current_Output (by default, an
 Environment output window). You can redirect the job report using the
 Result parameter. Errors are indicated in log messages, which, by default,
 are also sent to the output window. Log messages are not affected by the
 Result parameter.

 This procedure is most useful for merging two objects that are variants
 (modified copies) of an original object. The procedure first compares each
 variant separately to the original object to find out which lines have
 changed. Unchanged lines and lines containing nonconflicting changes are
 merged as is. Lines containing conflicting changes are marked in the
 same format used by the Difference procedure.


 PARAMETERS

 Original : Name := "";

 Specifies the original object against which the two variants are compared.
 A special name such as "<SELECTION>" can be used. Multiple original
 objects can be
 specified with wildcards, provided that multiple pairs of variant objects
 are specified for File_1 and File_2.


 File_1 : Name := "";

 Specifies the first variant object to be merged. Multiple File_1 objects can
 be specified using substitution characters to construct names from the
 Original parameter.


 File_2 : Name := "";

 Specifies the second variant object to be merged. Multiple File_2 objects
 can be specified using substitution characters to construct names from the
 Original parameter.


 Result : Name := "";

 Specifies the file to which to direct the job report. The default is to
 write to Current_Output (by default, an Environment output window).

 Note that errors are indicated in log messages, which are not redirected
 by this parameter. To redirect both log messages and the job report, leave
 the Result parameter with its default value and enter the
 !Commands.Log.Set_Output procedure in the same command window as the
 Merge procedure, specifying the location to which to direct output.


 ERRORS

 The most common error is incorrect specification of a filename.


 EXAMPLES

 The following command merges files Foo and Bar, after comparing them to file
 Original, and places the results in file Result.

   File_Utilities.Merge ("original","foo","bar","result");
   

 REFERENCES

 procedure Difference
 procedure Strip



 @node !Commands.File_Utilities.Name

 subtype Name is String;

 DESCRIPTION

 Defines the names of objects.

 This subtype allows the use of special names, wildcards in the Source
 parameter, context prefixes, and attributes that are defined for general
 naming.

 Special names, wildcards, context characters, and attributes are explained
 in the Parameter-Value Conventions tabbed section in the Reference Summary
 (RS).



 @node !Commands.File_Utilities.Sort

 procedure Sort (File   : Name   := "<IMAGE>";
                 Result : Name   := "";
                 Key_1  : String := "";
                 Key_2  : String := "";
                 Key_3  : String := "");

 DESCRIPTION

 Sorts the lines of text in the specified object, using the specified sort
 keys.

 By default, the job reports sorted lines in Current_Output (by default, an
 Environment output window). You can redirect the job report using the
 Result parameter. Errors are indicated in log messages, which, by default,
 are also sent to the output window. Log messages are not affected by the
 Result parameter.

 By default, this procedure performs an ascending ASCII sort on full lines.
 By specifying one or more Key_n parameters, you can:

 *  Define sort keys based on whole lines, on fields within lines, or on
    segments within fields. Fields are portions of lines separated by one or
    more blanks; the leftmost field in each line is field 1. Segments of
    fields are identified by column numbers; the leftmost column in each field
    is column 1. For example, you can sort lines based on the characters in
    columns 8 through 10 of field 3 in each line.

 *  Define major, intermediate, and minor sort keys. Major and minor sort
    keys allow you to specify a hierarchy of sort criteria. For example,
    assume you have a list of lines containing three fields: filename, file
    owner, and file size. You can produce a list in which files are grouped
    by usernames and, within each group, arranged from smallest to largest.
    In this case, the username field is the major sort key (Key_1), the size
    field is the intermediate sort key (Key_2), and the filename is the minor
    sort key (Key_3).

 *  Sort in reverse ASCII order (descending, from highest to lowest, from Z
    to A, and so on).

 *  Sort on numeric values of fields.

 Each of the Key_n parameters takes the same set of options. Key_2 is
 ignored if Key_1 is not specified; similarly, Key_3 is ignored if Key_2 is
 not specified.


 PARAMETERS

 File : Name := "<IMAGE>";

 Specifies the objects whose lines are to be sorted. A file or library can be
 specified. When a library is specified, its entries are sorted by object
 name. File must name a single object. The default is the object whose
 image contains the cursor.


 Result : Name := "";

 Specifies the file to which to direct the job report. The default is to
 write to Current_Output (by default, an Environment output window).

 Note that errors are indicated in log messages, which are not redirected
 by this parameter. To redirect both log messages and the job report, leave
 the Result parameter with its default value and enter the
 !Commands.Log.Set_Output procedure in the same command window as the Sort
 procedure, specifying the location to which to direct output.


 Key_1 : String := "";

 Defines the major sort key using the options listed below. The syntax for
 specifying multiple options is given in the Parameter-Value Conventions
 tabbed section in the Reference Summary (RS). Each option can be specified
 by the first character of its name (for example, F=6 specifies field 6).


 *  Field=number

    Specifies the field to be used as the sort key. Fields are nonblank
    characters separated by blanks. The leftmost field is field 1, which
    always includes column 1, even if column 1 is blank. If this option is
    not specified, the entire line, blanks included, counts as a single
    field.


 *  Start_Column=number

    Specifies the starting column number relative to the beginning of the
    specified field. The default value is 1. Together with End_Column, this
    option allows you to use a subportion of the specified field as the sort
    key.


 *  End_Column=number

    Specifies the ending column number relative to the beginning of the
    specified field. The default value is Integer'Last. Together with
    Start_Column, this option allows you to use a subportion of the
    specified field as the sort key.


 *  Reverse

    Specifies a descending sort for the key.


 *  Numeric

    Performs a sort on the numeric value of the field represented as a
    Long_Integer.


 Key_2 : String := "";

 Defines a minor sort key using the options listed under Key_1 above. This
 key is used only if Key_1 is also specified.


 Key_3 : String := "";

 Defines the least significant sort key using the options listed under Key_1
 above. This key is used only if Key_1 and Key_2 are also specified.


 EXAMPLES

 The following command sorts a file called Test in ascending order, based on
 columns 5 through 7 of the entire line:

   File_Utilities.Sort
      (File  => "test",
       Key_1 => "start_column=5, end_column=7");

 The following command sorts a file called Test based on columns 5 through 7
 of field 2 in descending order:

   File_Utilities.Sort
      (File  => "test",
       Key_1 => "field=2, start_column=5, end_column=7, reverse");

 This command can be abbreviated as follows:

   File_Utilities.Sort
      (File  => "test",
       Key_1 => "f=2, s=5, e=7, r");

 Assume that you want to sort information from a library display based on
 username and object size. First, copy the expanded library image into a
 text file (sorting a library directly allows you to sort only on the
 object name). The text file contains something like this:

   Access_List_Rdf         :   90/12/30 13:48:08 Gzc     35637 { 0}
   Access_List_Tools_Rdf   :   90/12/29 17:35:00 Gzc     44974 { 0}
   Archive_Rdf             :   90/12/30 15:36:53 Gzc      111k { 0}
   Compilation_Rdf         :   90/12/30 10:21:28 Gzc     56170 { 0}
   File_Utilities_Rdf      :   Today    18:01:40 Sjl     42046 { 0}
   Graphics                :   91/05/04 18:26:52 Sjl     Vol 3 { 0}
   Include_File_Utilities_ :   Yesterdy 15:49:04 Sjl      3393 { 0}
      Wildcards
   Intro_Rdf               :   90/12/29 17:25:08 Gzc     77634 { 0}
   Library_Rdf             :   Yesterdy 15:34:26 Sjl      135k { 0}

 Assuming that the text file is called Listing, the following command sorts
 based on username and size in reverse order. Note that numeric comparison
 is specified in Key_2 so that the numbers 135k and 3393 are compared
 numerically rather than textually:

   File_Utilities.Sort (File  => "listing",
                        Key_1 => "f=6",
                        Key_2 => "f=7,r,n");

 The results of the command are displayed in an Environment output window:

  Intro_Rdf                        :   90/12/29 17:25:08 Gzc     77634 {0}
  Archive_Rdf                      :   90/12/30 15:36:53 Gzc      111k {0}
  Compilation_Rdf                  :   90/12/30 10:21:28 Gzc     56170 {0}
  Access_List_Tools_Rdf            :   90/12/29 17:35:00 Gzc     44974 {0}
  Access_List_Rdf                  :   90/12/30 13:48:08 Gzc     35637 {0}
  File_Utilities_Rdf               :   Today    18:01:40 Sjl     42046 {0}
  Include_File_Utilities_Wildcards :   Yesterdy 15:49:04 Sjl      3393 {0}
  Library_Rdf                      :   Yesterdy 15:34:26 Sjl      135k {0}
  Graphics                         :   91/05/04 18:26:52 Sjl     Vol 3 {0}


 @node !Commands.File_Utilities.Strip

 procedure Strip (Source : Name := "<SELECTION>";
                  Target : Name := "");

 DESCRIPTION

 Takes the result of the Merge or the Difference procedure and creates a
 clean file.

 This procedure removes any variation annotations that were inserted in
 column 1 of the result file produced by the Merge or Difference procedure.
 (The result file should be edited before stripping to resolve conflicting
 changes.)


 PARAMETERS

 Source : Name := "<SELECTION">;

 Specifies the file to be stripped. This file is typically the result file
 produced by the Merge or Difference procedure. The specified file is not
 changed. Multiple objects can be specified using wildcards, context
 characters, set notation, indirect files, and attributes. The default is
 the current selection.


 Target : Name := "";

 Specifies the file into which the stripped source is to be placed. If this
 file does not already exist, it is created. If it does exist, its previous
 contents are overwritten. This parameter can use special names. The
 default is to display the results in an Environment output window.


 ERRORS

 The most common error is incorrect specification of a filename.


 EXAMPLES

 The following example illustrates the results of using the Strip procedure
 on a file created by the Difference procedure.

 The procedure:

   File_Utilities.Strip (source=>"text3",target=>"text4");

 was run on the file Text3 below:

   * Object 1: !USERS.GZC.WM_FILE_UTILITIES.TEXT1
   * Object 2: !USERS.GZC.WM_FILE_UTILITIES.TEXT2
   1 This is text from file one.
   2 This is text from file two.
     This is text that is in both files.
   1 This is more text from file one.
   2 This is more text from file two.

 The results placed in file Text4 are:

   Object 1: !USERS.GZC.WM_FILE_UTILITIES.TEXT1
   Object 2: !USERS.GZC.WM_FILE_UTILITIES.TEXT2
   This is text from file one.
   This is text from file two.
   This is text that is in both files.
   This is more text from file one.
   This is more text from file two.

 REFERENCES

 procedure Difference
 procedure Merge



 @node !Commands.Library

 Package Library provides commands for manipulating objects in the library
 system and for type-specific editing of library images. As with most
 commands in the !Commands world, these commands can be executed from
 programs but are tailored for use as interactive commands.


 RESOURCES IN PACKAGE LIBRARY

 The commands in package Library fall into several functional groups. Types
 and constants are not included in this list.

 Managing objects in libraries:

            Copy            Create                Create_Directory
            Create_Unit     Create_World          Delete
            Destroy         Freeze                Move
            Reformat_Image  Rename Set_Subclass
            Undelete        Unfreeze

 Managing versions of objects:    Default, Expunge, Set_Retention_Count

 Managing name resolution:        Context, Enclosing_World, Resolve

 Producing lists of objects:      Ada_List, File_List, List, Verbose_List

 Managing disk space:             Compact_Library, Space


 KEY CONCEPTS FOR PACKAGE LIBRARY

 This package introduction contains information to help you use the
 commands in this package. Specifically, it contains information about:

 *  Name resolution and context

 *  Model worlds

 *  Versions

 *  Recursive operation

 *  Operations affecting multiple objects

 *  Access control

 This introduction also contains information about manipulating the library
 image to display more or less information.

 For an introduction to the Environment library system and types of
 libraries, see Chapter 1, "Managing Libraries."


 Name Resolution and Context

 When names are specified as parameter values, the Environment resolves
 (maps) these names to the objects they reference. Because each object has
 a unique fully qualified pathname, the strings given as parameter values
 are evaluated and converted into fully qualified pathnames. To this end,
 wildcard, context, and substitution characters are expanded into name
 components. Furthermore, relative pathnames are interpreted relative to
 the context in which they are used; such names are supplemented with name
 components from this context. Note that you can use the Resolve procedure
 to determine how a name will be resolved before you actually use that
 name in a command.

 By default, the context in which names are resolved is the current
 library. The current library is determined by the job in which the names
 are used. (A job is a set of one or more commands that are promoted at the
 same time in a single command window.) Specifically, the current library
 is the closest enclosing library to where the job is executed. If the job
 is executed from a command window attached to a library, that library is
 the current library. If the job is executed from a command window attached
 to any other object, the current library is the nearest library enclosing
 that object.

 By default, objects that are defined in the current library can be
 referenced by their simple names, whereas the names of objects in other
 libraries must be qualified. If many such names need to be qualified in a
 given job, you can save typing by resetting the context for resolving
 names during that job. That is, you can use the Context or Enclosing_World
 procedures to change the name-resolution context to a library other than
 the current library. Names are resolved relative to the new context for
 the duration of the job (or until the context is reset within the same
 job). Thus, the commands in this job:

   Library.Context ("!Users.Gzc.Sample_Directory");
   Library.Delete ("To_Do");
   Text.Create ("New_List");

 are equivalent to the commands in the following job:

   Library.Delete ("!Users.Gzc.Sample_Directory.To_Do");
   Text.Create ("!Users.Gzc.Sample_Directory.New_List");

 In simple cases, such as the previous example, you can effectively change
 the name-resolution context by entering the job in a different context.
 However, using the Context or Enclosing_World procedures is more flexible,
 allowing you to change the context more than once during the course of a
 single job.


 Model Worlds

 A world can be created with certain predefined characteristics. The
 characteristics are copied from a model world, which is specified by the
 Model parameter in the Create and Create_World commands. Specifying a
 model when a world is created is a shortcut for specifying the following
 characteristics as separate operations:

 *  An associated library switch file. Library switches affect such things
    as compilation and pretty-printing within a world (see package
    Switches).

 *  A set of links to units in other Environment libraries. Links determine
    the Environment resources that are visible to the units in the newly
    created world (see package Links).

 *  A target key. A world's target key determines (1) the target for which
    units in the world are to be compiled and (2) the program design
    language (PDL), if any, to be enforced in the world. Targets other than
    the R1000 are supported by the Rational Compilation Integrator (RCI),
    the Target Build Utility (TBU), and Rational's Cross-Development
    Facility (CDF) products; see the family of RCI, TBU, and CDF manuals
    for more information. See the Rational Design Facility manuals for
    information about PDLs.

 By default, worlds are created from a model called !Model.R1000. The
 target key that is set by this model causes units to be compiled for
 execution on the R1000; this model also provides links to the most common
 Environment commands and tools. The Environment provides several other
 predefined R1000 model worlds that provide different sets of links. These
 can be found in the world !Model.

 Any world can serve as a model world; you can create your own model world
 by creating a world with a null value for the Model parameter and
 associating the desired switches, setting the desired target key, and
 adding the desired links to that world. (See packages Switches,
 Compilation, and Links.)


 Versions

 Environment objects such as Ada units and files can have multiple versions.
 In particular, a new version is created when:

 *  An Ada unit in the source state is opened for editing

 *  An Ada unit in the installed or coded state is incrementally edited

 *  A text file is committed or promoted

 Versions are numbered starting with 1, which represents the oldest version
 (the object at creation). When an object is displayed in a window, the
 object's version number is displayed in the 'V attribute after the name in
 the window banner. For example, the window banner for the file containing
 this documentation shows that the current version is 12:

   ....DEVEL_WORKING.UNITS.LIBRARY_RDF'V(12)

 When a new version of an object is created, the new version automatically
 becomes the current default version. The default version is used by
 default whenever the object is viewed, edited, or referenced by name.


 Deleted Versions and Retention Count

 When a newly created version becomes the default, the previous default
 version is automatically deleted. Depending on the object's retention
 count, deleted versions are either retained or expunged. Retained versions
 are deleted but recoverable--they can be undeleted (reinstated as the
 default version with the Default or Undelete command) and/or referenced
 using the 'V attribute. Deleted versions that have been retained are
 sometimes called nondefault versions. In contrast, expunged versions are
 deleted permanently and are unrecoverable. The object's retention count
 determines the maximum number of deleted versions that can be retained
 before the Environment starts expunging the oldest versions.

 If an object's retention count is 0, no deleted versions are retained, so
 that when a new version is created, all previous versions are permanently
 expunged. If the object's retention count is 1, one deleted version is
 retained, so that when a new version is created, the previous version can
 be referenced and even reinstated as
 the default version. Figure 1 shows all the versions of an object that is
 five versions old and that has a retention count of 2.

   Default  |        Deleted Versions
   Version  |      /                   \
            |
   -----    |    -----  -----  - - -  - - -
   | 5 |    |    | 4 |  | 3 |    2 |    1 |
   |   |    |    |   |  |   |  |      |
   -----    |    -----  -----  - - -  - - -
            |     \        /   \        /
            |      Retained     Expunged
            |    (nondefault)   versions
            |      versions

   Figure 1   Object with Retention Count 2


 An object inherits its retention count from the default retention count
 that is associated with the enclosing library. Thus, if a library has a
 default retention count of 1, then the objects in it have a retention
 count of 1 when they are created. Libraries themselves do not have
 versions, so a library's default retention count applies only to the
 nonlibrary objects it contains.

 You can change an object's retention count with the Set_Retention_Count
 command. This command also can be used to change the default retention
 count associated with a library, which by default changes the retention
 count of the objects in that library.

 Note that versions of objects in the library system should not be confused
 with CMVC generations. Generations refer to changes that have accumulated
 in a controlled object between checking it out and checking it in; there
 may be many versions to a single generation. (See the Project Management
 (PM) book for details.)


 Deleted Objects

 Deleted versions should not be confused with deleted objects. A deleted
 version is an old default version that has been deleted automatically
 because a new default version has been created. In contrast, a deleted
 object is an object whose default version has been deleted, for example,
 with the Delete procedure. That is, an object is deleted when all of its
 versions are deleted. As before, a deleted object is recoverable only if
 it has a nonzero retention count, so that at least one of its deleted
 versions is retained. The Undelete command restores an object by setting a
 retained nondefault version to be the default version.

 In an expanded library image, entries for deleted (nondefault) versions
 are preceded with hyphens (-), and entries for all versions of deleted
 objects are enclosed in braces ({ })--see "Structure of Library Images,"
 page nn.


 Recursive Operation

 Many commands in package Library operate recursively by default--that is,
 these commands operate not only on the specified objects but also on the
 children of the specified objects. Thus, by default, copying a library also
 copies all the objects within the library; freezing an Ada unit also
 freezes its subunits.

 Commands that operate recursively have a Recursive parameter that can be
 set to False to prevent the recursive behavior. In this case, just the
 specified objects are affected by the command. By default, the Recursive
 parameter is set to True.

 When the Recursive parameter is True, the effect is the same as using the
 ?? wildcard in specifying the objects to be operated on. For example,
 the following commands are equivalent for freezing a world called
 Projects and all of its contents (including any worlds it contained):

   Library.Freeze (Existing => "Projects", Recursive => True);

   Library.Freeze (Existing => "Projects??", Recursive => False);

 Full recursion through worlds is often too powerful. If you want an
 operation to recursively affect all contained objects except worlds, you
 can set Recursive to False and use the ? wildcard. For example, the
 following command freezes the world Projects and all of its contents
 except any worlds it contains:

   Library.Freeze (Existing => "Projects?", Recursive => False);


 Operations Affecting Multiple Objects

 Commands in package Library can operate on multiple specified objects and
 (recursively) their subobjects. Sometimes commands fail before
 completing a list of objects. If this happens, the objects that have
 already been affected remain that way. That is, if you are deleting a set
 of five objects and the Delete command is abandoned after deleting three
 objects, those three objects remain deleted. (In contrast, commands in
 some packages are atomic, which means that if the command fails before
 finishing an operation, the partial effect of the command is reversed as if
 the command was never entered.)


 Access Control

 Access to worlds, Ada units, and files is controlled by the access-control
 lists (ACLs) associated with each object of these types. Thus, when you
 perform operations on objects to which you do not have the required
 access, error messages will be generated indicating that you do not have
 the required access class. For further information on access control, see
 package Access_List in this book.


 STRUCTURE OF LIBRARY IMAGES

 Libraries contain objects such as files, Ada units, and other libraries. A
 library's image is a sequence of lines, of which the first line is the
 fully qualified name of the library. The rest of the lines in the image are
 single-line entries for the objects in the library, sorted in alphabetical
 order. There is a direct relationship between library entries and the
 objects they represent--for example, deleting an object's library entry
 deletes the object itself. Commands from package !Commands.Common can be
 used from a library image to operate on objects (see "Commands from
 Package Common," page nn).

 Library images can be adjusted interactively to display a variety of
 information about the contained objects. Detail can be adjusted
 "horizontally" and "vertically":

 *  The !Commands.Common.Explain command expands the information display
    "horizontally" (to the right) to provide additional information in each
    object's library entry. "Horizontal" detail can be cycled through three
    levels--namely, default, standard, and miscellaneous.

 *  The !Commands.Common.Expand and !Commands.Common.Elide commands adjust
    the information display "vertically" to provide more or fewer entries,
    which includes or omits deleted versions and subunits in the display.
    "Vertical" detail can be expanded through nine levels of elision.

 The information that is displayed at these various levels of detail can be
 tailored on a session-by-session basis using session switches (see
 "Session Switches for Controlling Library Displays," page nn). The
 following discussion assumes the standard session-switch settings.


 Default Level of Detail

 Under the standard session-switch settings, traversing to a library
 displays a default level of library detail that simply lists the names of
 the objects in the library. This image is displayed by default because it
 takes the least amount of time to display.

 Figure 2 shows an example of the default library image for user Lance's
 Projects world.

   !Users.Lance.Projects
     A_Generic_Instantiation
     A_Generic_Package
     A_Generic_Package
     A_Package
     A_Package
       .Nested
       .T
     A_Procedure
     A_Procedure
       ._Ada_1_
     Control_Link
     Current_Release
     File_From_Direct_Io
     File_From_Text_Io
     Library_Switches
     Nested_Directory
     Nested_World
     _Ada_7_                                      

   Figure 2   Default Level of Detail


 Note that subunits of Ada units are displayed on the lines following their
 parents, prefixed with a period (.). Insertion points or withdrawn items
 are also listed. Their names begin with the characters _Ada_.

 The window banner for a library image contains a truncated form of the
 library's name, an indication that the image type is library, and some
 additional information, including:

 *  Whether the library is frozen

 *  The name of the target key for the library if it is not R1000

 *  Whether it is a world or a directory

 *  The current level of elision


 Standard Level of Detail

 You can use the !Commands.Common.Explain command to expand the library
 display to the standard level of detail. Using this command with the
 cursor on the first line of the image shows more information about every
 object. You can also use this command with the cursor on an individual
 entry to show more detail about just that object. Under the standard
 switch settings, expanding the library display once produces a display
 like the one shown in Figure 3.

   !Users.Lance.Projects : Library (World);
     A_Generic_Instantiation : Ada (Pack_Inst);
     A_Generic_Package       : Ada (Gen_Pack);
     A_Generic_Package       : Ada (Pack_Body);
     A_Package               : Ada (Pack_Spec);
     A_Package               : Ada (Pack_Body);
       .Nested               : Ada (Pack_Body);
       .T                    : Ada (Task_Body);
     A_Procedure             : Ada (Proc_Spec);
     A_Procedure             : Ada (Proc_Body);
       ._Ada_1_              : Ada (Statement);
     Control_Link            : Pipe;
     Current_Release         : File (Activity);
     File_From_Direct_Io     : File (Binary);
     File_From_Text_Io       : File (Text);
     Library_Switches        : File (Switch);
     Nested_Directory        : Library (Directory);
     Nested_World            : Library (World);
     _Ada_7_                 : Ada (Comp_Unit);

   Figure 3   Standard Level of Detail 


 The additional information includes the class of each object with the
 object's subclass enclosed in parentheses. The subclass of the object
 can be helpful in distinguishing the different kinds of Ada units
 (specs, bodies, instantiations, and so on) or different kinds of files
 (text, binary, activity, and so on). A list of classes and subclasses is
 included in the Parameter-Value Conventions tabbed section in the
 Reference Summary (RS) book.


 Miscellaneous Level of Detail

 Additional information is displayed at the miscellaneous level of detail
 (see Figure 4), which is obtained by entering the !Commands.Common.Explain
 command from the standard level.

   !Users.Lance.Projects : Vol 4 {1};
     A_Generic_Instantiation : I 91/06/02 18:57:19 Lance    5251  { 1} Frz;
     A_Generic_Package       : I 91/06/02 18:56:24 Lance    2968  { 1}    ;
     A_Generic_Package       : I 91/06/02 18:56:37 Lance    2934  { 1}    ;
     A_Package               : I 91/06/02 18:51:42 Lance    2885  { 1}    ;
     A_Package               : I 91/06/02 18:53:51 Lance    6261  { 1}    ;
       .Nested               : I 91/06/02 18:52:53 Lance    3052  { 1}    ;
       .T                    : I 91/06/02 18:53:58 Lance    3047  { 1}    ;
     A_Procedure             : C 91/06/02 18:54:51 Lance    2880  { 1}    ;
     A_Procedure             : C 91/06/02 19:03:14 Lance    3161  { 1}    ;
       ._Ada_1_              : S 91/06/02 19:03:15 Lance     665  { 1}    ;
     Control_Link            :   91/06/02 18:51:03 Lance       0  { 1}    ;
     Current_Release         :   91/06/02 18:58:33 Lance     187  { 1} Frz;
     File_From_Direct_Io     :   91/06/02 18:48:28 Lance      17  { 1}    ;
     File_From_Text_Io       :   91/06/02 18:48:27 Lance      17  { 1}    ;
     Library_Switches        :   91/06/02 19:00:11 Lance      45  { 1}    ;
     Nested_Directory        :                     Vol 4          { 1}    ;
     Nested_World            :                     Vol 4          { 1}    ;
     _Ada_7_                 : S 91/06/02 19:01:50 Lance     651  { 1}    ;

   Figure 4   Miscellaneous Level of Detail


 This information includes (from left to right):

 *  The compilation state of Ada units: archived (A), source (S), installed
    (I), or coded (C)

 *  The date and time the object was last edited

 *  The user who last edited the object or the volume number if it is a
    library

 *  The size of the object in bytes

 *  The number of versions to be retained for the object (the retention
    count)

 *  An indication if the object is frozen


 Setting Up the Standard and Miscellaneous Displays

 Session switches can be used to control the kinds of information that are
 displayed for the standard and miscellaneous levels of detail. The
 switches that control the standard information have the string "_Std_" in
 their names. The switches that control the miscellaneous information
 have the string "_Misc_" in their names.

 Session switches also can be used to bypass the default level of
 information (shown above) in favor of either the standard or the
 miscellaneous level:

 *  When the Library_Show_Standard session switch is set to True, the
    standard level of information is shown as the default level when you
    traverse to libraries.

 *  When the Library_Show_Misc session switch is set to True, the
    miscellaneous level of information is shown as the default level when
    you traverse to libraries.

 Note: Displaying additional detail in library images means that it takes
 longer to obtain the images of new libraries or to update changed library
 images.

 For example, many users prefer a display like that shown in Figure 5 when
 they traverse to a library.

   !Users.Lance.Projects :   Library (World);
     A_Generic_Instantiation : I Ada (Pack_Inst);
     A_Generic_Package       : I Ada (Gen_Pack);
     A_Generic_Package       : I Ada (Pack_Body);
     A_Package               : I Ada (Pack_Spec);
     A_Package               : I Ada (Pack_Body);
       .Nested               : I Ada (Pack_Body);
       .T                    : I Ada (Task_Body);
     A_Procedure             : C Ada (Proc_Spec);
     A_Procedure             : C Ada (Proc_Body);
       ._Ada_1_              : S Ada (Statement);
     Control_Link            :   Pipe;
     Current_Release         :   File (Activity);
     File_From_Direct_Io     :   File (Binary);
     File_From_Text_Io       :   File (Text);
     Library_Switches        :   File (Switch);
     Nested_Directory        :   Library (Directory);
     Nested_World            :   Library (World);
     _Ada_7_                 : S Ada (Comp_Unit);

   Figure 5   Setting the Level of Detail 


 To establish this as your default libraries display, modify the following
 session-switch values:

 *  Library_Show_Standard := True

 *  Library_Std_Show_Unit_State := True

 This causes the standard additional information to be displayed by default
 and unit-state information to be added to this standard information.


 Levels of Elision

 At any level of detail (default, standard, or miscellaneous), a library
 display also can be adjusted "vertically" through various levels of
 elision. At the system-defined default level of elision, the default
 versions of all undeleted objects are displayed; successive levels of
 elision provide information about deleted objects and retained versions of
 objects. For example, entering the !Command.Common.Expand command from
 the system-defined default library image produces a display like that shown
 in Figure 6.

   !Users.Lance.Projects
     {A_Deleted_Unit'V(3)}
   - {A_Deleted_Unit'V(2)}
     A_Generic_Instantiation'V(3)
   - A_Generic_Instantiation'V(2)
     A_Generic_Package'V(3)
   - A_Generic_Package'V(2)
     A_Generic_Package'V(3)
   - A_Generic_Package'V(2)
     A_Package'V(3)
   - A_Package'V(2)
     A_Package'V(4)
   - A_Package'V(3)
       .Nested'V(6)
   -   .Nested'V(5)
       .T'V(1)
     A_Procedure'V(3)
   - A_Procedure'V(2)
     A_Procedure'V(5)
   - A_Procedure'V(4)
       ._Ada_1_'V(1)
     Control_Link'V(2)
   - Control_Link'V(1)
     Current_Release'V(3)
   - Current_Release'V(2)
     File_From_Direct_Io'V(1)
     File_From_Text_Io'V(3)
   - File_From_Text_Io'V(2)
     Library_Switches'V(9)
   - Library_Switches'V(8)
     Nested_Directory
     Nested_World
     _Ada_7_'V(1)

   Figure 6   Expanded Level of Elision 


 Versions of objects are shown with the 'V attribute. Where multiple
 versions are listed for a single object, all but the first in the list are
 prefixed with the hyphen (-). Deleted objects and their versions are
 enclosed in braces ({ }).

 Table 1 describes the available elision levels that can be obtained with
 the !Commands.Common.Expand and !Commands.Common.Elide commands. They are
 arranged in order with the most expanded level at the top and the most
 elided level at the bottom.

                          Table 1   Elision Levels
                   ------------------------------------ 
                  |         |                          |
                  |Banner   |Descriptions              |
                  |Symbol   |                          |
                   ------------------------------------ 
                  |         |                          |
                  |{versions|All deleted and undeleted |
                  |}        |versions                  |
                   ------------------------------------ 
                  |         |                          |
                  |versions |All undeleted versions    |
                   ------------------------------------ 
                  |         |                          |
                  |{lib     |All deleted and undeleted |
                  |vers}    |versions; no subunits     |
                   ------------------------------------ 
                  |         |                          |
                  |lib vers |All undeleted versions; no|
                  |         |subunits                  |
                   ------------------------------------ 
                  |         |                          |
                  |{units}  |All deleted and undeleted |
                  |         |objects                   |
                   ------------------------------------ 
                  |         |                          |
                  |units    |All undeleted objects     |
                   ------------------------------------ 
                  |         |                          |
                  |{lib     |All deleted and undeleted |
                  |units}   |objects; no subunits      |
                   ------------------------------------ 
                  |         |                          |
                  |lib units|All undeleted objects; no |
                  |         |subunits                  |
                   ------------------------------------ 



 The system-defined default level of elision is units. You can change the
 default level of elision for your session using the
 Library_Show_Deleted_Objects and Library_Show_Deleted_Versions session
 switches:

 *  When the Library_Show_Deleted_Objects switch is set to True, the
    default level of elision is {units}.

 *  When the Library_Show_Deleted_Versions switch is set to True, the
    default level of elision is versions.

 *  When both switches are set to True, the default level of elision is
    {versions}.

 Note that the default elision level, as determined by the values of the
 Library_Show_Deleted_Objects and Library_Show_Deleted_Versions, is blank
 (that is, there is nothing on the banner).


 Setting Up the Default Level of Elision

 Session switches can be used to cause elision-level information to be
 displayed at the default level of elision. In particular, the session
 switches Library_Show_Deleted_Objects, Library_Show_Deleted_Versions,
 and Library_Show_Subunits can be set to True to cause deleted objects,
 deleted versions, and subunits to be displayed without having to use the
 !Commands.Common.Expand command.


 SESSION SWITCHES FOR CONTROLLING LIBRARY DISPLAYS

 This section lists all the session switches that pertain to libraries.
 Some of these switches allow you to set up the standard and miscellaneous
 levels of detail or the default level of elision. Other switches control
 the textual presentation of libraries, independent of the level of detail
 or elision. For example, you can use the Library_Capitalize switch to
 control whether identifiers are capitalized in library images.

 Note that changed switch values take effect only in newly visited library
 images. Library images that are on the screen when the switch values are
 changed must be abandoned and revisited for the new values to take effect.

 For more information on session switches, see Session and Job Management
 (SJM), Session Switches. For information about displaying and editing
 switches, see package Switches in this book.

 Setting Up the Standard Level of Detail

 Several session switches control the information that is displayed as part
 of the standard level of detail:

 *  Library_Show_Standard (default False) causes the standard level of
    information to be displayed when libraries are visited.

 *  Library_Std_Show_Class (default True) shows class along with
    subclass--for example, File (Text) instead of Text when displaying
    standard information.

 *  Library_Std_Show_Subclass (default True) shows subclass as part of the
    standard information.

 *  Library_Std_Show_Unit_State (default False) shows unit state for Ada
    units as part of the standard information.


 Setting Up the Miscellaneous Level of Detail

 Several session switches control the information that is displayed as part
 of the miscellaneous level of detail:

 *  Library_Misc_Show_Edit_Info (default True) shows time and user of last
    update/ edit for the version.

 *  Library_Misc_Show_Frozen (default True) shows "Frz" for frozen objects.

 *  Library_Misc_Show_Retention (default True) shows the retention count
    (for example, 10).

 *  Library_Misc_Show_Size (default True) shows the size of the version in
    bytes.

 *  Library_Misc_Show_Subclass (default False) shows the object's subclass.

 *  Library_Misc_Show_Unit_State (default True) shows the shortened form of
    the unit state of Ada objects.

 *  Library_Misc_Show_Volume (default True) shows the volume for libraries.

 *  Library_Show_Miscellaneous (default False) causes the miscellaneous
    level of information to be displayed when libraries are visited.


 Setting Up the Default Level of Elision

 Several session switches control the information that is displayed at the
 default level of elision:

 *  Library_Show_Deleted_Objects (default False) shows all deleted objects
    (for example, {Foo'Body}) and undeleted objects at the default level of
    elision.

 *  Library_Show_Deleted_Versions (default False) shows all undeleted
    versions of existing objects at the default level of elision.

 *  Library_Show_Subunits (default True) shows subunits at the default
    level of elision.

 When both the Library_Show_Deleted_Objects and the Library_Show_Deleted-
 _Versions switches are set to True, all deleted and undeleted versions of
 all objects are shown at the default level of elision.


 Controlling the Textual Presentation of Libraries

 The following switches control how libraries are presented, independent of
 the level of elision or detail:

 *  Library_Break_Long_Lines (default True) controls whether lines that
    exceed the value of the Library_Line_Length session switch are broken.

 *  Library_Capitalize (default True) determines whether identifiers in
    library images are capitalized.

 *  Library_Indentation (default 2) determines how much to indent subunit
    names when displayed in the short form (that is, without their parent
    name as prefixes, which is determined by the value of the
    Library_Shorten_Names session switch).

 *  Library_Lazy_Realignment (default True) determines whether the image is
    realigned when a longer name is added. If True, the Environment waits
    for a Redraw request.

 *  Library_Line_Length (default 80) determines how long a line can be
    before it is eligible to be broken.

 *  Library_Shorten_Names (default True) determines whether the pathname of
    the parent is displayed for subunits.

 *  Library_Shorten_Subclass (default True) shows subclasses in shortened
    form when subclasses are displayed.

 *  Library_Shorten_Unit_State (default True) shows only the first letter of
    the unit state when unit states are displayed.

 *  Library_Show_Version_Number (default False) shows the version number of
    the default or maximum version as part of the object name (for example,
    Foo'V(4) or Bar'V(2)).

 *  Library_Uppercase (default False) determines whether identifiers in
    library images are uppercased.


 COMMANDS FROM PACKAGE COMMON FOR EDITING LIBRARIES

 Many commands from package !Commands.Common are supported for editing
 libraries. Commands from package Common are typically used through the key
 combinations to which they are bound. Commands from package Common that
 are supported for editing libraries are summarized in Table 2. For
 further information about these commands, see the Editing Specific Types
 (EST) book, package Common.

      Table 2   Commands from Package Common for Editing Libraries
     --------------------------------------------------------------- 
    |               |                                               |
    |Key Bound To   |Accomplishes ...                               |
    |...            |                                               |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Abandon |Ends the editing of the specified image. The   |
    |               |window is removed from the screen and from the |
    |               |window directory. The Window parameter allows  |
    |               |you to specify which window should be          |
    |               |removed. The default is the current image,     |
    |               |unless there is a selection in that image. In  |
    |               |that case, the selection is abandoned.         |
    |               |Procedure Common.Complete refreshes the library|
    |               |image in the current window to the current     |
    |               |value of the underlying permanent              |
    |               |representation and realigns the columns of the |
    |               |image.                                         |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Complete|Refreshes the library image in the current     |
    |               |window to the current value of the underlying  |
    |               |permanent representation and realigns the      |
    |               |columns of the image.                          |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Create_ |Creates a command window below the current     |
    |Command        |library window if one does not exist;          |
    |               |otherwise, the procedure puts the cursor in the|
    |               |existing command window below the current      |
    |               |library window. This command window initially  |
    |               |has a use clause:                              |
    |               |                                               |
    |               |     use Editor, Library, Common;              |
    |               |                                               |
    |               |                                               |
    |               |This use clause provides direct visibility to  |
    |               |the declarations in packages Editor, Library,  |
    |               |and Common without requiring qualification for |
    |               |names resolved in the command.                 |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.        |Finds the defining occurrence of the named or  |
    |Definition     |designated element and brings up its image in a|
    |               |window on the screen. If a name is provided, it|
    |               |is used. If no name is provided, a selection   |
    |               |with the cursor in it is used if one exists.   |
    |               |Otherwise, the cursor location is used to      |
    |               |designate the element. An In_Place parameter   |
    |               |specifies whether the existing window should be|
    |               |used. A Visible parameter specifies whether to |
    |               |go to the visible part or the body (if         |
    |               |possible).                                     |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Demote  |Demotes the selected Ada unit to the next lower|
    |               |state. The procedure changes the               |
    |               |state of the selected Ada unit, assuming there |
    |               |are no other units dependent on the unit. If   |
    |               |there are dependent units, a list of them is   |
    |               |displayed in the menu window that is brought   |
    |               |onto the screen. See Editing Specific Types    |
    |               |(EST), Menus, for more information on the      |
    |               |editing operations available on menus.         |
    |               |The specific effect of this procedure depends o|
    |               |the current state of the unit. If the current  |
    |               |state is:                                      |
    |               |*  Archived: The procedure has no effect.      |
    |               |*  Source: The procedure has no effect.        |
    |               |*  Installed: The unit is demoted to the source|
    |               |   state.                                      |
    |               |*  Coded: The unit is demoted to the installed |
    |               |   state.                                      |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Edit    |Creates a window in which to edit the named or |
    |               |selected object. An In_Place parameter         |
    |               |specifies whether the existing window should be|
    |               |used. A Visible parameter specifies whether to |
    |               |bring up the visible part or the body (if      |
    |               |possible).                                     |
    |               |For more information on the actions performed, |
    |               |see Editing Specific Types (EST), procedure    |
    |               |Common.Edit, for the class of object being     |
    |               |edited.                                        |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Elide   |Reduces the number of entries displayed in the |
    |               |designated library. See "Levels of Elision,"   |
    |               |page nn, for more details.                     |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.        |Finds the parent library unit of the current   |
    |Enclosing      |library and displays that parent in a window.  |
    |               |An In_Place parameter specifies whether the    |
    |               |existing window should be used. A Library      |
    |               |parameter specifies whether the resulting image|
    |               |should be a library rather than the parent body|
    |               |when the parent body is not a library.         |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Expand  |Increases the number of entries displayed in   |
    |               |the designated library. See "Levels of         |
    |               |Elision," page nn, for more information.       |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Explain |Changes the level of detail displayed for the  |
    |               |designated object(s) in the library. There are |
    |               |three levels:                                  |
    |               |*  Default information                         |
    |               |*  Standard information                        |
    |               |*  Miscellaneous information                   |
    |               |This command cycles through the levels,        |
    |               |proceeding down the list and cycling back to   |
    |               |the top when at the bottom. See "Structure of  |
    |               |Library Images," page nn, for more information.|
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Format  |Refreshes the library image in the current     |
    |               |window to the current value of the underlying  |
    |               |permanent representation and realigns the      |
    |               |columns of the image.                          |
    |               |This command performs the same operation as the|
    |               |Common.Revert procedure.                       |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Promote |Promotes the selected Ada unit to the next     |
    |               |higher unit state. The specific effect of this |
    |               |procedure depends on the current state of the  |
    |               |unit. If the current state is:                 |
    |               |*  Archived: The unit is promoted to the source|
    |               |   state.                                      |
    |               |*  Source: The unit is promoted to the         |
    |               |   installed state.                            |
    |               |*  Installed: The unit is promoted to the coded|
    |               |   state.                                      |
    |               |*  Coded: If the unit is selected, execution is|
    |               |   attempted. If parameters are required, the  |
    |               |   prompt for them appears in a command window.|
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Release |Ends the editing of the library image. The     |
    |               |library-image window is removed from the screen|
    |               |and from the window directory.                 |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Revert  |Refreshes the library image in the current     |
    |               |window to the current value of the underlying  |
    |               |permanent representation and realigns the      |
    |               |columns of the image.                          |
    |               |                                               |
    |               |This command performs the same operation as the|
    |               |Common.Format procedure.                       |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Undo    |Undeletes the selected object. This procedure  |
    |               |is similar to the Library.Undelete procedure.  |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the child of the current selection. The|
    |Child          |procedure selects the line the cursor is on if |
    |               |there are no selections or if the cursor is not|
    |               |in the selection. If a line is selected, the   |
    |               |procedure selects the first child of that line.|
    |               |If the selected line has no child, it selects  |
    |               |the next line.                                 |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Copies the selected object into the image where|
    |Copy           |the cursor is located. The procedure prompts   |
    |               |with a Library.Copy command in a command window|
    |               |below the window in which the cursor is        |
    |               |located. The From parameter has the name of the|
    |               |selected object as the default value, and the  |
    |               |To parameter has the current context as the    |
    |               |default value.                                 |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Deletes the selected object. If other elements |
    |Delete         |are dependent on the element because of        |
    |               |semantic references (from installed or coded   |
    |               |units), the deletion fails, a menu of the      |
    |               |dependent units is displayed in the menu       |
    |               |window, and a Library.Delete command with the  |
    |               |name of the selected unit as the parameter is  |
    |               |placed in a command window. For more           |
    |               |information, see the description of the editing|
    |               |operations on menus in Editing Specific Types  |
    |               |(EST), Menus. Contained units of the selected  |
    |               |element are not deleted. The cursor must be in |
    |               |the selection for the operation to succeed.    |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the first child of the current         |
    |First_Child    |selection. The procedure selects the line the  |
    |               |cursor is on if there are no selections or if  |
    |               |the cursor is not in the selection. If a line  |
    |               |is selected, the procedure selects the first   |
    |               |child of that line. If the selected line has no|
    |               |child, it selects the next line.               |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Creates an insertion point in a library where  |
    |Insert         |an Ada compilation unit can be inserted.       |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the last child of the current          |
    |Last_Child     |selection. If there is no selection in the     |
    |               |image or the cursor is not in the selection,   |
    |               |this procedure selects the current line. If    |
    |               |there is a selection, the procedure selects    |
    |               |the last child of the current selection. If the|
    |               |selection has no subobjects, it selects the    |
    |               |next object.                                   |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Moves the selected object into the library in  |
    |Move           |which the cursor is located. The procedure     |
    |               |prompts with a Library.Move command in a       |
    |               |command window below the library in which the  |
    |               |cursor is located. The From parameter specifies|
    |               |as a default, the selected object, and the To  |
    |               |parameter specifies, as a default, the library |
    |               |in which the cursor is located.                |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the next object at the same or greater |
    |Next           |level past the currently selected object.      |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the parent of the current selection. If|
    |Parent         |there is no selection or if the cursor is not  |
    |               |in the selection, the procedure selects the    |
    |               |line on which the cursor is located.           |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the previous object at the same or     |
    |Previous       |greater level before the currently selected    |
    |               |object.                                        |
     --------------------------------------------------------------- 




 @node !Commands.Library.Ada_Format

 Ada_Format : constant Fields := Fields'(Status      => True,
                                         Declaration => True,
                                         Others      => False);

 DESCRIPTION

 Defines a constant that specifies a set of data for Ada objects to be
 displayed by the List procedure.

 This is the default value of the Displaying parameter in the Ada_List
 procedure.



 @node !Commands.Library.Ada_List

 procedure Ada_List (Pattern    : Name    := "<IMAGE>@'C(ADA)";
                     Displaying : Fields  := Library.Ada_Format;
                     Sorted_By  : Field   := Library.Declaration;
                     Descending : Boolean := False;
                     Response   : String  := "<PROFILE>";
                     Options    : String  := "") renames List;

 DESCRIPTION

 Displays the specified set of data about the specified set of versions of
 specified objects.

 This procedure performs exactly as the List procedure except that it has
 different default parameters. The default parameters provide a display of
 all Ada units in the current context.


 PARAMETERS

 Pattern : Name := "<IMAGE>@'C(ADA)";

 Specifies the set of objects to be listed. Wildcards, context prefixes, and
 attributes can be used in this name. The default gives the set of objects
 of the class Ada in the current image.


 Displaying : Fields := Library.Ada_Format;

 Specifies the set of data to list about each object. The default is to list
 the Ada format set of data.


 Sorted_By : Field := Library.Declaration;

 Specifies the field that should be sorted to order the list. The default is
 to order by the declaration.


 Descending : Boolean := False;

 Specifies whether to reverse the ordering. The default is to use the
 natural ascending 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.


 Options : String := "";

 No options currently are implemented for this command. This parameter is
 reserved for future development.


 EXAMPLES

 Consider the following world:

   !Users.Gzc         :   Library (World);
     File_1           :   File (Text);
     Library          :   Library (Directory);
     My_Unit          : I Ada (Pack_Spec);
     My_Unit          : I Ada (Pack_Body);
     Sample_Directory :   Library (Directory);
     Sample_World     :   Library (World);
     S_1              :   Session;
     S_1_Switches     :   File (Switch);

 The following command displays all of the Ada units in the above world,
 their status, and their subclass, as shown below:

   Ada_List ("!Users.Gzc.@'c(Ada)");

   92/01/06 14:48:11 ::: Listing of !USERS.GZC.@'C(ADA) sorted by
   declaration.

    STATUS           DECLARATION
   =========  ==========================
   INSTALLED  My_Unit : Ada (Pack_Spec);
   INSTALLED  My_Unit : Ada (Pack_Body);

   92/01/06 14:48:12 ::: [End of Library.List command -- No errors
   detected].

 REFERENCES

 procedure File_List
 procedure List
 procedure Verbose_List



 @node !Commands.Library.All_Fields

 All_Fields : constant Fields := Fields'(others => True);

 DESCRIPTION

 Defines a constant that specifies that all fields of data be displayed for
 the objects displayed by the List procedure.



 @node !Commands.Library.Compact_Library

 procedure Compact_Library (Existing : Name   := "<SELECTION>";
                            Response : String := "<PROFILE>");

 DESCRIPTION

 Reduces the amount of storage consumed by frequently modified libraries
 (worlds or directories).

 Libraries accumulate unneeded information as objects in them are created
 and destroyed. This procedure removes the unneeded information, reducing
 the space required by the library.


 PARAMETERS

 Existing : Name := "<SELECTION>";

 Specifies the name of the library to be compacted. The default is the
 current selection. No other jobs can reference a library being
 compacted.


 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 compacts the specified library, resulting in the
 display below:

   Library.Compact_Library ("!Users.Gzc);

   92/01/06 14:57:45 ::: [Library.Compact_Library ("!users.gzc", PERSEVERE);].
   92/01/06 14:57:47 --- GZC's size was 9658 bytes, new size is 8237.
   92/01/06 14:57:47 +++ !USERS.GZC has been compacted.
   92/01/06 14:57:47 ::: [End of Library.Compact_Library command -- No errors
   92/01/06 14:57:47 ... detected].


 @node !Commands.Library.Context

 procedure Context (To_Be    : Context_Name := "$";
                    Response : String       := "<PROFILE>");

 DESCRIPTION

 Sets the context for resolving names to the specified location.

 The context is set on a per-job basis. After the naming-resolution context
 has been set to a particular library, objects in that library can be
 referenced using their simple names for the duration of the job. The
 Context command thus serves to reduce the amount of typing required to
 specify Environment objects to subsequent commands.

 Promoting a command window initiates a single job, no matter how many com-
 mands are executed at a time. When a job is initiated, the context for
 naming resolution is the current library (the library that is or encloses
 the object to which the job's command window is attached). If you need to
 reference objects in a different library during the course of the job, you
 can use the Context command
 to change the context to that library. Then, for the rest of the job (or
 until you change the context again), you need use only simple names for
 the objects in that library.


 PARAMETERS

 To_Be : Context_Name := "$";

 Specifies the new context for resolving names, which must be a world or a
 directory. By default, this parameter specifies that the command display
 the current naming-resolution context without changing it. Wildcards,
 attributes, and context characters can be used in this name if the name
 resolves unambiguously to only one 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.


 EXAMPLES

 Assume that the user GZC opens a command window attached to the library
 !Users.Gzc. From this command window, she wants to perform operations on
 objects in !Users.Gzc.Sample_Directory. She can do this as follows:

   Library.Context ("!Users.Gzc.Sample_Directory");
   Library.Delete ("To_Do");
   Text.Create ("New_List");
   Library.Rename ("My_File", "Your_File");

 Note that these commands are equivalent to the following commands entered
 from the same context:

   Library.Delete ("Sample_Directory.To_Do");
   Text.Create ("Sample_Directory.New_List");
   Library.Rename ("Sample_Directory.My_File", "Sample_Directory.Your_File");

 REFERENCES

 procedure Enclosing_World



 @node !Commands.Library.Context_Name

 subtype Context_Name is Name;

 DESCRIPTION

 Defines the name of a world or directory that is the context for other
 commands or name resolution.

 The name can use special names, wildcards, and context prefixes but must
 resolve to a unique directory or world. See the Parameter-Value
 Conventions tabbed section in the Reference Summary (RS) book for more
 information about referencing Environment objects.



 @node !Commands.Library.Copy

 procedure Copy (From       : Name    := "<REGION>";
                 To         : Name    := "<IMAGE>";
                 Recursive  : Boolean := True;
                 Response   : String  := "<PROFILE>";
                 Copy_Links : Boolean := True;
                 Options    : String  := "");

 DESCRIPTION

 Copies the contents of one or more existing source objects to or into the
 specified destination object(s).

 This procedure can be used to copy objects under a different name in the
 same library. The procedure also can be used to copy objects into a
 different library, under either the same or a different simple name.
 Multiple objects can be copied under new names by specifying the From
 parameter with wildcards and the To parameter with substitution
 characters.

 The source object(s) must already exist. If a source object contains other
 objects, the default value of the Recursive parameter causes the contained
 subobjects to be copied as well. If more than one object is copied, each
 object is copied independently of any other.

 The destination object may, but need not, already exist:

 *  If the destination object already exists, it must be of the same class
    as the source object. The Copy procedure overwrites (and in some cases
    merges) the contents of the destination object with the contents of the
    source object. For Ada units and files, a new version of the destination
    object is created, which may force old versions of the object to be
    expunged.

 *  If the destination object does not already exist, it is created. A
    newly created destination object has the same class as its source
    object (that is, copying a world creates a new world). For all Ada
    units, the destination object is created in the source state.

 If you are copying a library that is associated with a library switch file,
 then the copy operation handles the association as follows:

 *  If the library is copied along with its switch file, the copy of the
    library is associated with the copy of the switch file. This situation
    frequently arises when you copy a library that contains its switch file.
    Note that when copying directories between views in a subsystem, you
    may need to change switch-file associations that arise this way.

 *  If the library is copied without its switch file, the copy is associated
    with the same switch file as the copy's parent library.

 Note that when worlds are copied, the default value of the Copy_Links
 parameter causes their links to be copied as well. Note also that the
 semantic consistency of copied Ada units is not assured by the Copy
 procedure. Semantic references must be checked after the object is copied.

 Depending on the types of source and destination objects that are
 specified, the Copy command either copies the source object to the
 destination object (overwriting it or merging their contents) or copies
 the source object into the destination object (provided that the
 destination object can contain other objects). For example, copying an
 object from one library to another with the same simple name can be
 accomplished by using the name of the destination library as the To
 parameter.

 Table 3 summarizes the to or into copy operations that result from
 specifying various types of objects as the To and From parameters. The
 number in parentheses following the results indicates a restriction on
 the move. These restrictions are listed below the table.

       Table 3   Using the Copy Procedure with To and From Parameters
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |         |To     |To     |       |       |To     |       |
       |From     |Non-Ada|Library|To     | To    |Direct | To No |
       |         |Object |Unit   |Subunit| World | ory   | Object|
       |         |       |       |       |       |       |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Non-Ada  |To (1) |Error  |Error  | Into  | Into  | To    |
       |Object   |       |       |       |       |       |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Library  |Error  |To     |To     | Into  | Into  | To    |
       |Unit (2) |       |       |       |       |       |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Subunit  |Error  |Into   |To     | Into  | Into  | To    |
       |(2)      |       |       |       |       |       |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |World (3)|Error  |Error  |Error  | To (4)| To (4)| To    |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Directory|Error  |Error  |Error  | To (4)| To (4)| To    |
       |(3)      |       |       |       |       |       |       |
        --------------------------------------------------------- 


 1 The objects must be of the same class.

 2 If the Recursive parameter is True, the subunits of the unit are involved. 
   The relative nesting of subunits is preserved.

 3 If the Recursive parameter is True, the subcomponents of the library are
   involved. The relative nesting of subcomponents is preserved.

 4 The contents of the From library are merged with the contents of the To
   library.                                          


 PARAMETERS

 From : Name := "<REGION>";

 Specifies the existing object or objects to be copied. Multiple objects can
 be specified using wildcards, context characters, set notation, indirect
 files, and attributes. The default is the selection, whether or not the
 cursor is in the selection.


 To : Name := "<IMAGE>";

 Specifies the name of the destination object. If a relative pathname is
 specified, it is interpreted relative to the current library. The default
 is the current image. Substitution characters can be used to create the
 destination name(s) from the source name(s). Each source name must map to
 a unique destination name.

 If the To parameter names an existing object, that object is overwritten
 or objects are copied into it, as specified above. If the To parameter does
 not name an existing object, the destination object is created.


 Recursive : Boolean := True;

 Specifies whether to copy objects contained in the specified source objects.
 The default is to copy all contained 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.


 Copy_Links : Boolean := True;

 Specifies whether to copy the links that are associated with worlds
 specified by the To parameter. The default is to copy all links. If
 Copy_Links is False when copying worlds, the copied worlds will have no
 links.


 Options : String := "";

 No options currently are implemented. This parameter is reserved for
 future development.


 RESTRICTIONS

 Objects representing devices cannot be copied.

 Any situation that would require demoting unrelated declarations results
 in an error, suppressing the copy.

 For Ada units, changing the simple name during a copy may require changing
 the name in the Ada-unit declaration before installation.


 EXAMPLES

 Consider the following world:

   !Users.Rjb : Library (World);
       Check_Messages : Ada (Proc_Spec);
       Check_Messages : Ada (Proc_Body);
       Macros         : Library (Directory);
       Sample         : File (Text);

 The following command, entered from the context !Users.Rjb, creates a copy
 of the file Sample in the same world:

   Copy ("Sample","Sample2");

 The world now appears as shown below:

   !Users.Rjb : Library (World);
       Check_Messages : Ada (Proc_Spec);
       Check_Messages : Ada (Proc_Body);
       Macros         : Library (Directory);
       Sample         : File (Text);
       Sample2        : File (Text);

 Now user JPL would like to copy the Macros package into his home library.
 He can do this with either of the following commands, entered from the
 context !Users.Rjb:

   Copy ("Macros","!Users.Jpl.Macros");
   Copy ("Macros","!Users.Jpl");

 Alternatively, he can do this with the following command, entered from his
 home library, !Users.Jpl:

   Copy ("!Users.Rjb.Macros","Macros");

 The world Rjb is not changed, but package Macros and all subunits are
 copied into !Users.Jpl. If package Macros already exists in the world Jpl,
 a new version of the package is created and older versions may be lost.

 Finally, suppose user JPL wants to copy the Macros package into his home
 library but wants to call it New_Macros. He can do this with the following
 command, entered from the context !Users.Rjb:

   Copy ("Macros","!Users.Jpl.New_Macros");
   

 REFERENCES

 procedure Move
 procedure Rename



 @node !Commands.Library.Create

 procedure Create (Name     : Library.Name := ">>LIBRARY NAME<<";
                   Kind     : Library.Kind := Library.Directory;
                   Vol      : Volume       := Library.Nil;
                   Model    : String       := "!Model.R1000";
                   Response : String       := "<PROFILE>");

 DESCRIPTION

 Creates a library or package in the Environment library hierarchy.

 The new object is created with the specified name and class on the specified
 disk volume. In particular:

 *  If the object is a world, the Vol parameter can be used to specify the
    disk volume on which the world is built. Furthermore, the Model
    parameter can be used to specify the model from which the new world
    gets its links, its target key, and its library switch-file association.

 *  If the object is a package or a directory, it is built on the same
    volume as the nearest enclosing world. Furthermore, if the object is a
    directory, it gets its library switch-file association from its parent
    library.


 PARAMETERS

 Name : Library.Name := ">>LIBRARY NAME<<";

 Specifies the name of the new object. This parameter must specify a single
 object that does not already exist. If a single name component is
 specified, the new object is created under that name in the current
 library. Alternatively, a qualified name can be specified to create the
 object in a location other than the current library (however, the specified
 location must exist). Wildcards, context prefixes, and attributes can be
 used except in the rightmost component of the name (the object's simple
 name). The default parameter placeholder ">>LIBRARY NAME<<" must be
 replaced or an error will result.


 Kind : Library.Kind := Library.Directory;

 Specifies the kind of object to be built. The default is a directory.


 Vol : Volume := Library.Nil;

 Specifies the disk volume on which the object is built. The default
 specifies the "best" volume, as defined by the Environment (see constant
 Nil). This parameter is ignored when packages and directories are created.


 Model : String := "!Model.R1000";

 Specifies the model to be used when a world is created. The new world gets
 its links, its target key, and its library switches from the model. The
 default model is !Model.R1000, which has links to most Environment
 resources.

 Specifying the null string ("") creates a world with no links and with a
 target key for R1000 compilation. When the null string is specified, the
 new world inherits its library switch-file association from its parent
 library.


 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

 Worlds can be created only in other worlds and in directories that are
 nested in other worlds. Worlds cannot be created in subsystems or views.


 EXAMPLES

 The following command creates a directory called My_Directory in the world
 !Users.Gzc:

   Library.Create ("!Users.Gzc.My_Directory");
   

 REFERENCES

 procedure Create_Directory
 procedure Create_Unit
 procedure Create_World



 @node !Commands.Library.Create_Directory

 procedure Create_Directory
                (Name     : Library.Name := ">>DIRECTORY NAME<<";
                 Kind     : Library.Kind := Library.Directory;
                 Vol      : Volume       := Library.Nil
                 Model    : String       := "";
                 Response : String       := "<PROFILE>")
                                                  renames Create;

 DESCRIPTION

 Creates a directory with the specified name.

 The new directory is built on the same volume as the nearest enclosing
 world. Furthermore, the new directory gets its library switch-file
 association from its parent library.

 This procedure is a rename of the Create procedure and has the same
 parameter profile, with the exception of the Model parameter.


 PARAMETERS

 Name : Library.Name := ">>DIRECTORY NAME<<";

 Specifies the name of the new directory. This parameter must specify a
 single object that does not already exist. If a single name component is
 specified, the new directory is created under that name in the current
 library. Alternatively, a qualified name can be specified to create the
 directory in a location other than the current library (however, the specified
 location must exist). Wildcards, context prefixes, and attributes can be used
 except in the rightmost component of
 the name (the object's simple name). The default parameter placeholder
 ">>DIRECTORY NAME<<" must be replaced or an error will result.


 Name : Library.Kind := Library.Directory;

 Specifies the type of unit to create--in this case, a directory.


 Vol : Volume := Library.Nil;

 Specifies the disk volume on which the object is built. The default
 specifies the "best" volume, as defined by the Environment (see constant
 Nil). Nondefault values for this parameter are ignored when directories
 are created.


 Model : String := "";

 For use in creating worlds only.


 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 directory called My_Directory in the world
 !Users.Gzc:

   Library.Create_Directory ("!Users.Gzc.My_Directory");
              

 REFERENCES

 procedure Create
 procedure Create_Unit
 procedure Create_World



 @node !Commands.Library.Create_Unit

 procedure Create_Unit
                  (Name     : Library.Name := ">>ADA NAME<<";
                   Kind     : Library.Kind := Library.Subpackage;
                   Vol      : Volume       := Library.Nil
                   Model    : String       := "";
                   Response : String       := "<PROFILE>")
                                                  renames Create;

 DESCRIPTION

 Creates a package specification and a body with the specified name.

 These objects are created and installed in the current library. This
 procedure typically is used in programs rather than interactively.

 This procedure is a rename of the Create procedure.


 PARAMETERS

 Name : Library.Name := ">>ADA NAME<<";

 Specifies the name of the unit to be created. If a single name component is
 specified, the new unit is created under that name in the current
 library. Alternatively, a qualified name can be specified to create the unit
 in a location other than the current library (however, the specified location 
 must exist). Wildcards, context prefixes, and attributes can be used except in
 the rightmost component of the name (the object's simple name). The default
 parameter placeholder ">>ADA NAME<<" must be replaced or an error will
 result.


 Kind : Library.Kind := Library.Subpackage;

 Specifies the kind of object to be built--in this case, a package.


 Vol : Volume := Library.Nil;

 Specifies the disk volume on which the object is built. The default
 specifies the "best" volume, as defined by the Environment (see constant
 Nil). Nondefault values for this parameter are ignored when packages are
 created.


 Model : String := "";

 For use in creating worlds only.


 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 package specification and a body called My-
 _Unit in the world !Users.Gzc and promotes them to the installed state:

   Library.Create_Unit ("!Users.Gzc.My_Unit");

 REFERENCES

 procedure Create
 procedure Create_Directory
 procedure Create_World



 @node !Commands.Library.Create_World

 procedure Create_World
                    (Name     : Library.Name := ">>WORLD NAME<<";
                     Kind     : Library.Kind := Library.World;
                     Vol      : Volume       := Library.Nil
                     Model    : String       := "!Model.R1000";
                     Response : String       := "<PROFILE>")
                                                  renames Create;

 DESCRIPTION

 Creates a world with the specified name on the specified volume.

 The Model parameter can be used to specify the model from which the new
 world gets its links, its target key, and its library switch-file
 association. If no model is specified, the world is created with no links
 and with a target key for R1000 compilation. Furthermore, the new world
 gets its library switch-file association from its parent library.

 This procedure is a rename of the Create procedure and has the same
 parameter profile, with the exception of the Model parameter.


 PARAMETERS

 Name : Library.Name := ">>WORLD NAME<<";

 Specifies the name of the world to create. This parameter must specify a
 single object that does not already exist. If a single name component is
 specified, the new world is created under that name in the current library.
 Alternatively, a qualified name can be specified to create the world in a
 location other than the current library (however, the specified location
 must exist). Wildcards, context prefixes, and attributes can be used except
 in the rightmost component of the name (the object's simple name). The
 default parameter placeholder ">>WORLD NAME<<" must be replaced or an
 error will result.


 Kind : Library.Kind := Library.World;

 Specifies the kind of unit to be built. The default is a world.


 Vol : Volume := Library.Nil;

 Specifies the volume on which to create the world. The default value
 specifies that the world should be created on the "best" volume, as defined
 by the Environment. The best volume is one of the volumes with the most
 free space (see constant Nil).


 Model : String := "!Model.R1000";

 Specifies the model to be used in creating the new world. The new world
 gets its links, its target key, and its library switches from the model.
 By default, !Model-
 .R1000 is used, which has links to most Environment resources.

 Specifying the null string ("") creates a world with no links and with a
 target key for R1000 compilation. When the null string is specified, the
 new world inherits its library switch-file association from its parent
 library.


 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

 Worlds can be created only in other worlds and in directories that are
 nested in other worlds. Worlds cannot be created in subsystems or views.


 EXAMPLES

 The following command creates a world called My_World in !Users.Gzc. The
 links for this world are copied from the links located in !Model.R1000:

   Library.Create_World ("!Users.Gzc.My_World");
    

 REFERENCES

 procedure Create
 procedure Create_Directory
 procedure Create_Unit



 @node !Commands.Library.Default

 procedure Default (Existing : Name   := "<SELECTION>";
                    Response : String := "<PROFILE>");

 DESCRIPTION

 Sets the specified version of an object to be the default version.

 If the current default version is specified, it is in effect exchanged with
 itself. When a nondefault version is specified, it is exchanged with the
 current default version, essentially "reverting" the object to the
 specified version.

 A nondefault version can be specified only if it has been retained (that
 is, if the object's retention count is high enough to prevent it from
 being expunged).

 Directories and worlds do not have multiple versions, so this procedure
 does not affect them.

 When applied to a deleted object (an object with no default version), this
 procedure is equivalent to undeleting the object using the Undelete
 procedure.


 PARAMETERS

 Existing : Name := "<SELECTION>";

 Specifies the version to be made the default version. The default is the
 current selection.

 Version numbers can be specified using the 'V attribute, as in
 My_File'V(3). Omitting the version number specifies the current default
 version. Omitting the version number when there is no default version
 causes the highest-numbered nondefault version to be made the default.


 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 user GZC has copied an Ada unit called Unit_1 from another
 directory. The original version ('V(1)) contained several errors, which
 she repaired in a second version ('V(2)). In the third version ('V(3)),
 she made several modifications that she no longer wants. To return to the
 desired version ('V(2)), she can use the command:

   Library.Default ("!Users.Gzc.Unit_1'V(2)");

 REFERENCES

 procedure Undelete



 @node !Commands.Library.Default_Keep_Versions

 Default_Keep_Versions : constant := -1;

 DESCRIPTION

 Defines a constant that can be specified in the Set_Retention_Count command.

 When used in this command, the value of Default_Keep_Versions causes an
 object to take its retention count from its parent. For example, when the
 object is a child of a library, the object is given the default retention
 count that is associated with the library. When the object is a subunit of
 an Ada unit, the subunit is given the same retention count as the parent
 unit.


 REFERENCES

 procedure Set_Retention_Count



 @node !Commands.Library.Delete

 procedure Delete
           (Existing : Name                     := "<SELECTION>";
            Limit    : Compilation.Change_Limit := "<DIRECTORIES>";
            Response : String                   := "<PROFILE>");
                                        renames Compilation.Delete;

 DESCRIPTION

 Deletes the default version of the selected or named object.

 Deleting an object's default version effectively deletes the object from
 the library system. However, if the object has a retention count of at
 least 1, the deleted default version is retained and can be undeleted
 with the Undelete command, if desired. If the object has a retention count
 of 0, the delete operation is unrecoverable and the object is expunged
 as well as deleted. Note that deleting a library is always a permanent
 operation; libraries cannot be undeleted.

 Deleting an Ada unit using this procedure also deletes subordinate units
 (bodies and subunits). Any units within the specified limit that depend on
 a deleted unit are automatically demoted to the source state. A delete
 operation is abandoned if it would cause the demotion of units outside the
 specified limit.

 To expunge deleted versions that have been retained, use the Expunge
 procedure. To make unrecoverable deletions, use the Destroy procedure.


 PARAMETERS

 Existing : Name := "<SELECTION>";

 Specifies the name of the object to be deleted. The default is the current
 selection, provided that the selection contains the cursor. Multiple
 objects can be specified using wildcards, context characters, set notation,
 indirect files, and attributes.


 Limit : Compilation.Change_Limit := "<DIRECTORIES>";

 Specifies the extent to which Ada units can be demoted to permit deletion.
 By default, units can be demoted only if they are in the same directories
 as the units specified in the Existing parameter. The values that can be
 specified for the Limit parameter are defined in the
 Compilation.Change_Limit subtype; they are repeated here for convenience:

 "<UNITS>"                  Modifies only the units named in the operation.

 "<SUBUNITS>"               Modifies only the units named in the operation
                            and their subunits.

 "<DIRECTORIES>"            Modifies only the units that share the same
                            enclosing library as a unit specified to the
                            operation.

 "<WORLDS>"                 Modifies only the units that share the same
                            enclosing world as a unit specified to the
                            operation.

 "<ACTIVITY>"               Modifies only units in views named in the
                            current activity.

 "<ALL_WORLDS>"             Modifies a unit in any world.


 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 user GZC has in her home library a file called Test_File that
 she no longer needs. To remove the file from the directory, she can enter
 the command:

   Library.Delete ("!Users.Gzc.Test_File");

 REFERENCES

 renamed procedure Destroy
 procedure Expunge
 procedure Undelete
 subtype Compilation.Change_Limit
 procedure Compilation.Delete



 @node !Commands.Library.Destroy

 procedure Destroy
        (Existing  : Name                     := "<SELECTION>";
         Threshold : Natural                  := 1;
         Limit     : Compilation.Change_Limit := "<DIRECTORIES>";
         Response  : String                   := "<PROFILE>")
                                     renames Compilation.Destroy;

 DESCRIPTION

 Destroys all versions of the specified object.

 Destroying an object is equivalent to deleting and expunging all versions
 of that object. A destroyed object cannot be recovered; recoverable
 deletions can be made with the Delete procedure.

 Destroying an Ada unit also destroys subordinate units (bodies and
 subunits). A destroy operation is abandoned if it would cause the demotion
 of units outside the specified limit.

 The procedure provides for a threshold number of dependent objects that
 can be destroyed along with each specified object. If the threshold is
 exceeded, the procedure abandons all destructions. The threshold serves
 as a safeguard against destroying too many objects. For example, if you
 inadvertently specify a wildcard expression that matches a library you do
 not want to destroy, and the default threshold is used, the operation is
 abandoned because the library has more dependents than are permitted by
 the default threshold. The procedure can be executed again with a new
 threshold (or with a more precise naming expression).


 PARAMETERS

 Existing : Name := "<SELECTION>";

 Specifies the name of the object to be destroyed. The default is the
 current selection, provided that it contains the cursor. Multiple
 objects can be specified using wildcards, context characters, set notation,
 indirect files, and attributes.


 Threshold : Natural := 1;

 Specifies the total number of objects per named object that can be
 destroyed before the procedure fails. The default permits only the named
 units--not their dependents--to be destroyed.


 Limit : Compilation.Change_Limit := "<DIRECTORIES>";

 Specifies which Ada units can be demoted to allow the destruction. By
 default, units can be demoted only if they are in the same directories as
 the units to be destroyed. The values that can be specified for the Limit
 parameter are defined in the Compilation.Change_Limit subtype; they are
 repeated here for convenience:

 "<UNITS>"                  Modifies only the units named in the operation.

 "<SUBUNITS>"               Modifies only the units named in the operation
                            and their subunits.

 "<DIRECTORIES>"            Modifies only the units that share the same
                            enclosing library as a unit specified to the
                            operation.

 "<WORLDS>"                 Modifies only the units that share the same
                            enclosing world as a unit specified to the
                            operation.

 "<ACTIVITY>"               Modifies only units in views named in the
                            current activity.

 "<ALL_WORLDS>"             Modifies a unit in any world.


 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

 A user named GZC has in her home library a text file called Test_File that
 she no longer needs. To delete and expunge the file from the directory, she
 would enter the command:

   Library.Destroy ("!Users.Gzc.Test_File");

 The file would not be recoverable with the Undelete procedure.

 A user named GZC has an Ada unit called Macros in her home library. She
 wants to destroy both the spec and the body. To do this, she uses the
 command:

   Destroy ("Macros",2);

 REFERENCES

 procedure Delete
 procedure Compilation.Destroy



 @node !Commands.Library.Display

 procedure Display (Name : Library.Name := "[]");

 DESCRIPTION

 Displays the library containing the named object, with that object
 highlighted.


 PARAMETERS

 Name : Library.Name := "[]";

 Specifies a simple name. The default is the current context.



 @node !Commands.Library.Enclosing_World

 procedure Enclosing_World (Levels   : Positive := 1;
                            Response : String   := "<PROFILE>");

 DESCRIPTION

 Changes the context for resolving names to the parent world of the current
 context.

 This procedure is equivalent to entering the Context command with the
 appropriate naming expression: Context ("^$$");


 PARAMETERS

 Levels : Positive := 1;

 Specifies the number of levels (worlds) to go up in changing the context.


 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 the current context is the world !Users.Gzc.Sample_World.
 Entering the following command here changes the naming-resolution context
 to the parent world--namely, !Users.Gzc:

   Library.Enclosing_World;

 REFERENCES

 procedure Context
 Editing Specific Types (EST), procedure Common.Enclosing



 @node !Commands.Library.Error

 Error : exception renames Profile.Error;

 DESCRIPTION

 Defines the exception raised when an error condition occurs in a command
 and when the error reaction defined in the profile requests an exception to
 be raised.



 @node !Commands.Library.Expunge

 procedure Expunge (Existing      : Name    := "<IMAGE>";
                    Keep_Versions : Integer := 0;
                    Recursive     : Boolean := True;
                    Response      : String  := "<PROFILE>");

 DESCRIPTION

 Expunges all but the specified number of retained versions for the
 designated objects.

 Expunged versions cannot be referenced or undeleted. This procedure does
 not affect an object's default version. However, deleting an object's
 default version and then expunging all of its retained versions removes
 that object from the Environment permanently.

 Previous versions of an object are retained only when the object's
 retention count is greater than zero. Retained versions can be referenced,
 undeleted, or reinstated as the object's default version. The Expunge
 procedure overrides the retention count to delete some or all of the
 retained versions permanently. If an object has a retention count of zero,
 there are no versions for this procedure to expunge.

 By default, this procedure expunges all of an object's retained versions.
 However, some number of retained versions can be preserved by specifying
 the Keep_Versions parameter. When the Keep_Versions parameter is
 specified, the least recent (lower-numbered) versions are expunged, leaving
 the specified number of more recent (higher-numbered) versions. Note that
 the default version is never expunged, even if its version number is
 low.


 PARAMETERS

 Existing : Name := "<IMAGE>";

 Specifies the name of the objects whose retained versions are to be
 expunged. The default is the current image. Multiple objects can be
 specified using wildcards, context characters, set notation, indirect files,
 and attributes.


 Keep_Versions : Integer := 0;

 Specifies the number of versions that are to be preserved. The default is
 to keep zero deleted versions (to expunge all deleted versions).


 Recursive : Boolean := True;

 Specifies whether to expunge any subobjects of the named object. The
 default is to expunge all subobjects, as well as the named object.


 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 File_1 in !Users.Gzc has been deleted. The following command
 permanently expunges all versions of that object:

   Library.Expunge ("!Users.Gzc.{File_1}");

 REFERENCES

 procedure Delete



 @node !Commands.Library.Field

 type Field is (Object, Version, Class, Subclass, Updater,
                Update_Time, Creator, Create_Time, Reader,
                Read_Time, Size, Status, Frozen, Retain,
                Declaration);

 DESCRIPTION

 Defines the set of data that can be displayed for any object.

 This type is used to specify what data are displayed about objects in the
 List procedure and several renames of List. The type is also used to
 specify what data the listing is sorted by when a display is generated.


 ENUMERATIONS


 Class

 Specifies display of the class name of the object.


 Create_Time

 Specifies display of the time when the object was created.


 Creator

 Specifies display of the name of the user who created the object.


 Declaration

 Specifies display of the declaration of the object. Sorting by declaration
 means displaying objects in the order in which they occur in their
 enclosing package.


 Frozen

 Specifies display of whether the object is frozen.


 Object

 Specifies display of the unique simple name of the object.


 Read_Time

 Specifies display of the time when the object was last read.


 Reader

 Specifies display of the name of the user who last read the object.


 Retain

 Specifies display of the number of retained versions of the object.


 Size

 Specifies display of the size of the object in bytes of data (which
 includes some overhead).


 Status

 Specifies display of the declaration state of the object (applies only to
 Ada-class objects).


 Subclass

 Specifies display of the subclass of the object.


 Update_Time

 Specifies display of the time of the last update. For Ada objects, this is
 the time when editing began after the last time the image was committed
 (saved).


 Updater

 Specifies display of the name of the user who last updated the object.


 Version

 Specifies display of the version of the object. An asterisk appears in
 front of the default version name.


 REFERENCES

 procedure Ada_List
 procedure File_List
 procedure List
 procedure Verbose_List



 @node !Commands.Library.Fields

 type Fields is array (Field) of Boolean;

 DESCRIPTION

 Defines a type used to specify the set of data to be displayed by the List
 procedure.

 A parameter of this type in the List procedure specifies the fields to
 display. Several constants of this type provide common sets of fields.


 REFERENCES

 constant Ada_Format
 procedure Ada_List
 constant All_Fields
 procedure File_List
 procedure List
 constant Terse_Format
 constant Verbose_Format
 procedure Verbose_List



 @node !Commands.Library.File_List

 procedure File_List
                 (Pattern    : Name    := "<IMAGE>@'C(FILE)";
                  Displaying : Fields  := Library.Verbose_Format;
                  Sorted_By  : Field   := Library.Object;
                  Descending : Boolean := False;
                  Response   : String  := "<PROFILE>";
                  Options    : String  := "") renames List;

 DESCRIPTION

 Displays the specified set of data for the specified set of file objects.

 The procedure performs exactly as the List procedure except that this
 procedure has different default parameters. The default parameters in this
 procedure provide a detailed display of all versions of all File-class
 objects in the current context.


 PARAMETERS

 Pattern : Name := "<IMAGE>@'C(FILE)";

 Specifies the set of objects to be listed. Special names, wildcards,
 context prefixes, and attributes can be used in this name. The default
 gives the set of all versions of all File-class objects in the default
 context.


 Displaying : Fields := Library.Verbose_Format;

 Specifies the set of data to display about each object. The default is to
 display the verbose set.


 Sorted_By : Field := Library.Object;

 Specifies the field that should be sorted to order the list. The default is
 to order alphabetically by the object name.


 Descending : Boolean := False;

 Specifies whether to reverse the ordering. The default is to use the
 natural ascending 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.


 Options : String := "";

 No options currently are implemented for this command. This parameter is
 reserved for future development.


 EXAMPLES

 Consider the world shown below:

   !Users.Gzc
     File_1
     Library
     My_Directory
     My_Unit
     My_Unit
     Sample_Directory
     Sample_World
     S_1
     S_1_Switches

 The following command produces the display shown below, which lists infor-
 mation for the two files in that world:

 Library.File_List;

 92/01/06 17:24:17 ::: Listing of !USERS.GZC.<IMAGE>@'C(FILE) sorted by object.

 OBJECT       VER CLASS SUBCLASS UPDATER   UPDATE_TIME     SIZE STATUS FRZ RETAIN
 ============ === ===== ======== ======= ================= ==== ====== === ======
 FILE_1       *2  FILE   TEXT      GZC   92/01/06 16:02:15  37   n/a   1
 S_1_SWITCHES *4  FILE   SWITCH    GZC   92/01/06 17:23:23 303   n/a   1
 92/01/06 17:24:19 ::: [End of Library.List command -- No errors detected].

 REFERENCES

 procedure Ada_List
 procedure List
 procedure Verbose_List



 @node !Commands.Library.Freeze

 procedure Freeze (Existing  : Name    := "<IMAGE>";
                   Recursive : Boolean := True;
                   Response  : String  := "<PROFILE>");

 DESCRIPTION

 Freezes the specified object or objects to prevent further changes to it.

 The procedure can freeze a single object or an entire library structure of
 objects.

 Freezing objects can be used as part of releasing software. When objects
 are frozen, no changes can be made to them, including changing Ada-unit
 state. However, frozen units can be executed. The Unfreeze procedure
 undoes the effect of this procedure.

 The Freeze and Unfreeze procedures are both subject to access-control
 restrictions. To freeze or unfreeze objects within a world, a user must
 have owner access to that world.


 PARAMETERS

 Existing : Name := "<IMAGE>";

 Specifies the object to be frozen. The default is the current image.
 Special names, context prefixes, wildcards, and attributes can be used to
 specify any series of objects to be frozen.


 Recursive : Boolean := True;

 Specifies whether to freeze subobjects. The default is to freeze
 subobjects. To avoid freezing subworlds, use Recursive => False and the
 wildcard ?.


 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

 A user has in his home library a world called Sample_World that he wants
 to freeze. To accomplish this, he can use the following command:

   Library.Freeze ("Sample_World");

 REFERENCES

 procedure List
 procedure Unfreeze


                                                                           

 @node !Commands.Library.Kind

 type Kind is (World, Directory, Subpackage);

 DESCRIPTION

 Defines the major structural elements that can be created to produce the
 Environment library hierarchy.


 ENUMERATIONS


 Directory

 Defines a directory as a structural element in the library system.
 Directories provide a structural element that is also like an Ada
 library. Directories and worlds are collectively called libraries. A
 directory provides a closed naming scope as does a library. It also
 requires explicit imports and exports through a set of links. A direc-
 tory, however, uses the set of links provided by the enclosing world; a
 directory does not have its own links.

 Directories are used for structuring or partitioning the contents of a
 world. Because the world contains all of the links for the entire
 structure, directories are better suited to breaking down the project or
 system within the world.

 Directories can be nested inside other directories or worlds, including
 subsystems and views. Directories can contain any set of units such as
 directories, worlds, Ada units, files, sessions, or other
 Environment-defined objects.


 Subpackage

 Defines a standard Ada package as a structural element in the library
 system. A subpackage is an element of its containing library. It resides
 on the same disk volume as its enclosing world. Subpackages do not have
 links.


 World

 Defines a world as a structural element in the library system. Worlds
 provide a structural element that is like an Ada library. Directories and
 worlds are collectively called libraries. A world provides a closed
 naming scope as does a library. A world requires explicit imports and
 exports through a set of links. Each world has its own links. These links
 provide imports and exports not only for the world but also for any
 contained directory. In addition, these links provide name resolution for
 units within the world or within contained directories.

 Worlds are used as the resource-management element. The effect of links
 and the closed scoping makes a world the focal point for name resolution
 and resource allocation. The internal links associated with a world allow
 any unit in any directory within the world to have visibility to other
 units. Thus the world and its associated set of links can capture the
 entire set of names.

 Worlds can be nested inside other directories or worlds. However, they
 cannot be created within subsystems or views. Worlds can contain any set
 of units, such as directories, worlds, Ada units, files, sessions, or other
 Environment-defined objects. For further information about directories and
 worlds, see Chapter 1, "Managing Libraries."


 REFERENCES

 procedure Create
 procedure Create_Directory
 procedure Create_Unit
 procedure Create_World



 @node !Commands.Library.List

 procedure List (Pattern    : Name    := "<IMAGE>@";
                 Displaying : Fields  := Library.Terse_Format;
                 Sorted_By  : Field   := Library.Object;
                 Descending : Boolean := False;
                 Response   : String  := "<PROFILE>";
                 Options    : String  := "");

 DESCRIPTION

 Displays the specified set of data about the specified set of versions of
 specified objects.

 This procedure displays a list of objects and data about those objects.
 The list displayed can be of any set of objects, sorted in any specified
 way. The default parameters produce an alphabetic list of objects with
 no additional information. Renamed versions of this procedure with
 different default parameters give other forms of lists.

 The job display is sent to Current_Output (by default, an Environment
 output window). Errors are reported in log messages, which, by default,
 are also sent to the output window.


 PARAMETERS

 Pattern : Name := "<IMAGE>@";

 Specifies the set of objects to be listed. Wildcards, context prefixes, and
 attributes can be used in this name. The default gives the set of objects
 contained by the object in the current image. For example, if the current
 image is a library, then the default value resolves to the objects in the
 library.


 Displaying : Fields := Library.Terse_Format;

 Specifies the set of data to display about each object. The default is to
 list only the name of the object.


 Sorted_By : Field := Library.Object;

 Specifies the field that should be sorted to order the list. The default is
 to order alphabetically by the object name.


 Descending : Boolean := False;

 Specifies whether to reverse the ordering. The default is to use the
 natural ascending 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.


 Options : String := "";

 No options currently are implemented for this command. This parameter is
 reserved for future development.


 EXAMPLES

 Consider the following world:

   !Users.Gzc
     File_1
     Library
     My_Directory
     My_Unit
     My_Unit
     Sample_Directory
     Sample_World
     S_1
     S_1_Switches

 The following command produces the display shown below, containing an
 alphabetical listing of all objects in this world that end with the
 string "_1":

   Library.List ("@_1");

   91/03/25 17:39:29 ::: Listing of !USERS.GZC.@_1 sorted by object.

   OBJECT
   ======
   FILE_1
   S_1

   91/03/25 17:39:30 ::: [End of Library.List command -- No errors
   detected].

 REFERENCES

 procedure Ada_List
 procedure File_List
 procedure Verbose_List



 @node !Commands.Library.Move

 procedure Move (From       : Name    := "<REGION>";
                 To         : Name    := "<IMAGE>";
                 Recursive  : Boolean := True;
                 Response   : String  := "<PROFILE>";
                 Copy_Links : Boolean := True;
                 Options    : String  := "");

 DESCRIPTION

 Copies the contents of one or more source objects to or into the specified
 destination object(s) and then deletes the source object(s).

 This procedure can be used to move an object from one library to another,
 preserving or changing its simple name in the new location. This
 procedure can also be used to give an object a new simple name within the
 same library, equivalent to the Rename procedure. Multiple objects can be
 moved and given new names by specifying the From parameter with wildcards
 and the To parameter with substitution characters.

 The source object(s) must already exist. If a source object contains other
 objects, the default value of the Recursive parameter causes the contained
 subobjects to be moved as well. If more than one object is moved, each
 object is moved independently of any other.

 The destination object may, but need not, already exist:

 *  If the destination object already exists, it must be of the same class
    as the source object. The Move procedure overwrites (and in some cases
    merges) the contents of the destination object with the contents of the
    source object. For Ada units and files, a new version of the destination
    object is created, which may force old versions of the object to be
    expunged.

 *  If the destination object does not already exist, it is created. A
    newly created destination object has the same class as its source
    object (that is, moving a world creates a new world). For all Ada
    units, the destination object is created in the source state.

 If deleting a source object would result in demotion or obsolescence of
 any Ada units, that source object is copied rather than moved. Objects
 that cannot be copied are not deleted.

 If you are moving a library that is associated with a library switch file,
 then the move operation handles the association as follows:

 *  If the library is moved along with its switch file, the moved library is
    associated with the moved switch file. This situation frequently arises
    when you move a library that contains its switch file. Note that when
    moving directories between views in a subsystem, you may need to change
    switch-file associations that arise this way.

 *  If the library is moved without its switch file, the moved library is
    associated with the same switch file as the new parent library.

 Note that when worlds are moved, the default value of the Copy_Links
 parameter causes their links to be moved as well. Note also that the
 semantic consistency of new Ada units is not assured by this procedure.
 Semantic references must be checked after the object is moved.

 Depending on the types of source and destination objects that are
 specified, the move command either moves the source object to the
 destination object (overwriting it or merging their contents) or it
 moves the source object into the destination object (provided that the
 destination object can contain other objects). Table 4 summarizes the to
 or into move operations that result from specifying various types of
 objects as the To and From parameters. The number in parentheses fol-
 lowing the results indicates a restriction on the move. These restrictions
 are listed below the table.

       Table 4   Using the Move Procedure with To and From Parameters
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |         |To     |To     |       |       |       |       |
       |From     |Non-Ada|Library|To     | To    |To     | To No |
       |         |Object |Unit   |Subunit| World |Direct | Object|
       |         |       |       |       |       | ory   |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Non-Ada  |To (1) |Error  |Error  | Into  | Into  | To    |
       |Object   |       |       |       |       |       |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Library  |Error  |To     |To     | Into  | Into  | To    |
       |Unit (2) |       |       |       |       |       |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Subunit  |Error  |Into   |To     | Into  | Into  | To    |
       |(2)      |       |       |       |       |       |       |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |World (3)|Error  |Error  |Error  | To (4)| To (4)| To    |
        --------------------------------------------------------- 
       |         |       |       |       |       |       |       |
       |Directory|Error  |Error  |Error  | To (4)| To (4)| To    |
       |(3)      |       |       |       |       |       |       |
        --------------------------------------------------------- 


 1 The objects must be of the same class.

 2 If the Recursive parameter is True, the subunits of the unit are involved. 
   The relative nesting of subunits is preserved.

 3 If the Recursive parameter is True, the subcomponents of the library are
   involved. The relative nesting of subcomponents is preserved.

 4 The contents of the From library are merged with the contents of the To
   library.                                           


 PARAMETERS

 From : Name := "<REGION>";

 Specifies the existing object or objects to be moved. Multiple objects can
 be specified using wildcards, context characters, set notation, indirect
 files, and attributes. The default is the current selection, whether or not
 the cursor is in the selection.


 To : Name := "<IMAGE>";

 Specifies the name of the destination object. If a relative pathname is
 specified, it is interpreted relative to the current library. The default
 is the current image. Substitution characters can be used to create the
 To name(s) from the From name(s); however, because the move operation
 deletes source objects, it is recommended that you use the Resolve command
 to test a pair of From and To names containing wildcards and substitution
 characters. Each source name must map to a unique destination name.

 If the To parameter names an existing object, that object is overwritten
 or objects are moved into it, as specified above. If it does not name an
 existing object, the destination object is created.


 Recursive : Boolean := True;

 Specifies whether to move subunits. The default is to move all subunits.


 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.


 Copy_Links : Boolean := True;

 Specifies whether to copy the links that are associated with worlds
 specified by the To parameter. The default is to copy all links. If
 Copy_Links is False when moving worlds, the moved worlds will have no
 links.


 Options : String := "";

 No options currently are implemented for this command. This parameter is
 reserved for future development.


 EXAMPLES

 Consider the world shown below:

   !Users.Rjb : Library (World);
       Check_Messages : Ada (Proc_Spec);
       Check_Messages : Ada (Proc_Body);
       Macros         : Library (Directory);
       Sample         : File (Text);

 It is decided that the Check_Messages procedure belongs in the Macros
 library instead of the home library. The following command, entered from
 the context !Users.Rjb, moves the procedure:

   Library.Move ("Check_Messages", "Macros.Check_Messages");

 The procedure is copied into the Macros library and then deleted from the
 Rjb world. The result is that the Rjb world contains only the Macros
 library and Sample file, and the full name of the procedure is now
 !Users.Rjb.Macros.Check_Messages.


 REFERENCES

 procedure Copy
 procedure Rename



 @node !Commands.Library.Name

 subtype Name is String;

 DESCRIPTION

 Defines a name for objects used in procedures in this package.

 The type allows special names, wildcards, context prefixes, attributes, and
 substitution characters. In some uses of this type, the name must be
 unique. See the Parameter-Value Conventions tabbed section in the
 Reference Summary (RS) book for more information about referencing
 Environment objects.



 @node !Commands.Library.Nil

 Nil : constant Volume := Volume'First;

 DESCRIPTION

 Defines the disk volume that represents the "best" volume.

 This constant is the default value for the Vol parameter of the Create
 procedure. The Vol parameter determines the disk volume to which newly
 created worlds are to be assigned. (Newly created Ada units and
 directories always are assigned to the same volume as the nearest
 enclosing world.)

 To determine the "best" disk volume, the Environment examines the
 percentage of free space on each disk volume:

 *  If one volume has at least 30% free space, that volume is the "best"
    volume.

 *  If several volumes have at least 30% free space, the "best" volume
    rotates between those volumes.

 *  If no volume has at least 30% free space, the "best" volume is that
    which has the greatest percentage of free space.

 *  If no volume has at least 30% free space and several volumes have the
    same amount of free space, the "best" volume rotates between those
    volumes with the same amount of free space.



 @node !Commands.Library.Reformat_Image

 procedure Reformat_Image (Existing : Name   := "<SELECTION>";
                           Response : String := "<PROFILE>");

 DESCRIPTION

 Forces the creation of a new pretty-printed image of an Ada unit.

 Ada units have two representations: the DIANA tree representation and the
 pretty-printed image. This procedure forces the creation of a new
 pretty-printed image of an Ada unit.

 This procedure is useful when you have changed pretty-printing switches
 and you want existing units to be formatted under the new pretty-printing
 settings. (If you do not explicitly reformat existing units with this
 procedure, they remain unaffected by new pretty-printer settings.)


 PARAMETERS

 Existing : Name := "<SELECTION>";

 Specifies the Ada unit whose image is to be reformatted. The default is the
 current image. Multiple units can be specified using wildcards, context
 characters, set notation, indirect files, and attributes.


 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.Library.Rename

 procedure Rename
               (From     : Name        := "<SELECTION>";
                To       : Simple_Name := ">>NEW SIMPLE NAME<<";
                Response : String      := "<PROFILE>");

 DESCRIPTION

 Renames the specified object, giving it the specified new name.

 This procedure has the same effect as the Move command, although Rename is
 designed to simplify the specification of names when you rename an object
 within the same library. When Rename is used, the object's new name is
 constructed by replacing the object's original simple name with the entire
 string specified by the To parameter (see the examples below).

 The renamed object contains all of the contents of the original object.
 All contained directories, worlds, links, and objects are moved into the
 new object.

 If an object with the specified new name already exists, it is overwritten
 and a new version of the object is created. If an object with the specified
 new name does not exist, it is created. For Ada units, the new object is
 created in the source state.


 PARAMETERS

 From : Name := "<SELECTION>";

 Specifies the existing object or objects to be renamed. Multiple objects
 can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. The default is the current selection.


 To : Simple_Name := ">>NEW SIMPLE NAME<<";

 Specifies the new name for the renamed object. Substitution characters are
 allowed in this name; however, because the rename operation deletes the
 original objects, it is recommended that you use the Resolve command to
 test a pair of From and To names that contain wildcards and substitution
 characters. The default parameter placeholder ">>NEW SIMPLE NAME<<" must
 be replaced or an error will result.

 The name specified for the To parameter may, but need not be, a simple
 name. The new object name is formed by replacing the simple name (the
 rightmost component) of the From name with the entire To name (after
 substitution characters have been evaluated).


 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 any renaming would result in demotion or obsolescence of an existing
 object, the object is not deleted but is still copied into the new name.
 Other objects being renamed by this procedure that do not make other units
 obsolete are not affected. Objects that cannot be copied are not deleted.

 The semantic consistency of the new object is not assured by this
 procedure. Semantic references must be checked after the object is
 renamed.


 EXAMPLES

 Consider the world shown below:

   !Users.Rjb : Library (World);
       Check_Messages : Ada (Proc_Spec);
       Check_Messages : Ada (Proc_Body);
       Macros         : Library (Directory);
       Sample         : File (Text);

 You decide that Check_Messages should be renamed Check_Mail to indicate
 the type of messages it checks. The following command, entered in the
 context !Users.Rjb, changes the object's name to !Users.Rjb.Check_Mail:

   Library.Rename ("Check_Messages","Check_Mail");

 Assume that the Rename command is to be entered from the context !Projects
 instead of !Users.Rjb. Then the From and To parameters can be specified as
 follows:

   Library.Rename ("!Users.Rjb.Check_Messages","Check_Mail");

 Finally, assume that procedure Check_Messages is to be renamed and moved
 into the Macros directory. The following command, entered from the context
 !Projects, accomplishes this, producing !Users.Rjb.Macros.Check_Mail:

   Library.Rename ("!Users.Rjb.Check_Messages","Macros.Check_Mail");

 REFERENCES

 procedure Copy
 procedure Move



 @node !Commands.Library.Resolve

 procedure Resolve (Name_Of      : Name    := "<TEXT>";
                    Target_Name  : Name    := "";
                    Objects_Only : Boolean := True;
                    Response     : String  := "<PROFILE>");

 DESCRIPTION

 Resolves the specified name by finding the object or objects it references
 and then displaying the fully qualified pathnames of those objects.

 This procedure is especially useful for evaluating names containing
 wildcards, context characters, and substitution characters.

 By default, the procedure attempts to resolve the specified name by looking
 through the objects listed in Environment libraries. However, if the
 Objects_Only parameter is set to False, the procedure also attempts to
 resolve the specified name by inspecting identifiers within Ada units.

 Note that the Resolve procedure displays the fully qualified pathname of an
 object only if you have at least read access to the world enclosing that
 object.

 The job display is sent to Current_Output (by default, an Environment
 output window). Errors are reported in log messages, which, by default,
 are also sent to the output window.


 PARAMETERS

 Name_Of : Name := "<TEXT>";

 Specifies the name to be resolved. The default is the name that is
 currently highlighted. Note that this can be a highlighted text string
 or a selected object.


 Target_Name : Name := "";

 Specifies a name that contains substitution characters.

 Together, the names specified by the Name_Of and Target_Name parameters re-
 solve to one or more new names. This parameter is useful when you are
 preparing to enter a move or copy operation and you want to test a pair
 of source and destination names that contain wildcards and substitution
 characters.


 Objects_Only : Boolean := True;

 Specifies whether to restrict the resolution of names to objects in
 libraries or to include declarations within Ada units, too. If the value
 is True, the default, only library units or subunits are resolved.

 If False, declarations within installed or coded Ada units can also be
 resolved. Note that if the wildcards ? and ?? are used to match
 declarations within Ada units, these wildcards must be preceded by the
 grave (`) context character. (When the grave follows an Ada-unit name and
 is followed by a simple name, the simple name is looked up among the
 objects that are directly visible in the specified Ada unit.)


 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

 Assume that the current context is !Users.Anderson, which contains an Ada
 unit called Calculation and its subunit Add. The following command
 displays the fully qualified pathnames of the objects referenced by the
 name "Calculation":

   Library.Resolve (Name_Of => "Calculation");

 This command produces the output shown below:

   91/05/01 14:01:35 ::: [Library.Resolve ("calculation", "", FALSE,
   PERSEVERE);].
   !USERS.ANDERSON.CALCULATION'SPEC'V(1)
   !USERS.ANDERSON.CALCULATION'BODY'V(1)
   91/05/01 14:01:36 ::: [End of Library.Resolve command -- No errors
   detected].

 The following command shows how the naming expression Calculation?
 resolves:

   Library.Resolve (Name_Of => "Calculation?");

 This command produces the output shown below, which includes the subunit
 Add:

   91/05/01 14:01:35 ::: [Library.Resolve ("calculation", "", FALSE,
   PERSEVERE);].
   !USERS.ANDERSON.CALCULATION'SPEC'V(1)
   !USERS.ANDERSON.CALCULATION'BODY'V(1)
   !USERS.ANDERSON.CALCULATION.ADD'BODY'V(1)
   91/05/01 14:01:36 ::: [End of Library.Resolve command -- No errors
   detected].

 The following command resolves not only to Calculation and its secondary
 units but also to all declarations within them:

   Library.Resolve (Name_Of      => "Calculation`?",
                    Objects_Only => False);


 Example 2

 Assume that you know that a file called Good_Restaurants exists somewhere
 in the Environment, but you do not know where. You can use the following
 command to find the file's fully qualified pathname:

   Library.Resolve (Name_Of => "!??Good_Restaurants");


 Example 3

 Assume that you want to delete certain files in the current library and
 that you plan to do this by specifying a naming expression to the Delete
 command.

 Before you do this, you want to verify that the naming expression resolves
 only to what you want to delete. The following command displays the list
 of files to which the naming expression resolves:

 Library.Resolve (Name_Of => "@_Temp'c(file)");



 @node !Commands.Library.Set_Retention_Count

 procedure Set_Retention_Count
       (Existing      : Name    := "<IMAGE>"
        Keep_Versions : Integer := Library.Default_Keep_Versions;
        Recursive     : Boolean := True;
        Response      : String  := "<PROFILE>");

 DESCRIPTION

 Sets the retention count for the specified object(s).

 An object's retention count determines the number of deleted versions that
 can be retained before the Environment starts expunging the oldest
 versions. (Versions are deleted when new versions are created.) The
 retention count does not include the current default version of that
 object.

 By default, this procedure sets an object's retention count to be the same
 as its parent's retention count. Changing a library's retention count
 automatically changes the retention count of all the nonlibrary objects
 contained in that library.


 PARAMETERS

 Existing : Name := "<IMAGE>";

 Specifies the object whose retention count is to be set. The default is the
 current image.


 Keep_Versions : Integer := Library.Default_Keep_Versions;

 Specifies the new retention count. The default is to keep the parent's
 retention count.


 Recursive : Boolean := True;

 Specifies whether to change the retention count of contained units. The
 default is to change the retention count of the contained units.


 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

 A user named Bill wants to keep five deleted versions of each object in his
 home library. The following command sets the retention count for his home
 library to 5:

 Library.Set_Retention_Count ("!Users.Bill",5);



 @node !Commands.Library.Set_Subclass

 procedure Set_Subclass (Existing    : Name   := "<SELECTION>";
                         To_Subclass : String := "";
                         Response    : String := "<PROFILE>");

 DESCRIPTION

 Sets the subclass of the selected or named object.

 If a null string value ("") is provided for the To_Subclass parameter, the
 Environment deduces the subclass.

 Note that this procedure is typically used to convert from an older
 release of the Environment that did not support subclasses. If subclasses
 are not set on such systems, the information on the library object
 subclass is not available for objects created under the old release. For
 information on subclasses, see the Parameter-Value Conventions tabbed
 section in the Reference Summary (RS) book.


 PARAMETERS

 Existing : Name := "<SELECTION>";

 Specifies the name of the object(s) for which to set the subclass. The
 default is the current selection. The name can contain any legal directory
 name and can match multiple objects.


 To_Subclass : String := "";

 Specifies the name of the subclass to set for the object(s). The null
 string value ("") specifies that the Environment should deduce the subclass
 for the object.


 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.Library.Simple_Name

 subtype Simple_Name is String;

 DESCRIPTION

 Defines a simple name for objects.

 This subtype can use wildcards, but it cannot use attributes.



 @node !Commands.Library.Space

 procedure Space (For_Object   : Name        := "<IMAGE>";
                  Levels       : Positive    := 2;
                  Recursive    : Boolean     := True;
                  Each_Object  : Boolean     := False;
                  Each_Version : Boolean     := False;
                  Space_Types  : Boolean     := False;
                  Response     : String      := "<PROFILE>"
                  Options      : String      := "");

 DESCRIPTION

 Reports the disk space, in pages, consumed by the specified object(s).

 This procedure reports disk-utilization information for each specified
 object. Totals are also reported when appropriate. All figures are in pages
 (8,192 bits or 1,024 bytes per page).

 For worlds, space for the set of links for that world is also included.
 Nested worlds, directories, and any other objects must be explicitly
 specified to be included.

 The job report is sent to Current_Output (by default, an Environment
 output window). Errors are indicated in log messages, which, by default,
 are also sent to the output window.


 PARAMETERS

 For_Object : Name := "<IMAGE>";

 Specifies the name of the object(s) about which to display disk-space
 information. Special names, wildcards, context prefixes, and attributes are
 allowed in this name. The default is the current image.


 Levels : Positive := 2;

 Specifies the number of library levels. This parameter is used only if the
 Space_Types parameter is False.


 Recursive : Boolean := True;

 Specifies whether to include subobjects. The default is to include
 subobjects.


 Each_Object : Boolean := False;

 Specifies whether to display the space for each object of the specified set
 or the summary of the space used. The default is to display the summary.


 Each_Version : Boolean := False;

 Specifies whether to display information about each version of each object.
 The default is to display information about the default versions only.
 This parameter is used only if the Space_Types parameter is True.


 Space_Types : Boolean := False;

 Specifies whether to break down the information into the different types of
 space used. The default is not to break down the information. When
 Space_Types is False, it shows the space utilization in pages for
 For_Object. It also displays space usage for contained libraries unless
 Recursive is False. If Recursive is False, only the space for the specified
 object is displayed. Thus, if Recursive is True, the space is cumulatively
 totaled.


 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.


 Options : String := "";

 No options currently are implemented for this command. This parameter is
 reserved for future development.



 @node !Commands.Library.Terse_Format

 Terse_Format : constant Fields := Fields'(Object => True,
                                           Others => False);

 DESCRIPTION

 Defines a constant that specifies that a terse set of data be displayed by
 the List procedure.



 @node !Commands.Library.Undelete

 procedure Undelete (Existing : Name   := "<CURSOR>";
                     Response : String := "<PROFILE>");

 DESCRIPTION

 Undoes the deletion of the specified object, reinstating the object's
 default version.

 Objects can be undeleted only if they have a nonzero retention count.

 A deleted object is defined as an object that has no default version--that
 is, all of its versions, including the default, have been deleted. If the
 object's retention count is high enough, the deleted default version is
 retained, along with zero or more retained nondefault versions. Undeleting
 an object means reinstating any of the retained versions as the default
 version.

 When applied to an existing object (an object that still has a default
 version), this procedure effectively reverts that object to a previous
 version and is equivalent to the Default procedure.

 Ada units recreated by the Undelete procedure are in the archived state.


 PARAMETERS

 Existing : Name := "<CURSOR>";

 Specifies the object to be undeleted. The default is the object on which
 the cursor is located (you may need to expand the parent library display
 to see entries for deleted objects). Special names, wildcards, context
 prefixes, and attributes are allowed in this name. However, unlike some
 commands, this command does not require that you enclose the deleted
 object's name in braces.

 If a version number is not explicitly specified, the highest-numbered
 retained version is undeleted. Version numbers can be specified using the
 'V attribute, as in My_File'V(3).


 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

 A user accidentally deletes a file called My_File, which has a nonzero
 retention count. To undelete it, the user enters the command:

   Library.Undelete ("My_File");

 REFERENCES

 procedure Default
 procedure Delete



 @node !Commands.Library.Unfreeze

 procedure Unfreeze (Existing  : Name    := "<IMAGE>";
                     Recursive : Boolean := True;
                     Response  : String  := "<PROFILE>");

 DESCRIPTION

 Unfreezes the specified frozen object or objects.

 Unfreezing an object permits changes to be made to it. The procedure can
 unfreeze a single object or an entire library structure of objects.

 This procedure undoes the effect of the Freeze procedure. When objects are
 frozen, no changes can be made to them, including changing Ada-unit
 state. (However, frozen units can be executed.) Freezing objects can be
 used as part of releasing software.

 The expanded library display or the List procedure can be used to
 determine whether an object is frozen.

 The Freeze and Unfreeze procedures are subject to access-control
 restrictions. To freeze or unfreeze objects within a world, a user must
 have owner access to that world.


 PARAMETERS

 Existing : Name := "<IMAGE>";

 Specifies the object to be unfrozen. The default is the current image.
 Special names, context prefixes, wildcards, and attributes can be used to
 specify any series of objects to be unfrozen.


 Recursive : Boolean := True;

 Specifies whether to unfreeze subunits. The default is to unfreeze
 subunits. To avoid unfreezing nested worlds, use Recursive => False and
 the wildcard ?.


 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

 A user has frozen a world called Sample_World, which she now wants to un-
 freeze. To do this, she can execute the command:

   Library.Unfreeze ("Sample_World");

 REFERENCES

 procedure Freeze



 @node !Commands.Library.Verbose_Format

 Verbose_Format : constant Fields :=
                           Fields'(Object .. Update_Time => True,
                                   Size .. Retain        => True,
                                   Others                => False);

 DESCRIPTION

 Defines a constant that specifies a verbose set of data to be displayed by
 the List procedure.



 @node !Commands.Library.Verbose_List

 procedure Verbose_List
            (Pattern    : Name    := "<IMAGE>{@'V(ALL)}";
             Displaying : Fields  := Library.Verbose_Format;
             Sorted_By  : Field   := Library.Object;
             Descending : Boolean := False;
             Response   : String  := "<PROFILE>";
             Options    : String  := "") renames List;

 DESCRIPTION

 Displays the specified set of data about the specified set of versions of
 specified objects.

 This procedure is similar to the List procedure, but it has different
 default parameters. The default parameters in this procedure provide a
 detailed display of all objects in the current context, sorted by object
 name.


 PARAMETERS

 Pattern : Name := "<IMAGE>{@'V(ALL)}";

 Defines the set of objects to be listed. Special names, wildcards, context
 prefixes, and attributes can be used in this name. The default gives the
 set of objects, all versions of both deleted and undeleted objects, in the
 current image.


 Displaying : Fields := Library.Verbose_Format;

 Specifies the set of data to display about each object. The default is to
 display the verbose set.


 Sorted_By : Field := Library.Object;

 Specifies the field that should be sorted to order the list. The default is
 to order alphabetically by the object name.


 Descending : Boolean := False;

 Specifies whether to reverse the ordering. The default is to use the
 natural ascending 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.


 Options : String := "";

 No options currently are implemented. This parameter is reserved for
 future development.


 EXAMPLES

 Consider the following world:

   !Users.Gzc
     File_1
     Library
     My_Directory
     My_Unit
     My_Unit
     Sample_Directory
     Sample_World
     S_1
     S_1_Switches

 The following command produces the display shown below:

 Library.Verbose_List ("!Users.Gzc.@");

 92/01/06 18:11:40 ::: Listing of !USERS.GZC.@ sorted by object.

OBJECT         VER  CLASS  SUBCLASS  UPDTR    UPDATE_TIME    SIZE STATUS  FRZ RETAIN
============== === ======= ========= ===== ================= ==== ======  === ======
FILE_1          *2 FILE    TEXT      GZC   92/01/06 16:02:15   37 n/a       5
MY_UNIT         *1 ADA     PACK_SPEC GZC   92/01/05 14:38:43 7162 INSTALLED 5
MY_UNIT'BODY    *1 ADA     PACK_BODY GZC   92/01/05 14:38:44 7195 INSTALLED 5
SAMPLE_DIRECTRY *1 LIBRARY DIRECTORY GZC   92/01/06 14:57:47 7535 n/a       1
SAMPLE_WORLD    *1 LIBRARY WORLD     GZC   92/01/06 14:57:47 7302 n/a       1
S_1             *1 SESSION NIL             92/01/06 17:23:18    0 n/a       5
S_1_SWITCHES    *4 FILE    SWITCH    GZC   92/01/06 17:23:23  303 n/a       5
UNIT_1          *1 ADA     PACK_SPEC GZC   92/01/06 15:52:40 7162 SOURCE    5
UNIT_1'BODY     *1 ADA     PACK_BODY GZC   92/01/06 15:52:40 7195 SOURCE    5

   92/01/06 18:11:43 ::: [End of Library.List command -- No errors
   detected].

 REFERENCES

 procedure Ada_List
 procedure File_List
 procedure List



 @node !Commands.Library.Volume

 subtype Volume is Natural range 0 .. 31;

 DESCRIPTION

 Defines the subtype used to represent disk volumes.

 This subtype is used to specify the disk units on which libraries are
 built. Whenever an object is created, it is assigned to a disk volume. A
 world can be assigned to a specific volume; an object other than a world is
 automatically assigned to the same volume as the world enclosing it.

 This subtype defines the possible disk volumes. Typical systems contain
 either two or four disk volumes, numbered consecutively from 1. Volume 0
 is not an actual disk; it is used as a convention to indicate that the
 system should select the volume on which to allocate the control point.



 @node !Commands.Links

 Package Links provides commands for creating, editing, deleting, and
 viewing links. Links are the Environment's mechanism for resolving Ada
 simple names that are referenced in with clauses. Using links, you can
 permit visibility between units in different libraries.

 The commands in package Links are appropriate for both interactive and
 programmatic use.


 RESOURCES IN PACKAGE LINKS

 The commands in package Links fall into several functional groups. Types
 and constants are not in this list.

 Viewing links:                     Display, Edit, Visit

 Creating links:                    Add, Copy, Insert

 Changing links:                    Replace, Update

 Deleting links:                    Delete, Expunge

 Listing the units that use a link: Dependents


 KEY CONCEPTS FOR PACKAGE LINKS

 As defined by the Reference Manual for the Ada Programming Language (Ada
 LRM), you can permit Ada units to use types, procedures, or functions
 defined in other units by naming those units in with clauses. When you name
 a unit in a with clause, you use the simple name (for example, Factorial).
 This resolves when the unit you with is in the current library.

 The Rational Environment also permits you to make use of units in other
 libraries. In this case, the simple name cannot be resolved without extra
 information. Links provide this extra information. They are the mechanism
 by which the Environment resolves (determines the fully qualified pathname
 for) Ada simple names in with clauses.

 A set of links (possibly empty) is associated with each world in the
 Environment. The set of links for a world can be used by any units in that
 world to gain visibility to particular units in other libraries.
 Directories do not have links associated with them; units in a directory
 use the set of links associated with the nearest enclosing world (see
 Chapter 1, "Managing Libraries," for more information about directories
 and worlds).

 The following subsection provides an introductory example using links. The
 remaining subsections explain key concepts underlying the links mechanism.


 An Example Using Links

 Assume you are developing a program to compute and display the sums of
 various types of numbers. In your Utilities directory, your procedure,
 Display_Sums, withs other procedures that calculate and display the sums
 of particular types of numbers. You want to use Reyes's procedure
 Display_Complex_Sums to compute and display the sums of complex numbers.
 The library structure is shown in Figure 1.

   ---------------------------------------------------------------
   |                       USERS (world)                         |
   |                                                             |
   | ----------------------------- ----------------------------- |
   | | YOUR_USERNAME (world)     | |       REYES (world)       | |
   | |                           | |                           | |
   | | ------------------------- | |                           | |
   | | | UTILITIES (directory) | | |                           | |
   | | |                       | | |                           | |
   | | | ----------------      | | | ------------------------  | |
   | | | | Display_Sums |----------->| Display_Complex_Sums |  | |
   | | | | (with D_C_S) |--    | | | |                      |--| |
   | | | ---------------- |    | | | ------------------------ || |
   | | |   |              |    | | |   |                      || |
   | | |   ----------------    | | |   ------------------------| |
   | | |                       | | |                           | |
   | | ------------------------- | |                           | |
   | |                           | |                           | |
   | ----------------------------- ----------------------------- |
   |                                                             |
   ---------------------------------------------------------------
   Figure 1   Library Structure of Display_Sums Program


 Before Display_Sums can successfully with Display_Complex_Sums, a link to
 Display_Complex_Sums must be added to the set of links for the world
 enclosing Display_Sums (namely, !Users.Your_Username) (see "Creating
 Links," page nn). The following link maps the simple name
 Display_Complex_Sums to its fully qualified pathname
 !Users.Reyes.Display_Complex_Sums:

   EXT: DISPLAY_COMPLEX_SUMS => !USERS.REYES.DISPLAY_COMPLEX_SUMS

 You also need to make sure that your procedure references the link that
 points to Display_Complex_Sums.

   with Display_Complex_Sums;
   procedure Display_Sums is
   ...
   end Display_Sums;

 When you promote Display_Sums to the installed state, the Environment
 performs several steps, stopping when it is able to resolve the simple
 name Display_Complex_Sums:

 1. The Environment looks for a unit called Display_Complex_Sums in the
    current library, !Users.Your_Username.Utilities. No unit with that name
    is found there.

 2. The Environment checks the set of links associated with the current
    world, !Users.Your_Username.

    Finding a link to Display_Complex_Sums, the Environment successfully
    installs Display_Sums.

 If no link existed, an error message would be displayed and the
 installation would fail. No other directories, worlds, or sets of links
 would be searched.


 Link Components

 A link is a pairing of a simple name and a fully qualified pathname--for
 example, TEXT_IO => !IO.TEXT_IO. Accordingly, each link has two
 components: a link name (for example, Text_Io) and a source name
 (!Io.Text_Io).

 The link name is a simple Ada identifier that can appear in with clauses.
 By default, the link name is the rightmost name component of the source
 name. In other words, the link name is usually the simple name of the Ada
 unit to which the link points. However, the link name can be any legal Ada
 simple name. In this way, links can be used to rename units imported into
 the library. This feature can be useful for differentiating between units
 of the same simple name contained in different libraries. Link names must
 be unique within a set of links.

 The source name is the fully qualified pathname of the Ada unit to which
 the link points. The fully qualified pathname traces the path from the
 Environment`s root world (!) to the named object. Source names do not need
 to be unique within a set of links; any number of links can point to a
 single source unit, provided different link names are used.

 When an Ada unit uses a link name in a with clause, the unit that is
 actually withed is the unit of the corresponding source name. For example,
 if a set of links for a world contains the link TEXT_IO => !IO.TEXT_IO,
 then units in that world (or in directories in that world) are able to
 reference package !Io.Text_Io by simply including the clause with Text_Io.
 When the Environment encounters this with clause, it is able to resolve
 the simple name Text_Io by using the link of that name.


 Kinds of Links

 There are two kinds of links: internal links and external links. For most
 purposes, you need to manage only external links, because the Environment
 automatically creates and manages internal links.

 The difference between internal and external links depends on where the
 source unit is located in the library hierarchy. To understand the kinds
 of links, it is important to understand the library hierarchy (see
 Chapter 1, "Managing Libraries").

 Links are a property of worlds; every world in the Environment library
 structure has a set of links (possibly empty) associated with it.
 Directories use the links of the nearest enclosing world. Accordingly,
 links to units in libraries (directories or worlds) outside a world are
 called external links, and links to units in different directories within
 a world are called internal links.

 For example, assume the libraries shown in Figure 2.

   ---------------------- -------------------------------------
   |  !Users.Robinson   | |           !Users.Reyes            |
   |                    | |                                   |
   |                    | |                                   |
   | Display_Utilities  | |  Display_Complex_Sums             |
   |                    | |                                   |
   ---------------------- | ----------- --------------------- |
                          | | World_A | |    Directory_B    | |
                          | |         | |                   | |
                          | | Complex | | Complex_Utilities | |
                          | |         | | List_Generic      | |
                          | ----------- --------------------- |
                          -------------------------------------
   Figure 2   Library Structure Containing Three Worlds and One Directory


 This diagram includes three worlds (Robinson, Reyes, and World_A) and one
 directory (Directory_B). Each library contains at least one Ada unit. In
 the set of links associated with the world Reyes, links exist to all the
 units referenced by Display_Complex_Sums (Display_Utilities, Complex,
 Complex_Utilities, and List_Generic). The type of link for each is
 determined by the location of these units:

 *  The link that references Display_Utilities is an external link because
    Display_Utilities is outside world Reyes.

 *  The link to Complex is also an external link because Complex belongs to
    its nearest enclosing world, World_A.

 *  The links to Complex_Utilities and List_Generic are internal links
    because their nearest enclosing world is Reyes. (Remember that, for
    compilation purposes, directories only divide worlds; they do not have
    links.)

 The only units in this diagram that could reference each other without
 links are Complex_Utilities and List_Generic, because they exist in the
 same library.

 External links (denoted by EXT) must be explicitly created using commands
 from this package. Thus, in the example above, Reyes must explicitly
 create links in his home world in order to reference Display_Utilities and
 Complex. For convenience, the default set of links for any world contains
 external links to all standard Environment resources.

 Internal links (denoted by INT), by default, are created by the
 Environment when a unit specification is promoted to the installed state
 for the first time. Thus, in the example above, the Environment would
 automatically create links in world Reyes that would allow
 Display_Complex_Sums, Complex_Utilities, and List_Generic to reference
 each other. Creation of internal links can be suppressed by setting the
 Directory.Create_Internal_Links switch to False (see package Switches).


 Predefined Sets of Links

 The Environment provides predefined sets of external links. They are
 associated with worlds called model worlds and can be requested when
 creating new worlds. The Model parameter in the Library.Create_World
 command allows you to copy the specified model world's links into the new
 world. Once links are copied, you can add, delete, or change the links for
 either the model world or the new world without affecting the other world.

 Prepackaged model worlds are located in !Model. !Model.R1000 contains
 links for standard Environment facilities and commands.
 !Model.R1000_Portable contains

 links only for Ada resources defined by the Ada LRM. You also can create
 model worlds containing links tailored to special needs.

 For more information on model worlds, see package Library in this book.


 Links and Subsystems

 The operations in package Links are appropriate only for establishing
 visibility in worlds and directories. When a project is developed in
 subsystems using the Environment's configuration management and version
 control (CMVC) facilities, visibility between views in subsystems must
 be controlled using CMVC import and export operations. For details, see
 the Key Concepts of the Project Management (PM) book.


 USING COMMANDS FROM PACKAGE LINKS

 Using commands from this package, you can view, create, change, or remove
 links. The following subsections discuss these operations and the commands
 available for each.


 Viewing Links

 Package Links provides three commands for viewing links:

 *  Edit

 *  Visit

 *  Display

 Normally, you can use the Edit procedure. The Edit procedure displays the
 set of links for the specified world in a window from which they can be
 edited (see "Editing Links," page nn). Each set of links is displayed in a
 new window unless the specified set of links is already visible in a
 window. In that case, the window is reused and the cursor is moved to that
 window.

 The Visit procedure is similar to the Edit procedure except that it always
 reuses an existing window that contains a set of links, if one exists.
 Thus, instead of creating a new window each time a set of links is viewed,
 the procedure replaces the set of links currently being viewed with the
 new set. If a window containing links does not exist, a new window is
 created. The Visit procedure is useful for window management but should
 not be used when you are comparing two sets of links or copying links
 between sets.

 If you want to view a subset of links, such as all those that reference a
 particular source unit, you can use the Display procedure. The Display
 procedure generates a list of the links from the specified world that match
 the specified link name, source name, and kind. Only those links that match
 all three parameters are displayed. Because the display is a textual
 representation of the links, links are not opened for editing by this
 procedure. To open links for editing, use the Edit or Visit procedure.


 Creating Links

 Package Links provides two commands for creating links:

 *  Insert

 *  Add

 The Insert and Add procedures are similar in that they allow you to create
 one or more new links by specifying the names of the source unit or units.
 Both procedures accept wildcard characters and other naming conventions.
 Additionally, both procedures automatically determine whether the new link
 is an internal or external link.

 The easiest way to create a new link is to use the Insert procedure. First
 use the Edit or Visit procedure to bring up a window containing the set of
 links in which you want to create a new link. Then call the Insert
 procedure by entering the key combination for Common.Object.Insert. This
 command opens a command window containing a prompt for the fully qualified
 pathname of the unit to which the new link is to point. The Insert
 procedure assumes that the link name is to be the simple name of the
 unit to which the link points. If a link of that name already exists, the
 existing link is overwritten, provided it does not have dependents.

 The Add procedure is more powerful in that it allows you to specify a link
 name that differs from the simple name of the source unit. Specifying a
 link name that differs from the simple name of the unit allows you to
 create local aliases for units in other libraries. You can also specify
 the world in which to add the link. Thus, you can use the Add procedure
 from any window. The Add procedure is also somewhat safer because it
 generates an error if a link of the specified link name already exists; it
 does not overwrite existing links.


 Copying Links

 You can copy links from the set of links for one world to the set of links
 for another world using the Copy procedure. You can specify any subset
 of links to be copied based on link names, source names, or kind. For
 example, you can specify all the links whose link name begins with Text
 that reference units in !Io (such as the link for !Io.Text_Io).

 The link name and source name are copied exactly as they appear in the
 source set of links. As with the Insert procedure, if an existing link
 with the specified name already exists, that link is overwritten unless it
 has dependents. In that case, the Copy procedure fails and that link is
 not copied. If multiple links are being copied, only that link creation
 fails. As usual, the Environment automatically determines whether the
 new link is an internal or external link.


 Editing Links

 There are two situations in which you may want to edit existing links:

 *  You may want to change the source unit that is pointed to by a
    particular link name. This is especially useful when you want a unit to
    reference a new implementation of a package or subprogram contained
    outside the current library.

 *  You may want to change the name of a link. For example, you may want to
    use an existing link name for a new link.

 These two cases are discussed in detail below.


 Changing a Source Name

 Package Links provides two commands for changing the source name for an
 existing link:

 *  Update

 *  Replace

 The Update and Replace procedures are similar in several ways.
 Specifically, both procedures:

 *  Allow you to provide a new source name for an existing link.

 *  Automatically overwrite any existing link of the given link name,
    provided that link has no dependents. If the existing link is used by a
    unit in that library, both procedures generate an error and fail to
    edit the link.

 *  Allow you to use a current link name for a unit whose simple name is
    not the same as the name of the link.

 *  Automatically determine whether the new link is an internal or external
    link.

 The easiest way to change the source name for an existing link is to use
 the Update procedure from a window containing the link to be edited. The
 Update procedure can be entered directly in a command window or called
 by entering the key combination for Common.Edit. The Update procedure
 operates on the link on which the cursor is located. The current link name
 is maintained even if it does not match the simple name of the new source
 unit. Thus, the existing link is always overwritten.

 The Replace procedure is more powerful in that it allows you to specify a
 link name that may not currently exist, and it can be used from any
 window. Rather than using cursor position to determine the link to edit,
 you are required by the Replace procedure to specify a link name (or have
 one automatically built from the source name). The procedure then searches
 the specified set of links for a link of that link name. If a link of that
 name exists, it is changed to point to the new source. If a link does not
 exist, one is created.


 Changing a Link Name

 None of the commands in package Links directly change the link name for a
 particular link, because links usually have dependents that would be
 made obsolete if the link name were changed. Normally, you simply create
 additional links, using new link names, that reference the source unit.
 This ensures that any dependents that used the old link name will not
 become obsolete.

 However, if you want to change a link name (for example, so that you can
 reuse that link name), you need to perform several steps:

 1. Create a new link to the old source unit, using the Add or Insert
    procedure. You should now have two links referencing this source unit.

 2. Check to make sure that the old link has no dependents, using the
    Dependents or Common.Explain procedure. If the link does have
    dependents, demote the

    dependent units to the source state or incrementally withdraw the with
    clause referencing the link.

 3. Delete the old link (see "Removing Links," below).

 4. Edit any units that depended on the old link so that they now reference
    the new link, repromoting them if necessary.


 Removing Links

 There are two situations in which you might be removing unused links:

 *  You may want to remove links to units that have been deleted.

 *  You may want to remove links to units that exist but are no longer
    needed.

 To match these two situations, package Links provides two commands for
 removing links:

 *  Expunge

 *  Delete

 When a unit is deleted, the links that reference it remain in existence
 until a new image of the links is created. To remove links that reference
 nonexistent units without creating a new link image, use the Expunge
 procedure. This procedure essentially just refreshes the link image.

 Sometimes a unit may still exist, but you may not want to reference it.
 Although you do not need to delete the link, you may want to so that you
 can use that link name to reference a different unit. To remove a link,
 use the Delete procedure. Note that if the link is currently being used by
 any units, you cannot delete it without first editing those units. To see
 if a unit is currently being used, use the Dependents or Common.Explain
 procedure.

 Changes to links take effect immediately. Thus, there is no way to restore
 deleted or expunged links.


 Links and Access Control

 For the purpose of access control, links belong to a world. Thus, to
 perform operations on the links for a world, you must have the
 appropriate access right to that world. Additionally, some operations on
 links are subject to the access-control restrictions on the source units
 pointed to by those links. Specifically:

 *  To view the links for a world, you must have read access to that world.

 *  To create a link in the set of the links for a world, you must have
    owner access to that world and read access to the source unit pointed
    to by the link.

 *  To copy a link, you must have owner access to the target world, read
    access to the source world, and read access to each source unit pointed
    to by a copied link.

 *  To delete a link from the set of links for a world, you must have owner
    access to that world.

 For further information about access control, see package Access_Control
 in this book.


 COMMANDS FROM PACKAGE COMMON FOR EDITING LINKS

 When executed from an editable window containing a set of links, many com-
 mands from package !Commands.Common are supported for editing links.
 Commands from package Common typically are used through the key combina-
 tions to which they are bound. Commands from package Common that are sup-
 ported for editing links are summarized in Table 1. For further
 information about these commands, see Editing Specific Types (EST), package
 Common.

        Table 1   Commands from Package Common for Editing Links
     --------------------------------------------------------------- 
    |               |                                               |
    |Key Bound To   |Accomplishes ...                               |
    |...            |                                               |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Abandon |Ends the editing of the current set of links.  |
    |               |The window is removed from the screen and from |
    |               |the window directory. The Window parameter     |
    |               |allows you to specify which window should be   |
    |               |removed. The default is the current image.     |
    |               |Because all operations on links implicitly     |
    |               |commit any changes, this procedure does not    |
    |               |abandon changes.                               |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Commit  |Has no effect. All operations on links         |
    |               |implicitly commit any changes.                 |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Create_ |Creates a command window below the current     |
    |Command        |window, if one does not exist; otherwise, the  |
    |               |procedure puts the cursor in the existing      |
    |               |command window. When attached to a window      |
    |               |containing links, the command window initially |
    |               |has a use clause that includes package Links.  |
    |               |Thus, commands from package Links can be       |
    |               |entered in the command window by using their   |
    |               |simple names.                                  |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.        |Finds the defining occurrence of the unit      |
    |Definition     |referenced by the designated link and visits or|
    |               |creates a window containing the specification o|
    |               |that unit. If a pathname is provided, that     |
    |               |object is displayed. If no name is provided,   |
    |               |the unit referenced by the selected link is    |
    |               |displayed. Otherwise, the cursor location is   |
    |               |used to designate the link. An In_Place        |
    |               |parameter specifies whether the current window |
    |               |should be used (the default is False). The     |
    |               |Visible parameter has no effect when a link is |
    |               |designated.                                    |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Edit    |Creates a command window and places in it the  |
    |               |command:                                       |
    |               |                                               |
    |               |     Update ("selected or current link");      |
    |               |                                               |
    |               |                                               |
    |               |where selected or current link is the source   |
    |               |name of the link on which the cursor is        |
    |               |currently located, whether or not there is a   |
    |               |selection. Providing a new source name and     |
    |               |promoting the command changes the source for   |
    |               |that link. The INT or EXT prefix is            |
    |               |automatically changed to match the location of |
    |               |the new source in relationship to the current  |
    |               |world.                                         |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Elide   |Reduces (elides) the number of links displayed |
    |               |in the window. There are three levels:         |
    |               |*  All links (the default)                     |
    |               |*  External links                              |
    |               |*  Internal links                              |
    |               |This command cycles through the levels,        |
    |               |proceeding down the list and cycling back to   |
    |               |the top when at the bottom.                    |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.        |Finds the parent world for the set of links    |
    |Enclosing      |that are in the current window and creates or  |
    |               |visits a window containing that world. An      |
    |               |In_Place parameter specifies whether the curren|
    |               |window should be used (the default is False).  |
    |               |The Library parameter has no effect, because   |
    |               |the parent of a set of links is always a       |
    |               |library.                                       |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Expand  |Increases (expands) the number of links        |
    |               |displayed in the window. There are three       |
    |               |levels:                                        |
    |               |*  All links (the default)                     |
    |               |*  Internal links                              |
    |               |*  External links                              |
    |               |If the display contains either of the two lower|
    |               |levels of detail, this command displays all    |
    |               |links. Attempts to expand beyond all links have|
    |               |no effect.                                     |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Explain |Inserts, below the current link, a list of     |
    |               |units that use the designated link. Note that  |
    |               |this command lists units that use the          |
    |               |designated link, not those that use the source |
    |               |unit. If an explanation already exists, this   |
    |               |procedure removes that explanation.            |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Release |Ends the editing of the current set of links.  |
    |               |The window is removed from the screen and from |
    |               |the window directory.                          |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Revert  |Refreshes the image of the set of links in the |
    |               |current window. If the set of links has been   |
    |               |changed by another user or program, the new    |
    |               |image reflects those changes. Refreshing the   |
    |               |links image is generally not necessary, because|
    |               |the set of links is refreshed each time you    |
    |               |add, edit, or delete a link.                   |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Sort_   |Sorts the set of links displayed in the window.|
    |Image          |There are four displays:                       |
    |               |*  Alphabetic by link name (the default)       |
    |               |*  Alphabetic by source name                   |
    |               |*  Alphabetic internal link names followed by  |
    |               |   alphabetic external link names              |
    |               |*  Alphabetic internal source names followed by|
    |               |   alphabetic external source names            |
    |               |This command cycles through the levels,        |
    |               |proceeding down the list and cycling back to   |
    |               |the top when at the bottom.                    |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the link on which the cursor is        |
    |Child          |located. If that link is already selected, the |
    |               |pro- cedure has no effect. If all links are    |
    |               |already selected, the procedure selects only   |
    |               |the link on which the cursor is located.       |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Copies the selected link into the set of links |
    |Copy           |on which the cursor is located. If a link of   |
    |               |the same link name already exists in the set of|
    |               |links on which the cursor is located, that link|
    |               |is replaced. If the selected link and the      |
    |               |cursor are both in the same set of links, the  |
    |               |procedure has no effect.                       |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Deletes the selected link, provided it has no  |
    |Delete         |dependents.                                    |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the first line (the header) in the set |
    |First_Child    |of links.                                      |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Creates a command window and places in it the  |
    |Insert         |command:                                       |
    |               |                                               |
    |               |     Insert ("[link=>] source; etc.");         |
    |               |                                               |
    |               |                                               |
    |               |where the pathname for a unit must be specified|
    |               |Specifying a pathname and promoting the        |
    |               |command inserts a new link with the same simple|
    |               |name as the source unit. If a link already     |
    |               |exists with this simple name, it is replaced.  |
    |               |Multiple links can be inserted by separating   |
    |               |them with semicolons.                          |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the last link of the set.              |
    |Last_Child     |                                               |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the next link. If no link is selected, |
    |Next           |this procedure selects the link on which the   |
    |               |cursor is located. If all links are selected,  |
    |               |this procedure produces an error.              |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the link on which the cursor is        |
    |Parent         |located. If that link is selected, this        |
    |               |procedure selects all links in the set. If all |
    |               |the links are already selected, this procedure |
    |               |has no effect.                                 |
     --------------------------------------------------------------- 
    |               |                                               |
    |Common.Object. |Selects the previous link. If no link is       |
    |Previous       |selected, this procedure selects the link on   |
    |               |which the cursor is located. If all links are  |
    |               |selected, this procedure produces an error.    |
     --------------------------------------------------------------- 




 @node !Commands.Links.Add

 procedure Add (Source   : Source_Name := ">>SOURCE NAMES<<";
                Link     : Link_Name   := "#";
                World    : World_Name  := "<IMAGE>";
                Response : String      := "<PROFILE>");

 DESCRIPTION

 Adds one or more links to the set of links for the specified world.

 This procedure creates a link with the specified link and source names in
 the set of links for the specified world. Naming expressions can be used to
 specify multiple source names and to allow building of link names from
 source names.

 Note that link names within a set of links must be unique. Thus, if a link
 of the specified link name already exists, the source name for the new link
 must reference the same unit or the procedure will fail. In contrast,
 several links can share the same source name, provided they use different
 link names.

 The Environment automatically determines whether the links being added are
 internal or external links.

 This procedure is similar to the Insert procedure. However, you should use
 the Insert procedure if:

 *  You are already in a window containing the set of links in which you
    want to create a link, and

 *  You want to use the simple name of the unit as the link name, and

 *  You want to automatically overwrite any existing link of the given link
    name.


 PARAMETERS

 Source : Source_Name := ">>SOURCE NAMES<<";

 Specifies the fully qualified pathname of the source unit. Multiple units
 can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. The default parameter placeholder ">>SOURCE
 NAMES<<" must be replaced or an error will result.


 Link : Link_Name := "#";

 Specifies the name of the link. Substitution characters can be used to
 allow building of link names from source names (see subtype Link_Name).
 The default is the simple name of the source unit.


 World : World_Name := "<IMAGE>";

 Specifies the world in which to add the link. Special names, wildcards, and
 context characters can be used when they resolve to a unique world. The
 default is the current selection, if one exists, or the object in whose
 image the cursor is located. If the current image is not a world, the
 Environment uses the current world (the world enclosing the current
 context).


 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 link, you must have read access to the unit named in the Source
 parameter and owner access to the world for which the link is to be
 added.


 ERRORS

 If a link of the specified link name already exists, the link addition
 fails. Existing links are not overwritten.

 If a set of links is being added and any one fails because of name
 conflicts with existing units, only that link addition fails.


 EXAMPLES

 Suppose you want to add links for each of the packages in !Commands to the
 set of links for your home world. The following command will add the
 links, using the simple name of each source unit as its link name:

   Links.Add (Source   => "!Commands.@",
              Link     => "#",
              World    => "!Users.Your_Username",
              Response => "<PROFILE>");

 The Environment automatically determines that, in this case, the links
 being added are external links.

 Note that, by default, links to Environment packages are already included
 in the set of links for each world. Thus, you generally do not need to
 explicitly create links to commands in package Common.


 REFERENCES

 procedure Insert
 procedure Replace
 procedure Update



 @node !Commands.Links.Any

 Any : constant Link_Kind := Links_Implementation.Any;

 DESCRIPTION

 Defines a constant of type Link_Kind specifying both internal and external
 links.

 This constant is used as the default value for the Kind parameter in the
 Copy, Delete, Dependents, and Display commands.


 REFERENCES

 constant External
 constant Internal
 subtype Link_Kind



 @node !Commands.Links.Copy

 procedure Copy
             (Source_World : World_Name     := ">>WORLD NAME<<";
              Target_World : World_Name     := "<IMAGE>";
              Link         : Link_Name      := "@";
              Source       : Source_Pattern := "?";
              Kind         : Link_Kind      := Links.Any;
              Response     : String         := "<PROFILE>");

 DESCRIPTION

 Copies one or more links from one world to another world.

 This procedure adds links to the set of links for a target world by
 copying them from the set of links for a source world. By default, all
 links from the source world are copied. Any subset of those links can be
 specified by link name, source name, or kind. The links to be copied must
 match all of the parameters specified. Typically, either the set of link
 names or the set of source names is restricted to some subset of the links
 in the set.

 The newly created links have the same link and source name as the links
 from which they were copied. Note that if a link of the specified link name
 already exists in the target world, that link is replaced by the copied
 link. In contrast, any number of links may have the same source name,
 provided they have different link names.

 The Environment automatically determines whether the newly created links
 are internal or external, based on their new location.


 PARAMETERS

 Source_World : World_Name := ">>WORLD NAME<<";

 Specifies the world from which the links are to be copied. Special names,
 wildcards, and context characters can be used when they resolve to a
 unique world. The default parameter placeholder ">>WORLD NAME<<" must be
 replaced or an error will result.


 Target_World : World_Name := "<IMAGE>";

 Specifies the world into which the links are to be copied. Special names,
 wildcards, and context characters can be used when they resolve to a
 unique world. The default is the current selection, if one exists, or the
 object in whose image the cursor is located. If the current image is not a
 world, the Environment uses the current world (the world enclosing the
 current context).


 Link : Link_Name := "@";

 Specifies the names of the links that are to be copied. A restricted subset
 of naming expressions are allowed (see subtype Link_Name). The default is
 all link names.


 Source : Source_Pattern := "?";

 Specifies the fully qualified pathnames of the links to be copied. A
 restricted subset of naming expressions are allowed (see subtype
 Source_Pattern). The default is all source names.


 Kind : Link_Kind := Links.Any;

 Specifies the kinds of links to be copied. The default is both internal and
 external links.


 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

 Link names must be unique within a set of links. Thus, if a link of the
 specified link name already exists in the target world, that link is
 overwritten by the new link, provided the link does not have dependents.

 To copy links, you must have owner access to the target world, read access
 to the source world, and read access to each source unit pointed to by a
 copied link.


 EXAMPLES

 Suppose that you and a user named Bob reference many of the same commands
 in package !Tools. Rather than create new links, you decide to copy all
 the links in Bob's home world that reference packages in !Tools, using the
 following command:

   Links.Copy (Source_World => "!Users.Bob",
               Target_World => "!Users.Your_Username",
               Link         => "@",
               Source       => "!Tools?");

 The links are created in the set of links for your home world. They have
 the same link and source names as the original links in Bob's home world.


 REFERENCES

 subtype Link_Name
 subtype Source_Pattern



 @node !Commands.Links.Delete

 procedure Delete (Link     : Link_Name      := ">>LINK NAMES<<";
                   Source   : Source_Pattern := "?";
                   Kind     : Link_Kind      := Links.Any;
                   World    : World_Name     := "<IMAGE>";
                   Response : String         := "<PROFILE>");

 DESCRIPTION

 Deletes one or more links from a specified world.

 This procedure deletes the specified links from the set of links for the
 designated world. Any subset of the links can be specified by link name,
 source name, or kind. The links to be deleted must match all the
 parameters specified. Typically, either the set of link names or the set of
 source names is restricted to some subset of the links in the set.

 Note that deleted links are unrecoverable. To reinstate a deleted link,
 you must create a new link to the desired unit, using the Add or Insert
 procedure.


 PARAMETERS

 Link : Link_Name := ">>LINK NAMES<<";

 Specifies the names of the links to be deleted. A restricted subset of
 naming expressions are allowed (see subtype Link_Name). The default
 parameter placeholder ">>LINK NAMES<<" must be replaced or an error will
 result.


 Source : Source_Pattern := "?";

 Specifies the fully qualified pathnames of the links to be deleted. A
 restricted set of naming expressions are allowed (see subtype
 Source_Pattern). The default is any source name.


 Kind : Link_Kind := Links.Any;

 Specifies the kinds of links to be deleted. The default is both internal
 and external links.


 World : World_Name := "<IMAGE>";

 Specifies the world from which the links are to be deleted. Special names,
 wildcards, and context characters are allowed when they resolve to a
 unique world. The default is the current selection, if one exists, or the
 object in whose image the cursor is located. If the current image is not a
 world, the Environment uses the current world (the world enclosing the
 current context).


 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

 You cannot delete a link that is currently being used. To delete a link
 that is being used, you must first remove the dependency by one of three
 methods:

 *  Edit the dependent unit so that it no longer references the link

 *  Demote the dependent unit to the source state

 *  Delete the dependent unit

 To check for the units that are currently using a particular link, you can
 use the Common.Explain or the Dependents procedure.

 To delete a link, you must have owner access to the world from which the
 link is to be deleted.


 EXAMPLES

 Suppose you have links in the set of links for your home world to units
 you are testing in !Tools.Test_Cases, but that you no longer want to be
 able to reference these units. To delete all the links in your home world
 that reference units in !Tools.Test_Cases, you can use the command:

   Links.Delete (Link     => "@",
                 Source   => "!Tools.Test_Cases?",
                 Kind     => Links.Any,
                 World    => "!Users.Your_Username",
                 Response => "<PROFILE>");

 REFERENCES

 procedure Dependents
 subtype Link_Name
 subtype Source_Pattern



 @node !Commands.Links.Dependents

 procedure Dependents (Link     : Link_Name := "@";
                       Source   : Source_Pattern := "?";
                       Kind     : Link_Kind := Links.Any;
                       World    : World_Name := "$$";
                       Response : String := "<PROFILE>");

 DESCRIPTION

 Displays a list of the Ada units that depend on a specified link.

 This procedure displays a list of the units that use any one of the
 specified links. By default, all the links in the set are checked for
 dependencies. Any subset of those links can be specified by link name,
 source name, or kind. The links to be checked must match all of the
 parameters specified. Typically, either the set of link names or the set of
 source names is restricted to some subset.

 Note that this procedure checks for units that depend on the specified
 link(s). A link's dependents include any units that contain a with
 referencing the link name. When the link name is the same as the simple
 name of the unit, dependents do not include units in the same library as
 the unit to which the link points. Names of units in the same library as
 the unit that withs them are resolved without using links.

 Note also that this procedure recognizes only dependent units that are in
 the installed or coded state. Dependent units in the source state are
 not reported.

 The display is placed in Current_Output (by default, an Environment output
 window). Errors are reported in log messages, which, by default, are
 also sent to the output window.


 PARAMETERS

 Link : Link_Name := "@";

 Specifies the names of the link(s) to be checked for dependencies. A
 restricted subset of naming expressions are allowed (see subtype
 Link_Name). The default is all link names.


 Source : Source_Pattern := "?";

 Specifies the fully qualified pathnames of the links to be checked for
 dependencies. A restricted subset of naming expressions are allowed (see
 subtype Source_Pattern). The default is all source names.


 Kind : Link_Kind := Links.Any;

 Specifies the kinds of links to be checked for dependencies. The default is
 both internal and external links.


 World : World_Name := "$$";

 Specifies the world whose links are to be checked for dependencies. Special
 names, wildcards, and context characters are allowed when they resolve to
 a unique world. The default is the current world (the world enclosing the
 current context).


 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

 All dependents must be in the installed or coded state. This procedure
 does not recognize dependents in the source state.


 EXAMPLES

 The examples below refer to a procedure for displaying sums of complex
 numbers. The program's main procedure, Display_Complex_Sums, uses
 resources from three packages: Complex, Complex_Utilities, and
 List_Generic. Complex_Utilities has a subunit called Image. The structure
 of this program is depicted in Figure 3, in which arrows are used to
 represent the dependencies introduced by with clauses.

                   ------------------------
                   | Display_Complex_Sums |
                   |        (proc)        |--
                   ------------------------ |
                     ------------------------
                         /          \
                        /            \
                       v              v
       -----------------           ---------------------
       | Complex (pkg) |<----------| Complex_Utilities |
       |               |--         |      (pkg)        |--
       ----------------- |        /--------------------- |
         -----------------       /   ---------------------
                                /                |
                               v             -------------
                      ----------------       |   Image   |
                      | List_Generic |       | (subunit) |
                      |  (gen pkg)   |--     -------------
                      ---------------- |
                        ----------------
   Figure 3   Dependencies in the Display_Complex_Sums Program


 The units in Figure 3 are contained in three different libraries,
 !Users.Anderson, World_A, and Directory_B, as displayed in Figure 4.

     -------------------------------------------------------
     |      !USERS.ANDERSON.COMPLEX_UTILITIES (world)      |
     |                                                     |
     |   ------------------------                          |
     |   | Display_Complex_Sums |                          |
     |   ------------------------                          |
     |                                                     |
     |   ---------------       -------------------------   |
     |   |   WORLD_A   |       |      DIRECTORY_B      |   |
     |   |             |       |                       |   |
     |   | ----------- |       | --------------------- |   |
     |   | | Complex | |       | | Complex_Utilities | |   |
     |   | ----------- |       | --------------------- |   |
     |   |             |       | ---------             |   |
     |   |             |       | | Image |             |   |
     |   ---------------       | ---------             |   |
     |                         | ----------------      |   |
     |                         | | List_Generic |      |   |
     |                         | ----------------      |   |
     |                         -------------------------   |
     -------------------------------------------------------
   Figure 4   The World !Users.Anderson.Complex_Utilities



 Example 1

 The following command produces the list of units that depend on the link
 Complex_Utilities:

   Links.Dependents ("Complex_Utilities");

 Only the body of Display_Complex_Sums names Complex_Utilities in a with
 clause, so the following output is displayed:

   92/01/02 22:44:05 --- List of dependents.

   !USERS.ANDERSON.COMPLEX_NUMBERS.DISPLAY_COMPLEX_SUMS'BODY'V(1)


 Example 2

 Wildcards can be used to specify multiple link names. For example, the
 following command produces a list of the units that depend on either the
 Complex or Complex_Utilities link:

   Links.Dependents ("Complex@");

 Because both Display_Complex_Sums and Complex_Utilities use a link to a
 unit that begins with the prefix Complex (Complex_Utilities withs Complex,
 and Display_Complex_Sums withs both Complex_Utilities and Complex), both
 of these units are listed in the output:

   92/01/02 22:38:28 --- List of dependents.

   !USERS.ANDERSON.COMPLEX_NUMBERS.DIRECTORY_B.COMPLEX_UTILITIES'SPEC'V(3)
   !USERS.ANDERSON.COMPLEX_NUMBERS.DISPLAY_COMPLEX_SUMS'BODY'V(1)


 Example 3

 Note that the Dependents procedure lists units that depend on the link,
 not the unit, of the given name. Assume the following command was entered:

   Links.Dependents ("List_Generic");

 Because List_Generic and the unit that withs it (Complex_Utilities) are in
 the same library, the link is not referenced. Thus, the output from the
 command shows that no units depend on the link to List_Generic:

   92/01/02 22:41:40 --- There are no dependents.

 REFERENCES

 subtype Link_Name
 subtype Source_Pattern



 @node !Commands.Links.Display

 procedure Display (World    : World_Name     := "<IMAGE>";
                    Link     : Link_Name      := "@";
                    Source   : Source_Pattern := "?";
                    Kind     : Link_Kind      := Links.Any;
                    Response : String         := "<PROFILE>");

 DESCRIPTION

 Displays a subset of links from the links for the specified world.

 This procedure displays the links from the specified world that match the
 specified link name, source name, and kind. The display is placed in
 Current_Output (by default, an Environment output window). Errors are
 reported in log messages, which, by default, are also sent to the output
 window.

 By default, all links from the source world are displayed. Any subset of
 those links can be specified by link name, source, or kind. The links to be
 displayed must match all of the parameters specified. Typically, either the
 set of link names or the set of source names is restricted to some subset
 of the links in the set.


 PARAMETERS

 World : World_Name := "<IMAGE>";

 Specifies the world whose links are to be displayed. Special names,
 wildcards, and context characters are allowed when they resolve to a
 unique world. The default is the current selection, if one exists, or the
 object in whose image the cursor is located. If the current image is not
 a world, the Environment uses the current world (the world enclosing the
 current context).


 Link : Link_Name := "@";

 Specifies the names of the links to be displayed. A restricted subset of
 naming expressions are allowed (see subtype Link_Name). The default is all
 link names.


 Source : Source_Pattern := "?";

 Specifies the fully qualified pathnames of the links to be displayed. A
 restricted subset of naming expressions are allowed (see subtype
 Source_Pattern). The default is all source names.


 Kind : Link_Kind := Links.Any;

 Specifies the kind of links to be displayed. The default is both internal
 and external links.


 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 links for a world, you must have read access to that world.


 EXAMPLES

 To list all the links in the set of links for your home world that
 reference packages in !Io, you can use the following command:

   Links.Display (World    => "!Users.Your_Username",
                  Link     => "@",
                  Source   => "!Io?",
                  Kind     => Links.Any,
                  Response => "<PROFILE>");

 A display such as the following appears in an Environment output window:

   92/01/22 17:34:06 --- Links from !USERS.YOUR_USERNAME.

             Link             Kind             Actual Name
   =========================  ====  ==================================
   DEVICE_INDEPENDENT_IO      EXT   !IO.DEVICE_INDEPENDENT_IO'SPEC
   DIRECT_IO                  EXT   !IO.DIRECT_IO'SPEC
   IO                         EXT   !IO.IO'SPEC
   IO_EXCEPTIONS              EXT   !IO.IO_EXCEPTIONS'SPEC
   OBJECT_SET                 EXT   !IO.OBJECT_SET'SPEC
   PIPE                       EXT   !IO.PIPE'SPEC
   POLYMORPHIC_IO             EXT   !IO.POLYMORPHIC_IO'SPEC
   POLYMORPHIC_SEQUENTIAL_IO  EXT   !IO.POLYMORPHIC_SEQUENTIAL_IO'SPEC
   SEQUENTIAL_IO              EXT   !IO.SEQUENTIAL_IO'SPEC
   TAPE_SPECIFIC              EXT   !IO.TAPE_SPECIFIC'SPEC
   TERMINAL_SPECIFIC          EXT   !IO.TERMINAL_SPECIFIC'SPEC
   TEXT_IO                    EXT   !IO.TEXT_IO'SPEC
   WINDOW_IO                  EXT   !IO.WINDOW_IO'SPEC

 REFERENCES

 subtype Link_Name
 subtype Source_Pattern



 @node !Commands.Links.Edit

 procedure Edit (World : World_Name := "<IMAGE>");

 DESCRIPTION

 Opens the links from the specified world for editing.

 This procedure creates a window and displays the set of links from the
 specified world in that window. From the window, the links can be edited
 with many of the operations from package !Commands.Common (see the
 introduction to this package for details). If a window already exists
 containing the designated set of links, that window is reused.

 This procedure creates a new window for each set of links to be edited. To
 reuse an existing links window to view a different set of links, use the
 Visit procedure. To display a subset of links, without opening them for
 editing, use the Display procedure.


 PARAMETERS

 World : World_Name := "<IMAGE>";

 Specifies the world whose links are to be edited. Special names, wildcards,
 and context characters are allowed when they resolve to a unique world.
 The default is the current selection, if one exists, or the object in whose
 image the cursor is located. If the current image is not a world, the
 Environment uses the current world (the world enclosing the current context).


 RESTRICTIONS

 To view the links for a world, you must have read access to that world.


 EXAMPLES

 To display the set of links for your home world in a window from which you
 can edit them, execute the command:

   Links.Edit ("!Users.Your_Username");
            

 REFERENCES

 procedure Display
 procedure Visit



 @node !Commands.Links.Expunge

 procedure Expunge (World    : World_Name := "<IMAGE>";
                    Response : String     := "<PROFILE>");

 DESCRIPTION

 Removes obsolete links from the set of links for the specified world.

 When a unit is deleted, links to that unit are not removed from sets of
 links that are currently displayed or open for editing. This procedure
 refreshes the image of a set of links by removing links to units that no
 longer exist. The set of links is also refreshed each time a new image of
 the links is created.


 PARAMETERS

 World : World_Name := "<IMAGE>";

 Specifies the name of the world whose set of links is to be expunged.
 Special names, wildcards, and context characters are allowed when they
 resolve to a unique world. The default is the current selection, if one
 exists, or the object in whose image the cursor is contained. If the
 current image is not a world, the Environment uses the current world (the
 world enclosing the current context).


 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 expunge the links for a world, you must have owner access to that
 world.



 @node !Commands.Links.External

 External : constant Link_Kind : Links_Implementation.External;

 DESCRIPTION

 Defines a constant that specifies external links.

 An external link is a link whose source unit is contained outside the
 current world.

 For more information about kinds of links, see the introduction to this
 package.


 REFERENCES

 constant Any
 constant Internal
 subtype Link_Kind



 @node !Commands.Links.Insert

 procedure Insert (Source : Source_Name := ">>SOURCE NAME<<");

 DESCRIPTION

 Inserts a link to the unit specified by the source name.

 This procedure creates a link with the specified source name in the set of
 links for the enclosing world. The link name is automatically the simple
 name of the source unit. If a link of that link name already exists, the
 existing link is overwritten, provided it does not have dependents.

 This procedure is generated when you execute the !Commands.Common.Object-
 .Insert procedure from a window containing links. When entered in a
 command window that is not attached to a major window containing links,
 this procedure creates a window containing the set of links for the
 current world and places the cursor in that window. To add a new link
 without creating a window, use the Add procedure.

 You should also use the Add procedure instead of this procedure if you
 want to:

 *  Create a link with a link name that differs from the simple name of the
    source unit

 *  Ensure that you do not inadvertently overwrite existing links

 *  Obtain a job progress report in the form of log messages


 PARAMETERS

 Source : Source_Name := ">>SOURCE NAME<<";

 Specifies the fully qualified pathname of the source unit. Multiple units
 can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. Multiple names can be separated by a
 semicolon. The default parameter placeholder ">>SOURCE NAME<<" must be
 replaced or an error will result.


 RESTRICTIONS

 Link names must be unique within a set of links. If a link of the specified
 link name already exists, that link is overwritten by the new link,
 provided the existing link has no dependents.

 To insert a link into the set of links for a world, you must have owner
 access to that world and read access to the unit named in the Source
 parameter.


 ERRORS

 If links are being inserted and any one fails because of name conflicts
 with existing units, only that link insertion fails.


 EXAMPLES

 To create a link in the set of links for your home world to procedure
 !Users.Anderson.Factorial, place the cursor in your home world or in the
 set of links for your home world and execute the following command:

   Links.Insert ("!Users.Anderson.Factorial");

 REFERENCES

 procedure Add
 procedure Replace
 procedure Update



 @node !Commands.Links.Internal

 Internal : constant Link_Kind : Links_Implementation.Internal;

 DESCRIPTION

 Defines a constant that specifies internal links.

 An internal link is a link whose source unit is contained inside the
 current world. It does not include links whose source units are contained
 in nested or enclosing worlds.

 For more information about kinds of links, see the introduction to this
 package.


 REFERENCES

 constant Any
 constant External
 subtype Link_Kind



 @node !Commands.Links.Link_Kind

 subtype Link_Kind is Links_Implementation.Link_Kind;

 DESCRIPTION

 Specifies the kind of link on which procedures are to operate.

 The kind of link can be internal, external, or any (which specifies both
 internal and external links).

 For more information about kinds of links, see the introduction to this
 package.


 REFERENCES

 constant Any
 constant External
 constant Internal



 @node !Commands.Links.Link_Name

 subtype Link_Name is String;

 DESCRIPTION

 Defines the form of link names.

 This subtype is a string that denotes the local names of units. That is,
 this subtype denotes the shortened names (link names) used in the set of
 links to refer to Ada units in other libraries. Units that with units in
 other libraries use names of this subtype in their with clauses.
 Therefore, names of this subtype must be legal Ada simple names.

 In the Add and Replace procedures, the Link_Name subtype accepts the use
 of substitution characters to allow building link names from source names
 (see Table 2). In all other procedures, the Link_Name subtype allows use
 of only a restricted subset of naming expressions (see Table 3).

                     Table 2   Substitution Characters
             ------------------------------------------------ 
            |      |                                         |
            |Charac|               Description               |
            | ter  |                                         |
             ------------------------------------------------ 
            |      |                                         |
            |  @   |Maps onto the next wildcard in the source|
            |      |name. The @ is replaced with each string |
            |      |that is matched by the wildcard, possibly|
            |      |resulting in multiple destination names. |
            |      |Useful when copying, moving, or renaming |
            |      |multiple objects in a single operation.  |
             ------------------------------------------------ 
            |      |                                         |
            |  #   |Maps onto the next whole name component  |
            |      |in the source name. The # is replaced    |
            |      |with this name component in the expanded |
            |      |destination name. Useful for saving      |
            |      |typing when the source and destination   |
            |      |names have components in common.         |
             ------------------------------------------------ 
            |      |                                         |
            |  ?   |Compatible with previous releases of the |
            |      |Environment; not recommended for use.    |
             ------------------------------------------------ 



                  Table 3   Restricted Naming Expressions
             ------------------------------------------------ 
            |      |                                         |
            |Charac|               Description               |
            | ter  |                                         |
             ------------------------------------------------ 
            |      |                                         |
            |  #   |Matches a single character other than a  |
            |      |period. T#### matches Tools.             |
             ------------------------------------------------ 
            |      |                                         |
            |  @   |Matches zero or more characters not      |
            |      |containing a period. !U@.@.Tools matches |
            |      |!Users.Anderson.Tools.                   |
             ------------------------------------------------ 
            |      |                                         |
            |  ?   |Matches zero or more name components.    |
            |      |!Users.Anderson? matches !Users.Anderson |
            |      |and everything in it.                    |
             ------------------------------------------------ 
            |      |                                         |
            |  []  |Enclose a set of names.                  |
            |      |[!Users.Anderson?,!Users.Miyata?] matches|
            |      |everything in the home worlds for        |
            |      |Anderson and Miyata.                     |
             ------------------------------------------------ 
            |      |                                         |
            |  ~   |Indicates that something should not be   |
            |      |matched. [@,~Tools] matches everything in|
            |      |a library except Tools.                  |
             ------------------------------------------------ 



 REFERENCES

 subtype Source_Name
 subtype Source_Pattern



 @node !Commands.Links.Replace

 procedure Replace (Source   : Source_Name := ">>SOURCE NAMES<<";
                    Link     : Link_Name   := "#";
                    World    : World_Name  := "<IMAGE>";
                    Response : String      := "<PROFILE>");

 DESCRIPTION

 Replaces the source name for one or more links.

 This procedure searches for a link of the specified link name. If one
 exists, this procedure replaces it with a link to the new source unit. If
 a link of the specified link name does not exist, a link is created using
 the specified link and source names. By default, link names are the simple
 names of the source units they reference.

 Note that this procedure replaces the source name of an existing link; it
 does not change the link name. To change the link name of an existing
 link, you must first create a new link with the desired link and source
 names and then delete the old link to that source (see "Editing Links," in
 the introduction to this package).

 The Replace procedure is similar to the Update procedure. However, the
 Update procedure is easier to use if you are in a window containing the
 link to be edited. To create one or more new links, see the Add and Insert
 procedures.


 PARAMETERS

 Source : Source_Name := ">>SOURCE NAMES<<";

 Specifies the fully qualified pathname of the source unit. Multiple units
 can be specified using wildcards, context characters, set notation,
 indirect files, and attributes. The default parameter placeholder
 ">>SOURCE NAMES<<" must be replaced or an error will result.


 Link : Link_Name := "#";

 Specifies the name of the link. Substitution characters can be used to
 allow building link names from source names (see subtype Link_Name). The
 default is the simple name of the source unit.


 World : World_Name := "<IMAGE>";

 Specifies the world in which to replace the link. Special names, wildcards,
 and context characters can be used when they resolve to a unique world.
 The default is the current selection, if one exists, or the object in
 whose image the cursor is located. If the current image is not a world,
 the Environment uses the current world (the world enclosing the current
 context).


 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

 Link names must be unique within a set of links. If a link of the specified
 link name already exists, that link is overwritten by the new link,
 provided the existing link has no dependents.

 To replace a link, you must have owner access to the world in which to
 replace the link and read access to the new source unit.


 ERRORS

 If a set of links are being replaced and any one fails because of name
 conflicts with existing links, only that link replacement fails.


 EXAMPLES

 The default set of links includes a link called Message that references
 !Commands.Message. Suppose you want to change the link so that Message
 references a package called Message in your Utilities world. To change
 the source for link Message, execute the following command:

   Links.Replace
          (Source   => "!Users.Your_Username.Utilities.Message",
           Link     => "#",
           World    => "<IMAGE>",
           Response => "<PROFILE>");

 The procedure automatically overwrites the existing link to
 !Commands.Message. For this reason, the procedure will succeed only if the
 link Message has no dependents. If you want to create a link to your
 Message unit without overwriting !Commands.Message, you can execute the
 command and provide a nondefault value (one that is not the simple name of
 the unit) for the Link parameter.


 REFERENCES

 procedure Add
 procedure Insert
 procedure Update
 Session and Job Management (SJM), package Profile



 @node !Commands.Links.Source_Name

 subtype Source_Name is String;

 DESCRIPTION

 Defines the form of the names of units that are the sources of links.

 This subtype is a string that denotes the fully qualified pathname of
 linked units. This string is matched against units in the library
 structure by link procedures that traverse the library structure searching
 for the source unit and create a link to that unit (Add, Insert, Replace,
 and Update).

 The units named in parameters of this subtype do not have to be installed,
 but their declarations must exist in the library. Wildcards, context
 characters, set notation, indirect files, and attributes can be used.
 Multiple units can be named by strings of this type in all procedures
 except the Update procedure, in which only one Ada unit can be named.

 Note that this subtype differs from the Source_Pattern subtype, which is
 matched against the textual representation of source names in the set of
 links for a world.


 REFERENCES

 procedure Add
 procedure Replace
 subtype Source_Pattern
 procedure Update



 @node !Commands.Links.Source_Pattern

 subtype Source_Pattern is String;

 DESCRIPTION

 Defines the form of the names of source units in sets of links.

 This subtype is a string that denotes the fully qualified pathname of
 linked units. This string is matched against the source names in the set
 of links for a world by link procedures that select a subset of links on
 which to operate (Copy, Delete, Dependents, and Display). A restricted
 subset of naming expressions are allowed (see Table 4).

 Note that this subtype differs from the Source_Name subtype, which is
 matched against actual units in the library hierarchy.

                  Table 4    Restricted Naming Expressions
             ------------------------------------------------ 
            |      |                                         |
            |Charac|               Description               |
            | ter  |                                         |
             ------------------------------------------------ 
            |      |                                         |
            |  #   |Matches a single character other than a  |
            |      |period. T#### matches Tools.             |
             ------------------------------------------------ 
            |      |                                         |
            |  @   |Matches zero or more characters not      |
            |      |containing a period. !U@.@.Tools matches |
            |      |!Users.Anderson.Tools.                   |
             ------------------------------------------------ 
            |      |                                         |
            |  ?   |Matches zero or more name components.    |
            |      |!Users.Anderson? matches !Users.Anderson |
            |      |and everything in it.                    |
             ------------------------------------------------ 
            |      |                                         |
            |  []  |Enclose a set of names.                  |
            |      |[!Users.Anderson?,!Users.Miyata?] matches|
            |      |everything in the home worlds for        |
            |      |Anderson and Miyata.                     |
             ------------------------------------------------ 
            |      |                                         |
            |  ~   |Indicates that something should not be   |
            |      |matched. [@,~Tools] matches everything in|
            |      |a library except Tools.                  |
             ------------------------------------------------ 



 REFERENCES

 procedure Copy
 procedure Delete
 procedure Dependents
 procedure Display



 @node !Commands.Links.Update

 procedure Update (Source : Source_Name := ">>SOURCE NAME<<");

 DESCRIPTION

 Updates the source name of the designated link.

 This procedure changes the source name of the link on which the cursor is
 located. The old link name resolves to this new source unit. The link to
 the original source unit is overwritten, provided it does not have
 dependents. This command is generated in response to procedure
 !Commands.Common.Edit when executed in a window containing links.

 If this procedure is entered in a command window that is not attached to a
 window that contains a set of links, an error results. To change the
 source name of a link without creating a window containing the set of
 links, use the Replace procedure. You should also use the Replace
 procedure if you want the procedure to automatically create a new link
 when a link of the given link name does not already exist, or if you want
 to obtain a job progress report in the form of log messages.


 PARAMETERS

 Source : Source_Name := ">>SOURCE NAME<<";

 Specifies the fully qualified pathname of the source unit. Wildcards,
 context characters, set notation, indirect files, and attributes are
 allowed if they resolve to a single unit. The default parameter
 placeholder ">>SOURCE NAME<<" must be replaced or an error will result.


 RESTRICTIONS

 To update a link, you must have owner access to the world and read access
 to the new source unit.


 ERRORS

 If the designated link has dependents, the procedure fails.

 This procedure can be used only from a window containing a set of links.
 If executed from any other location, the procedure fails.


 EXAMPLES

 The default set of links includes a link called Message that references
 !Commands.Message. Suppose you want to change the source name for the
 Message link in your home world so that Message references your own
 package Message in !Users.Your_Username.Utilities.Message. To change the
 source for link Message, place the cursor on the Message link and execute
 the following command:

   Update (Source => "!Users.Your_Username.Utilities.Message");

 The procedure automatically overwrites the existing link to
 !Commands.Message. For this reason, the procedure will succeed only if the
 link Message has no dependents. If you want to create a link to your
 Message unit without overwriting !Commands.Message, use the Replace or
 Add command, which allows you to specify that the link name be different
 from the source name for the unit it references.


 REFERENCES

 procedure Add
 procedure Replace



 @node !Commands.Links.Visit

 procedure Visit (World : World_Name := "<IMAGE>");

 DESCRIPTION

 Visits the links from the specified world.

 This procedure replaces the set of links in an existing window with the
 set of links from the specified world. From the window, the links can be
 edited with operations from package !Commands.Common that are supported
 for editing links (see the introduction to this package for details). If a
 window does not already exist for editing links, one is created.

 This procedure does not allow you to create a second window containing
 links. Thus, if you are performing operations that are easier when two
 sets of links are displayed simultaneously (such as copying links), use
 the Edit procedure to open the second set of links in a new window.


 PARAMETERS

 World : World_Name := "<IMAGE>";

 Specifies the world whose links are to be visited. Special names,
 wildcards, and context characters are allowed when they resolve to a
 unique world. The default is the current image. If the current image is
 not a world, the Environment uses the current world (the world enclosing
 the current context).


 RESTRICTIONS

 To view the set of links for a world, you must have read access to that
 world.


 EXAMPLES

 To display the set of links for your home world in an existing links
 window, from which they can be edited, execute the command:

   Links.Visit ("!Users.Your_Username");

 If a window containing links does not already exist, one is created.


 REFERENCES

 procedure Edit



 @node !Commands.Links.World_Name

 subtype World_Name is String;

 DESCRIPTION

 Defines the form of world names.

 This subtype is a string that denotes the fully qualified pathname of an
 existing world. Wildcards, special names, and context characters are
 allowed when they reference a unique world. Multiple worlds cannot be
 specified.


 ENDCOMMENT ]


 @node !Commands.Switches

 Package Switches provides operations for creating, manipulating, changing,
 and deleting the switches associated with a session or library. As with
 most commands in the world !Commands, these commands can be executed
 programmatically but are intended for interactive use.


 RESOURCES IN PACKAGE SWITCHES

 The commands in package Switches fall into several functional groups.
 Unless otherwise noted, commands affect both library and session switch
 files. Types and constants are not included in this list.

 Creating switch files:                    Create, Define (library)

 Controlling association of library        Associate, Associated,
 switch files:                             Dissociate

 Displaying a group of switches:           Display

 Opening switch files for editing:         Edit (library), (session),
                                           Edit_Session_Attributes
                                           Visit
                                                                           
 Changing the values of switches:          Change, Insert, Set

 Saving switches to a specified file:      Write


 KEY CONCEPTS FOR PACKAGE SWITCHES

 Switches provide a means of tailoring the behavior of the various
 Environment facilities. They control such facilities as the formatting,
 semanticizing, and compilation of Ada units; the reporting of warnings
 and errors; debugger operations; window management; networking; and
 printer operations. Switches are divided into two kinds, library and
 session, based on the types of operations they affect.


 Library Switches

 Library switches are defined for a specific library (that is, a directory or
 world). These switches are designed to control facilities that are
 program- or project-specific rather than user-specific. That is, they
 control facilities that should be constant throughout a particular program
 on which many users may be working. Library switches affect the following
 operations:

 *  Compilation--specifically, certain compiler optimizations and the
    compiler's response to particular types of errors

 *  Automatic creation of internal links

 *  Pretty-printing of Ada units

 *  FTP processes initiated from that library

 For a list of the library switches, see "Library Switches Grouped by
 Function," page nn. For information about a particular library switch, see
 "Description of Library Switches," page nn.


 Association of Library Switch Files

 Library switch files can be located in any library. However, to affect the
 units in a particular library, a library switch file must be explicitly
 associated with that library. Library switch files may, but need not, be
 contained in the libraries with which they are associated:

 *  A single library switch file can be associated with several directories
    or worlds.

 *  Only one library switch file can be associated with any particular
    library at a given time.


 Ensuring Consistency throughout a Project

 To ensure consistency across a project or program, you can associate a
 single library switch file with all of the libraries that are part of that
 project or program. This process can be aided by the use of a model world.

 A model world designates several features, including the associated
 library switch file, that are set when new libraries are created. When a
 library is created, it is automatically associated with the same library
 switch file as its model world. If no model is specified, then the library
 is associated with the switch file associated with the enclosing library.
 If the specified model (or the enclosing library) does not have an
 associated library switch file, then the newly created library is not
 associated with a library switch file. Libraries without associated library
 switch files use system-defined default settings.


 Library Switches and Subsystems

 Views are automatically associated with a library switch file called
 Compiler_Switches, which resides in the State directory of that view.
 Directories in a view are also associated with the Compiler_Switches file
 in that view. You cannot remove this association or create a different
 association. Thus, all changes must be made to the values in the
 Compiler_Switches file.

 The Compiler_Switches file is created when the view is created. The initial
 switch values are determined according to the type of view:

 *  A new working view copies its initial switch values from the library
    switch file associated with the model from which the view is created. If
    no model is specified, the switches are copied from the library switch
    file associated with the enclosing subsystem. If the specified model
    (or enclosing subsystem) is not associated with a library switch file,
    then the switches assume system-defined default values.

 *  A spec view copies its initial switch values from the working view from
    which it was created.

 *  A released view copies its initial switch values from the working view
    from which it was created.

 See the Project Management (PM) book for more information about
 subsystems, views, and releases.


 Session Switches

 Session switches affect the way the system behaves on your terminal.
 Session switches are designed to control facilities that are user-specific
 rather than object-specific. That is, they control facilities that do not
 need to be consistent throughout a project but that are subject to the
 user's preference. These switches affect log files, error reaction, library 
 displays, text I/O, debugger operations, window management, networking, and
 printer control when using the session. Session switches also determine
 the default activity for the session.

 Session switch files are located in the user's home world. A user can have
 several session switch files, one for each session. The switch file for a
 session is designated by the filenaming convention Session_Name_Switches.
 Because session switch files are associated with a particular session
 through this naming convention, they do not need to be explicitly
 associated with a session to take effect.

 For more information about session switches, see Session and Job
 Management (SJM), Session Switches.


 Switches That Exist as Both Library and Session Switches

 Switches controlling file transfers exist in both library and session
 switch files. In library switch files, these switches have the prefix Ftp. In
 session switch files, these switches have the prefix Session_Ftp. These
 switches interact to control the login procedure on the remote machine,
 the specifications of the remote machine, and the specifications of the file
 transfer.


 Interaction between Library and Session FTP Switches

 When you execute an FTP command, you can enter string values for each
 parameter or you can use the default parameter values. The default
 parameter values for many FTP commands are functions. These functions
 obtain file-transfer information by checking the following locations in
 order:

 *  FTP library-switch values

 *  Session_Ftp session-switch values

 *  The files identified by the Profile.Remote_Passwords and
    Profile.Remote_Sessions session switches

 *  Embedded system-defined default values

 Searching through these, FTP uses the first nonnull value it encounters for
 each parameter.


 Example

 Assume that the following switch values are in the library switch file
 associated with the current library:

   *         Ftp . Account                 : String         := "S_1"
             Ftp . Remote_Type             : String         := ""

 Assume that the following switch values are in the session switch file for
 the current session:

   * Session_Ftp . Account                 : String         := "S_2"
   *     Profile . Remote_Passwords        : Object         := <Nil>
   *     Profile . Remote_Sessions         : Object         := <Nil>
     Session_Ftp . Remote_Type             : String         := ""

 After establishing an FTP connection to a remote machine, you execute the
 following command to store the file Test_Notes in a file of the same name
 on the remote machine:

   Ftp.Store (From_Local_File => "Test_Notes",
              To_Remote_File  => "",
              Append_To_File  => False,
              Response        => Profile.Get,
              Remote_Type     => Ftp.Current_Remote_Type,
              Account         => Ftp_Profile.Account);

 The values for the Remote_Type and Account parameters are the default
 functions, instructing FTP to search the appropriate switch files for the
 values to insert.

 FTP first checks the switches for the current library. The Ftp.Account
 switch provides the account name "S_1". However, the value for
 Ftp.Remote_Type is the null string.

 To find the Remote_Type, FTP checks the switches associated with the
 current session. Here the value for the Session_Ftp.Remote_Type switch is
 also the null string, so FTP finally uses the system-defined default remote
 type, Rational.


 USING COMMANDS FROM PACKAGE SWITCHES

 Using commands from this packages you can create, view, edit, or delete
 sets of session or library switches. The following subsections discuss
 these operations and the commands available for each.

 Commands that are applicable only for a particular kind of switch file are
 noted accordingly; otherwise, commands can be used on both library
 switches and session switches.


 Creating Switch Files

 When a switch file is first created, it is "empty"; that is, all of the
 switches are assigned system-defined default values. These values are the
 same as those that are used when no switch file exists. Thus, you need to
 create a switch file only if you want to change the value of one or more
 switches or if you want to view the default switch values.

 This package provides two procedures for explicitly creating switch files:

 *  Create

 *  Define

 You can use the Create procedure to create either a library or a session
 switch file of the given name. By default, the Create procedure creates a
 library switch file. If a switch file of the specified name already exists,
 that file is overwritten by a new (empty) switch file.

 The Define procedure always creates a library switch file of the given name.
 As with the Create procedure, if the specified switch file already exists, a
 new (empty) version is created and the existing switch file is overwritten.

 As a shortcut, you can create a switch file for your current session and
 open it for editing in a single operation, using the
 Edit_Sesson_Attributes procedure. Similarly, you can use the Edit
 procedure to create a library switch file (automatically named
 Library_Switches), associate it with the current library, and open it for
 editing.

 Remember that session switch files must be named using the convention
 Session_Name_Switches. Session switch files always are placed in your
 home world.

 Library switch files can be assigned any name and can be created in any
 library. Library switch files do not need to exist in a particular library
 to affect operations in that library. Instead, library switch files must be
 associated explicitly with a library in order to affect operations in that
 library (see "Associating and Dissociating Library Switch Files," page
 nn).


 Opening a Switch File for Editing

 Package Switches provides three commands for opening switch files for
 editing:

 *  Edit

 *  Edit_Session_Attributes

 *  Visit

 To create a window containing the specified library switch file, use the
 Edit procedure. By default, the Edit procedure opens the library switch
 file associated with the current library. If the specified library switch
 file does not exist, one of that name is created and associated with the
 current library. If no library switch file is specified and none is
 associated with the current library, the procedure creates a switch file
 called Library_Switches, places it in the current library, and associates
 it with the current library.

 To open the session switch file associated with the current session, use
 the Edit_Session_Attributes procedure. If a switch file does not exist
 for the current session, one is created and opened in a window.

 The Edit and Edit_Session_Attributes procedures display each switch file in
 a new window unless the specified set of switches is already visible in a
 window. In that case, the window is reused and the cursor is moved to that
 window.

 The Visit procedure is similar to the Edit and Edit_Session_Attributes
 procedures except that it always reuses an existing switch window, if one
 exists. Thus, instead of creating a new window each time a set of switches
 is viewed, the procedure replaces the set of switches currently being
 viewed with the new set. By default, the Visit procedure opens the library
 switch file associated with the current library; however, you can use it to
 open any library or session switch file.


 Listing Switches

 If you want to view a subset of switches, such as all those with the
 processor name R1000_Cg, you can use the Display procedure. The Display
 procedure generates a list of the switches from the specified library or
 session switch file that match the specified composite (processor and
 switch) name. Because the image
 produced by the Display procedure is a textual representation of the
 switches, switches are not opened for editing by this procedure. To open
 switches for editing, use the Edit, Edit_Session_Attributes, or Visit
 procedure.


 Changing the Value of a Switch

 Package Switches provides three commands for changing the value of a
 switch:

 *  Change

 *  Insert

 *  Set

 To change the value of the switch on which the cursor is located, use the
 Change procedure. The Change procedure can be entered directly in a
 command window or brought up by using the Common.Edit procedure in a
 switch window.

 To change the value of one or more switches, you can use the Insert or the
 Set procedure. For each procedure, you must specify both the switches to
 be changed and the new values. Multiple switches can be inserted by
 separating them with semicolons.

 The Insert procedure can easily be brought into a command window by using
 the Common.Object.Insert procedure in a switch window. However, the Set
 procedure is more powerful in two ways. The Set procedure:

 *  Allows you to specify any switch file. If the specified switch file does
    not exist, one of that name is created automatically.

 *  Automatically commits the changes to the switch file.

 Note: Switch files must be committed for new switch values to take effect.
 If the switch file is a library switch file, it also must be associated with
 a directory or world to affect operations in that directory or world.


 Saving Switch Files

 Switch files must be committed for new switch values to take effect. To
 save a switch file, execute !Commands.Common.Promote or
 !Commands.Common.Commit from the window containing the switch file.

 To write switch values to a switch file of a different name, use the Write
 procedure (defined in this package), specifying the file to which to write
 the switches.


 Associating and Dissociating Library Switch Files

 Library switch files must be associated explicitly with a particular world
 or directory to affect units in that library. To associate a library
 switch file with a directory or world, use the Associate procedure,
 specifying the name of the switch file and the name of the library with
 which to associate it.

 To check for the switch file associated with a particular library, you can
 use the Associated function. Because the Associated function returns a
 value, you also need to specify how you would like the value returned. For
 example, the following command writes the name of the switch file
 associated with the current library in the message window:

   Io.Echo (Switches.Associated)

 If no switch file is associated with the current library, the Associated
 function returns the null string.

 To remove the association between a directory or world and a library
 switch file, enter the Switches.Dissociate command, specifying the library
 from which to dissociate the library switch file.

 Note: Views and directories in views are automatically associated with the
 library switches contained in View_Name.State.Compiler_Switches. This
 switch-file association cannot be changed.


 Getting Help on Switches

 To get help on either a library or a session switch, open the switch file
 for editing using the Edit or Edit_Session_Attributes procedure, place the
 cursor on the line of the switch in question, and execute the
 Common.Explain procedure. A help file appears on the line(s) below the
 switch.

 You can get help on several adjacent switches by selecting the desired
 switches and executing Common.Explain. If a selected switch is scrolled
 off the screen, that switch is still considered selected and the
 Common.Explain procedure operates
 on it.


 LIBRARY SWITCHES GROUPED BY FUNCTION

 Within the set of library switches, switches are further grouped by
 processor. Each processor designates a general functionality that is
 controlled by that group of switches. Within each processor group, there
 may be several switches that affect that particular function of the
 Environment.

 The following lists name all library switches, grouped by processor name.
 Following the lists are descriptions of the library switches, ordered
 alphabetically. For a list of session switches, see Session and Job
 Management (SJM), Session Switches.

 Note that this section describes only the library switches that are
 delivered as part of the standard Environment. Session switches that
 control layered products, such as Rational's family of Cross-Development
 Facility (CDF) products, are documented in the manuals for those
 products.


 Switches for Formatting Ada Units

 Switches that control the formatting of Ada units have the processor name
 Format. Changes to these switches affect only Ada units created after the
 changes are made. To apply new Format switch values to an existing Ada
 unit, use the Library.Reformat_Image command.

 Alignment_Threshold               Comment_Column
 Consistent_Breaking               Id_Case
 Keyword_Case                      Line_Length
 Major_Indentation                 Minor_Indentation
 Number_Case                       Statement_Indentation
 Statement_Length                  Wrap_Indentation


 Switches for Semanticizing Ada Units

 Switches that control the semanticizing of Ada units have the processor
 name Semantics.

 Closed_Private_Part               Flag_Inevitable_Exceptions
 Ignore_Interface_Pragmas          Ignore_Invalid_Rep_Specs
 Ignore_Minor_Errors               Ignore_Unsupported_Rep_Specs
 Reject_Bad_Lrm_Pragmas            Reject_Bad_Rational_Pragmas
 Reject_Inevitable_Exceptions      Reject_Statement_Prompts
 Reject_Undefined_Pragmas          Subsystem_Interface


 Switches for the R1000 Compiler

 Switches that control the compilation of Ada units for the R1000 target
 have the processor name R1000_Cg. Suggestions for using these switches to
 affect compilation are provided in Chapter 3, "Tailoring the Compilation
 Setting."

 Asm_Listing                       Check_Compatibility
 Configuration                     Delta1_Code_View_Compatibility
 Elab_Order_Listing                Enable_Deallocation
 Full_Debugging                    Package_Integration
 Page_Limit                        Retain_Delta1_Compatibility
 Seg_Listing                       Terminal_Echo


 Switches for Registering Ada Units in Libraries

 Switches that control the library- and links-management operations that
 are performed the first time an Ada unit is promoted to the installed
 state have the processor name Directory.

 Create_Internal_Links             Create_Subprogram_Specs
 Require_Internal_Links


 Switches for File Transfers

 Switches that specify the default parameter values for file-transfer
 operations have the processor name Ftp.

 Account                           Auto_Login
 Password                          Prompt_For_Account
 Prompt_For_Password               Remote_Directory
 Remote_Machine                    Remote_Roof
 Remote_Type                       Send_Port_Enabled
 Transfer_Mode                     Transfer_Structure
 Transfer_Type                     Username


 DESCRIPTION OF LIBRARY SWITCHES


 Account

 Specifies the account name to be provided by default to a remote computer
 when an FTP connection is established. For the R1000, the account name is
 used to represent the name of a session. The default is the null string.
 The full switch name is Ftp.Account.


 Alignment_Threshold

 Specifies the number of blank spaces that the pretty-printer can insert to
 align lexical constructs (such as colons, assignments, and arrows in
 named notation) in consecutive statements. If more than this number of
 spaces would be needed to align a construct, the construct is left
 unaligned. Legal values are integers in the range 0 .. 254. The default
 is 0. The full switch name is Format.Alignment_Threshold.


 Asm_Listing

 Controls whether an assembly-code list file is created for the generated
 code. Assembly-code list files are stored as associated files of Ada units
 and have the name <Asm_Listing>. These files can be echoed to the screen
 during creation using the Terminal_Echo switch. The default (False) does
 not cause the compiler to create listings. The full switch name is
 R1000_Cg.Asm_Listing.


 Auto_Login

 Controls whether the !Commands.Ftp.Connect command attempts to log into a
 remote computer as soon as a connection is established. The default is
 False. The full switch name is Ftp.Auto_Login.


 Check_Compatibility

 Controls whether spec views and load views are checked for compatibility
 when a main program is coded. When True, programs containing
 incompatibilities fail to code. The default is True. The full switch name
 is R1000_Cg.Check_Compatibility.


 Closed_Private_Part

 Managed by Rational Subsystems. This switch should not be changed by
 users. The full switch name is Semantics.Closed_Private_Part.


 Comment_Column

 Specifies the column in which the !Commands.Editor.Char.Tab_To_Comment com-
 mand inserts a comment delimiter. Comments placed in this column remain in
 this column after formatting, provided the first comment in the grouping
 begins to the right of and on the same line as text. This switch is useful
 only if the !Commands.Editor.Char.Tab_To_Comment command is bound to a
 key. Legal values are integers. The default is column 1. The full switch
 name is Format.Comment_Column.


 Configuration

 Managed by Rational Subsystems. This switch should not be changed by
 users. The full switch name is Parser.Configuration.


 Consistent_Breaking

 Controls the formatting of lists of the form (xxx:aaa; yyy:bbb), which
 appear in subprogram formal parts and as discriminants in type
 declarations. Also controls formatting of lists of the form (xx=>aaa,
 yyy=>bbb), which appear in subprogram calls and aggregates. If this option
 is nonzero (True) and a list does not fit on a line, every element of the
 list begins on a new line. If this option is zero (False) and a list does
 not fit on a line, as many elements as fit are placed on each line. Legal
 values are integers. The default is 1 (True). The full switch name is
 Format.Consistent_Breaking.


 Create_Internal_Links

 Controls whether internal links are created automatically when the visible
 parts of library units are promoted to the installed state. Internal links
 for library units are created in the set of links for the nearest
 enclosing world. The default is True. The full switch name is
 Directory.Create_Internal_Links.


 Create_Subprogram_Specs

 Controls whether specifications for library-unit subprograms are created
 automatically. When True, the contents of these specifications are
 created the first time the body is successfully installed. The with clause
 for the spec is derived from the with clauses in the body. Only those with
 clauses required to promote the specification are included. The default is
 True. The full switch name is Directory.Create_Subprogram_Specs.


 Delta1_Code_View_Compatibility

 Controls whether the compiler produces code views and loaded main programs
 that can be copied to machines running Environment releases prior to
 D_12_1_1. For this switch to have any effect, the Retain_Delta1_Compatibility
 switch must also be set to True. The default is False. The full switch name
 is R1000_Cg.Delta1_Code_View_Compatibility.


 Elab_Order_Listing

 Controls whether a file containing a listing of the elaboration order of
 the units in its closure is created when a coded main program is executed.
 Elaboration-order listings can be created only for coded main programs.
 Elaboration-order files are stored as associated files of Ada units and have
 the name <Elab_Order_Listing>. These files can be echoed to the screen
 during creation using the Terminal_Echo switch. The default (False) does
 not produce elaboration-order listings. The full switch name is
 R1000_Cg.Elab_Order_Listing.


 Enable_Deallocation

 Controls whether to implicitly apply the Enable_Deallocation pragma to all
 access types. When deallocation is enabled, the Unchecked_Deallocation
 procedure can be used to reclaim storage space for access types. However,
 enabling deallocation causes each allocated object to consume additional space.
 Therefore, this switch should be set to True only when needed. The default is
 False. The full switch name is R1000_Cg.Enable_Deallocation.


 Flag_Inevitable_Exceptions

 Controls whether to flag with a warning any statically determinable
 situation that is certain to raise an exception when executed, such as an
 illegal assignment. This switch is overridden by the
 Reject_Inevitable_Exceptions switch. Thus, if both switches are True,
 inevitable exceptions are rejected. The default is False. The full switch
 name is Semantics.Flag_Inevitable_Exceptions.


 Full_Debugging

 Controls whether compiler optimizations are suppressed, thereby enabling
 full use of the debugger on the produced code. When False, the compiler
 may generate no code at all for certain constructs so that single-stepping
 appears to skip statements and breakpoints cannot be set in certain
 places. The default is False. The full switch name is
 R1000_Cg.Full_Debugging.


 Id_Case

 Specifies the case of identifiers printed by the pretty-printer in Ada
 units. Legal values are Lower, Upper, and Capitalized. The default is
 Capitalized. The full switch name is Format.Id_Case.


 Ignore_Interface_Pragmas

 Controls whether pragma Interface is ignored. When True, the R1000
 compiler ignores the pragma completely. When False, the R1000 compiler
 builds an implicit body that raises the Program_Error exception whenever
 the subprogram is executed. The default is False. The full switch name
 is Semantics.Ignore_Interface_Pragmas.


 Ignore_Invalid_Rep_Specs

 Controls whether to flag either invalid or unsupported representation
 specifications with a warning or as an error. When False, all invalid
 representation specifications are flagged as errors, thus preventing the
 units that contain them from being installed. (Unsupported
 representation specifications are flagged as errors only if the
 Ignore_Unsupported_Rep_Specs switch is also False.) When
 Ignore_Invalid_Rep_Specs is True, both invalid and unsupported
 representation specifications are flagged with warning messages in the log
 file and are otherwise ignored. (Setting this switch to True overrides the
 value of the Ignore_Unsupported_Rep_Specs switch.) Representation
 specifications are considered invalid if they do not conform to the
 restrictions specified in Appendix F for the R1000 compiler. For most
 purposes, the Ignore_Invalid_Rep_Specs switch and the Ignore_Unsupported-
 _Rep_Specs switch should have the same value. The default is False. The
 full switch name is Semantics.Ignore_Invalid_Rep_Specs.


 Ignore_Minor_Errors

 Controls whether to flag minor errors with a warning or as an error. When
 False, minor errors are flagged as errors, thus preventing the units that
 contain them from being installed. When True, minor errors are flagged
 with warning messages in the log file and are otherwise ignored. Minor errors
 are those that the Reference Manual for the Ada Programming Language defines 
 as illegal but that do not affect the semantic validity of the program. 
 An example is illegal declaration order. The default is False. The full switch
 name is Semantics.Ignore_Minor_Errors.


 Ignore_Unsupported_Rep_Specs

 Controls whether to flag unsupported representation specifications with a
 warning or as an error. When False, unsupported representation
 specifications are flagged as errors, thus preventing the units that
 contain them from being installed (the Ignore_Invalid_Rep_Specs switch
 must also be False). When Ignore_Unsupported_Rep_Specs is True,
 unsupported representation specifications are flagged with warning messages
 in the log file and are otherwise ignored. For most purposes, the
 Ignore_Unsupported_Rep_Specs switch and the Ignore_Invalid_Rep_Specs
 switch should have the same value. The default is False. The full switch
 name is Semantics.Ignore_Unsupported_Rep_Specs.


 Keyword_Case

 Specifies the case of keywords printed by the pretty-printer in Ada units.
 Legal values are Lower, Upper, and Capitalized. The default is Lower. The
 full switch name is Format.Keyword_Case.


 Line_Length

 Specifies the number of columns used by the pretty-printer for printing
 lines in Ada units before wrapping them. Legal values are integers in the
 range 0 .. 254. The default is 80. The full switch name is
 Format.Line_Length.


 Major_Indentation

 Specifies the number of columns that the pretty-printer indents structured
 (major) constructs such as if statements, case statements, and loop
 statements. Legal values are integers in the range 0 .. 15. The default is
 4. The full switch name is Format.Major_Indentation.


 Minor_Indentation

 Specifies the number of columns that the pretty-printer indents minor
 constructs. Minor constructs include record declarations, variant record
 declarations, type declarations, exception handlers, alternatives, case
 statements, and named and labeled statements. Legal values are integers in
 the range 0 .. 15. The default is 4. The full switch name is
 Format.Minor_Indentation.


 Number_Case

 Specifies the case to be used by the pretty-printer in displaying the "E"
 in floating-point literals and based digits in based literals. Legal
 values are Lower, Upper, and Capitalized. The default is Uppercase. The
 full switch name is Format.Number_Case.


 Package_Integration

 Controls whether the code generator integrates all packages for which
 integration is possible, thus generating more efficient code for nested
 packages. When a package is integrated, the code is generated as if all
 of its declarations were declared

 directly with its parent package. Package integration is not allowed for
 packages that contain tasks or an initialization block, for library-unit
 packages, or for package subunits whose bodies are separate. Code
 generated with this switch set to True is not compatible with code
 generated by pre-D_12_1_1 compilers. The default is False. The full switch
 name is R1000_Cg.Package_Integration.


 Page_Limit

 Specifies the minimum value for the page limit for a job executing a unit
 that was compiled with this switch. The maximum number of pages allowed
 for a job is the highest of the following: the value of this switch, the
 Page_Limit pragma, and the session switch Session.Default_Job_Page_Limit.
 Legal values are integers less than 2 ** 24 - 1. The default is 8000. The
 full switch name is R1000_Cg.Page_Limit.


 Password

 Specifies the password to be provided by default to a remote computer when
 logging in using an FTP connection. The default is the null string. The
 full switch name is Ftp.Password.


 Prompt_For_Account

 Controls whether FTP, when logging into a remote computer, prompts the user
 to supply an account name. The user is prompted only if an account name is
 required by the remote computer and the Account switch is the null
 string. On the R1000, the account name is used to represent the name of a
 session. The default is False. The full switch name is Ftp.Prompt_For_Account.


 Prompt_For_Password

 Controls whether FTP, when logging into a remote computer, prompts the
 user to supply a password. The user is prompted only if a password is
 required by the remote computer and the Password switch is the null
 string. The default is False. The full switch name is
 Ftp.Prompt_For_Password.


 Reject_Bad_Lrm_Pragmas

 Controls whether to flag illegal Ada pragmas with warnings or as errors.
 When True, illegal Ada pragmas are flagged as errors, thus preventing the
 units that contain them from being installed. When False, illegal Ada
 pragmas are flagged with warning messages in the log file and are otherwise
 ignored. The default is False. The full switch name is
 Semantics.Reject_Bad_Lrm_Pragmas.


 Reject_Bad_Rational_Pragmas

 Controls whether illegal Rational pragmas are reported as warnings or
 errors. When True, illegal Rational pragmas are flagged as errors, thus
 preventing the units that contain them from being installed. When False,
 illegal Rational pragmas are flagged with warning messages in the log file
 and are otherwise ignored. The default is False. The full switch name is
 Semantics.Reject_Bad_Rational_Pragmas.


 Reject_Inevitable_Exceptions

 Controls whether to flag as an error any statically determinable situation
 that is certain to raise an exception when executed, such as an illegal
 assignment. This switch overrides the Flag_Inevitable_Exceptions switch.
 Thus, if both switches are

 True, inevitable exceptions are rejected. The default is False. The full
 switch name is Semantics.Reject_Inevitable_Exceptions.


 Reject_Statement_Prompts

 Controls whether the compiler will allow you to promote to the coded state
 Ada units that contain [statement] prompts. When False (the default),
 units that contain [statement] prompts can be coded; an error is raised
 only if an attempt is made to execute the prompt. When True, units that
 contain [statement] prompts cannot be promoted to the coded state. The
 full switch name is Semantics.Reject_Statement_Prompts.


 Reject_Undefined_Pragmas

 Controls whether any pragmas not defined in the Reference Manual for the
 Ada Programming Language or the Rational Environment Reference Manual are
 reported as warnings or errors. When True, undefined pragmas are flagged as
 errors, thus preventing the units that contain them from being installed.
 When False, undefined pragmas are flagged with warning messages in the log
 file and are otherwise ignored. The default is False. The full switch name
 is Semantics.Reject_Undefined_Pragmas.


 Remote_Directory

 Specifies a directory (or Environment library) on a remote computer to
 which to connect by default when establishing an FTP connection. The
 default is the null string, which signifies the default working directory.
 The full switch name is Ftp.Remote_Directory.


 Remote_Machine

 Specifies the name of the remote computer to which to connect by default
 when establishing an FTP connection. The default is the null string. The
 full switch name is Ftp.Remote_Machine.


 Remote_Roof

 Specifies a directory on a remote computer. This directory is an ancestor
 directory for a group of files that FTP is to transfer. By default, FTP
 uses the Remote_Roof for mapping between local and remote filenames. The
 default is the null string (the current working directory on the remote
 computer). The full switch name is Ftp.Remote_Roof.


 Remote_Type

 Specifies the type of remote computer to be used by default when using an FTP
 connection. Currently Rational, R1000, VMS, UNIX, AOS, and MVS types are
 supported. By default, FTP uses the Remote_Type for mapping between
 local and remote filenames. The default is Rational. The full switch name
 is Ftp.Remote_Type.


 Require_Internal_Links

 Controls whether failure to create internal links (as controlled by the
 Directory.Create_Internal_Links switch) generates an error. The default
 (True) is to treat failure to generate links as an error and to
 discontinue the operation. If the Directory.Create_Internal_Links switch 
 is set to False, this switch has no effect. The
 full switch name is Directory.Require_Internal_Links.


 Retain_Delta1_Compatibility

 Controls whether the compiler produces code that is compatible with code
 generated on releases prior to D_12_1_1. When False (the default), all
 of the new features and bug fixes in the D_12_1_1 (or later) compiler are
 enabled, producing code that is incompatible with previous releases. When
 True, compatible code is generated, disabling a number of features and bug
 fixes in the D_12_1_1 (or later) compiler. Note that validation under ACVC
 1.10 and 1.11 applies only when the switch is set to False. For further
 information about the effects of this switch, see the D_12_1_1 release
 note or the Key Concepts section of this book. The full switch name is
 R1000_Cg.Retain_Delta1_Compatibility.


 Seg_Listing

 Controls whether an object-code list file is created for the generated
 code. Object-code list files are stored as associated files of Ada units
 and have the name <Seg_Listing>. These files can be echoed to the screen
 during creation using the Terminal_Echo switch. The default is False. The
 full switch name is R1000_Cg.Seg_Listing.


 Send_Port_Enabled

 Controls whether FTP by default explicitly transmits the local data-port
 number to the remote server before initiating a file transfer. This
 practice ensures that local and remote machines are using the same
 connection. The switch should be set to True (the default) for transfer of
 multiple files. The full switch name is Ftp.Send_Port_Enabled.


 Statement_Indentation

 Specifies the number of columns the pretty-printer indents the second and
 subsequent lines of a statement when the statement has to be broken
 because it is longer than Line_Length. The pretty-printer indents
 Statement_Indentation number of columns only if there is no lexical
 construct with which the indented code can be aligned. Legal values are
 integers in the range 0 .. 15. The default is 3. The full switch name is
 Format.Statement_Indentation.


 Statement_Length

 Specifies the number of columns the pretty-printer reserves on each line to
 print a statement. If the current level of indentation allows for fewer than
 Statement_Length columns on a line, the pretty-printer starts over with
 the Wrap_Indentation column as its new level of indentation. This
 practice prevents deeply nested statements from being printed beyond the
 right margin. Legal values are integers in the range 0 .. 254. The default
 is 35. The full switch name is Format.Statement_Length.


 Subsystem_Interface

 Managed by Rational Subsystems. This switch should not be changed by
 users. The full switch name is Semantics.Subsystem_Interface.


 Terminal_Echo

 Controls whether listings files are displayed on the terminal as they are
 generated. Generation of listings files is controlled by the Asm_Listing,
 Elab_Order_Listing, and Seg_Listing switches. The default is False. The
 full switch name is R1000_Cg.Terminal_Echo.


 Transfer_Mode

 Sets the mode of an FTP file transfer. Currently, only Stream type is
 supported. The full switch name is Ftp.Transfer_Mode.


 Transfer_Structure

 Sets the structure of an FTP file transfer. Currently, only File type is
 supported. The full switch name is Ftp.Transfer_Structure.


 Transfer_Type

 Sets the type of an FTP file transfer. Currently, Ascii, Ascii_Telnet,
 Binary, Local_Binary, Local_Byte, and Image transfers are supported. The
 default is Ascii. The full switch name is Ftp.Transfer_Type.


 Username

 Specifies the username to be provided by default to a remote computer when
 logging in using an FTP connection. The default is the null string. The
 full switch name is Ftp.Username.


 Wrap_Indentation

 Specifies the column at which the pretty-printer begins the next level of
 indentation when the current level of indentation does not allow for
 Statement_Length. This practice prevents deeply nested statements from
 being printed beyond the right margin. Legal values are integers in the
 range 0 .. 254. The default is column 16. The full switch name is
 Format.Wrap_Indentation.


 COMMANDS FROM PACKAGE COMMON FOR EDITING SWITCHES

 When executed from an editable window containing switches, the following
 commands from package !Commands.Common are supported for editing
 switches. Operations from package Common that do not apply to switches
 produce a message to that effect when used on switches.

 Commands from package Common typically are used through the key combina-
 tions 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 Switches
     ---------------------------------------------------------------- 
    |               |                                                |
    |Key Bound To   |Accomplishes ...                                |
    |...            |                                                |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Abandon |Abandons the editing of the switches. The window|
    |               |is removed from the screen. Any changes made to |
    |               |the switches since the last commit operation are|
    |               |lost.                                           |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Commit  |Saves (commits) changes to the switches. While a|
    |               |switch file is being edited, changes to the     |
    |               |switches are made in a temporary area of the    |
    |               |Environment. This procedure makes the changes   |
    |               |permanent and causes them to take effect.       |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Create_ |Creates a command window attached to the current|
    |Command        |window. The use clause in the command window:   |
    |               |                                                |
    |               |     use Editor, Ada, Switches, Common;         |
    |               |                                                |
    |               |                                                |
    |               |includes packages Common and Switches, so       |
    |               |operations in these packages are visible in the |
    |               |command window without qualification.           |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.        |Finds the definition of the selected switch valu|
    |Definition     |if that value is of type Object or File_Name.   |
    |               |This procedure has no meaning for switch values |
    |               |of other types.                                 |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Edit    |Creates a command window and places in it the   |
    |               |following command, where the parameter is the   |
    |               |current value of the switch on which the cursor |
    |               |is located, whether or not there is a selection:|
    |               |                                                |
    |               |     Change ("current switch value");           |
    |               |                                                |
    |               |                                                |
    |               |Providing a new switch value and promoting the  |
    |               |command changes the value of the switch. If the |
    |               |current switch is of Boolean type, this         |
    |               |procedure toggles the value of the switch       |
    |               |without creating a command window.              |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Elide   |Reduces (elides) the number of switches         |
    |               |displayed in the window. The window can display |
    |               |all or only the nondefault switches. This       |
    |               |procedure reduces the number of switches        |
    |               |displayed to include only the switches with     |
    |               |nondefault values (those marked with an         |
    |               |asterisk). Reducing the number below the        |
    |               |nondefault switches has no effect.              |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.        |Creates a window with the library that contains |
    |Enclosing      |the switches that are in the current window. If |
    |               |the window contains session switches, this      |
    |               |procedure creates a window containing the home  |
    |               |world for that session. The In_Place parameter  |
    |               |specifies whether the library window replaces th|
    |               |switch window.                                  |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Expand  |Increases (expands) the number of switches      |
    |               |displayed in the window. The window can display |
    |               |all or only the nondefault switches. This       |
    |               |procedure increases the number of switches      |
    |               |displayed to include all the switches in the    |
    |               |system. Increasing the number above all switches|
    |               |in the system has no effect.                    |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Explain |Inserts, below the current switch, an           |
    |               |explanation of that switch. If an explanation is|
    |               |already there, this procedure removes it.       |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Promote |Saves (commits) changes to the switches. While  |
    |               |the switch file is being edited, changes to the |
    |               |switches are made in a temporary area of the    |
    |               |Environment. This procedure makes the changes   |
    |               |permanent and causes them to take effect.       |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Release |Commits changes and ends the editing of the     |
    |               |switches. The window is removed from the screen |
    |               |and any changes to the switches are saved.      |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Revert  |Reverts to the most recent committed version of |
    |               |the switches and redraws the switches in the    |
    |               |current window. Any changes made since the last |
    |               |commit operation are lost.                      |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Selects the switch on which the cursor is       |
    |Child          |located. If that switch is already selected,    |
    |               |this procedure has no effect. If all switches   |
    |               |are already selected, this procedure selects    |
    |               |only the switch on which the cursor is located. |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Copies the value of a highlighted switch from   |
    |Copy           |one set of switches to the switch of the same   |
    |               |name in the set of switches on which the cursor |
    |               |is located. If the selected switch and the      |
    |               |cursor are both in the same set of switches,    |
    |               |this procedure has no effect.                   |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Deletes the selected switch or the switch on    |
    |Delete         |which the cursor is located. Because switch file|
    |               |store only nondefault switches, deleting a      |
    |               |switch from the file causes the switch to assume|
    |               |a system-defined default value.                 |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Selects the first line of the switch file.      |
    |First_Child    |                                                |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Creates a command window and places in it the   |
    |Insert         |following command, where the parameter must be  |
    |               |specified to provide a switch and its value:    |
    |               |                                                |
    |               |     Insert ("[Processor.]  Switch := Value;"); |
    |               |                                                |
    |               |                                                |
    |               |Specifying a switch and a value for that switch |
    |               |and promoting the command inserts, or changes, a|
    |               |switch value. Multiple switches can be inserted |
    |               |simultaneously by separating them with          |
    |               |semicolons. This procedure uses the same format |
    |               |as an Options parameter.                        |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Selects the last line of the switch file.       |
    |Last_Child     |                                                |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Moves the value of a highlighted switch from one|
    |Move           |set of switches to the switch of the same name  |
    |               |in the set of switches on which the cursor is   |
    |               |located. If the selected switch and the cursor  |
    |               |are both in the same set of switches, this      |
    |               |procedure has no effect.                        |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Selects the next switch. If no switch is        |
    |Next           |selected, this procedure selects the switch on  |
    |               |which the cursor is located. If all switches are|
    |               |selected, this procedure produces an error.     |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Selects the switch on which the cursor is       |
    |Parent         |located. If the switch is already selected, this|
    |               |procedure selects all the switches in the set.  |
    |               |If all the switches are already selected, this  |
    |               |procedure has no effect.                        |
     ---------------------------------------------------------------- 
    |               |                                                |
    |Common.Object. |Selects the previous switch. If no switch is    |
    |Previous       |selected, this procedure selects the switch on  |
    |               |which the cursor is located. If all switches are|
    |               |selected, this procedure produces an error.     |
     ---------------------------------------------------------------- 




 @node !Commands.Switches.Associate

 procedure Associate (File     : File_Name := "<SELECTION>";
                      Library  : String    := "<IMAGE>";
                      Response : String    := "<PROFILE>");

 DESCRIPTION

 Associates the designated library switch file with the specified library.

 This procedure builds an association between a library switch file and a
 directory or world. The switches in the library switch file are used for
 all applicable operations within that directory or world. The
 association is by reference, which means that changes made to the library
 switch file have an immediate effect on subsequent operations or units in
 the associated directory or world.

 A library switch file must be explicitly associated with a directory or
 world to affect units within that directory or world. A single library
 switch file can be associated with several different directories or
 worlds. However, a directory or world can have only one library switch file
 associated with it. Thus, associating a library switch file to a directory
 or world dissociates any library switch file previously associated with
 that directory or world.

 Note that changes made to Format switches affect only Ada units created
 after the changes were made. Executing the command Library.Reformat_Image
 on a previously created Ada unit makes changes to Format switches affect
 that Ada unit.

 Owner access to the world containing the library and read access to the
 associated switch file are required to execute this procedure successfully.

 To check for the library switch file associated with a particular library,
 use the Associated function. To remove the association between a library
 and an associated library switch file, use the Dissociate procedure.

 Note that views and directories in views are automatically associated with
 the library switches contained in View_Name.State.Compiler_Switches. Thus,
 this procedure cannot be used to associate views and directories in
 views with any other library switch file.


 PARAMETERS

 File : File_Name := "<SELECTION>";

 Specifies the file to be associated with the directory or world. The default
 is the current selection.


 Library : String := "<IMAGE>";

 Specifies the directory or world with which to associate the library switch
 file. The default is the directory or world enclosing the current 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.


 EXAMPLES

 Assume that you have a library switch file called Library_Switches in your
 home world. You want to associate this switch file with your world
 !Users.Your_Username.Projects. When executed from a command window
 attached to !Users.Your_Username.Projects, the following command
 associates the switch file Library_Switches with that library:

   Switches.Associate
            (File     => "!Users.Your_Username.Library_Switches",
             Library  => "<IMAGE>",
             Response => "<PROFILE>");

 Any library switch file previously associated with your Project world is
 automatically dissociated.


 REFERENCES

 function Associated
 procedure Dissociate



 @node !Commands.Switches.Associated

 function Associated (Library : String := "<IMAGE>")
                                   return File_Name;

 DESCRIPTION

 Finds the associated library switch file for the specified directory or
 world.

 This function returns the name of the library switch file that is
 associated with the specified directory or world. If no library switch file
 has been associated with the directory or world, this function returns the
 null string.


 PARAMETERS

 Library : String := "<IMAGE>";

 Specifies the directory or world for which the associated library switch
 file is desired. The default is the directory or world enclosing the image.


 return File_Name;

 Returns the name of the library switch file associated with the directory
 or world. If no switch file is associated with the directory or world, it
 returns the null string.


 EXAMPLES

 Entering the following command in a command window attached to your home
 world returns the name of the library switch file associated with your home
 world:

   Io.Echo (Switches.Associated);

 The name of the associated library switch file, if one exists, is displayed
 in the message window.


 REFERENCES

 procedure Associate
 procedure Dissociate



 @node !Commands.Switches.Change

 procedure Change (Image : Value_Image := ">>SWITCH VALUE<<");

 DESCRIPTION

 Changes the value of the selected switch or the switch on which the cursor
 is located, if there is no selection.

 This procedure changes the value of a switch. The new switch value is
 provided as a string whose form depends on the type of switch.

 This command is generated in response to using the !Commands.Common.Edit
 procedure in a switch window. When generated by the Common.Edit command,
 the current value of the switch on which the cursor is located replaces
 the default parameter placeholder ">>SWITCH VALUE<<".

 Note that the switch file must be committed for the new switch value to
 take effect. If the switch file is a library switch file, it also must be
 associated with a directory or world to affect operations or units in
 that directory or world.

 To simultaneously change the values of multiple switches, use the Insert
 procedure. To change the values of switches from a location other than a
 window containing switches, use the Set procedure.


 PARAMETERS

 Image : Value_Image := ">>SWITCH VALUE<<";

 Specifies the new switch value. The default parameter placeholder ">>SWITCH
 VALUE<<" must be replaced or an error results.


 EXAMPLES

 Assume that you want to change the value of the Format.Line_Length from
 the default value (80) to 60. Placing the cursor on the Line_Length
 library switch and executing the Common.Edit command opens a command
 window containing the following command:

   Change ("80");

 Entering 60 for the switch value and executing the command changes the
 value of the Line_Length switch. To make this change take effect, commit
 the switch file using either the Common.Promote or the Common.Commit
 procedure.


 REFERENCES

 procedure Insert
 procedure Set



 @node !Commands.Switches.Composite_Name

 subtype Composite_Name is String;

 DESCRIPTION

 Defines a name that is the full (composite) name for a library or session
 switch.

 You can refer to a switch by its simple name or by its composite name. The
 simple name can be used when it is not ambiguous; otherwise, the composite
 name must be used. A composite name is composed of the processor name, a
 period, and the simple name.

 The processor name designates the group within the set of library or
 session switches to which that switch belongs. Within each processor
 group, there may be several switches that affect that particular area of
 the Environment.


 EXAMPLES

 The following is a composite name for a switch, in which Session is the
 processor name and Cursor_Bottom_Offset is the simple switch name:

   "Session.Cursor_Bottom_Offset"

 REFERENCES

 subtype Specification



 @node !Commands.Switches.Create

 procedure Create (File     : File_Name := ">>SWITCH FILE<<";
                   Category : Character := 'L';
                   Response : String    := "<PROFILE>");

 DESCRIPTION


 Creates a library or session switch file.

 This procedure creates a new switch file of the specified name and type. If
 the specified switch file already exists, a new version, containing the
 system-defined default values, is created. This new version overwrites the
 existing version.

 When switch files are first created, they are empty. An empty switch file is
 one in which all of the switch values are the system-defined default
 values. These values are "hard-wired" and are not read from any other
 switch file. These system-defined values are also used if no switch file
 exists. Thus, you need to create a switch file only if you want to edit a
 switch so that it uses a nondefault value.

 Note that the name of a session switch file must follow the naming
 convention Session_Name_Switches for it to affect that session. For
 example, the session switch file S_1_Switches affects the way the system
 behaves in session S_1.

 Library switch files must be associated explicitly with a directory or
 world to affect operations or units in that directory or world. To
 associate a library switch file, use the Associate procedure.

 Library switch files can also be created using the Define procedure.


 PARAMETERS

 File : File_Name := ">>SWITCH FILE<<";

 Specifies the name of the file to be created. The default parameter
 placeholder ">>SWITCH FILE<<" must be replaced or an error results.


 Category : Character := 'L';

 Specifies the kind of switch file to be created. The default is a library
 switch file (`L'). A session switch file is designated by `S'.


 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

 Creating a Library Switch File

 Assume that you have a world called !Users.Your_Username.Projects. When
 executed from this world, the following command creates a library switch
 file named Project_Switches in that world:

   Switches.Create (File     => "Project_Switches",
                    Category => 'L',
                    Response => "<PROFILE>");

 Initially, this switch file assumes the system-defined default value for
 each of the switches. To make Project_Switches affect operations in
 !Users.Your_Username.Projects, you need to explicitly associate it with
 that world using the Associate procedure.


 Creating a Session Switch File

 To create a session switch file named S_1_Switches, you can use the
 following command:

   Switches.Create (File     => "S_1_Switches",
                    Category => 'S',
                    Response => "<PROFILE>");

 The file, initally containing the default value for each of the switches,
 is created in your home world. The switches in this file affect operations
 when you are logged into session S_1.


 REFERENCES

 procedure Associate
 procedure Define



 @node !Commands.Switches.Default_File

 Default_File : constant File_Name := "";

 DESCRIPTION

 Defines a constant that represents the selected, or default, switch file.

 If there is no selection or if the selection is not a switch file, the
 constant represents the library switch file associated with the enclosing
 directory or world. If the enclosing directory or world does not have an
 associated switch file, the constant represents no switch file.



 @node !Commands.Switches.Define

 procedure Define (File     : File_Name := ">>SWITCH FILE<<";
                   Response : String    := "<PROFILE>");

 DESCRIPTION

 Creates a new library switch file.

 This procedure creates a library switch file of the specified name. If the
 specified library switch file already exists, a new version, containing the
 system-defined default values, is created. This new version overwrites the
 existing version.

 When library switch files are first created, they are empty. An empty switch
 file is one in which all the switches assume the system-defined default
 values. These values are "hard-wired" and are not read from any other
 switch file. These system-defined values are also used if no switch file
 exists. Thus, you need to create a library switch file only if you want
 to edit a switch so that it uses a nondefault value.

 Library switch files must be associated explicitly with a directory or
 world to affect operations or units in that directory or world. To
 associate a library switch file, use the Associate procedure.

 Library switch files can also be created using the Create procedure. To
 create a session switch file, you must use either the Create or the
 Edit_Session_Attributes procedure.


 PARAMETERS

 File : File_Name := ">>SWITCH FILE<<";

 Specifies the name of the switch file to be created. The default parameter
 placeholder ">>SWITCH FILE<<" must be replaced or an error results.


 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 library switch file named Library_Switches
 in the directory or world enclosing the current image:

   Switches.Define ("Library_Switches");

 To make the file affect operations in a particular library, you must
 explicitly associate it with that library using the Associate procedure.


 REFERENCES

 procedure Associate
 procedure Create
 procedure Edit_Session_Attributes



 @node !Commands.Switches.Display

 procedure Display (Names    : Composite_Name := "@.@";
                    File     : File_Name      := "<SWITCH>";
                    Response : String         := "<PROFILE>");

 DESCRIPTION

 Displays the specified set of switches from the designated switch file.

 This procedure lists the switches in the specified switch file that match
 the specified name. The name must be specified in the form of a composite
 name, containing the processor name (for example, Format), a period, and
 the simple name of the switch or switches (for example, Line_Length).
 Naming expressions such as wildcard characters can be used for the
 processor name and the simple name to specify multiple switches.

 Note that switch files actually store only the switches that have
 nondefault values. This procedure searches these switch files and,
 therefore, displays only switches with nondefault values that match the
 specified names. However, for some groups of switches, the entire group is
 written to the switch file when one switch has a nondefault value. Thus,
 this procedure may display switches with default values if they belong to
 a group for which one member has a nondefault value.

 The job display is sent to Current_Output (by default, an Environment
 output window). Errors are reported in log messages, which, by default,
 are also sent to the output window.

 Note that switches cannot be edited from the output window. To open a
 library switch file for editing, use the Edit procedure. To open a session
 switch file for editing, use the Edit_Session_Attributes procedure.


 PARAMETERS

 Names : Composite_Name := "@.@";

 Specifies the switches to be displayed from the switch file. The default is
 all switches.


 File : File_Name := "<SWITCH>";

 Specifies the switch file from which to display the switches. The default is
 the currently selected switch file or the library switch file associated
 with the directory or world enclosing the current 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.


 ERRORS

 If the default ("<SWITCH>") is used for the File parameter and no switch
 file is selected or the enclosing directory or world does not have an
 associated switch file, an error occurs.


 EXAMPLES



 Example 1: Displaying a Subset of the Switches

 The following command lists all the switches in S_1_Switches with
 nondefault values that have Profile as their processor name:

   Switches.Display (Names    => "Profile.@",
                     File     => "S_1_Switches",
                     Response => "<PROFILE>");

 The resulting display, sent to an Environment output window, is shown
 below:

   Contents of Switch File !USERS.JAF.S_1_SWITCHES'V(3)

   Processor       Switch        Type   Value
   =========  ================  ======  =====
    Profile.  Remote_Passwords  Object  <NIL>
    Profile.  Remote_Sessions   Object  <NIL>


 Example 2: Displaying All of the Nondefault Switches

 When executed from the library containing a switch file called
 Library_Switches, the following command displays all of the nondefault
 library switches in that file:

   Switches.Display ("@.@", "Library_Switches")

 The display, showing all of the specified switches, appears below. Note
 that all the switches with the prefix Semantics are included even though
 only Semantics.Ignore_Interface_Pragma has a nondefault value. This is
 an example of a group of switches that are saved and displayed as a group.

   Contents of Switch File !USERS.JAF.LIBRARY_SWITCHES'V(4)

   Processor               Switch              Type    Value
   ==========  =============================  =======  =====
         Ftp.  Auto_Login                     Boolean  TRUE
      Format.  Alignment_Threshold            Integer  15
   Semantics.  Closed_Private_Part            Boolean  FALSE
      Format.  Consistent_Breaking            Integer  0
   Semantics.  Flag_Inevitable_Exceptions     Boolean  FALSE
   Semantics.  Ignore_Interface_Pragmas       Boolean  TRUE
   Semantics.  Ignore_Minor_Errors            Boolean  FALSE
   Semantics.  Ignore_Unsupported_Rep_Specs   Boolean  FALSE
   Semantics.  Reject_Bad_Lrm_Pragmas         Boolean  FALSE
   Semantics.  Reject_Bad_Rational_Pragmas    Boolean  FALSE
   Semantics.  Reject_Inevitable_Exceptions   Boolean  FALSE
   Semantics.  Reject_Undefined_Pragmas       Boolean  FALSE


 @node !Commands.Switches.Dissociate

 procedure Dissociate (Library  : String := "<IMAGE>";
                       Response : String := "<PROFILE>");

 DESCRIPTION

 Removes the association between a directory or world and a library switch
 file.

 This procedure dissociates a library switch file from its previously
 associated directory or world. Switches in the previously associated
 switch file no longer affect operations or units in the specified directory
 or world. If the directory or world does not have an associated switch
 file, the procedure has no effect.

 This procedure is the opposite of the Associate procedure.

 To check for the switch file associated with a particular library, use the
 Associated function.

 Note that views and directories in views are automatically associated with
 the library switches contained in View_Name.State.Compiler_Switches. This
 switch-file association cannot be removed.


 PARAMETERS

 Library : String := "<IMAGE>";

 Specifies the directory or world from which to dissociate the associated
 library switch file. The default is the directory or world enclosing the
 current 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.


 EXAMPLES

 The following command removes the association between the library
 !Users.Robinson and its currently associated library switch file:

   Switches.Dissociate ("!Users.Robinson");

 REFERENCES

 procedure Associate
 function Associated



 @node !Commands.Switches.Edit

 procedure Edit (File : File_Name := "<SWITCH>");

 DESCRIPTION

 Creates a window in which the set of switches from the specified library
 switch file can be edited.

 The procedure creates a window and displays in it the set of switches from
 the specified library switch file. If a window already exists with those
 switches in it, the window is reused. From the window, the switches can be
 edited with many operations from package !Commands.Common that apply to
 the window (see the introduction to this package for details).

 By default, this procedure displays the set of switches associated with
 the directory or world enclosing the current image. If a switch file is
 specified that does not exist, a library switch file of that name is
 created, associated with the directory or world enclosing the current
 image, and displayed. If there is no associated switch file and no switch
 file is specified, a switch file of the name Library_Switches is created,
 associated with the directory or world enclosing the current image, and
 displayed.

 This procedure creates a new window for each set of switches to be edited.
 To reuse the same window to edit a different set of switches, use the
 Visit procedure.

 To open session switch files for editing, use the Edit_Session_Attributes
 procedure.


 PARAMETERS

 File : File_Name := "<SWITCH>";

 Specifies the switch file in which switches are to be edited. The default is
 the currently selected switch file or the switch file associated with the
 directory or world enclosing the current image.


 EXAMPLES

 To open the set of library switches associated with your home world for
 editing, you can enter the following command from a command window
 attached to your home world:

   Switches.Edit (File => "<SWITCH>");

 The command creates a window containing the library switch file associated
 with the enclosing directory or world (in this case, your home world). If
 no library switch file is associated with your home world, the procedure
 creates and associates a new library switch file with your home world.
 From this window, you can edit your switches using commands from package
 Common (see the introduction to this package).


 REFERENCES

 procedure Edit_Session_Attributes
 procedure Visit



 @node !Commands.Switches.Edit_Session_Attributes

 procedure Edit_Session_Attributes;

 DESCRIPTION

 Creates a window in which the session switches for the current session can
 be edited.

 This procedure creates a window and displays the set of session switches
 for the current session. If no session switch file exists, one is created
 and displayed. If a window containing the current session switches already
 exists, the window is reused. From the window, the switches can be edited
 with many operations from package !Commands.Common that apply to the
 window (see the introduction to this package for details).

 There is only one set of session switches for a session. For this reason,
 you do not need to specify the name of a switch file to this procedure. The
 procedure always opens the switch file for the current session. The switch
 file for the current session is designated by the filename convention
 Session_Name_Switches.

 This procedure creates a new window for each set of switches to be edited.
 To reuse the same window but edit a different set of switches in that
 window, see the Visit procedure.

 To display and edit library switch files, see the Edit procedure.


 REFERENCES

 procedure Edit
 procedure Visit



 @node !Commands.Switches.File_Name

 subtype File_Name is String;

 DESCRIPTION

 Defines a name of a switch file.

 This name can use any of the wildcards, indirect files, context prefixes, or
 attributes as long as it is unambiguous. The name can specify a switch
 file, directory, or world. When the name specifies a directory or world, the
 switch file associated with that directory or world is used.

 For further information about wildcards, indirect files, context prefixes,
 and attributes, see the Parameter-Value Conventions tabbed section in
 the Reference Summary (RS) book.



 @node !Commands.Switches.Insert

 procedure Insert (Spec : Specification := ">>SWITCHES<<");

 DESCRIPTION

 Inserts one or more switches and switch values into the current set of
 switches.

 This procedure appears in a command window in response to the !Commands-
 .Common.Object.Insert procedure. This procedure inserts (changes) one or
 more switches in the current set of switches. Multiple switches can be
 inserted with this procedure by separating the switches with semicolons.
 Changes to the switch values must be explicitly committed to take effect.

 To change the value of a single switch, you can also use the Change
 procedure. To change the value of a switch without opening the switch file
 for editing, you can use the Set procedure.


 PARAMETERS

 Spec : Specification := ">>SWITCHES<<";

 Specifies the switch or switches and their new values to be inserted into
 the switch file. The default parameter placeholder ">>SWITCHES<<" must be
 replaced or an error results.


 EXAMPLES

 The following command inserts the value "50" for the
 Session.Cursor_Bottom_Offset switch:

   Switches.Insert ("Session.Cursor_Bottom_Offset:="50");

 To insert a value of type switch, you must enclose the value in two sets
 of double quotation marks. The command inserts the username "Reyes" into
 the Ftp.Username switch:

   Switches.Insert ("Ftp.Account:=""Reyes""");

 Notice that the assignment of the value to the switch name is also
 enclosed in double quotation marks, resulting in a total of three sets of
 quotation marks.


 REFERENCES

 procedure Change
 procedure Set



 @node !Commands.Switches.Of_Library

 Of_Library : constant File_Name := "<SWITCH>";

 DESCRIPTION

 Defines a local constant for the name of the switch file associated with the
 world or directory enclosing the current image.

 If a switch file is selected, that switch file is referenced. If no library
 switch file is associated or selected, one is created.

 This constant can be used in place of an explicit filename in commands that
 require the name of a switch file as a parameter.


 EXAMPLES

 The following command uses the Of_Library constant as the value for the
 File parameter to specify that the value of the Line_Length switch is to
 be changed in the library switch file associated with the current library:

   Switches.Set (Spec     => "Format.Line_Length:=75",
                 File     => "Session.Of_Library",
                 Response => "<PROFILE>");

 REFERENCES

 constant Of_Session

                                                                           

 @node !Commands.Switches.Of_Session

 Of_Session : constant File_Name := "<SESSION>";
                                           

 DESCRIPTION

 Defines a constant for the name of the switch file associated with the
 current session.

 If no switch file exists for the current session, one is created.

 This constant can be used in place of an explicit filename in commands that
 require a filename as a parameter.


 EXAMPLES

 The following command uses the Of_Session constant as the value for the
 File parameter to specify that the value of the Beep_On_Errors switch is
 to be changed in the switch file for the current session:

   Switches.Set (Spec     => "Session.Beep_On_Errors:=False",
                 File     => "Switches.Of_Session",
                 Response => "<PROFILE>");

 REFERENCES

 constant Of_Library



 @node !Commands.Switches.Set

 procedure Set (Spec     : Specification := ">>SWITCHES<<";
                File     : File_Name     := "<SWITCH>";
                Response : String        := "<PROFILE>");

 DESCRIPTION

 Sets the specified switches and values in the specified switch file.

 This procedure changes the value of one or more switches in the specified
 switch file. The specification defines both the switches to be changed and
 the new values for those switches. If the specified switch file does not
 exist, one is created and the specified switch value is set. After changing
 the value of the switch, this procedure commits the change to the switch
 file.

 To change the values of multiple switches from a window containing the set
 of switches you want to edit, you can also use the Insert procedure. To
 change the value of a single switch, you can use the Change procedure.


 PARAMETERS

 Spec : Specification := ">>SWITCHES<<";

 Specifies the switches and their new values to be changed in the switch
 file. The default parameter placeholder ">>SWITCHES<<" must be replaced or
 an error results.


 File : File_Name := "<SWITCH>";

 Specifies the switch file to be changed. The default is the selected switch
 file or the library switch file associated with the enclosing directory or
 world.


 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 have a library switch file called Library_Switch in your
 home world. The following command changes the value of the
 Format.Alignment_Threshold library switch in that file from its current
 value to "10":

   Switches.Set (Spec     => "Format.Alignment_Threshold:=10",
                 File     => "!Users.Your_Username.Library_Switches",
                 Response => "<PROFILE>");

 To set a value of the string type, you must enclose the value in two sets
 of double quotation marks. The following command sets the value of the
 Session.Ftp_Username switch in the set of switches for session S_1 to
 "Reyes":

   Switches.Set (Spec     => "Session_Ftp.Username:=""Reyes""",
                 File     => "S_1_Switches",
                 Response => "<PROFILE>");

 Notice that the assignment of the value to the switch name is also
 enclosed in double quotation marks, resulting in a total of three sets of
 quotation marks.


 REFERENCES

 procedure Change
 procedure Insert



 @node !Commands.Switches.Specification

 subtype Specification is String;

 DESCRIPTION

 Defines a string that specifies both a switch and a value for the switch.

 This subtype is used in the Insert and Set procedures to specify both a
 switch to be changed and the new value for the switch. The string takes
 the form of the Options parameter. The option name is the Composite_Name
 or simple name of the switch. The value is the Value_Image of the switch.


 EXAMPLES

 The following specification assigns an integer value to the
 Cursor_Bottom_Offset switch:

   "Cursor_Bottom_Offset := 50"

 The following specification assigns a Boolean value to the Image_Fill_Mode
 switch:

   "Image_Fill_Mode := True"

 The following specification assigns values to two switches:

   "Cursor_Bottom_Offset := 50; Image_Fill_Mode := True"

 Note that to assign a value of type string, you must enclose the value in
 two sets of double quotation marks, as in the following specification:

   "Ftp.Username := ""Reyes"""

 REFERENCES

 subtype Composite_Name
 subtype Value_Image



 @node !Commands.Switches.Value_Image

 subtype Value_Image is String;

 DESCRIPTION

 Defines a string that specifies a value for a switch.

 This subtype is used in the Insert and Set procedures as part of the
 Specification subtype to specify a new value for a switch. It is also used
 in the Change procedure independent of a specification to specify a new
 value for the switch on which the cursor is located.

 The form of the string depends on the type of the switch being changed.


 EXAMPLES

 The following command changes the value of the Cursor_Bottom_Offset
 switch. In this specification to change the switch, the Value_Image is 50:

   Set ("Cursor_Bottom_Offset := 50");

 The following command uses the Value_Image of True without a specification
 to change the value of the switch on which the cursor is located:

   Change ("True");

 REFERENCES

 subtype Specification



 @node !Commands.Switches.Visit

 procedure Visit (File : File_Name := "<SWITCH>");

 DESCRIPTION

 Brings the specified switch file into an existing window where the switches
 can be edited.

 This procedure uses an existing switch window for editing switches and
 displays the set of switches from the specified file in that window. If a
 window does not already exist for editing switches, one is created. From
 the window, the switches can be edited with many operations from package
 !Commands.Common that apply to the window (see the introduction to this
 package for details). The switch file previously in the window is
 abandoned; any changes made to that file since the last commit operation
 are lost.

 By default, this procedure brings up the library switch file associated
 with the library enclosing the current image. If no switch file is specified
 and none is associated with the current library, this procedure creates
 a library switch file called Library_Switches, associates it with the
 current library, and opens it for editing.

 If a session or library switch file is specified that does not exist, one of
 that name is automatically created. If it is a library switch file, it also
 is associated with the current library.

 This procedure does not create a new window for each set of switches to be
 edited. To create a new window in which to edit a set of switches, see
 the Edit and Edit_Session_Attributes procedures.


 PARAMETERS

 File : File_Name := "<SWITCH>";

 Specifies the switch file in which the switches are to be edited. The
 default is the currently selected switch file or the library switch file
 associated with the directory or world enclosing the current image.


 REFERENCES

 procedure Edit
 procedure Edit_Session_Attributes



 @node !Commands.Switches.Write

 procedure Write (File : File_Name := ">>SWITCH FILE<<");

 DESCRIPTION

 Writes the switches in the current window into the specified switch file.

 This procedure saves the switches that are being edited into a specified
 file. If the specified switch file does not exist, this procedure creates a
 switch file with the specified name in the directory or world enclosing the
 current image.

 This procedure is useful for copying an entire set of switches to another
 switch file. To save a switch file to a file of the current name (rather than
 writing it to a different switch file), you can use the
 !Commands.Common.Commit or !Commands.Common.Promote procedure.


 PARAMETERS

 File : File_Name := ">>SWITCH FILE<<";

 Specifies the file into which to write the switches. The default parameter
 placeholder ">>SWITCH FILE<<" must be replaced or an error results.



 @node !Tools.Xref_Utility'Spec_View.Units.Commands.Xref

 Package Xref provides commands for checking dependencies between
 constructs in Ada units. These commands search the specified units for
 constructs of user-determined types and list the units that either
 reference or are referenced by those constructs, depending on the Xref
 operation performed. Commands from package Xref are appropriate for both
 interactive and programmatic use.


 RESOURCES IN PACKAGE XREF

 Package Xref contains two procedures for determining cross-references
 between constructs of user-determined types in the Ada unit or units
 specified:

 *  Used_By: Generates a list of the units that reference any construct of
    one of the indicated types.

 *  Uses: Generates a list of the units that contain the defining occurrence
    of any construct of one of the indicated types.

 The Used_By and Uses procedures provide analogous functions to the
 interactive facilities, Ada.Show_Usage and Common.Definition, respectively.
 However, whereas Xref facilities operate on multiple constructs within
 one or more units, Show_Usage and Definition operate only on the single
 construct specified. See Editing Specific Types (EST), package Ada, for
 further information about the Show_Usage procedure. See Editing Images
 (EI), package Common, for further information about the Definition
 procedure.


 KEY CONCEPTS FOR PACKAGE XREF

 In the process of analyzing, maintaining, or debugging a program, you
 often need to know where and how various program elements are used or
 defined. This is especially true when editing units using incremental
 operations. Incremental operations, discussed in EST, Ada Images,
 require that changes be upwardly compatible and, therefore, require a
 knowledge of the relationships between Ada units.

 The commands in package Xref provide a batch analysis of constructs within
 specified units. They search the specified units and identify each construct
 that matches one of the indicated types. The types of constructs
 recognized by these procedures include functions, procedures, packages,
 and generics. The procedures also recognize entries, exceptions, labels,
 record components, constants, parameters, types, and variables.
 Depending on the Xref procedure used, the units that reference or that are
 referenced by the indicated constructs are reported. The job report is
 directed to Current_Output, which is, by default, an Environment output
 window.

 The following subsections provide information about reading the Xref
 report and a sample program for use with the examples in the reference
 entries.


 Reading the Xref Report

 The format for the Xref report is the same whether you execute the Uses or
 the Used_By procedure. That is, both procedures produce a report that
 lists:

 *  The simple names of the constructs identified

 *  The unit and line number in which each construct is defined

 *  The unit, line number, and way in which each construct is used or
    referenced

 The only difference between the Uses and Used_By reports is the column in
 which the unit or units you specified are listed. For the Used_By
 procedure, all of the identified constructs are defined in one of the units
 you specified. For the Uses procedure, all of the identified constructs are
 referenced in (or used by) one of the units you specified.

 A sample of the report produced by a Uses operation is shown in Figure 1.

 ITEM                   DEFINED IN              IS REFERRED TO BY

 NEW_LINE'2             TEXT_IO[23] 77   .FORMATTER.PRINT_HEADER(U)[12] 25
 PUT_LINE'2             TEXT_IO[24] 135  .FORMATTER.PRINT_HEADER(U)[12] 28
                                             .PRINT_TEAM_STATS(U)[14]   50 59

                  FULL NAMES OF "IS REFERRED TO BY" UNITS

   12       !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_HEADER
   14       !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_TEAM_STATS

                  FULL NAMES OF "DEFINED IN" UNITS

   23       !IO.TEXT_IO.NEW_LINE'2
   24       !IO.TEXT_IO.PUT_LINE'2                                   

   Figure 1   Sample Xref Report


 For this example, the Uses procedure was executed on a package called
 Formatter, which includes declarations for procedures Print_Header and
 Print_Team_Statistics (see "Sample Program for Examples," below). In the
 resulting Xref report:

 *  The "Item" column indicates that the Uses procedure has identified
    procedure New_Line as one of the constructs named in package Formatter.
    The '2 indicates that more than one declaration exists for New_Line and
    that Formatter references the second of these.

 *  The "Defined In" column indicates that procedure New_Line is defined in
    package Text_Io. The number in brackets ( [23] ) refers to the entry
    for the unit's fully qualified pathname (!Io.Text_Io.New_Line'2) in the
    "Full Names of `Defined In' Units" section below. The final number
    indicates the line number (77) in Text_Io in which New_Line is
    defined.

 *  The "Is Referred to By" column indicates that procedure New_Line is
    referenced by procedure Print_Header in package Formatter. The
    one-letter flag enclosed in parentheses (U) indicates that New_Line is
    directly used by Print_Header (see Table 1 for the possible flags and
    their meanings). The number in brackets ( [12] ) refers to the entry for
    the corresponding fully qualified pathname (!Users-
    .Your_Username.Baseball_System.Formatter.Print_Header) in the "Full
    Names of `Is Referred to By' Units" section below. The final number (25)
    indicates the line number in Formatter in which New_Line is referenced.

                      Table 1    Xref Flag Definitions
               -------------------------------------------- 
              |  |               |                         |
              |Fl|  Stands For   |          Means          |
              |ag|               |                         |
               -------------------------------------------- 
              |  |               |                         |
              |  |Used           |Object is read from or is|
              |U |               |an in parameter          |
               -------------------------------------------- 
              |  |               |                         |
              |  |Set            |Object is written into or|
              |S |               |is an out parameter      |
               -------------------------------------------- 
              |  |               |                         |
              |  |Both used and  |Object is an in out      |
              |B |set            |parameter                |
               -------------------------------------------- 
              |  |               |                         |
              |  |Used through   |Object is read through   |
              |UT|               |pointer                  |
               -------------------------------------------- 
              |  |               |                         |
              |  |Set through    |Object is written through|
              |ST|               |pointer                  |
               -------------------------------------------- 
              |  |               |                         |
              |  |Both used and  |Object is an in out      |
              |BT|set through    |parameter through pointer|
               -------------------------------------------- 




 Sample Program for Examples

 The examples in the reference entries of this package use the
 Baseball_Statistics program included below. When looking at the
 reference-entry examples, you may want to refer back to this section for
 details about the relationship between units.

 The Baseball_Statistics program uses procedures from three packages:
 Formatter, Data_Inputter, and Baseball. The structure of the program is
 depicted in Figure 2.

                    Baseball_Statistics (proc)

                         /      |      \
                        /       |       \
                       /        |        \
                                |
            Formatter (pkg)     |      Data_Inputter (pkg)
                                |
                       \        |        /
                        \       |       /
                         \      |      /

                          Baseball (pkg)

   Figure 2    Structure of Baseball_Statistics Program


 In short, Baseball_Statistics first calls Data_Inputter. Procedures in
 Data_Inputter request the name, number of times at bat, number of hits,
 and number of runs batted in for each player. This information is passed
 to procedures in package Baseball that calculate the statistics for each
 player and the combined statistics for the team. Finally, procedures from
 package Formatter display the statistics.

 The portions of the source code relevant to the reference-entry examples
 are included below.


 Baseball_Statistics'Body

   with Baseball, Data_Inputter, Formatter;
   procedure Baseball_Statistics is
       Team_Sums       : Baseball.Total_Players_Statistics;
       Team_Statistics : Baseball.Team_Statistics;
       Player_Iterator : Baseball.Team_Iterator;

   begin

       . . .

       Formatter.Print_Header;
       Baseball.Initialize (Player_Iterator, Team_Statistics);

       while not Baseball.Is_Done (Player_Iterator) loop
           Formatter.Print_Player_Stats
              (Baseball.Value_Of (Player_Iterator));
           Baseball.Get_Next (Player_Iterator);
       end loop;

       Formatter.Print_Team_Stats (Team_Sums);

   end Baseball_Statistics;


 Formatter'Spec

   with Baseball;
   package Formatter is
       procedure Print_Header;
       procedure Print_Player_Stats
                    (Statistics : Baseball.Player_Statistics);
       procedure Print_Team_Stats
                    (Statistics : Baseball.
                                     Total_Players_Statistics);
   end Formatter;


 Formatter'Body

   with Text_Io;
   package body Formatter is

       package Tio renames Text_Io;
       package Nat_Io is new Tio.Integer_Io (Natural);
       package Flt_Io is new Tio.Float_Io (Baseball.Percent);

       procedure Put_Statistic_Values
                    (At_Bat     : Baseball.Times_At_Bat;
                     Hits       : Baseball.Number_Hits;
                     Runs       : Baseball.Runs_Batted_In;
                     Percentage : Baseball.Percent) is
       begin
           Nat_Io.Put (At_Bat, 6);
           Nat_Io.Put (Hits, 8);
           Nat_Io.Put (Runs, 7);
           Tio.Put ("     ");
           Flt_Io.Put (Percentage, Fore => 0, Aft => 3, Exp => 0);
       end Put_Statistic_Values;

       procedure Print_Header is
       begin
           Tio.New_Line;
           Tio.Put_Line ("Name               " &
                         "     ab       h     rbi      pct");
           Tio.Put_Line ("-----------------------------" &
                         "-------------------------------");
       end Print_Header;


       procedure Print_Player_Stats
                    (Statistics : Baseball.Player_Statistics) is
       begin
           Tio.Put (String (Statistics.The_Name));
           Put_Statistic_Values (Statistics.The_Times_At_Bat,
                                 Statistics.The_Number_Hits,
                                 Statistics.The_Runs_Batted_In,
                                 Statistics.The_Percentage);
           Tio.New_Line;
       end Print_Player_Stats;


       procedure Print_Team_Stats
                    (Statistics : Baseball.
                                     Total_Players_Statistics) is
       begin
           Tio.Put_Line ("------------------------------" &
                         "------------------------------");
           Tio.Put ("Totals              ");
           Put_Statistic_Values (Statistics.Total_Times_At_Bat,
                                 Statistics.Total_Number_Hits,
                                 Statistics.Total_Runs_Batted_In,
                                 Statistics.Total_Percentage);
           Tio.New_Line;
           Tio.Put_Line ("------------------------------" &
                         "------------------------------");

       end Print_Team_Stats;

   end Formatter;


 @node !Tools.Xref_Utility'Spec_View.Units.Commands.Xref.Used_By

 procedure Used_By
            (List_Of_Names           : String  := "<IMAGE>";
             Do_Functions            : Boolean := True;
             Do_Generics             : Boolean := True;
             Do_Procedures           : Boolean := True;
             Do_Attributes           : Boolean := False;
             Do_Record_Components    : Boolean := False;
             Do_Constants            : Boolean := False;
             Do_Entries              : Boolean := False;
             Do_Exceptions           : Boolean := False;
             Do_Labels               : Boolean := False;
             Do_Packages             : Boolean := False;
             Do_Parameters           : Boolean := False;
             Do_Pragmas              : Boolean := False;
             Do_Task_Bodies          : Boolean := True;
             Do_Types                : Boolean := False;
             Do_Variables            : Boolean := False;
             Exclude_References_From : String  := "";
             List_File_Name          : String  := "");
                          

 DESCRIPTION

 Produces a list of the Ada units that reference particular types of
 constructs in the specified unit or units.

 This procedure checks each of the Ada units specified in the List_Of_Names
 parameter. From these units, it identifies each construct that matches one
 of the types specified. Constructs are specified by entering the value True
 for the appropriate Do_xxx parameter, where xxx is a type of construct.
 Each construct that has at least one reference to it is included in the
 output. All references to those constructs are included.

 For each construct, the procedure lists:

 *  The simple name of the construct.

 *  The unit and line number in which the construct is defined. (This unit
    will always be one of those specified in the List_Of_Names parameter.)

 *  The unit, line number, and way in which the construct is referred to or
    used.

 The job report is sent to Current_Output (by default, an Environment
 output window) unless a filename is specified in the List_File_Name
 parameter. For information about reading the job report, see "Reading
 the Xref Report" in the introduction to this package.

 By default, all the units that depend on the specified unit(s) and
 transitively all the units that depend on those units are searched for
 references to the identified constructs. An Ada unit can be excluded from
 the search for references by naming it in the Exclude_Reference_To
 parameter.

 This procedure is useful for determining the impact of changing a unit or
 particular constructs within a unit. To check for the units that
 reference a single construct (rather than all the constructs of a given
 type), use the Ada.Show_Usage procedure (see EST, package Ada or Ada
 Images). To check for the units that depend on a specified unit as a whole
 without taking particular constructs into consideration, use the
 Compilation.Dependents procedure (see package Compilation in this book).


 PARAMETERS

 List_Of_Names : String := "<IMAGE>";

 Specifies the list of Ada units for which a cross-reference is to be built.
 The default is the currently selected unit or, if no selection exists,
 the unit in the current image. Multiple units can be specified using
 wildcards, context characters, set notation, indirect files, and
 attributes. For subsystems, the value of this parameter must be a spec
 view (see the Project Management (PM) book for information on subsystems).


 Do_Functions : Boolean := True;

 Specifies whether uses of function definitions will be included in the
 cross-reference.


 Do_Generics : Boolean := True;

 Specifies whether uses of generic definitions will be included in the cross-
 reference.


 Do_Procedures : Boolean := True;

 Specifies whether procedure definitions will be included in the
 cross-reference.


 Do_Attributes : Boolean := False;

 This parameter has no effect.


 Do_Record_Components : Boolean := False;

 Specifies whether all record-component definitions will be included in the
 cross-reference.


 Do_Constants : Boolean := False;

 Specifies whether constants will be included in the cross-reference.


 Do_Entries : Boolean := False;

 Specifies whether entry definitions will be included in the cross-reference.


 Do_Exceptions : Boolean := False;

 Specifies whether uses of exception names will be included in the
 cross-reference.


 Do_Labels : Boolean := False;

 Specifies whether label definitions will be included in the cross-reference.


 Do_Packages : Boolean := False;

 Specifies whether package definitions will be included in the
 cross-reference.


 Do_Parameters : Boolean := False;

 Specifies whether uses of parameters will be included in the
 cross-reference.


 Do_Pragmas : Boolean := False;

 This parameter has no effect.


 Do_Task_Bodies : Boolean := True;

 This parameter has no effect.


 Do_Types : Boolean := False;

 Specifies whether all type definitions will be included in the
 cross-reference.


 Do_Variables : Boolean := False;

 Specifies whether uses of variables will be included in the
 cross-reference.


 Exclude_References_From : String := "";

 Specifies the Ada units that are not to be searched for references to the
 indicated constructs. By default, all installed or coded Ada units in the
 entire library hierarchy are searched.


 List_File_Name : String := "";

 Specifies the name of the file in which to write the output. By default,
 output is directed to Current_Output, which is, by default, an
 Environment output window. This parameter does not control where to write
 errors reported in log messages.


 RESTRICTIONS

 The Ada units specified in the List_Of_Names parameter must be in the
 installed or coded state. Similarly, only installed or coded Ada units
 will be checked to see if they reference the specified constructs.


 EXAMPLES

 Consider the Baseball_Statistics program described in the introduction to
 this package. Suppose you want to know which units use constructs defined
 in package Formatter. You want to know not only the names of the units,
 but also the constructs that they reference and the line numbers of both
 the definition and usage.

 By executing the following command, you can cause the Environment to
 identify constructs of the default types (functions, generics, and
 procedures) from Formatter and determine the units that reference those
 constructs:

   Xref.Used_By ("Formatter'Spec");

 The resulting report is displayed in an Environment output window, as
 shown below:

 ITEM                 DEFINED IN              IS REFERRED TO BY

 PRINT_HEADER         FORMATTER[4]4     .BASEBALL_STATISTICS(U)[11]30
 PRINT_PLAYER_STATS   FORMATTER[5]5     .BASEBALL_STATISTICS(U)[11]34
 PRINT_TEAM_STATS     FORMATTER[6]7     .BASEBALL_STATISTICS(U)[11]39


               FULL NAMES OF "IS REFERRED TO BY" UNITS

   11      !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.BASEBALL_STATISTICS


               FULL NAMES OF "DEFINED IN" UNITS

   4    !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_HEADER
   5    !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_PLAYER_STATS
   6    !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_TEAM_STATS

 This display shows that several constructs defined in package Formatter are
 used by procedure Baseball_Statistics.

 Looking at the entry for Print_Header, you can see that procedure
 Print_Header is used by procedure Baseball_Statistics. The numbers after
 Formatter in the "Defined In" column indicate that the full pathname of
 Print_Header is given in entry 4 below and that Print_Header is defined on
 line 4 of package Formatter. Similarly, the numbers in the "Is Referred to
 By" column indicate that the full pathname of Baseball_Statistics is given
 in entry 11 below and that Baseball_Statistics references Print_Header on
 line 30. The U flag in parentheses indicates that Print_Header is directly
 used or read by Baseball_Statistics.

 For further information about reading the job report, see "Reading the
 Xref Report" in the introduction to this package.


 REFERENCES

 procedure Compilation.Dependents
 procedure !Commands.Ada.Show_Usage



 @node !Tools.Xref_Utility'Spec_View.Units.Commands.Xref.Uses

 procedure Uses
          (List_Of_Names             : String  := "<IMAGE>";
           Visible_Declarations_Only : Boolean := True
           Do_Functions              : Boolean := True;
           Do_Generics               : Boolean := True;
           Do_Procedures             : Boolean := True;
           Do_Attributes             : Boolean := False;
           Do_Record_Components      : Boolean := False;
           Do_Constants              : Boolean := False;
           Do_Entries                : Boolean := False;
           Do_Exceptions             : Boolean := False;
           Do_Labels                 : Boolean := False;
           Do_Packages               : Boolean := False;
           Do_Parameters             : Boolean := False;
           Do_Pragmas                : Boolean := False;
           Do_Task_Bodies            : Boolean := True;
           Do_Types                  : Boolean := False;
           Do_Variables              : Boolean := False;
           Exclude_References_To     : String  := "";
           Only_References_To        : String  := "";
           List_File_Name            : String  := "");

 DESCRIPTION

 Produces a list of the Ada units that contain the defining occurrence of
 particular constructs, identified by type, that are used in the unit or
 units specified by the user.

 This procedure checks each of the Ada units specified in the List_Of_Names
 parameter. From these units, it identifies each construct that matches
 one of the types specified. Constructs are specified by entering the value
 True for the appropriate Do_xxx parameter, where xxx is a type of
 construct. Each construct that has at least one reference to it is
 included in the output.

 For each construct, the procedure lists:

 *  The simple name of the construct.

 *  The unit and line number in which the construct is defined.

 *  The unit, line number, and way in which the construct is referred to or
    used. (This unit is always one of those specified in the List_Of_Names
    parameter.)

 The job report is sent to Current_Output (by default, an Environment
 output window) unless a filename is specified in the List_File_Name
 parameter. For information about reading the job report, see "Reading
 the Xref Report" in the introduction to this package.

 By default, all the units that are withed by the specified unit(s) and
 transitively all the units those units with are searched. An Ada unit can
 be excluded from the search for definitions by naming it in the
 Exclude_References_To parameter. Conversely, the set of units searched
 for definitions can be limited by naming units to be searched in the
 Only_References_To parameter. The Exclude_References_To and
 Only_References_To parameters are mutually exclusive.

 To check for the defining occurrence of a single construct (rather than all
 the constructs of a given type), you can use the Common.Definition
 procedure. See Editing Images (EI), package Common, or Editing Specific
 Types (EST), Ada Images, for details.


 PARAMETERS

 List_Of_Names : String := "<IMAGE>";

 Specifies the list of Ada units for which a cross-reference is to be built.
 The default is the currently selected unit or, if no selection exists, the
 unit in the current image. Multiple units can be specified using wildcards,
 context characters, set notation, indirect files, and attributes.


 Visible_Declarations_Only : Boolean := True;

 Specifies that only declarations that are exported will be included in the
 cross-reference.


 Do_Functions : Boolean := True;

 Specifies whether uses of functions will be included in the
 cross-reference.


 Do_Generics : Boolean := True;

 Specifies whether generic instantiations will be included in the
 cross-reference.


 Do_Procedures : Boolean := True;

 Specifies whether all procedures called will be included in the
 cross-reference.


 Do_Attributes : Boolean := False;

 This parameter has no effect.


 Do_Record_Components : Boolean := False;

 Specifies whether all record components used will be included in the cross-
 reference.


 Do_Constants : Boolean := False;

 Specifies whether all constants used will be included in the
 cross-reference.


 Do_Entries : Boolean := False;

 Specifies whether all entries used will be included in the cross-reference.


 Do_Exceptions : Boolean := False;

 Specifies whether uses of exception names will be included in the
 cross-reference.


 Do_Labels : Boolean := False;

 Specifies whether all labels used will be included in the cross-reference.


 Do_Packages : Boolean := False;

 Specifies whether all packages used will be included in the
 cross-reference.


 Do_Parameters : Boolean := False;

 Specifies whether all parameters used will be included in the
 cross-reference.


 Do_Pragmas : Boolean := False;

 This parameter has no effect.


 Do_Task_Bodies : Boolean := True;

 This parameter has no effect.


 Do_Types : Boolean := False;

 Specifies whether all types used will be included in the cross-reference.


 Do_Variables : Boolean := False;

 Specifies whether all variables used will be included in the
 cross-reference.


 Exclude_References_To : String := "";

 Specifies the Ada units that are not to be searched for the definitions of
 constructs. This parameter cannot be used if the Only_References_To
 parameter has a nondefault value. By default, all installed or coded Ada
 units in the entire library hierarchy are searched.


 Only_References_To : String := "";

 Specifies the Ada unit or units that are the only ones to be searched for
 the definitions of constructs. This parameter cannot be used if the
 Exclude_References_To parameter has a nondefault value. By default, all
 installed or coded Ada units in the entire library hierarchy are searched.


 List_File_Name : String := "";

 Specifies the name of the file in which to write the output. By default,
 output is directed to Current_Output, which is, by default, an Environment
 output window. This parameter does not control the location to which
 errors indicated in log messages are written.


 RESTRICTIONS

 The Ada units specified in the List_Of_Names parameter must be in the
 installed or coded state. Similarly, only installed or coded Ada units
 will be checked to see if they contain the definition of the specified
 constructs.


 EXAMPLES

 Consider the Baseball_Statistics program described in the introduction to
 this package. Suppose you want to know which units are referenced by or
 used in package Formatter. You want to know not only the names of the
 units, but also the constructs that use them and the line numbers of
 both the definition and usage.

 By executing the following command, you can cause the Environment to
 identify constructs of the default types (functions, generics, and
 procedures) from Formatter and determine the units in which those
 constructs are defined:

   Xref.Uses ("!Users.Your_Username.Baseball_System.Formatter")

 The resulting report is displayed in an Environment output window, as
 shown below:

 ITEM                DEFINED IN              IS REFERRED TO BY

 FLOAT_IO            TEXT_IO[8] 172       .FORMATTER.FLT_IO(U)[10] 7
 INTEGER_IO          TEXT_IO[6] 142       .FORMATTER.NAT_IO(U)[9] 6
 NEW_LINE'2          TEXT_IO[23] 77       .FORMATTER.PRINT_HEADER(U)[12] 25
                                              .PRINT_PLAYER_STATS(U)[13] 42
                                              .PRINT_TEAM_STATS(U)[14]   58
 PUT'4                  TEXT_IO[19] 128   .PUT_STATISTIC_VALUES(U)[11]   18
                                              .PRINT_PLAYER_STATS(U)[13] 37
                                              .PRINT_TEAM_STATS(U)[14]   52
 PUT_LINE'2             TEXT_IO[24] 135   .FORMATTER.PRINT_HEADER(U)[12] 28 26
                                              .PRINT_TEAM_STATS(U)[14]   50 59

                  FULL NAMES OF "IS REFERRED TO BY" UNITS

   9       !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.NAT_IO
   10      !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.FLT_IO
   11      !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PUT_STATISTIC_VALUES
   12      !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_HEADER
   13      !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_PLAYER_STATS
   14      !USERS.YOUR_USERNAME.BASEBALL_SYSTEM.FORMATTER.PRINT_TEAM_STATS

                  FULL NAMES OF "DEFINED IN" UNITS

   6        !IO.TEXT_IO.INTEGER_IO
   8        !IO.TEXT_IO.FLOAT_IO
   19       !IO.TEXT_IO.PUT'4
   23       !IO.TEXT_IO.NEW_LINE'2
   24       !IO.TEXT_IO.PUT_LINE'2

 This display shows that Formatter uses several procedures defined in
 !Io.Text_Io.

 Looking at the entry for New_Line, you can see that procedure
 Formatter.Print_Header references Text_Io.New_Line. The numbers after
 Text_Io in the "Defined In" column indicate that the full pathname of
 New_Line is given in entry 23 below and that New_Line is defined on line
 77 of package Text_Io. Similarly, the numbers in the "Is Referred to By"
 column indicate that the full pathname of Print_Header is given in entry
 12 below and that Print_Header references New_Line on line 25. The U flag
 in parentheses indicates that New_Line is read from by Print_Header.

 For further information about reading the job report, see "Reading the
 Xref Report" in the introduction to this package.


 REFERENCES

 procedure !Commands.Common.Definition