Filenames and DSS pathnames can be masked as input arguments to HEC-MetVue command line utilities. This allows for specification of multiple files/paths, without listing each individually, leveraging a useful name patterns in files/paths. This simplifies the specification of a large number of files/paths, and prevents the need to update command text for automated processes that occur at regular time intervals.

Masks can be performed with three approaches:

  • Date Masks
  • Wildcards with a set number of characters
  • Wildcards without a set number of characters

Date Masks

For date masking, there are a number of time specification patterns that may be used. The date masking relies on Java SimpleDateFormat, but key portions of the documentation for HEC-MetVue are described below:

PatternDescription
s:

Argument prepended onto a pattern specifying that the mask should be filled with the start date of the image time window.

e:

Argument prepended onto a pattern specifying that the mask should be filled with the end date of the image time window.

yyyy

The 4 digit year for the given date. YYYY should be avoided as it provides inconsistent results for dates in the first/last week of the year. YYYY specifies a "week year" concept described in the SimpleDateFormat documentation.

MMM

The 3 character abbreviation of a month for the given date. For example, a date in January would replace the mask with "Jan"

MM

The 2 digit numerical representation of the given month. For example, a date in January would replace the mask with "01"

dd

The 2 digit numerical representation of the given day of the month. For example, a January 1st  would replace the mask with "01"

HH

The 2 digit numerical representation of the given hour of the day (00-23). For example, a January 1st 00:00  would replace the mask with "00"

kk

The 2 digit numerical representation of the given hour of the day (01-24). For example, a January 1st 00:00  would replace the mask with "24"

mm

The 2 digit numerical representation of the given minute of the hour. For example, a January 1st 00:00  would replace the mask with "00"

ss

The 2 digit numerical representation of the given second of the minute. For example, a January 1st 00:00:00  would replace the mask with "00"

When building a mask, the following rules must be followed:

  • Each mask must be enclosed in % 
    • For example, %s:yyyyMMMdd_HHmm% would expand to 2022Jan01_0000 for an image that ranges from January 1st 2022 at 00:00 to January 1st 2022 at 01:00
  • If no s: or e: arguments are specified, the results will match the starting date of each image. (i.e. s: is the default if unspecified)
    • Therefore %s:yyyyMMMdd_HHmm% yields the same results as %yyyyMMMdd_HHmm%
  • Multiple date masks can be used in a single file/path mask
    • For example, the previous example can be changed to %yyyy%%MMM%%dd%_%HH%%mm% and return the same results.
  • Start date, end date and duration must be specified at the command line.
    • This provides the necessary information for each utility to build up a set of dates, ranging from the start date to the end date, at the specified time interval. Based on this list of dates, the command line utility will build up a set of file/path names, by replacing the mask with the set of dates.
    • Although this builds up a set of potential files/paths, this doesn't mean that the utility will read each of the potential files/paths. After building this list of files/paths, each file/path will be check to ensure it conforms to the specified date/duration filter. For example, a start date of 01Jan2022:0000, end date of 01Jan2022:0100, and duration of 1Hour, with a mask of %yyyyMMMdd_HHmm%.asc, whould yield 2 files: 2022Jan01_0000.asc and 2022Jan01_0100.asc. Each of these would subsequently checked in the time filter, and only the 2022Jan01_0000.asc file would be selected. Since 2022Jan01_0100.asc has a start date of 01Jan2022:0100, which is equal to the end date of the time filter, and therefore does not intersect with the specified time window.

File Masking Note

Note that on Windows machines, A single % will get stripped from the command line, and therefore %% should be used in the file masking.

Wildcards with a set number of characters

For wildcards with a set number of characters, the ? character should be used. In this case, a ? should be placed for each character intended to be masked.

For example, if three files exist: file-001.txt, file-010.txt, file-100.txt, then each file can be found with a mask file-???.txt.

Wildcards without a set number of characters

For wildcards without a set number of characters, the * character should be used. In this case, a single * should be placed in the mask to replace one or more characters.

For example, if three files exist: file-1.txt, file-10.txt, file-100.txt, then each file would be found with a mask file-*.txt.

DSS and Applicable Masking

For DSS, pathnames can be masked, but DSS filenames must be specified explicitly. Date masking is possible for the D and E parts. For INST-VAL data, an example mask is /SHG/MARFC/TEMP-AIR/%%e:ddMMMyyyy:kkmm%%//OBS/, but for non-INST-VAL data, the example mask is /SHG/MARFC/PRECIP/%%s:ddMMMyyyy:HHmm%%/%%e:ddMMMyyyy:kkmm%%/OBS/. Alternatively, wildcards can be used. An example is /SHG/MARFC/PRECIP/*/*//, where any dates within the specified range, and with the specified duration, will be selected. Wildcards can also be used to mask A, B, C and F parts.

Compound Masking Examples

Any combination of wildcards and date masks may be used to find the desired files. A few illustrative examples below show how XMRG files that follow the pattern "xmrgMMddyyyyHHz" can be selected:

"xmrg%s:MMddyyyyHH%z"
"xmrg%s:MMdd%??????z"
"xmrg%s:MMdd%*z"
"????%s:MMdd%*z"
"????%s:MMdd%*%s:HH%z"