Often it is desirable to run scripts in the "background" so that you do not see the interactions or tables or graphics, but instead have the appropriate functions executed or .png files created. Most math scripts do not write to the screen, so this is not an issue. If you call higher level functions, there is the potential that some dialogs may appear, especially if there are errors. The ListSelection class tries to figure out how you are running a script and will only print messages if you are running it in the background, but show message dialogs if your are running in the foreground. This means that you can get different message dialog behavior if you run a script from HEC-DSSVue that accesses ListSelection than if you run it in a batch mode.

Headless on Windows

On the PC, you can set the location of plots and tables off-screen so that they are not visible to the user, create the .png or .jpg file, and then close the plot or table. For example:

plot = Plot.newPlot()
plot.setSize(600, 500)
plot.setLocation(-10000, -10000)

…
plot.showPlot()
…
plot.saveToPng("C:/temp/myPlot.png")
plot.close()

Headless on UNIX

On UNIX, you must have an X-Window server on which to generate a plot or table. This is done using a Virtual X-Window server, such as Xvfb. The programs treat this as a normal X-Window display. Like the PC, you run the scripts as normal, although you don't need to set at location:

plot = Plot.newPlot()
plot.setSize(600, 500)
…
plot.showPlot()
…
plot.saveToPng("/tmp/myPlot.png")
plot.close()

For more information, refer to: http://www.x.org/archive/X11R6.8.2/doc/Xvfb.1.html

On UNIX it is generally advantageous to use the same script to run in an interactive mode as well as a batch mode. This can be accomplished by checking to see if the DISPLAY environment variable is set. If it isn't, then check that Xvfb is running and set the DISPLAY variable to ":1.0". For example:

#!/bin/ksh
# ******************************************************************
if [ "$DISPLAY" = "" ]
then
   XvfbRunning=`ps -ef | grep Xvfb | grep -v grep | wc -l | sed -e "s/ //g"`
   if [ $XvfbRunning -gt 0 ]
   then
      DISPLAY=":1.0"
      export DISPLAY
      printf "\nWARNING : Using virtual display – “
      printf "no graphics will be visible.\n\n"
   else
      printf "\nWARNING : Virtual display server is not running."
      printf "\n          Set DISPLAY variable or start Xvfb.\n\n"
      return -1
   fi
fi
# ******************************************************************
# Execute the program here….

Interactive and Batch Mode Scripts

A script is said to be interactive if it is executed from the HEC-DSSVue menu bar, tool bar, Script Selector, or Script Editor. With any of these methods, the user interacts with the HEC-DSSVue GUI to launch a script. Conversely, a script is said to be in batch mode if it is executed from a command prompt or shortcut as a parameter to the HEC-DSSVue program.

To run a script in batch mode, you specify the file name of the script as a parameter to HEC-DSSVue, following the program name; for example:

HEC-DSSVue.exe C:\HecDSSVueDev\HecDssVue\scripts\Oakville.py

In Windows, this can be passed through a .bat file and then you can run that .bat file; e.g., RunOakville.bat:
HEC-DSSVue.exe C:\HecDSSVueDev\HecDssVue\scripts\Oakville.py

On Windows, a shortcut can be utilized instead of a batch file. To create a shortcut for a script, right click on HEC-DSSVue.exe and select Create Shortcut. 

Edit the Target in the Shortcuts Properties dialog box to include the script name following the program name in the Target area, as shown below.

In UNIX, a file is made executable by changing its mode to be executable, e.g., RunOakville:

HEC-DSSVue /usr1/HecDssVue/scripts/Oakville.py
chmod 555 RunOakville

If a batch mode script requires parameters, they must be appended to the command line (or target field in the shortcut) after the name of the script:

HEC-DSSVue.exe C:\HecDSSVueDev\HecDssVue\scripts\xyz.py a b c

A script may determine whether it is executing in interactive or batch mode by calling the isInteractive() ListSelection method.

One characteristic of batch mode scripts is that any GUI components (plot, tables, etc…) displayed during their execution close when the script completes. While this behavior is acceptable for generating files containing tables and plot images, it is often desirable for a batch mode script to display GUI components that persist until the user dismisses them. A batch mode script may utilize Dialog functions to keep the GUI components visible.  However, if a batch mode script uses one of the window types listed below, it can call the stayOpen() method of the window to gain persistence without the need for an extra dialog.

Window Types with stayOpen() Method

The stayOpen() method causes the window to wait and stay open until the window is closed. Like the MessageDialog functions, the stayOpen() cannot be used in an interactive script. It will cause the program to freeze. Plots will stay open automatically when in an interactive mode. An example use for Oakville.py is:

Display the plot and wait for them to close
plot.stayOpen() # Do not use in an interactive script

Modality in Scripts

Modality refers to whether an application window allows interaction with other windows of the same application. A modal window prevents interaction with other application windows as long as it is displayed. Once the modal window is dismissed, interaction with other application windows resumes. Conversely, modeless windows allow interaction with other application windows while they are displayed. Most HEC-DSSVue windows are modeless, although error dialogs and dialogs created with the MessageBox  are modal.