![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Switches Switches are used by Apex to specify command options and to control various aspects of object management, version control and compilation. Some provide critical information required by a command while others merely affect the amount or detail of the information commands produce.
The following topics are covered in this chapter:
- Overview
- Switch Kinds
- Switch Name Format
- Switch Types
- Switch Syntax
- Switch Values
- Inclusion
- Registration
- Managing Switches
OverviewSwitches are categorized by their associated context, which in turn determines the scope of their effects. Session switches apply to everything within a particular Apex session, while context switches only apply to operations or files in the subsystem or Summit/CM view (Apex/Summit) where they are defined. The following sections describe how to use switches; individual switches are described along with the commands that use them.
Each Apex switch has a number of characteristics which include:
- A switch kind which determines the scope of the switch and how its value will be stored. Some switches are stored in UNIX environment variables while other switches are stored in files associated with specific library contexts.
- A switch name which determines how the switch will be referenced.
- A switch type which determines the possible values of the switch.
- A current value which is set in either an environment variable or a file and thus may be relative to a particular scope.
- A default value which will be used if the switch has no current value.
There are switches that correspond to many of the options of most Apex command line commands. These commands are described in the online document, Command Reference which can be displayed by executing the Help > Manuals > Command Reference command. When you invoke an Apex command, the precedence for each option is:
- If you specified the option on the command line, use it.
- Otherwise, if the corresponding switch is defined, use it.
- Otherwise, use the default value.
Some switches do not correspond to command options because it would not be useful to be able to specify them on a command line.
Most switches can be displayed with the Control > Reports > Switches (Apex/Summit) or Compile > Architectural Control > Show Switches (Apex/ClearCase)command, which brings up the Switch Report dialog box illustrated in Figure 30.
Figure 30 Switch Report Dialog Box
![]()
Switch KindsThere are three kinds of switches: Session, Context, and Property. The kind of a switch determines the scope of its effect.
Session Switches
Session switches are associated with an entire Apex session. A session switch can be set as an environment variable or as a command option. A switch alias cannot be used to set a session switch in the environment.
Session switches are UNIX environment variables whose names begin with APEX_. You set them the same way you set any UNIX environment variables. Through the GUI, use the Tools > Session > Environment command.
% setenv APEX_EDITOR vi
or in the Bourne or Korn shell:
$ APEX_EDITOR=vi $ export APEX_EDITOR
Note: Session switch names are case-sensitive. Use all uppercase.
When you start Apex with the apexinit command, it sets several session switches —— that is, environment variables —— for you, but it does not override the values of any session switches that you have already set.
For additional information on the apexinit command, open an Apex shell (Tools > Shell) and enter:
man apexinit
To see the session switches that you or apexinit have set, in an Apex xterm, use the Tools > Session > Environment command or enter the following command in the C shell:
% setenv | grep APEX_
or enter the following command in the Bourne or Korn shell:
$ env | grep APEX_
To see a table of all session switches and their current values, use Control > Show > Switches (Apex/Summit) or Compile > Architectural Control > Switches (Apex/ClearCase) or enter the following command:
% show_switches -session
If you or apexinit have not explicitly set a switch, its default value is shown. Changes to your session switches do not take effect until you exit and restart Apex.
Context Switches
Context switches are specified in switch files and are associated with the context that contains the file. Some context switches can also be set as command options, depending on how they affect commands performed in their associated context.
A context switch file named Switches can be found in the Policy directory of every library context. Other switch files, with an extension of ".sw", can be created in subsystems, Summit/CM views, or elsewhere. The Policy/Switches file is used implicitly by operations performed within a library context.
Context switches apply to commands that are executed in, and objects that reside in, a specific subsystem or Summit/CM view. Each subsystem and Summit/CM view contains a switch file —— Policy/Switches —— and that file contains switches that apply only to the enclosing context.
For Apex/Summit, the switch file in a subsystem is used to initialize the switch file in a newly created working view when no model is specified as part of view creation. The switch file in a view is used when placing objects under Summit/CM control, compiling and debugging source code, spawning new released views, and so on.
In a switch file, switches are listed one per line and formatted as follows:
OPTIMIZATION_LEVEL: 2 REPLACE_TABS_WITH_BLANKS: False
Note: Context switch names are not case-sensitive, but by convention they are written in all uppercase.
To see a table of all the context switches in the current context and their current values, use Control > Reports > Switches and select the Show Context Switches option or enter this command:
% show_switches -context
The Control > Show > Switches command will open an Apex editor window containing the context switches for the enclosing subsystem or Summit/CM view. Changes to your context switches take effect immediately; subsequent Apex commands will use the new switch values.
Please see the "Switches" topic in the Online Reference for a complete description of each switch.
Property Switches
Property switches, like Context switches, are also associated with a context, which is usually a Summit/CM view or Rational subsystem. They are used by Apex to manage various Summit/CM view or Rational subsystem properties, such as those associated with build management. These files have an extension of .prop, but certain .sw files may also contain property switches.
Switch Name FormatSwitch names are composed of alphanumeric characters and underscores. Context and property switches may also include periods. Some switches have alternate names known as aliases; these are primarily useful for shorthand when typing command lines. For example, for Apex/Summit, the -checked_in option for the Apex show command can be specified by its -in alias.
Switch TypesEach switch has a type that determines what values it can represent.
The value of a boolean valued switch may be specified with literals: the strings "false", "off", or "no" are recognized for a false value, and the strings "true", "on", or "yes" are recognized for a true value. The case of these literals is insignificant. In addition, a numeric value may be used; a value of zero means false, any other value means true.
The value of an integer valued switch may be specified as a signed decimal number, or in C style notation with a leading "0" for octal or leading "0x" for hexadecimal.
The value of a string valued switch is just its literal content. For a file switch, this excludes any leading spaces between the switch name with its colon separator and the value itself. Double quotes can be used around the entire value to include leading or trailing whitespace.
The value of a pathname switch is the same as a string valued switch. If the switch value is not fully qualified (that is, does not start at root), it is made fully qualified relative to the structure that encloses the source switch file. For property switches, this is the directory associated with the property switch file that contains the switch.
A token valued switch is a special form of a string switch with whitespaces separating its components. Surrounding whitespace is not significant. Token valued switches may also be differential, that is, they may specify additions or deletions relative to previously seen values of the same switch.
A search-path valued switch is similar to a token valued switch, except that a colon is used as the token separator. Search-path valued switches may be differential.
An aggregate valued switch is a special form of a string switch that uses aggregate notation to define a sequence of string tokens or other sequences. This kind of switch is typically used to define various kinds of tables, with a variable number of dimensions and values per component. This switch type is typically used only for property switches.
A table valued switch is a special form of an aggregate switch that has a defined two-dimensional format. A table valued switch may be differential, but only additions are allowed. This switch type is typically used only for property switches.
Switch SyntaxSession switch values are set in an environment variable whose name corresponds to the name of the switch, in all capitals, prepended with "APEX_". For example, the environment variable for the "Verbose" session switch would be APEX_VERBOSE. A switch alias cannot be used to set a session switch in the environment; therefore, although "V" is an alias of "Verbose", setting APEX_V will have no effect.
All other switch values are set by the following syntax.
- Command line syntax for non-boolean switches.
-switch value -switch=value -switch:=value -switch-value -switch:+value -switch-value -switch:-value
- Command line syntax for boolean switches.
For the forms with just the switch name but no explicit value, a leading `-' specifies a true value, and a `+' specifies a false value.
-switch +switch -switch=value -switch:=value
- Switch file syntax.
switch: value switch:= value
- Additional switch file syntax for differential switches.
switch:+ value switch:- value
Additional switch file syntax for multi-line values which can be used for either regular or differential values. In the second form, the ending marker with the closing brace must be on a line by itself.
switch: first \ second \ third
{switch: first part middle part last part
switch}
The following shows examples of valid switch specifications.
BOOL: on STRING: a string value PATHNAME: Linker.cfg SEARCH.PATH: ../Imports:../Exports INCLUDE: local_switches.sw TOKENS: one TOKENS:+ two TABLE: { { first table row }, \ { second table row }, \ { third table row } } {ANOTHER_TABLE: { { first table row }, { second table row }, { third table row } } ANOTHER_TABLE}
Switch ValuesSwitch values are subject to keyword and naming attribute replacement, and may be absolute or differential. Options may be differential relative to other options, to values from either switch files or environment variables (depending on the switch kind), or to default values.
Values are read from switch files in the order they appear. When the same switch is specified multiple times, either in the same file or indirectly through an included file, the value supplied for the last occurrence is the one that is used. Differential switches modify this by using each value as it is encountered to incrementally change the current value.
Whitespace at the beginning and end of each line within a multi-line value (after a trailing backslash, if any, is removed), is not considered part of the value. Quotes can be used to embed any such whitespace should it be required. Strings can be catenated with a `+' or `&' appearing outside of any other quoted string, the same as within aggregates. As shown in this example, the resulting switch value will contain two spaces between the words `first' and `of'.
SWITCH: "the first " \ + " of several lines" \ + " that comprise a single string value"
Switch files can be changed manually with an editor, or with the Apex set_switch command. When set_switch is used, the new value is always appended to the file. If the new value is not differential, any other non-differential values are removed from the switch file. The new value is always written on a single line.
Replacement
Values of most switches may contain keywords and naming attributes that are processed when the switch value is read. Some switches do not allow one or the other of these replacements; this is generally true for many property switches where keyword replacement needs to be done later. Basic keywords are allowed in switch values, but the complex list and generator forms are not. Naming attributes are useful to obtain information from some context other than the one associated with the current switch context. For example, in Apex/Summit, a switch value can be set to the name of the associated view's model using keyword replacement like this:
name: <view'model>
Attributes are also useful for command line options. In the following Apex/Summit example, a view is created using the same model that is used by some other view (note that percent is used instead of the apostrophe to avoid having to quote the entire argument string):
% apex create_working -model /path/to/other/view%model new_view_nameAs another example, a switch value can be made to have the same value as specified in a switch file in another context (the view's model in this case), with this combination of keyword replacement and naming attributes:
RELEASE_NAME: <view'model>/common_switches.sw'switch(RELEASE_NAME)Differential Values
The values of certain switch types may be composed from several values by incrementally adding or removing components. The switch type determines what a component is. Each token of a token valued switch, each pathname of a search-path valued switch, and each row of a table valued switch is a component. Table rows can be incrementally added but not removed.
A differential value is specified with a `+' to add a value and a `-' to remove a value. These extra characters follow the colon in a normal switch specification; see the section about switch syntax for details. Replacement is performed on each differential value before it is combined with any others.
A differential value is relative to any values that appear before it in the following order:
- 1 . default value
- 2 . context value from current switch file and any included files
- 3 . option value combined with any prior option values
An absolute value replaces any values that precede it in this ordering. This also applies across included files, that is, an occurrence of the switch in an included file can replace the value from the current file, provided the include follows the current value.
For example, assuming "name" is a token valued switch, a switch file might contain a sequence of values such as the following:
name: zero name:= one name:+ half name:+ two three name:- half name:+ four
The value of this switch would be "one two three four" as a sequence of tokens. The token "zero" is not included because the "name:= one" value is absolute and replaces it. The token "half" is not be included because "name:- half" removes it.
InclusionSwitch files may use one or more include switches to include the content of other switch files. Each include switch is search-path valued. Include switches can appear more than once to include several files, or a single include switch can name more than one file. Include switches cannot be tagged.
The INCLUDE switch allows the named switch file to be included as if the contents of the switch file had been textually inserted into the referencing file. It is an error if an included switch file does not exist, provided the value being read depends on the included file.
The INCLUDE_OPTIONAL switch has the same meaning as INCLUDE except that no error occurs if the named file does not exist.
Inclusion in property switch files works the same as for context switch files, except that different switches must be used, namely INCLUDE_PROPERTY and INCLUDE_PROPERTY_OPTIONAL.
Protection against multiple includes of the same file is implicit; no switch file is included more than once. A file is included at the point where the last include switch names it.
When resolving the names of included switch files, the context is the directory containing the referencing switch file. The named files may have relative or absolute path names. In addition, the names of included switch files are subject to keyword replacement, so it is convenient to make them relative to the current Summit/CM view, the subsystem, or even its model. For example, the following will include a switch file from the model library context:
INCLUDE: <model>/model_switches.sw
Other keywords are useful for producing a hierarchy of switch files with limited scope. The following INCLUDE switch will include a switch file named switch.sw from the enclosing directory, but if the current directory is the library context itself, the result of the keyword replacement is empty which makes the include switch value empty, so nothing is included at that level.
INCLUDE: <dir:pview:append(/switch.sw)>
Switch file inclusion is useful for controlling switch files.
Apex/Summit
Because the Policy/Switches file is automatically updated by various Apex operations, placing it under source control can be problematic. But Policy/Switches can include a local switch file that can be controlled without causing any of those problems. If the include switch is at the end of Policy/Switches, any values in the local file would override those in Policy/Switches.
Apex/ClearCase
Policy/Switches file(s) are controlled when the Rational subsystem is controlled.
RegistrationThe set of switches known to Apex is defined by a set of registration files, which are located in the directories specified by the $APEX_MESSAGES environment variable. The same language-specific subdirectories as used to locate message files are used. The registration files are automatically generated and are not intended for customization.
If a switch file contains an unrecognized switch, Apex will produce a warning message, but otherwise ignore the switch and its value. When this happens, it usually means the command was applied in a context where the switch file contains switches defined for a layered product, but the current session does not have that product enabled.
Managing SwitchesSwitch files may include other switch files, providing a means to centralize switch values. In addition, switches may be overridden to allow you to try out non-standard settings.
For example, let's assume that the file Standard.sw contains the standard switch settings. This file is stored in a special place and is under version control.
In a user library context, their switch file would contain
include: <pathname>/Standard.sw
This line provide access to all of the switches in Standard.sw.
Now let's assume that Standard.sw contains a following setting for the CPP_OPTIONS switch in order to provide the standard options for compiling C++ code.
CPP_OPTIONS: in
To override this setting, the local switch file could contain
include: <pathname>/Standard.sw CPP_OPTIONS: -g
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |