Class PVUtil


  • public class PVUtil
    extends java.lang.Object
    Utility for handling PVs and their values in scripts.
    • Constructor Detail

      • PVUtil

        public PVUtil()
    • Method Detail

      • getVType

        public static org.epics.vtype.VType getVType​(RuntimePV pv)
                                              throws java.lang.NullPointerException
        Get valid value from PV
        Parameters:
        pv - PV
        Returns:
        Valid value
        Throws:
        java.lang.NullPointerException - when PV is not connected, no valid value
      • getDouble

        public static double getDouble​(RuntimePV pv)
        Try to get a 'double' type number from the PV.
        Parameters:
        pv - PV
        Returns:
        Current value. Double.NaN in case the value type does not decode into a number, or PV has no value.
      • getInt

        public static int getInt​(RuntimePV pv)
                          throws java.lang.NullPointerException
        Try to get an integer from the PV.
        Parameters:
        pv - PV
        Returns:
        Current value as int. Boolean will turn into 0, 1.
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getLong

        public static long getLong​(RuntimePV pv)
                            throws java.lang.NullPointerException
        Try to get a long integer from the PV.
        Parameters:
        pv - PV
        Returns:
        Current value as long
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getString

        public static java.lang.String getString​(RuntimePV pv)
                                          throws java.lang.NullPointerException
        Get value of PV as string.
        Parameters:
        pv - PV
        Returns:
        Current value as string. Boolean will turn into "false"/"true"
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getString

        public static java.lang.String getString​(RuntimePV pv,
                                                 boolean byte_array_as_string)
                                          throws java.lang.NullPointerException
        Get value of PV as string.

        Optionally, byte arrays can be requested as a (long) string, instead of "[ 1, 2, 3, .. ]"

        Parameters:
        pv - PV
        byte_array_as_string - Decode byte arrays as string?
        Returns:
        Current value as string
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getLabels

        public static java.lang.String[] getLabels​(RuntimePV pv)
                                            throws java.lang.NullPointerException
        Get labels for a VEnum value, or headers for a VTable.
        Parameters:
        pv - the PV.
        Returns:
        Enum labels or empty array if not enum nor table
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getDoubleArray

        public static double[] getDoubleArray​(RuntimePV pv)
                                       throws java.lang.NullPointerException
        Try to get a 'double' type array from a PV.
        Parameters:
        pv - the PV.
        Returns:
        Current value as double[]. Will return single-element array for scalar value, including { Double.NaN } in case the value type does not decode into a number.
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getLongArray

        public static long[] getLongArray​(RuntimePV pv)
                                   throws java.lang.NullPointerException
        Try to get a 'long' type array from a PV.
        Parameters:
        pv - the PV.
        Returns:
        Current value as long[]. Will return single-element array for scalar value.
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getStringArray

        public static final java.lang.String[] getStringArray​(RuntimePV pv)
                                                       throws java.lang.NullPointerException
        Get string array from pv.
        Parameters:
        pv - The PV.
        Returns:
        String array. For string array, it's the actual strings. For numeric arrays, the numbers are formatted as strings. For enum array, the labels are returned. For scalar PVs, an array with a single string is returned.
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getTimeString

        public static java.lang.String getTimeString​(RuntimePV pv)
                                              throws java.lang.NullPointerException
        Get the timestamp string of the PV.

        Time stamp of the PV is formatted using the common TimestampFormats helper for the local time zone.

        Parameters:
        pv - PV
        Returns:
        Timestamp string
        Throws:
        java.lang.NullPointerException - if the PV has no value
        See Also:
        to fetch time stamp for custom formatting
      • getTimeInMilliseconds

        public static final long getTimeInMilliseconds​(RuntimePV pv)
                                                throws java.lang.NullPointerException
        Get milliseconds since POSIX Epoch, i.e. 1 January 1970 0:00 UTC.

        Note that we always return milliseconds relative to this UTC epoch, even if the original control system data source might use a different epoch (example: EPICS uses 1990), because the 1970 epoch is most compatible with existing programming environments.

        Parameters:
        pv - PV
        Returns:
        milliseconds since 1970.
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getSeverity

        public static final int getSeverity​(RuntimePV pv)
        Get alarm severity of the PV as an integer value.
        Parameters:
        pv - PV
        Returns:
        0: OK; 1: Major; 2:Minor, -1: Invalid or Undefined
      • getLegacySeverity

        @Deprecated
        public static final int getLegacySeverity​(RuntimePV pv)
        Deprecated.
        Use getSeverity
        Get alarm severity of the PV as an integer value.

        This uses the legacy mapping of alarm severities

        Parameters:
        pv - PV
        Returns:
        0: OK; 1: Major; 2:Minor, -1: Invalid or Undefined
      • getSeverityString

        public static final java.lang.String getSeverityString​(RuntimePV pv)
        Get alarm severity of the PV as a string
        Parameters:
        pv - PV
        Returns:
        Alarm severity as "NONE", "MINOR", "MAJOR", "INVALID", "UNDEFINED"
      • getStatus

        public static final java.lang.String getStatus​(RuntimePV pv)
        Get alarm status, i.e. text that might describe the alarm severity
        Parameters:
        pv - PV
        Returns:
        Alarm status
      • getTable

        public static java.util.List<java.util.List<java.lang.Object>> getTable​(RuntimePV pv)
                                                                         throws java.lang.NullPointerException
        Get a table from PV

        Ideally, the PV holds a VTable, and the returned data is then the table's data.

        If the PV is a scalar, a table with a single cell is returned.

        If the PV is an array, a table with one column is returned.

        Parameters:
        pv - PV
        Returns:
        List of rows, where each row contains either String or Number cells
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getStructure

        public static java.util.List<java.util.List<java.lang.Object>> getStructure​(RuntimePV pv,
                                                                                    java.lang.String name)
                                                                             throws java.lang.NullPointerException
        Get data from a structured value by name.

        As with other structure-related get methods, full and partial names may be used. However, the name must designate a structured field, rather than a scalar data field. For example, the structure

          structure value
                structure Foo
                    scalar_t[] a
                   structure Bar
                       scalar_t[] a
                       scalar_t[] x
          
        can match "Foo" (which returns data for Foo/a, Bar/a, and x) or "Foo/Bar" (which returns data for Bar/a and x), but not "Foo/a" or "Bar/x". For those, use getStructureElement(RuntimePV, String, int). Ambiguous names will find the first structure with a matching name.
        Parameters:
        pv - RuntimePV that should how a VTable
        name - Name of the substructure to get; if blank (empty String, ""), the entire structure is returned
        Returns:
        A List of "rows", where rows are lists of scalar data (Strings or Numbers) belonging to scalar fields of the matching sub-structure; if there is no matching sub-structure, the list is empty.
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getTableCell

        public static java.lang.Object getTableCell​(RuntimePV pv,
                                                    int row,
                                                    int column)
                                             throws java.lang.NullPointerException
        Get a table cell from PV

        PV must hold a VTable

        Parameters:
        pv - RuntimePV that should how a VTable
        row - Row index, 0..
        column - Column index, 0..
        Returns:
        Either String or Number for the cell's value, null if invalid row/column
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getStructureElement

        public static java.util.List<java.lang.Object> getStructureElement​(RuntimePV pv,
                                                                           java.lang.String name)
                                                                    throws java.lang.NullPointerException
        Get a structure element from a PV by field name.

        PV should hold a VTable which represents the structure.

        For nested structure elements represented with slash-separated names, full and partial field names are accepted. For instance, a structure "value" with the definition

          structure value
              structure Foo
                  scalar_t[] a
                  structure Bar
                      scalar_t[] a
                      scalar_t[] x
          
        has the field "x" with full name "Foo/Bar/x", which can be found with "Foo/Bar/x", "Bar/x", or "x". Ambiguous names (like "a" in the example above) will find the first field with a matching name.
        Parameters:
        pv - RuntimePV that should how a VTable
        name - Structure element name
        Returns:
        If the value has an elements with a matching name, a List<String> or List<Number> is returned, depending on the element's data type. If not, and the value is a VTable, an empty list is returned. Otherwise, a List containing one element, a String representation of the value.
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • getStructureElement

        public static java.lang.Object getStructureElement​(RuntimePV pv,
                                                           java.lang.String name,
                                                           int index)
                                                    throws java.lang.NullPointerException
        Get an element from a PV structure by field name and array index.

        If index is valid, this method is equivalent to getStructureElement(pv, name).get(index).

        Parameters:
        pv - RuntimePV
        name - Structure element name
        index - Element index in range [0, n-1], where n is the length of the structure element
        Returns:
        Either String or Number for the cell's value, null if invalid name/index
        Throws:
        java.lang.NullPointerException - if the PV has no value
      • createPV

        public static RuntimePV createPV​(java.lang.String pv_name,
                                         int timeout_ms)
                                  throws java.lang.Exception
        Create a PV.

        Ideally, scripts use the PVs of widgets or the script 'input' PVs, where the display runtime handles the PV connection. In rare cases it might be necessary to create a PV in a script, in which case the script must then also release the PV.

        Parameters:
        pv_name - Name of the PV
        timeout_ms - Connection timeout in milliseconds
        Returns:
        PV
        Throws:
        java.lang.Exception - on error
        See Also:
        releasePV(RuntimePV)
      • writePV

        public static final void writePV​(java.lang.String pv_name,
                                         java.lang.Object value,
                                         int timeout_ms)
                                  throws java.lang.Exception
        Write a value to a PV

        Ideally, scripts use the PVs of widgets or the script 'input' PVs, where the display runtime handles the PV connection. In rare cases it might be necessary to create a PV in a script, write a value, and then release the PV, which is done by this method.

        Parameters:
        pv_name - Name of the PV
        value - Value to write
        timeout_ms - Connection timeout in milliseconds
        Throws:
        java.lang.Exception - If write cannot be performed.