|
DataMuseum.dkPresents historical artifacts from the history of: Rational R1000/400 Tapes |
This is an automatic "excavation" of a thematic subset of
See our Wiki for more about Rational R1000/400 Tapes Excavated with: AutoArchaeologist - Free & Open Source Software. |
top - metrics - downloadIndex: L T
Length: 817816 (0xc7a98)
Types: TextFile
Names: »LM_HELP«
└─⟦d10a02448⟧ Bits:30000409 8mm tape, Rational 1000, ENVIRONMENT, D_12_7_3
└─⟦fc9b38f02⟧ »DATA«
└─⟦f95d63c89⟧
└─⟦this⟧
@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.Revn.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.Revn.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.Revn.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