NAME
iarequest - request on-demand waveforms from Internet Accelerometer Network
SYNOPSIS
iarequest [-p pfname] [-c cmdorbname] [-t target] [time [endtime]]
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
The
iarequest program puts a request for acquisition of
segmented waveform data onto an Antelope orbserver. The request is
to be filled by a separately-running instance of the
ia2orb(1)
program listening to that same orbserver for command packets.
If a single
time is specified on the command line of
iarequest (in any format acceptable to
str2epoch(3)), the
network request is constructed to acquire waveforms covering the
specified discrete point in time. If both
time and
endtime
are specified, the request is constructed to acquire waveforms
covering the range between the start and end time. When run with
such command-line arguments, the
iarequest program will print on
the command line the first command-response received from the
ia2orb program.
If no
time or
endtime arguments are specified on the
command-line,
iarequest launches in a Graphical User Interface
(GUI) configuration, allowing the user to make requests interactively
via the GUI. The GUI version of the program has a pair of radiobuttons,
labeled
Point and
Span, allowing the user to choose
whether to request data covering a point in time or an extended time-span.
If the
Point button is chosen, a single entry-box labeled
Start will be displayed, allowing the user to enter the point
in time the waveform data should cover, in any of the formats
acceptable to
str2epoch(3)). If the
Span button is chosen,
an additional entry-box labeled
End will be displayed. In
this configuration, the data files requested are all those on the
Internet Accelerometer
on-demand network that contain the time-span
between the specified
Start and
End times (see the
ia2orb(1) man-page for the distinction between
on-demand and
continuous stations: the
iarequest program affects only
data acquisition for those stations configured as
on-demand
in the
ia2orb parameter file). The most important part of the
iarequest GUI window is the large green
Send button in
the middle. Until that is pressed, no actual data request is made
to
ia2orb. When the
Send button is pressed, the data
request is sent to
ia2orb. The bottom window of the
iarequest
GUI shows responses received from the
ia2orb instance via the
command-orb.
OPTIONS
-
-p pfname
Specify the parameter-file to use, overriding the default parameter-file iarequest.pf
-
-c cmdorbname
Specify the name of the command-orb on which to place command packets, overriding the
cmdorbname specified in the parameter file.
-
-t target
Specify the target name of the ia2orb(1) instance at which to direct command packets,
overriding the target specified in the parameter file.
PARAMETER FILE
Parameter File Parameters
-
cmdorbname
iarequest constructs parameter-file command packets to instruct ia2orb(1) to
acquire particular data. The cmdorbname parameter specifies the name of the
orbserver on which to put the constructed command packets, for pick-up by the ia2orb(1)
instance.
-
default_gui_mode
This parameter specifies whether the default mode of iarequest, when launched as a GUI,
is point (requests are for waveforms covering a single point in time) or span
(requests are for waveforms covering a time span).
-
default_request_start
This parameter specifies the default start-time for requests when iarequest is run as a GUI.
For example, a value of '-00:10' for this parameter will set the start-time of requests to
10 minutes before the current system-clock time (as explained in the time formats acceptable to
str2epoch in the man-page str2epoch(3)). Of course, the actual start time may be edited before
the request is submitted with the Send button.
-
target
This parameter specifies the target-name of the ia2orb(1) instance, towards which command
packets are directed. The suffix pf/dlcm is appended to the contents of this
parameter in order to construct the orb source-name of the command packets generated by
iarequest.
Parameter File Example
target ia2orb
cmdorbname :
default_gui_mode point
default_request_start -00:10
EXAMPLE
The example below shows a simple request for waveforms covering one distinct point in time. The argument, in
single quotes, is a time-string in any of the formats interpretable by the str2epoch(3) command and documented
in that man-page:
% iarequest '2010-04-18 3:00'
iarequest: Received response from ia2orb:
[ia2orb thread 'command']: Issued acquisition-request to all on-demand stations for window overlapping ' 4/18/2010 3:00:00.000 UTC'
%
Because the str2epoch(3) command is able to interpret requests for data relative to the current system-clock time,
we can also use this feature to ask for relative times, such as to acquire waveforms containing the point in
time 10 minutes ago. Again, see the str2epoch(3) man-page for details on this formatting trick. As a small point
of Unix trivia, in order to get this to work with relative (negative) times, one has to precede the time value
with a "--" to indicate to the iarequest command that all hyphenated option-arguments have been given
and the next item is a command-line argument that should not be interpreted as one of the OPTION items listed
above (this "--" trick is a standard Unix feature, though one perhaps not as widely known as some others):
% iarequest -- '-00:10'
iarequest: Received response from ia2orb:
[ia2orb thread 'command']: Issued acquisition-request to all on-demand stations for window overlapping ' 4/18/2010 3:36:05.588 UTC'
%
SEE ALSO
ia2orb(1)
BUGS AND CAVEATS
Don't forget to hit the
Send button in the GUI after setting the time or times for your
data request.
When
iarequest runs in non-GUI mode, only the first response from
ia2orb is
printed before exiting. When
iarequest is run in GUI mode, all responses from
ia2orb
are printed in the scrolling text box, however this may include responses to other instances
of
iarequest as well as to instances of
iatrigger(1). This allows the
iarequest user
to better understand all data requests being undertaken by
ia2orb(1) from the Internet
Accelerometer network.
AUTHOR
Kent Lindquist
Lindquist Consulting, Inc.
Antelope User Group Contributed Software