How to Modify XML Files (*.xml)#

Now let’s learn how to edit and search for variables in an *.xml file

We will use xmlchange to modify xml variables and use xmlquery to search xml variables. Note that you can change XML files manually, but using the xmlchange script prevents XML errors and ensures there is a record of your changes in the CaseStatus file.

For the examples below, you can follow along by going to your CASEROOT directory b.day1.0 that you completed in the Basics section.

1. Editing with xmlchange#

When modifying an *.xml file, we highly recommend using the xmlchange tool. This is done using the syntax ./xmlchange VARIABLE=VALUE in your case directory.

The xml files can also be edited manually with your favorate text editor (vi, emacs, etc.), but users should take care not to introduce any formatting errors that could lead to incomplete environment variable settings. You can use your text editor to take a look at the xml files – you will find descriptions of each variable, which can be very helpful in understanding what they control.

Here is an example for using xmlchange. If you want to change the length of your run to one month, edit env_run.xml via the xmlchange tool by typing on the command line:

./xmlchange STOP_OPTION=nmonths,STOP_N=1
Tips! When using xmlchange to modify multiple environment variables, use comma (and no space!) in between variables.
You can always find help by typing `./xmlchange --help`
Click here for example output of `./xmlchange --help` 
./xmlchange --help

Output: 

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.
   
...

Evaluate your understanding

If you want to manually resubmit an initial case that previously had a CONTINUE_RUN value of FALSE, how do you change it to TRUE?

Click here for the solution

Use xmlchange to modify the variable value with the command:

    ./xmlchange CONTINUE_RUN=TRUE

2. Searching xml variables with xmlquery#

We recommend using the xmlquery tool in your case directory to query xml variables.

For example, to find out the run type of your job, search for xml variable RUN_TYPE:

./xmlquery RUN_TYPE
Tips!

You can always find help by typing ./xmlquery --help

This will return the default RUN_TYPE value:

RUN_TYPE: hybrid


Evaluate your understanding

Let’s check if the variables in the previous exercise are properly modified.

Query for the value of STOP_N, STOP_OPTION, and CONTINUE_RUN.

Click here for the solution

Use xmlquery to search the variables with the command: 

    ./xmlquery STOP_N,STOP_OPTION,CONTINUE_RUN

If you see: 
>STOP_N: 1 
>STOP_OPTION: nmonths 
>CONTINUE_RUN: TRUE

Great! You have successfully queried these variables.

3. Use the subgroup functionality of xmlchange#

Now let’s first try to find out the wallclock time of your job, search for xml variable JOB_WALLCLOCK_TIME:

./xmlquery JOB_WALLCLOCK_TIME
Tips!

If you are unsure about the full name of the xml variable, you can query variables with a partial match, using --partial-match or -p.

For example: ./xmlquery -p WALLCLOCK


You will find that the query of wallclock time returns multiple instances:

Results in group case.run
JOB_WALLCLOCK_TIME: 00:30:00

Results in group case.st_archive
JOB_WALLCLOCK_TIME: 00:30:00

The variable JOB-WALLCLOCK_TIME has two instances in two different subgroups: case.run and case.st_archive.

Then, how do we specify which instance we want to modify?

For variables that have multiple instances, we can use the “subgroups” functionality in xmlchange. For example, if we want to change the default JOB_WALLCLOCK_TIME from 30 minutes to 1 hour for the short term archiver subgroup, type in the following command:

./xmlchange --subgroup case.st_archive JOB_WALLCLOCK_TIME=01:00:00

Try it yourself! Type in the command above and use xmlquery to check if your modifications are correctly applied.