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 /Users/sacks/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.