5.1 Get Started with LabTalk


Summary

LabTalk is a scripting language in Origin, which can be used to perform importing, data analysis and graphing and publication by writing and executing script. The LabTalk script can be executed both independently, or as a part of an analysis dialog in the Origin GUI.

A LabTalk script is a single block of code that is received by the LabTalk interpreter. A LabTalk script is composed of one or more complete programming statements, each of which performs an action. Each statement in a script should end with a semicolon, which separates it from other statements.

The LabTalk programming statements can be written from several elements, which are: system variables, commands, functions, macros, objects and X-Functions.

There are many ways to run LabTalk script, the most frequent being from Script/Command Window, from .ogs files, or from a toolbar button and graphical objects.

What You Will Learn

In this tutorial, you will learn:

  • How to run LabTalk script from the Script Window or Command Window
  • How to run LabTalk script in an .ogs file
  • How to run LabTalk script from toolbar button/graphical object
  • Basic usage of each LabTalk elements
  • A comparison of different ways to run LabTalk script

Steps

Run Script From Script/Command Window

The Script Window and Command Window are most commonly used to execute LabTalk script, each supports both single and multiple lines of script execution.

The Script Window has only a cursor and will execute highlighted code or code at the current cursor position when you press Enter, while the Command Window has a prompt and will execute all code entered at the prompt.

The Command Window includes auto-completion and hint for X-functions and command history, and supports recall of line history, however the Command Window history is not editable as from Script Window. User should choose to run script in either windows based on his/her own needs.

From Script Window

  1. Open Origin, select Window:Script Window (or press Alt + Shift + 3) to open the Script Window.
  2. Make sure Edit:Script Execution is selected from the menu items of the Script Window.
  3. In the Script Window, type the following text and press Enter to run the script:
    type -b "Hello World"
    An attention box will pop up, displaying the "Hello World" text, which means the script was executed successfully.
  1. Press OK to close the attention box. Copy and paste the following script into the Script Window. To execute, select the three lines of pasted text and press Enter. The script creates a new workbook with 4 columns, and types the workbook name (stored in a string register %H) and number of columns (stored in a substitution notation $(wks.ncols)) to the script window:
  2. newbook;
    wks.ncols=4;
    type -a "In %H, there are $(wks.ncols) columns."
  3. Now we will learn how to type in multiple lines to script window without executing the current line.
  4. We would type in the following script (4 lines) one by one:
  5. loop(num,1,4)
       {
          num =;
       }
  6. Clear all the contents in the Script Window and deselect Edit:Script Execution from the Script Window menu items.
  7. This disables script execution, so you can then type in the four script lines above one by one, using Enter to create new line.
  8. When you finished typing, select Edit:Script Execution again and highlight the four lines you just typed, hit Enter to execute.


From Command Window

  1. Open Origin, select Window:Command Window (or press Alt + 3) to open the command window.
  2. Follow the steps 3 and 4 above and run both script examples in the command window. For the second script example you do not need to highlight all script to execute.

An alternative to type multiple lines without execution is to use Ctrl+Enter to create a new line. This can be used in both Script Window and Command Window.

Run Script From OGS File

  1. Paste the following script into an empty Script Window:
type -b "HELLO WORLD";

[Section1]
type -a "Hello";

[Section2]
type -a "World";
  1. Click File(Text):Save As... from the top menu of Script Window and save the script as Test.ogs in your User Files Folder.
  2. Open the Command Window (Window:Command Window or Alt + 3) and type the following text and click Enter:
  3. run.file(Test)
    run.file( ) is a method of the Labtalk Run Object. It executes the script in the specified .ogs file provided it occurs in the beginning of a file before any named section.
  4. Click OK to close the attention box displaying "HELLO WORLD", and type the following in the Command Window and click Enter:
  5. run.section(Test, Section1)
    run.section( ) is also a method of the Run object. It executes the script in the named section of the specified .ogs file.
Notes: If the .ogs file is not saved under the User Files Folder, full file path will be needed when the run.file( ) or run.section( ) method is used.
The .ogs extension is not needed for either method.
A script executed by either method terminates when it encounters a named section (or a return statement).
Type statements direct their output to the Window which executed the command.


Run Script From Customized Buttons

From Toolbar Buttons

  1. Make sure you have the Test.ogs file saved in User Files Folder from the previous section.
  2. Open Origin and make sure both Script Window and Command Window are closed.
  3. Select View:Toolbars from top menu to open the Customize dialog for toolbars, go to the Button Groups tab and select User Defined under the Groups section. Note that there are 10 buttons in the group.
  4. Click the Add button under Button section and select 7 for Button Image in the popped-up Add Button dialog.
  5. Click OK and an additional Run button is added to the buttons thumbnail list:
    LT Tutorial Get Started 01.png
  6. Click on the second Run button and click the Settings... button to open the Button Settings dialog.
  7. Click the Browse button right to the File Name box and select the Test.ogs file you created under User Files Folder.
  8. Type Section1 for Section Name. Click OK to apply the settings and close the dialog.
  9. Drag the button onto the Origin workspace and then close the Customize dialog.
  10. The button will be floating in the Origin interface, click this button to run the script, you will see the Script Window is opened and text "Hello" is typed.


From Graphical Objects

  1. Click the Button New Graph.png button to create an empty graph.
  2. Right click on the blank area on the graph and choose Add Text from context menu, type Run2 as the label text.
  3. Select the text object, right click and choose Programming Control to open the Programming Control dialog. choose Button Up for Script, Run After, and type the following script to the script edit box:
    run.section(Test, Section2);
    LT Tutorial Get Started 02.png
  4. Click OK and the text label becomes a button. Click on the Run2 button to execute the script added to its script edit box.

Once a graphical object becomes a button, you can use Edit Mode(Edit:Edit Mode or Ctrl + Alt + B) to edit its properties or hold down the Alt key and double-click the button. If you use Edit Mode, remember to select it again to turn it off.

Notes:
  1. You must have an .ogs file in order to run script from a toolbar button, while you can just enter lines of LabTalk script in the script edit box of graphical objects.
  2. Edit Mode is called Button Edit Mode in versions prior to Origin 2017.

LabTalk Elements

Usage and examples of different LabTalk elements are summarized below:

A read only or read/write variable to monitor or control Origin behavior.
Example: use the @ASC system variable to check and change the number of megabytes needed to trigger auto save checking.
//Run the following script line to get the variable value
@ASC = ;
//Run the following script line to set the variable value to be 10 (MB)
@ASC = 10;
A statement ( which may include option switches ) to carry out a defined task.
Example: use the Type command and its -n option.
//Display string in a dialog box with Yes and No buttons
type -n "Do you want to continue?";
type -a Script continues here since you clicked Yes.;
A statement which optionally includes arguments in parentheses to return either a single value or a range of values (a dataset)
Example1: use the Left( ) function to process strings
//Define a string "Hello World" first
string str1$ = "Hello World";
//Use the function to get the first 5 characters of the pre-defined string
string strLeft$ = Left(str1$,5)$;
strLeft$ = ; //should return Hello
Example2: Some functions can appear on the left side of an equation
//Fill column A with a defined sequence of numbers
col(A) = data(600,850,10); // Fill column A with 600 to 850 in steps of 10
Associate a new variable name with given script which can later be used as a command and include arguments.
Example: define a simple macro and use it later.
Run the following script first to define a macro named as testmacro
def testmacro
{
	repeat %1
	{
		repeat %2
		{
			type -l "=";
		}
		type;
	}
}
Then run the following line to execute the pre-defined script in this macro
testmacro 2 64; // '2' is substituted for %1 and 64 for %2
An object (visible or not visible) whose properties and methods can be accessed via LabTalk.
Example1: See the run.file( ) and run.section( ) example in the section 3.2, where two methods of the Run object were used.
Example2: Run the following script to return the program path property of the system.path object
System.path.program$ = ;
//The directory path of Origin's executable (.EXE) file should be returned
A primary tool for executing tasks and tapping into Origin features from your LabTalk scripts.
Example: use the newbook x-function to create a new workbook with specified book name and sheet number
Run the following script:
//The workbook will be named as Test1 (both long and short name)
//There'll be 5 worksheets in this workbook
newbook name:=Test1 sheet:=5 option:=lsname;
A function properly implemented with Origin C can be called by LabTalk script.
Example: create an Origin C function and call it via LabTalk
Open Code Builder and create a new .c file, paste the following OC code:
double CubeRoot(double x)
{
	if(x < 0)
		return -10^(log10(abs(x))/3);
	else
		return 10^(log10(x)/3);
}
Compile the Origin C function and you can use this MyFunc function by running the LabTalk script:
double aa = CubeRoot(125);
aa = ;//It should return aa=5