Class PVUtil
- java.lang.Object
-
- org.csstudio.display.builder.runtime.script.PVUtil
-
public class PVUtil extends java.lang.Object
Utility for handling PVs and their values in scripts.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
PVUtil.PVHasNoValueException
-
Constructor Summary
Constructors Constructor Description PVUtil()
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static RuntimePV
createPV(java.lang.String pv_name, int timeout_ms)
Create a PV.static double
getDouble(RuntimePV pv)
Try to get a 'double' type number from the PV.static double[]
getDoubleArray(RuntimePV pv)
Try to get a 'double' type array from a PV.static int
getInt(RuntimePV pv)
Try to get an integer from the PV.static java.lang.String[]
getLabels(RuntimePV pv)
Get labels for aVEnum
value, or headers for aVTable
.static int
getLegacySeverity(RuntimePV pv)
Deprecated.Use getSeveritystatic long
getLong(RuntimePV pv)
Try to get a long integer from the PV.static long[]
getLongArray(RuntimePV pv)
Try to get a 'long' type array from a PV.static int
getSeverity(RuntimePV pv)
Get alarm severity of the PV as an integer value.static java.lang.String
getSeverityString(RuntimePV pv)
Get alarm severity of the PV as a stringstatic java.lang.String
getStatus(RuntimePV pv)
Get alarm status, i.e.static java.lang.String
getString(RuntimePV pv)
Get value of PV as string.static java.lang.String
getString(RuntimePV pv, boolean byte_array_as_string)
Get value of PV as string.static java.lang.String[]
getStringArray(RuntimePV pv)
Get string array from pv.static java.util.List<java.util.List<java.lang.Object>>
getStructure(RuntimePV pv, java.lang.String name)
Get data from a structured value by name.static java.util.List<java.lang.Object>
getStructureElement(RuntimePV pv, java.lang.String name)
Get a structure element from a PV by field name.static java.lang.Object
getStructureElement(RuntimePV pv, java.lang.String name, int index)
Get an element from a PV structure by field name and array index.static java.util.List<java.util.List<java.lang.Object>>
getTable(RuntimePV pv)
Get a table from PVstatic java.lang.Object
getTableCell(RuntimePV pv, int row, int column)
Get a table cell from PVstatic long
getTimeInMilliseconds(RuntimePV pv)
Get milliseconds since POSIX Epoch, i.e.static java.lang.String
getTimeString(RuntimePV pv)
Get the timestamp string of the PV.static org.epics.vtype.VType
getVType(RuntimePV pv)
Get valid value from PVstatic void
releasePV(RuntimePV pv)
static void
writePV(java.lang.String pv_name, java.lang.Object value, int timeout_ms)
Write a value to a PV
-
-
-
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
- PVbyte_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 aVEnum
value, or headers for aVTable
.- 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 getSeverityGet 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 PVIdeally, 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, usegetStructureElement(RuntimePV, String, int)
. Ambiguous names will find the first structure with a matching name.- Parameters:
pv
- RuntimePV that should how a VTablename
- 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 PVPV must hold a VTable
- Parameters:
pv
- RuntimePV that should how a VTablerow
- 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 VTablename
- 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
- RuntimePVname
- Structure element nameindex
- 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 PVtimeout_ms
- Connection timeout in milliseconds- Returns:
- PV
- Throws:
java.lang.Exception
- on error- See Also:
releasePV(RuntimePV)
-
releasePV
public static void releasePV(RuntimePV pv)
- Parameters:
pv
- PV to release- See Also:
createPV(String, int)
-
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 PVIdeally, 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 PVvalue
- Value to writetimeout_ms
- Connection timeout in milliseconds- Throws:
java.lang.Exception
- If write cannot be performed.
-
-