About the xconfmanager Utility
The xconfmanager is a command-line utility that is used to add, remove, and modify the properties in the Windchill property files. You should use the xconfmanager to manipulate properties; you should not manually edit property files.
The xconfmanager utility saves your changes in the site.xconf file and provides an option to generate updated property files using those changes. The site.xconf file contains changes made to Windchill property files, starting with installation and continuing with each use of the xconfmanager utility. The xconfmanager utility is located in the <Windchill>/bin directory.
This topic describes only the information and instructions necessary to modify specific Windchill properties.
A full description of the xconfmanager utility and management of the Windchill property files is documented in Using the xconfmanager Utility.
Anyone with write access to the XCONF files and the property files under the Windchill installation directory can successfully run the xconfmanager utility. The xconfmanager is executed from the command line from within a windchill shell. See Windchill Shell for more information about the windchill shell.
The syntax of xconfmanager command with only commonly used parameters is as follows:
xconfmanager {-h} {-r <product_root>} {-s <property_pair>}
{-t <property_file>} {--add <property_pair>}
{--remove <property_pair>} {--reset <property_names>}
{--undefine <property_names>} {-d <property_names>} {-p}
{-t <property_file>} {--add <property_pair>}
{--remove <property_pair>} {--reset <property_names>}
{--undefine <property_names>} {-d <property_names>} {-p}
For the purposes of modifying Windchill properties, you will primarily use the -s, -t, and -p parameters as follows:
• Use the -s (--set) parameter to identify the relevant property and specify the new property value. For information about formatting the <property_pair> value, see section Formatting Property Value Guidelines.
• Use the -t (--targetfile) parameter to specify the directory location of the property file. If the file name or path contains spaces, you must enclose the <property_file> value in double quotes (" "). It is recommended to use a fully qualified file name to ensure an accurate reference to the file is made.
• Use the -p (--propagate) parameter to propagate the changes made to the XCONF files into the property files being modified in order to keep the XCONF and the property files in sync with one another.
• Use the -h (--help) parameter to view the help for xconfmanager. The help describes all xconfmanager parameters.
Additionally, you can add and remove property values from properties that are declared as a multi-valued property using the following parameters:
• Use the --add parameter to add the value specified at the end of the set of ordered values already defined in the property.
• Use the --remove parameter to remove the value specified from the set of ordered values already defined in the property.
 |
If you are unsure as to whether 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.
|
Some examples of using the xconfmanager utility are as follows:
• xconfmanager is run from the windchill shell. To open a windchill shell, execute the following command at a command prompt:
windchill shell
• To display xconfmanager help, execute the following command from the windchill shell:
xconfmanager -h
• To display the current settings for a property, execute the following command from the windchill shell:
xconfmanager -d <property_names>
<property_names> is a comma-separated list of property names. This means that you can display the current settings for multiple properties by executing one command.
• To change a property value, execute the following command from the windchill shell:
xconfmanager -s <property_name>=<property_value>
-t <property_file> -p
-t <property_file> -p
|
|
Use the fully qualified name of the property file to ensure an accurate reference. If you are sure that there is only one property file that is known to xconfmanager containing the property, you can omit the -t parameter. When setting a value for a new property not in a property file, you must include the -t parameter to name the property file to which the property is added.
|
• To add a new classpath entry to the Windchill 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 will be 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.
|
|
The previous example command did not include the target file in the -t parameter since the property is known to be in only wt.properties.
|
Formatting Property Value Guidelines
The following guidelines will help ensure that you set properties correctly on the command line when using xconfmanager:
• To specify a property whose value contains characters that might be interpreted by your shell (such as spaces and special characters), escape them using the appropriate technique for the shell you are using.
On a Windows system, you can include spaces in a value by enclosing the argument with doubles quotes or you can escape the space character with ^. For example, use either of the following:
-s "wt.inf.container.SiteOrganization.name=ACME Corporation"
-s wt.inf.container.SiteOrganization.name=ACME^ Corporation
-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 \. For example, use either of the following:
-s "wt.inf.container.SiteOrganization.name=ACME Corporation"
-s wt.inf.container.SiteOrganization.name=ACME\ Corporation
-s wt.inf.container.SiteOrganization.name=ACME\ Corporation
• When including file paths in property values, use the forward slash (/) as the separator character; do not use the Windows backward slash (\) character.
On UNIX, the backward slash (\) is not valid a file path separator. Using forward slashes (/) in file paths ensures that the property values are valid on all platforms.
• 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 the shell does not interpret it 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'
index.jsp'
or
-s wt.homepage.jsp=
\$(wt.server.codebase)/wtcore/jsp/wt/portal/index.jsp
\$(wt.server.codebase)/wtcore/jsp/wt/portal/index.jsp
Other than escaping arguments so that the command-line shell does not misinterpret them, you should not need to escape other values to be compatible with XML or property file syntaxes. The xconfmanager escapes property names and values automatically if necessary.