...
MARS command line options | |
Option | Meaning |
-d | switches debug information on (same as MARS_DEBUG=1) |
-h | prints help information |
-p | to use the previous MARS binary. If you suspect a new version of MARS may yield different results (including errors, crashing, etc...) this is the first thing to try. If the previous version of MARS works, then contact the CallDesk to report the problem you've found. |
In addition, the behaviour of MARS can be changed via various environment variables:
...
MARS environment variables | |||
Environment variable | Usage | ||
MARS_COMPUTE_FLAG | if set to 0, the model identification number is preserved. When using compute, GRIB headers of resulting fields are changed to reflect fields have been created by MARS. In particular, model identification number is set to 255. With this env. variable, the model identification of the first field is copied onto the result. | ||
MARS_DEBUG | if set to a value different from 0, additional output will be generated | ||
MARS_MULTITARGET_STRICT_FORMAT | if set to 1, 'consistent' file naming will be applied for multi targets, see Data storage keywords | ||
GRIB_APIMIR_DEBUG | If set to 1, it will enable debug level logging messages to be displayed by the library. | JDCNDBG | if MIR_DEBUG and MARS_DEBUG are set to 1, debug information for interpolation with MIR will be generated (values 2, 3 ... give progressively more detailed diagnostics) |
Request syntax
A MARS request is the way to specify an action on a set of fields or observations. The directives specified in a MARS request have the following syntax:
...
- Leading spaces and tab characters are ignored.
- verbs and directives keyword=value have to be terminated with a comma, except the last one, which MARS considers as the end of a request.
- Directives may be in upper or lower case or a mixture of both; MARS converts everything except file names to upper case.
- Characters * ! and # can be used to comment until end-of-line.
- Values may be predefined names, numeric values or user-supplied character strings such as file names.
- Abbreviations may be used for verbs, keywords and values, provided enough letters are given to uniquely identify what is meant.
- MARS has acronyms for the names of different parameters which can be specified by users.
- Keywords may be assigned a single value, a list of values or a range of values. A list is indicated by the separator / ; a range is indicated by using the keywords to as well as / and by. Examples of different formats for values are given in the table below.
Examples of MARS keyword assignments Format Example single value param = temperature/SSRD list of values step = 12/24/48 range of values date = 19990104/to/19990110/by/2
...
retrieve
action class=od
stream = oper,
identification of archive expver = 1,
date = -1,
date and time related type = analysis,
levtype = model levels,
levelist = 1/to/91,
param = temperature,
grid = 2.5/2.5,
post-processing area = europeEurope,
use = infrequent,
execution control target = analysis.12
storage
Retrieve requests have to specify, at least, directives to identify the data and directives for storage of the retrieved data. The ones to identify fields can be found in the MARS Catalogue. Data manipulation (post-processing) directives and execution control directives are optional, depending on your needs.
...
read can be used to filter or manipulate data already retrieved into a file.
write is mainly used to save data from fieldsets, a temporary storage, into files, see Fieldsets.
Fieldsets
A fieldset is a temporary storage for fields, either retrieved from MARS or read from a UNIX file. Fieldsets can be seen as variables in a MARS request, and they can be referenced in subsequent MARS requests in the same execution. This is an example how to retrieve data into a fieldset named analysis:
retrieve,
class = od,
type = analysis,
stream = oper,
expver = 1,
date = -1,
time = 12,
levtype = pressure levels,
levelist = 1000/850/500,
param = temperature,
fieldset = analysis
|
At the end of the execution, all fieldsets are released. Therefore, data in unsaved fieldsets will be lost. Fieldsets can be saved as UNIX files with write requests, like in this example:
write,
fieldset = analysis,
target = "data"
|
Note that fieldsets are in fact using temporary disk storage on the host where MARS is executed, usually in $TMPDIR directory. When dealing with big fieldsets, you are advised to make such variable point to a suitable directory were temporary data can be stored (e.g. $SCRATCH on ecgate).
One can extract fields (sub fieldsets) from a fieldset using square brackets. If X is a fieldset, X[2] is the second field, X[1,10] comprises the first 10 fields, and X[2,8,2] comprises every second field of x starting from 2 up to 8.
Multiple requests in one call to MARS
Note |
---|
This feature is not available when When accessing MARS via the Web API client, only one target file per MARS call is permitted. |
MARS can accept more than one request in the same invocationcall. This allows you e.g. to do further computations than the ones provided by the standard post-processing directives before writing the data into a target file and it is how the compute verb can be used. The following concepts have to be taken into account:
...