arget.pod

NAME

arget, argrep, arinfo - CLI tools to query Channel Archiver

SYNOPSIS

arinfo [common options]

argrep [common options] [-R] <regex patterns...>

argrep [common options] -W <wildcard patterns...>

argrep [common options] --exact <pv names...>

arget [common options] [get options] [-W,-R,--exact] <patterns...>

arget [common options] -E hdf5 [get options] [-W,-R,--exact] <hdf file[:path]> <patterns...>

arsnap [common options] [get options] [-W,-R,--exact] <patterns...>

DESCRIPTION

These utilities will attempt to contact a Channel Archiver Data Server or an Archiver Appliance. The server configuration is determined by a configuration file and the -C argument.

arinfo serves the purpose of listing which archive sections will by queries by default, or with a given set of -a options.

argrep serves to find which PVs in the given archive sections match the given regular expression.

arget retrieves data for a time range and can either write it to the screen, or an HDF5 file.

arsnap retrieves data for a single time and prints it to screen.

OPTIONS

Common Options

-h, --help

Show help message

--info, --search, --get, --snapshot

Select operation to perform. Normally this is implicit in the executable name. arinfo is a synonym for arget -I.

-C CONFIG, --conf=CONF

Specify a configuration file section name.

-a NAME, --archive=NAME

Search the named archive section. Can be given more than once to add additional archives. When given the default archive section specification is overridden.

--pv-list=FILE

Read PVs from file in addition to argument list ("-" for stdin).

-v, --verbose

Print more information. May be given up to 3 times.

Search Options

-W, --wildcard

Name patterns are interpreted as wildcard expressions which may contain '*' and '?'. This is the default of argrep.

-R, --regexp

Name patterns are interpreted as regular expressions. This is the default of argrep.

--exact

Name patterns are interpreted as list of literal PV names. No further interpretation is done. This is the default of arget.

Get Options

-s TIME, --start=TIME, -e TIME, --end=TIME

For arget, specify start and end times to use for the query. If not specified then the current system time is used. One of these must always be given or the query will return no data.

See the section TIMES for information on the formats recognised.

-T FMT, --time=FMT

Time format in text output. Supported formats are 'string' or 'posix' (floating point).

-c NUM, --count=NUM

Limit the total number of samples returned to this number. 0 may be given to retrieve all samples. However, care should be taken when doing this as it may return a lot of data.

-l NUM, --chuck=NUM

arget may make several queries to fetch all of the requested data. This option specifies the number of points to request for each of these queries. The default will usually be sufficient for scalar PVs. However, for large waveforms if may not. If the server reports 500 errors then try setting a smaller chunk size.

This option does not effect the data returned.

--no-enum

Print enumerations as integers

--skip-first

Do not print the value of PVs at the start of the time range. Only PVs which change during the time window are printed.

EXAMPLES

List all available archive sections. Override any default pattern which may be set.

$ arinfo -a '*'
section1
section2
...

Search for some PVs having 'Dev1' or 'Dev2' in the name.

$ argrep -a 'section*' 'Dev[12]'
X:Dev1:Set
X:Dev2:Set
...

To get information on available time ranges for each PV.

$ argrep -v Dev1:Set
...
2012-04-10 14:41:11.999682 , 2012-10-15 02:02:15.933004 , X:Dev1:Set

Or get a further breakdown by archive section.

$ argrep -vv Dev1:Set
...
X:Dev1:Set
  2012-04-10 14:41:11.999682 , 2012-10-15 02:00:21.288242 , section1
  2012-10-15 02:02:15.571932 , 2012-10-15 02:02:15.933004 , section3

To retrieve and print up to 1000 points in the given time range.

$ arget -s '2012-10-15 01:50:0.0' -e '2012-10-15 02:10:00' -c 1000 X:Dev1:Set
X:Dev1:Set
2012-10-15 01:49:57.838879 -14.0
...

Or write all points of in this time range to an HDF5 file.

$ arget -E hdf5 -s '2012-10-15 01:50:0.0' -e '2012-10-15 02:10:00' -c 0 file.h5:/group X:Dev1:Set

TIME FORMAT

The time and date formats understood by the --start and --end arguments can be absolute time as

[YYYY-]MM-DD HH:MM[:SS[.fff]]

DD/MM[/YYYY] HH:MM[:SS[.fff]]

HH:MM[:SS[.fff]]

When part of the date is omitted then the current day is used. When part of the time is omitted then zero is used.

### UUU [### UUU ...]

where ### is a signed floating point number, and UUU is a unit string.

Supported unit strings

us
ms
s, sec, secs, second, seconds
m, min, mins, minute, minutes
h, hrs, hour, hours
d, day, days
w, week, weeks

Relative times can also be specified according to the following rules.

If both --start and --end are relative then they are taken to be in relation to the current system time.

If only --start is relative then it is taken as relative to the absolute end time.

If only --end is relative then, if end >0 it is taken in relation to the absolute start time. However, if <0 it is taken as relative to the current system time.

The following example retrieves 00:00 through 04:00 on 24 March of the current year.

$ arget -s '24/03 00:00' -e '4 h'...

To retrieve the last 10 minites of data.

$ arget -s '-10 min' ...

HDF5 LAYOUT

The HDF5 file given to arget will be created if it does not exist. If it does exist it will be added to if the new data has a timestamp later then any which is currently stored.

When invoking arget an additional argument is given with the filename. This has the form 'filename:/group'. If group is omitted then '/' is used. For each PV to be stored a sub-group is created with two datasets 'value' and 'meta'.

/group/<pv name>/value
/group/<pv name>/meta

The 'meta' dataset is a compound type (structure) which four members: severity, status, sec, and ns. These are copied verbatim from the data received from the data server. The field 'sec' is relative to Posix Epoch (1 Jan 1970).

The 'value' dataset is an MxN of type string, int32, or float64. M is the sample number and is matched with a corresponding entry in 'meta'. N is the index in the value of a single sample. N is choosen to hold the longest returned value.

CONFIG FILES

Several files are read for configuration parameters. The order in which they are read is:

1) /etc/carchive.conf
2) $HOME/.carchiverc
3) $PWD/carchiver.conf

Values read from each file override values from previous files or defaults.

See /etc/carchive.conf.example for available options.

AUTHOR

Michael Davidsaver <[email protected]>