Table of Contents

MARS command

The mars command can accept a request file as a parameter or read the MARS request from standard input.

The mars command issued on the command line will output a message welcoming you to the system. At this point, one can type a mars request, then send an end-of-file to MARS by typing <CTRL>-d. As this method is error prone it is not recommend except for test purposes.

The recommended way to use MARS is by passing a request file, which can be created as a 'here document', to the mars command, e.g. 

cat > my_request <<EOF
retrieve,
   type  =an,
   date  = -1, 
   target="my_an"
EOF

mars my_request

Directives can also be passed into mars from the input stream:

mars <<EOF
retrieve,
   type  =an,
   date  = -1, 
   target="my_an"
EOF

All data retrievals should be submitted as batch jobs.

MARS can be called with the command line options listed in table 2. Most of these options are particularly useful when problems arise.

In addition, the behaviour of MARS can be changed via various environment variables: 

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:

...

write is mainly used to save data from fieldsets, a temporary storage, into files, see section 5.2.

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:

...

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

MARS can accept more than one request in the same invocation. This allows users 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:

Keyword inheritance

When two or more retrieve requests are used in a single call to MARS, keywords not explicitly set in the second request are inherited from the first (previous). The following example retrieves 12 UTC model level and 1000 hPa pressure level temperature for yesterday's analysis:

...

There can be cases in which unwanted keywords are inherited. They can be removed from subsequent requests by assigning the value off.

Append to target file

It is possible to store data from different requests into the same target file. Note that MARS will append the result of each retrieve request at the end of the target file. The following example retrieves first some Analysis data from yesterday. Then, a second retrieval will extract the same data for 40 days ago run and append it at the end of the target file.

retrieve,
   class  = od,
   type   = analysis,
   stream = oper,
   expver = 1,
   date   = -1,
   time   = 12,
   levtype= pressure levels,
   levelis= 1000/850/500,
   param  = temperature,
   target = "analysis.grb"
retrieve,
   date   = -40,
   target = "analysis.grb"     

Manipulate already retrieved data

Read requests can be used to filter or manipulate data from already retrieved files. It reads the data from a Unix file specified by the keyword source. This data can either be stored in a fieldset for further manipulation or written to a Unix file specified with the keyword target. Consider for example that file myfile contains certain meteorological parameters at all pressure levels. One can extract level 1000 hPa only and interpolate those fields to a 2.5x2.5 lat/lon grid, using the following MARS request:

...