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, Display Viewer Applet, 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 Viewer Applet. Threshold commands do not work with the Display Server. Threshold commands can be assigned to objects found on the General tab that are labeled either discrete dynamic or range dynamic. Depending on how you have deployed RTView, threshold commands are executed either on the Display Server or the client machine.

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: § Drill Down Display Name § Window Title § Drill Down Substitution Value 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.
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. Select Current, Parent, Top, New, or Named in the Browser Window property to set which window the page will come up in. New is the default setting. 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. 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.
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 Viewer Applet or 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. Note: Email attachments are not supported in the Display Viewer Applet. 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. Note: This command requires additional setup when used with the Display Viewer Applet. Attachments are not supported in the Display Viewer Applet. 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.