xmlchangeΒΆ
xmlchange is a script in CIMEROOT/scripts/Tools.
$ ./xmlchange --help
usage: xmlchange [-h] [-d] [-v] [-s] [--caseroot CASEROOT] [--append]
[--subgroup SUBGROUP] [--id ID] [--val VAL] [--file FILE]
[--delimiter DELIMITER] [--dryrun] [--noecho] [-f]
[-loglevel LOGLEVEL]
[listofsettings]
Allows changing variables in env_*xml files via a command-line interface.
This provides two main benefits over editing the xml files by hand:
- Settings are checked immediately for validity
- Settings are echoed to the CaseStatus file, providing a "paper trail" of
changes made by the user.
Examples:
To set a single variable:
./xmlchange REST_N=4
To set multiple variables at once:
./xmlchange REST_OPTION=ndays,REST_N=4
Alternative syntax (no longer recommended, but supported for backwards
compatibility; only works for a single variable at a time):
./xmlchange --id REST_N --val 4
Several xml variables that have settings for each component have somewhat special treatment.
The variables that this currently applies to are:
NTASKS, NTHRDS, ROOTPE, PIO_TYPENAME, PIO_STRIDE, PIO_NUMTASKS
For example, to set the number of tasks for all components to 16, use:
./xmlchange NTASKS=16
To set just the number of tasks for the atm component, use:
./xmlchange NTASKS_ATM=16
The CIME case xml variables are grouped together in xml elements <group></group>.
This is done to associate together xml variables with common features.
Most variables are only associated with one group. However, in env_batch.xml,
there are also xml variables that are associated with each potential batch job.
For these variables, the '--subgroup' option may be used to specify a particular
group for which the variable's value will be adjusted.
As an example, in env_batch.xml, the xml variables JOB_QUEUE and JOB_WALLCLOCK_TIME
appear in each of the batch job groups (defined in config_batch.xml):
<group id="case.run">
<group id="case.st_archive">
<group id="case.test">
To set the variable JOB_WALLCLOCK_TIME only for case.run:
./xmlchange JOB_WALLCLOCK_TIME=0:30 --subgroup case.run
To set the variable JOB_WALLCLOCK_TIME for all jobs:
./xmlchange JOB_WALLCLOCK_TIME=0:30
positional arguments:
listofsettings Comma-separated list of settings in the form: var1=value,var2=value,...
optional arguments:
-h, --help show this help message and exit
-d, --debug Print debug information (very verbose) to file /glade/work/turuncu/APPS/ufs-mrweather-app/cime/scripts/Tools/xmlchange.log
-v, --verbose Add additional context (time and file) to log messages
-s, --silent Print only warnings and error messages
--caseroot CASEROOT Case directory to change.
Default is current directory.
--append, -append Append to the existing value rather than overwriting it.
--subgroup SUBGROUP, -subgroup SUBGROUP
Apply to this subgroup only.
--id ID, -id ID The variable to set.
(Used in the alternative --id var --val value form, rather than
the recommended var=value form.)
--val VAL, -val VAL The value to set.
(Used in the alternative --id var --val value form, rather than
the recommended var=value form.)
--file FILE, -file FILE
XML file to edit.
Generally not needed, but can be specified to ensure that only the
expected file is being changed. (If a variable is not found in this file,
an error will be generated.)
--delimiter DELIMITER, -delimiter DELIMITER
Delimiter string in listofvalues.
Default is ','.
--dryrun, -dryrun Parse settings and print key-value pairs, but don't actually change anything.
--noecho, -noecho Do not update CaseStatus with this change.
This option is mainly meant to be used by cime scripts: the 'paper trail' in
CaseStatus is meant to show changes made by the user, so we generally don't
want this to be contaminated by changes made automatically by cime scripts.
-f, --force Ignore typing checks and store value.
-loglevel LOGLEVEL Ignored, only for backwards compatibility.