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.simplepv.IPV` | `createPV(java.lang.String name, org.csstudio.opibuilder.editparts.AbstractBaseEditPart widget)` Create a PV and start it.
    `static double` | `getDouble(org.csstudio.simplepv.IPV pv)` Try to get a double number from the PV.
    `static double` | `getDouble(org.csstudio.simplepv.IPV pv, int index)` Try to get a double-typed array element from the Value.
    `static double[]` | `getDoubleArray(org.csstudio.simplepv.IPV pv)` Try to get a double-typed array from the pv.
    `static java.lang.String` | `getFullString(org.csstudio.simplepv.IPV pv)` Get the full info from the pv in this format
    `static java.lang.Long` | `getLong(org.csstudio.simplepv.IPV pv)` Try to get a long integer number from the PV.
    `static long[]` | `getLongArray(org.csstudio.simplepv.IPV pv)` Try to get an integer-typed array from the pv.
    `static int` | `getSeverity(org.csstudio.simplepv.IPV pv)` Get severity of the pv as an integer value.
    `static java.lang.String` | `getSeverityString(org.csstudio.simplepv.IPV pv)` Get severity of the PV as a string.
    `static double` | `getSize(org.csstudio.simplepv.IPV pv)` Get the size of the pv's value
    `static java.lang.String` | `getStatus(org.csstudio.simplepv.IPV pv)` Get the status text that might describe the severity.
    `static java.lang.String` | `getString(org.csstudio.simplepv.IPV pv)` Converts the given pv's value into a string representation.
    `static double` | `getTimeInMilliseconds(org.csstudio.simplepv.IPV pv)` Get milliseconds since epoch, i.e.
    `static java.lang.String` | `getTimeString(org.csstudio.simplepv.IPV pv)` Get the timestamp string of the pv
    `static void` | `writePV(java.lang.String pvName, java.lang.Object value)` Write a PV in a background job.
    `static void` | `writePV(java.lang.String pvName, java.lang.Object value, int timeout)` Write a PV in a background job.

    - ### 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.simplepv.IPV 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.simplepv import IPVListener

                  class MyPVListener(IPVListener):
                          def valueChanged(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.simplepv.IPV 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.simplepv.IPV 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.simplepv.IPV 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.simplepv.IPV 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(IPV)`, `getDouble(IPV)`

    - #### getLongArray

          public static final long[] getLongArray(org.csstudio.simplepv.IPV 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(IPV)`, `getLong(IPV)`

    - #### getSize

          public static final double getSize(org.csstudio.simplepv.IPV 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.simplepv.IPV 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.simplepv.IPV 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.simplepv.IPV 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.simplepv.IPV 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.simplepv.IPV pv)

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

    - #### getSeverityString

          public static final java.lang.String getSeverityString(org.csstudio.simplepv.IPV 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.simplepv.IPV pv)

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

    - #### writePV

          public static final void writePV(java.lang.String pvName,
                     java.lang.Object value,
                     int timeout)

      Write a PV in a background job. It will first creates and connects to the PV. After PV is connected, it will set the PV with the value. If it fails to write, an error dialog will pop up.
      Parameters:
        `pvName` - name of the PV.
        `value` - value to write.
        `timeout` - maximum time to try connection.

    - #### writePV

          public static final void writePV(java.lang.String pvName,
                     java.lang.Object value)

      Write a PV in a background job. It will first creates and connects to the PV. After PV is connected, it will set the PV with the value. If it fails to write, an error dialog will pop up. The maximum time to try connection is 10 second.
      Parameters:
        `pvName` - name of the PV.
        `value` - value to write.