EZScripts

• EZScript Editor

For convenience, EZL comes with a built-in editor, specifically tailored to writing EZLScripts.

The EZScript Editor can be opened either from the Tools menu

or by right-clicking on an EZScript file within the Directory Browser and clicking "Edit"

When the editor is first opened, a tab will automatically be created containing either a blank script (when opened through the Tools menu) or your pre-existing script (when opened by right-clicking on a Directory Browser item).

New scripts can be created by clicking New from within the File menu, by pressing Ctrl+N on the keyboard, or by clicking the button located on the right-side of the editor.

Open existing scripts by clicking Open from the within the File menu, by pressing Ctrl+O on the keyboard, or by clicking the button on the editor's toolbar. When opening existing scripts a new tab will be created automatically, unless the script within the current tab is empty (in which case, the current tab is reused).

Save your scripts by clicking Save from the within the File menu, by pressing Ctrl+S on the keyboard, or by clicking the button on the editor's toolbar.

If the current script already has a file name associated with it, you can use Save As... from the File menu to save it under a different name.

Close scripts by clicking Close Script from within the File menu, by pressing Ctrl+K on the keyboard, or by clicking the button located on the right-side of the editor.

To begin a comment line within a script, or to comment or uncomment the current line, use the and toolbar buttons, respectively. Or use their keyboard shortcuts: Ctrl+R and Ctrl+T (these shortcut keys were adopted from Matlab).

Finally, the toolbar's run button allows you to immediately execute the script. While, in general, EZScripts are saved to the hard drive so they can later be executed from the Command Window, this button provides you with a convenient way to run/test your scripts. It works on unnamed scripts (ie. unsaved) as well as name scripts. Note, however, that if your script uses input arguments, you may receive errors, as arguments can only be provided to the script via the Command Window or when running EZL from the Windows' command prompt (using the -script <script_name> option).

• EZScript Basic Syntax

In its most basic form, an EZScript is simply a list of EZL commands. When executed, EZL sends the script line-by-line to the Command Window. EZScripts can call other EZScripts. There are no restrictions on the depth of embedded scripts.

• EZScript Input Arguments

One powerful aspect of EZScripts is the ability to write generic scripts using input arguments. When run through the Command Window, you may pass input arguments to an EZScript, which will then be embedded into the script text. Argument designators are specified in an EZScript using the syntax "%d", where d is a number specifying which argument to use. For example:

Suppose we have data files for several GPS receivers: receiver1.dat, receiver2.dat, receiver3.dat, etc... The EZScript shown above allows us to pass in the receiver number and a tailored x-label.

Running the example script with this command (via the Command Window)

replaces all instances of %1 with 3, and %2 with "GPS Satellites". So, the input file becomes receiver3.dat, the title becomes "Acquisition of Receiver 3", and the x-label becomes "GPS Satellites".

Notice that the first argument (%1) was used twice in the script: once as a portion of the input data file "receiver%1.dat", and again as a portion of the title "Acquisition of Receiver %1". Arguments may be reused as many times as desired, and there is no limit to the number of input arguments (eg. %1, %2, %3, %4...)

Running the above script, might produce the example plot shown below.

If there are more input arguments than there are designators in the script, the extra arguments are ignored. For example, if our command was

the final argument "Extra Argument" would simply be ignored, since the script has no %3 designator.

However, if a script designator specifies an argument which does not exist, an error is produced. For example, if our command were

an error would be displayed to indicate that a parameter is missing (in this case, parameter %2).

• Helpful Tips

• When using EZScripts to generate multiple curves on a single plot, your scripts can often be easier to read when using multiple "ezl" commands with the "-append" flag, as opposed to a single "ezl" command with multiple input files

  For example:

  --> An example script to produce three curves on a single plot (example 1)

  ezl -f file1.dat file2.dat file3.dat -x 1 -y 2 -x 2 -y 5 -x 1 -y 3

  May be easier to understand when written as

  --> An example script to produce three curves on a single plot (example 2)

  ezl -f file1.dat -x 1 -y 2

  ezl -f file2.dat -x 2 -y 5 -append

  ezl -f file3.dat -x 1 -y 3 -append

• You can use EZScripts to generate multiple plots, each on their own plot tab. Use the "newtab" or "usingtab" command to create new tabs:

  --> An example script to produce three curves, each on their own tab (example 3)

  usingtab File 1

  ezl -f file1.dat -x 1 -y 2

  usingtab File 2

  ezl -f file2.dat -x 2 -y 5

  usingtab File 3

  ezl -f file3.dat -x 1 -y 3

• While the above example works, you will be left four tabs in total: the three you created, and the default tab "Plot 1" which was created when EZL was initially run. A better approach, therefore, may be the following:

  --> An example script to produce three curves, each on their own tab (example 4)

  closeall

  tablabel File 1

  ezl -f file1.dat -x 1 -y 2

  usingtab File 2

  ezl -f file2.dat -x 2 -y 5

  usingtab File 3

  ezl -f file3.dat -x 1 -y 3

  
  The "closeall" command closes all tabs, leaving one remaining tab with an empty (cleared) plotter. The remaining tab is then renamed to "File 1" using the "tablabel" command.