MARS

Specifies a file into which data is to be written after retrieval or manipulation.

Web API client

When using the Web API there can be only one target file per request. See Limit target size and Limit number of fields.

Multiple targets are not supported.

target="<pathname>"

Path names should always be enclosed in double quotes, e.g.:

target = "/scratch/ms/gid/analysis.grb"

The MARS client supports automatic generation of multiple target files using MARS keywords enclosed in square brackets [ ]. This is a very useful way of organising fields into target files according to the keywords describing the fields. Instead of making repeated calls to MARS that may access several times the same tape, one could, with one retrieve, get as much data from the same tape as possible and write it to different target files. The following example retrieves analysis fields on pressure levels for the four main synoptic hours, storing them in four different target files, one per synoptic time:

retrieve,
   type    = an,
   expver  = 1,
   levtype = pl,
   levelist= 1000/850/700/500/400/300,
   param   = 129,
   date    = 19990222,
   time    = 0000/0600/1200/1800,
   target  = "an.[time]"

By default the keyword values will use a generic format, e.g. in the example above the files will be named an.0, an.600, an.1200 and an.1800, i.e. without leading zeros. If the environment variable MARS_MULTITARGET_STRICT_FORMAT is set to 1 before calling mars, the keyword values will be used in the filename as shown by the ecCodes GRIB tool grib_ls -m, e.g. with MARS_MULTITARGET_STRICT_FORMAT set to 1 the values for  keywords time, expver and param will be formatted as 0600, 0001 and 129.128 rather than 600, 1 and 129.

Please note that the multiple target syntax is only supported for fields when retrieved to a target file, i.e. it wouldn't work with observations, fieldsets or with the verbs list, write or compute. Furthermore, the keywords specified in [ ] have to be those used by MARS, e.g. levelist and not level or any other abbreviation.

In a similar way multiple target files can be specified using ecCodes grib keys in curly braces, e.g. target="an.{shortName}".

Please note that this is a feature of the ecCodes package rather than generic MARS functionality.

Dissemination

Obsolete in the  Data Requirement Editor (DRE)

4 Comments

  1. Matt Garvert

    I am trying to use this multiple target feature to avoid looping over mars requests but it is not working. When I follow this example I get a single downloaded file called "an.[time]". I have MARS_MULTITARGET_STRICT_FORMAT set to 1. Are there any other env variables or settings that must be changed in order for this to work? Is a there a way to use the multiple target feature for requests made in python using ECMWFService via ecmwfapi? 

    1. Carsten Maass

      The multiple target feature is only available calling the mars client on ECMWF machines. (If that doesn't work as expected, users should contact our service desk.)
      To achieve a similar result when using the Web API the recommendation is, to get as much data from the same tape as possible, write to one target file and then use some tool to split the file into suitable subsets. The splitting could be done e.g. with the ecCodes command line tools grib_filter or grib_copy.

  2. Unknown User (chcs)

    I am also trying to use the multiple target feature but how can I set the MARS_MULTITARGET_STRICT_FORMAT to 1 ? 

    Thank you

    1. Carsten Maass

      E.g. in a ksh or bash script by adding the line

      MARS_MULTITARGET_STRICT_FORMAT=1

      before calling the mars command.