The TPRI.BaseScreen class is the base class from which all user screens should be inherited. It provides the default functionality to automate communications with TSENTRY controller, access the data dictionary, and navigate between screens.

The TPRI.BaseScreen class should not be used by itself; it is intended solely for use as a base class for other screens.

The simplest custom user screens need only to inherit from the TPRI.BaseScreen class in order to take advantage of common functionality provided by the BaseScreen class.  However, if a custom screen wishes to perform some initialization as the screen is started (i.e. once the display is active and all contained objects are instantiated) it should override the StartScreen(..) method.  By the same token, if a custom screen wishes to implement some form of security, it should override the SecureScreen(..) method to modify itself for the current security level.

The following protected properties are exposed by the TPRI.BaseScreen class.

The following public methods are exposed by the TPRI.BaseScreen class.

Protected Overridable Function StartFromAsp( _
ByRef vobjWindow As Object _
) As Integer

Description:

Start active operation of the screen from an ASP web page.

Parameters:

vobjWindow

Window object of the Document Object Model (DOM) API in the browser.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should only be called by the container ASP to initiate activity on the screen.

Protected Overridable Function StartFromForm( _
ByRef vobjForm As Object, _
ByRef host As String, _
ByRef path As String, _
ByRef args As String _
) As Integer

Description:

Start active operation of the screen.

Parameters:

vobjContainer

Form object containing this screen.

host

Name or IP address of the host system to which the screen should connect..

path

Path to page on host.

args

String argument(s) to pass to screen for initialization/customization.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should only be called by the container form to initiate activity on the screen.

The following overridable methods are exposed by the TPRI.BaseScreen class.

Protected Overridable Function StartScreen( _
ByRef vobjContainer As Object _
) As Integer

Description:

Start active operation of the screen.

Parameters:

vobjContainer

Container object.  If screen is started from a web page, this will contain a reference to the Window object of the Document Object Model (DOM) API in the browser.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should be overridden by derived classes to provide custom startup functionality.

Protected Overridable Sub SecureScreen( _
ByVal securityLevel As Integer _
)

Description:

Secure the screen according to the specified security level.

Parameters:

securityLevel

Security level of the user.  This value is a bitmask of rights provided to the user.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should be overridden by derived classes to implement security on individual screens.

Protected Overridable Sub LinkTo( _
ByVal URL As String _
)

Description:

Navigate the current screen to a new page.

Parameters:

URL

URL of the new page.  Alternatively, passing the string '@MENU' links the screen back to the most recent menu and passing the string '@BACK' links the screen back to the previous page.

Return Value:

Zero for success; non-zero for failure.

Protected Overridable Sub LinkToMenu()

Description:

Navigate the current screen back to the most recent menu page.

Remarks:

Calling this method is equivalent to calling LinkTo("@MENU").

Protected Overridable Sub LinkToMenu()

Description:

Navigate the current screen back to the previous page.

Remarks:

Calling this method is equivalent to calling LinkTo("@BACK").

The following events are exposed by the TPRI.BaseScreen class.

Public Event OnLinkTo( _
ByVal page As String _
)

Description:

Indicates screen request to navigate to a different page.

Parameters:

page

Name of the next page to load.

Public Event ErrorTerminate()

Description:

Indicates the screen has reached a fatal error and must terminate.

The TPRI.BaseControl class is the base class from which all TSENTRY screen component controls are derived. It provides various functions in common use throughout the TSENTRY controls.

The TPRI.BaseControl class should not be used directly on any user page.  It is intended solely for use as a base class for other active objects.

The following protected properties are exposed by the TPRI.BaseControl class.

The following overridable methods are exposed by the TPRI.BaseControl class.

Public Overridable Sub OnInitialized()

Description:

Indicates that all control properties have been loaded from the screen.

Public Overridable Function GetActiveVars( _
ByRef varList() As String, _
ByRef tagList() As String _
) As Integer

Description:

Retrieve the variable/tag pairs to be requested from the data host on behalf of the object.

Parameters:

varList()

List to be populated with fully qualified variable names required by the BaseControl object.

tagList()

List to be populated with tags associated with each of the variables in the varList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned varList() and tagList() arrays.

Remarks:

Derived classes that wish to request variables from the host system should override this method to fill in the lists of variables and tags.  The method AddActiveVar(..) should be used to build these lists.

Public Overridable Function UpdActiveVar( _
ByVal tag As String, _
ByVal value As Object, _
ByVal timestamp As Date, _
ByVal quality As Integer _
) As Integer

Description:

Update the value of one of the active variables associated with the control.

Parameters:

tag

Tag of updated variable.

value

Value of updated variable.

timestamp

Date and time associated with this variable update.

quality

Data quality flags as passed from host.

Return Value:

Zero for success; non-zero for failure.

Remarks:

This method should not be called from any user code; it is intended solely for use by other TPRI-based objects.

If this method is overridden by a derived class, the default implementation of UpdActiveVar(..) should be called to ensure that the OnActiveUpd(..) event below is raised.

Public Overridable Function GetModifiedVars( _
ByRef tagList() As String, _
ByRef valList() As Object _
) As Integer

Description:

Retrieve list of variables and corresponding values that have been modified and must be written back to the data host.

Parameters:

tagList()

List to be populated with tags to be updated back to data host.

valList()

List to be populated with values associated with each of the tags in the tagList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned tagList() and valList() arrays.

Remarks:

This function is called by the manager to find all variables and values that should be written back to the server.  Any derived control should fill in the passed arrays with the appropriate variable/value pairs, reset any internal data-changed flags, reset its display to indicate that the variables have been sent to the server, and wait for the next update from the server as a confirmation that the updates took place.

Public Overridable Sub SetDisconnected()

Description:

Set the object into a disconnected state.

Remarks:

This function is provided as a callback to a derived class to reset the display of the object to indicate that it is no longer connected to live data.

The following public methods are exposed by the TPRI.BaseControl class.

Public Function IsInitialized() As Boolean

Description:

Indicates whether or not all control properties have been loaded from data stored in screen initialization.

Return Value:

Flag indicating whether or not all control properties have been loaded from data stored in screen initialization.

Public Function InitActiveVars( _
ByRef pManager As Object, _
ByRef iTscIdx As Integer, _
ByRef varList() As String, _
ByRef tagList() As String _
) As Integer

Description:

Initialize the BaseControl object and retrieve all variables and tags that are to be requested from the server on behalf of the object.

Parameters:

pManager

Reference to manager (typically TPRI.OpcMgr) object on parent form.

iTscIdx

Index of this BaseControl object on parent form.  This value is later used to identify this control in calls to various manager methods.

varList()

List to be populated with fully qualified variable names required by the BaseControl object.

tagList()

List to be populated with fully tags to be associated with each of the variables in the varList() array.

Return Value:

The number of variable/tag pairs to be requested.  This value should equal the number of elements in each of the returned varList() and tagList() arrays.

Remarks:

This method should not be called from any user code; it is intended solely for use by other TPRI-based objects.

Protected Sub AddActiveVar( _
ByRef varList() As String, _
ByRef tagList() As String, _
ByRef count As Integer, _
ByRef var As String, _
ByRef tag As String _
)

Description:

Add the specified variable name and tag to the supplied lists and increment the total count.

Parameters:

varList()

Array to which the variable name should be added.

tagList()

Array to which the variable tag should be added.

count

Total count of variable name/tag pairs in the above lists.

var

Name of variable to add to the list.

tag

Variable tag to add to the list.

Remarks:

Derived classes that wish to request variables from the host system should use this method to add variable/tag pairs to the supplied lists.

Public Shared Function FindControl( _
ByRef ctrlColl As Control.ControlCollection, _
ByRef name As String, _
ByRef type As String _
) As Integer

Description:

Find a control of the specified type and the specified name within a collection of controls.

Parameters:

ctrlColl

Collection of controls to search.

name

Name of control to search for.  If name = "*", search all names.

type

String containing type of control to search for.  If type = "*", search all types.

Return Value:

The index of the control in the collection, or -1 if not found.

Public Shared Function FindControl( _
ByRef ctrlColl As Control.ControlCollection, _
ByRef name As String, _
ByRef type As Type _
) As Integer

Description:

Find a control of the specified type and the specified name within a collection of controls.

Parameters:

ctrlColl

Collection of controls to search.

name

Name of control to search for.  If name = "*", search all names.

type

Type of control to search for.

Return Value:

The index of the control in the collection, or -1 if not found.

The following events are exposed by the TPRI.BaseControl class.

Public Event OnActiveUpd( _
ByVal Sender As Object, _
ByVal tag As String _
)

Description:

Indicates that a data variable has been updated from the host.

Parameters:

Sender

The source of the event.

tag

Tag of updated variable.

The TPRI.TextBox is used for live display and input of a scalar variable in global common.

The TPRI.TextBox control can operate in two modes: display-only mode and input mode.  In display-only mode, the value is continually updated as the value in global common changes, but the user is locked out from modifying the displayed value.  

In input mode, the text box is unlocked to allow the user to modify the displayed value.  Once the user starts to type in a new value, the background color of the display changes color and the active update of the value is put on hold to allow the user to finish changing the value.  Note that this new value is not sent back to the server until a call is made to the TPRI.OpcMgr object's WriteModified() method.  This is method is typically called in the click-handler of a button on the screen.  Once the data has been sent back to the server the background color of the control is changed back to the original color and a special string (property tResetStr, default “@@@”) is displayed until the new value is updated to the screen.  This provides verification that the variable in memory has been updated.

If the flag AutoSubmit is set to true the control automatically submit changes to the host when leaving the control or the Enter button is pressed.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value, a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Below are all of the properties of the TPRI.TextBox object.

The following events are exposed by the TPRI.TextBox class.

Public Function tTextReset() As String

Description:

If unlocked (tLocked = False), reset the display of the object to indicate that the value has not been modified.  If tResetToStr = True, reset the text displayed to the tResetStr string as well.

Return Value:

The string originally contained in the object.

Remarks:

This function is called while updating modified data back to the server.  It provides a single function to get the new value contained in the object and reset the object to wait for the next update.

The following events are exposed by the TPRI.TextBox class.

Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

The TPRI.Shape is used as a basic shape control (similar to the Shape control in VB6).  

The Shape object allows the designer to create the visual shape controls on the screens. It is a basic shape control without the specific logic ties to any other controls. It can be used as a base control to create the specific type of shape control.

The Shape control is configured by modifying the Shape, BorderOption, and FillOption properties.  Shape property provides the outline (shape) of the control. The BorderOption property provides the options of shape control border (width, color...). The FillOption property provides the options of shape control fill (color, style...)

Below are all of the properties of the TPRI.Shape object.

There are no public methods exposed by the TPRI.Shape class.

There are no public events exposed by the TPRI.Shape class.

The TPRI.ActiveShape is used to provide a graphical indication of the current value of a variable in global common.  

The TPRI.ActiveShape object allows the designer to divide the real number line into multiple ranges and assign a different shape and color for each range.  As the variable value is automatically updated to the control, the appropriate shape and color is displayed based on the range into which the current value falls.

• For example, the ActiveShape control can be used to display the current speed of a rolling mill.  If the speed is less than 10 feet per minute, the shape will display a red square with the text Stopped.  If the speed is greater than 10 feet per minute but less than 300 feet per minute, the display is a light blue square with the text Creep.  If the speed is greater than 300 feet per minute the display will be a green circle with the text Run.  Alternatively, the ActiveShape can be configured to display the current value of the speed variable rather than the text descriptions above.
  

If the current value of the variable is not actively being updated by the server, the ActiveShape will take on a separate display configuration to indicate that there is a communications problem.

The ActiveShape control is configured by modifying the ActiveShapeSetup property.  This property is actually an array of ActiveShapeSetup class objects, where each ActiveShapeSetup class contains all of the properties required to describe the display configuration for a range along the real number line.  

• Following the mill speed example above, there would be three ActiveShapeSetup objects in this array: one indicating the configuration when the speed variable is less than 10, one for when the speed is greater than 10 but less than 300, and a third for when the speed is greater than 300.
  

Each ActiveShapeSetup object has a property BoundMax, which defines the maximum value of the range.  The minimum value of the particular range is implied by the maximum value of the previous ActiveShapeSetup object in the array; hence the ranges of the real number line are defined in ascending order with each additional ActiveShapeSetup object in the array.  The two exceptions are the first and last ActiveShapeSetup objects in the array.  First, the minimum value of the range defined by the ActiveShapeSetup(0) object in the array (since there is no ActiveShapeSetup(-1) object in the array) is assumed to be negative infinity.  Second, the BoundMax property of the last ActiveShapeSetup object in the array is ignored and taken to be positive infinity.

Following would be the bounds defined for the speed example given above:

ActiveShapeSetup(0) BoundMax = 10
ActiveShapeSetup(1) BoundMax = 300
ActiveShapeSetup(2) BoundMax = 99999 (this is assumed to be +∞)

The ActiveShapeSetup object contains the following properties for configuring the display for a given range.  Note that the display configuration while disconnected (specified by the ActiveShape property DisconnectSetup) is also an ActiveShapeSetup object, so any of these properties can be modified to effect the display when communications are off-line.

The remaining properties of the ActiveShape class are as follows:

The following methods are exposed by the TPRI.ActiveShapeArray class.

The following events are exposed by the TPRI.ActiveShape class.

Public Event Click ( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Triggered when the control is clicked.

Parameters:

Sender

The source of the event.

e

The possible argument of the event.

The TPRI.ActiveShapeArray provides the methods, properties and events to create and access an array of TPRI.ActiveShape controls.

The following properties are exposed by the TPRI.ActiveShapeArray class.

Default Public ReadOnly Property Item ( _
ByVal index As Integer _
) As TPRI.ActiveShape

Description:

Access TPRI.ActiveShape controls in the collection by index.

Parameters:

index

Index of the ActiveShape object to access.

Return Value:

Indexed ActiveShape object.

The following methods are exposed by the TPRI.ActiveShapeArray class.

Public Sub Add ( _
ByVal value As TPRI.ActiveShape _
)

Description:

Add a TPRI.ActiveShape control to the collection.

Parameters:

value

ActiveShape object to add to the array.

The following events are exposed by the TPRI.ActiveShapeArray class.

Public Event Click ( _
ByVal Sender As System.Object, _
ByVal index As Integer _
)

Description:

Triggered when the control is clicked.

Parameters:

sender

The source of the event (i.e. the entire collection).

index

The index of the item in the collection that raised the event.

The TPRI.CmdButton object provides a button to link one screen to another.

The TPRI.CmdButton object is primarily configured using the tURL property.  This property specifies the name of the desired screen to which the HMI should be navigated following a click of the button.  Alternatively, tURL can also be set to one of the following predefined strings to provide special navigation functions:

• "@MENU"
  Link to the most recent menu.

• "@BACK"
  Link to the previous screen.

In actuality, when clicked the TPRI.CmdButton simply calls LinkTo(..) method from the TPRI.BaseScreen class, passing tURL as the method parameter.  As an alternative to using the TPRI.CmdButton object, a developer may instead choose simply to place a regular Windows button on his form, add a click handler to the button, and from that handler call one of the TPRI.BaseScreen screen navigation functions, such as LinkTo(..), LinkToMenu(), or LinkBack().

The following properties are exposed by the TPRI.CmdButton class.

There are no public methods exposed by the TPRI.CmdButton class.

The following events are exposed by the TPRI.CmdButton class.

Public Event Click( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Triggered when the control is clicked.

Parameters:

Sender

The source of the event.

e

The possible argument of the event.

The TPRI.CmdButtonArray provides the methods, properties and events to create and access an array of TPRI.CmdButton controls.

The following properties are exposed by the TPRI.CmdButtonArray class.

Default Public ReadOnly Property Item ( _
ByVal index As Integer _
) As TPRI.CmdButton

Description:

Access TPRI.CmdButton controls in the collection by index.

Parameters:

index

Index of the CmdButton object to access.

Return Value:

Indexed CmdButton object.

The following methods are exposed by the TPRI.CmdButtonArray class.

Public Sub Add ( _
ByVal value As TPRI.ActiveShape _
)

Description:

Add a TPRI.CmdButton control to the collection.

Parameters:

value

CmdButton object to add to the array.

The following events are exposed by the TPRI.CmdButtonArray class.

Public Event Click ( _
ByVal Sender As System.Object, _
ByVal index As Integer _
)

Description:

Triggered when the control is clicked.

Parameters:

sender

The source of the event (i.e. the entire collection).

index

The index of the item in the collection that raised the event.

The TPRI.ToggleButton is an on/off switch that connects to a Boolean variable in global common.

[PICTURE]

The active display of the TPRI.ToggleButton object consists of two main states: on (true, non-zero) and off (false, zero).  The display of each of these states is configured by setting the various object properties.

When the button is pressed, the current value of the associated global common variable is changed to the opposite state. For example, if the variable is currently true, its value is changed to false and vice-versa. The button is then disabled until the new variable value is updated back to the screen. This prevents accidental double clicks of the button from changing the variable back to its original value.

The following properties are exposed by the TPRI.ToggleButton class.

[TABLE]

The following public methods are exposed by the TPRI.ToggleButton class.

Public Function tValueReset() As Integer

Description:

Reset the display of the object to indicate that the button has not been clicked.

Return Value:

The value originally contained in the object.

Remarks:

This function is called while updating modified data back to the server.  It provides a single function to get the new value contained in the object and reset the object to wait for the next update.

Public Function isClicked() As Boolean

Description:

Indicate whether or not the button is currently clicked.

Return Value:

The current click state.

The following events are exposed by the TPRI.ToggleButton class.

Public Event Click( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Triggered when the control is clicked.

Parameters:

Sender

The source of the event.

e

The possible argument of the event.

Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

The TPRI.BarGraph is used as a live graphical display of up to two parallel array variables in global common.  The arrays are displayed as a set of bars growing up or down from a centerline.  For instance, this object is commonly used to display a feedback stress array for flatness control in metal rolling.

[PICTURE]

[PICTURE]

In general, the bar graph is configured according to the following.  

Number of bars

The horizontal extent of the display is divided into N bar slots, where N is equal to the tNumBars property.  Each of the bar slots is divided into a left and right bar; when active, the heights of each of the left bars correspond to the values in the first (right) array, while the heights of each of the right bars correspond to the values in the second (left) array.

Alternatively, the tNumBars property can be set to the name of a variable in global common.  In this case, the bar graph will retrieve the value of this variable and use it to configure the number of bars displayed.  

Horizontal display configuration

Both sets of bars can be configured to take up some fraction of each bar slot.  The property tLeftBarPercent specifies the percentage of each bar slot that the left bar should consume; the left bar is always assumed to start at the leftmost edge of the bar slot.  The property tRightBarPercent specifies the percentage of the bar slot that the right bar should consume; however, the starting point of the right bar is specified with the tRightBarOffset property.  If the sum of tRightBarOffset and tRightBarPercent exceeds 100, the right bar will be truncated as the rightmost edge of the bar slot.

Vertical display configuration

The displayed heights of each bar are specified relative to three TPRI.BarGraph properties.  The tEngUnitCenterLine property specifies the engineering units of the horizontal centerline of the graph.  This is line from which each of the bars will grow up or down.  If the array element value associated with a given bar is less than tEngUnitCenterLine, the bar will be drawn down from the centerline, and conversely, if the value associated with a bar is higher than tEngUnitCenterLine, the bar will be drawn up from the centerline.  This allows the bar graph to be configured to display deviations from a nominal non-zero value.  The top and bottom vertical limits of the graph are specified by the tEngUnitTop and tEndUnitBottom properties; array element values outside this range will display bars extending to the limits of the display.

If forcing any of these three properties to a fixed value is not appropriate for the display, there are two alternatives.  First, the property can be set to the name of a variable in global common whose value will be retrieved at runtime and used as the associate engineering value.  This allows the display to be programmatically controlled by values in global common.  Second, the property can be set to a special string consisting of an ampersand '@' followed by the name of a text box on the screen; in this case the value entered into the text box will be used as the associate engineering value.  This allows the HMI user to configure the display at runtime as he pleases.

Scale display configuration

The property YTickSpacing is defined as the spacing (in engineering units) between the y-axis ticks annotating the graph.  A tick is a short horizontal line drawn to the left of the graph together with a label indicating the corresponding y-axis position.  A property YTickSpacing value less than or equal to zero indicates that no ticks should be drawn.  A positive value indicates that ticks and labels should be drawn at integer multiples of the spacing value between the lower and upper limits of the graph.  The default value is zero.

The following properties are exposed by the TPRI.BarGraph object.

[TABLE]

The following methods are exposed by the TPRI.BarGraph class.

Public Function fSetVals( _
ByRef afValue As Object _
) As Object

Description:

Set new values for all left and right bars (same value for left and right).

Parameters:

afValue

Tag of updated variable.

Return Value:

Zero for success; non-zero for failure.

The following events are exposed by the TPRI.BarGraph class.

Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

A TPRI.CoverageBar control is a horizontal bar illustrating the location of a closed section within a wider region.  Typically a TPRI.CoverageBar is tacked on below a bar graph to depict which bars are to be considered ‘valid’.  For example, the CoverageBar may be used on a rolling mill to indicate which zones of a flatness bar display are covered by the strip itself.

[PICTURE]

At run-time, the TPRI.Coverage bar is a display-only object representing a contiguous range of values on the real number line.  The left and right edges of the horizontal bar represent the lower (or most negative) and the upper (or most positive) limits of this range.  Within this displayed range there is assumed to be a single range of values that are to be considered valid; these values are drawn in a different color to visually indicate the span of values that is valid.  In the image above, this valid range is drawn in blue, while the total displayed range is drawn in gray.

At design time, each of the four limits of the two ranges (left and right limits of displayed range, left and right limits of valid range) is set as a property of the object and can be specified in one of three ways.  First, the property can be hard-coded to the actual numeric value.  Second, the property can be set to the name of a variable on the host system that contains this value; at run-time this value will be actively retrieved and updated from the server.  Third, the property can be set to the name of a TPRI.TextBox [LINK] object elsewhere on the screen prepended with an ampersand ('@') character that contains the specified value; this allows the HMI user to configure the display himself at run-time.

The following properties are exposed by the TPRI.CoverageBar class.

[TABLE]

The following public methods are exposed by the TPRI.CoverageBar class.

Public Sub SetLeftData( _
ByVal afValue As Object _
)

Description:

Set the value associated with the left side of the covered section.

Parameters:

afValue

Value to be associated with the left side of the covered section.

Public Sub SetLeftEdge( _
ByVal afValue As Object _
)

Description:

Set the value associated with the left side of the entire bar.

Parameters:

afValue

Value to be associated with the left side of the entire bar.

Public Sub SetRightData( _
ByVal afValue As Object _
)

Description:

Set the value associated with the right side of the covered section.

Parameters:

afValue

Value to be associated with the right side of the covered section.

Public Sub SetRightEdge( _
ByVal afValue As Object _
)

Description:

Set the value associated with the right edge of the entire bar.

Parameters:

afValue

Value to be associated with the right edge of the entire bar.

There are no events exposed by the TPRI.CoverageBar class.

The TPRI.LogMsg object actively displays all messages that are logged to a TSENTRY log message queue.  For instance, the bottom half of the NtRtMgr screen uses this object to display messages from the default ‘LogMsg’ queue.

[PICTURE]

Active operation of the TPRI.LogMsg object is fully automated by the screen framework provided that the user screen is derived from the TPRI.BaseScreen class and that it contains a TPRI.OpcMgr object.  

Configuration of a TPRI.LogMsg control consists mainly of setting the desired LogMsg queue name in the LogMsgName property.  This string must match one of the LogMsg queues defined in the system logs initialization file [LINK].  Once configured, the TPRI.LogMsg object will display all messages logged to the specified queue.

Below is a list of all the properties that are exposed by the TPRI.LogMsg class.

[TABLE]

There are no public methods exposed by the TPRI.LogMsg class.

There are no public events exposed by the TPRI.LogMsg class.

The TPRI.ComboBox is used as a live display and input of global common variables that are defined only to have a finite set of allowable values.  

[PICTURE]

The TPRI.ComboBox is similar to the TPRI.TextBox [LINK] in that it displays the current value of a variable in global common and operates in two possible modes, read-only mode and input mode.  However, whereas the TextBox is a text-entry box that allows the user to enter any new value, the ComboBox is a drop down list that allows the user only to select a new value from the presented list of choices.  Moreover, since many times the HMI user does not think of the list of choices in terms of numerical values but instead in conceptual possibilities, the ComboBox allows the designer to associate a text string with each of the possible variable values; these strings can be displayed at run-time instead of the actual values themselves.

For example, suppose there is a variable in global common representing the current mode of a controller: automatic, manual, or off.  The variable itself is an integer, and is defined such that automatic = 2, manual = 1, and off = 0.  The TPRI.ComboBox object therefore limits the user choices in the drop down box to ‘Auto’, ‘Manual’, or ‘Off’, though it internally manages updating the variable value on the host to a 2, 1, or 0, respectively.

When the TPRI.ComboBox object is initially connected to the host, it displays the descriptive string associated with the current value of the variable in global common.  If this value is changed by some other process, the display will be updated accordingly to display the new descriptive string.  If the user makes a new selection from the drop down list, however, the background color of the display changes color and the active update of the value is put on hold while the user finalizes his selection.  The new value is not sent back to the server until a call is made to the TPRI.OpcMgr object's WriteModified() method.  This is method is typically called in the click-handler of a button on the screen.  Once the data has been sent back to the server the background color of the control is changed back to the original color and a special string (property tResetStr, default “@@@”) is displayed until the new value is updated to the screen.  This provides verification that the variable in memory has been updated.

In the case where the current value of the variable on the host is not in the list of available values defined in the TPRI.ComboBox object, the object will display “{XXX}” where XXX is the current value of the variable.

If the flag AutoSubmit is set to true the control automatically submit changes to the host when a new item is selected from the list.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value, a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Below are all of the properties of the TPRI.ComboBox object.

[TABLE]

The following public methods are exposed by the TPRI.ComboBox class.

Public Function ConvertStrToNum( _
ByVal StrText As String _
) As String

Description:

Retrieve the value associated with the specified descriptive string.

Parameters:

StrText

Descriptive string.

Return Value:

Variable value associated with the descriptive string.

Public Function ConvertNumToStr( _
ByVal StrNum As String _
) As String

Description:

Retrieve the descriptive string associated with the specified variable value.

Parameters:

StrNum

Variable value.

Return Value:

Descriptive string associated with the passed value.

The following events are exposed by the TPRI.ComboBox class.

Public Event Change( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Indicates the selected value has been changed.

Parameters:

Sender

The source of the event.

e

Event argument.  This will always be nothing.

Public Event OnValidate( _
ByVal Sender As System.Object, _
ByRef Cancel As Boolean _
)

Description:

The current selection is being validated.

Parameters:

Sender

The source of the event.

Cancel

Flag indicating whether or not the selection is valid.

Remarks:

This event will be raised when the current selection must be validated.  The event handler should set the Cancel parameter according to whether or not the current selection is valid.

Public Event ErrorTerminate( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The event is raised when a serious error has occurred in the control.

Parameters:

Sender

The source of the event.

e

Event argument. This will always be nothing.

The TPRI.OpcMgr object is responsible for automating all active variables on a screen.  On initialization it searches for any objects on the screen that are derived from TPRI.BaseControl and requests from each of them a list of variables that should be retrieved from the host system.  Then as these variables are updated from the server to the client, the OpcMgr object passes these updates back to each of the associated BaseControl objects.

[PICTURE]

In most cases, all operation of the TPRI.OpcMgr object is fully automated by the TPRI.BaseScreen framework. While connected to the data host, the OpcMgr object will display green and indicate the date/time of the most recent variable update from the host.  Before the initial connection and any time the OpcMgr object disconnects from the host, the display will turn orange and will indicate the date/time of the most recent connection attempt; the OpcMgr object should attempt to reconnect every 3-5 seconds.  Finally, there are two cases in which the OpcMgr object will turn red:

If the OpcMgr object is unable to find any variables configured on the screen for retrieval from the server, the object will turn red and display a message indicating that there are no OPC items configured.

If the OpcMgr object encounters an unrecoverable error the object will turn red and display an error indication.  Details of the error can be viewed by holding down the control key and left clicking on the object.

There are some situations where a screen may want to receive variable updates for data that it wishes to use for its own purposes rather than for display in one of the existing active objects.  To accomplish this, the screen should do the following:

Add an event handler for OnRestart(..).  Inside this handler make appropriate calls to the AutoAddItem() method to add all variables that the screen would like to receive directly.

Add an event handler for OnDataUpdate(..).  Inside this handler process individual variable updates.

Optionally add an event handler for OnDisconnect(..).  Place any code to reset the visual display of the screen to indicate that the screen is not connected to the data host.

The following public properties are exposed by the TPRI.OpcMgr object.

[TABLE]

The following methods are exposed by the TPRI.OpcMgr object.

Public Function StartComm( _
ByRef hostName As String _
) As Integer

Description:

Start communications with a host.

Parameters:

hostName

Name or IP address of the data host.

Return Value:

Zero for success; non-zero for failure.

Remarks:

By default, the TPRI.BaseScreen implementation looks for all TPRI.TrendCom objects and calls this method to automatically initialize trending.  This is disabled if the tAutoStart property is set to False.

Public Function AutoAddItem( _
ByRef fullItemName As String, _
ByRef tagName As String _
) As Integer

Description:

Add a variable to the list of variables retrieved from the host.

Parameters:

fullItemName

Name of variable to be added.

tagName

Tag to associate with this variable.

Return Value:

Zero for success; non-zero for failure.

Public Function WriteItem( _
ByRef tagName As String, _
ByRef value As Object _
) As Integer

Description:

Write a value back to the specified variable on the host.

Parameters:

tagName

Tag of variable to be written.

value

New value of variable.

Return Value:

Zero for success; non-zero for failure.

Public Function WriteModified( _

) As Integer

Description:

Find and write all modified variables on the screen back to the host.

Return Value:

Zero if no error, nonzero if error.

Public Function RemoveItem( _
ByRef tagName As String _
) As Integer

Description:

Remove an existing variable from the list of variables retrieved from the host.

Parameters:

tagName

Tag of variable to be written.

Return Value:

Zero for success; non-zero for failure.

Public Function RefreshAll( _
) As Integer

Description:

Request the server to refresh all data values back to the client.

Return Value:

Zero for success; non-zero for failure.

The following methods should not be called from an application screen.  They are used by other active controls to configure variables associated only with those controls.

Public Function AutoAddTscItem( _
ByRef fullItemName As String, _
ByRef tscIdx As Integer, _
ByRef tag As String _
) As Integer

Description:

Add a variable owned by a specific control to the list of variables retrieved from the host.

Parameters:

fullItemName

Name of variable to be added.

tscIdx

Index of calling control.

tagName

Tag to associate with this variable.

Return Value:

Zero for success; non-zero for failure.

Public Function WriteTscItem( _
ByRef tscIdx As Integer, _
ByRef tag As String, _
ByRef value As Object _
) As Integer

Description:

Write a value back to the specified variable on the host.

Parameters:

tscIdx

Index of calling control.

tag

Tag of variable to be written.

value

New value of variable.

Return Value:

Zero for success; non-zero for failure.

Public Function RemoveTscItem( _
ByRef tscIdx As Integer, _
ByRef tag As String _
) As Integer

Description:

Remove an existing variable from the list of variables retrieved from the host.

Parameters:

tscIdx

Index of calling control.

tag

Tag of variable to be written.

Return Value:

Zero for success; non-zero for failure.

The following events are exposed by the TPRI.OpcMgr object

Public Event OnDataUpdate( _
ByVal Sender As System.Object, _
ByVal tag As String, _
ByVal value As Object, _
ByVal timestamp As Date, _
ByVal quality As Integer _
)

Description:

Indicates that a data variable has been updated from the host.

Parameters:

Sender

The source of the event.

tag

Tag of updated variable.

Value

Value of updated variable.

timestamp

Date and time associated with this variable update.

quality

Data quality flags as passed from host.

Public Event OnClientMsg( _
ByVal Sender As System.Object, _
ByVal err As Integer, _
ByVal msg As String, _
)

Description:

Passes a message to the client.

Parameters:

Sender

The source of the event.

err

Error number.

msg

Error description.

Public Event OnRestart( _
ByVal Sender As System.Object, _
)

Description:

Indicates that communications with the host have restarted.

Parameters:

Sender

The source of the event.

Public Event OnDisconnect( _
ByVal Sender As System.Object, _
)

Description:

Indicates that the connection to the host has been disconnected.

Parameters:

Sender

The source of the event.

The TPRI.OpcCom object is an OPC communications client for accessing variables in global common on the host.  

The TPRI.OpcCom class is intended solely for internal use by the other TSENTRY objects.  For access to variables in global common exposed by the OPC server on the host, see the TPRI.OpcMgr [LINK] class.

There are no properties exposed by the TPRI.OpcCom class for public use.

There are no public methods exposed by the TPRI.OpcCom class for public use.

There are no events exposed by the TPRI.OpcCom class for public use.

The TPRI.DataSetInfo is used to create, load, update and delete data set configuration files.

[PICTURE]

[TABLE]

The TPRI.DDVarSelect object is used to select a variable from the data dictionary and display its name to the user.

[PICTURE]

[TABLE]

The TPRI.DataDict object is used to access the data dictionary on the controller.

[PICTURE]

[TABLE]

The TPRI.HMI.Controls.TrendCtrl object is used to select variables for trending as well as to monitor the values of each of these variables during trending.  The main display of the TrendCtrl object is a grid of information displaying information about the entire set of trended variables.  

[PICTURE]

[TABLE]

Clicking one of the variable index buttons on the Trend Setup form will display a special window for inserting and deleting variables to and from the list of trended variables.

Answer each visible question before clicking the OK button.  More questions will become visible when the previous question has been answered.

Several rows can be deleted from the trend variable list by selecting the Delete option on the above form, which then displays a second question asking how many rows to delete..

Now the user inserts 3 in the textbox to answer the question “How many rows”?  All questions are answered, so the OK button can be pressed.  Rows are deleted starting at the row whose button was initially pressed to get to this screen.  The rows below the deleted section are moved up in the list.

If instead the user wishes to insert rows, again they are inserted starting at the row whose button was initially pressed.  This form also allows the user to insert arrays of variables into the trend list.

The first thing the user needs to do is enter the array variable.  He can simply type it in or click the ‘*’ button to bring up the data dictionary form.  After entering in a variable, the user will need to specify which elements they want trended.  The example array variable is mycommon.mystruct[0-3].myvar[0-5]. This will insert the following 24 array variables:

mycommon.mystruct[0].myvar[0]
mycommon.mystruct[0].myvar[1]
mycommon.mystruct[0].myvar[2]
.
.
mycommon.mystruct[0].myvar[5]
mycommon.mystruct[1].myvar[0]
mycommon.mystruct[1].myvar[1]
.
.
mycommon.mystruct[1].myvar[5]
mycommon.mystruct[2].myvar[0]
.
.
mycommon.mystruct[2].myvar[5]
mycommon.mystruct[3].myvar[0]
.
.
mycommon.mystruct[3].myvar[5]

Next, the user has the option of assigning a label to each trend variable.  This field can be left blank for no label.  In this example, the user entered ‘My Trending Array Variable [$1$, $2$]’.  As the individual trend variable labels are populated, the first element index will replace the $1$, and the second element index will replace the $2$.  In this case, the following array labels will be inserted.

My Trending Array Variable [0,0]
My Trending Array Variable [0,1]
My Trending Array Variable [0,2]
.
.
My Trending Array Variable [0,5]
My Trending Array Variable [1,0]
My Trending Array Variable [1,1]
.
.
My Trending Array Variable [1,5]
My Trending Array Variable [2,0]
.
.
My Trending Array Variable [2,5]
My Trending Array Variable [3,0]
.
.
My Trending Array Variable [3,5]

If the user enters a label without the dollar signs, this same label will be added to all variables.

Next, select the color options.  There are three options.  

• Each variable’s color should be the same – this option displays a button that will be the line color.  Click the button to select a different color.

• Each variable’s color should be chosen from a set of commonly used colors – this option will only apply colors from a set of about 15 commonly used colors.  This option will ensure that the line colors are not similar shades of the same color.

• Each variable’s color should be assigned randomly – this option will randomly assign each color.

Finally, the user will select the line type and axis.  After all of this is completed, the user can click OK to insert the array variable.

The TPRI.TrendPlayback object is used to control the playback of trends on a screen.  It provides buttons to run the trend display forward in time, backwards in time, pause and restart trends, and to step through the trend data.

The TPRI.TrendPlayback object is intended as an enhancement to a TPRI.TrendCtrl object on a screen.  Individual TrendCtrl objects may be associated with a TrendPlayback object by setting the ttpPlayback property of the TrendCtrl object to the name of the TrendPlayback object on the screen.  Doing so forces the TrendCtrl object to use the associated TrendPlayback object to control how trends are played back on the page via the buttons on the TrendPlayback object. Each of these buttons and fields are described in the following table.

Button or Field	Function
	The start and end times allow the user to narrow down the times for which data will be displayed.  This is described in more detail below.
	Play data forwards in time as fast as possible.  For most practical purposes, this is the best option for viewing real-time data, as the trend will be displayed as soon as data is available.
	Play data backwards in time as fast as possible.  Effectively, this rewinds the data as fast as the communications with the trend host will allow.
	This entry specifies the playback speed when either the single arrow buttons immediately adjacent to this text box are selected.  For example, a value of 1 means that the data will played back at the same speed at which is was recorded, whereas a value of 2 means that data will be played back at twice the speed it was recorded.
	Play data forwards in time at the playback speed specified in the text box to the left of this button.
	Play data backwards in time at the playback speed specified in the text box to the left of this button.
	Pressing this button restarts trend playback by flushing all data and reconnecting to the trend host.
	Pressing this button toggles the pause mode on and off.  While paused, trend playback is suspended so that no more new data is pushed onto the trend graph.
	This entry specifies the amount of time (in seconds) to step forwards or backwards when either of the stepper buttons to the left of right of this text box are pressed.
	Pressing this button causes the trend display to step forward in time by the number of seconds specified in the step time text box above.  Once the specified number of seconds of data has been pushed onto the trend, trend playback will pause itself to stop further updates.
	Pressing this button causes the trend display to step backward in time by the number of seconds specified in the step time text box above.  Once the specified number of seconds of data has been pushed onto the trend, trend playback will pause itself to stop further updates.

By default, the trending system automatically decides on the starting and ending times for trends. However, by checking either the Start or End check boxes the user can manually specify desired starting and ending times.  This is particularly useful when reviewing large historical trends that contain only a short period of interesting information; rather that wait for the trend to play all the way from the beginning to the point of interest, the user can simply enter the time at which trending playback should begin.  By the same token, if the user wants trending playback to stop at a specific time in the data, he check the appropriate box, enter the time, and the trending system will stop once it hits that point in the data.  

There are no properties exposed by the TPRI.TrendPlayback object for public use; all properties are intended solely for use by other TSENTRY objects.

There are no public methods exposed by the TPRI.TrendPlayback object.

The following events are exposed by the TPRI.TrendPlayback object.

Public Event OnChangePlaybackMode( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The current playback mode has changed.

Parameters:

Sender

The source of the event.

e

Event argument.

Public Event OnPlaybackRestart( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

Playback has been restarted.

Parameters:

Sender

The source of the event.

e

Event argument.

The TPRI.DataSetInfo is used to create, load, update and delete TrendSet configuration files.

A TrendSet contains all of the configuration information associated with a customized TrendX display.

Once placed on a screen, a TPRI.DataSetInfo object must be initialized in code with an appropriate call to the Initialize(..) method.  This configures the DataSetInfo object to retrieve and save data set files to the host system.

At runtime, the text box on the object display indicates the currently loaded TrendSet.  Each of the buttons to the right perform some operation on the current data set:

Pressing the Load button above presents the Load Data Set form.

This form allows the user to select and load a TrendSet file from the host.  These files transferred to and from the host through the NtRtInfo service, and are stored on the host in the NtRtInfo-based shared folder whose name is specified ShareName property with an extension specified by the Extension property.  The default values for these properties are DataSet and TrendSet, respectively.

The following properties are exposed by the TPRI.DataSetInfo class.

The following public methods are exposed by the TPRI.DataSetInfo object.

Public Sub Initialize( _
ByVal host As String, _
ByVal page As String, _
Optional ByVal loadLast As Boolean = True _
)
Description:
Initialize the object.
Parameters:
host
Name of the host to which the object should connect.
page
Name of parent page. This is used for storing the most recently used data set associated with a particular page.
loadLast
Flag to load the most recently used data set.
Remarks:
This function must be called before the object can be used to access a data set.
 
Public Function LoadDataSet( _
Optional ByVal dsName As String = "" _
) As Integer
Description:
Load the specified data set.
Parameters:
dsName
Name of the data set to load.  If none is specified the Load Data Set form is displayed to allow the user to select the desired data set file.
Return Value:
Zero for success; non-zero for failure.
 
Public Function SaveDataSet( _
Optional ByVal fileExt As String = "..." _
) As Integer
Description:
Save the current data set.
Parameters:
fileExt
File extension to append to the data set name. If none is specified (or default "..."), no file extension will be appended.
Return Value:
Zero for success; non-zero for failure.
 
Public Sub ResetDataSet()
Description:
Reset the current data set.
 
Public Function DeleteDataSet( _
Optional ByVal dsName As String = "" _
) As Integer
Description:
Delete the specified data set.
Parameters:
dsName
Name of the data set to delete.  If none is specified the current data set is deleted.
Return Value:
Zero for success; non-zero for failure.
 
The remaining public methods are intended solely for use by the other TSENTRY objects.

The events for this class are not yet documented.

The TPRI.TrendSrcSelect object is used to allow the user to select the current trend source on a screen.  Trend sources include all real-time trend sources (typically TrendGsm for data trended from global common) as well as all historical trend data files on the host system.

Once placed on a screen, the TPRI.TrendSrcSelect object must be initialized in code with appropriate calls to the Initialize(..) and AddTrendSrc(..) methods.  These calls allow the object to configure the Trend Source Selection form, which is accessed at runtime by pressing the TrendSrc button on the object.

The top half of this form lists of the all available Realtime Trending trend sources.  Typically this will contain only TrendGsm, which refers to data recorded from variables in global shared memory.

The bottom half of this form lists all of the available historical Trigger Trend Files available.  These files are exposed through the Trigger share on the host system.

Double clicking on any of the available trend sources selects that source as active and closes the Trend Source Selection form.

The following properties are exposed by the TPRI.TrendSrcSelect class.

The following public methods are exposed by the TPRI.TrendSrcSelect class.

Public Sub Initialize( _
ByRef hostName As String _
) As Integer

Description:

Initialize the object for a specific host.

Parameters:

hostName

Name or IP address of the data host.

Public Sub AddTrendSrc( _
ByVal tsName As String _
) As Integer

Description:

Add a trend source to the list of available reat-time trend sources.

Parameters:

tsName

Name of trend source to add.

The following events are exposed by the TPRI.TrendSrcSelect class.

Public Event OnChangedTrendSrc( _
ByVal Sender As System.Object, _
ByVal e As System.EventArgs _
)

Description:

The current trend source has been changed.

Parameters:

Sender

The source of the event.

e

Event argument.

The TPRI.TrendCom object is responsible for automating communications for all trends on a screen.  On initialization it searches for any TrendCtrl objects on the screen and begins to request data on their behalf from the host system.  As responses are received, the TrendCom object feeds the data back to the appropriate TPRI.TrendCtrl [LINK] objects.

In most cases, all operation of the TPRI.TrendCom object is fully automated by theTPRI.BaseScreen [LINK] framework. While connected to the data host, the TrendCom object will display green and indicate the date/time of the most recent trend data response from the host.  Before the initial connection and any time the TrendCom object disconnects from the host, the display will turn orange and will indicate the date/time of the most recent connection attempt; the TrendCom object should attempt to reconnect every 3-5 seconds.  Finally, there are three cases in which the TrendCom object will turn red:

If the TrendCom object has not been supplied a hostName to which it should connect, the object will turn red and display a message indicating that there is no host specified.

If the TrendCom object is unable to find any TrendCtrl objects on the screen or none of the TrendCtrl object specify any variables to be trended, the object will turn red and display a message indicating that there are no trend items configured.

If the TrendCom object encounters an unrecoverable error the object will turn red and display an error indication.

The following public properties are exposed by the TPRI.TrendCom class.

The following methods are exposed by the TPRI.TrendCom class.

Public Function StartComm( _
Optional ByRef sHostName As String = "" _
Optional ByRef sPathDir As String = "" _
) As Integer

Description:

Start communications with a host.  

Parameters:

sHostName

Name or IP address of the data host.

sPathDir

Path/directory of container page on host.  This is used to configure the location of the data dictionary contained in any TrendCtrl object this control finds on the page.

Return Value:

Zero if no error, nonzero if error.

Remarks:

The first time this method is called both parameters must be passed in order to initialize the component. These parameters are saved internally, so following requests need not pass the parameters again.

By default, the TPRI.BaseScreen implementation looks for all TPRI.TrendCom objects and calls this method to automatically initialize trending.  This is disabled if the tAutoStart property is set to False.

There are no events exposed by the TPRI.TrendCom class.

The TPRI.TriggerEd object is used to create, edit, activate, and deactivate trigger configuration files for the historical trending system.

The TPRI.TriggerEd object acts purely as a run-time user interface for interacting with the historical trend system.  The buttons along the top row of the screen allow the user to create a New trigger definition, Load an existing trigger, Save the current trigger, Activate the current trigger, or Deactivate the current trigger.

Below the row of buttons are a set of fields to configure general information about the trigger.

Below the general information fields are two columns of variables.  The left column of Trigger Variables allows for specification of all variables that define the trigger.  Each line in this list defines a Boolean operation; the trigger is considered active when every one of these operations is satisfied.  Each operation is defined by a variable name, a comparison operator and comparison value selected; hence the operation is considered true when the associated variable on the host system meets the specified criterion.  In order to facilitate variable selection, each of the variable name entry fields are TPRI.DDVarSelect [LINK] objects; clicking on the '*' in the upper right hand corner of the text box will load the data dictionary browser form.

The right column of variables, the Trend Variables, specifies each of the variables that should be recorded while the trigger is considered active.  Like the Trigger Variable names, the data dictionary browser can be loaded by pressing the '*' in the upper right hand corner of any of the Trend Variable entry text boxes.

Below are all of the properties of the TPRI.TriggerEd object.
 

There are no public methods exposed by the TPRI.TriggerEd object.

There are no events exposed by the TPRI.TriggerEd object.

The TPRI.TriggerStat object is used to display the current status of each trigger that has been activated on the TSENTRY historical trend subsystem.

Once placed on a screen, the TPRI.TriggerStat object must be initialized in code with appropriate calls to the Initialize(..) method.  Once initialized, the TriggerStat object will continually check for updates to the trigger status file on the host and display all available information in the status box.  The trigger status file, periodically rewritten by the TrendMgr process, is exposed through the Trigger share on the host system as /Trigger/Def/TrigStat.txt.

There are no public properties exposed by the TPRI.TriggerStat object.

The following public methods are exposed by the TPRI.TriggerStat class.

Public Sub Initialize( _
ByRef hostName As String _
) As Integer

Description:

Initialize the object for a specific host.

Parameters:

hostName

Name or IP address of the data host.

There are no events exposed by the TPRI.TriggerStat object.

The TPRI.RpsEditor class is used to present rule configuration data in an editable tree view format.

Each of the root nodes in the tree refers to an individual rule and contains sub-nodes listing each of the parameters and associated values for the rule.  

By default, the tree view initializes itself by loading the active rules configuration file from the host system.  This file contains the configurations of each of the rules that are active on the host system and is periodically updated by the rules manager process with the latest data. This file is exposed on the host via a network share.

The rule editor can also open configuration files of rules that are not active on the host system. When these rules are displayed in the rule editor, the rule name displayed as the label on the root node is appended with the full path to the rule file (as shown above).

Parameter values can be modified by single-left-clicking on the parameter value, which will bring up an edit box that allows for text entry.  

Pressing the enter key while editing or clicking outside of the edit box will validate the user entry; if it is valid the rule parameter will be changed, while if there is a problem the user will be prompted and asked to correct the value.

Editing a criteria or action value brings up a special text edit box that provides access to the Data Dictionary [LINK] by right clicking in the edit box.

Once any rule parameter has been modified from its original value, the rule name displayed as the label on the root node is appended with an asterisk to indicate that it has been modified.

For more in-depth information about the data dictionary, refer to Data Dictionary [LINK].

A rule can be saved to a file on disk and stored for later reference by choosing either of the first two save options from the popup menu.  The Save Rule option simply saves the rule to its current file, while the Save Rule As... option saves the rule under a different name or into a different folder.

Before the rule can be saved to disk, though, it must be validated to ensure that each of its parameters is formatted correctly and contains valid data.  If validation is not successful the user will be prompted with a list of problems and the rule display will be populated with a red Local Errors node that contains a duplicate of this list.

For instance, an improperly formatted VariableCondition statement containing unmatched parentheses causes a fatal validation error because the condition cannot be properly parsed.  On the other hand, a properly formatted VariableCondition statement that contains a variable name that cannot be located in the data dictionary only causes a non-fatal validation warning, as this rule can still be properly parsed by the rules manager process.

If only validation warnings are encountered, and there are no fatal validation errors, the user has the option of continuing with the save process or canceling the save to fix the problems; however, if any fatal errors are encountered the save cannot continue.

If a rule is currently active on the host, it can only be saved to the host share under its current name by re-activating it at the same time (see below).  The user may however choose to save the rule to a different folder under the same name.

A rule can be activated on the host by right clicking anywhere on the rule configuration and choosing the Save and Activate Rule option from the popup menu.  The effect of this is twofold.  First, the rule configuration is saved to the host share as the file MyRule.rpsRule, where MyRule corresponds to the rule name.  All activated rules have a duplicate of their rule configuration stored on the host network share as such as a backup of the rule configuration.  Second, a rule command file is written to the host share, which indicates to the rule manager process that the rule should be added to the system.  If the rule is already activated on the system, the manager process will replace the existing rule rather than adding a new one.  Once a rule is activated its file name is removed from the rule label in the tree view.

An active rule can be deactivated and removed from the host system by right clicking anywhere on the rule configuration and choosing the Deactivate Rule option from the popup menu.  This writes a command file to the host share that instructs the manager process to remove the rule from the active list.  However, because the rule was saved to a separate file before it was activated, the rule configuration can still be retrieved from the host share.

Various other rule operations are available from the popup menu available by right-clicking anywhere in the tree display.

The available items on this menu are as follows:

If the rule configuration as loaded contains status information about the rule, these entries will be displayed in the Status node under the rule node.  If the rule is indicating an error, this node, as well as the root rule node, will be colored red to indicate that attention is required.  In this case typically the Status node contains some information about the error.

The following properties are exposed by the TPRI.RpsEditor class.

The following public methods are exposed by the TPRI.RpsEditor object.

Public Function Initialize( _
ByVal sHostName As String, _
ByVal sPathDir As String _
) As Integer

Description:

Initialize object and begin communications with a host.

Parameters:

sHostName

Name or IP address of the data host.

sPathDir

Path/subdirectory of page on host.

Return Value:

Zero for success; non-zero for failure.

Public Function RefreshRules( _
ByVal bForceRefresh As Boolean _
) As Integer

Description:

Refresh the rules display from the configuration file on the host system.

Parameters:

bForceRefresh

Flag to force a complete refresh of the display.  If this flag is false then the display will only be updated if the rules configuration has changed.

Return Value:

Zero for success; non-zero for failure.

There are no events exposed by the TPRI.RpsEditor object.

The TPRI.HMI.Controls.NumericUpDown is used for live display and update of a scalar variable in global common.

The TPRI.HMI.Controls.NumericUpDown can operate in two modes: display increment value mode (property DisplayIncrement = True) and display variable value mode (property DisplayIncrement = False). In display variable value mode, the control displays live value specified by the ProbeSource property. In display increment mode, the control displays increment value specified by the Increment property. When the up/down buttons are clicked the live value specified by the ProbeSource property is updated by adding/subtrsacting a value specified by the Increment property. The value will not be updated to any value above maximum value or below minimum value specified.

If the variable specified by the ProbeSource property is not numeric data type, a special string “Invalid variable type” is displayed.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value, a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Below are all of the properties of the TPRI.HMI.Controls.NumericUpDown class.

The following methods are exposed by the TPRI.HMI.NumericUpDown class.

Public Overrides Sub DownButton()

Description:

Overrides System.Windows.Forms.NumericUpDown public subroutine DownButton() to decrement variable manually.

Public Overrides Sub UpButton ()

Description:

Overrides System.Windows.Forms.NumericUpDown public subroutine UpButton () to increment variable manually.

None

The TPRI.HMI.Controls.LevelDisplay control represents a scalar value in a graphical format. Intended to show the tilt level of a physical object, this control monitors a singular scalar value and displays the value as a colored wedge. The current numeric value is always indicated at the scale on the far right edge of the graph region.

• Typical Example with the Upper/Lower

• Limits = +100/-100 and current value = 60.

The “x-axis” of this control represents the zero point of the scalar value. To display tilt, a line is drawn through the center of the x-axis. The right-most point of the line is set to the current numeric value. The left-most end-point is set to the negative of the current numeric value. The area between the line and x-axis is filled with a solid color in order to make the angle more visible. As the variable value increases or decreases, the angle of the line increases or decreases accordingly. The slope of the line is positive when the variable value is positive. The slope of the line is negative when the variable value is negative.

Scaling and Upper and Lower Limits

A scale is displayed on the right side of the graph region. The number at the top indicates the upper limit of the variable value (as set in the UpperLimit property). The number at the bottom indicates the lower limit of the variable value (as set in the LowerLimit property). Grid lines and scale ticks and labels will be displayed as specified.

Figure 1 shows an example where LowerLimit and UpperLimit property settings are symmetrically scaled. In this case, the x-axis is shown in the center of the control. However, this control will also allow you to set the UpperLimit and LowerLimit properties to values that are not the negative of the other. Figures 2 through 7 show examples of this asymmetrical scaling.

If the variable specified by the ProbeSource property is not numeric data type, a special string “Invalid variable type” is display

Below are all of the properties of the TPRI.HMI.Controls.LevelDisplay class.

None

None

The TPRI.HMI.Controls.SelectButton is used for live display and update of a variable in global common.

The TPRI.HMI.Controls.SelectButton control is a pushbutton object used to indicate whether or not a variable on the host is currently equal to a specified value.  In addition, clicking the button will automatically set the host variable to the specified value.

For instance, suppose an integer variable on the host system is used to indicate the current user selection from a finite number of choices.  Typically, a screen will use several SelectButton objects to allow a user to quickly see which of the choices is currently selected and change the current selection by clicking on the appropriate button.

By default, the SelectButton assumes that the user can directly set the current selection variable on the host.  In some instances, however, the user must request a selection and the host system will validate the request before updating the current selection.  In this case, a second variable (WriteProbeSource property) is required.

If WriteProbeSource is an empty string, then when the user clicks on the button the specified value is written back to the host using ProbeSource.

If WriteProbeSource is not an empty string, then when the user clicks on the button the specified value is written back to the host using WriteProbeSource.

Finally, if communications with the server is inactive for some reason and the object is not being actively updated with the current value (type mismatch…), a special string (property tDisconnectedStr, default “###”) is displayed to indicate that the display is not live.

Below are all of the properties of the TPRI.HMI.Controls.SelectButton class.

None

None

The TPRI.HMI.Controls.StateList control is used to display a list of all of the allowed states of a variable, highlighting the current state. 

Each item in the StateList is shown with a small circle icon which is colored green to indicate the current state on the host system.  In addition, each state can be associated with a TabPage on the parent form that will automatically be displayed when the user select a specific state in the list.

When the StateList control first starts up, it requests the current state variable from the host system.  Any time the host sends the current value back to the StateList control will automatically select the tab page associated with that value (auto select live data item mode is on).

When an item on the list (a node) is selected manually, the auto select live data item mode is turned off. Now when the host sends the current value back to the StateList control the tab page associated with that value will not be selected automatically.

Right click the list to turn the auto select live data item mode on or off (a popup menu).

It is allowed for different list entries to be associated with the same value; when the current state is this value then both entries in the list will have their indicators lit up.  On the initial update the StateList should select the tab page associated with the first entry that it finds that matches the  cureent state.

It is allowed for different list entries to be associated with the same TabPage.

ProbeSource should only support Integer values returned from the host.

This class is used to store the attributes of each item on the list. The attributes are:

• Text as String
  Text displayed in the list view for this state

• Value as Integer
  Value of the state

TabPage as TabPage - Reference to the associated tab page to display when the item is selected. When user sets this property, if property Text is empty then set it to TabPage.Text by default.

Below are all of the properties of the TPRI.HMI.Controls.SelectButton class.

None

None

TPRI.HMI.Controls.ActiveGrid control is a tree-style grid that is automatically populated with data from the probe server. 

At its simplest, an ActiveGrid displays elements from an array of data on the host system.  Suppose that the host system has an array variable named Variable1 with 100 elements.  The ActiveGrid could be used to display elements 10-13 of this array as follows:

Label

• +Variable1

• 1.2

• 2.3

• 3.4

• 4.5

In this example, the numbers “1.2”, “2.3”, etc. correspond to the values Variable1[10] through Variable1[13].

The grid itself is configured by a GridSet file loaded from the host system.  A GridSet file is an xml-style ASCII text file that is automatically downloaded by the ActiveGrid using the NtRtInfo client/host services.  A GridSet that would define the above example is as follows:

<GridSet>
   <Header Label="Label" Width="20" />
   <Group Label="Variable1">
      <Records Range="10-13">
<Column Type="Probe" Value="Variable1[]" Format="" Style="Text" />
      </Records>
   </Group>
</GridSet>

The following elements are defined in the GridSet file:

Within the grid, multiple nodes and groups of records can be defined.  Below is an example of a more complicated ActiveGrid:

The GridSet definition for this complex ActiveGrid would be the following:

<GridSet>
   <Header Label="" Width="20" />
   <Header Label="Label" Width="100" />
   <Header Label="Value" Width="100" />
   <Header Label="Force" Width="100" />
   <Header Label="ForceValue" Width="100" />
   <Group Label="A/I">
      <Group Label="A/I 0-7">
         <Records Range="0-7">
            <Column Type="Index"/>
            <Column Type="Probe"
                    Value="$PXIDATA.Stand[0].AnalogIn.point[].label"
                    Format=""
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].AnalogIn.point[].value"
                    Format="F3"
                    ZeroColor="Red"	
                    NonZeroColor="Lime"	
                    Style="Light" />
            <Column Type="Probe" 
  			  Value="PXIDATA.Stand[0].AnalogIn.point[].forceEnable"
                    Format=""
                    ZeroColor="Red"	
                    NonZeroColor="Lime"	
                    Style="Button" />
<Column Type="Probe"  
  	  Value="PXIDATA.Stand[0].AnalogIn.point[].forceValue"
                    Format="F3"
                    Style="EditText" />
         </Records>
      </Group>
      <Group Label="A/I 16-23">
         <Records Range="16-23">
            <Column Type="Index"/>
            <Column Type="Probe"
                    Value="$PXIDATA.Stand[0].AnalogIn.point[].label"
                    Format=""
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].AnalogIn.point[].value"
                    Format="F3"
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].AnalogIn.point[].forceEnable"
                    Format=""
                    Style="Button" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].AnalogIn.point[].forceValue"
                    Format="F3"
                    Style="Text" />
         </Records>
      </Group>
   </Group>
   <Group Label="A/O">
      <Group Label="A/O 0-7">
         <Records Range="0-7">
            <Column Type="Index"/>
            <Column Type="Probe"
                    Value="$PXIDATA.Stand[0].AnalogOut.point[].label"
                    Format=""
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].AnalogOut.point[].value"
                    Format="F3"
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].AnalogOut.point[].forceEnable"
                    Format=""
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].AnalogOut.point[].forceValue"
                    Format="F3"
                    Style="Text" />
         </Records>
      </Group>
   </Group>
   <Group Label="D/I">
      <Group Label="D/I 0-7">
         <Records Range="0-7">
            <Column Type="Index"/>
            <Column Type="Probe"
                    Value="$PXIDATA.Stand[0].DigitalIn.point[].label"
                    Format=""
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].DigitalIn.point[].value"
                    Format=""
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].DigitalIn.point[].forceEnable"
                    Format=""
                    Style="Text" />
            <Column Type="Probe"
                    Value="PXIDATA.Stand[0].DigitalIn.point[].forceValue"
                    Format=""
                    Style="Button" />
         </Records>
      </Group>
   </Group>
</GridSet>

The following properties are exposed by the TPRI.HMI.Controls.ActiveGrid class.

None

None