xmlquery
xmlquery is a script in CIMEROOT/CIME/Tools.
$ ./xmlquery --help
usage: xmlquery [-h] [-d] [-v] [-s] [--caseroot CASEROOT] [--listall]
[--file FILE] [--subgroup SUBGROUP] [-p] [--no-resolve] [-N]
[--full | --fileonly | --value | --raw | --description | --get-group | --type | --valid-values]
[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.
options:
-h, --help show this help message and exit
--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.
-N, --non-local Use when you've requested a machine that you aren't on. Will reduce errors for missing directories etc.
--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.
Logging options:
-d, --debug Print debug information (very verbose) to file /home/runner/work/cime/cime/CIME/Tools/xmlquery.log
-v, --verbose Add additional context (time and file) to log messages
-s, --silent Print only warnings and error messages