![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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
- files | directories | views
Specifies the checked-out objects to be abandoned.
- options
Specifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseExpand any configuration arguments.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that compilation artifacts should not be copied with source files.
Default value: falseSaves the contents of each checked-out file in a .saved file. The file is saved only if it has been modified.
Default value: falseSpecifies that the command should emit additional informational output.
Default value: falseRelated 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:
% apex accept_changes -source tom.wrk integration.wrk
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
- files | directories | views
Specifies the destination objects to which changes will be propagated.
- options
Note: Multi-valued options must be enclosed in quotes.
-accept_changes_source latest | objects | history
Specifies the kind of source to be used by the command. This option is only examined if no explicit source is provided by the -latest, -source, -source_task, -source_version or -source_history options. When the option is examined then the source of the command is determined in the following way:
- When the value is latest that all existing objects are updated to the latest version of their respective histories and no new objects are added.
- When the value is objects then the default value of the -source option is accepted from.
- When the value is history then the default value of the -source_history option is examined to determine a set of source histories to accept from. The histories are subject to the normal left-to-right precedence rules.
This option is mostly used to establish default behavior when no explicit source value is provided. In particular, since the default values is based on a context switch the default source can be set on per-view basis.
Default value: "<view'switch(VC_ACCEPT_CHANGES_SOURCE)>"-all_artifacts
Specifies that artifacts in the source view, that are not older than the artifacts being copied (an artifact associated with the file being copied), and whose associated file in the source and destination views are the same controlled file (version and history) to also be copied.
This option is not for the casual user. It allows all artifacts to be copied over to the destintation view and prevent recompilations, requiring only program_library refresh.
This option is mutually exclusive with the -no_artifacts option.
Default value: falseSpecifies how the history of existing controlled objects is allowed to change. Histories listed first are given higher precedence than histories listed later. Changes are only allowed from lower precedence to higher precedence histories. When the special value all is used then all history changes are allowed and all have equal precedence.
Default value: "<view'switch(VC_ACCEPTABLE_HISTORY_CHANGES)>"Specifies that deleted objects are allowed to freely change their history during change propagation. When this option is not set and a view contains a deleted object on one history and changes are accepted from another view with a corresponding object on a different history then the deleted object will not be changed. However, when this option is set, the deleted object will be changed to be reference the history and version of the corresponding source object.
Default value: falseSpecifies that uncontrolled destination objects can be updated by controlled source objects. If this option is not set then controlled source objects will not overwrite uncontrolled destination objects.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that source files that do not exist in the destination will not be created.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command. the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecThis options provides a way to filter the destination objects which will be updated. In particular, destination objects will only be updated if their history matches one of the histories named in this option. The special value all, which is the default, signifies that all objects should be updated regardless of their history.
Default value: allSetting this option will cause the command to be run in reconstruction mode rather than integration mode.
You use this option when you wish to make the destination objects identical to the source regardless of their current state. For example, this option can be used to make a destination view be identical to a source view.
Default value: falseDo not check or do model related processing.
Does not do host specific processing (like apex delete of a file will not remove object, sienna, or diana files).
Specifies that all destination objects will be updated to the latest version.
Default value: falseNew controlled files are introduced into destination views only if the history of the new files matches one of the histories named in this option. The special value all may be used to signify that all histories are allowed and all histories have equal precedence when new objects are being accepted.
Default value: "<view'switch(VC_ACCEPTABLE_HISTORIES)>"Specifies that compilation artifacts should not be copied with source files.
Default value: falseSpecifies that all version control context switches should be copied from the source view to the destination view. This option is only applicable when accepting changes between views. Note that when this option is applied, the version control context switches are copied into the destination prior to propagating other changes so that the new context switch values will have an effect on the propagation.
Default value: falseIf set and an uncontrolled object is updated by a controlled object, the original contents of the uncontrolled object are saved.
Default value: false-strict
If set, will prevent the acceptance of deleted versions, including from histories with a higher precedence.
Default value: falseSpecifies that the destination objects will be updated to versions associated with these source files or views.
Default value: "<view'switch (VC_ACCEPT_CHANGES_SOURCE_OBJECTS)>"Specify a set of histories from which to accept changes. When histories are accepted the latest version of the source history is accepted for destination object. If multiple histories are specified they are processed based on the precedence established by the -new_history and -change_history options. In addition to actual history names or the value of switches a number of special history names may be used as the value of this switch. In particular, if the special history name current_history is used then changes will be accepted from all of the histories currently associated with the view.
Default value: "<view'switch(VC_ACCEPTABLE_HISTORIES)>"Only available when Summit/TM is installed.
Specifies that the destination objects will be updated to versions associated with the named tasks. See Summit/TM documentation for details and other options that apply when changes are propagated from tasks.
Default value: " "Specifies that the source of the command is to be a specific version or versions. If full_version names a file then full version names are read from the file one per line. If full_version does not name a file then it must be a string containing a full version name.
Default value: " "Specifies that the command should emit additional informational output.
Default value:falseRelated 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
- destination
Specifies the directory or subsystem to be updated. Remote references are added and removed only within the context of the destination.
- options
Command line option always take precedence over the settings in the Policy/Switches file.
Reports the effect of the command but does not make any changes.
Default value: falseDo not add any references to new subsystems or views.
Default value: falseDo not remove any references to orphaned subsystems or views.
Default value: falseSpecifies the names of remote directories that will not be searched for additions and the names of local directories that will not be searched for orphans to remove.
This option can also be set in the local source tree's switch file.
Default value: " "Specifies the names of remote directories that can be searched for subsystems to add. Also used to specify the names of local directories that can be searched for orphaned objects to remove.
This option can also be set in the local source tree's switch file.
Default value: "*"Specifies the names of directories that will be created as remote links and will not be searched. (Can also be set as a context switch in the Policy/Switches file)
Default value: " "Specifies the names of remote subsystems that will not be searched for additions and the names of local subsystems that will not be searched for orphans to remove.
This option can also be set in the local source tree's switch file.
Default value: " "Specifies the names of remote subsystems to which references can be added and the names of local subsystems that can be searched for orphaned objects to remove. Also used to specify subsystems in which new view references can be added and orphaned view references can be removed.
This option can also be set in the local source tree's switch file.
Default value: "*.ss"Specifies the names of views to which remote references will not be added. (Can also be set as a context switch in the Policy/Switches file)
Default value: " "Specifies the names of remote views to which references can be added or removed.
This option can also be set in the local source tree's switch file.
Default value: "*.wrk *.rel"Specifies the name of the domain from which the destination will be updated. The two options provide alternative ways to specify the same thing. If -source is non-empty, its value is used. Otherwise the value of -domain is used.
The special value all_domains specifies that changes from all known domains should be accepted.
Default value (of -domain): all_domains
Aliases: -domainRelated 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:
- all is a special name that indicates that every export set in the source view should be processed.
- default_export_set is a special name that indicates that the default export set in the source view should be processed.
Parameters
- options
Create the target export set if it does not exist.
Does not actually do anything.
The target export set is made identical to the source export set. This option has precedence.
A source a file that does not exist in the target view is not added to the target export set.
Deals only with the original exports of the target export set.
- a file not in the source export set is removed from the target export set
- a file previously in the target export set, that does not exist in the target view, is removed from the target export set.
Specifies the export set to process. Multiple export sets may be specified by quoting a whitespace separated list of export set names.
-source views_or_configurations
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
- views | configurations
Specifies the views that will be updated with new imports.
- options
Reports the import changes that would be made, but does not actually make any changes.
Default value: falseMakes the imports of the destination identical to those of the source. This may result in imports being removed. When the option is not set, new imports are added but no imports are removed.
Default value: false-import views_or_configurations
Specifies additional views to search in looking for imports.
Default value: " "Specifies that views with the same name should not be considered as candidates.
Default value: falseSpecifies that imports of the source view should not be considered as imports of the destination views.
Default value: false-source views_or_configurations_or_system_descriptions
Specifies the source views from which to accept the changes. A non-empty value must be specified for this option.
Default value: " "Specifies that the imports should be changed to "strictly" match the destination and designated import sets. Existing imports are removed if they do not name a view specified in the destination set or by the -import option.
Default value: falseRelated 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.
- options
Specifies that source files that do not exist in the destination will not be created.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command. the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecThis options provides a way to filter the destination objects which will be updated. In particular, destination objects will only be updated if their history matches one of the histories named in this option. The special value all, which is the default, signifies that all objects should be updated regardless of their history.
Default value: allNew controlled files are introduced into destination views only if the history of the new files matches one of the histories named in this option. The special value all may be used to signify that all histories are allowed and all histories have equal precedence when new objects are being accepted.
Default value: "<view'switch(VC_ACCEPTABLE_HISTORIES)>"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
- name
Specifies the simple name of the remote domain being referenced.
- options
Specifies the name of the directory that is the root of the remote domain's source tree. This should not be the logical name of the source tree (that is, this should not have the same value as the -root option). This should be the name of the storage directory of the remote domain's source tree root directory.
Default value: " "Specifies the root of the source tree in the current domain. If no value is specified, the enclosing source tree is used.
Default value: " "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
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.
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
- program_units | directories | views | configurations (Ada)
files | directories | views | configurations (C/C++)Specifies the units to be analyzed.
- options
In library contexts which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the library context will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the library context contains Java and C/C++ units to compile. The default value in a particular library context can be changed by setting the BUILD_COMPONENT context switch in the library context.
Default value: cpp-closure installed | coded | linked (Ada)
Determines additional units to be analyzed. The empty string (" ") is equivalent to specifying installed. If the -configuration option is specified, the closure set is computed from units in the library contexts of the configuration. Otherwise, the set is computed from units in the imported library contexts.
Default value: " "-configuration configuration (Ada)
Specifies configuration used to compute a closure set. Can be used to specify units to analyze beyond those found in the analyze closure in the imported library contexts. This option only has an effect if the -closure linked option is also specified.
Default value: " "Specifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIndicates whether compilation is to continue past the first unit with errors. If set, processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported library contexts of the specified objects. The imported library contexts are processed in the import order so that library contexts which have no imports are processed first.
Default value: false-make_options make-options (C/C++)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Default value: falseSpecifies that the command should emit additional informational output.
Default value: falseapex_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:
apex_BOM -verbose -fmt 3 <exe>To provide minimal machine readable info:
apex_BOM -nosw -nohdrs -fmt 2 <exe>Parameters
- options
<n> The format style
1 indented lines
2 comma separated lines
3 table format
9 tower save format
<n> The level of information
<0 same as 0
0 exe closure objects
1 0 + switches
2 1 + library names
3 2 + library closure objects
4 3 + view names
5 4 + view controlled objects
>5 same as 5
The level of debug information
No closure objects will be displayed; overrides the detail level.
No header information; supresses extraneous information.
No switch information; overrides the detail level.
Dump info on the exe full name of view objects ls -l on exe and libs.
-views
Assumes views are supplied and processes the views as if they were the closure of a single executable. This option is intended for use but the apex_TWR command.
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_BOM -fmt 9 <exe> > /a/b/v.wrk_exe.tower
apex_TWR /a/b/*.ss/v.wrk > /a/b/v.wrk.towerapex_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.
apex_TWR -recreate /a/b/v.wrk.towerParameters
- options
-effort
Supply list of views to be reconstructed, without doing any actual reconstruction.
-recreate tower_description_file
Recreate a tower from a previously created tower description file.
-storage storage_location
Specifies the storage location for the restored views.
views
List of views to process.
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:
- Updates switches.
- Updates imports.
- Deletes and recreates .Rational/Compilation and .Rational/Imports_Control (unless the -no_cleaning option is set).
- Remodels all specified views (skips views for which you do not have write permission).
Parameters
- what_to_upgrade
For what_to_upgrade, provide the directory names of each subsystem, view, and/or the file name of any configuration.
- Views (must have the suffixes .wrk or .rel)
- Subsystems (must have the suffix .ss)
- Configuration files (must have the suffix .cfg). Each configuration must contain a list of one or more fully-qualified directory views.
The object's simple name is sufficient if it resides in the current directory; otherwise, provide the full pathname. You can list multiple objects, separated by spaces, and you can use shell wild cards such as asterisk (*) and question mark (?). You can mix the list of subsystems, views and configurations.
If you specify a subsystem, all views within that subsystem will be upgraded. The -skip_* options below can be used to omit views you do not want to upgrade.
Note: Mutually imported views must be upgraded together.
- options
Effort only. Shows the subsystems and views to be upgraded, and the changes that would take place to Policy/Switches files and Import files.
Verbose mode. Show more information about changes taking place.
Create model map file. This must be done before actual upgrade can take place. See discussion below about removing UNKNOWN entries from map file.
Do actual upgrade. Must also specify -pass option.
Do pass 1, pass 2, or both. See discussion below for what happens during each pass.
Attempt to upgrade views based on pre-3.0.0 models. See discussion below on "Upgrading very old views" for more information.
Restore views to state before they were upgraded. Does not restore compilation artifacts.
Remove state files that were created during upgrade. These state files are needed if user wishes to run -restore option.
Show usage, and detailed documentation if available.
Do not upgrade Policy/Switches files. Only applies during pass 1.
Do not remodel views. Only applies during pass 1.
Do not remove compilation artifacts. Only applies during pass 1.
Do not update imports. Default is to update imports to views from the latest release. Only applies during pass 1.
Do not compile any views. Default is to compile where possible. Only applies during pass 2.
If a view's Compiler Key or Build Key switch is set to a non-Rational value, change the switch to match the value in the new Apex model. Default is no leave non-Rational values as they are. Only applies during pass 1.
-skip_ada83
-skip_ada95
-skip_cpp
-skip_rciThese options remove various categories of views from the list of views being upgraded.
If a view contains a .Rational/Rci directory, it is considered to be an rci view.
If a view's language matches the expression *C++, it is considered to be a C++ (cpp) view.
If a view contains an import that matches the expression */lrm.ss/*ada95* it is considered to be an Ada 95 view.
If a view contains any other lrm.ss import, it is considered to be an Ada 83 view.
This option removes specific views from the list of views being upgraded. You can explicitly specify a single <view>. Alternatively, you can specify a <file> that lists one view per line. You can use the -skip_view option multiple times.
This option is obsolete, and remains for backward compatibility with other internal apex scripts.
There are four basic actions that can be done with apex_upgrade:
- Create a model map
- Do the upgrade (using the model map)
- Revert (to pre-upgrade state)
- Commit (remove files needed to Revert)
These actions correspond to the following four options:
-create_model_map <map>
-use_model_map <map>
-revert
-commitThe 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:
- updates Policy/Switches
- updates Imports
- cleans views
- remodels views based on new models
Pass 2 performs the following operations:
- remodels views (if run separately from pass 1)
- compiles views
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.
- The Policy/Switches file.
Policy/Switches.pre_$APEX_PROD_VERSION.upgrade
- The Imports/*.cfg files.
Imports/*.cfg.pre_$APEX_PROD_VERSION.upgrade
- The view's current model.
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 2 replaces instances of UNKNOWN in /tmp/model_map
Step 3 confirms that there are no expected problems performing 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:
apex_upgrade -create_model_map /tmp/model_map [options] what_to_upgrade ...
- 4 . Edit model map.
Replace any instances of UNKNOWN with valid models.
- 5 . Upgrade the appropriate subsystems using the following command:
apex_upgrade -use_model_map /tmp/model_map -pass both [options] what_to_upgrade ...
% apex_upgrade -use_model_map /tmp/model_map -pass both -skip hold.wrk open_door.ssThis 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:
apex_upgrade -create_model_map /tmp/model_map [options] what_this_user_can_upgrade ...
vi /tmp/model_map (replace any instances of UNKNOWN)
apex_upgrade -use_model_map /tmp/model_map.$USER -pass 1 [options] what_this_user_can_upgrade ...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:
apex_upgrade -create_model_map /tmp/model_map [options] full_list_to_upgrade ...
vi /tmp/model_map (replace any instances of UNKNOWN)
apex_upgrade -use_model_map /tmp/model_map -pass 2 [options] full_list_to_upgradeThe 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
- files | directories | views | configurations
- options
Specifies a sequence of other commands to be applied to the view. The value of this option may be any fragment of code written in "Apex Shell" or C-shell (see the "Scripting Language Guide" for a description of Apex Shell). The default value specifies that the current view and all imports are to be prepared and then compiled. The default value in a particular view may be changed by setting the value of the BUILD_PHASES context switch.
Default value: "apex prepare -imports <view>; apex code -imports <view>"In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falsebuild_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
- api_view
Name of the API view to be created (API destination view). The api_view is where the API is built. Any contents of that view are destroyed and replaced with the API specification. As a safety measure, api_view must be an already empty view or a view whose BUILD_POLICY switch has the value API.
- source_views
Name(s) of the views to included in the API view being created (API source view(s)). source_views is the collection of Ada and C views that will make up the API. source_views may include one or more configuration files (with the suffix .cfg), in which case the views named by those files will be included.
The import closure of the source views must not contain two different views of the same subsystem. If there areany mutually importing views among the source views, all the mutually importing views of that set must beincluded. The source views must all have the same compiler key. None of them can be RCI views or API views.They all must be the same language dialect, Ada 83 or Ada 95.
- options
The API builder will not attempt to compile any C views among the source view unless this switch is set.
Suppress the copying of the diana trees from the source views. For large APIs the diana trees can be quite large, so that this option can save disk space. However, this option can only be used to construct an API view if the view, and any API views that import it, contain in the published spec no inlined routines or replicated generics whose bodies are not published. The ability to use the -lightweight option is one reason for putting pragma API on a body. This restriction is not checked by the API builder, so caveat emptor.
The object files in the source views are copied into a UNIX archive, and a shared_library if the -shared_library option is specified. If a name is given after the option, that name is used for the shared library. The actual library name is derived from <name> using the same conventions used by the CREATE_SHARED_LIBRARY switch. By default, the name used is libname.so, where <name> is the simple subsystem name of the API view.
If -shared_library is specified, the CREATE_SHARED_LIBRARY switch must be present in all the source views.
Causes the API builder to ignore all the pragma APIs in the source view, and produce an API with an empty specification.
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:
package P is package Q is procedure Has_Body; procedure Missing_Body_1; end Q; end P;
package body P is package body Q is separate; end P;
separate (P) package body Q is procedure Missing_Body_2; procedure Has_Body is ... end Q;
When the specification of P is examined, build_bodies detects that P.Q.Missing_Body_1 has no body, and will incrementally insert a body for it in the unit P.Q'Body. However, no body is inserted for P.Q.Missing_Body_2.
- 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.
- Application to a Child Unit
Build Body may be applied to a child unit. Say that we execute Build Body on the following specification:
package Geometry.Circle is type Object is private; function Create (Center : in Point; Radius : in Float) return Circle.Object; private type Object is null record; end Geometry.Circle;
14:32:40 +++ Created new unit GEOMETRY.CIRCLE'BODY package body Geometry.Circle is function Create (Center : in Point; Radius : in Float) return Circle.Object is begin [statement] end Create; end Geometry.Circle;
- Application to Protected Units, Protected Type Declations and Entry bodies
Running Build Body on the following declaration:
protected type Counter is procedure Increment; procedure Decrement; function Value return Integer; entry Wait (For_Value : Integer); private Current : Integer := 0; end Counter;
results in the following body:
protected body Counter is procedure Increment is begin [statement] end Increment; procedure Decrement is begin [statement] end Decrement; function Value return Integer is begin [statement] end Value; entry Wait (For_Value : Integer) when [Boolean-expression] is begin [statement] end Wait; end Counter;
Parameters
- scope
Identifies the Ada units, directories or views in which build_bodies is to examine Ada units and fill in needed bodies.
- -visit
Causes the units in which bodies were built to be visited. This is the default if neither -visit nor -no_visit is specified.
- -no_visit
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:
package Geometry is type Point is private; Origin : constant Point; function Translate (P : in Point; Dx, Dy : in Float) return Point; private type Point is record X, Y : Float; end record; Origin : constant Point := (0.0, 0.0); end Geometry;
14:15:57 +++ Created new unit GEOMETRY'BODY package body Geometry is function Translate (P : in Point; Dx, Dy : in Float) return Point is begin [statement] end Translate; end Geometry;
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:
package A is package B is package C is procedure D; end C; end B; end A; package body A is package body B is package body C is procedure D is begin [statement] end D; end C; end B; end A;
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:
package Geometry is type Point is private; Origin : constant Point; function Translate (P : in Point; Dx, Dy : in Float) return Point; function Distance (P1, P2 : in Point) return Float; private type Point is record X, Y : Float; end record; Origin : constant Point := (0.0, 0.0); end 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):
14:20:18 +++ Added new body GEOMETRY.DISTANCE'BODY package body Geometry is function Translate (P : in Point; Dx, Dy : in Float) return Point is begin return (P.X + Dx, P.Y + Dy); end Translate; function Distance (P1, P2 : in Point) return Float is begin [statement] end Distance; end Geometry;
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:
package body Geometry is function Translate (P : in Point; Dx, Dy : in Float) return Point is begin return (P.X + Dx, P.Y + Dy); end Translate; function Distance (P1, P2 : in Point) return Float is separate; end Geometry;
Then running Build Body on geometry.1.ada causes the creation of a subunit for Distance:
15:52:12 +++ Created new unit GEOMETRY.DISTANCE'BODY separate (Geometry) function Distance (P1, P2 : in Point) return Float is begin [statement] end Distance;
check_in - checks in the objects
Syntax
check_in [options] files | directories | views...
Aliases
checkin, in, ckin, check_in, ciDescription
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
- files | directories | views
- options
Allows files with merge annotations to be checked in. Normally, such files cannot be checked in until the annotations have been removed.
Default value: falseSpecifies the name of a file containing attribute settings which will be set on the checked in version.
Default value: " "Specifies that name of an extended attribute whose value will be set on the checked in version.
Default value: " "Specifies the value of the extended attribute which will be set on the checked in version.
Default value: " "Uses a compress/uncompress algorithm when storing the file(s) in the cmvc database.
The apex difference command will NOT work on files stored with this attribute. It is intended for use when binary data (e.g., executables) must be controlled.
This option must be set on the command line; the APEX_COMPRESSED environment variable is for use only with the difference command.
Default value: falseIf the object is currently uncontrolled, makes it controlled as though the control command was run. If not set, only checked-out objects are processed.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecInhibits the replacement of keyword substitution strings. When this option is set, substitution symbols are left in their original form. This option is especially useful for controlling binaries or data files.
Default value: falseSimply records the file in the cmvc database.
The apex difference command will NOT work on files stored with this attribute. It is intended for use when binary data like executables must be controlled. This option must be set on the command line.
Default value: falseEnters the text as a note associated with new version.
Default value: " "Enters the contents of the file as a note associated with the version.
Default value: " "Specifies that list valued attributes are to be replaced rather than have a new value appended to the existing value.
Default value: falseSpecifies that all changes associated with a task are checked in.
Default value: " "Attributes will be reset for the versions associated with the task.
Default value: " "Specifies that a privately checked-out file is to be checked in even if the private check out is not based on the latest version. This is useful when a private check out has been reconciled through the merge command and the new contents should be checked in.
Default value: falseSpecifies that the command should emit additional informational output.
Default value:falseRelated 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
- files | directories | views
The objects to be checked out.
- options
Specifies the name of a file containing attribute settings which will be set on the checked in version.
Default value: " "Specifies that name of an extended attribute whose value will be set on the checked out version.
Default value: " "Specifies the value of the extended attribute which will be set on the checked out version.
Default value: " "Uses a compress/uncompress algorithm when storing the file(s) in the cmvc database.
The apex difference command will NOT work on files stored with this attribute. It is intended for use when binary data (e.g., executables) must be controlled.
This option must be set on the command line; the APEX_COMPRESSED environment variable is for use only with the difference command.
Default value: falseIf the object is uncontrolled it will be made controlled and then checked out.
Default value: falseIf the file is currently check out with a reservation then convert the check out to a private check out.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseIf the current version is not the latest, allows the check out to succeed without updating the file to the latest version.
Default value: falseUpdates the contents of the object to correspond to the latest version. If the file does not have the latest version, the operation fails if this option (or -keep_current) is not set.
Default value: false-no_keyword_replacement
Inhibits the replacement of substitution strings. When this option is set, substitution symbols are left in their original form. Applies to cmvc versions being created (controlled).
Default value: falseSimply records the file in the cmvc database.
The apex difference command will NOT work on files stored with this attribute. It is intended for use when binary data like executables must be controlled. This option must be set on the command line.
Default value: falseEnter the text as a note associated with the check-out version.
Default value: " "Enters the contents of the file as a note associated with the version.
Default value: " "If not set, the check out acquires reservations. If set, the check out will be private to the view and not acquire reservations.
Default value: falseSpecifies that list valued attributes are to be replaced rather than have a new value appended to the existing value.
Default value: falseAttributes will be reset for the versions associated with the task.
Default value: " "If the file is already checked out privately, changes the check out to one with a reservation. Succeeds only if there is no current reservation on the history of the file.
Default value: falseSpecifies that the command should emit additional informational output.
Default value:falseRelated 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
- files | directories | views | configurations
The source files to be checked.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: false-make_options make-options (C/C++ only)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseclean - removes compilation artifacts
Syntax
clean [options] [program_units|directories|views|configurations...] (Ada)clean [options] files|directories|views|configurations... (C/C++)
Description
Removes artifacts of compilation to reduce the specified files to the provided goal state. If no objects are provided, the current directory is processed.
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
- program_units | directories | views | configurations (Ada)
files | directories | views | configurations (C/C++)For Ada, specifies the program units to be cleaned.
For C/C++, specifies the objects to be cleaned. When individual source files are cleaned, compilation artifacts associated with those source files are removed. When directories or views are cleaned, all compilation artifacts in the directories, views, and all subdirectories are removed.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cpp-clean_goal archived | source | installed | coded (Ada)
Specifies the state to which the units will be cleaned. All compilation artifacts associated with higher states are deleted.
Default value: archivedSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: false-make_options make-options (C/C++)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output.
Default value: falseRelated 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
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.
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:
% show_switches -context | grep -i code
Parameters
- program_units | files | directories | views | configurations
Specifies the program units (Ada) or files (C/C++) to be compiled. For Ada, if views or directories are named, all contained program units are compiled. For C/C++, when directories are specified, code is generated for all files in the directories and in any subdirectories. For C/C++, when views are specified, code is generated for all source files in the view and in addition libraries are updated as specified by the view's build policy. When configurations are specified, all views referenced by the configuration are coded.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppDetermines additional units to be coded. The empty string (" ") is equivalent to specifying coded. If the -configuration option is specified, the closure set is computed from units in the views of the configuration. Otherwise, the set is computed from units in the imported views.
Default value: " "-closure_compilation_policy: compilation_policy (C/C++)
Specifies the policy for compiling the closure when compiling a view that contains a library. The possible values are compile_all and compile_none. The default value of the option in a particular view may be changed by setting the CLOSURE_COMPILATION_POLICY context switch.
Default value: compile_all-configuration configuration (Ada)
Specifies the configuration to use during a link. If not specified, the imports are used. Can be used to specify units to code beyond those found in the code closure in the imported views. This option only has an effect if the -closure linked option is also specified.
Default value: " "-c_options compiler-options (C/C++)
Specifies option values to be passed to the target compiler for C source files. See target compiler documentation for specific values. The default value of this option in a particular view may be changed by setting the C_OPTIONS context switch.
Default value: " "-c_pre_options compiler-options (C/C++)
Specifies option values to be passed to the target compiler for C source files. See target compiler documentation for specific values. The default value of this option in a particular view may be changed by setting the C_PRE_OPTIONS context switch. These options will precede the values of -c_options and the include (for example., "-I") options based on import relationships
Default value: " "-cpp_options compiler-options (C/C++)
Specifies option values to be passed to the target compiler for C++ source files. See target compiler documentation for specific values. The default value of this option in a particular view may be changed by setting the CPP_OPTIONS context switch.
Default value: " "-cpp_pre_options compiler-options (C/C++)
Specifies option values to be passed to the target compiler for C++ source files. See target compiler documentation for specific values. The default value of this option in a particular view may be changed by setting the CPP_PRE_OPTIONS context switch. These options will precede the values of -cpp_options and the include (for example, "-I") options based on import relationships
Default value: " "Specifies that debugging is to be enabled. The default value of this option in a particular view may be changed by setting the DEBUGGING context switch.
Default value: false
Aliases: -debug, -gSpecifies that the command should only display information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are displayed.
Default value: falseIndicates whether compilation is to continue past the first unit with errors. If true, compilation stops at the first unit with an error.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is specified, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: false-make_options make-options (C/C++)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the compiler should recompile units which were compiled with an earlier (incompatible) version of Apex. Normally the compiler will not recompile units that were compiled with an older release of Apex; an error message is displayed. This is to prevent people from going into an old view and accidently recompiling it with a new compiler.
Default value: false-no_closure_compilation (C/C++)
Specifies that when building libraries, the closure of the libraries is not to be compiled. If set, this switch will override any compilation specified by the switch
-closure_compilation_policy.
Default value: false
Aliases: -no_closure_comp, -ncc-no_main_program_compilation (C/C++)
Specifies that registered main programs will not be compiled when compilation entire views or subdirectories.
Default value: false-s_options assembler-options (C/C++)
Specifies option values to be passed to the assembler when assembly (.s) files are processed. See target assembler documentation for specific values. The default value of this option in a particular view may be changed by setting the S_OPTIONS context switch.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that basic block instrumentation profiling events are to generated. These are used with the Tasking Logic Analyzer.
Default value: falseSpecifies that call-return instrumentation profiling events are to generated. These are used with the Tasking Logic Analyzer.
Default value: falseSpecifies that when building libraries, the closure from the last build should be used. If no closure exists then it will be computed. Setting this switch also specifies that no recompilation of the closure will occur. Only valid for C/C++.
Default value: false
Aliases: -uecSpecifies that the command should output additional informational output.
Default value: falseRelated 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.
- baseline_view
Specifies the view containing the corresponding objects.
- files | directories | views
Specifies the objects to compare, which must be in the same subsystem as the baseline view.
- options
Includes all files in the comparison.
Default value: falseShows the status for controlled objects that are checked in.
Default value: falseIncludes in the comparison, files that are checked out in either view.
Default value: falseIncludes in the comparison, files that are controlled in either view.
Default value: falseIncludes in the comparison, files that are deleted in either view.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecIncludes in the comparison, files that are controlled in the baseline view, do not exist in the current view, and would be accepted by accept_changes on the basis of the -new_history option and the current inclusion/exclusion switches in the current view.
Default value falseIncludes in the comparison, files that are controlled in the baseline view but do not exist in the current view.
Default value: falseSpecifies histories used to determine which new files would be accepted from the baseline to the current view. Multiple values may be specified separated by spaces. If more than one history is specified, the list must be surrounded by quotes.
Default value: <view'switch(VC_ACCEPTABLE_HISTORIES)>Simply records the file in the cmvc database.
The apex difference command will NOT work on files stored with this attribute. It is intended for use when binary data like executables must be controlled. This option must be set on the command line.
Default value: falseDisplay only the differences in the compared units.
Default value: falseIncludes in the comparison, files that share the same history in both views and for which the version in the baseline view is later than that in the current view. Note that if the baseline view version is checked out and the current view version is the latest checked in version, then the file is not considered out-of-date and it is not included in the result.
Default value: falseIncludes in the comparison, files that are uncontrolled in either view.
Default value: falseSpecifies that the command should emit additional informational output.
Default value:falseRelated 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:
- " " (empty string)
The history and version number are the same for the element in each view.
- +
The history is the same and the current view has a later version.
- -
The history is the same and the current view has an older version.
- *
The two views have different histories for the element.
- o
The file is checked out in one of the views and the other view has selected the latest checked in version.
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:
Ada:
Baseline View: /test/lower.ss/tom.wrk
Current View: /test/lower.ss/sam.wrk
Baseline Default History: Common
Current Default History: Common
Baseline Current
File Name History Version State History Version State
buffer.1.ada Common 1 In Common 1 In
- buffer.2.ada Common 3 Out Common 1 In
+ list.1.ada Common 1 In Common 2 In
o list.2.ada Common 1 In Common 2 Out
- queue.1.ada Common 2 Del Common 1 In
- queue.2.ada Common 2 Del Common 1 In
* stack.1.ada Common 1 In Sun4 1 In
- stack.2.ada Common 2 In Common 1 In
C/C++:
Baseline View: /test/lower.ss/tom.wrk
Current View: /test/lower.ss/sam.wrk
Baseline Default History: Common
Current Default History: Common
Baseline Current
File Name History Version State History Version State
buffer.b Common 1 In Common 1 In
- buffer.c Common 3 Out Common 1 In
+ list.b Common 1 In Common 2 In
o list.c Common 1 In Common 2 Out
- queue.b Common 2 Del Common 1 In
- queue.c Common 2 Del Common 1 In
* stack.b Common 1 In Sun4 1 In
- stack.c Common 2 In Common 1 In
control - places the objects under version control
Syntax
control [options] files | directories | views... (Apex/Summit)control [options] files | directories... (Apex/ClearCase)
Alias
ctrlDescription
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
- files | directories | views
Specifies the files to be controlled. If a directory is specified, all appropriate files are controlled in the directory and any subdirectories. Note that for Apex/ClearCase, Rational Subsystems can also be controlled.
- options
Specifies the name of a file containing attribute settings which will be set on the newly created version.
Default value: " "-attr_name attribute-name (Apex/Summit)
Specifies that name of an extended attribute whose value will be set on the version associated with the controlled file.
Default value: " "-attr_value attribute-value (Apex/Summit)
Specifies the value of the extended attribute which will be set on the version associated with the controlled file.
Default value: " "Uses a compress/uncompress algorithm when storing the file(s) in the cmvc database.
The apex difference command will NOT work on files stored with this attribute. It is intended for use when binary data (e.g., executables) must be controlled.
This option must be set on the command line; the APEX_COMPRESSED environment variable is for use only with the difference command.
Default value: false-control_enclosing_subsystem (Apex/ClearCase)
Causes the enclosing subsystem to be controlled. You cannot control files unless their enclosing subsystem is also controlled. The enclosing subsystem must be a Rational Subsystem (RSS)
Default value: ""-control_history history (Apex/Summit)
The history with which the files are associated. You can use the special string default_history to refer to the default history for the associated view.
Default value: default_historyWhen the history already exists, and the file contents do not match the latest version, a new version is created based on the current contents of the file. This forces the operation to succeed. The history cannot be checked out for this to be successful.
Default value: falseSpecifies that the designated history is to be created if it does not already exist.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: false-expand_configurations (Apex/Summit)
Specifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecWhen the history already exists and the file contents do not match the latest version, the file contents are changed to match the latest version. This forces the operation to succeed by changing the file.
Default value: falseWhen the history already exists, this option specifies that the current file contents must match the latest version of the history. If the contents do not match, the operation fails.
Default value: falseSpecifies that compilation artifacts should not be copied with source files.
Default value: false-no_keyword_replacement (Apex/Summit)
Inhibits the replacement of substitution strings. When this option is set, substitution symbols are left in their original form.
Default value: falseEnters the text as a note associated with the version.
Default value: " "Enters the contents of the file as a note associated with the version.
Default value: " "Specifies that list valued attributes are to be replaced rather than have a new value appended to the existing value.
Default value: falseSpecifies that the command should emit additional informational output.
Default value:falseRelated 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:
- Subsystems (Apex/Summit)
There are no special restrictions or semantics associated with copying subsystems.
- Views (Apex/Summit)
You can copy a view only if it contains no checked out files that have acquired reservations. Options are provided to check in or abandon any checked out files prior to making the copy.
The version control characteristics of files in the destination view are based on the characteristics of the files in the source view and the options that were set.
When a view is copied, all import information is reanalyzed as though the import -refresh command were run on the newly created view.
- Files
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
- source
- destination
- options
Specifies that any checked-out files are to be abandoned prior to copying.
This option does not apply when copying an entire subsystem.
Default value: falseAllow the copy to occur if a view contains privately checked out files. This option is intended primarily for copying an entire view.
Default value: false.Specifies the name of a file containing attribute settings which will be set on the checked in version.
Default value: " "Specifies that name of an extended attribute whose value will be set on the checked in version.
Default value: " "Specifies the value of the extended attribute which will be set on the checked in version.
Default value: " "-attrs_extended
When this option is set, any extended version attributes associted with controlled files are copied. This option only applies when version information is being copied from one subsystem to another subsystem. This is a simple copy mechanism, for more specific control a post_copy_verison customization is recommended.
Default value: falseSpecifies that any checked-out files are to be checked in prior to copying.
This option does not apply when copying an entire subsystem
Default value: false-control_history history (Apex/Summit)
The history to use when the -set_history option is set.
This option does not apply when copying an entire subsystem.
Default value: default_historySpecifies that the history family named by -control_history should be created if it does not exist. This option does not apply when copying an entire subsystem.
Default value: false-goal archived | source | installed | coded | linked | preserve
The new views will contain only files appropriate to the goal state. Units in the new views are compiled to the requested state as required, except in the case of preserve, which preserves the original state but does not perform any recompilation. Specifying a value other than preserve is equivalent to cleaning the view to that goal and then compiling the view to that goal. The Templates/*.state files are not copied if the -goal_archived option is used with Apex C++ models.
Default value: preserveSpecifies that the latest checked in version of any checked out files should be copied to the destination. For privately checked out files, copies the version on which the private check out is based.
Default value: falseWhen this option is not set, new values are appended to the existing list. When this option is set, new values replace the existing value.
Default value: falseIf checked-out files are abandoned, this option specifies whether the contents of modified files are to be saved in a special .saved file.
Default value: falseSpecifies that newly created destination files are to be controlled with the history specified by -control_history. Applies only when the source file was itself controlled.
This option does not apply when copying an entire subsystem.
Default value: falseSpecifies that the storage for new views is to be allocated within the designated directory. If no value is given, storage is allocated within the associated subsystem.
Default value: " "Specifies that newly created destination files are to be left uncontrolled after the copy.
This option does not apply when copying an entire subsystem.
Default value: falseRelated 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:
- The ability to filter the files which will be copied into the new view.
- The ability to specify a new model and imports for the new view.
- The ability to automatically generate the names of the new views.
- The ability to specify a storage location for the new views.
- The ability to specify the desired compilation state of the new views.
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:
- Check in the files,
- Use the latest checked in version of the files
- Abandon the check out of the files.
- Uncontrol the files in the new view.
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
- views | configurations
Specifies the views to be copied. (The kind of the source views and the kind of the newly created views need not be the same.) When a configuration is specified, the views contained in the configuration are copied. You can copy only one view from each subsystem in the same operation.
- destination
Specifies the name of the views to be created. This name is always resolved in the context of the subsystems containing the source views.
This parameter should not be provided if -generate_name is specified.
- options
Specifies that any checked-out files are to be abandoned prior to copying.
Default value: falseAllows views to be copied even if they contain privately checked out files. This option takes precedence over the -latest option.
Default value: false-attrs_extended
When this option is set, any extended version attributes associted with controlled files are copied. This option only applies when version information is being copied from one subsystem to another subsystem. This is a simple copy mechanism, for more specific control a post_copy_verison customization is recommended.
Default value: falseSpecifies that any checked-out files are to be checked in prior to copying.
Default value: falseSpecifies the new history to use when the -set_history option is set.
Default value: default_history-copy_access_category access_category
Specifies the access category for the new views. The special value model may also be specified in which case the access category will be the same as that of the model. The default value will cause the new view to have the same access category as the source view.
Default value: preserveSpecifies that you should create the history family named by the -control_history option if it does not exist.
Default value: falseCreates a configuration referencing the newly created views.
Default value: " "-force
Specifies that the copy will persevere, leaving a newly created view in a potentially inconsistent state or without having copied all the objects contained by the source views. This can be useful when a set of views is being copied and the primary goal is to get all the views created and the imports of the newly created views adjusted to reference each other.
Treats all the arguments as views to be copied and creates all new views with names generated from state in each view. When this option is set, use the -view_kind option to determine the class of the target views.
Default value: false-goal archived | source | installed | coded | linked | preserve
The new views will contain only files appropriate to the goal state. Units in the new views are compiled to the requested state as required, except in the case of preserve, which preserves the original state but does not perform any recompilation. Specifying a value other than preserve is equivalent to cleaning the view to that goal and then compiling the view to that goal. The Templates/*.state files are not copied if the -goal_archived option is used with Apex C++ models.
Default value: preserveSpecifies the Unix group to be associated with the new view. The current user must be a member of this group. By default, the group is the same as that associated with the enclosing directory. The special value user may also be specified to use the effective group of the current user.
Default value: inherit-import views_or_configurations
Specifies that the imports of the new view should include the indicated views_or_configurations. Existing imports of a subsystem are updated to reflect the newly specified view; no new subsystems are imported. Imports specified are used to update any imports specified by the -model option. Can be a set of views or configurations.
Default value: " "Create interface views.
Default value: false-interface_copy_exclusions names...
Specifies the set of objects which will not be copied when an interface view is being created. This option is applied in addition to the "working copy" and "release copy"specific options.
Default value: "*.2.ada *.C *.cc *.cpp *.cxx *.c"-interface_copy_inclusions names...
Specifies the set of objects which will be copied when an interface view is being created. This option is applied in addition to the "working copy" and "release copy"specific options.
Default value: "*"Specifies that if a view contains checked out files then the latest checked in version will be placed in the target view.
Default value: falseUsed in automatic name generation. See Name Generation Context Switches for more information. Values in the range 1 to 8 are allowed.
Default value: 1The newly created views are based on this model. In particular, the switch file from the model view is copied into the new views, and the imports of the model are used to update the imports of the new views. If no new model is provided (the default), each new view has the same model as the corresponding source view.
Default value: " "-release_copy_exclusions names...
Specifies the set of objects which will not be copied when a working view is being created.
Default value: "*~ #*# .nfs*"-release_copy_inclusions names...
Specifies the set of objects which will be copied when a release view is being created.
Default value: "*"Applies only when a new model is specified. If this option is not set, only switches specifying the compiler are changed in the destination view to reflect the values in the model. If this option is set, all switches are updated to match their values in the model's switch file.
Default value: falseIf checked out files are abandoned, specifies whether the contents of modified files are to be saved in a special .saved file.
Default value: falseSpecifies that the history of each controlled file will be set to the value supplied by the -control_history option, as if the set_history command were run. If it is not possible to set the history for a particular file, that file is left uncontrolled.
Default value: falseSpecifies that the storage for new views is to be allocated within the designated directory. If no value is given, storage is allocated within the associated subsystem.
Default value: " "Specifies that all files in the destination views will be left uncontrolled.
Default value: false-view_kind working | release | development | stable | frozen | preserve
Specifies the kind of the newly created views. The kind must be compatible with the extension of the target name if a target name is supplied. Specifying release is the same as specifying development. Use the value preserve to ensure that the new view will have the same kind as the source view.
Default value: preserve-working_copy_exclusions names...
Specifies the set of objects which will not be copied when a working view is being created.
Default value: "*~ #*# .nfs*"-working_copy_inclusions names...
Specifies the set of objects which will be copied when a working view is being created.
Default value: "*"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.
- WORKING_COPY_INCLUSIONS: names...
Specifies the set of objects which will be copied when a working view is created.
Default value: "*"- WORKING_COPY_EXCLUSIONS: names...
Specifies the set of objects which will not be copied when a working view is created.
Default value: "*~ #*# .nfs*"- RELEASE_COPY_INCLUSIONS: names...
Specifies the set of objects which will be copied when a release view is created.
Default value: "*"- RELEASE_COPY_EXCLUSIONS: names...
Specifies the set of objects which will be copied when a release view is created.
Default value: "*~ #*# .nfs*"- INTERFACE_COPY_INCLUSIONS: names...
Specifies the set of objects which will be copied when an interface view is created.
Default value: "*"- INTERFACE_COPY_EXCLUSIONS: names...
Specifies the set of objects which will be copied when an interface view is created.
Default value: "*.2.ada *.C *.cc *.cpp *.cxx *.c"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".
- RELEASE_NAME: string
Specifies the pattern used in automatic generation of names for releases.
Default value: "<subsystem>/Releases/" + "<view:t:r>.<switch(release_levels)>"- RELEASE_LEVELS: string
Specifies level numbers used in automatic generation of release names.
Default value: "0.0.0"- INTERFACE_RELEASE_NAME: string
Specifies the pattern used in automatic generation of interface-only releases.
Default value: "<subsystem>/Releases/" + "<view:t:r>.ifc.<switch(interface_release_levels>"- INTERFACE_RELEASE_LEVELS: string
Specifies level numbers.
Default value: "0.0.0"- WORKING_NAME: string
Specifies pattern used in automatic generation of working view names.
Default value: "<subsystem>/<user>.wrk"- WORKING_LEVELS: string
Specifies level numbers.
Default value: "0.0.0"- INTERFACE_WORKING_NAME: string
Specifies pattern used in automatic generation of spec-only working views.
Default value: "<subsystem>/<user>.ifc"- INTERFACE_WORKING_LEVELS: string
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
- names
Names of the objects to be created. The names are resolved in the current directory context. The name must contain any extensions necessary to identify the class of the object.
- options
If a file has been created, place it under source control.
Default value: falseVisits the newly created object. File objects are made editable.
Default value: falseSelects the newly created object in the appropriate directory viewer.
Default value: falseVisits the newly created object in the appropriate editor.
Default value: falseRelated Commands
- create_subsystem - creates new subsystem
- create_working - creates new, empty, working views (Apex/Summit)
- create_release - creates new, empty development release views (Apex/Summit)
- create_directory - creates new directories
- create_file - creates new files
- create_ada - creates new Ada units (Ada only)
- create_body - creates new Ada unit bodies (Ada only)
- create_spec - creates new Ada unit specs (Ada only)
- create_c - creates new C language files (C/C++ only)
- create_cpp - creates new C++ language files (C/C++ only)
- create_class - creates new C++ language files (C/C++ only)
- create_configuration - creates a new configuration file
- create_history - creates new version histories (Apex/Summit)
- create_export_set - creates export sets
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
- names
The names of the Ada unit to be created. Names with the .[12].ada extension are created as the appropriate part, possibly overriding the value specified by the -part option.
- options
Places the newly created Ada units under version control if possible. If the -edit option is set, the units are also checked out.
Default value: falseVisits the newly created units in the appropriate editor. The units are made editable.
Default value: false-part spec | body | generic_spec | both | generic_both | subunit
Determines which files to create. Together with -unit, also determines the template used to fill in the initial contents. The values of spec, body, generic_spec and subunit cause a single file to be created, while the values of both and generic_both cause both the spec and body files to be created.
Default value: specSelects the newly created units in the appropriate directory viewer.
Default value: false-unit package | procedure | function | task | protected | empty
The kind of the unit to be created. Together with -part, determines the template used to fill in the initial contents of the unit.
Default value: packageVisits the newly created units in the appropriate editor.
Default value: falseRelated 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
- names
The names of the C files to be created.
- options
Places the newly created files under version control if possible. If the -edit option is set, the units are also checked out.
Default value: falseVisits the newly created files in the appropriate editor. The units are made editable.
Default value: falseDetermines whether the commands will create header files, source (body) files or both. Together with -unit, this option also determines the prototypes used to fill in the initial contents.
Default value: headerSelects the newly created files in the appropriate directory viewer.
Default value: falseThe kind of initial declaration to be created. Together with -part, determines the prototype used to fill in the initial contents.
Default value: emptyVisits the newly created files in the appropriate editor.
Default value: falseRelated 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
- names
The names of the C++ classes. Each name is also used as the base name for newly created files unless the -file option is set.
- options
Places the newly created files under version control if possible. If the -edit option is set, the units are also checked out.
Default value: falseVisits the newly created files in the appropriate editor. The units are made editable.
Default value: falseUsed as the base name for the file to be created.
Default value: " "Determines whether the command creates header files, source (body) files, or both.
Default value: headerSelects the newly created files in the appropriate directory viewer.
Default value: falseVisits the newly created files in the appropriate editor.
Default value: falseRelated Commands
create_configuration - creates a new configuration file
Syntax
create_configuration [options] names...
Aliases
create_config, crconfig
Description
Creates a new configuration file.
Parameters
- names
The names of the new configuration files.
- options
Visits the newly created configurations in the appropriate editor. The files are made editable.
Default value: falsePlaces the newly created configurations under version control, if possible. If the -edit option is set, the files are also checked out.
Default value: falseSelects the newly created configurations in the appropriate directory viewer.
Default value: falseVisits the newly created configurations in the appropriate editor.
Default value: falseRelated 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
- names
The names of the C++ files to be created. When the -unit option specifies a class kind, each name is also used as the class name within the newly created file. When the -file option is specified only one file will be created and the names are the C++ classes to be declared within the file.
- options
Places the newly created files under version control if possible. If the -edit option is set, the units are also checked out.
Default value: falseVisits the newly created files in the appropriate editor. The units are made editable.
Default value: falseUsed as the base name for the file to be created.
Default value: " "Determines whether the command will create header. source (body) files or both. Together with -unit, this option also determines the prototypes used to fill in the initial contents.
Default value: headerSelects the newly created files in the appropriate directory viewer.
Default value: false-unit main | class | template_class | template_function | empty
The kind of initial declaration to be created in the C++ files. Together with -part, the option determines the prototype files used to fill in the initial contents.
Default value: emptyVisits the newly created files in the appropriate editor.
Default value: falseRelated Commands
create_directory - creates new directories
Syntax
create_directory [options] names...
Alias
crdir
Description
Parameters
- names
The names for the new directories.
- options
Visits the newly created directory in the directory viewer.
Default value: falseSelects the newly created directory in the appropriate directory viewer.
Default value: falseVisits the newly created directory in the directory viewer.
Default value: falseRelated Commands
create_export_set - creates export sets
Syntax
create_export_set [options] simple_name...
Alias
crxpsDescription
Export sets are used to control the set of interfaces made available to clients.
Parameters
- simple_name
- options
The view in which the export set is created, defaults to the current view. May name a set of views.
Default value: " "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
- names
- options
Places the newly created files under version control if possible. If the -edit option is set, the files are also checked out.
Default value: falseVisits the newly created file in the appropriate editor. The file is made editable.
Default value: falseSelects the newly created file in the appropriate directory viewer.
Default value: falseVisits the newly created file in the appropriate editor.
Default value: falseRelated Commands
create_history - creates new version histories (Apex/Summit)
Syntax
create_history [options] simple_name...
Alias
crhstDescription
Creates new version histories in the specified subsystem.
Parameters
- simple_name
The simple name of the history.
- options
The subsystem in which to create the history family. If not given, the history is created within the current subsystem. May name a set of subsystems.
Default value: " "Related Commands
create_registered_set - creates registered sets
Syntax
create_registered_set [options] simple_name...
Alias
create_reg_setDescription
Creates new registered sets with the specified names.
Parameters
- simple_name
The name of the new registered set.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseThe views in which to create the sets. If not specified, the sets are created in the current view.
Default value: " "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
- names
Names of the development release views to be created. The names are resolved in the current directory context. The names may or may not have the release view extension.
- options
-access_category access_category
Specifies the access category for the new view. The possible values are the access category names. The special value model may also be specified in which case the access category will be the same as that of the model.
Default value: group_publicVisits the newly created release views in the directory viewer.
Default value: falseSpecifies the UNIX group to be associated with the new view. The current user must be a member of this group. By default, the group is the same as that associated with the enclosing directory. The special value user may also be specified to use the effective group of the current user.
Default value: inheritThe created view will be an interface view.
Default value: false-import views_or_configurations
Specifies the imports of the new view. These views are added to those specified by the model. May name a set of views or configurations.
Default value: " "You create the new releases based on the designated model view. The model serves as a prototype for the new views. Subdirectories, switches, and imports of the new views are copied from the model view. There are no restrictions on views that you can use as models. If you do not specify this option, the value of the APEX_DEFAULT_MODEL session switch (normally initialized during installation of the product) is used. If this option is provided on the command line with an explicit value of " ", the new view is created without a model.
Default value: " "Selects the newly created release views in the directory viewer.
Default value: falseUse the designated export set for any imported views. The value default_export_set specifies that the designated default export set of each imported view will be used.
Default value: default_export_setSpecifies that the physical storage for the view is located in the designated parent directory. If no value is given (the default), the storage is located in the associated subsystem.
Default value: " "Visits the newly created release views in the directory viewer.
Default value: falseRelated 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:
- You can specify a fully qualified name to the create_subsystem command. The fully qualified name is the permanent name of the subsystem.
- You can specify a relative name in the context of a directory that already has a permanent name. In this case, the permanent name of the subsystem is derived from the permanent name of the directory context.
Parameters
- names
The name of the new subsystem. Subject to the restrictions, noted above, that this name specifies the permanent name of the subsystem.
- options
Visits the newly created subsystems in the directory viewer.
Default value: falseSelects the newly created subsystems in the directory viewer.
Default value: falseThe parent directory for the physical storage used by the subsystem. When no value is specified, the physical storage is in the location specified by the name.
Default value: " "Visits the newly created subsystem in the directory viewer.
Default value: falseSession Switches
- APEX_SS_CONTEXT_EXCLUSIONS: names...
Specifies directories in which subsystems should not be created. This restriction also applies when subsystems are copied or moved.
Default value: /tmp?*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
- names
Names of the working views to be created. The names are resolved in the current directory context. The names may or may not have the working view extension.
- options
-access_category access_category
Specifies the access category for the new view. The possible values are the access category names. The special value model may also be specified in which case the access category will be the same as that of the model.
Default value: group_publicVisits the newly created working views in the directory viewer.
Default value: falseSpecifies the UNIX group to be associated with the new view. The current user must be a member of this group. By default, the group is the same as that associated with the enclosing directory. The special value user may also be specified to use the effective group of the current user.
Default value: inheritThe created view will be an interface view.
Default value: false-import views_or_configurations
Specifies the imports of the new view. These views are added to those specified by the model. May name a set of views or configurations.
Default value: " "You create the new working views based on the designated model view. The model serves as a prototype for the new views. Subdirectories, switches, and imports of the new views are copied from the model view. There are no restrictions on the views that can be used as models.
If this option is not specified, the value of the APEX_DEFAULT_MODEL session switch (normally initialized during installation of the product) is used. If this option is provided on the command line with an explicit value of " ", the new view is created without a model.
Default value: " "Selects the newly created working views in the directory viewer.
Default value: falseUse the designated export set for any imported views. The value default_export_set specifies that the designated default export set of each imported view is used.
Default value: default_export_setSpecifies that the physical storage for the view is located in the designated parent directory. If no value is given (the default), the storage is located in the associated subsystem.
Default value: " "Visits the newly created working views in the directory viewer.
Default value: falseSession Switches
- APEX_DEFAULT_MODEL: string
Specifies the model to use when creating new views when no explicit model was specified.
Default value: <established during product installation>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:
- DELIVER_OBJECTS
Specifies the names of objects to deliver.
- DELIVER_TO_DIRECTORY
Specifies the directory to which the objects are to be delivered.
In addition to the switches named above there are additional switches named
- DELIVER_OBJECTS_[1-9]
DELIVER_TO_DIRECTORY_[1-9]which can be used to specify additional sets of objects to be delivered to different directories.
Parameters
- files | directories | views | configurations
The context in which to run the command.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falsedemotion_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
- -as_file <unit>
Name of the unit (file) for which the demotion impact is to be displayed. (for example, ada.calendar.1.ada)
- - <ada_name>
Name of the Ada object for which the demotion impact is to be displayed. (for example, Ada.Calendar.Year'Body)
- options
-in_context <view>
-in_context <configuration>Specifies the compilation context to use for the analysis. Defaults to the view containing the Ada object or unit. The context is either a single view and its imports or is it a collection of views specified by the contents of a configuration file.
Acts as a filter on the output. Any number of views and units may be specified as the scope of the analysis. Only units from this list or from these views will be reported as being affected by the proposed demotion.
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
- files | directories | views | configurations
The source files for which dependencies are updated.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseRelated 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.
- If the -previous_file option specifies an uncontrolled file, that file is used as the previous object.
- If the -previous_file option specifies a controlled file, the -previous option is used to determine a version of that file.
- If the -previous_file is not specified, the difference will be determined for two versions, specified by -current and -previous, of the file argument.
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
- files
Specifies the arguments used for the current objects in the difference.
- options
Uses a compress/uncompress algorithm when storing the file(s) in the cmvc database.
The apex difference command will NOT work on files stored with this attribute. It is intended for use when binary data (e.g., executables) must be controlled.
This option must be set on the command line; the APEX_COMPRESSED environment variable is for use only with the difference command.
Default value: falseBy default, whitespace differences at the beginning and end of lines are ignored when displaying differences. If this option is set, such difference are shown.
Default value: falseWhen -compressed is set, this option controls the number of context lines that display around the difference regions.
Default value: 0Specifies the version number used for the current object. May specify a simple or a full version number. If a full version number is specified, the files are ignored.
Default value: CurrentIf set then processing stops when the first error occurs.
Default value: falseBy default, the upper case and lower case version of a character is considered significant. If this option is set, such differences are not shown. If -parse_ada is also in effect, case variations within in Ada strings and Ada comments are not shown (implies -strict).
Default value: false-ignore_comments
By default, variations in Ada comments are considered significant. If this option is set, such differences are not shown. This option casues comment lines to be treated as blank lines and comments appearing on the same line with other Ada code to be ignored. This option applies only when -parse_ada is in effect.
Default value: falseBy default, whitespace within a line is considered significant. If this option is set, such differences are not shown. This option overrides -consider_whitespace. If -parse_ada is also in effect, differences in whitespace within Ada strings and Ada comments are not shown.
Default value: false-parse_ada
By default, whitespace in and around Ada contructs is considered significant. If this option is set, such differences are not shown. This option should be applied only to Ada units.
Default value: falseSpecifies the version number used for the previous object. May specify a simple or a full version number. If a full version number is specifies, -previous_file is ignored.
Default value: PreviousSpecifies the previous object.
Default value: " "-strict
By default, the upper case and lower case version of a character of an Ada construct is considered significant. If this option is set, such differences are not shown. This option applies only when -parse_ada is in effect.
Default value: falseSpecifies that the command should emit additional informational output.
Default value: falseRelated 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
- files | directories | views | configurations
The objects to disassemble. If an object file is specified then that object file is disassembled. If a source file is specified then the object file associated with the source file is disassembled. If a directory or view is specified then object files associated with all source files are disassembled.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: false-disassemble_options disassemble-options
Options that will be passed to the disassembler whenever a object file is disassembled. Specific disassembler documentation should be consulted for acceptable values. The default value may be modified in a particular view by setting the DISASSEMBLE_OPTIONS context switch.
Default value: " "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.
- Subsystems
No restrictions or special semantics are associated with deleting a subsystem.
- Views (Apex/Summit)
When a view is deleted as part of the deletion of the enclosing subsystem, no restrictions or special semantics apply.
When a view's deletion is not a part of a subsystem's deletion, usually the view cannot be deleted if it contains checked-out files.
Deleting a view is not affected by whether the view has importers. Importers of a deleted view are made obsolete and are not compilable until their imports are successfully updated.
- Controlled Files
No special semantics are associated with deleting a controlled file when the enclosing view is being deleted at the same time.
When a controlled file is deleted without deleting the enclosing view, the deletion results in the creation of a deleted version in the history currently associated with the file. Deleted versions are treated like any other version by most Summit/CM operations. Accepting a deleted version causes the file to be deleted. A controlled file cannot be deleted if it is currently checked out.
You cannot delete controlled files if their history is currently checked out in another view. Deleting checked-out files performs an implicit "abandon" operation prior to the deletion.
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
- files | directories | views | subsystems
- options
Causes any checked-out files to be abandoned prior to deletion.
Default value: falseAllows a view to be deleted if it contains privately checked out files.
Default value: false-auto_check_in
This option causes the specified export set file to be checked in, provided it was checked out by this operation. The option has no effect if -auto_check_out is not set.
Default value: false-auto_check_out
This option causes the export set file to be checked out, if the file is controlled and currently checked in.
Default value: falseCauses any checked out files to be checked in prior to deletion.
Default value: falseForces the object to be deleted. Tries to maintain consistency of data structures, but the object will be deleted even if consistency is broken.
Default value: falseCreates a note that will be attached to the deleted version
Attaches the designated file filename to the deleted version.
Recursively deletes subobjects. If not set, the operation will fail if the objects contain user-created files or directories.
Default value: false-set export_set
Specifies the export set to be updated when files are deleted. This option is ignored for objects that are not in a view. Multiple export sets may be specified by quoting a whitespace separated list of export set names. Failure to update of the export set will not cause the command to fail, but will generate warning messages.
Default value: ""Specifies uncontrol files prior to deletion. This is useful when you do not want to create a permanent deleted version.
Default value: falseRelated 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
- simple_name
Specifies the name of the export set to be deleted.
- options
Specifies the name of the view containing the export sets that will be deleted. When no library context is specified, the enclosing library context is used.
Default value: " "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
- histories
Specifies the name of the history to delete.
- options
Forces the history to be deleted even if it is currently being used. Controlled files using the history will be made uncontrolled.
Default value: falseSpecifies the subsystems in which the named histories will be deleted. When no value is specified, the enclosing subsystem is used.
Default value: " "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
- simple_name
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseThe views in which to delete the sets. If not specified, the sets are deleted in the current view.
Default value: " "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
Name of a source unit file or Rational Subsystem view to be coded or linked.
If a unit filename is specified along with the link option, do_clearcase_audit, the resulting CR can displayed (using the ClearCase cleartool catcr command) as a bill of materials listing all of the source files and other filesystem objects that contributed to the generation of the executable.
If a library context is specified with either the code or link option, the resulting CR will be created in a way that enables winkin of compilation artifacts into other ClearCase views. The CR generated by the link form of the command when a library context is specified is not suitable for generation of a bill of materials; for a CR that will produce a correct bill-of-materials, you must specify a program unit file name.
- options
noclean
Do not clean the import closure.
This option will only be recognized if it follows the code, link, or build command and precedes the compile_options or link options
The named objects compilation state is always cleaned. This parameter only determines whether the import closure is cleaned as well. All cleaning takes place before the audited build begins.
In the general case, it is necessary for the closure to be cleaned, so that the compilation of every unit can be included in the audited build. If an audited code operation is performed without cleaning the closure, then DOs will not be generated for every unit. This, in turn, lessens the usefulness of the view as a source view for winkins; since the target view will be missing compilation artifacts after the winkin, the compiler will have to generate them. Moreover, if an audited link is done in a closure that is not clean, the CR for the linked executable will not represent a complete bill of materials for the build.
The noclean option should only be used if there is absolute certainty that it is not necessary for do_clearcase_audit to do the closure cleaning operation. Examples of this case might be:
- All of the subsystems in the closure of the specified subsystem are in an up-to-date coded state. In this case, you know that recompilations in the current view certainly cannot call for compilation of anything on the closure, since nothing on the closure is a candidate for compilation in the first place.
- The closure has already been manually cleaned.
noimports
Do not audit the import closure.
This option will only be recognized if it follows the code, link, or build command and precedes the compile_options or link options
compile_options | link options
Example
do_clearcase_audit code noclean -no_closure_compilation -- /vobs/bagel_world/winkin/client.rss
do_clearcase_audit link -- /vobs/bagel_world/winkin/client.rss/main.2.adaenable_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
- views
Ada views containing C or C++ in the closure.
- options
Specifies a C/C++ model to be used in linking the Ada main program. If not specified then the value of the session switch APEX_CPP_MODEL is used.
Default value: " "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
- program_units
Specifies the program units to be exported.
- directories
Specifies that all program units in the directory (and subdirectories) are exported.
- views
Specifies that when the -refresh option is given, all export information is re-analyzed for the designated views.
- options
-auto_check_in
This option causes the specified export set file to be checked in, provided it was checked out by this operation. The option has no effect if -auto_check_out is not set.
Default value: false-auto_check_out
This option causes the export set file to be checked out, if the file is controlled and currently checked in.
Default value: falseSpecifies the name of the export set from which the units will be exported. Multiple export sets may be specified by quoting a whitespace separated list of export set names. If the option is not set, the default export set is used.
Default value: default_export_setCauses the export information to be refreshed based on the description file when views are specified.
Default value: falseRelated 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
- files | directories | views | configurations
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falsegenerate - 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
- files | directories | views | configurations
The objects to be used in the generation.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falsehelp - 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:
% apex import "*.ss/tom.wrk" new_imports.cfg
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
- importers
Specifies the views that will have their imports updated. The parameter may name working views or configurations. If a configuration is named, all working views in the configuration will have their imports changed.
- new_imports
Specifies the new imports for the view. For subsystems that were already imported, the imports are changed; for subsystems that were not imported, the imports are added. The imports may be specified by views or configurations containing views.
- options
Specifies the set of views that will form a mutual importing set.
Default value: falseBy default, import information is not recomputed if no changes have occurred. When this option is set, import information for the current views and all imported views are recomputed.
Default value: falseRecomputes the import information without adding any new imports.
Default value: falseSpecifies the export set that will be used for the import operation. If the view is already imported, it changes the export set being used. A value of " " causes the current export set to be used. This option is ignored when -refresh is set.
Default value: default_export_setSpecifies that the new import is added only if the importer currently imports some other view from the subsystem of the new import.
Default value: falseRelated Commands
link -generates an executable file
Syntax
link [options] [program_units |directories |views | configurations...] (Ada)link [options] files | directories | views | configurations... (C/C++)
Description
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).
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:
% show_switches -context | grep -i link
Parameters
- program_units | files | directories | views | configurations
For Ada, specifies program units that contain main entry points.
For C++, specifies the main programs to be linked. When a specific source file is specified, that source file must have been registered as a main program. When a directory or view is specified, all registered main programs in the directory or view and any subdirectories are linked. When a configuration is specified, all main programs in the views referenced by the configuration will be linked.
- options
This command accepts all options associated with the code command.
-ada_link_mode mode (Ada)
Used to determine the link mode for Ada main programs. The possible values are static, dynamic, dynamic_or_static and default. The link mode specifies whether archive or shared libraries will be used in the link. The link mode is described in more detail in the section on Linking. The default value in a particular view may be modified by setting the ADA_LINK_MODE context switch.
Default value: defaultProceed with the link even if there were errors in compiling the closure of the main program.
Default value: falseIn views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppUsed to determine the link mode for C main programs. The possible values are static, dynamic, dynamic_or_static and default. The link mode specifies whether archive or shared libraries will be used in the link. The link mode is described in more detail in the section on Linking. The default value in a particular view may be modified by setting the C_LINK_MODE context switch.
Default value: default-c_link_options linker-options (C/C++)
Options that will be passed to the linker whenever a C main program is linked. Specific linker documentation should be consulted for acceptable values. The value of this option will follow all object files, libraries, and options that are contributed from views in the main program's closure. The default value may be modified in a particular view by setting the C_LINK_OPTIONS context switch.
Default value: " "-c_link_pre_options linker-options (C/C++)
Options that will be passed to the linker whenever a C main program is linked. Specific linker documentation should be consulted for acceptable values. The value of this option will precede all object files, libraries, and options that are contributed from views in the main program's closure. The default value may be modified in a particular view by setting the C_LINK_PRE_OPTIONS context switch.
Default value: " "-closure_compilation_policy: compilation-policy (C/C++)
Specifies the policy for compiling the closure of the main program. The possible values are compile_all and compile_none. The default value of the option in a particular view may be changed by setting the CLOSURE_COMPILATION_POLICY context switch.
Default value: compile_allSpecifies the configuration to use during the link. If not specified, the imports are used. Note that, for each view named in a configuration used for linking, there must already be a view from the same subsystem in the normal import structure; that is, views in configurations are replacements for imports, not patches to fill in holes in the imports.
Default value: " "Used to determine the link mode for C++ main programs. The possible values are static, dynamic, dynamic_or_static and default. The link mode specifies whether archive or shared libraries will be used in the link. The link mode is described in more detail in the section on Linking. The default value may be modified in a particular view by setting the CPP_LINK_MODE context switch.
Default value: default-cpp_link_options linker-options (C/C++)
Options that will be passed to the linker whenever a C++ main program is linked. Specific linker documentation should be consulted for acceptable values. The value of this option will follow all object files, libraries, and options that are contributed from views in the main program's closure. The default value may be modified in a particular view by setting the CPP_LINK_OPTIONS context switch.
Default value: " "-cpp_link_pre_options linker-options (C/C++)
Options that will be passed to the linker whenever a C++ main program is linked. Specific linker documentation should be consulted for acceptable values. The value of this option will precede all object files, libraries, and options that are contributed from views in the main programs closure. The default value may be modified in a particular view by setting the CPP_LINK_PRE_OPTIONS context switch.
Default value: " "Specifies that debugging is to be enabled. The default value of this option in a particular view may be changed by setting the DEBUGGING context switch.
Default value: false
Aliases: -debug, -gSpecifies that the command should only display information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are displayed.
Default value: false-elaboration_order_listing (Ada)
Specifies that a file containing a list of the elaboration order of the units in its closure is created when a main program is coded.
Elaboration-order list can be created only for main programs. Like assembly listings, an elaboration-order file is stored in the .Rational/Compilation directory; for a main unit named tofu.2.ada the elaboration order file has the name tofu.2.elab_order.
Indicates whether compilation is to continue past the first unit with errors.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is specified, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseAttempts to use incremental features of the platform linker.
Default value: false-link_closure_policy closure-policy (C/C++)
Determines the way in which the closure of the main program will be computed. The default value in a particular view may be modified by setting the LINK_CLOSURE_POLICY context switch.
Default value: combineThis option specifies when the linker should create a link map. This is only valid for Apex native. The generated link map is placed in a file with a .2.batch_map extension.
The recognized values for when are:
on_error - produce a link map, if an error is detected.
always - produce a link map
never - do not produce a link map
For example, the command:
% apex link -keep_load_map always foo.2.adaproduces the file foo.2.batch_map which contains the link map for foo.
Default value: " "-make_options make-options (C/C++)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value -d will normally provide tracing of the underlying make command.
Default value: " "Specifies that the compiler should recompile units which were compiled with an earlier (incompatible) version of Apex. Normally the compiler will not compile units that were compiled with an older release of Apex; an error message is displayed. This is to prevent people from going into an old view and accidently recompiling it with a new compiler.
Default value: false-no_closure_compilation (C/C++)
Specifies that when building libraries, the closure of the libraries is not to be compiled. If set, this switch will override any compilation specified by the switch -closure_compilation_policy.
Default value: false
Aliases: -no_closure_comp, -ncc-non_ada_linkage [arguments] (Ada)
Specifies arguments to pass to the target linker. This can be used to specify object files and archive libraries for non-Ada program units that will be included when an Ada main program is linked. For example, to include compiled C routines named c_routine1 and c_routine2, to include the c_lib.a library, and to produce a linker trace listing.
Default value: " "-runtimes alternate_runtime_pathname (Ada)
Specifies the pathname for the Rational Ada runtimes to use at link time if the default version is not appropriate. In most cases, the default switch value (empty) is the correct one to use. This switch is for use only at the direction of Rational technical support.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that basic block instrumentation profiling events are to generated. These are used with the Tasking Logic Analyzer described in the Tasking Logic Analyzer Guide.
Default value: falseSpecifies that call-return instrumentation profiling events are to generated. These are used with the Tasking Logic Analyzer described in the Tasking Logic Analyzer Guide.
Default value: falseSpecifies that you wish to link with an instrumented runtime. This is necessary to generate runtime logs used by the Tasking Logic Analyzer described in the Tasking Logic Analyzer Guide.
Default value: falseSpecifies that both runtime and basic block instrumentation events are to be profiled. These are used with the Tasking Logic Analyzer described in the Tasking Logic Analyzer Guide.
Default value: falseSpecifies that both runtime and call_return instrumentation events are to be profiled. These are used with the Tasking Logic Analyzer described in the Tasking Logic Analyzer Guide.
Default value: falseSpecifies that when building libraries, the closure from the last build should be used. If no closure exists then it will be computed. Setting this switch also specifies that no recompilation of the closure will occur.
Default value: falseSpecifies that the command should output additional informational output.
Default value: falseRelated 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
- files | directories | views | subsystems
Specifies the objects to be checked and possibly repaired.
For C/C++, may also specify maintainance of the build files.
- options
Use in conjunction with the -version_control option when maintenance is being applied to a subsystem. Applies to the history information of the subsystem. Specifies that the reservation on checked-out files is to be abandoned if the view containing the checked-out file does not exist or is otherwise unreachable.
Default value: falseEquivalent to specifying -locks, -version_control, -compiler, and -permissions.
Default value: falseThis option is on applicable to views that use C/C++ build management. Specifies that build maintenance should occur. In particular, this command will maintain the makefiles and symbolic links that are used to implement the build system.
Build maintenance is automatically invoked prior to build commands when files have been added or deleted by non-Apex commands.
Default value: falsePerforms maintenance on any state involving compilation. This includes the state associated with importing and exporting.
Default value: falseChecks for problems; does not attempt to make repairs.
Default value: false
Aliases: -checkAutomatically assumes that the -locks option is also set. Allows you to recover locks held by a process on a machine that is temporarily inaccessible or has been removed from the network.
If maintain cannot positively determine whether the process holding the lock still exists, it assumes that the process is still active. This option causes maintain to assume the process has terminated and recover locks on that basis.
To avoid inadvertently recovering valid locks, the -force_lock_recovery option is effective only when a file involved in the lock is used as a parameter to the maintain command. If a file is not provided as a parameter, this option is ignored.
Default value: falseWhen a subsystem is specified, limits which version histories in the subsystem are checked. If no value is given, all histories are checked.
Default value: allChecks for abandoned locks and aborted updates. When repair is requested, abandoned locks are recovered and aborted updates are reverted or completed.
Default value: falseChecks the UNIX permissions. In particular, check that the UNIX permissions are consistent with the Apex access control model.
Default value: falseWhen subsystems are specified, causes the nested views to also be checked. When directories outside of subsystems are specified, this causes subdirectories to be checked.
Default value: falseChecks the consistency of the version control information. When applied to subsystems, checks the historydatabases for consistency. When applied to a view or directory, checks the consistency of information for all files in the view or directory. When applied to a file, checks the consistency of the version control information, including the contents of the file and the permissions. If the contents of any file are changed by this process, a .saved file is generated with the original contents.
Default value: falseReleasing 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
maintain -recursive -locks -force_lock_recovery ...
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:
onremote_machine
ps 1
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
- targets
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseOptions that will be passed to make when it is invoked. The default value may be changed in a view by setting the MAKE_OPTIONS context switch.
Default value: " "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
- scope
Identifies the Ada units, directories or views in which make_inline is to examine Ada units and inline them if possible.
- options
Prevents the visiting of inlined declarations.
Causes the inlined declaration to be visited. This is the default if neither -visit nor -no_visit is specified.
This command is not always a semantic preserving transformation, as shown by the following example:
package P is private X : constant := 3; end P; package P.Q is private Y : constant := X; end P.Q;
WheP.Q is made inline, it looks like:
package P is package Q is private Y : constant := X; end Q; private X : constant := 3; end Q;
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,
package Geometry is type Point is private; Origin : constant Point; function Translate (P : in Point; Dx, Dy : in Float) return Point; function Distance (P1, P2 : in Point) return Float; package Circle is type Object is private; function Create (Center : in Point; Radius : in Float) return Circle.Object; private type Object is ... end Circle; private type Point is record X, Y : Float; end record; Origin : constant Point := (0.0, 0.0); end Geometry; package body Geometry is function Translate (P : in Point; Dx, Dy : in Float) return Point is ...; function Distance (P1, P2 : in Point) return Float is ... package body Circle is function Create (Center : in Point; Radius : in Float) return Circle.Object is begin [statement] end Create; end Circle; end Geometry;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.
package Geometry is type Point is private; Origin : constant Point; function Translate (P : in Point; Dx, Dy : in Float) return Point; function Dstance (P1, P2 : in Point) return Float; private type Point is record X, Y : Float; end record; Origin : constant Point := (0.0, 0.0); end Geometry; package body Geometry is function Translate (P : in Point; Dx, Dy : in Float) return Point is ... function Distance (P1, P2 : in Point) return Float is ... end Geometry; package Geometry.Circle is type Object is private; function Create (Center : in Point; Radius : in Float) return Circle.Object; private type Object is null record; end Geometry.Circle; package body Geometry.Circle is function Create (Center : in Point; Radius : in Float) return Circle.Object is begin [statement] end Create; end Geometry.Circle;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
- file1
The first file in the merge. If not supplied, a full version number must be supplied by the -version1 option.
- file2
The second file in the merge. If not supplied, either a full version number must be supplied by the -version2 option or it is assumed that the second file is a version of file1.
- options
Specifies the ancestor version to use. The value compute_ancestor specifies that the common ancestor (if one exists) should be computed from the history relationships. If an actual value is supplied, that value is taken as a version of the file specified by -ancestor_file (or -file1 if -ancestor_file was not set). When -ancestor_file is set, compute_ancestor is the same as current.
Default value: compute_ancestorSpecifies an ancestor file.
Default value: " "By default, changes that occur both in file1 and file2 are applied to the result without annotation. Setting this option annotates such changes.
Default value: falseApplies any non-conflicting changes that originated in file1.
Default value: falseApplies any non-conflicting changes that originated in file2.
Default value: falseApplies all non-conflicting changes, which has the same effect as -apply_file1_changes, -apply_file2_changes and +annotate_common_changes.
Default value: falseSpecifies that file1 will be checked out with a reservation because it is going to be used as the result of the merge. If the file is currently checked out, with a reservation or privately, then this option is ignored.
Default value: falseConsiders whitespace differences as changes. Otherwise, such changes are ignored.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSame as the -visit option.
Default value: falseSpecifies that the result is to be placed into file1. The file1 argument must specify a controlled file which is checked out (with a reservation or privately).
Default value: falseSpecifies that file1 will be checked out privately because it is going to be used as the result of the merge. If the file is currently checked out, with a reservation or privately, then this option is ignored.
Default value: falseSpecifies the file to contain the result of the merge. If not specified (the default), the result is placed in file1.merged.
Default value: " "When -into_file1 is set, then save the original value of file1 in file1.contrib.
Default value: falseIncludes extra annotations, including header lines that describe the parameters.
Default value: falseSpecifies the version of file1 to be used in the merge. By default the current version of file1 is used.
Default value: current
Aliases: -v1Specifies the version of file2 to be used in the merge. By default the latest version of file2 is used
Default value: latest
Aliases: -v2If set, the result file is brought up in the appropriate editor.
Default value: falseChange Regions
The following annotations are used to specify different kinds of changes. The annotations precede text in the result file.
1--|
Specifies a deletion in file1 with respect to the common ancestor.
1++|
Specifies an insertion in file1 with respect to the common ancestor.
2--|
Specifies a deletion in file2 with respect to the common ancestor.
2++|
Specifies an insertion in file2 with respect to the common ancestor.
12-|
Specifies an identical deletion in file1 and file2 with respect to the common ancestor.
12+|
Specifies an identical insertion in file1 and file2 with respect to the common ancestor.
1==|
Specifies a line that occurs in both the ancestor and file1. Only found in conflict regions.
2==|
Specifies a line that occurs in both the ancestor and file2. Only found in conflict regions.
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:
:::| CONFLICT
Denotes the beginning of a conflict, followed by the change region from file1.
:::|-----------------------------
Separates the file1 region from the file2 region.
:::| END CONFLICT
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
- files
Specifies the files to be migrated.
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseSpecifies the directory into which the files will be migrated. Must name a view or a directory in a view. If no value is given, the current directory is used.
Default value: " "-make_options make-options (C/C++)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the command should emit additional informational output.
Default value: falseRelated 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
- The user is running this command in an apex_shell off Apex/ClearCase session.
Salient Points
There are two sections of the output:
- Files in Summit view but not in RSS
- Files that have different version,history, or version control status.
Parameters
maps the given history to main branch (succeeds only if none of the elements on the history have an ancestor element on another history)
specifies a Summit view of a subsystem
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:
- Apex is running in ClearCase mode
- the user is running this command in an Apex shell
- /bin/csh is available
- each destination Rational Subsystem pathname in the migration map file is within a VOB
- the destination VOB(s) have been created and have enough storage
- the destination VOB(s) are mounted
- the user has write permissions to the destination VOB(s), and permission to create attributes/label types
- all files in the source subsystem are checked in
migrate_subsystem migrates each Summit subsystem according to the following rules:
- A Rational Subsystem is created with the pathname specified in the migration map file given by the map-file parameter (see below). The .rss directory, along with the other subdirectories and files that represent the Rational Subsystem (that is, the "characteristic file" structure) are controlled as ClearCase elements.
- For each Summit history, a ClearCase branch type is created with the same name off of /main/0, except for the history that is mapped to /main (see the -main_history parameter below). Versions of a file in a given history are migrated to versions of that file on the corresponding branch.
- For each Summit view sub directory represented in the Summit subsystem's controlled elements, a ClearCase directory element is created on the main branch. This initial version of the subdirectory is created to contain all migrated elements in that directory from any Summit history. Recall that Summit subsystem views may contain subdirectories. Although subdirectories in Summit cannot be placed under version control, in ClearCase directories can be controlled, and moreover must be controlled if they in turn are to contain controlled elements.
- If a file is found to be checked out, the latest checked in version is migrated and a warning is issued.
- The version number, attributes and notes attached to a Summit element are preserved as version number, attributes and notes of the corresponding ClearCase version
- A deleted version is migrated as a normal ClearCase version with a file of 0 size.
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
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.
Specifies a list of one or more subsystems to migrate.
- options
Redirects summary output to logfile.
Maps the given history to the /main branch. This succeeds only if none of the elements on the history have an ancestor element on another history.
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:
- Rational Subsystem (".rss") directories, with contents equivalent to those of the source Summit views
- Subdirectories within each Rational Subsystem corresponding to subdirectories in the source Summit views, with equivalent contents. Only subdirectories within which there are controlled elements are migrated.
- Subsystem characteristics files in the Policy/, Imports/, Exports/, and .Rational/View_Control directories in each Summit view. Names of views imported by the source Summit views are translated into the equivalent Rational Subsystem pathnames according to the migration map file.
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:
element * CHECKEDOUT per-element rules... element * .../branch-name/LATEST element * /main/LATEST
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
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.
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.
Pathname of the config spec file to be generated.
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).
- options:
Apply a ClearCase label to the ClearCase element versions corresponding to the element versions in the source Summit views, as well as to all new controlled elements (directories and subsystem characteristic files) that are created. If the label type does not yet exist in the VOB, it is created. In addition, the label is used in place of LATEST in branch-selection rule:
element * .../branch-name/label
If the -replace option is given, migrate_view invokes cleartool mklabel with -replace. This causes mklabel to apply the label to every element, even if another version of the element on the same branch already has the label (in which case the label is removed from the version that previously carried the label). If the -replace option is not given, migrate_view performs a check on each subsystem before performing the labeling operation to make sure that no versions on branch-name of elements in the subsystem already carry the label. If mklabel could not succeed without the -replace option, then migrate_view prints a warning and skips the labeling operation for that subsystem.
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
- source
- destination
The destination object. Rational subsytems in Apex/ClearCase cannot be moved. For Apex/Summit, if the destination object is a subsystem, the following rules apply:
- A relative name is acceptable if the target context already has a permanent name established.
- Otherwise a full name is required and that becomes the permanent name of the subsystem.
- Certain contexts (like /tmp_mnt) are excluded from containing subsystems.
- options
Allows the move to occur when a view contains privately checked-out files. This option only applies when copying an entire view.
Default value: falseSpecifies that any checked-out files are to be abandoned prior to moving.
This option does not apply when moving an entire subsystem.
Default value: falseSpecifies a file containing a list of attribute names and values which should be set.
Default value: " "The name of the attribute field which will be set. The value "all" may be used to refer to all current attributes of a version.
Default value: " "The value of the attribute which will be set.
Default value: " "-auto_check_in
This option causes the specified export set file to be checked in, provided it was checked out by this operation. The option has no effect if -auto_check_out is not set.
Default value: false-auto_check_out
This option causes the export set file to be checked out, if the file is controlled and currently checked in.
Default value: falseSpecifies that any checked-out files are to be checked in prior to moving.
This option does not apply when moving an entire subsystem.
Default value: false-control_history history (Apex/Summit)
Specifies the history to use when the -control_history option is set.
This option does not apply when moving an entire subsystem.
Default value: default_historySpecifies that you should create the history family named by the -control_history option if it does not exist.
This option does not apply when moving an entire subsystem.
Default value: falseWhen this option is not set, new values are appended to the existing list. When this option is set, new values replace the existing value.
Default value: falseIf checked-out files are abandoned, this option specifies whether the contents of modified files are to be saved in a special .saved file.
Default value: false-set export_set
Specifies the export set to be updated when files are deleted. This option is ignored for objects that are not in a view. Multiple export sets may be specified by quoting a whitespace separated list of export set names. Failure to update of the export set will not cause the command to fail, but will generate warning messages.
Default value: ""Specifies that newly created destination files are to be controlled with the history specified by -control_history. This option only applies when the source file was controlled.
This option does not apply when moving an entire subsystem.
Default value: falseSpecifies that the storage for new views is to be allocated within the designated directory. If no value is given, storage is allocated within the associated subsystem.
Default value: " "When this option is specified, the destination is interpreted as a new parent location for the storage. The logical name of the object does not change. You can apply this only to subsystems and views. (overrides -storage)
Default value: falseSpecifies that newly created destination files are to be left uncontrolled after the copy.
This option does not apply when moving an entire subsystem.
Default value: falseRelated 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
- files | directories | views
- options
Specifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseEnters the text as the note.
Default value: " "Uses the contents of the file as notes associated with the specified version.
Default value: " "Specifies that the command should emit additional informational output.
Default value:falseSpecifies the version with which the note will be associated.
Default value: CurrentRelated 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
- program_units | directories | views | configurations (Ada)
Specifies the program units to be parsed.
- files | directories | views | configurations (C/C++)
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: false-make_options make-options (C/C++)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output.
Default value: falseprepare - 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
- files | directories | views | configurations
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falsepretty_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
- program_units | directories | views | configurations (Ada)
Specifies the program units to pretty print.
- files | directories | views | configurations (C/C++)
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: false-make_options make-options (C/C++)
Options that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output
Default value: falseproperties - 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
- files | directories | views | subsystems
Information is shown for these objects. If no objects are provided, information for the current directory is shown.
- options
For example, the information displayed for a view would look like the following:
/test/lower.ss/rev1.rel Class: Release Kind: Stable Model: /apex/base/ada/model.ss/sun4_sunos.1.2.rel Storage: /accts/mars.d Access Control Properties Group: devel Category: group_public Directories: rwxrwsr-x Files: rw-rw-r-- Build Properties Supported Language: Ada Host Architecture: sun4 Target Architecture: sun4
/test/lower.ss/rev1.rel Class: Release Kind: Stable Model: /apex/base/c++/model.ss/sun4_sunos.1.2.rel Storage: /accts/mars.d Access Control Properties Group: devel Category: group_public Directories: rwxrwsr-x Files: rw-rw-r-- Build Properties Supported Language: C++ Host Architecture: sun4 Target Architecture: sun4
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
- files | directories | views
Specifies the files to be recovered. May specify deleted files, deleted directories, existing directories, or views. When directories or views are named, all deleted files in the directory or view are recovered.
- options
Do not check or do model related processing.
Does not do host specific processing (like apex delete of a file will not remove object, sienna, or diana files).
If the latest version of the file is deleted, a new version is created whose contents correspond to the contents of the last undeleted version.
Default value: falseRelated Commands
register - registers the files in the registered set
Syntax
register [options] files...
Description
Registers the named files in the specified set.
Parameters
- files
- options
-auto_check_in
This option causes the registration file to be checked in, provided it was checked out by this operation. The option has no effect if -auto_check_out is not set.
Default value: false-auto_check_out
This option causes the registration file to be checked out, if the file is controlled and currently checked in.
Default value: falseCreate the registered set if it does not exist.
Default value: false
Aliases: -create_reg_setIn views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseThis option causes the registered set information to be refreshed. This is typically used when the contents of the registration file have been edited.
Default value: falseRelated 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
remdlDescription
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
- views | configurations
Specifies the views to be updated. Currently, this parameter may name only one view per subsystem.
- options
Forces the operation to occur even if some consistency condition would normally prevent it.
Default value: false-import views_or_configurations
Specifies imports that are to be updated as part of remodelling. The effect is the same as if the import -update command were run.
Default value: ""Specifies the model to be used. To be used as a model, this view cannot have obsolete compiler key or build key information.
Default value: ""Refreshes the model-oriented information in the view. In particular, the switches and the imports are re-analyzed.
Default value: false-release_kind development | stable | frozen | preserve
Changes the kind of a release. Changing the kind to frozen implicitly causes a refresh of all other information, as if -refresh had been specified.
Default value: preserveApplied only when a new model is specified. If this option is not set, only the COMPILER_KEY, BUILD_KEY, CPP_COMPILER_HOME, and CPP_COMPILER_VARIANT switches are updated to the value specified in the switch file of the model. If this option is set, the entire switch file is updated to match the contents of the switch file in the specified model.
Default value: falseSpecifies that the specified views are to be made up-to-date with respect to the last previous model. This option can be used when the characteristics of the compiler key or build key have changed and those changes need to be propagated into the view.
Default value: falseRelated 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
- domain
Specifies the simple name of the domain reference to be removed.
- options
Specifies the root of the source tree from which the domain will be removed. If no value is specified, the enclosing source tree is used.
Default value: " "Related Commands
remove_export - removes the exports
Syntax
remove_export [options] program_units | directories | views...
Alias
rmxpDescription
No longer exports the objects from their enclosing views.
Parameters
- program_units | directories | views
Specifies the program units that are not to be exported.
- options
Specifies the export set to use. Multiple export sets may be specified by quoting a whitespace separated list of export set names.
Default value: default_export_setRelated 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:
rm Imports/Description.cfg touch Imports/Description.cfg import -refresh .
Parameters
- importer
Specifies the view whose imports are being changed. May be a working view or a configuration containing working views.
- old_imports
The imports being changed. Subsystems, views, and subsystem simple names can be specified. Names of deleted views are acceptable.
- options
Removes all imports for the designated importers.
Default value: falseRemoves all mutual imports for the designated importers.
Default value: falseRemoves any imports that are deleted or otherwise unreachable. This can be dangerous if the subsystem is temporarily inaccessible. For example, a view may appear to be unreachable when it is not accessible due to network failure.
Default value: falseThe -unused option will be ignored if used without one of the following options.
Apply Apex dependencies to all C++ views
Apply Apex parse to all Ada views
Apply Apex import -refresh to all views
Process each argument separately
Process all arguments as a single library
Displays additional information, including a description of any obsolete state and a list of the export set that has been specified for each imported view.
Default value: falseRelated 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
- files | directories | views | subsystems
The objects for which the report will be generated.
- options
Expand any configuration arguments.
Default value: falseThe format string to use.
Default value: " "The name of a file containing the format string.
Default value: " "List the keyword replacement symbols.
Default value: falseA file into which the report will be written. If not specified the report is written to standard output.
Default value: " "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:
%apex report -format "{<object:t> <object'cmvc_state>,<nl>}" *
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
- ada_name
Ada name to be resolved. If -file_mode is specified, the Ada name is assumed to be the file name of an Ada package, procedure or function,
- options
-resolve_context configuration | context
Specifies the context in which the name is to be resolved. All views in the import closure of the given context are examined to resolve the specified Ada name. If this parameter is omitted, the current context is used.
If this boolean parameter is specified, the Ada name is assumed to be a file name of an Ada package, procedure or function.
Examples
- 1 . resolve_ada_name text_io.put_line
Example output for this command is shown below.
Resolutions in: /ned/base/predefined.ss/geb/sol.geb.wrk/io/text_io.1.ada Line: 127, Character: 15 procedure Put_Line (File : in File_Type; Item : in String); Line: 128, Character: 15 procedure Put_Line (Item : in String); /ned/base/predefined.ss/geb/sol.geb.wrk/io/text_io.2.ada Line: 474, Character: 15 procedure Put_Line (File : in File_Type; Item : in String) is Line: 480, Character: 15 procedure Put_Line (Item : in String) isNote: 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
- options
Change the working directory to <dir>. You can specify . to use the current directory as the working dorectory. ( -d .)
Show this usage message and exit.
Changes the maximum allowable size for an e-mail from -s <maximize>.
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
- files | directories | views
Specifies the objects which versions are associated with. If this argument is not provided then the -current option must specify a full version name.
When a file is specified the version is associated with that file. When a directory or view is specified the versions are associated with the controlled objects in the directory or view.
- options
Specifies a file containing a list of attribute names and values which should be set.
Default value: " "The name of the attribute field which will be set. The value "all" may be used to refer to all current attributes of a version.
Default value: " "The value of the attribute which will be set.
Default value: " "If this option is set then attribute fields will be cleared. Note that this may be different than initializing those fields.
Default value: falseSpecifies the version with which the note will be associated.
Default value: CurrentSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseIf this option is set then attribute fields will be set to their designated initial values.
Default value: falseWhen this option is not set, new values are appended to the existing list. When this option is set, new values replace the existing value.
Default value: falseAttributes will be set on the versions associated with the specified task.
Default value: " "Specifies that the command should emit additional informational output.
Default value: falseset_history - changes the version history file used (Apex/Summit)
Syntax
set_history [options] history files | directories | views...
Alias
sethstDescription
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
- history
Specifies the history that will be used.
- files | directories | views
Specifies the objects that will share the history. May specify views, directories, or files. When views or directories are specified, the operation is applied recursively to all the contained files and subdirectories.
- options
Specifies that checked-out files are abandoned prior to changing the history.
Default value: falseSpecifies that checked-out files are to have their history changed and remain checked out.
This option is allowed only if the new history is not checked out. If the file is checked out and this option is set, -match, -create, and -latest are ignored.
Setting this option is equivalent to the following sequence of commands:
Default value: falseSpecifies that checked-out files are checked in prior to changing the history.
Default value: falseIf the files are uncontrolled, they will be controlled with the named history.
Default value: falseSpecifies that a new version is to be created if the file contents do not match the latest version.
Default value: falseSpecifies that the named history should be created if it does not exist.
Default value: falseSpecifies that the history will become the default history for the specified views.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the' configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseDo not check or do model related processing.
Specifies that file contents are to be changed if the contents do not match the latest version.
Default value: falseSpecifies that file contents must match the latest version.
Default value: false-must_create_new_history
-must_not_create_new_historySpecifies whether a new history must (or must not) be created for the objects whose history is being changed. By default, a new history is created if it does not already exist. Note that these options do not control whether a new history family is created for the associated subsystem. The -create_history option controls that.
Specifies that compilation artifacts should not be copied with source files.
Default value: falseDoes not do host specific processing (like apex delete of a file will not remove object, sienna, or diana files).
-no_keyword_replacement
Inhibits the replacement of substitution strings. When this option is set, substitution symbols are left in their original form. Applies to cmvc versions being created (controlled).
Default value: falseEnters the text as a note for the version in the history associated with the object.
Default value: " "Enters the contents of the file as a note for the version in the history associated with the object.
Default value: " "Saves the file if a checked-out file has been modified and is abandoned.
Default value: falseSpecifies that the command should emit additional informational output.
Default value:falseRelated Commands:
set_location - sets the permanent name (Apex/Summit)
Syntax
set_location [options] directories | subsystems | views...
Alias
setlocDescription
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
- directories | subsystems | views
- options
Replaces an existing name with a new name. Otherwise, objects that have an existing permanent name are not affected.
Default value: falseRelated 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
- name1, name2, ... nameN
Specifies the names of the context switches
- value1, value2, ... valueN
Specifies the values of the switches.
- options
-switch_context subsystems_or_views_or_configurations
Specifies the context in which to change the switch file. If a subsystem or view is specified, the associated switch file is changed. If a configuration is specified, switches are changed in all views listed in the configuration. If no context is specified, switches are changed in the enclosing view or subsystem.
Default value: " "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
- files | directories | views
Specifies the objects to revert. May name files, directories, or views.
- options
Abandons checked-out objects prior to changing the version.
Default value: falseAllows a file to be changed while it is checked out. The contents of the version are copied onto the file and the file remains checked out.
Default value: falseChecks in any affected objects currently checked out. The version is changed after the check in.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecDo not check or do model related processing.
Specifies that compilation artifacts should not be copied with source files.
Default value: falseDoes not do host specific processing (like apex delete of a file will not remove object, sienna, or diana files).
Reverts the object to this version. Note that the default causes objects to revert to their previous version.
Default value: PreviousIf checked-out files are abandoned or overwritten, this option saves the contents of each modified file in a .saved file.
Default value: falseSet to the versions in the specified view. This option overrides the -replacement option. May name a set of views.
Default value: " "Specifies that the command should emit additional informational output.
Default value:falseRelated Commands
- abandon - abandons the check out
- accept_changes - propagate changes between objects (Apex/Summit)
- check_in - checks in the objects
- accept_latest - same as accept_changes with the -latest option (Apex/Summit)
- control - places the objects under version control
- uncontrol - removes the objects from version control (Apex/Summit)
- accept_latest - same as accept_changes with the -latest option (Apex/Summit)
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
- directories | views | subsystems
Specifies objects in the local domains source tree.
- options
Specifies the domain to be displayed. By default, information about all domains is displayed.
Default value: all_domainsSpecifies that information about the objects in the source tree should be shown. This generates a table with an entry for each directory, subsystem, and view that is a child of the parameters. Each table entry shows whether the object is local to the name or in a remote domain.
Default value: falseRelated 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
- views
Shows all the exports for these views.
- options
Shows the exports in the named set. Multiple export sets may be specified by quoting a whitespace separated list of export set names. Use the special name all to show the exports in all export sets.
Default value: default_export_setExport 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:
- Valid
Specifies that there are no problems with the exported unit.
- Deleted
Specifies that the unit has been deleted since it was exported.
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:
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
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
- views | subsystems
Specifies the subsystems and views to display. When no names are provided, the enclosing subsystem or view is used.
- options
Specifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecSpecifies that the command should emit additional informational output.
Default value:falseRelated 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
- views | configurations
Specifies the views to display.
- options
Generates a system description that includes designated views and the views in their import closure.
Default value: falseSpecifies the file in which to save the system description.
Default value: "Description.sysd"Displays the imports in a system-oriented manner that emphasizes the import relationships between a set of views. Showing the imports of a single view in system mode will also show the import relationships for the entire import closure of the original view.
Default value: falseDisplays unused imports. The -unused option will be ignored if used without one of the following options.
Displays additional information, including a description of any obsolete state and a list of the export set that has been specified for each imported view.
Default value: falseVerbose 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:
- Valid
Specifies that the imported view has valid import information and has not been changed since it was imported into the current view.
- Deleted
Specifies that the imported view has been deleted or is otherwise inaccessible.
- Modified
Specifies that the imported view has valid import information that has been changed since it was imported into the current view.
- Obsolete
Specifies that the imported view has obsolete information, because the views it imports have been modified.
- Obsolete/Modified
Specifies that the imported view has been modified and is also obsolete.
- Malformed
Specifies that the imported view is badly formed. Run the maintain command to provide additional information or to repair the view.
The Kind field provides information about the type of import and possibly how it was provided to the current view. The values are:
- Normal
Specifies that the import is a normal hierarchical import.
- Mutual
Specifies that the import is a mutual import.
- Model
Specifies that the import is a hierarchical import provided by the model.
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:
- A summary of whether or not the imports for the view are currently valid and the reason. If the imports are invalid because the BUILD_KEY or COMPILER_KEY switch has been changed, the old and new values are displayed.
- Whether or not the import description files have been edited since the imports were last analyzed.
- The time at which the imports were last successfully updated.
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
- files | directories | views | subsystems
Prints the permanent name currently used by each of these objects. If no arguments are provided, prints the current working directory.
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
- directories | views | subsystems
Specifies that a lock context is a view, a subsystem, or a directory outside of a view. All the locks are shown for the contexts of the specified objects.
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
shst, show, statusDescription
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
- files | directories | views
The files whose version control status will be shown. Can specify views, directories in views, or files. If no parameter is supplied, the enclosing directory is used.
- options
Shows the status for all objects.
Default value: falseShows the status for controlled objects that are checked in.
Default value: falseShows the status for checked_out objects.
Default value: falseShows the status of files whose history is checked out in another view.
Default value: falseShows the status for deleted objects.
Default value: falseSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecShows the status for controlled objects whose version is prior to the latest checked-in version.
Default value: falseSpecifies that only attributes specified by the -show_attrs option are to be shown.
Default value: false
Note: Quotes are needed if more than one attribute is specified.
Specifies a list of extended attribute names which should be shown in addition to the predefined attributes. The attributes are only shown when either the -verbose option or the -no_predefined_attrs option is also specified.
Default value: " "Shows the status for uncontrolled objects.
Default value: falseSpecifies that the command should emit additional informational output.
Default value:falseRelated 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
- directories | views | subsystems | property_switch_files
Specifies the objects whose associated switches are shown.
If no specific options are set, -session and -context are assumed.
- options
Shows switch aliases. This option is orthogonal to the -session, -context and -property options. If specified, aliases are included with the non-alias switches of the specified switch kinds.
Default value: falseShows all switch information.
Default value: falseShows context switches.
Default value: falseShows the default values of the switch(es).
Default value: falseShows the property switches.
Default value: falseShows session switches.
Default value: falseShows information on the particular switch. If you use the -output_filter none (or -of none) option, you will only get one line of information.
Default value: falseControls the width of the displayed value column. A value of 0 implies that the column will be as wide as the widest value so no value is truncated.
Default value: 120Related 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
- ada_name
Ada name for the declaration whose usages are to be displayed. The name is resolved in the current context.
- options
Forces a summary listing/window to appear even if there is only one item in the result.
Compile the -search units and the argument units to at least this state before computing usages.
Labels on declare-begin-end blocks are never marked as unused.
Names exported by a library specification or a library level subroutine are never marked as unused.
Loop identifiers (the "I" of "for I in 1..10") are never marked as unused.
Loop labels are never marked as unused.
Specifies the compilation context to use for the analysis. Defaults to the view containing the Ada object or unit. The context is either a single view and its imports or is it a collection of views specified by the contents of a configuration file.
Forces a window to appear with result. This is the default for show_usage from the GUI but not from the command line.
Specifies which units are included in the report.
none only those directly named by -search
import include those in the imported views.
link include all units in the linkage closure of -search
Default value: none
Default value: noneSpecifies the Ada units in which usages are to be examined while calculating unused declarations.
Specifies which Ada units to search. Modifies the operation of -search
none just search named units
import Also search all units in the imports
link Search linkage closure of the named units
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
- ada_name
Ada name for the declaration whose usages are to be displayed. The name is resolved in the current context.
- options
Forces a summary listing/window to appear even if there is only one item in the result.
Compile the units in the search scope to at least the specified goal_state state before computing usages.
Specifies the compilation context to use for the analysis. Defaults to the view containing the Ada object or unit. The context is either a single view and its imports or is it a collection of views specified by the contents of a configuration file.
Forces a window to appear with result. This is the default for show_usage from the GUI but no from the command line.
Specifies which units are included in the report
none only those directly named by -search
import include those in the imported views.
link include all units in the linkage closure of -search
Default value: none
Default value: noneSpecifies the Ada units in which usages are to be examined while calculating usage declarations.
Specifies which Ada units to search. Modifies the operation of -search
none just search named units
import Also search all units in the imports
link Search linkage closure of the named units
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
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
shver, versions, lsvtreeDescription
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
- files | directories | views
- options
Specifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecSpecifies the first version to show.
Default value: FirstSpecifies the last version to show.
Default value: LastShows the notes as well as the other information.
Default value: falseSpecifies that only the notes associated with the requested versions are displayed.
Default value: falseSpecifies a list of extended attribute names which should be shown in addition to the predefined attributes. The attributes are only shown when the -verbose option is also specified.
Default value: " "
Note: Quotes are needed if more than one attribute is specified.
Specifies that the command should emit additional informational output.
Default value:falseRelated 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
- files | directories | views
- options
Specifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseIf set to a non-empty value, the version image is stored in the file.
Default value: " "Specifies the version to be shown. May be a simple or a full version number. If a simple version number is specified, the version is relative to the current version history of the objects. If a full version number is specified, that version is shown and the objects are ignored.
Default value: PreviousSpecifies that the command should emit additional informational output.
Default value: falseRelated 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
- files | directories | views | configurations
- options
In views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "-strict
Specifies that any configurations listed should not be expanded; instead these files will be treated like any other files.
Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falsetree - display Diana tree of an Ada object
Syntax
apex tree [options] <file_name>
Description
Displays the Diana tree of the specified Ada object.
Arguments
- <file_name>
An Ada object or a preprocessor object
- options
-debugger
-decl_numbers
-help
-id_table
-lx
-nocg
-normalize
-paths
-verbose
-sm_ops
-summary
-supplier
-symbols
-unrooteduncontrol - removes the objects from version control (Apex/Summit)
Syntax
uncontrol [options] files | directories | views...
Alias
unctrlDescription
Removes the objects from version control. The objects no longer needs to be checked out to be modified.
Parameters
- files | directories | views
Specifies the objects to be uncontrolled.
- options
Specifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseSpecifies that if any configuration files are passed as parameters to this command, the operation is applied to the views referenced by the configuration and not to the configuration itself.
Default value: false
Aliases: -expand_configs, -ecIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: false-private
Specifies that a privately checked-out file is to be uncontrolled, without modifying its current contents (the private check-out is abandoned).
Specifies that the command should emit additional informational output.
Default value:falseRelated Commands
unregister - removes the files from the registered sets
Syntax
unregister [options] files...
Description
Removes the files from the specified sets.
Parameters
- files
- options
The name of the registered set. This option is required.
Default value: " "This option causes the registration file to be checked out, if the file is controlled and currently checked in.
Default value: falseThis option causes the registration file to be checked in, provided it was checked out by this operation. The option has no effect if -auto_check_out is not set.
Default value: falseIn views which support multiple "components" this switch is used to determine the component to which the operation is applied. The standard models support development of C/C++ and Java components, the value of the switch determines whether the C/C++ components, the Java components, or both will be built. For example, if the value of the switch is "cpp" (the default) then applying the code command to the view will cause C/C++ units to be coded but no Java units will be compiled. The possible values are cpp, java, and java_cpp. Note that java_cpp is used when the view contains Java and C/C++ units to compile. The default value in a particular view can be changed by setting the BUILD_COMPONENT context switch in the view.
Default value: cppSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the code command, the names of the files requiring recompilation are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur even if it is not necessary. For example, when the option is applied to the code command, all arguments are recompiled even if recompilation is not needed.
Default value: falseWhen this option is applied to a build command, the command is applied to specified objects and to all imported views of the specified objects. The imported views are processed in the import order so that views which have no imports are processed first.
Default value: falseOptions that will be passed to each invocation of make. In particular, these options will be passed to make when make is called as part of executing other build commands. For example, setting -make_options to the value "-d" will normally provide tracing of the underlying make command.
Default value: " "Specifies that the command should emit additional informational output. For example, when the option is applied to the code command, invocations of the compiler by make will be emitted along with their arguments.
Default value: falseRelated 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
- files | directories | views
Specifies the objects which versions are associated with. If this argument is not provided then the -current option must specify a full version name.
When a file is specified the version is associated with that file. When a directory or view is specified the versions are associated with the controlled objects in the directory or view.
- options
The name of the attribute field which will be set. The value "all" may be used to refer to all attributes of the designated versions.
Default value: " "Specifies the version with which the note will be associated.
Default value: CurrentSpecifies that the command should only emit information about what the command would do if invoked in the normal way. For example, when the option is applied to the check_in command, the names of the files which would be checked in are emitted.
Default value: falseIf set then processing stops when the first error occurs.
Default value: falseSpecifies that operation should be forced to occur if it would normally be disallowed by some constraint.
Default value: falseAttributes will be reset for the versions associated with the task.
Default value: " "Specifies that the command should emit additional informational output.
Default value:false
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |