Using the xconfmanager Utility
The xconfmanager is a command line utility that you can run to add, remove, or modify properties in Windchill property files that are used for your defining your system.
Windchill uses some property files to manage internal system activities that you should never modify, including the following:
• associationRegistry.properties
• descendentRegistry.properties
• modelRegistry.properties
• moduleRegistry.properties
• moduleDir.properties
• debug.properties
The xconfmanager utility saves your changes in the site.xconf file and provides an option to generate updated property files using the updates in the site.xconf file. The site.xconf file contains the changes made to Windchill property files starting with the installation and continuing with each use of the xconfmanager utility. The site.xconf file is located in the directory where Windchill is installed.
Anyone with write access to the XCONF and property files under the Windchill installation directory can successfully run the xconfmanager utility.
The following sections describe how to enter the xconfmanager command and how to set property values and list property information using the command. The last section describes the other xconfmanager options that may be useful when running your Windchill solution.
The xconfmanager utility is located in the bin directory where your Windchill solution is installed. For example, if Windchill solution is installed in the C:\ptc\Windchill directory, then the utility is in the C:\ptc\Windchill\bin directory.
Before executing the xconfmanager command, set up your environment by using the windchill shell. To use the shell, either execute the shortcut (on a Windows system) or enter the following on the command line:
windchill shell
Then from the new window that opens, you can enter the xconfmanager command, as described in the next section.
xconfmanager Command Syntax
xconfmanager syntax
The syntax of xconfmanager command that administrators should use is as follows:
xconfmanager {-fFhuwvV} {-r <product_root>} {-d <property_names>} {-s
<property_pair>} {-t <property_file>} {--add <property_pair>} {--remove
<property_pair>} {--reset <property_names>} {--setfromfile <property_file>}
{--undefine <property_names>} {-i <declarative_xconf>} {--validateassite
<site_xconf>} {--validateasdecl <declarative_xconf>} {--validatefilesassite
<site_list_file>} {--validatefilesasdecl <declar_list_file>} {-p}
The brackets ({}) in the syntax indicate optional parameters and indicate parameters that you specify together. The syntax includes only the short version of each parameter name. Parameter names are case-sensitive; enter the names using the case shown in the syntax and the following table.
The following variables are used in the syntax of multiple parameters:
• <property_pair> is a command-line escaped name=value pair that is compatible with the specification for java.util.Properties. For an example, see section Setting Property Values and Propagating Your Changes.
• <property_names> is a comma-separated list of property names.
• <property_file> is the relative or full path name of the property file.
• <declarative_xconf> is either a full URL or relative file path to the declarative XCONF file.
In the following table, all parameter names are listed in alphabetical order with corresponding parameter descriptions:
|
Parameter Name
|
Description
|
|
--add
|
Add the specified value at the end of the set of ordered values already defined in the property. Use this parameter only when the property is declared as a multi-valued property.
To determine if property is multi-valued, you can display the current set of values using the -d parameter. The output from this parameter lists the multivalue separator when the property is multi-valued.
|
|
-d
or
--describe
|
Lists the values that are currently set and the corresponding XCONF file where each value is set for the specified properties.
This parameter executes after all parameter setting options and the -p option have executed.
|
|
-F
or
--force
|
Forces the propagator to ignore its cache of XCONF-to-properties file dependencies and ignore the timestamp comparison it usually does to determine which property files need to be updated. Using this option propagates all site-specific changes to property files.
Use this parameter in place of -p if you suspect that there are problems with file timestamps or you want to switch between the -w and -u options.
|
|
-f
or
--forcescan
|
Forces the propagator to ignore its cache of XCONF-to-properties file dependencies. This parameter is ignored if you specify -F.
Use this option in place of -p if you suspect that the cache is out of date.
|
|
-h
or
--help
|
Displays the help for the xconfmanager command.
|
|
-i
or
--install
|
Installs a declarative XCONF file that you have created. New declarative XCONF files are used when creating additional property files. When you are adding code in which new properties can be set, you can choose to create a separate property file where the properties are stored. For details on what to put in the declarative XCONF file, see the Windchill Customization Guide.
|
|
-p
or
--propagate
|
Propagates all changes that have been made to XCONF files into the property files that are being used. This option always executes after any options that set properties. This execution order ensures that the newly set properties are included in the propagation.
Updated property files are accessed when the Windchill solution is restarted.
|
|
-r
or
--productroot
|
The root directory from which all relative paths are based for XCONF references specified in the declarations.xconf file and target file paths specified in the -t parameter.
The default root directory is the bin directory where the Windchill solution is installed.
|
|
--remove
|
Removes the specified value that is in the set of ordered values defined in the property. Use this option only when the property is declared as a multi-valued property.
To determine if a property is multi-valued, you can display the current set of values using the -d parameter. The output from this parameter lists the multivalue separator when the property is multi-valued.
|
|
--reset
|
Resets the site specific value of a property or set of properties to the declared default values.
|
|
-s
or
--set
|
Sets the named property to a specific value in the site.xconf file.
To set multiple properties in the same target property file, use multiple occurrences of this parameter or use the following parameter:
--setfromfile
To set multiple properties that are in different target property files, enter multiple xconfmanager commands, one for each target file.
Use this parameter in conjunction with the -t parameter.
|
|
--setfromfile
|
Adds the name=value pairs that are in the specified file to the end of the site.xconf file, thus setting each property named to the specified value. There is no checking done to determine if the value set is the default.
<property_file> is the file that contains a set of name=value pairs (one pair per line) that indicate the properties and values you want set in one target property file. Each pair sets a value for one property.
With this parameter, you can set multiple properties in the same target property file using one xconfmanager command. To set properties that are in different target property files, enter multiple xconfmanager commands, one for each target file.
Use this parameter in conjunction with the -t parameter.
|
|
-t
or
--targetfile
|
Identifies the property file in which the property value specified in the -s parameter is set or the property values specified in the following parameter are set:
--setfromfile
Use this parameter in conjunction with either the -s or the following parameter:
--setfromfile
This parameter is optional when setting common properties where the default property file to update has been declared and is available to the xconfmanager utility. For example, properties stored in wt.properties and db.properties do not require this parameter.
For other properties, you may need to specify the file path of the property file in this parameter. For example, updating properties in the federation.properties file requires that you enter this parameter using the codebase/federation.properties file path.
|
|
-u|w
or
--unix|win
|
Indicates the platform for which the property files are to be generated. Normally, the current platform settings determine the format of the property files.
Include this parameter when you want to generate property files for a specific platform that is not the current platform.
For UNIX platforms, specify -u or the following:
--unix
For Windows platforms, specify -w or the following:
--win
|
|
--undefine
|
Resets the specified properties such that their values will be null (instead of an empty string) when read through a java.util.Properties instance.
|
|
-v
|
Turns on verbose console output, which shows full exception stack traces.
|
|
-V
|
Turns on debug verbose console output. This option shows full exception stack traces and additional information.
|
|
--validateasdecl
|
Validates a specific file as a declarative XCONF file.
Returns a non-zero result if file cannot be validated.
|
|
--validatefilesasdecl
|
Validates a list of files as declarative XCONF files. The list is contained in the specified file, where each line in the file is either a full URL or relative file path to a declarative XCONF file.
Returns a non-zero result if any of the files cannot be validated.
<declar_list_file> is either a full URL or relative file path to the file containing the list of declarative XCONF files you want to validate.
|
|
--validatefilesassite
|
Validates a list of files as site-specific XCONF files. The list is contained in the specified file, where each line in the file is either a full URL or relative file path to a site-specific XCONF file.
Returns a non-zero result if any of the files cannot be validated.
<site_list_file> is either a full URL or relative file path to the file containing the list of site-specific XCONF files you want to validate.
|
|
--validateassite
|
Validates a specific file as a site-specific XCONF file.
Returns a non-zero result if file cannot be validated.
<site_xconf> is either a full URL or relative file path to the site-specific XCONF file you want to validate.
|
|
|
The xconfmanager executes the following parameters in the order that they are specified in the command:
-s, --reset, --add, --remove, --undefine
This means that if the same property is set in multiple parameters, the last setting is used.
|
The xconfmanager always executes the -p parameter after executing the previously listed parameters for setting, resetting, adding, removing, and undefining values. This is done so that all parameter settings are included in the propagation.
Additionally, the xconfmanager always executes the -d parameter after executing the previously listed parameters. This is done so that the descriptions returned include all of the parameter settings made on the command.
Viewing xconfmanager Help
On the xconfmanager command, use -h or the following parameter:
--help
to list the xconfmanager command syntax and provide a description of each parameter.
Setting Property Values and Propagating Your Changes
The xconfmanager utility provides options that allow you to manage the properties in a Windchill property file as follows. You can:
• Set a property value to specific value by using the -s and -t parameters.
• Set a property value to the declared default value by using the following parameter:
--reset
• Set a property value to null (instead of an empty string) using the following parameter:
--undefine
• Add and remove property values from properties that are multi-valued using the following parameters:
--add
--remove
• Propagate the site changes stored in the site.xconf file to all affected property files using the -p parameter.
Since property values are cached, propagated values are not used until you restart Windchill and your servlet engine.
Setting Specific Property Values
On the xconfmanager command, use the -s parameter to set a specific property value and the -t parameter to set the target property file for the property setting. In a given xconfmanager command, you can specify multiple -s parameters. However, all properties specified must reside in the same target property file; there can only be one -t parameter.
The property values you set must conform with the specification for java.util.Properties. The following guidelines will help ensure that you set properties correctly:
• Use forward slashes (/) in file paths so that the platform designation is not an issue.
• To specify a property whose value contains characters that might be interpreted by your shell, escape them using the appropriate technique for the shell you are using.
For example, on a Windows system you can include spaces in a value by enclosing the argument with doubles quotes. For example, use the following:
-s wt.inf.container.SiteOrganization.name="ACME Corporation"
On a UNIX system, you can use doubles quotes or you can escape the space character with a backslash. For example, use the following:
-s wt.inf.container.SiteOrganization.name="ACME\ Corporation"
On UNIX, dollar signs are usually interpreted by shells as variable prefixes. To set a property value that has a dollar symbol in it, use single quotes around the argument so that it is not interpreted by the shell or use backslash to escape the dollar symbols. For example, use either of the following:
-s 'wt.homepage.jsp=$(wt.server.codebase)/wtcore/jsp/wt/portal/index.jsp'
or
-s wt.homepage.jsp=\$(wt.server.codebase)/wtcore/jsp/wt/portal/index.jsp
Other than escaping arguments so that the command line shell does not misinterpret them, the values should not need to be escaped any further to be compatible with XML or property file syntaxes. The xconfmanager escapes property names and values automatically if necessary.
The following xconfmanager command used on a Windows system sets the wt.properties property file wt.temp property to the WCtemp directory that is under the Windchill installation directory [as defined by $(wt.home)]:
xconfmanager -s wt.temp=$(wt.home)/WCtemp -t wt.properties -p
Assuming that the command was executed from the Windows C:\ptc\Windchill\bin directory, then the resulting output is:
Default product root=C:\ptc\Windchill\bin\..
java -jar "C:\ptc\Windchill\bin\..\codebase\WEB-INF\lib\install.jar"
-r "C:\ptc\Windchill\bin\.." -s wt.temp=$(wt.home)/WCtemp
-t wt.properties -p
Propagating xconf data to target files...
The xconfmanager creates a backup of the current site.xconf file, adds the property element for wt.temp to the site.xconf file (replacing any existing property setting that had been in the site.xconf file), and then propagates the change to wt.properties. Since property values are cached, the propagated values are not used until you restart Windchill and your servlet engine.
Restoring a Property Value to Its Default Value
Use the --reset parameter on the xconfmanager command to restore one or more properties to their default values. To specify multiple properties in the parameter, separate the properties using a comma.
The following xconfmanager command resets the wt.temp property:
xconfmanager --reset wt.temp -p
Assuming that the command was executed from the Windows C:\ptc\Windchill\bin directory, then the resulting output is:
Default product root=C:\ptc\Windchill\bin\..
java -jar
"C:\ptc\Windchill\bin\..\codebase\WEB-INF\lib\install.jar"
-r "C:\ptc\Windchill\bin\.." --reset wt.temp -p
Propagating xconf data to target files...
The xconfmanager creates a backup of the current site.xconf file, removes any existing property settings for the specified properties that had been in the site.xconf file, adds a ResetProperty element for each property that was specified (in this case, only wt.temp), and then propagates the change to property files that have the specified properties (in this case, only wt.properties).
Setting a Property Value to the Null Value
Use the following parameter on the xconfmanager command to set one or more properties to null values:
--undefine
To specify multiple properties in the parameter, separate the properties using a comma.
The following xconfmanager command sets the wt.services.service.1160 property to null (which disables the service):
xconfmanager --undefine wt.services.service.1160 -p
Assuming that the command was executed from the Windows C:\ptc\Windchill\bin directory, then the resulting output is:
Default product root=C:\ptc\Windchill\bin\..
java -jar
"C:\ptc\Windchill\bin\..\codebase\WEB-INF\lib\install.jar"
-r "C:\ptc\Windchill\bin\.." --undefine
wt.services.service.1160 -p
Propagating xconf data to target files...
The xconfmanager creates a backup of the current site.xconf file, removes any existing property settings for the specified properties that had been in the site.xconf file, adds an UndefineProperty element for each property that was specified (in this case, only wt.services.service.1160), and then propagates the change to property files that have the specified properties (in this case, only wt.properties).
Adding and Removing a Property Value to a Multi-valued Property
To add a new classpath entry (d:\MyLibaries\somelibrary.jar) to the Windchill end of the classpath specified in the wt.java.classpath property, execute the following command from the windchill shell:
xconfmanager --add wt.java.classpath=d:\MyLibaries\somelibrary.jar -p
The value d:\MyLibaries\somelibrary.jar is added to the end of the ordered set. You do not have to specify the delimiter $(path.sep) as this will be added to the property value automatically by the xconfmanager.
To remove the classpath entry added in the previous example from the wt.java.classpath property, execute the following command from the windchill shell:
xconfmanager --remove wt.java.classpath=d:\MyLibaries\somelibrary.jar -p
The value d:\MyLibaries\somelibrary.jar is removed.
|
|
The previous example commands do not include the target file (in the -t parameter). The target file is not needed when the property is known to be in only one existing property file.
|
Listing Property Information
Use the -d parameter on the xconfmanager command to list information about one or more properties. To specify multiple properties in the parameter, separate the properties using a comma. The resulting output includes the current value of each property and the location of the files where each property is set.
The following xconfmanager command lists the information for the wt.home property:
xconfmanager -d wt.home
Assuming that the command was executed from the Windows C:\ptc\Windchill\bin directory, then the resulting output is:
Default product root=C:\ptc\Windchill\bin\..
java -jar "C:\ptc\Windchill\bin\..\codebase\WEB-INF\lib\install.jar"
-r "C:\ptc\Windchill\bin\.." -d wt.home
WARNING: Propagation of xconfs to properties was not requested.
To ensure your properties are up to date, re-run with the -p option.
Property information for 'wt.home':
Values:
- C:\Windchill
Locations:
- file:/C:/Windchill/site.xconf, line 9
- file:/C:/Windchill/codebase/wt.properties.xconf, line 17
Validating XCONF Files
You can use the following options to validate XCONF files:
• To validate a site-specific XCONF file, use:
--validateassite
or to validate a list of site-specific XCONF files, use:
--validatefilesassite
• To validate a declarative XCONF file, use:
--validateasdecl
or to validate a list of declarative XCONF files, use:
--validatefilesasdecl
The following section provides examples.
Validating XCONF Files Examples
To validate a single file as a site-specific XCONF file, run the command:
xconfmanager --validateassite=<site_xconf>
If the file is valid, then the xconfmanager will issue no output and exit with a return code of zero.
To validate that several files are valid site XCONF files in one invocation, there are two options. You can use the
--validateassite
parameter multiple times. For example:
xconfmanager --validateassite=<site_xconf>
--validateassite=<site_xconf>
The other option is to create a text file, add a line for each path to a file to be validated, then run the command:
xconfmanager --validatefilesassite=<site_list_file>
If all the files are considered valid site XCONF files, xconfmanager issues no output and exits with a return code of zero.
You can validate declarative XCONF files in the same manner using the following parameters:
--validateasdecl
or
--validatefilesasdecl
Other xconfmanager Options
The xconfmanager utility provides additional options that can be useful when setting up a Windchill cluster, performing customizations, or analyzing system problems:
• To specify the root directory that is not the default root directory, use -r. The default root directory is the bin directory under the Windchill installation directory.
The xconfmanager utility uses the root directory when relative paths for XCONF references and target file paths are used.
• To force propagation of all property values listed in the site.xconf, use -F instead of using -p. The -F option forces the propagation regardless of the analysis that is done to determine which files are already up-to-date.
• To generate properties in a format different from the current platform setting, use one of the following:
◦ For the UNIX platform format, use -u.
◦ For the Windows platform format, use -w.
• To turn on additional console output, use either -v (verbose) or -V (debug verbose).
