Chapter 4. Writing Scripts

Table of Contents

4.1. Creating a Script
4.2. Hello World
4.3. Accessing Data
4.4. Modifying Data
4.5. Two-Way Data Manipulation
4.5.1. Adapt it for your needs
4.6. Making a Window
4.7. Encrypting a Script
4.8. Scripting Tips
4.8.1. Copying a complete tutorial
4.8.2. Setting up a scripting environment

Writing a script for the DataHub is not difficult, particularly when you follow a few basic principles. Working directly with DataHub points and the Gamma interpreter environment creates special opportunities, and you can take best advantage of them by using the suggestions offered here.

[Note]

Most of the examples in this chapter use DataSim, which is installed with the DataHub. You should ensure that it is connected and sending data to the DataHub before attempting these examples. For more information, please refer to DataSim in the Cascade DataHub manual or the OPC DataHub manual.

4.1. Creating a Script

The best way to write a DataHub script is to create a single class in which your entire script runs. This keeps all variables and functions (methods) local to the class and isolated from any other script running in Gamma. Rather than create the class from scratch, the DataHub writes a template for you that contains what you need. Here's how it works:

  1. Open the DataHub Properties window and select the Scripting option.
  2. Click the New button. This dialog will appear:
  3. In the New class: field, enter a name of your choice. The default is MyApp.
  4. Look at the File name: field to make sure this is where you want the script to be created. If not, you can browse your file system for a better location.
  5. Checking the Allow only one instance box will ensure that each instance of the class gets destroyed whenever a new instance is created. Thus you will only ever have one instance. If you want your code to create multiple simultaneous instances of the class, don't check this box.
  6. The Include sample code option lets you choose one of the following:

      None will generate no sample code.

      Windows will generate code to help you create windows.

      Data Manipulation will generate code for doing linear transformations and other data manipulation.

    These options will be illustrated and discussed in upcoming sections.
  7. Click the OK button to create the file.
    The Script Editor should open, displaying a script template ready for editing. The basic template looks like this:
    /* All user scripts should derive from the base "Application" class */
    
    require ("Application");
    
    /* Get the Gamma library functions and methods for ODBC and/or
     * Windows programming.  Uncomment either or both. */
    
    //require ("WindowsSupport");
    //require ("ODBCSupport");
    
    /* Applications share the execution thread and the global name
     * space, so we create a class that contains all of the functions
     * and variables for the application.  This does two things:
     *   1) creates a private name space for the application, and
     *   2) allows you to re-load the application to create either
     *      a new unique instance or multiple instances without
     *      damaging an existing running instance.
     */
    class MyApp Application
    {
    }
    
    /* Use methods to create functions outside the 'main line'. */
    method MyApp.samplemethod ()
    {
    }
    
    /* Write the 'main line' of the program here. */
    method MyApp.constructor ()
    {
    }
    
    /* Any code to be run when the program gets shut down. */
    method MyApp.destructor ()
    {
    }
    
    /* Start the program by instantiating the class.  If your
     * constructor code does not create a persistent reference to
     * the instance (self), then it will be destroyed by the
     * garbage collector soon after creation.  If you do not want
     * this to happen, assign the instance to a global variable, or
     * create a static data member in your class to which you assign
     * 'self' during the construction process.  ApplicationSingleton()
     * does this for you automatically. */
    ApplicationSingleton (MyApp);
    

The following sections explain how to edit this template and run the finished script.