2.4.1.3 X-Function Execution Options

X-Function Option Switches

The following option switches are useful when accessing X-Functions from script:

Switch Full Name Function
-cf -- Copy column format of the input range, and apply it to the output range.
-d -dialog Brings up a dialog to set X-Function parameters and generate script.
-db -- Variation of dialog; Brings up the X-Function dialog as a panel in the current window.
-dc IsCancel -- Variation of dialog; Brings up a dialog to select X-Function parameters. Set IsCancel to 0 if click the OK button, set to 1 if click the Cancel button. When clicking the Cancel button, no error message like #User Abort! dumps to Script Window and the script after X-Function can be executed.
-e -- Open the X-Function in the X-Function Builder. This works the same as the edit -x command.
-h -help Prints the contents of the help file to the Script window.
-he -- Prints the contents of script example to the Script window.
-hn -- Loads and compiles the X-Function without doing anything else. If the X-Function has already been compiled and loaded, it will do nothing.
-hs -- Variation of -h; Prints only the Script Usage Examples.
-ht -- Variation of -h; Prints only the Treenode information, if any exists.
-hv -- Variation of -h; Prints only the Variable list.
-hx -- Variation of -h; Prints only the related X-Function information.
-r <option> -recalculate Specify the recalculation mode: 0 = none; 1 = auto; 2 = manual:Example. Recalculate is not supported when output is the same as <input>.
-s -silent Runs in silent mode; results are not sent to Results log.
-sb -- Variation of -s; suppresses error messages and Results log output.
-se -- Variation of -s; suppresses error messages, does not suppress Results log output.
-sl -silent Same as -s.
-sr

(Origin 2016 SR1)

-- Variation of -s; suppresses result messages to the script window.
-ss -- Variation of -s; suppresses info messages to the script window.
-sw

(Origin 2016 SR1)

-- Variation of -s; suppresses warning messages to the script window.
-t <Name> -theme Uses the designated preset theme.
-u

(Origin 2024b)

-undo Specify whether the operation can be undone when running from script.


For options with an existing Full Name, either the shortened switch name or the full name may be used in script. For instance, for the X-Function smooth,

smooth -h

is the same as

smooth -help

Examples

Open X-Function Dialog

Use -d switch to open X-Function dialog so that user can inter interactively supply input and parameters

The following script fills column 1 & 2 with data, use the -d switch to open the smooth X-Function dialog, where user can preview result, adjust settings, etc. Upon clicking OK, the script will continue to plot column 2 and 3 as line graph.

col(1)=data(1,100); //fill column 1 with row numbers.
col(2)=normal(100); //fill column 2 with normalized data
//open dialog with input, method and number of points loaded. 
//Play with settings in the dialog and click OK
smooth (1,2) method:=2 npts:=25 -d; 
//plot Y columns (column 2 and 3) against X column in sheet (column 1) as line graph
plotxy (?,2:3) p:=200;

Using a Theme

Use the -t switch to execute the x-function with saved dialog theme. Dialog theme is basically the settings of X-Function dialog, parameters and output. Usually input is excluded in theme file.

The following steps shows how to save a dialog theme file and then use the -t switch to use it.

  1. Select column 2 created after above script. Run the following script to open smooth dialog. Or u can choose Analysis: Signal Processing: Smoothing: Open dialog... menu
    smooth -d;
  2. Set the Method as Adjacent-Averaging and Points of Window as 5.
  3. Click the > button next to Dialog Theme on the top and choose Save As.... Save the dialog settings as FivePtAdjAve.
  4. Cancel the dialog.
  5. Activate the workbook with data in previous script.
  6. Run the X-Function with -t switch to perform a smoothing with XY data in column 1 and 2 using the theme named FivePtAdjAve, which means Method as Adjacent-Averaging and Points of Window as 5
    smooth (1,2) -t FivePtAdjAve;

Note: No need to specify the theme file path since Origin automatically saves and retrieves your themes from User Files\Themes\AnalysisAndReportTable\. You can share the theme file with others. They can drag and drop the theme file into Origin workspace to install it. Themes saved in one project (*.OPJ) will be available for use in other projects as well. Start from Origin 2024, Origin will first look for your themes from current project folder. If not found, then from User File Folder.

Setting Recalculate Mode

Use the -r switch to set recalculation mode of output.

Multiple switches can be used together. Two switches: -t FivePtAdjAve are used below to smooth with FivePtAdjAve theme and -r 1 to set recalculation mode to auto

smooth (1,2) -t FivePtAdjAve -r 1;

The following script runs the freqcounts X-Function with -r 1 to automatically recalculate when data in the input column changes.

newbook;
col(1)=uniform(100)*50; //generate uniformly distributed random data from 0 to 50.
//do frequency count with increment 5, recalculation mode set to auto
freqcounts irng:=col(1) min:=0 max:=50 stepby:=increment inc:=5
   end:=0 count:=1 center:=1 cumulcount:=0 rd:=col(4) -r 1;

Open X-Function Builder

Help file dumped by -h switch can be overwhelming and hard to read, while other -he, -hv is too limited.

So instead, user can use the -e switch to open the X-Function in X-Function Builder so that user can see all parameter in table view with full info.: input/output, data type, default value, etc, etc. This is also the dialog for advanced users to learn the code of built-in X-Functions. By clicking Edit X-Function in Code Builder button in the dialog. the X-Function code shows in Code Builder.

smooth -e;

Copy Format from Input to Output

Use the -cf switch to format the output data to match that of the input data:

By default, all analysis results are output as datatype double. The following script makes the output data format to be short(2), which is the input data format.

// Import a *.wav file; imported *.wav data format is short(2).
fname$ = system.path.program$ + "Samples\Signal Processing\sample.wav";
newbook s:=0; 
newsheet col:=1; 
impWav options.SparkLines:=0;

//Perform lowpass fft_filter on col 1 of 1st sheet in current book with cutoff freq = 2000
fft_filters -cf [%H]1!col(1) cutoff:=2000  
oy:=(<input>,<new name:="Lowpass Sound Frequency">);

Undo the Operation

Use the -u switch to support undo the x-function operation when running from scripts.

If a x-function is run from the dialog, by default the operation can be undone. But if it is run from scripts, we should use -u switch to support undo. The following scripts transpose the active worksheet and output the results to a new workbook and then undo the operation.

wtranspose -u ow:=<new>;
undo;