Judy's EPICS PV query application: https://seal.slac.stanford.edu/apex/mccqa/f?p=259:8

Table of Contents

1. Starting the Application

WEB START users, please read the information on the page where you got the program. Other users, please continue.

To start ArchiveViewer, make sure JAVA_HOME is defined. Change to the directory that contains archiveviewer.jar.
Type java -jar archiveviewer.jar [-options], where [-options] can be one (or sometimes more) of these:
-u "url"

Connects to the archive data server at the specified URL
-f "config file"

Loads a configuration file
-a "name"

Selects the specified archive
-d "absolute path"

Sets your home directory (e.g. for config files)
-v(ersion)

Prints version info
-h(elp)

Prints this info

2. Basics

• Main Components
  ArchiveViewer consists of 4 major components.
  • The control panel contains the ArchiveViewer entries (AVEs) configurator (on the left) and the axes configurator (on the right)
  • The tabbed pane at the bottom shows loaded plot plugins
  • Between control panel and plot plugins panel is a (narrow) status panel. The status panel shows important static as well as dynamic information. There is also a progress bar (on the right). Tip: Always take a look at the status panel, when you are not sure if a task is running.
• Main steps
  If you use command line options, you might not need to perform some of these steps. If you don't, but possess a configuration file, you can load it now (see #Menubar). The default procedure though is the following:
  • go to FILE menu and select NEW CONNECTION (FILE => NEW CONNECTION)
  • select (or enter) the URL of the desired archive data server and press OK
  • after the server information was retrieved, you can select a desired archive directory in the main panel
  • Enter a search string into the main text field; press SEARCH or hit ENTER. A window pops up that allows you to configure your search. Its right half is empty at first, but will soon be filled with meta data of matching PVs (if it doesn't happen soon, please take a look at the progress in the status panel => perhaps you simply asked for too many PVs)
  • Select your desired PVs and add them to the main panel by pressing ADD (or you can just double click on a particular PV)
  • Close or move away the search window
  • If desired, enter time ranges for the MAIN TIME AXIS (we facilitate this by providing the TIME SELECTORs that appear when you press one of the "..."- buttons next to time entry fields)
  • Press PLOT and wait
  • After data is retrieved, you can access tooltips that contain further information about AVEses by holding the mouse for about 2 seconds over corresponding AVE table cells.

3. Axes Configuration

You can configure time and range axes on the right side of the control panel

1. 1. Time Axis
      Enter either absolute or relative time strings (see #Entering Times) into the fields under the time axes box. Alternatively, you can use time selectors that appear when you press the "..." button next to the proper text field. Tip: There are syntax tooltips available if you hold the mouse over a text field for about 2 seconds. Under the time fields, a box lets you select a location for your time axis.
   2. Range axis
      Enter numeric values into the min/max text fields under the range axes box. Java understands a huge variety of number formats (e.g. 1e-1 is allowed), so just try some out, and please do tell us if you think some currently unsupported formats should be added. Note: If you enter nothing, the value is considered to be "whatever it actually is". You can specify the scale type and the location of the range axis by selecting the values in corresponding combo boxes. Currently supported range axes types are NORMAL and LOG(arithmic).
   3. Advanced settings
      You can access advanced axes features by clicking the "..." to the right of the axis name. The options here are:
      • "add new axis" pops up a dialog and asks you to enter a unique label of the new axis.
      • "remove selected axis" (note: you can not remove the last axis)
      • "rename selected axis"
      • "update selected axis from active chart" updates the range of the corresponding axis to what is shown by the currently active chart
      • "update all axes from active chart" updates all ranges of the axes to what is shown by the currently active chart
      • "reset selected axis" resets the corresponding axis range
      • "reset all axes" resets all axes ranges

4. Entering Times

Times can be entered either manually or through time selectors, which appear when you press one of the "..."- buttons to the right of the proper textfield in the time axes panel. Even if you decide to never enter times manually, you should read this reference.

• Absolute Times
  You can enter absolute times for start and end times of a query. Many of absolute time string components are optional. The format for absolute time strings is shown as a tool tip on a time text field. The minimal, mandatory, absolute time string must follow the pattern 'MM/dd' (MM is the month, dd- the day of month) The application will automatically enter these values for missing time components:
  • year: current system year
  • hours: 00
  • minutes: 00
  • seconds: 00
  • msecs: 000
• Keyword "now"
  The application accepts the keyword "now". Milliseconds before the server request is actually sent, "now" is replaced by the current system time. Please note: If you press PLOT without checking "Keep Plot Ranges", despite caching new data request will be generated because "now" is resolved to a later value.
• Relative Times
  One of ArchiveViewer's most innovative features is its ability to parse relative time strings. Unfortunately, as with all innovations, the correct usage requires some learning time.
  1. Following tokens are accepted for each of the relative time components (please, note that they indeed are case sensitive):
     • y - year
     • M - month
     • d - day
     • H - hours
     • m - minutes
     • s - seconds
  2. For numeric values, only integers are allowed. For positive integers, you may also use the preceeding "+" sign, which would makes sense semantically
  3. Finally, you can use absolute time entries at the end of each relative date string.
  4. Here are some examples of relative time strings:
     • Legal
       "+1d", "6m", "-1M 6d", "-8H", "-2d 08:00" (note: no spaces are allowed between numbers and relative time tokens)
     • Illegal
       "-1D", "+2 y", "2.5H"
  5. Semantics
     • The sole notion of "relative" time strings requires some kind of a base, and indeed there is something we call "base times", relatively to which "relative times" are resolved. In very most cases, base times can be determined intuitively. We call a relative time string "positive", if the result of parsing and calculating it (in seconds) is a positive number; and we call such string "negative", if the result is a negative number. Please, note that it makes no sense to use positive relative time strings for the start time of a query.
     • All in all, there are 6 cases to consider:
       1. Start time is absolute; end time is absolute Example: Start: 01/01/2003 8:00 End: 01/02/2003
       2. Start time is negative relative; end time is absolute => base time: end time Example: Start: -10d End: now Means: retrieve data from the last 10 days
       3. Start time is absolute; end time is positive relative => base time: start time Example: Start: 01/02/2004 10:00 End: +8H Means: retrieve data that was generated on January 2nd 2004 between 10am and 6pm
       4. Start time is negative relative; end time is positive relative => base time for start time: "now"; base time for end time: start time Example: Start: -7d 8:00 End: +8H Means: retrieve data from the current shift a week ago
       5. Start time is absolute; end time is negative relative => base time: "now" Example: Start: 06/01/2004 End: -5d Means: retrieve data from the 1st of June up to 5 days ago from now
       6. Start time is negative relative; end time is negative relative => base times: "now" for both time strings Example: Start: -10d End: -5d +8H Means: retrieve data from 10 days ago upto 5 days ago, plus 8 more hours of data
  6. Conclusion
     Relative time strings is a fairly intuitive and very useful feature because they allow automated processing of many desirable configurations (just think how easily you can retrieve "yesterday's shift data" day after day).

5. Formulas

One of the more complex features of the ArchiveViewer is the ability to use PVs from common archive directories in a formula that is treated like a genuine PV by the application. You can create a new formula by loading the formula configurator when you press the "NEW FORMULA"- button on the main controls panel.

Following steps are recommended for creating a formula:

• Select PVs from the supplied PV list
• Assign a unique variable to each PV (default variables will be x0, x1, etc.)
• Using these variables, type in your formula, possibly using the supplied calculator UI

Variables have two major advantages: resulting formulas will be short and thus, well readable; and complex formulas could be re-used for other PVs without much hassle.

Supported functions

Besides basic arithmetics and binary operations, all functions specified by methods of the java.lang.Math class as well as min, max, and arithmetic mean functions (with indefinite number of arguments) are supported by the internal formula parser.

6. Graphs Configuration

The ArchiveViewer assigns default colors, plot types, and time/range axes to each graph (i.e. a genuine PV or a formula). By pressing the "..."-button next to each graph name, you can change these settings.

1. 1. Axes selection
      The labels in the selection box correspond to the labels of the axes in the main control panel. Note: If you want to plot a graph normalized, select the empty entry in the box
   2. Color
   3. Draw types
      • scatter
      • lines: connects graph data points directly
      • steps: connects data points of a graph by drawing a horizontal line and then a vertical line (like a step). This draw type is default/li>
   4. Width
      You can adjust the width of graph lines with this slider
   5. Visibility
      Uncheck the visibility box, if you don't want to display the graph in the next plot. This might be useful if, for example, you 'd like to see the underlying graphs.

7. Export

• The export dialog is located under FILE => Export...
• Basic configuration
  • Generally speaking, you always have to select one archive directory from which you want to export data. However, exporting data from more than one archive at the same time might be supported by some servers, too.
  • By selecting "Selected Graphs Only", you can make the program export data of selected PVs and formulas only.
  • You can enter a new time range for the query. Alternatively, you can load time ranges from the currently selected time axis.
  • The application contains an internal exporter that prints data in CSV format (actually, separated by tabs). Other exporters can be plugged in.
  • Per default, data is exported to an output window. However, you can bypass it by specifying a file. You can type a file path to the desired file manually, or you can select a file after pressing the "..."- button
  • As soon as you press OK, the export starts. Please take notice of the export progress. If it seems to take too much time or just to be too much data, you may interrupt the request (by pressing the red button next to progress bar). Note: data that was exported before interruption remains available
• Advanced configuration
  • You can reach advanced settings by pressing the "..."- button and then selecting the "MORE..." menu item.
  • The method combobox contains data retrieval methods for export that are supported by current archive server.
  • You may enter a maximum number of data samples per PV.
  • For some export methods, it will make more sense to enter a period of time for which you want a single sample (this field and the "max number of values" field are symbiotic)
    You may enter your own timestamp format (useful, for instance, if you are going to send the file to Europe). Please, use the tooltip to see the supported syntax.
  • Finally, you can export data as well as status information, or just pure data.

8. Menubar

1. 1. FILE menu
      • New Connection
        pops up a dialog where you can enter the connection parameters for the data server
      • Reconnect
        Sometimes there are (network) errors that may corrupt current connection to the data server. Simply press this menu button to re-establish the connection
      • Open, Open Recent..., Save, Save As
        These menu buttons are used for loading and saving the PVs/axes configuration from the main controls panel. Note: For preferences stuff, please go to the EDIT menu.
      • Export
        See #Export.
      • Print... and Page Setup...
        Displays widgets for printing the application window
      • Clear All
        Clears all information in the main window.
      • Quit
        Exits the application
   2. EDIT menu
      • Copy, cut, paste
        standard menu items, have the same effects as corresponding keyboard short cuts (e.g. Ctrl+x etc. on Windows)
      • Preferences
        Includes a plot title setter, a legend configurator, and a plot plugin loader
   3. VIEW menu
      • Search Dialog
        Displays the search dialog
      • Full Screen
        Resizes the main window to occupy the entire screen
      • Show Console, Show Event Log, Show Memory Console
        Some of XAL widgets
   4. TOOLS menu
      • Assign Selected Archive
        Assigns the selected archive to selected graphs (useful for formulas, or if archive names changed etc.)
      • Clear Cache
        Clears all cached data
   5. WINDOW menu
      • Capture As PNG...
        Does the same as the PRINT SCREEN key, but is more specific
   6. HELP menu
      • Contents
        Opens this guide
      • Server Info
        Shows information that the current archive server might have on itself
      • About
        Some basic information on the application

9. General Plot Plugin Features

Note: some plot plugins may support only subsets of these features, others may have more functionality. Please, check proper user manuals.

1. 1. Plot legend
      Consists at least of colorful shapes. To configure the legend, please go to EDIT => Preferences...
   2. Zoom in
      You can zoom into the plot with your left mouse. There is a minimum dragging distance required to activate the zoom capability. This prevents accidental mouse "hang ups".
   3. Plot manipulation buttons
      From left to right:
      • goes back in time the time range(s) you currently see on screen
      • goes forth in time the time range(s) you currently see on screen
      • goes "up" the value range(s) you currently see on screen
      • goes "down" the value range(s) you currently see on screen
      • doubles the time range(s) you currently see on screen
      • doubles the value range(s) you currently see on screen
      • zooms out if you previously zoomed in (note: will be moved to the right mouse button - menu in nearest future)
      • displays a menu for advanced configuration:
        • uses anti-alias drawing method if checked
        • leaves ignored items if checked and no new data is retrieved
   4. Some typical "right mouse click" menu - features
      • Properties: some chart specific properties
      • Save as... : saves the plot as a PNG image
      • Print... : prints the plot
      • Ignore Item... : ignores the current plot item (may be inactive)
   5. Dock/undock
      In the top right corner of a plot plugin panel, there is the dock/undock button. Please, note that once a plot plugin is undocked, it can not be controlled from the main controls panel. However, zoom-in and plot manipulation buttons should continue to function.

Written by Sergei Chevtsov (chevtsovs@ornl.gov) April 11th, 2005