Define/Execute Command
There are several types of commands you can assign to objects with RTView, including custom commands. Commands can be setup to execute when you click on an object or automatically execute the command when the value of an object reaches a specified threshold.
Depending on which data sources are licensed in your RTView application, there are several commands that can be assigned to an object. For information on the Define Command dialog for your data source, refer to the RTView Data Sources section of this documentation.
Note: Some data sources do not support commands.
How your command is executed depends on the type of command, which are described in this section.
Commands
Commands work with the Display Builder, Display Viewer, and the Display Server. When you deploy RTView as a Thin Client Browser or Served Data deployment, depending on the command, it is executed either on the server or the client. See command descriptions for information on where commands are executed.
Define Command
For Control Objects, assign a command by right-clicking on actionCommand in the Object Properties window. For all other objects, assign a command by right-clicking on command in the Object Properties window. Select Define Command and choose SYSTEM, ALERT (see Define Alert Command), MULTIPLE (see Define Multiple Commands ), or your data source. For information on the Define Command dialog for your data source, refer to the RTView Data Sources section of this documentation.
Note: Some data sources do not support commands.
Execute Command
Once a command has been assigned to a control object, it is executed when the control object is activated. For more information on how each control object is activated, see the Control Objects section. For all other objects, double-click on the object in the Display Builder, single-click in the Display Viewer, or right-click and select Execute Command from the popup menu to execute the command. In the Display Server, commands execute on a single-click or by right-clicking and selecting Execute Command from the popup menu.
Note: Select Tools>Options to execute commands on non-control objects in the Display Viewer with a double-click. See General Tab for more information.
Multiple commands are executed as a series of individual commands that are launched in sequence.
Note: There is no guarantee that any individual command will have completed before the execution of the next command due to their potentially asynchronous nature.
It is possible to execute a command from an individual element in an object that displays tabular data (i.e., a cell in a table or a bar in a bar graph). Based on your data attachment, substitutions are created that will be applied to the command before it is executed. See the Drill Down Substitutions section for information on how to customize which substitutions will be passed into the command.
Command Confirmation
By default, the command confirmation dialog is disabled. To control this option for each individual object, use the commandConfirm check box in the Object Properties window. If confirmation is required for a multiple command, a single confirmation dialog is presented. If you confirm the execution, all individual commands will be executed in sequence with no further confirmation. If the you cancel the execution, none of the commands in the sequence will executed.
Use the commandConfirmText property to write your own text for the confirmation dialog. Otherwise, text from the command property will be used.
It is also possible to override the confirmation status of individual objects with an application wide policy. Select Tools>Options to choose from three confirmation values:
|
Policy |
Description |
|
Do not confirm |
Indicates that no commands require confirmation (regardless of each object's confirmation status). |
|
Confirm all |
Indicates that all commands require confirmation (regardless of each object's confirmation status). |
|
Use object confirm flag |
Indicates that the confirmation status of each object will determine whether confirmation is required. This is the default policy. |
Close Window Command
Use the commandCloseWindowOnSuccess check box to automatically close the window that initiates a system command when the system command is executed successfully. This applies to system commands only. With data source commands, the window is closed whether or not the command is executed successfully. For multiple commands, the commandCloseWindowOnSuccess is applied to each command individually. Therefore, if the first command in the multiple command sequence succeeds, the window will close before the rest of the commands are executed. See Define Multiple Commands for more information.
Note: The commandCloseWindowOnSuccess property is not supported in the Display Server.
Threshold Commands
Threshold commands work with the Display Builder, Display Viewer, and the Display Server. There are four objects that support threshold commands: obj_circ2d_ilvx_ra4, obj_rect_ilvx_ra4, obj_circ2d_ilvx_da3, and obj_rect_ilvx_da3 (found in the General tab labeled either Range Dynamic or Discrete Dynamic). A threshold command can be defined using valueCommandResetTrigger and valueCommandTimeout on those objects. Both the range dynamic and the discrete dynamic objects have the thresholding functionality turned off by default. In the descriptions below, the object's value is the current value of the value property.
Range Dynamic
Range Dynamic objects allow you to setup your threshold so that if the object's value is within a range of numbers, the threshold functionality executes. To enable the high alarm threshold, check the valueHighAlarmEnabledFlag. This will enable several related properties. When the object's value is greater than or equal to the valueHighAlarm property, the background of the object will change to the valueHighAlarmColor, the bitmap on the image will change to the valueHighAlarmImage and the valueHighAlarmCommand will be executed. To enable the high warning threshold, check the valueHighWarningEnabledFlag. When the object's value is greater than or equal to the valueHighWarning, but less than the valueHighAlarm, the background of the object will change to the valueHighWarningColor, the bitmap on the image will change to the valueHighWarningImage and the valueHighWarningCommand will be executed. The low alarm and low warning threshold properties work the same way, but activate when the object's value is less than or equal to the valueLowAlarm or valueLowWarning properties.
Discrete Dynamic
Discrete Dynamic objects are similar to Range Dynamic objects, except that the threshold functionality is executed when the object's value equals the threshold value instead of when it is within the range of threshold values. To enable the high alert threshold, check the valueHighAlertEnabledFlag. When the value property equals the valueHighAlert, the background of the object will change to the valueHighAlertColor, the bitmap on the image will change to the valueHighAlertImage and the valueHighAlertCommand will be executed. To enable the medium alert threshold, check the valueMediumAlertEnabledFlag. When the value property equals the valueMediumAlert, the background of the object will change to the valueMediumAlertColor, the bitmap on the image will change to the valueMediumAlertImage and the valueMediumAlertCommand will be executed. The low alert threshold property works the same way, but activates when the object's value is less than or equal to the valueLowAlert property.
For both the Discrete Dynamic and Range Dynamic objects, threshold commands will only execute if the number of seconds specified in the valueCommandTimeout has elapsed since the previous threshold command was executed and the value has changed to another threshold. For example, if the high warning threshold range is between 40 and 50, when object's value enters this range, the valueHighWarningCommand will be executed. The valueHighWarningCommand will not be executed again until the object's value leaves the high warning threshold range and then re-enters it. If this occurs in less time than is specified in the valueCommandTimeout property, it will not be executed until that time elapses. If the valueCommandTimeout is set to 0, the internal default, 5 seconds, is used. However, if the value of valueCommandResetTrigger property is changed, then the object's threshold command will be executed again even if the value property has not changed. Changing the value of valueCommandResetTrigger when the object's value is not at or above a limit has no effect.
If the webLabelFlag property is checked on an object with a threshold command, the threshold command will be executed in a thin client deployment when appropriate. If the threshold command is a supported client-side command it will be executed in the browser. The client-side commands are: Play Audio File, Drilldown/Set substitution, Execute Custom Command (if the custom command has a javascript implementation), and Open Browser. All other commands are executed by the display server or (for a data source command) in the data server.
Define Threshold Command
To assign a threshold command, right-click on a threshold command property in the Object Properties window. Select Define Command and choose SYSTEM, ALERT (see Define Alert Command), MULTIPLE (see Define Multiple Commands ), or your data source.
Execute Threshold Command
Once a threshold command has been assigned to an object, it is executed when the current value of the object (based on the attached data source) reaches the specified threshold. Multiple commands are executed as a series of individual commands that are launched in sequence.
Note: There is no guarantee that any individual command will have completed before the execution of the next command due to their potentially asynchronous nature.
Open/Close Display Commands
You can define a command to be activated when a display (.rtv) file is opened or closed.
Define Open/Close Display Command
Select Edit>Model Properties and right-click on either onCloseCommand or onOpenCommand. Select Define Command and choose SYSTEM, ALERT (see Define Alert Command), MULTIPLE (see Define Multiple Commands ), or your data source.
Note: The SYSTEM drill down command is not supported for onCloseCommand and onOpenCommand.
Execute Open/Close Display Command
Open Display and Close Display commands are executed when the display (.rtv) file (where you set the Model Properties) is opened/loaded or closed/replaced.
Multiple Commands
You can define multiple commands to execute when a command is activated.
Define Multiple Commands
To define multiple commands, right-click on a command property in the Object Properties window. Select Define Command and choose MULTIPLE. To create multiple commands, click on the Add button. Select an existing command and click Edit to modify, Duplicate to copy, or Remove to delete.
Execute Multiple Commands
Multiple commands are executed as a series of individual commands that are launched in sequence. There is no guarantee that any individual command will have completed before the execution of the next command due to their potentially asynchronous nature. Therefore, you cannot count on a result of the first command to apply to the rest of the commands. Command failure dialogs will appear for any command in the sequence that fails.
Command Failure
Commands executed by a data source or a system command can return a dialog window or a console message indicating whether the command was successful. Where and how the dialog window appears depends on which type of command is executed and the type of RTView deployment:
Application or Rich Client Browser with Direct Data Connection:
System command - Dialog window appears on the client
Data source command - Console message appears on the client. For the data sources that support error dialogs for command failure, a dialog will also appear on the client. See the Define Command section for your data source to see if it supports error dialogs.
Application or Rich Client Browser with Served Data:
System command - Dialog window appears on the client
Data source command - Message appears in Data Server console
Thin Client Browser with Served Data:
System command - Message appears in Display Server console
Data source command - Message appears in Data Server console
Thin Client Browser with Direct Data:
For both command types - Message appears in Display Server console
Define System Command
You can access the Define System Command dialog from the Object Properties window. This dialog is used to assign system commands allowing you to issue commands. Commands can be executed from within an RTView display in the client (the Builder, Viewer or Display Server). Additionally, several commands can be executed on a Data Server (the Execute Custom Command, Execute URL, Run DOS Command or Unix Shell, Send Email and Send SNMP Trap commands). For details, see Execute Commands on a Data Server. By default, commands execute on the client.
To bring up the Define System Command dialog, right-click on the appropriate command property in the Object Properties window and select Define Command>SYSTEM. The Define System Command dialog provides a drop down menu with available commands. When a command can execute on a Data Server, the Data Server drop down menu appears at the bottom of the dialog. Argument fields vary based on the selected command type. See the Define/Execute Command section for information on how to execute a command.
Command Types
The following commands are executed in the client or, where indicated, can also be redirected to a Data Server.
|
Command Type |
Description |
|||||||||
|
Beep |
Plays the system default audio beep. This command does not work in the Display Server. Note: If you execute this command from one of the Served Data deployments, this command will execute on the client. |
|||||||||
|
Close Window |
Closes the window specified in the Window Name argument. If no Window Name is given it closes the window containing the object that generated the command. This command cannot be used to close the main window. See Drill Down Displays for more information. Note: If you execute this command from a Thin Client with Direct Data Connection or any Served Data deployment, this command will execute on the client. |
|||||||||
|
Drill Down or Set Substitution |
Drill down to a new display or set substitutions on the current display. Click on Edit Drill Down Target to open the Drill Down Properties dialog and define your drill down or substitution. Substitutions are not applied to this command before it is executed. In the Drill Down Properties dialog, to attach one of the following fields to data, right-click and choose Attach to Data or double-click in the field:
Note: If you execute this command from a Thin Client with Direct Data Connection or any Served Data deployment, this command will execute on the client. Limitation: This command cannot be executed via an alertCommand from the Thin Client. |
|||||||||
|
Execute Custom Command |
Executes the custom command in the Command Name field with the specified Command Value. You may define your own custom commands in the Custom Command Handler. The specified Command Name and Command Value will be passed into the invokeCommand method in the Custom Command Handler. If you execute this command in a Thin Client deployment, it will execute on the server if implemented in Java and on the client if implemented in JavaScript. See Define Custom Command for more information. Note: If you execute this command from one of the Served Data deployments, this command will execute on the server. Otherwise, this command executes on the client. This command can also execute on a Data Server. See Execute Commands on a Data Server for more information. |
|||||||||
|
Execute URL |
Executes the specified URL String. This can be used to execute JSP, ASP or CGI scripts. This command will not open the specified URL in a browser. Note: If you execute this command from a Thin Client with Direct Data Connection or any Served Data deployment, this command will execute on the client. This command can also execute on a Data Server. See Execute Commands on a Data Server for more information. |
|||||||||
|
Open Browser |
Opens the specified URL in a browser window or a new tab. Select Current, Parent, Top, New, or Named in the Browser Window property to set in which browser window the page will display. New is the default setting. If you specify Browser Window as Named and Window Name as _tab, then the URL will open in a new browser tab (in the thin client). Note: When trying to open the URL in a new tab, your browser’s settings must be configured to automatically open a new tab for popup windows. If your browser’s settings are configured to open popups in a new window, then the Open Browser command will open the URL in a (new) browser regardless of the settings. Note: If you execute this command from a Thin Client with Direct Data Connection or any Served Data deployment, this command will execute on the client. |
|||||||||
|
Play Audio File |
Plays the specified audio file. The File Name should include a relative path from your RTView display to the audio file. The support for audio file formats varies by platform, as follows.
Note: Only .wav files are supported by the Play Audio File command in the builder/viewer. Note: If you execute this command from one of the Served Data deployments, this command will execute on the client. |
|||||||||
|
Run DOS Command or UNIX Shell |
Executes the specified DOS command or UNIX Shell. This will be executed in the directory where you started RTView. Note: This command does not work in the Display Server. This command can also execute on a Data Server. See Execute Commands on a Data Server for more information. |
|||||||||
|
Send Email |
Sends the specified email message. Note: Multiple addresses or attachments should be separated by spaces or commas. To use the Send Email system command you must modify the Java security settings on each client to include the following permissions: permission java.net.SocketPermission "SMTPHostName", "resolve"; permission java.net.SocketPermission "SMTPHostIP", "accept, connect, listen, resolve"; permission java.util.PropertyPermission "user.name", "read"; }; Where SMTPHostName is the name of the SMTP server, SMTPHostIP is the IP address of the SMTP server. Contact your system administrator for SMTP Host address and SMTP Port number. SMTP Port field is optional. If left blank, SMTP Port 25 is used. User and Password fields are optional, unless authenticated mail sever access is required. This command executes on the server. This command can also execute on a Data Server. See Execute Commands on a Data Server for more information. |
|||||||||
|
Send SNMP Trap |
Enables a display to send an SNMP Trap message, such as would be sent from an SNMP Agent to a SNMP Management Station. Requires outgoing access to UDP port 162 (or a different port as specified in your command). Note: If you execute this command from a thin-client deployment it will execute on the server, otherwise it will execute on the client. This command can also execute on a Data Server. See Execute Commands on a Data Server for more information. |
|||||||||
|
|
Use the following fields to define your SNMP Trap Message: Trap Type --SNMP version of the trap. Destination Address -- System name or IP address of the receiving system. Default value is 127.0.0.1 (localhost). To attach the Destination Address to data, right-click and choose Attach to Data or double-click in the field. Destination Port -- UDP port on the receiving system. Default value is 162. Value must be an integer greater than 0. To attach a Destination Port to data, right-click and choose Attach to Data or double-click in the field. Community Name -- SNMPv2 Community Name string. Default value is public. To attach the Community Name to data, right-click and choose Attach to Data or double-click in the field. |
|||||||||
|
|
Enterprise OID -- SNMP Object ID to be used as the sender's Enterprise. Default value is 1.3.6.1.6.3.1.1.5. Generic Trap -- List of generic traps. Specific Trap --List of specific traps available will depend on the property for which you are defining a command. The Generic Trap selected must be enterpriseSpecific to enable this menu. |
|||||||||
|
|
Currently the only Specific Trap option is Alert, which is available if you are defining a command for the alertCommand property. The Alert trap is sent with the name rtviewAlert and includes the following MIB definition: |
|||||||||
|
|
rtview OBJECT IDENTIFIER ::= { sl 1 } rtviewNotifications OBJECT IDENTIFIER ::= { rtview 1 } rtviewAlert NOTIFICATION-TYPE OBJECTS { rtviewAlertName, rtviewAlertIndex, rtviewAlertTime, rtviewAlertLastUpdateTime, rtviewAlertSeverity, rtviewAlertText, rtviewAlertID, rtviewAlertLabel, rtviewAlertCommandText, rtviewAlertCurrentValue, rtviewAlertComparisonValue } ::= { rtviewNotifications 2 } Note: Traps sent by RTView use Enterprise OID private.enterprises.sl (.1.3.6.1.4.1.34605). |
Execute Commands on a Data Server
The Data Server drop down menu appears at the bottom of the dialog when a command can be executed on a Data Server. Drop down menu options are:
|
Option |
Description |
|
none |
Sets the command to execute on the client. This is the default. |
|
default |
Sets the command to execute on the default Data Server. If there is no connection defined for that Data Server, the command is not executed. |
|
Enter a named Data Server |
Enter a named Data Server in the Data Server field on which to execute the command. If there is no connection defined for that Data Server, the command is not executed. |
|
Substitution |
Enter a substitution in the Data Server field, such as $server. |
For example:
|
$server: |
An empty string sets the command to execute on the client. |
|
$server:__none |
__none sets the command to execute on the client. This value starts with two underscore characters. |
|
$server:__default |
__default sets the command to execute on the default Data Server. If there is no connection defined for that Data Server, the command is not executed. This value starts with two underscore characters. |
|
$server:SalesDS |
A named Data Server sets the command to execute on the named Data Server. If there is no connection defined for that Data Server, the command is not executed. |
Substitutions
Substitutions allow you to build open-ended displays in which commands depend on values defined at the time the display is run. Generic names are used instead of arguments for specific commands. Later when the display is running, these generic values are defined by the actual arguments. In this way, a single display can be reused to issue a number of different commands. Substitutions are not applied to Drill Down or Set Substitution commands. For more information on creating displays using substitution values, see Substitutions.
Special Values
|
$value |
When an actionCommand is executed $value is replaced with the value from the control. This value may be used in any field in the Define System Command dialog. Note: This value may only be used for Action Commands. See Commands for more information. |
The following describes Define System Command dialog commands:
|
Command |
Description |
|
OK |
Applies values and closes the dialog. |
|
Apply |
Applies values without closing the dialog. |
|
Reset |
Resets all fields to last values applied. |
|
Clear |
Clears all fields. Detaches object from data source (once Apply or OK is selected). |
|
Cancel |
Closes the dialog with last values applied. |