1.3.1 Calling X-Functions from Script

X-Function, Execution from ScriptX-Function, Execution without Dialog

Most built-in X-Functions can be called in LabTalk by default. This means you can call it from anywhere LabTalk Script can be executed, such as Command Window, Script Window, Toolbar buttons, Script embedded in worksheet, Script behind button, etc.

Syntax to Call X-Functions

Each X-Function has its own set of input and output variables of different data types, such as int, double, string, range, and even tree, etc. The syntax to call All the X-Functions is the same.
<xfunction> -<option1> option1value -<option2> option2value var1:=value1 var2:=value2 ....

Here we will use X-Function smooth to help user get started.

• Support option full name or shortened name. E.g. both scripts below dump help of smooth

smooth -h

smooth -help

• Support variable full name or shortened name. E.g. both scripts below specify method 1 Savitzky-Golay, (indexing starts at 0) for method variable

smooth m:=1

smooth method:=1

• For some variables, support value as string or indexing number. E.g. both scripts below specify method 1 Savitzky-Golay for method variable

smooth method:=1

smooth method:=sg

• Option and variable orders can be mixed up. E.g. Both scripts below specify method 1, and number of points as 5 and recalculation option is set to auto.

smooth -r 1 method:=1 npts:=5

smooth method:=1 -r 1 npts:=5

• There are default values for most variables. No need to specify var1:=value if you want to use default values. E.g. default iy (input) variable is <active> (active plot in graph or selected data in worksheet). All the scripts below do smoothing on active plot in graph or selected data in worksheet.

smooth //smooth on active plot or selected data with all default smoothing settings

smooth m:=2 //smooth on on active plot or selected data with method 2

smooth npt:=7 //smooth on active plot with default method 1, but set points of window to 7

• Variable name part var1:= can be skipped if you type variable values by order. E.g. if you type smooth -h to see all variables, you will see 1st variable is iy, second is method. Both scripts below is the same as smooth iy:=(1,2) method:=2, smooth on dataset (x is 1st column, y is 2nd column of active worksheet) with method 2.

smooth (1,2) 2 //iy:= is skipped, method:= is skipped. It's same as smooth iy:=(1,2) method:=2

smooth (1,2) method:=2 //iy:= is skipped. It's same as smooth iy:=(1,2) method:=2

• Run -d to open X-Function dialog. Most X-Functions has corresponding dialog. You can run the following Script to easily specify variables and execute.

smooth -d //opens smooth dialog with all default settings.

smooth method:=2 -d //opens smooth dialog with method set to method 2

• Run -db to open X-Function dialog and dock it in current window. You can then save the window with dockable dialog for future use.

smooth -db //opens smooth dialog with default settings and the dialog is docked to the left of active window

• Run -u to support undo.

smooth -u // X-Function become undoable, i.e. you can undo by Ctrl + Z or select Undo from Edit menu

Use File Metadata as Input

You can reference file metadata in the X-Function. Open the Script Window (Window: Script Window) and type the following: page.info.= This dumps a listing of file metadata, including user variables that can be used when executing your X-Function.

rnormalize -r 2 method:=specify val:=page.info.USER.VARIABLES.NOOFPOINTS; // runs the X-Function rnormalize, dividing values in the selected column by the value of page.info.USER.VARIABLES.NOOFPOINTS.

As an alternative to dumping variables to the Script Window, you can right-click in the gray area to the right of import file worksheet columns and choose Show Organizer. Expand page.info, then right-click on a node and Copy Node Path.

Access Input and Output Variable Values after Execution

After X-Function is called, you can access variable values, no matter it's input or output. Some X-Function output will need to be put to a tree variable and then access it. Here we will only show some simple examples.

• Highlight a Y column and run smooth to execute it first. Then try the following Script

smooth.= //gives all variables and corresponding values

smooth.method= //gives method number

• Highlight a column and run stats to execute it first. Then try the following Script

stats.= //gives all output values

stats.min= //gives the calculated mean value

To access a report tree, ANOVA for example, you can use Getresults XF.

To get the config tree for an existing operation, you can use Op_change XF.

Quick Way in Command Window

An easier way to learn how to call X-Function is via Command Window (Window: Command Window) since X-Function name, options and variables can be auto filled as you type. Try this:

1. In a worksheet, fill first column with row numbers and fill 2nd column with random numbers. Highlight the 2nd column.
2. Choose Window: Command Window to open Command Window.
3. Type s, you will see an Auto fill list of X-functions starting with s

   

4. Press Down key to smooth and press Enter to select it. You can also double click mouse to select smooth.
5. Now smooth shows in Command line. Press Space key. You will see all variables for smooth.

   

6. Press Down key to method:=1and press Enter to select it.
7. You will see all methods you can pick

   

8. Press Down key to pf=2 Percentile Filter and press Enter to select it.
9. Press Space key and then press - key. You will see all options.

   

10. Press Down key to recalculate and press Enter to select it.
11. Press Space key and then 1 to specify recalculate option to be 1, which means auto recalculation if input data change.
12. Press Enter to execute it. You will see smoothing result shows in 3rd column.

    

13. In Command window, type smooth.= and press ENTER to see all the variable values specified in the executed X-Function.

    

14. run smooth.method= to get the method value.

Use Up and Down keys to scroll backwards and forwards through previous commands you’ve typed in the current session. On left panel of Command Window, you can see all executed commands in current session. You can put cursor there and press Enter to execute that command line again.

Save X-Function settings as a Dialog Theme File and Call it

The variable settings for an X-Function can be saved into a theme file. You can call an X-Function and use settings saved in the theme file by using the -theme or -t option.

Example:

1. In Script window, run smooth -d to open smooth dialog or use Analysis: Signal Processing: Smoothing menu to open it.
2. Change some settings, e.g. Method and Recalculation Mode.
3. Click > button next to Dialog Theme on the top of the dialog and choose Save as.... Give a name e.g. mytheme
4. The file will be saved under <User Files Folder>\Themes\AnalysisAndReportTable\, e.g. 0-smooth-mytheme.ois. Origin adds some pre-fix so user can tell it's for smooth X-Function.
5. In Script window, run the following to do smoothing on active data with mytheme theme

1. smooth -t mytheme //Do smoothing with mytheme

2. smooth -t mytheme -d; // Open smooth dialog with mytheme loaded.

Generate Script from X-Function Dialog

For some X-Functions, there is an option to Generate Script found in the context menu that will display underlying code for X-Function Scripts.

1. In Script window, run smooth -d to open smooth dialog or use Analysis: Signal Processing: Smoothing menu to open it.
2. Change some settings, e.g. Method and Recalculation mode.
3. Click > button next to Dialog Theme on the top of the dialog and choose Generate Script".

   

4. The script is dumped in Script window

smooth -r 1 method:=fft;

Note: The Dialog Theme box and corresponding Generate Script fly-out menu item are not available from all X-Function dialogs that you open with the -d option (for instance, compare fitpoly -d with rnormalize -d).

The amount of information that is displayed using the Generate Script feature is controlled by a System Variable @GAS. By default, @GAS = 0 but this value may be changed via System Variables... in the Preferences menu.

Make an X-Function not callable in LabTalk

As we said at the beginning, most X-Functions are callable in LabTalk. To prohibit it from calling,

1. Choose Tools: X-Function Builder... menu.
2. Use File: menu to open the X-Function.
3. Choose Tools: Tree View menu (or the Tree View button) to see tree view of the X-Function.
4. Expand the Usage Context branch
5. Uncheck the checkbox in front of LabTalk
6. Save the X-Function.

Note: For built-in functions, you can't overwrite it. So you have to save it as a User-defined X-Function. When there are X-Functions with same name in User Files folder and System folder, the one under User Files folder will be used.

Related Links

• X-Function Overview
• X-Function Input and Output
• X-Function Execution Options
• X-Function Exception Handling
• Use X-Function in LabTalk Tutorial
• Calling X-Functions in Origin C