org.csstudio.opibuilder.scriptUtil

## Class PVUtil

- java.lang.Object
- - org.csstudio.opibuilder.scriptUtil.PVUtil

-     public class PVUtil
      extends java.lang.Object

  The utility class to facilitate Javascript programming for PV operation.
  Author:
    Xihui Chen

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PVUtil()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static org.csstudio.utility.pv.PV` | `createPV(java.lang.String name, org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)` Create a PV and start it.
    `static double` | `getDouble(org.csstudio.utility.pv.PV pv)` Try to get a double number from the PV.
    `static double` | `getDouble(org.csstudio.utility.pv.PV pv, int index)` Try to get a double-typed array element from the Value.
    `static double[]` | `getDoubleArray(org.csstudio.utility.pv.PV pv)` Try to get a double-typed array from the pv.
    `static java.lang.String` | `getFullString(org.csstudio.utility.pv.PV pv)` Get the full info from the pv in this format
    `static java.lang.Long` | `getLong(org.csstudio.utility.pv.PV pv)` Try to get a long integer number from the PV.
    `static long[]` | `getLongArray(org.csstudio.utility.pv.PV pv)` Try to get an integer-typed array from the pv.
    `static int` | `getSeverity(org.csstudio.utility.pv.PV pv)` Get severity of the pv as an integer value.
    `static java.lang.String` | `getSeverityString(org.csstudio.utility.pv.PV pv)` Get severity of the PV as a string.
    `static double` | `getSize(org.csstudio.utility.pv.PV pv)` Get the size of the pv's value
    `static java.lang.String` | `getStatus(org.csstudio.utility.pv.PV pv)` Get the status text that might describe the severity.
    `static java.lang.String` | `getString(org.csstudio.utility.pv.PV pv)` Converts the given pv's value into a string representation.
    `static double` | `getTimeInMilliseconds(org.csstudio.utility.pv.PV pv)` Get milliseconds since epoch, i.e.
    `static java.lang.String` | `getTimeString(org.csstudio.utility.pv.PV pv)` Get the timestamp string of the pv

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### PVUtil

          public PVUtil()

  - ### Method Detail

    - #### createPV

          public static final org.csstudio.utility.pv.PV createPV(java.lang.String name,
                                            org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)
                                                           throws java.lang.Exception

      Create a PV and start it. PVListener can be added to the PV to monitor its value change, but please note that the listener is executed in non-UI thread. If the code need be executed in UI thread, please use `ScriptUtil.execInUI(Runnable, AbstractBaseEditPart)`. The monitor's maximum update rate is 50hz. If the PV updates faster than this rate, some updates will be discarded.
      Example Jython script:

                  from org.csstudio.opibuilder.scriptUtil import PVUtil
                  from org.csstudio.utility.pv import PVListener

                  class MyPVListener(PVListener):
                          def pvValueUpdate(self, pv):
                                  widget.setPropertyValue("text", PVUtil.getString(pv))

                  pv = PVUtil.createPV("sim://noise", widget)
                  pv.addListener(MyPVListener())

      Parameters:
        `name` - name of the PV.
        `widget` - the reference widget. The PV will stop when the widget is deactivated, so it is not needed to stop the pv in script.
      Returns:
        the PV.
      Throws:
        `java.lang.Exception` - the exception that might happen while creating the pv.

    - #### getDouble

          public static final double getDouble(org.csstudio.utility.pv.PV pv)

      Try to get a double number from the PV.

      Some applications only deal with numeric data, so they want to interprete integer, enum and double values all the same.

      Parameters:
        `pv` - the PV.
      Returns:
        A double, or `Double.NaN` in case the value type does not decode into a number, or `Double.NEGATIVE_INFINITY` if the value's severity indicates that there happens to be no useful value.

    - #### getLong

          public static final java.lang.Long getLong(org.csstudio.utility.pv.PV pv)

      Try to get a long integer number from the PV.

      Some applications only deal with numeric data, so they want to interprete integer, enum and double values all the same.

      Parameters:
        `pv` - the PV.
      Returns:
        A long integer.

    - #### getDouble

          public static final double getDouble(org.csstudio.utility.pv.PV pv,
                         int index)

      Try to get a double-typed array element from the Value.
      Parameters:
        `pv` - The PV.
        `index` - The array index, 0 ... getSize()-1.
      Returns:
        A double, or `Double.NaN` in case the value type does not decode into a number, or `Double.NEGATIVE_INFINITY` if the value's severity indicates that there happens to be no useful value.
      See Also:
        `getSize(PV)`, `getDouble(PV)`

    - #### getDoubleArray

          public static final double[] getDoubleArray(org.csstudio.utility.pv.PV pv)

      Try to get a double-typed array from the pv.
      Parameters:
        `pv` - the pv.
      Returns:
        A double array, or an empty double array in case the value type does not decode into a number, or if the value's severity indicates that there happens to be no useful value.
      See Also:
        `getSize(PV)`, `getDouble(PV)`

    - #### getLongArray

          public static final long[] getLongArray(org.csstudio.utility.pv.PV pv)

      Try to get an integer-typed array from the pv.
      Parameters:
        `pv` - the pv.
      Returns:
        A long integer array, or an empty long integer array in case the value type does not decode into a number, or if the value's severity indicates that there happens to be no useful value.
      See Also:
        `getSize(PV)`, `getLong(PV)`

    - #### getSize

          public static final double getSize(org.csstudio.utility.pv.PV pv)

      Get the size of the pv's value
      Parameters:
        `pv` - the pv.
      Returns:
        Array length of the pv value. `1` for scalars.

    - #### getString

          public static final java.lang.String getString(org.csstudio.utility.pv.PV pv)

      Converts the given pv's value into a string representation. For string values, returns the value. For numeric (double and long) values, returns a non-localized string representation. Double values use a point as the decimal separator. For other types of values, the value's `IValue.format()` method is called and its result returned.
      Parameters:
        `pv` - the pv.
      Returns:
        a string representation of the value.

    - #### getFullString

          public static final java.lang.String getFullString(org.csstudio.utility.pv.PV pv)

      Get the full info from the pv in this format

          timestamp value severity, status

      Parameters:
        `pv` -
      Returns:
        the full info string

    - #### getTimeString

          public static final java.lang.String getTimeString(org.csstudio.utility.pv.PV pv)

      Get the timestamp string of the pv
      Parameters:
        `pv` - the pv
      Returns:
        the timestamp in string.

    - #### getTimeInMilliseconds

          public static final double getTimeInMilliseconds(org.csstudio.utility.pv.PV pv)

      Get milliseconds since 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` - the pv
      Returns:
        milliseconds since 1970.

    - #### getSeverity

          public static final int getSeverity(org.csstudio.utility.pv.PV pv)

      Get severity of the pv as an integer value.
      Parameters:
        `pv` - the PV.
      Returns:
        0:OK; -1: Invalid; 1: Major; 2:Minor.

    - #### getSeverityString

          public static final java.lang.String getSeverityString(org.csstudio.utility.pv.PV pv)

      Get severity of the PV as a string.
      Parameters:
        `pv` - the PV.
      Returns:
        The string representation of the severity.

    - #### getStatus

          public static final java.lang.String getStatus(org.csstudio.utility.pv.PV pv)

      Get the status text that might describe the severity.
      Parameters:
        `pv` - the PV.
      Returns:
        the status string.