Usage : This utility retrieves data which has been accumulated by
one of the 'Lumberjack' circular dataloggers. The output data
is collated into paired dataset ASCII files which are named
after the device (eg 'M_OUTTMP.TMP'). The data is paired in
time vs. value columns where time is presented as units of hours
since midnight of the first day requested and value as engineering
or "common" units. These files, in turn, can be used as standard
input to various spreadsheets and plotting packages. Alternatively,
the data can be directly mailed to a specified user. Also, there is
an option to output the data to a database table instead. This
allows the user to read the data directly into programs like
Excel without having to go through the additional step of mailing
the data.
The command usage syntax is as follows:
$ dataview[/qualifiers] [device1][,...,device10]
or
$ dataview[/qualifiers]/input={device file}
Qualifiers are as follows:
/LJ
/LJ=lumberjack_name
This qualifier allows specification of the Lumberjack from which to
acquire data. If this parameter is not supplied, data will be taken
from the Lumberjack which is logging each parameter at the fastest
rate. There are also two special node values of "LOGGER_FASTEST_NODE"
(default) and "LOGGER_ANY_NODE".
/START
/START=date-time
Specifies the date-time of the first data point to be collected.
If this qualifier is specified and a special value is not used,
the date and time must be entered in 'dd-mmm-yyyy:hh:mm:ss' format,
as in the following examples:
TODAY today at midnight (default)
YESTERDAY yesterday at midnight
THIS_WEEK midnight Monday morning of this week
LAST_WEEK midnight Monday morning of last week
THIS_MONTH midnight of the first of this month
THIS_YEAR midnight of January 1st of this year
01-JAN-2001 assumes 01-JAN-2001:00:00:00
01-JAN-2001:10 assumes 01-JAN-2001:10:00:00
01-JAN-2001:10:30:05 assumes 01-JAN-2001:10:30:05
If this argument is not present, the start time will default to today
at midnight. You can also express the date in the format
"""dd-mmm-yyyy hh:mm:ss""". All of the enclosing quotes are
necessary if you wish to have embedded spaces in the date.
/END
/END=date-time
/STOP
/STOP=date-time
Specifies the date-time of the last data point to be collected.
If this qualifier is specified, the date-time must be entered in
'dd-mmm-yyyy:hh:mm:ss' format, as in the following examples:
NOW now
TODAY today at midnight (default)
YESTERDAY yesterday at midnight
THIS_WEEK midnight Monday morning of this week
LAST_WEEK midnight Monday morning of last week
THIS_MONTH midnight of the first of this month
THIS_YEAR midnight of January 1st of this year
01-JAN-2001 assumes 01-JAN-2001:00:00:00
01-JAN-2001:10 assumes 01-JAN-2001:10:00:00
01-JAN-2001:10:30:05 assumes 01-JAN-2001:10:30:05
If this argument is not present, the end time will default to the
present time. You can also express the date in the format
"""dd-mmm-yyyy hh:mm:ss""". All of the enclosing quotes are
necessary if you wish to have embedded spaces in the date.
/TIME_INTERVAL
/TIME_INTERVAL=DAY
In addition to explicitly specifying start and end times for data
acquisition, a start or end time and a time interval can be
specified. If the time interval is positive, the end time is
calculated based upon the start time. If the time interval is
negative, the start time is calculated based upon the end time.
Time interval specifiers:
MIN(S) -> minutes
HOUR(S) -> hours
DAY(S) -> days
WEEK(S) -> weeks
Each time interval can be preceded by an integer multiplier value
(ie 2DAYS).
/TSTAMP_FORMAT
/TSTAMP_FORMAT=ELAPSED_HOURS (default)
Specifies the type of timestamp to deliver. The default format is
a floating point number of hours since midnight of the first day
of the plot range.
Timestamp formats:
ELAPSED_HOURS -> timestamp is elapsed hours (float value) (default)
CTIME -> ctime format timestamp 'dow dd-mmm-yy hh:mm:ss'
VMS_TIME -> VMS format timestamp 'dd-mmm-yyyy hh:mm:ss'
SECONDS -> time in seconds since 01-Jan-1972 (integer)
ELAPSED_SECONDS -> time in seconds since start time
ORDINAL_TIME -> ordinal number of the data point 0,1,2, ...
NO_TIME -> no timestamp
/UNITS
/UNITS=COMMON (default)
Specifies the type of data value to deliver. The default format is
a floating point number representing the common (engineering) units
value.
Available units selections:
COMMON -> value is represented in common units (float value)
(ENGINEERING is a synonym for this format.)
(default)
PRIMARY -> value is represented in primary units (float value)
(VOLTS is a synonym for this format.)
RAW_HEX -> value is represented in raw units in hex
(RAW is a synonym for this format.)
RAW_DECIMAL -> value is represented in raw units in decimal
/INPUT
/INPUT="file_name"
Specifies an ASCII file from which to read the list of devices to be
read. There should be one device name per line with optional SDA
qualifier arguments. There is no limit to the number of devices in a file.
Example:
! comment line
m:outtmp
t_ha11[2] (setting property specified)
m:outtmp,f,1,2 (SDA arguments specify final data from case 1, set 2)
/MAIL
/MAIL=hendricks
or
/MAIL=hendricks@fnal.gov
Specifies that the data should be mailed to a user with one message
per device. No data files will be left in the user's directory.
/DB
/DB="{db}.{owner}.{table}"
Specifies a database table to send the output to rather than an ASCII
file. This allows programs such as Excel to read the data directly.
This table must have a somewhat fixed format. There must be five
columns in the table (four if you don't want timestamps). The first
column must be of type int and will be populated with the device's
device index. The second column must be of type smallint and will
be populated with the device property. The third column must be of
type int and will be populated with the device's array index. The type
of the fourth column depends upon the timestamp format selected with the
type being real if no timestamp format is selected. The data value
column (fourth or fifth depending on whether or not timestamps are
selected must be of type real.
Timestamp formats:
ELAPSED_HOURS -> fourth column should be of type real
CTIME -> fourth column should be of type char(19) or varchar(19)
VMS_TIME -> fourth column should be of type datetime
SECONDS -> fourth column should be of type int
ELAPSED_SECONDS -> fourth column should be of type int
ORDINAL_TIME -> fourth column should be of type int
NO_TIME -> only four columns needed with the fourth
being of type real to hold the data values
create table dataview_default_export
(
device_index int not null,
property_index smallint not null,
array_index int not null,
timestamp datetime not null,
value real not null
)
/DB_WITH_NAMES
/DB_WITH_NAMES="{db}.{owner}.{table}"
Specifies a database table to send the output to rather than an ASCII
file. This allows programs such as Excel to read the data directly.
This table must have a somewhat fixed format. There must be five
columns in the table (four if you don't want timestamps). The first
column must be of type char(8) or varchar(8) and will be populated with
the device's ACNET name. The second column must be of type smallint and
will be populated with the device property. The third column must be of
type int and will be populated with the device's array index. The type
of the fourth column depends upon the timestamp format selected with the
type being real if no timestamp format is selected. The data value column
(fourth or fifth depending on whether or not timestamps are selected must
be of type real. (Note: This option is the same as "DB" except for the
fact that the first column of the resultant database table will contain
the device name rather than the device index.)
Timestamp formats:
ELAPSED_HOURS -> fourth column should be of type real
CTIME -> fourth column should be of type char(19) or varchar(19)
VMS_TIME -> fourth column should be of type datetime
SECONDS -> fourth column should be of type int
ELAPSED_SECONDS -> fourth column should be of type int
ORDINAL_TIME -> fourth column should be of type int
NO_TIME -> only four columns needed with the fourth
being of type real to hold the data values
create table dataview_default_export
(
device_index int not null,
property_index smallint not null,
array_index int not null,
timestamp datetime not null,
value real not null
)
/BULK_INSERT
/BULK_INSERT (default)
/SQL_INSERT
Specifies the means of populating the output database table. The
default value of BULK_INSERT is much faster but requires that an
index be defined for the output table and that the target database
be enabled for slow bulk copies. Otherwise, the slower method,
SQL_INSERT, must be used.
/TRUNC
/TRUNC
/NOTRUNC (default)
Specifies whether or not to delete any existing entries in the
output database table before saving the first data point.
/SEP
/SEP="separator string"
Specifies the string which will separate the time and value columns
in the output file. The default string consists of a single tab.
/DISPLAY
/DISPLAY (default)
/NODISPLAY
Creates an efficient on-line display of DataView 2 processing. If
'NODISPLAY' is selected, a single line per device will be printed to
stdout indicating how many points were collected for each device.
/SKIP
/SKIP=number
/NOSKIP (default)
To cut down on the size of a collection, a user may wish to skip some
of the data points. By default no data points are skipped. A value
of 1 would skip 1 of every 2 points, 2 would skip 2 of every 3, etc..
/MIN_INTERVAL
/MIN_INTERVAL=5
Specifies the minimum number of seconds between returned points. If
this option is selected, it masks the SKIP parameter. The default
minimum interval is zero seconds.
/POINTS
/POINTS=number
This qualifier can be used to specify how many data points DataView 2
is to retrieve. By default the process continues to the requested
end time. This qualifier is useful if your plotting package is input
limited.
/SETTINGS
/SETTINGS
/READINGS (default)
By default DataView 2 will retrieve the reading property (PRREAD) for
all device values. This command allows the choice of the setting
property (PRSET) instead. Success is dependent on whether the
Lumberjack was instructed to save settings for the specified device(s).
This parameter is ignored if the 'INPUT' parameter has been supplied.
/SDAARGS
/SDAARGS
/NOSDAARGS (default)
This qualifier tells Dataview 2 to look for SDA arguments in the device
names. Since SDA arguments are separated from each other and the device
name by commas, device names must separated by back slashes when in this
mode. This parameter is ignored if the 'INPUT' parameter has been supplied.
Restart: This is not a constantly running process. It is executed on
demand using the command shown above in the usage section.
Keeper: Brian Hendricks
Now: Mon Oct 13 17:58:18 2008