TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Command Line Interface

abandon - abandons the check out

Syntax

abandon [options] files | directories | views...

Alias

unco

Description

Note: For Apex/ClearCase, the cleartool uncheckout command or the GUI command CM > Uncheckout command is used. The description provided here is only valid for Apex/Summit. Please see the ClearCase documentation for a description of the uncheckout command.

Abandons the check out of the objects. The contents of the objects revert to the last checked-in version.

Parameters

Related Commands

accept_changes - propagate changes between objects (Apex/Summit)

Syntax

accept_changes [options] files | directories | views...

Alias

accept

Description

The accept_changes command is used to propagate new versions into a set of destination objects from a set of sources. This command allows versions of objects that have been developed in one view to be propagated into other views in a controlled manner. Propagation of changes between views can be used to support parallel development, integration and construction of baselines. For example, consider a subsystem which contains a view integration.wrk which is being used for system integration and view tom.wrk which are used by an individual developer. The command:

could be used to move changes from the developer view into the integration view by update existing files and creating new files.

There are a number of different ways in which the destination objects and the sources of this command may be specified. The destination objects may be either files, directories or views. When files and directories are specified those objects must be nested within views. When individual files are specified, only those files are updated. When views or directories are specified, existing controlled files in the views and directories are updated and new files may be added to represent files which exist in the source but not in the destination.

The sources may be either a set of files, a set of views, a set of tasks, a set of histories, a set of versions, or simply the latest version of each existing object. The sources are specified by the options -source, -source_task, -source_history, -latest, and source_version. Only one of these options may be set on a given command. If none of these options is supplied then the option -accept_changes_source is examined to determine the source.

Although a variety of destination objects and sources are supported, the command fundamentally results in a set of destination files being updated to new versions. A number of options are provided to control the details of the update.

Parameters

Related Commands

accept_domain_changes - accepts changes from a remote domain (Apex/Summit)

Syntax

accept_domain_changes [options] destination...

Description

Accepts changes from a remote domain to the local domain. Unless the -no_addition option is set, the command creates remote references in the local domain to every subsystem and view whose primary domain is the specified source domain. Unless the -no_removal option is set, the command also removes references to orphaned subsystems and views whose primary domain is the specified source domain.

You can use the various inclusion and exclusion options to control the creation of remote references. Use these options to specify that references should be created (or not created) only in certain directories or to certain subsystems and views.

For example, to create a remote reference to a remote view, the view name must be matched by one of the patterns specified in the -remote_view_inclusions option and not matched by one of the patterns in the -remote_view_exclusions option. All inclusion and exclusion options can specify fully qualified or relative names. Naming expressions are equivalent to shell (csh) naming conventions.

Parameters

Related Commands

accept_export_changes - updates exports (Apex/Summit)

Syntax

accept_export_changes [options] views | configurations

Description

The export set name all_units, while a "valid" export set, is a special case that is defined and maintained by apex; options like -identical are noops on this export set.

As with other export commands:

Parameters

accept_import_changes - updates imports (Apex/Summit)

Syntax

accept_import_changes [options] views | configurations

Description

Updates the imports of the specified views (called the destination views) to reflect the import relations (including export sets) specified by the -source option. This command is useful for updating the imports of one set of views to match the relationships among another set of views, or for updating the imports of a set of views to match the relationships specified by a system description (.sysd).

The -source option can specify a set of views or a system description. When the -source option specifies a set of views, each destination view is updated to match the imports of the source view from the same subsystem. At most one source and one destination view can be specified for a given subsystem. When the -source option specifies a system description, each destination view is updated to reflect the import relationships specified in the system description. The use of a system description propagates import changes between towers.

To satisfy the import relationships specified by the -source option, the imports of each destination view are updated. New imports for a destination view are chosen by examining the source import relationships and selecting a candidate view to be imported from each subsystem designated as a supplier in the source relations. A candidate view from a supplier subsystem is chosen by applying selection rules and choosing the first view selected. A warning is emitted if the selection rules are unable to identify a candidate view to be used.

The default selection rules are given below in the order in which they are applied.

1 . If the destination already imports a view from the supplier subsystem, continue to import that view.

2 . If the destination has a view from the supplier subsystem among its current implicit imports, use that view.

3 . If the set of destination views contains a view from the supplier subsystem, use that view.

4 . If the set specified by the -import option contains a view from the supplier subsystem, use that view.

5 . If the supplier subsystem contains a view with the same name as the destination view, use that view.

This rule is not applied if the -no_name_candidates option is set.

6 . As a last resort, if the -source option specified a set of views, use the exact import of the corresponding source view.

This rule is not applied if the -no_source_candidates option is set.

When the -strict option is set, the selection rules are changed to "strictly" select imports from the views specified by the destination set and the views specified by the -import option. In particular, the -strict option provides a way to guarantee that a set of views do not import views external to the set. When the -strict option is set, the selection rules are:

1 . If the set of destination views contains a view from the supplier subsystem, use that view.

2 . If the set specified by the -import option contains a view from the supplier subsystem, use that view.

By default, new imports are added and no imports are removed. However, when the -identical or -strict options are set, import relationships of the destination views will be removed if those relationships are not specified by the -source option. In particular, the selection rules associated with the -strict option removes any existing imports of views that ar not included in the destination set or specified by the -import option.

Imports associated with a view's model are not updated by this command and imports associated with a source view's model are not propagated. The remodel command should be used to make any changes to imports associated with a model.

Parameters

Related Commands

accept_latest - same as accept_changes with the -latest option (Apex/Summit)

Syntax

accept_latest [options] files | directories | views...

Description

This is the same operation as accept_changes with the -latest option implied. All other options are the same as for accept_changes.

add_domain - adds a reference to the designated remote domain (Apex/Summit)

Syntax

add_domain [options] name

Description

Adds a reference from the current local domain to the designated remote domain.

Parameters

Related Commands

analyze - performs semantic analysis

Syntax

analyze [options] [program_units|directories|views|configurations...] (Ada)

analyze [options] files|directories|views|configurations... (C/C++)

Aliases

ana, inst, install

Description

Ada:

Performs semantic analysis on the designated program units. If successful, the units are advanced to the installed compilation state. If no arguments are provided, the command proceeds to the current directory.

Analysis of the designated units always requires that the analyze closure in the current imports be analyzed. Use the -closure and -configuration options to specify additional units to be analyzed.

C/C++:

This command has no predefined effects in the standard model but is available for user customization. For example, this command might be customized to perform semantic analysis on the specified source files.

Parameters

apex_BOM (Apex/Summit)

Syntax

apex_BOM [-fmt <n>] [-detail <n>] [-verbose] [-help] [-debug <n>] <executable>...

Description

apex_BOM takes an Apex executable and produces a bill of materials (BOM) from within an Apex build when Summit/CM is used as the underlying version control system (Apex/Summit). The format types allow for easier human (1 and 3) and tool (2) consumption of the result. The -nohdrs option will decrease the amount of output to make for machine readable form of the information.

apex_BOM must be run after a link is performed, it take as parameters the name of the linked executable and optionally the configuration used by the linker (if one was supplied to override the import closure).

The cm_status would list whether the file is controlled, checked in or out, and what kind of check out.

To provide the most human readable info:

To provide minimal machine readable info:

Parameters

apex_TWR (Apex/Summit)

Syntax

apex_TWR [options] views

Description

apex_TWR applies only when Summit/CM is used as the underlying version control system (Apex/Summit).

apex_TWR takes a list of views that define a tower and produces a tower description file. The tower description file will contain information to reconstruct the views listed as well as any views imported by the listed views.

apex_TWR invokes apex_BOM with the -fmt 9 option. While a tower description file can be generated directly from an executable using apex_BOM, this may not result in a complete tower if, for example, some views considered part of the tower are not referenced via the closure of the executable.

apex_TWR can reconstruct a tower given a previously created tower description file. The subsystems, including the cmvc database, can not be reconstructed. With the exception of imports, exports, and the Policy/Switches file, uncontrolled files will not be saved or restored. The model and key views should never be saved or restored using this tool; the model and key views used by the views being reconstructed must exist prior to the reconstruction of the views. Part of a tower can be restored by specifying subsystems or views to be restored; otherwise the entire tower is restored. An error is reported if a veiw to be restored already exists; existing objects will not be replaced or destroyed.

Parameters

apex_upgrade - upgrade subsystems, views and/or configurations (Apex/Summit)

Syntax

apex_upgrade [options] what_to_upgrade ...

Description

After installation, upgrade your subsystems using the apex_upgrade command. (Note that if you are doing just a patch install, it is not necessary to run apex_upgrade. Installing a patch to an existing release is covered in the Installation Guide.) When you invoke apex_upgrade, Apex performs the following actions:

Parameters

There are four basic actions that can be done with apex_upgrade:

These actions correspond to the following four options:

-create_model_map <map>
-use_model_map <map>
-revert
-commit

The actions are described below:

Action #1: Create a model map

With previous versions of apex_upgrade, the set of new models to use was provided by the user on the command line. Models that not specified on the command line were taken from environment variables (for example, $APEX_ADA95_MODEL).

This version of apex_upgrade computes the set of new models by translating the version number (eg 3.2.0) in old models to the new version number (eg 4.0.0). A one-to-one mapping of old to new models is created, and stored in a file specified by the user using the -create_model_map <map> option. After creation, you should inspect the newly created <map> file. Each line of this file is of the form "old_model: new_model". If any new_model is set to UNKNOWN, that means apex_upgrade was unable to determine a replacement view.

You must either edit this file and replace all instances of UNKNOWN with valid models, or rerun apex_upgrade with the -create_model_map <map> option omitting views based on the old_models that were mapped to UNKNOWN.

You may also edit the <map> file to override any new_model values.

Views that have already been upgraded will have the new models listed in the old_model column of the <map> file. The corresponding new_model will be set to "ALREADY_IS_NEW_MODEL", and can be left as-is.

Action #2: Do the upgrade (using the model map)

You can specify the set of views to be upgraded explicitly, or via subsystem names or configuration files. Specifying a subsystem will upgrade the Policy/Switches file for that subsystem, and all views in the subsystem. Specifying a configuration file will upgrade all views in the configuration.

Views can be removed from the list to be upgraded via the -skip* options.

You have the option of doing the upgrade in two passes. The reason for breaking the actual upgrade into two passes is that some product installations have file permissions such that different people must perform pass 1 on different sets of views. If this is not a concern for your installation, you can perform both passes at once. If you are unsure, use the -effort_only and -pass both options and look for warnings in the output relating to file permissions.

Pass 1 performs the following operations:

Pass 2 performs the following operations:

Action #3: Revert (to pre-upgrade state)

Backing out upgrade

This version of apex_upgrade allows you to partially back out an upgrade. Backups of following information is saved before apex_upgrade alters it.

Running apex_upgrade with the -restore option will restore these files, and remodel views.

Note however, that once views are cleaned (during pass 1) compilation information cannot be retrieved.

Action #4: Commit (remove files needed to Revert)

Although it will not harm anything to leave the backup files in place, the -commit option will remove them should you wish to do so.

Upgrading very old views

apex_upgrade is designed to upgrade views based on models from Apex beyond a specific version (currently 3.0.0). If you attempt to upgrade views based on older models, apex_upgrade will print an error, and give you the option of re-running with the -upgrade_very_old_views option. It is expected that there will be problems if you use this switch to upgrade old views. But it is provided for advanced Apex users who can finish upgrading views by hand after apex_upgrade has done what it can.

Remodeling views with non-Rational keys

If a C/C++ view has the BUILD_KEY switch set to a value other than $APEX_BASE/c++/keys/* the view is said to have a non-Rational key. The BUILD_KEY will not be updated, and the view will not be remodeled unless the -replace_other_keys switch is specified.

Similarly, if any other view has the COMPILER_KEY switch to a value other than $APEX_BASE/ada/key.ss/*.{rel,wrk} the view is said to have a non-Rational key. The COMPILER_KEY will not be updated, and the view will not be remodeled unless the -replace_other_keys switch is specified.

Example Invocation sequence

1 . apex_upgrade -create_model_map /tmp/model_map /my/area/*.ss

2 . vi /tmp/model_map

3 . apex_upgrade -effort_only -use_model_map /tmp/model_map /my/area/*.ss

4 . apex_upgrade -use_model_map /tmp/model_map /my/area/*.ss

Step 1 creates /tmp/model_map

Step 2 replaces instances of UNKNOWN in /tmp/model_map

Step 3 confirms that there are no expected problems performing upgrade

Step 4 performs upgrade

Single-Pass Upgrade

You can use a single-pass upgrade when you have write-access to all subsystems being upgraded. To perform a single-pass upgrade, follow these steps:

1 . Start the current version of Apex.

2 . Go to an Apex shell to enter your commands.

You can use a window created by the Tools > Shell menu button.

3 . Create model map:

4 . Edit model map.

Replace any instances of UNKNOWN with valid models.

5 . Upgrade the appropriate subsystems using the following command:

For example:

This command upgrades all views in the subsystem open_door.ss except hold.wrk.

Multiple-Pass Upgrade

You can use multiple-pass upgrade when no single individual has write access to all subsystems you want to upgrade. A multiple-pass upgrade has two steps:

1 . Individuals within groups perform preliminary upgrades on subsystems owned by each group. You can upgrade subsystems in any order:

a . Start the current version of Apex.

b . Go to an Apex shell to enter your commands. You can use a window created by the Tools:Shell menu button.

c . Upgrade the appropriate subsystems using the following commands:

The options and variables are the same as those for the regular apex_upgrade command. The command ignores any options that do not apply.

2 . Once the preliminary upgrade has been performed on all subsystems, anyone can perform the final upgrade:

a . Start the current version of Apex.

b . Go to an Apex shell to enter your commands.

c . Upgrade the appropriate subsystems using the following commands:

The options and variables are the same as those for the regular apex_upgrade command. The command ignores any options that do not apply.

This step refreshes imports for all views and recompiles all views.

Related Commands

Control > Maintenance > Upgrade to New Apex Release

build - build everything in the library context

Note: This command is only valid with C/C++ build management.

Syntax

build [options] files | directories | views | configurations...

Description

This command is provided for overall management of the build process. Generally this command is used to build everything in a library context by running a sequence of other build commands. That sequence of commands can be customizable for each library context as described below.

Parameters

build_api - build API view from specified source views (Apex/Summit)

Syntax

build_api [options] api_view source_views ...

Description

Creates an API view from the specified source views. The API builder first examines all the units in the source views, and attempts to compile any that are not compiled. Units in the closure of these views are compiled if necessary. If any of these compilations fail, the API builder does not update the API view.

Next, the API builder copies any unit in the source view containing pragma Api into the API view. The API builder does not create any subdirectories; units get copied directly into the API view no matter where they appeared in the directory hierarchy in the source view. The API builder also copies sufficient compiler artifacts so that clients can compile against the API just as if they had imported the source views, but only referenced the units containing pragma Api.

The view constructed by the API builder is considered by the compiler to be a read-only view. Do not edit, add, or delete Ada units from a view that has been built by the API builder. The compiler cannot be coaxed into performing any compilation in an API view. Any Ada units that are copied into the API view after the builder has run will be treated as ordinary text files by the compiler.

Because compilation cannot take place in API views, care should be taken not to delete any of the compilation artifacts, since they can only be recreated by rerunning the API builder. The Apex clean command will not modify an API view. If users have their own shell scripts for deleting compilation artifacts, they should be carefully written to avoid damaging API views.

When the API Builder is run, it records any export sets defined in the source views and uses them to enforce architectural control in the clients of the API. Any exports sets defined for the API view itself are ignored by the compiler. That is, if a unit U withs a unit V in an API view, the legality of that with determined using the exports sets defined in the source view from which V was copied when the API builder was run. If an API is created that uses export sets, it is a good idea to define a set of export sets in the API view that is the union of the exports sets in the source views. Although these sets will be ignored by the compiler, having them will minimize confusion among the users of the API.

A complete description of APIs can be found in the Ada Compiler Reference.

Parameters

build_bodies - supplies Ada bodies

Syntax

build_bodies [-visit|-no_visit] scope

Description

Completes Ada units by supplying skeletal implementations of bodies for specifications that require bodies but do not have them.

This command works on a list of compilation units in the following ways:

1 . If it is a specification, then:

a . If the body unit does not exist, create it, and supply bodies for all declarations in the specification.

b . If the body unit does exist, then incrementally add bodies for all declarations in the specification that do not have bodies.

c . If a specification declaration has a stub in the body unit, create a separate unit body fr the declaration.

2 . If it is a body or a subunit, then:

a . If the specification does not exist, create bodes for all program units nested in the body/subunit (provided they do not already have bodies).

b . If a specification does exist, do 1a, and also supply bodies for all declarations in the specification that do not have bodies. In addition, the specification itself is processed (that is, bodies are created for all programs units nested in the body/subunit (which don't already have bodies) irrespective of whether they are declared in the specification or body.

Note that if you are processing a subunit body, its specification is itself nested in a body, so the processing continues recursively.

c . If a stub exists, and no body exists for the stub, create the body for the stub.

This command examines all Ada units in the specified scope and builds bodies for each of the specifications in those units that are missing bodies as described above. scope must resolve to a set of Ada units, or directories or views.

This command assumes that all existing units in wich bodies are to be built are already checked out. If a unit is not checked out, an error is issued for it, and a body is not created for it.

The following are examples of the command line invocation of build_bodies:

1 . build_bodies p.1.ada

where the units p.1.ada, p.2.ada, and p.q.2.ada are:

2 . build_bodies p*.ada

where the units p.1.ada, p.2.ada and p.q.2.ada are as in example 1.

This time, bodies are provided for P.Q.Missing_Body_1 and P.Q.Missing_Body_2.

3 . build_bodies -no_visit *.ada

Build bodies for all specifications missing bodies in all Ada units.

4 . build_bodies -no_visit /a/b.ss/c1.wrk/d /a/b.ss/c2.wrk

Builds bodies of all Ada units in /a/b.ss/c1.wrk/d and its subdirectories, and in /a/b.ss/c2.wrk and its subdirectories.

Support for Ada 95

The build_bodies command fully supports many Ada 95 constructs including child units, protectec units and protected type declarations and can create entry bodies. Note that this functionality is only available in Ada 95 views.

Parameters

Examples

In this section, A is the compilation unit being processed. In theseexamples, A is a specification.

Build Body Applied to a specification which has no body

If A has no body, its body is created. In addition, if A is a (possibly generic) package specification, then bodies are created for all the program units nested in A (in both the visible and in the private part). For example, executing Build Body on the following specification:

creates the package body:

This processing is done recursively, so that bodies are also created for nested packages and for subprograms declared in such packages, as shown by the following example:

Build Body applied to a specification which has a body

If A has a body, and is a (possibly generic) package specification, then bodies are incrementally added for all program units nested A. Say for instance, that we add a function Distance to the specification of package Geometry:

Running Build Body on geometry.1.ada results in the addition of the body of Distance to the body of Geometry (without altering the rest of geometry.2.ada):

In addition, if one of the subprograms declared in the specification of the package being processed has a stub in the body of that package, running Build Body on the package specification creates the subunit for this subprogram if it doesn't already exist. Assume that the body of Geometry contains:

Then running Build Body on geometry.1.ada causes the creation of a subunit for Distance:

check_in - checks in the objects

Syntax

check_in [options] files | directories | views...

Aliases

Description

Note: For Apex/ClearCase, the cleartool checkin command is used. The description provided here is only valid for Apex/Summit. Please see the ClearCase documentation for a description of this command.

Checks in the designated objects. This causes a new version of the object to be finalized. The history of the object is no longer reserved.

Parameters

Related Commands

check_out - checks out objects

Syntax

check_out [options] files | directories | views...

Aliases

checkout, out, ckout, check_out, co

Description

Note: For Apex/ClearCase, the cleartool checkout command is used. The description provided here is only valid for Apex/Summit. Please see the ClearCase documentation for a description of this command.

Checks out objects for modification with a reservation or privately. When checked out with a reservation, the version history of the file is reserved. When checked out privately, no reservation is acquired. In either case, the permissions on the file are changed to allow write-access by owner and users in the file's associated group.

A private check out allows you to work privately in a view without having any affect on other users. However, a privately checked out file cannot be checked in unless the check out is upgraded to a check out with a reservation. The check in command performs an implicit upgrade if the private check out was based on the version that is still the latest version.

An upgrade can also be done explicitly. When an upgrade occurs and the -latest option is specified, the file is updated to contain the contents of the latest version and the contents in the file are placed in a file with extension .private.saved. Furthermore, the common ancestor is placed in a file with extension .ancestor.saved. If an upgrade occurs and the -keep_current option is set, the file retains its current contents and no additional files are created.

With no options set, the operation succeeds only if the file currently contains the latest version. Options allow the file to be automatically updated to the latest version or to maintain the contents of an older version.

Parameters

Related Commands

check_rules - check conformance with coding rules

Syntax

check_rules [options] files | directories | views | configurations...

Description

In the standard Apex models this command runs the code rule checker on the specified files. In non-Apex models this command has no predefined effect and is available for user customization.

See the Code Rule Checker documentation for further information.

Parameters

clean - removes compilation artifacts

Syntax

clean [options] [program_units|directories|views|configurations...] (Ada)

clean [options] files|directories|views|configurations... (C/C++)

Description

Ada

Removes artifacts of compilation to reduce the specified files to the provided goal state. If no objects are provided, the current directory is processed.

C/C++

In the standard model, this command will remove compilation artifacts associated with the specified objects. Compilation artifacts that are removed include object files, executables, template repositories, libraries and user specified objects.

Parameters

Related Commands

code - generates object code

Syntax

code [options] [program_units|directories|views|configurations...] (Ada)

code [options] files| directories|views|configurations... (C/C++)

Alias

compile

Description

Ada:

Generates object code for the designated program units. If successful, the units are advanced to the coded compilation state. If no arguments are provided, the command processes the current directory.

Coding the designated units requires that the code closure in the current imports be coded. Specify additional units to be coded using the -closure and -configuration options.

C/C++:

In the standard model the command will generate code for the specified source files.

There are a number of switches that can affect the code operation. These cannot be specified as command line options. These switches are as follows.

A full listing of coding switches can be displayed using the show_switches command. Use the following command from an Apex shell:

Parameters

Related Commands

compare - compares objects to the corresponding objects (Apex/Summit)

Syntax

compare [options] baseline_view files | directories | views...

Aliases

cmpr, show_comparison

Description

Compare the objects to the corresponding objects in the baseline view. This is useful for determining how entire files or even entire views differ from the corresponding objects in the baseline view. The information displayed by compare is similar to that displayed by show_status.

You can use the options to control which objects are displayed. If no options are set, -out_of_date and -new_acceptable_files are assumed, which show files that would be updated if changes were accepted from the baseline view to the specified objects by the accept_changes command. To see a full difference list, use the -all option.


Warning: The implementation of the compare command is different than the implementation of the
Control > Show > View Comparison command in the GUI.

Parameters

Related Commands:

Compare Output

The output of the compare command shows the difference between two views that are designated the baseline and the current views.

The output has the following format:

Baseline View: <view-name>
Current View: <view-name>
Baseline Default History: <history>
Current Default History: <history>

Baseline
Current
File Name
History
Version
State
History
Version
State
<diff><element>
<hist-1>
<ver-1>
<state-1>
<his-2>
<ver-2>
<state-2>
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

The first two lines provide the name of the baseline and current views.

The next two lines provide the default history of the baseline and current views.

The rest of the output is a table that provides information for each element represented in either one of the views.

The difference field (denoted by <diff>) is an annotation that summarizes how the views differ on a particular element. The possible values are:

The File Name field provides the element name (that is, the view-relative name of the file found in either of the views).

The rest of the fields provide the history, version, and state information for the element in either the baseline or current views. If a file does not exist in a view, the information is not provided.

An example of compare output is provided below:

control - places the objects under version control

Syntax

control [options] files | directories | views... (Apex/Summit)

control [options] files | directories... (Apex/ClearCase)

Alias

Description

For Apex/ClearCase, places the file or directory under version control. This includes Rational Subsystems (RSSs).

For Apex/Summit, places the objects under version control. If this is the first time an object with this name is controlled for the designated history, a new version history is created whose first version is identical to the current contents of the file. If the history already exists, the file contents must match the latest version.

You can use options to manage what happens when the current file contents do not match the latest version. The -match, -create, and -latest options are mutually exclusive. If none of the options of -match, -create, or -latest is given, -match is assumed.

Files can be controlled only if allowed by the inclusion and exclusion switches.

Parameters

Related Commands

copy - copies objects

Syntax

copy [options] source... destination

Alias

cpr

Description

Copies the source objects to the destination. Copies of directories are always recursive.

Exact semantics depend on the kind of objects being copied and their characteristics. For example, an Apex/Summit view cannot usually be copied within its subsystem if it contains any checked out files. Special semantics and restrictions for different objects are described below:

Copy operations are also subject to the normal access control requirements that source objects be readable and destination objects be writable. Copy operations that create new objects are also subject to any restrictions described by the various creation commands.

Parameters

Related Commands

copy_view - creates a set of new views from a set of source views (Apex/Summit)

Syntax

copy_view [options] views | configurations... [destination]

Alias

cpvw

Description

This command provides a powerful way to copy a set of related views. This command provides a number of capabilities beyond those of the common copy operation including:

Normally, the new views created by this operation will have the same version control characteristics as the original views. However, if the original views contain checked out files, then the copy will only succeed if an option is specified to do one of the following:

As part of the copy operation, the imports of the new views are updated to reflect the imports of the source view. In particular, if there is an import relationship between two source views, the corresponding target views will have the same import relationship. If the import information cannot be successfully analyzed, the copy of each view will be successful but each will have invalid import information.

Parameters

Controlling the Contents of New Views

Options and context switches are provide to control which objects are copied from the source view into the target view. The context switches in a source view establish the default behavior whenever a copy of the view is created. The default behavior may be overridden by setting the options on the command line.

There are specific switches to control the contents when working or release views are created. In order to be copied a file must be named by the appropriate inclusion switch and not named by the exlcusion switch. In addition, if an interface view is being created then the file must also be named by the interface inclusion switch and not named by the interface exclusion switch.

The context switches are:

Name Generation Context Switches

The following switches control automatic name generation when the -generate_name option is used.The switches used during name generation are determined by the kind of view being create, as specified by the -view_kind option, and the value of the -interface option.

Name generation switches come in pairs. One switch specifies a pattern used to generate the name. The other switch specifies the levels which are incorporated into the final name. The name pattern switch is subject to keyword replacement.

The levels switch contains a sequence of numbers and separator characters. During name generation, the -level option determines which number is incremented; all numbers to the right of the incremented number are set to zero. Levels are numbered from right to left; the right-most number is always considered level "1".

Interface Views

Setting the -interface option during view creation will create an interface view subject to interface view content filtering and name generation. In addition the following context switch is set to designate interface views:

Related Commands

create - creates new objects

Syntax

create [options] names...

Alias

cr

Description

Creates new objects with the specified names. You can use this command to create objects of any class by specifying the extension in the object name.

Parameters

Related Commands

create_ada - creates new Ada units

Note: This command is only valid for Apex Ada and Apex Duo.

Syntax

create_ada [options] names...

Alias

crada

Description

Creates new Ada units. The contents of the new units are initialized by prototypes selected based on the -unit and -part options.

Parameters

Related Commands

create_body - creates new Ada unit bodies

Note: This command is only valid for Apex Ada and Apex Duo.

Syntax

create_body [options] names...

Alias

crbody

Description

Creates new Ada unit bodies. This is the same operation as create_ada, but with -part body implied. All other options are the same as for create_ada.

Related Commands

create_c - creates new C language files

Note: This command is only valid for Apex C/C++ and Apex Duo.

Syntax

create_c [options] names...

Description

Creates new C language files. The contents of the new files are initialized by prototypes based on the -unit and -part options.

Parameters

Related Commands

create_class - creates new C++ language files

Note: This command is only valid for Apex C/C++ and Apex Duo.

Syntax

create_class [options] names...

Description

Creates new C++ language files which are initialized to contain class declarations. This command is essentially an alias for the create_cpp command with the -unit option set to class.

Parameters

Related Commands

create_configuration - creates a new configuration file

Syntax

create_configuration [options] names...

Aliases

create_config, crconfig

Description

Creates a new configuration file.

Parameters

Related Commands

create_cpp - creates new C++ language files

Note: This command is only valid for Apex C/C++ and Apex Duo.

Syntax

create_cpp [options] names...

Description

Creates new C++ language files. The contents of the new files are initialized by prototypes based on the -unit and -part options.

Parameters

Related Commands

create_directory - creates new directories

Syntax

create_directory [options] names...

Alias

crdir

Description

Creates new directories.

Parameters

Related Commands

create_export_set - creates export sets

Syntax

create_export_set [options] simple_name...

Alias

Description

Export sets are used to control the set of interfaces made available to clients.

Parameters

Related Commands

create_file - creates new files

Syntax

create_file [options] names...

Alias

crfile

Description

Creates new files. You can use this to create files of any subclass by specifying the correct subclass extension as part of the name.

Parameters

Related Commands

create_history - creates new version histories (Apex/Summit)

Syntax

create_history [options] simple_name...

Alias

Description

Creates new version histories in the specified subsystem.

Parameters

Related Commands

create_registered_set - creates registered sets

Syntax

create_registered_set [options] simple_name...

Alias

Description

Creates new registered sets with the specified names.

Parameters

Related Commands

create_release - creates new, empty development release views (Apex/Summit)

Syntax

create_release [options] names...

Aliases

crrel, create_rel

Description

Creates new, empty development release views with the specified names. You can create views only within subsystems, and the views cannot be nested within other views.

Parameters

Related Commands

create_spec - creates new Ada unit specs

Note: This command is only valid for Apex Ada and Apex Duo.

Syntax

create_spec [options] names...

Alias

crspec

Description

Creates new Ada unit specs. This is the same operation as create_ada but with -part spec implied. It is also possible to set -part generic_spec. All other options are the same as for create_ada.

Related Commands

create_subsystem - creates new subsystem

Note: If Apex/ClearCase is being used, this command will create a Rational Subsystem (RSS).

Syntax

create_subsystem [options] names...

Aliases

crss, create_ss, create_rss

Description

Creates new subsystems with the specified names. You can create subsystems anywhere within the directory system (subject to the restrictions below); however, subsystems cannot be nested within other subsystems. For Apex/ClearCase, subsystems that are to be controlled need to be in a VOB.

Creating a subsystem is subject to the restriction that you must establish a permanent name for a subsystem at the time you create it. You can establish the permanent name of a subsystem in two ways:

Parameters

Session Switches

Related Commands

create_working - creates new, empty, working views (Apex/Summit)

Syntax

create_working [options] names...

Aliases

crwrk, create_wrk

Description

Creates new, empty, working views with the specified names. You can create views only within subsystems, and the views cannot be nested within other views.

Parameters

Session Switches

Related Commands

deliver - deliver a set of objects to their final destination

Note: This command is only valid with C/C++ build management.

Syntax

deliver [options] files | directories | views | configurations...

Description

This command may be used to deliver a set of objects such as libraries or executables to their final destination. The command uses the settings of various context switches to determine which objects to deliver and the destination directory to which the objects are to be delivered.

The switches come in pairs of the following type:

In addition to the switches named above there are additional switches named

Parameters

demotion_impact - shows the compilation effects of demoting a unit

Syntax

demotion_impact [options] -as_file <unit>

demotion_impact [options] <ada_name>

Description

Shows what other units will be affected if the compilation state of the specified unit were to be changed to Source or Archived.

A unit's compilation state is the current status of a unit with respect to compilation. The compilation states are: Archived, Source, Installed, Coded, Unparsed, and Linked. Each of the compilation commands performs the processing necessary to advance a unit to a particular compilation state.

Parameters

dependencies - recomputes dependencies for C/C++ source files

Note: This command is only valid with Apex C/C++ and Apex Duo.

Syntax

dependencies [options] files | directories | views | configurations...

Description

In the standard models, this command will recompute the dependencies for the object files associated with the designated source files. Manual updates of dependencies are normally not needed since dependencies are automatically updated as part of each compilation.

Parameters

Related Commands

difference - show the differences between two objects

Syntax

difference [options] files...

Aliases

diffr, show_difference

Description

Note: For Apex/ClearCase, the cleartool diff command is used. The description provided here is only valid for Apex/Summit. Please see the ClearCase documentation for a description of this command. One exception is when -parse_ada is in effect; if -parse_ada is in effect, then the Ada unit difference will always be processed by Apex.

Shows the textual differences between two objects, each of which can either be an uncontrolled file or a version of a controlled file. The two objects are known as the current object and the previous object respectively. The differences are shown in a format that suggests how the previous object could be transformed into the current object.

The current object is specified by the file argument to the command and the value of the -current option. If the file argument names an uncontrolled file, the current contents of that file are used. If the file argument names a controlled file, the -current option is used to determine which version of the file will be used. When multiple file arguments are specified, each is processed individually.

The previous object is specified by the -previous_file and -previous options.

Note that the default behavior shows the difference between two versions of a controlled file that is named as the argument.

By default, the command ignores differences that are due only to "whitespace" changes (that is, blanks or tabs) at the beginning or end of lines.

Ada constructs are considered to be Ada ids, keywords, and variables.

Parameters

Related Commands:

disassemble - disassembles object files

Note: This command is only valid with Apex C/C++ and Apex Duo.

Syntax

disassemble [options] files|directories|views|configurations...

Description

This command disassembles object files. The resulting (.das or .asm) files are located in the source directory next to the source files (c/c++ or ada files, respectively).

Parameters

Related Commands

disable_cpp_linking - disables linking of C/C++ into Ada

Note: This command is only valid with Apex Duo.

Syntax

enable_cpp_linking [options] views...

Description

Disable linking of C and C++ into Ada main programs in the specified views.

This command may only be invoked directly and not by prefacing it with apex.

Parameters

Related Commands

discard - delete objects

Syntax

discard [options] files | directories | views | subsystems...

Aliases

delete, del, delr

Description

Deletes the objects and possibly their children. You can delete directories (including Apex/Summit views and subsystems) only if there are no child objects or if the -recursive option is set.

The exact semantics of deletion depend on the characteristics of the objects being deleted and the context of the deletion. For example, special semantics are associated with deleting a view, but these apply only when the deletion is not part of the deletion of the enclosing subsystem. Special semantics and restrictions for different objects are described below.

Deletion is also subject to access control restrictions. You can delete objects outside of subsystems only if the user has write-access to the enclosing directory. You can delete subsystems or objects within subsystems only if the user is in the associated group of the subsystem. (For further information about the associated group of a subsystem.

Parameters

Related Commands

discard_export_set - deletes export sets

Syntax

discard_export_set [options] simple_name...

Aliases

delete_export_set

Description

Deletes the export set in the named library context.

Parameters

Related Commands

discard_history - deletes the specified histories (Apex/Summit)

Syntax

discard_history [options] histories...

Aliases

delete_history, delete_hst, delhst

Description

Deletes the specified history in the subsystems. The command fails if any views use the named history. This restriction can be overridden using the -force option. If the history is deleted and there are controlled objects that use the history, all of those objects will be made uncontrolled.

Parameters

Related Commands

discard_registered_set - deletes registered sets

Syntax

discard_registered_set [options] simple_name...

Aliases

delete_registered_set, delete_reg_set

Description

Deletes the specified registered sets.

Parameters

Related Commands

do_clearcase_audit - builds derived objects (Apex/ClearCase)

Syntax

do_clearcase_audit code | link | build [noclean] [noimports] [ compile_options | link_options ] -- object ...

Description

Codes or links the specified object in a ClearCase audited shell. This generates compilation artifacts as ClearCase derived objects and produces a ClearCase configuration record. See "Audited Builds and Winkins" in the Rational Apex Getting Started Guide. do_clearcase_audit invokes the ClearCase clearaudit command to do the audited build.

Each Rational Subsystem in the import closure, is coded in a separate clearaudit shell. Any Summit views in the import closure are ignored for auditing purposes.

This command codes the import closure of the specified object in order of the import hierarchy. This differs from the normal Apex code operation, which codes units in a unit-dependency order. This is necessary so that clearaudit records only compilation artifacts generated in that Rational Subsystem as derived objects.

In addition, the normal source code reformatting (pretty-printing) performed by the compiler on checked-out or uncontrolled source files is disabled for audited builds. Pretty-printing modifies the source file, which would cause clearaudit to record the source file as a derived object in the configuration record.

Parameters

Example

enable_cpp_linking - enables linking of C/C++ into Ada

Note: This command is only valid with Apex Duo.

Syntax

enable_cpp_linking [options] views...

Description

Enables linking of C and C++ into Ada main programs in the specified views.

This command may only be invoked directly and not by prefacing it with apex.

Parameters

Related Commands

export - exports the designated objects

Syntax

export [options] program_units | directories | views...

Alias

xp

Description

Exports the designated objects from their enclosing views.

Parameters

Related Commands

finalize - this command is available for user customization

Note: This command is only valid with C/C++ build management.

Syntax

finalize [options] files | directories | views | configurations...

Description

This command has no predefined effects in the standard model, but is available for user customization. For example, this command might be customized to perform some final processing in the view.

Parameters

generate - this command is available for user customization

Note: This command is only valid with C/C++ build management.

Syntax

generate [options] files | directories | views | configurations...

Description

This command has no predefined effects in the standard model, but is available for user customization. For example, this command might be customized to generate additional artifacts by running a C/C++ executable which had been produced in the view.

Parameters

help - provides help

Syntax

help [command]

Description

Provides help in the form of a usage message for the designated command. If no command is specified, all commands and their arguments are listed.

Parameters

import - updates the importers

Syntax

import [options] importers... [new_imports...]

Description

Updates the importers to reflect the new imports. The imports must pass various consistency and compatibility conditions.

The interpretation of the arguments is dependent on the options specified. When the -mutual or -refresh option is specified, all arguments are interpreted as importers to be updated. When neither -mutual nor the -refresh is set, the importers are specified by the first argument and all the remaining arguments specify the new imports to add. In this case, the first argument may name a view or a configuration, or it may be a wildcard expression in quotes that resolves to a set of views or configurations. For example, you can use the following command to update the imports of a set of views in different subsystems to the values specified in a configuration:

When new_imports are specified or when the -mutual option is used, the appropriate import description files (discussed earlier) are updated with the new information. The imports are then computed on the basis of the contents of the description files. If an error occurs while analyzing the imports, the description files are left in their original state.

When the -refresh option is specified, the imports for each view are computed based on the current contents of the description files.

Whenever a single member of a mutual import set is analyzed, all other members of the set are also analyzed simultaneously.

Views processed by the same command are analyzed in the correct order to ensure that supplier views are updated before clients.

The -update, -mutual, and -refresh options are mutually exclusive.

Parameters

Related Commands

link -generates an executable file

Syntax

link [options] [program_units |directories |views | configurations...] (Ada)

link [options] files | directories | views | configurations... (C/C++)

Description

Ada

Produces executables based on main entry points in the designated program units. If successful, the units advance to the linked compilation state. If no arguments are provided, the current directory is processed and all appropriate main programs are linked. For Ada views, this means that all units with "pragma main" are linked when a directory is named.

The executable includes units from the link closure of the designated main program. The link closure is taken from the -configuration option or the imports (if -configuration is not set).

C/C++

Generate an executable from the designated main programs. Each source file containing a main program must have been registered by running register_main_program. In addition to generating an executable this command will produce a closure file (with extension .closure) which contains all of the object files, libraries and linker options that were used to link the program (with the exception of the object file for the main program itself).

There are a number of switches that can affect the link operation. These cannot be specified as command line options. These switches are as follows.

A full listing of linker switches can be displayed using the show_switches command. Use the following command from an Apex shell:

Parameters

Related Commands

maintain - corrects the Apex state

Syntax

maintain [options] files|directories|views|subsystems...

Aliases

maint, maintenance

Description

Use when the state managed by Apex is inconsistent. The directory structure and existence of required files is always checked. The options may be used to specify additional checks and/or repairs to make.

This command is especially useful when tools outside of Apex cause corruption of state.

Parameters

Releasing a Lock on a File

Locks are placed on files by Apex to prevent concurrent write access. Locks can be placed on various files during compilation, copy operations, Summit/CM operations, and for other reasons.

Locks are held by a particular process number running under a particular username on a particular host machine.

Locks are removed by Apex when the operation requiring the lock is finished. However, if the operation is interrupted - killed, crashes, that is, the lock may be left on a file.

The way to recover these locks is to run the maintain command. From the Apex command line, use the command

This is also available through the GUI using Control > Maintenance > Maintain. Select the "Lock Information Maintenance", "Force Lock Recovery", and "Recursively Maintain All Subdirectories" options.

This step will remove locks that are no longer deemed necessary by considering whether the process/user/host machine holding the lock is still active. If not, the lock is not needed. If it is, the lock may still be in use.

"Force Lock Recovery" causes locks held by processes on other hosts to be recovered if the other host is inaccessible. Effectively, the option causes Apex to abandon the conservative approach and to assume the lock is not needed.

Recovering File Locks from Remote Machines

When an Apex command runs on a machine (machine A), it attempts to acquire a lock for a file. If it finds the file locked on a remote machine (machine B), machine A checks machine B to see whether the process that acquired the lock is still active. If the process is not running, machine A recovers the file lock for itself. If the process is still running, the command running on machine B retains the file lock.

For this to work correctly, the ps command on the remote machine must be accessible. The default assumes the remote machine is running the remote execution demon (rexd).

To see whether rexd is running on the remote machine, enter the following command in an xterm window, where remote_machine is the hostname of the remote machine:

If a status line is returned, the remote machine is running rexd.

If you cannot run rexd, refer to the APEX_LOCKING switch for alternative remote commands or contact your Rational technical representative for alternative workarounds.

Related Commands

make - invokes the platform make command

Syntax

make [options] targets...

Description

This command may be used to invoke the platform make command through Apex. This command will ensure that makefile macros are updated prior to invoking make.

Parameters

Related Commands

make_inline - inline subunits/Ada 95 child units

Syntax

make_inline [-visit|-no_visit] scope

Description

Causes a collection of compilation units that are subunits or Ada 95 child units to become inlined into their parent units.

It works on a list of compilation units as follows:

1 . If it is a subunit, it is inlined into its parent at the point of the stub.

2 . If it is a child unit specification, it is inlined into its parent unit specification. Furthermore, if it has a body, that is treated as in 3 below.

3 . A child unit body is treated as follows:

a . First the specification is inlined into the parent specification.

b . Then, if the parent does not have a body, a body is created for the parent.

c . Then the child unit body is inlined into the parent unit body.

Parameters

This command is not always a semantic preserving transformation, as shown by the following example:

WheP.Q is made inline, it looks like:

The specifications P and its child unit P.Q are legal, but the specification P will not compile after P.Q is inlined since the private part of the nested package P.Q will not compile.

make_separate - make inlined bodies/specifications into subunits/child units

Syntax

make_separate [-no_visit] ada_name

Description

Makes inlined bodies into subunits. In Ada95, it is also used to make inlined specifications into child units.

This command operates on ada_name as follows:

1 . If ada_name is a program unit body, then the body is made separate, if possible. For example, no unit name conflicts, nested at the right level, etc.). The inlined body in the parent is modified into a stub.

2 . In the case of Ada 95, if the ada_name is a specification (necessarily in a package or a generic package), then Make_Separate will make the specification into a child unit.

a . If the specification additionally has an inlined body, the inlined body is removed and a child unit body is created.

b . If the specification additionally has a separate body, it is converted to a child unit body. If the specification is in the visible part, it becomes a public child, and otherwise, it becomes a private child.

Parameters

Note: In Ada 95, making an inlined specification into a child unit is not a semantics preserving transformation. However, a semantically legal inlined package specification in the visible part of a library level package will usually result in a semantic legal child unit that, in its private part, will gain visibility to the private part of the parent unit which it did not have before.

Examples

In Ada 95 views, the Make Separate command operates on both program unit bodies as well as specifications. If it is applied to a specification (nested in a library package), that specification is turned into a child unit. If the specification has a (separate or inlined) body, this body is turned into a child unit body. For example,

If make_separate is applied to the specification of Geometry.Circle, both the specification and the body of this package are extracted and turned into a child unit.

merge - merges the contents of two files

Syntax

merge [options] [file1 [file2]]

Description

Note: For Apex/ClearCase, the cleartool merge command is used. The description provided here is only valid for Apex/Summit. Please see the ClearCase documentation for a description of this command.

Merge the contents of file1 and file2 into a result file. The merge may be based on a common ancestor. The result file will contain contributions from both files and possibly annotations that describe in which file the contribution originated and whether contributions conflict.

Parameters

Change Regions

The following annotations are used to specify different kinds of changes. The annotations precede text in the result file.

When no common ancestor is specified, a common ancestor is assumed identical to the common regions in file1 and file2. This results in insertions with only annotations 1++| and 2++|.

Conflicting Changes

Conflicts occur when a common ancestor was specified and file1 and file2 contain different changes for the same region. Conflicts are denoted by adjacent change regions with special annotations:

migrate - parses text files to create Ada units or migrates C/C++ source files into Summit/CM views

Syntax

migrate [options] [files...] (Ada)

migrate [options] files (C/C++)

Alias

import_text_files

Description

For Ada, parses the specified files, placing the result into appropriately named program units in the specified directory.

For C/C++, this command can be used to migrate files into Summit/CM views.

Parameters

Related Commands

migrate_diff - compares a RSS and an Apex/Summit view

Syntax

migrate_diff [-log <output-file>] [-main_history <history>] <Summit view> <RSS>

Description

This command compares a RSS in a ClearCase view and a Apex/Summit view and lists out the differences, if any.

Assumptions
Salient Points

There are two sections of the output:

Parameters

-main_history <history>

maps the given history to main branch (succeeds only if none of the elements on the history have an ancestor element on another history)

<summit view>

specifies a Summit view of a subsystem

<RSS>

specifies the Rational Subsystem created by migrating subsystem, s (although its not a requirement)

migrate_subsystem - migrate Apex/Summit subsystems to Rational subsystems in ClearCase

Syntax

migrate_subsystem [-main_history history] [-log logfile] -use_map map-file subsystems

Description

Migrate a set of Apex/Summit subsystems into one or more ClearCase VOBs, creating a Rational subsystem for each Summit subsystem. A migration map file is supplied as input to the command, which specifies the mapping of Summit subsystems to new Rational Subsystems. migrate_subsystem assumes the following:

migrate_subsystem migrates each Summit subsystem according to the following rules:

migrate_subsystem prints out a summary report, by default to standard output. The -log switch can be used to redirect this summary output to a file.

Parameters

-use_map map-file

Specifies pathname of migration map file. Each line in the file contains the pathname of a source Summit subsystem followed by the name of the destination Rational Subsystem. The source and destination fields are separated by whitespace.

subsystems

Specifies a list of one or more subsystems to migrate.

Related Commands

migrate_view - Migrate Apex/Summit views to ClearCase

migrate_view - Migrate Apex/Summit views to ClearCase

Syntax

migrate_view [-label [-replace] label] [-log logfile] -config_spec filename -branch branch-name -use_map map-file view ...

Description

Creates a config spec to configure ClearCase view equivalent to a set ("tower") of Summit views. migrate_view operates on a "source tower" of Summit views, and a set of Rational Subsystems that have been migrated to ClearCase from source Summit subsystems using the migrate_subsystem command. The source tower is specified on the command line, while the set of Rational Subsystems is specified using the same migration map file that was supplied as input to migrate_subsystem.

migrate_view creates new checked-in versions of the following elements:

All of these were created as controlled elements by the migrate_subsystem command; migrate_view creates new versions of these elements. The new versions are created on the branch named by the branch-name. If this branch type does not exist, migrate_view creates it, and if this branch of the element does not exist, it is created off of /main/0. Otherwise, the new version succeeds the current latest version on the branch. It follows from this that towers representing stable baselines should be migrated in chronological order, from oldest (migrated first) to newest (migrated last). The new element is only created if it would be different than the current latest version on the branch.

migrate_view does not create a new ClearCase view. It produces a config spec containing an element rule for every file and directory element migrated from the source Summit tower.

A config spec generated by migrate_view has the following format:

The per-element rules are element rules that specify the full pathname of the element and the full version identifier for the migrated version.

This config spec can be used as-is to configure a ClearCase view, or it can be modified and/or its contents cut down and used as part of another config spec, or not used at all (for instance, if a label was applied using the -label option, one might write a config spec whose element rules selected elements based on that label).

migrate_view prints a summary of migration activity, by default to standard output. The -log option can be used to redirect this summary output to a file.

Parameters

-branch branch-name

The name of the branch to on which to create new element versions for the directories inside a rss (including .rss directory) and for controlled subsystem characteristic files.

-map map-file

Pathname of the migration map file to use. This should be the same migration map file that was supplied to the invocation of migrate_subsystem that migrated the Summit subsystems whose views are to be migrated. See migrate_subsystem in the Command Reference for more information on migration maps.

-config_spec filename

Pathname of the config spec file to be generated.

view ...

A list of one or more subsystem-relative view names (e.g., joe.rel2.wrk). These view names are applied to the subsystems listed in the map-file to produce a set of Summit views upon which migrate_view will operate. migrate_view reports an error if this set contains more than one view in any Summit subsystem. migrate_view prints a warning if any Summit view in the set does not exist (that is, if any Summit subsystem in migrate_map does not contain one view named in the list of view names).

Related Commands

migrate_diff - compares a RSS and an Apex/Summit view

migrate_subsystem - migrate Apex/Summit subsystems to Rational subsystems in ClearCase

move - moves objects

Syntax

move [options] source... destination

Alias

mvr

Description

Move the source objects to the destination. The effect is that of a copy followed by a delete of the source objects.

Exact semantics depend on characteristics of the objects involved and in general are the same as a copy followed by a delete. Move operations that create new objects are also subject to any restrictions described by the various creation commands.

Parameters

Related Commands

note - adds notes to the versions (Apex/Summit)

Syntax

note [options] files | directories | views...

Description

Adds new notes to versions associated with the objects. Unless an option is provided, takes notes from standard input.

Parameters

Related Commands

parse - performs syntax analysis

Syntax

parse [program_units|directories|views|configurations...] (Ada)

parse [options] files|directories|views|configurations (C/C++)

Description

For Ada, performs syntax analysis on the designated program units. If successful, the units are advanced to the source compilation state. If no arguments are provided, the command proceeds on the current directory.

For C/C++, this command has no predefined effects in the standard model but is available for user customization. For example, this command might be customized to perform syntactic analysis of the specified source files.

Parameters

prepare - this command is available for user customization

Note: This command is only valid with C/C++ build management.

Syntax

prepare [options] files | directories | views | configurations...

Description

This command has no predefined effects in the standard model but is available for user customization. For example, this command might be customized to perform some initial preparation of objects prior to compilation. An example of this may be found in Customizing Build Properties for New File Classes.

Parameters

pretty_print - pretty prints

Syntax

pretty_print [program_units|directories|views|configurations...] (Ada)

pretty_print [options] files|directories|views|configurations... (C/C++)

Alias

pp

Description

For Ada, pretty prints the files using the provided options, while maintaining consistency with the underlying tree. This command creates the DIANA tree if it doesn't exist.

For C/C++, this command has no predefined effects in the standard model but is available for user customization. For example, the command might be customized to reformat the specified source files.

Parameters

properties - shows basic Apex properties

Syntax

properties [options] [files | directories | views | subsystems]

Aliases

props, information, info, show_information, show_info

Description

Shows basic Apex properties about named objects, including the class and other information specific to the class. For example, when applied to views, this provides the model, the location of the physical storage, the release kind (if appropriate), access control characteristics and information about the compiler associated with the view.

The view properties file is held in <view>/.Rational/View_Control/View_Properties.prop.

Parameters

For example, the information displayed for a view would look like the following:

Ada

C/C++

The information shows that the view, /test/lower.ss/rev1.rel, is a stable release, and further shows the model and storage location for the view (which is a remote view).

recover - recovers deleted objects (Apex/Summit)

Syntax

recover [options] files | directories | views...

Aliases

rcvr, undelete, undel

Description

Recovers deleted files to their previous undeleted state.

Note: This applies only to files that were under version control.

Parameters

Related Commands

register - registers the files in the registered set

Syntax

register [options] files...

Description

Registers the named files in the specified set.

Parameters

Related Commands

register_main_program - registers the files as main programs

Syntax

register_main_program [options] files...

Description

Registers the files as main programs by entering them into the main_programs registered set. The files should contain a main entry point. Registration is necessary to apply the link command to the program unit. Registration also prevents the object file associated with the source file from being included in the link of any other main program. Manual main program registration need not be performed when using Apex C/C++ compilers.

Parameters

Related Commands

remodel - changes the model of the library context

Syntax

remodel [options] views | configurations...

Alias

Description

Sets the model to the value designated by the -model option. If no new model is specified, the characteristics associated with models, such as the switches and imports, are re-analyzed. For example, if the COMPILER_KEY or BUILD_KEY switch is changed to specify a new compiler, use this command to perform the processing necessary to deal with the change.

When a new model is specified, all imports associated with the previous model are removed and any new imports associated with the new model are added. The show_imports -verbose command shows the imports associated with the model.

If the model contains directories which are not present in the view then those directories will be added.

You can also use the command to change the kind of a release view.

The -model, -refresh, and -update options are mutually exclusive.

Parameters

Related Commands

remove_domain - removes the reference to the remote domain (Apex/Summit)

Syntax

remove_domain [options] domain...

Description

Removes the reference to the remote domain. This will cause all references to subsystems and views in the remote domain to become orphans.

Parameters

Related Commands

remove_export - removes the exports

Syntax

remove_export [options] program_units | directories | views...

Alias

Description

No longer exports the objects from their enclosing views.

Parameters

Related Commands

remove_import - removes imports

Syntax

remove_import [options] importers... [old_imports...]

Alias

rmmp

Description

Removes imports from the importer view. When the -mutual option is specified, all arguments are used as importers to be updated. Otherwise, the first argument specifies the importer to change and the other arguments name the imports to remove. When the -mutual option is not specified, the first parameter may name a view, a configuration, or a wildcard expression (in quotes) that resolves to a set of views or configurations.

The -unreachable and -mutual options are mutually exclusive.

To remove all imports from a view, do the following:

Parameters

Related Commands

report - generates a report

Syntax

report [options] files | directories | views | subsystems...

Description

Generates a report about the specified objects. The format of the report is specified by either the -format or -format_file options. The format may be specified using keyword replacement symbols.

Parameters

Example

The following command will generate a report containing the simple name of each object in the current directory followed by the version control state of the object:

resolve_ada_name - resolve Ada name in specified context

Syntax

resolve_ada_name [-context configuration|context] [-file_mode] ada_name

Description

Resolves the specified name in the given context and displays all the places where this name is defined. The name may refer to an overloaded function name or contain wildcards. In this case all the matching declarations are shown. This command is useful to find the place where a given Ada unit visible in the current closure is located. The specified Ada name must be in an unit that is at least in the installed state.

Parameters

Examples

1 . resolve_ada_name text_io.put_line

Example output for this command is shown below.

Note: The command can only find resolutions in Ada units that are at least in the installed state.

rreport - report problems, make suggestions, request license renewal

Syntax

rreport [options]

Description

This tool enables Apex customers to more easily and quickly report problems and suggestions to Apex Technical Support.

The rreport tool prompts the customer for the problem description and automatically includes required Apex data (version, patches, installation log) to the report sent to Apex support. In addition, a case in Vantive is automatically created when rreport is used to report problems/make suggestions to Rational. If generated files are greater than 99000 bytes, and e-mail is available, ftp the file and e-mail support the location of files. If you are on a classified system or otherwise do not have internet connectivity, you will be given an opportunity to create a directory with the information. This directory can be reviewed before sending it to Rational. You can then move the directory to another system to be ftp'd or e-mailed.

Parameters

set_attribute - set an extended attribute value (Apex/Summit)

Syntax

set_attribute [options] [files | directories | views...]

Description

Sets an extended attribute value on the designated versions.

Parameters

set_history - changes the version history file used (Apex/Summit)

Syntax

set_history [options] history files | directories | views...

Alias

Description

Changes the version control characteristics of files to enable them to use the specified history. Can also be used to change the default history associated with a view. If an object does not currently exist in the destination history, a new object will be created in that history. The -match, -create, and -latest options are mutually exclusive.

Parameters

Related Commands:

set_location - sets the permanent name (Apex/Summit)

Syntax

set_location [options] directories | subsystems | views...

Alias

Description

Establishes the permanent name of the named object. The argument must resolve to a subsystem, view, or a directory outside of a subsystem. This name is used whenever it refers to the object.

Subsystems and views are always given permanent names when they are created. As a result, this command should only be applied to subsystems and views when they have been broken, for example, if the .Rational_Location symbolic link was deleted or if it contains a path that can no longer be resolved.

This command may be run on directories outside of subsystems to give them a permanent name because those directories do not usually have a permanent name. This can be useful in that the permanent name of subsystems created in those directories will be based on the permanent name of the directories. For example, set_location is used to give a permanent name to /ned/sierra/docs. Now, if a subsystem is created in this location, for example, apex_docs, that new subsystem will have the permanent name /ned/sierra/docs/apex_docs.ss.

Parameters

Related Commands

set_switch - changes the values of the specified context switches

Syntax

set_switch [options] name1 value1 [name2 value2...]

Alias

setsw

Description

Changes the value of the given context switches.

Parameters

Related Commands

set_version - change the version of controlled objects (Apex/Summit)

Syntax

set_version [options] files | directories | views...

Aliases

revert, setver

Description

Changes the version of controlled files. Specifying a source view is the same as accepting changes from the view, however there is no restriction that the source version is later than the current version.

Parameters

Related Commands

show_domains - shows information about the remote domains (Apex/Summit)

Syntax

show_domains [options] [directories | views | subsystems...]

Description

Shows information about the remote domains. By default, lists the names of any remote domains and whether they are currently accessible. If the -verbose option is set, the command also provides information for the specified directories, views, subsystems, and their children. In particular, the command shows which of these objects are in a remote domain and which are in the local domain.

Parameters

Related Commands

show_exports - shows the exports

Syntax

show_exports [options] [views...]

Aliases

show_xp, shxp, show_xps

Description

Shows the exports of the views. If no views are provided, the exports of the enclosing view are shown. The contents of the specified export set are displayed.

Parameters

Export Output

Export information has the following format:

Current View: <view-name> Set: <export-set-name>


Current Exports
Status
<unit-name>
<status>
.
.
.
.


Diagnosis of Current Export State
<diagnostic information>

The first lines show the view and the export set being displayed.

The Current Exports field shows the name of the units currently exported.

The Status field represents the current state of the exported units. The possible values for this field are:

The Diagnosis of Current Export State field provides information about the current state of this export set. For example, if the export set description file has been updated, but the exports have not been refreshed, this will be noted in the diagnostic field.

Below is an example of export information:

Ada:

Current View: /test/lower.ss/tom.wrk


Set: general



Current Exports
Status
buffer.1.ada
Valid
list.1.ada
Valid
queue.1.ada
Deleted
stack.1.ada
Valid

C/C++:

Current View: /test/lower.ss/tom.wrk


Set: general



Current Exports
Status
buffer.h
Valid
list.h
Valid
queue.h
Deleted
stack.h
Valid

In the example, no diagnostic information is displayed because all export files are up-to-date.

Related Commands

show_histories - shows the histories being used (Apex/Summit)

Syntax

show_histories [options] [views | subsystems...]

Aliases

show_history, shhst

Description

Show the histories declared and used by subsystems and views. If subsystems are specified, all the histories declared in the subsystem are listed. If views are specified, the histories used by the views are listed.

Parameters

Related Commands

show_imports - shows the imports of the views

Syntax

show_imports [options] [views | configurations...]

Aliases

show_mp, shmp, show_mps, mps

Description

Shows the imports of the views. Shows both the explicit and implicit imports. If no views are given, the imports of the enclosing view are displayed.

Parameters

Verbose Import Output

Verbose import information has the following format:

Current View: <view-name>




Current Explicit Imports
Status
Kind
Export_Set
<explicit-import-name>
<status>
<kind>
<export-set-name>
.
.
.
.
.
.
.
.




Current Implicit Imports
Status


<implicit-import-name>
<status>


.
.


.
.


Diagnosis of Current Import State
<diagnostic information>



The Current Explicit Imports field and the Current Implicit Imports field display views that are explicit or implicit imports of the current view.

The Status field represents the current state of the imported views. The current view has valid imports only if the status of each imported view is valid. The possible values of this field are:

The Kind field provides information about the type of import and possibly how it was provided to the current view. The values are:

The Export_Set field displays the export set being used for each imported view.

The Diagnosis of Current Import State field provides the following information:

The following is an example of verbose import information. In this example, there is a view named tom.wrk in each subsystem base.ss, lower.ss, middle.ss, and upper.ss. The example shows the import information for upper.ss/tom.wrk, which imports from the other views.

Current View: /test/upper.ss/tom.wrk




Current Explicit Imports
Status
Kind
Export_Set
/test/middle.ss/tom.wrk
Valid
Normal
all_units
/test/lower.ss/tom.wrk
Valid
Normal
all_units




Current Implicit Imports
Status


/test/base.ss/tom.wrk
Valid






Diagnosis of Current Import State
Import state is currently valid.
Import state was last successfully updated by tom on 06/17/96 08:12:02

System Mode Output

When showing import information in system mode, the information is displayed for each designated view and for the entire set of imports of each designated view. Each view is assigned an import number used within the output. The import numbers are assigned in such a way as to represent the partial order of import relationships.

<number>
<view-name>


Current Explicit Imports
<number>
<explicit-import-name>

System mode information can also be displayed in a verbose format that includes status information in the output.

Related Commands

show_location - displays the permanent name

Syntax

show_location [files | directories | views | subsystems...]

Alias

shloc

Description

Displays the permanent name for the designated objects.

Parameters

Related Commands

show_locks - shows the locks

Syntax

show_locks [directories | views | subsystems...]

Aliases

shlock, locks

Description

Shows the locks, both active and abandoned, in the specified contexts. If no objects are specified. the locks associated with the context of the current directory are displayed.

Parameters

Related Commands

show_main_programs - displays the registered main programs

Syntax

show_main_programs [options] views...

Description

Displays the registered main programs in the designated views.

Parameters

Related Commands

show_status - shows the version control status (Apex/Summit)

Syntax

show_status [options] [files | directories | views...]

Aliases

Description

Shows the version control status for the designated files. The version control status includes the history, version number, and check-out status.

Most of the options for this command (that is, -deleted, -uncontrolled, -checked_out, -checked_out_other, -checked_in, and -out_of_date) provide filters you can use to select objects with the designated characteristics. If no specific options are given, -checked_out and -checked_in are assumed.

Parameters

Related Commands

show_switches - displays the switches

Syntax

show_switches [options] [directories | views | subsystems | property_switch_file ...]

Aliases

shsw, switches

Description

Shows the switches associated with the specified objects. If no objects are specified, the switches associated with the current context are displayed.

Parameters

Related Commands

show_unused - show unused declarations

Syntax

show_unused [-in_context] [-search_closure] [-file_mode] unit

Description

This command shows all the unused declarations within a given unit. The specified scope is examined to calculate usages of the declarations within the specified unit. If no scope is specified, the current view is taken as the scope. The Ada unit specified, as well as the Ada units in context, must be at least in installed state for this command to show the unused declarations correctly.

Parameters

Examples

1 . show_unused hello.2.ada

Shows the unused declarations in hello.2.ada. The -file_mode parameter is correctly inferred by the command.

2 . show_unused -in_context /users/test.ss/my_view.wrk "text_io'spec"

Shows all declarations of Text_Io'Spec not used in the specified view.

Note: The unit name must specify an Ada unit that is at least in the installed state. The Ada units in context must be in the installed state for this command to show unused declarations correctly.

show_usage - show line and character positions within Ada units

Syntax

show_usage [options] ada_name

Description

Shows the lines and character positions within Ada units that use a specified declaration. All the places where the given ada_name is used within the specified scope are displayed. If no scope is specified, the current view is taken as the scope. The Ada units in context must be at least in installed state for this command to identify the usages in those units.

Parameters

Examples

1 . show_usage text_io.put_line

Shows the usages for Text_Io.Put_Line in all Ada units in the current view.

2 . show_usage text_io hello.2.ada

Shows all usages of Text_Io in the file hello.2.ada

Note: ada_name must specify a declaration in an Ada unit that is at least in the installed state. In addition, the Ada units in scope must be in the installed state for this command to show usages correctly.

show_versions - shows information about the versions

Syntax

show_versions [options] files | directories | views...

Aliases

Description

Note: For Apex/ClearCase, the cleartool lsvtree command is used. The description provided here is only valid for Apex/Summit. Please see the ClearCase documentation for a description of this command.

Shows information about the versions of the listed objects. The output of this command lists each requested version and provides information about the time, date, view, and user for check out and check in of the version.

Parameters

Related Commands

show_version_image - generates the image of the specified version (Apex/Summit)

Syntax

show_version_image [options] files | directories | views...

Aliases

shvi, version_image

Description

Generates the image of the specified version.

Parameters

Related Commands

test - this command is available for user customization

Note: This command is only valid with C/C++ build management.

Syntax

test [options] files | directories | views | configurations...

Description

This command has no predefined effects in the standard model, but is available for user customization. For example, this command might be customized to run a test suite on the executables in the view.

Parameters

tree - display Diana tree of an Ada object

Syntax

apex tree [options] <file_name>

Description

Displays the Diana tree of the specified Ada object.

Arguments

uncontrol - removes the objects from version control (Apex/Summit)

Syntax

uncontrol [options] files | directories | views...

Alias

Description

Removes the objects from version control. The objects no longer needs to be checked out to be modified.

Parameters

Related Commands

unregister - removes the files from the registered sets

Syntax

unregister [options] files...

Description

Removes the files from the specified sets.

Parameters

Related Commands

unregister_main_program - unregisters the files

Syntax

unregister_main_program [options] files...

Description

Removes the files from registration as a main program.

Parameters

Related Commands

unset_attribute - reset an extended attribute value (Apex/Summit)

Syntax

unset_attribute [options] [files | directories | views...]

Description

Resets an extended attribute value on the designated versions. When an attribute value is reset it has a null value appropriate to its type. For example, string valued attributes will act as if the value is set to the empty string while integer valued attributes will act as if the value were 0.

Parameters


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2002, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS