Last modified: 28 January 2016
Tool Name: `h5watch`
Syntax:
  `h5watch [OPTIONS] OBJECT`
Purpose:
  Outputs new records appended to a dataset as the dataset grows.
Motivation:
  `h5watch` can be used to watch data that is added to a dataset. The functionality is similar to the Unix user command `tail` with the follow option, which outputs appended data as the file grows.
Current Limitations:
  The current limitations are the following:
  - `h5watch` can only be used on chunked datasets with unlimited dimension(s) or a fixed dimension with a maximum dimension setting.
  - While monitoring a dataset, users need to ensure that data that is being written to the dataset is flushed to the file.
Options and Parameters:
  Options:
  The following optional command-line options can be used with `h5watch:`

  Long Format | Comments
  `--help` | Print a usage message and exit.
  `--version` | Print the version of HDF5 and exit.
  `--label` | Label members of a compound datatyped dataset.
  `--simple` | Use a machine-readable output format.
  `--dim` | Monitor changes in dimension size of the dataset only.
  `--width=N` | Set the number of columns to N for output. A value of 0 sets the number of columns to the maximum (65535). The default width is 80 columns.
  `--polling=N` | Set the polling interval to N (in seconds) when the dataset will be checked for appended data. The default polling interval is 1.
  `--fields=list_of_fields` | Display data for the fields specified in `list_of_fields` for a compound datatype. `list_of_field` can be specified as follows: A comma-separated list of field names in a compound data type. A single field name in a compound data type. This option can be used multiple times to select multiple fields in a compound data type. Note that “,” is the separator for field names while “.” is the separator for a nested field. The backslash is the escape character; use it to escape character(s) in field names that conflict with the separators used by the tool.

  Object:
  `OBJECT` is the dataset to be monitored and is specified with the following format:

  `filename/path_to_dataset/dsetname`
  Each element in this specification of `OBJECT` is defined as follows:
  `filename` | The name of the HDF5 file. May be preceded by a path separated by slashes to the specified HDF5 file.
  `path_to_dataset` | The path within the HDF5 file separated by slashes to the specified dataset
  `dsetname` | The name of the dataset to be monitored.

Exit Status:

  0 | Succeeded.
  > 0 | An error occurred.

Example Usage:

  The default use is to include the tool name and the name of the dataset that will be watched. The output will describe any change and will list the changes.

  Suppose there is a dataset called dsetA in an HDF5 file called example.h5, and this dataset is a one-dimensional dataset with three records. After `h5watch` is run with a command line of `h5watch example.h5/dsetA`, the dimension size in the file is changed from three to five, and data is written to the dataset. The output from `h5watch` would be the following:

          dims[0]: 3->5

          Data:
          (3): record
          (4): record

  For more examples, see the h5watch Examples document.

See Also:

- `H5LDget_dset_type_size`
- `H5LDget_dset_dims`
- `H5LDget_dset_elmts`

History:

  Release | Change
  1.10.0 | Tool introduced in this release.