xmlqueryΒΆ

xmlquery is a script in CIMEROOT/scripts/Tools.

$ ./xmlquery --help
usage: xmlquery [-h] [-d] [-v] [-s] [--caseroot CASEROOT] [--listall]
                [--file FILE] [--subgroup SUBGROUP] [-p] [--no-resolve]
                [--full | --fileonly | --value | --raw | --description | --get-group | --type | --valid-values]
                [variables [variables ...]]

Allows querying variables from env_*xml files and listing all available variables.

There are two usage modes:

1) Querying variables:

   - You can query a variable, or a list of variables via
      ./xmlquery var1

     or, for multiple variables (either comma or space separated)
      ./xmlquery var1,var2,var3 ....
      ./xmlquery var1 var2 var3 ....
     where var1, var2 and var3 are variables that appear in a CIME case xml file

     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
     As examples:
     - to show the number of tasks for each component, issue
        ./xmlquery NTASKS
     - to show the number of tasks just for the atm component, issue
        ./xmlquery NTASKS_ATM

     - 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 query the variable's
       value for a particular group.

       As an example, in env_batch.xml, the xml variable JOB_QUEUE appears 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 query the variable JOB_QUEUE only for one group in case.run, you need
       to specify a sub-group argument to xmlquery.
          ./xmlquery JOB_QUEUE --subgroup case.run
              JOB_QUEUE: regular
          ./xmlquery JOB_QUEUE
            Results in group case.run
                 JOB_QUEUE: regular
            Results in group case.st_archive
                 JOB_QUEUE: caldera
            Results in group case.test
                JOB_QUEUE: regular

   - You can tailor the query by adding ONE of the following possible qualifier arguments:
       [--full --fileonly --value --raw --description --get-group --type --valid-values ]
       as examples:
          ./xmlquery var1,var2 --full
          ./xmlquery var1,var2 --fileonly

   - You can query variables via a partial-match, using --partial-match or -p
       as examples:
          ./xmlquery STOP --partial-match
              Results in group run_begin_stop_restart
                  STOP_DATE: -999
                  STOP_N: 5
                  STOP_OPTION: ndays
          ./xmlquery STOP_N
                  STOP_N: 5

    - By default variable values are resolved prior to output. If you want to see the unresolved
      value(s), use the --no-resolve qualifier
      as examples:
         ./xmlquery RUNDIR
             RUNDIR: /glade/scratch/mvertens/atest/run
         ./xmlquery RUNDIR --no-resolve
             RUNDIR: $CIME_OUTPUT_ROOT/$CASE/run

2) Listing all groups and variables in those groups

      ./xmlquery --listall

     - You can list a subset of variables by adding one of the following qualifier arguments:
       [--subgroup GROUP --file FILE]

       As examples:

       If you want to see the all of the variables in group 'case.run' issue
          ./xmlquery --listall --subgroup case.run

       If you want to see all of the variables in 'env_run.xml' issue
          ./xmlquery --listall --file env_run.xml

       If you want to see all of the variables in LockedFiles/env_build.xml issue
          ./xmlquery --listall --file LockedFiles/env_build.xml

     - You can tailor the query by adding ONE of the following possible qualifier arguments:
       [--full --fileonly --raw --description --get-group --type --valid-values]

     - The env_mach_specific.xml and env_archive.xml files are not supported by this tool.

positional arguments:
  variables             Variable name(s) to query from env_*.xml file(s)
                        ( 'variable_name' from <entry_id id='variable_name'>value</entry_id> ).
                        Multiple variables can be given, separated by commas or spaces.

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           Print debug information (very verbose) to file /Users/sacks/cime/scripts/Tools/xmlquery.log
  -v, --verbose         Add additional context (time and file) to log messages
  -s, --silent          Print only warnings and error messages
  --caseroot CASEROOT, -caseroot CASEROOT
                        Case directory to reference.
                        Default is current directory.
  --listall, -listall   List all variables and their values.
  --file FILE, -file FILE
                        The file you want to query. If not given, queries all files.
                        Typically used with the --listall option.
  --subgroup SUBGROUP, -subgroup SUBGROUP
                        Apply to this subgroup only.
  -p, --partial-match   Allow partial matches of variable names, treats args as regex.
  --no-resolve, -no-resolve
                        Do not resolve variable values.
  --full                Print a full listing for each variable, including value, type,
                        valid values, description and file.
  --fileonly, -fileonly
                        Only print the filename that each variable is defined in.
  --value, -value       Only print one value without newline character.
                        If more than one has been found print first value in list.
  --raw                 Print the complete raw record associated with each variable.
  --description         Print the description associated with each variable.
  --get-group           Print the group associated with each variable.
  --type                Print the data type associated with each variable.
  --valid-values        Print the valid values associated with each variable, if defined.