Ant Command Syntax for Running the Assistant
To run the Windchill Configuration Assistant, enter an ant command in one of the following general formats:
ant -f WindchillConfigAssistant.xml -projecthelp
Using this format displays a description of the main targets that can be specified.
ant -f WindchillConfigAssistant.xml target [-Dinteractive=false] [-Dpropagate=true] [-D<Property>=<Value>]
Using this format executes the specified target and optionally provides arguments that you can use to turn off the interactive mode, propagate configuration changes, and override values for specific properties.
You can specify one or more -D<Property>=<Value> arguments to set one or more property values that are then used in place of the default values used by the assistant. The set of property value defaults are stored in <Windchill>/utilities/wca/Configurator.properties file.
Targets for WindchillConfigAssistant.xml
The targets for WindchillConfigAssistant.xml can be grouped as follows:
• Targets that calculate recommended configuration values, write them to intermediate properties files.
• Targets that propagate changes already stored in intermediate properties files.
• Targets that you can use to restore your system to a previous configuration.
• Targets for adding and removing the ConfigurationRef element from the site.xconf file.
The following sections describe the targets that are supported for configuration options.
Targets for Calculating Recommended Values
The following list describes the targets that you can use to calculate recommended configuration values and write them to intermediate properties files.
 |
If the -Dpropagate=true command line argument is set, then the new values are propagated using the xconfmanager utility.
|
If the -Dinteractive=false command line argument is set, you are not prompted to confirm the recommended values.
configureWindchill
Calculates new values for the following properties and writes them to <Windchill>/utilities/wca/conf/windchill/windchillconfigurator.xconf file:
com.ptc.windchill.wca.buildDate
wt.admin.cache.maxDomains
wt.cache.size.AclCache
wt.cache.size.EnumerationDefinitionCache
wt.cache.size.IBADefViewManager$IBADefViewCache
wt.cache.size.IndexListCache
wt.cache.size.PagingSessionCache
wt.cache.size.PreferenceCache
wt.cache.size.RoleAccessCache
wt.cache.size.SessionCache
wt.cache.size.StandardFvService$ActiveFolderCache
wt.cache.size.StandardUfidSrvService$RemoteObjectIdCache
wt.cache.size.StructEnumAttTemplateCache
wt.cache.size.TypeDefinitionCache2
wt.cache.size.WTPrincipalCache
wt.manager.cmd.common.jmx.args
wt.manager.cmd.MethodServer
wt.manager.cmd.MethodServer.java.extra.args
wt.manager.cmd.ServerManager
wt.manager.cmd.ServerManager.java.extra.args
wt.manager.cmd.ServerManager.jmx.args
wt.manager.log.tee
wt.manager.maxHeap
wt.manager.minHeap
wt.manager.monitor.start.MethodServer
wt.method.log.tee
wt.method.maxHeap
wt.method.minHeap
wt.pom.dbConnectionsHardLimit
wt.pom.inClauseBindOptimizationCardinality
wt.pom.inClauseUseBindOptimization
wt.pom.maxDbConnections
wt.pom.minDbConnections
wt.pom.paging.snapshotQueryLimit
wt.pom.queryLimit
wt.pom.refreshCache.size
wt.pom.rowPrefetchCount
wt.pom.statementCacheSize
wt.queue.executeQueues
wt.services/rsc/default/ObjectReferenceCacheTable/ContainerCache.Size/null/0
wt.services/rsc/default/ObjectReferenceCacheTable/ContainerTeamCache.Size/null/0
Reads the existing contents of the JMX-Administrators list that is stored in the server manager MBean configuration file (serverManagerMBeanConfig.xml), and, when in interactive mode, allows updates to the list.
configureTomcat
Determines the value to set for the following property that is stored in the <Windchill>/tomcat/config.properties file and generates an intermediate file containing recommended updates in <Windchill>/utilities/wca/conf/tomcat/config.properties:
mode
The current value of the mode property is saved in <Windchill>/utilities/wca/conf/tomcat/configproperties.backup.
|
|
Tomcat is now known as the Embedded Servlet Engine (based on Apache Tomcat).
|
configure
Calls the following targets:
configureWindchill
configureTomcat
Using the configure target has the same results as running the Windchill Configuration Assistant two times, each time with one of the listed targets.
Targets for Propagating Values from Intermediate Files
The list that follows describes the targets that can be selected to propagate property values from intermediate files. The Windchill Configuration Assistant uses the xconfmanager utility to propagate Windchill properties.
|
|
To execute these targets, the ConfigurationRef element must be in your site.xconf file.
|
Before running the propagate targets, the assistant checks to ensure that the associated intermediate files exist. If a required intermediate file does not exist, the assistant returns an error stating that fact before attempting to propagate related property values. To correct the problem, you can rerun the corresponding target that produces the intermediate file.
Embedded Servlet Engine (formerly know as Tomcat) properties are not managed by the xconfmanager utility. Following the initial installation, the Embedded Servlet Engine installation directory contains a properties file named config.properties and an ant build script called config.xml. Embedded Servlet Engine configuration files are regenerated from a template file using values from the associated config.properties. The following file (which contains the value for the mode property) is regenerated when the config.xml script is run, and any manual edits that had been made are lost:
<Windchill>/tomcat/conf/web.xml
|
|
These targets propagate changes regardless of the value of propagate argument specified on the ant command.
|
propagateWindchill
Calls xconfmanager -p -F to propagate values from <Windchill>/utilities/wca/conf/windchill/windchillconfigurator.xconf to windchill properties files.
Copies the method server MBean configuration properties stored in the Windchill Configuration Assistant intermediate copy of the method server MBean configuration file to the method server MBean configuration file (<Windchill>/codebase/WEB-INF/methodServerMBeanConfig.xml).
|
|
After running the configureWindchill target and creating the intermediate configuration file, any additional method server changes made by executing the method server Loader MBean save operation are lost when the propagateWindchill target is run. For additional information about persisting MBean changes, see Using the Loader MBean to Persist Configuration Changes.
|
Applies the contents of the JMX-Administrators list that is stored in the intermediate copy of the method server MBean configuration file to all JMX-Administrators lists using the setEmailList ant target. For details on email lists and the ant script used by the Windchill Configuration Assistant, see Populating the JMX-Administrators List.
|
|
As a result of this action, all JMX-Administrators lists contain the same list of email addresses. To modify individual lists after completing the propagation, navigate to a specific JMX-Administrators MBean from a JMX client and, after changing the list, persist your changes using the Loader MBean.
|
When you specify the configureWindchill and configure targets, you can call the xconfmanager to propagate changes if you include the -Dpropagate=true argument on the ant command. Using the -Dpropagate=true argument can be done instead of using the propagateWindchill target.
propagateTomcat
Propagates property values found in the intermediate property file named <Windchilll>/utilities/wca/conf/tomcat/config.properties to the target Embedded Servlet Engine config.properties file and executes the configureJspEngine ant target in <Windchill>/tomcat/config.xml.
propagate
Calls the following targets:
propagateWindchill
propagateTomcat
Using the propagate target has the same results as running the Windchill Configuration Assistant two times, each time with one of the listed targets.
Targets for Rolling Back Configuration Changes Made Through the Assistant
The following table describes the targets that you can use to roll back the configuration changes that were propagated by the assistant.
|
|
Each time a target that calculates recommended values is run, the assistant generates a separate backup file. The assistant uses the latest backup files that were created for the restoration. Before running a target to roll back configuration changes, ensure that the latest backup files have the values you want to use.
|
|
Target
|
Description
|
|---|---|
|
restoreWindchill
|
Rolls back any changes that were made when the configureWindchill target was last run. It replaces values in <Windchill>/utilities/wca/conf/windchill/windchillconfigurator.xconf with backup values.
|
|
restoreTomcat
|
Rolls back any changes that were made when the configureTomcat target was run using the property values stored in the backup file.
|
|
restore
|
Calls the following targets:
restoreWindchill
restoreTomcat
|
|
|
Rolling back changes does not remove the ConfigurationRef element from the site.xconf file; if you want to remove the element, execute the uninstallConfigRef target.
|
Targets for the site.xconf ConfigurationRef Element
The assistant uses the ConfigurationRef element in the site.xconf file to establish the link between site-managed property values maintained in the site.xconf file and those values set as a result running the configure and configureWindchill targets.
The xlink:href value set in the ConfigurationRef element is the partial file path to the windchillconfigurator.xconf file. For example:
<ConfigurationRef xlink:href="utilities/wca/conf/windchill/windchillconfigurator.xconf"/>
If the ConfigurationRef element is not already present, it is automatically added to the site.xconf file when you include -Dpropagate=true on an ant command that executes either the configure or configureWindchill target.
If you want to use the propagate or propagateWindchill target to propagate the values stored in the windchillconfigurator.xconf file, the ConfigurationRef element must be in the site.xconf file before the target is executed.
The following table describes the targets that you can use to add and remove the ConfigurationRef element:
|
Target
|
Description
|
|---|---|
|
installConfigRef
|
Adds the ConfigurationRef element to the site.xconf file and creates an empty windchillconfigurator.xconf file in the <Windchill>/utilities/wca/conf/windchill directory.
If the ConfigurationRef element has already been added to site.xconf and the windchillconfigurator.xconf file exists, the target completes successfully, but no changes are made.
If the ConfigurationRef element has already been added to site.xconf but the windchillconfigurator.xconf file does not exist, an empty windchillconfigurator.xconf file is created.
|
|
uninstallConfigRef
|
Removes the ConfigurationRef element from the site.xconf file.
If the element is not in the site.xconf file, no error is returned.
|
Running Windchill Configuration Assistant in Unattended Mode
The Windchill Configuration Assistant can be run with or without user interaction. By default the assistant runs in interactive mode. In interactive mode, the user is prompted to accept or override property values calculated by the assistant as it runs each internal target.
To run the assistant in unattended mode, include -Dinteractive=false on the ant command:
ant -f WindchillConfigAssistant.xml target
-Dinteractive=false
-Dinteractive=false
In unattended mode, the assistant uses the calculated property values as though they were accepted by the user.
The targets for which the -Dinteractive=false argument is valid are as follows:
configure
configureWindchill
configureTomcat
If you specify other targets on the ant command, the assistant does not check the value of the interactive property when it runs. Therefore, the -Dinteractive=false argument is not used.
Running Windchill Configuration Assistant in Propagation Mode
When the Windchill Configuration Assistant runs a target that calculates recommended configuration values, it stores updated property name/value pairs in the file named:
<Windchill>/utilities/wca/conf/windchill/windchillconfigurator.xconf
The properties in this XCONF file can be propagated by the xconfmanager utility through to the various property files that it manages if the ConfigurationRef element has been added to the site.xconf file as described in the section “Targets for the site.xconf ConfigurationRef Element”.
The Windchill Configuration Assistant has the option to call xconfmanager utility to propagate all calculated property values to the appropriate properties files. By default, the Windchill Configuration Assistant does not propagate values; therefore, unless you explicitly set the value of the propagate argument to true on the ant command line when you are executing valid targets, the calculated property values are not propagated.
To run the assistant in propagation mode, include -Dpropagate=true on the ant command:
ant -f WindchillConfigAssistant.xml target
-Dpropagate=true
-Dpropagate=true
The targets for which the -Dpropagate=true argument is valid are as follows:
configure
configureWindchill
configureTomcat
If you specify other targets on the ant command, the assistant does not check the value of the propagate property when it runs. Therefore, the -Dpropagate=true argument is not used.
|
|
You can include both the -Dinteractive=false and -Dpropagate=true arguments if you want to run in both unattended and propagation modes at the same time.
|
|
|
If the Windchill Configuration Assistant is executed in propagation mode, it automatically adds the ConfigurationRef element to the site.xconf file (if not already present). The addition happens regardless of whether the installConfigRef target has been run. See the section “Targets for the site.xconf ConfigurationRef Element”.
|
Running the Assistant in Interactive Mode
When you are working in interactive mode, each recommended value is displayed in an [input] line on the command line. For example:
[input] Number of MethodServers to configure (current=1): [2]
If there is a current value defined, it is included on the line in the parenthetical phrase (current=x) where x is the current value. In the example, the current value is 1.
The recommended value is the value supplied at the end of the line inside the brackets []. In the example, the recommended value is 2.
Some inputs require specific values. When this is the case, the acceptable values are presented in parentheses at the end of the input line and the recommended value is inside brackets []. For example, the following input line shows the free and total values as the values you can enter and the recommended value is free:
[input] Allocate Windchill Memory region from total (16378 MB)
or free (10986 MB) physical memory ([free], total)
or free (10986 MB) physical memory ([free], total)
To override the recommended value, enter a new value at the prompt and press return. To accept the recommended value, just press return.
Setting Property Values on the Command Line
Include the -D<Property>=<Value> argument on the command line to override a select group of property values.
The assistant defines the following properties so that you can override calculated values for the CPU count, physical memory (in mega bytes), free memory (in mega bytes), and vendor that are calculated when running the configureWindchill target:
CPUCount
physMem
freeMem
vmVendor
For a specified property value to be used, the named property must be one that is calculated through the specified target. For example, executing the following command on a system with 4 CPUs and 8 GB of RAM overrides the calculated values for CPU, physical memory, free memory, and vendor. The command specifies 16 CPUs, 36 GB of RAM, 32 GB of free memory, and IBM Corporation as the vendor:
ant -f WindchillConfigAssistant.xml configureWindchill
-DCPUCount=16 -DphysMem=36000
-DfreeMem=32000 -DvmVendor="IBM Corporation"
-DCPUCount=16 -DphysMem=36000
-DfreeMem=32000 -DvmVendor="IBM Corporation"
Setting the CPUCount, physMem, and freeMem property values on a command that is run on a desktop class system allows the assistant to calculate other values that can then be used on a server class target system.
For a list of additional properties affected by each target, see the section “Targets for WindchillConfigAssistant.xml”.