1 Note For Upgrade Users

Introduction

These notes pertain to changes and improvements made to the LabTalk scripting language in Origin version 8.0. If you have script code developed in older versions such as 7.5, you may want to update your code to take advantage of the new features, as well as fix any compatibility issues with your script in later versions of Origin.

Key Limitations in Version 7.x

Many LabTalk commands act on an 'active' object such as a Worksheet, plotted data or column. This often required scripts to manage windows by remembering which window is a Worksheet and which is a Graph (or second Worksheet) and switch back and forth between these windows using the "window -a" command.

Variables were undeclared and global in scope.

Some Commands also can be destructive of data and require working on a copy if you need the original data.

Key Improvements in Version 8.0

Three additions to Origin 8 resolve the issues mentioned in the previous section. LabTalk programmers should familiarize themselves with these concepts:

Declared variables have context only in the procedure in which they are declared.

Range Variables can point to various Origin objects and eliminate the need for an object being active.

X-Functions can accept range variables as Input and Output, separate source data from analysis results, and automatically update analysis result when source data changes. Therefore it's a higher level of program function than regular LabTalk functions.

An Example

Suppose we want to look at Line graphs of the derivatives of data in multiple files.

The old way

In Origin 7.5, you could import multiple ASCII files into New sheets, New Columns or New Rows. These options can be manipulated by reading and writing a special structure in the worksheet, but Since the latter two would create a management headache, we will stick with New Sheets (the default). Since it would be difficult to know which sheets get created, we will delete the empty worksheet in a new Origin project before we begin.

Here is our import:

win -cd %H; // Delete the default Worksheet window
// Following causes prompt for files then imports
run.section(file,MultiImportToolbar);

We can loop over all the imported sheets using:

doc -e W { // Loop over all Worksheets
		...
	}

but the derivative command we need is destructive and we may want to keep the imported data, so we will add a copy of our data and use it for the derivative:

wo -a 1; // Add a column
copy col(2) col(3); // Column 3 is a copy of column 2
derivative col(3); // Column 3 is replaced with its derivative

To plot our data, we could create a graph window, remember it's name, loop over all worksheets (again), get the name of the data we want to add to the plot and temporarily switch to the graph to add the data.

Instead, I'll use a variable (count) so I know when I'm in the first pass of my Worksheet loop to create my first plot, then in subsequent loops, I will just note the name of the derivative data so I can temporarily switch to the graph (assuming I remembered its name) to add the data to my plot.

Here is our final script (comments removed):

win -cd %H;
run.section(file,MultiImportToolbar);
count = 1;
doc -e W {
	wo -a 1;
	copy col(2) col(3);
	derivative col(3);
	if( count == 1 )
	{
		wo -s 3 0 3 0;
		wo -p 200 LINE;
		%M = %H;
	}
	else
	{
		%N = col(3);
		win -o %M
		{
			layer -i %N;
		}
	}
	count++;
}
win -a %M;
layer -a;

The windows that are active (however briefly) in the above script are:

Worksheet1

Worksheet2

Worksheet3

Worksheet1

Graph1

Worksheet1

Worksheet2

Graph1

Worksheet2

Worksheet3

Graph1

Worksheet3

Graph1

An understanding of this sequence was a requirement to writing the code.

The New Way

Now let's make use of ranges and X-Functions and see how newer versions of Origin complete our task.

We begin with two X-Functions. The first prompts for the files to be imported, while the second directs how to import those files.

dlgfile gr:=*.dat mu:=1;
impASC options.ImpMode:=4 options.FileStruct.NumericSeparator:=0 options.Names.FNameToBk:=0;

It seems our old "run.section(file,MultiImportToolbar);" has been split in two, but the "dlgfile" function can be used in many other cases where we need to prompt for a file or files. The "impasc" X-Function now incorporates various options as part of its arguments, replacing many lines when options need to be modified.

Next, I'll declare a string variable which will be used for plotting:

string strRanges;

and then loop over each Worksheet (imported file) in our Workbook:

loop(ii,1,page.nlayers) // Our Workbook (a page) has multiple Worksheets (layers)
{
		...
}

Within the loop, I declare a range that points to the data I want a derivative of and use that range as an argument to the differentiate X-Function:

range raD = $(ii)!(1,2); // Our range references sheet by index using column 1 as X and column 2 as Y
differentiate iy:=raD; // Pass the range to the X-Function which defaults to creating new columns

Our string variable is used to define a string that's equivalent to a range syntax combining each range as a comma separated list:

if(ii == 1) strRanges$ = 1!(1,3);
else strRanges$ = %(strRanges$),$(ii)!(1,3);

When the loop exits, our string looks like this:

1!(1,3),2!(1,3),3!(1,3)

and our last line wraps this with parentheses:

strRanges$ = (%(strRanges$));

to create

(1!(1,3),2!(1,3),3!(1,3))

which the plotxy X-Function interprets as a multiple XY range to create the final plot with one command.

Here is our final code:

dlgfile gr:=*.dat mu:=1;
impASC options.ImpMode:=4 options.FileStruct.NumericSeparator:=0 options.Names.FNameToBk:=0;
string strRanges;
loop(ii,1,page.nlayers)
{
	range raD = $(ii)!(1,2);
	differentiate iy:=raD;
	if(ii == 1) strRanges$ = 1!(1,3);
	else strRanges$ = %(strRanges$),$(ii)!(1,3);
}
strRanges$ = (%(strRanges$));
plotxy %(strRanges$) plot:=200;

Incompatibilities

Some changes to the language accommodate new features or fix a problem can cause old scripts to break.

Here are some things to watch out for:

String assignment

When assigning values to a string variable,there should be no space between the variable name and '$'.

Old way:

str $ = "Hello"; // will not work now

New way:

str$ = "Hello";

String Registers

%D used to contain the name of the last Set Dataset. It now contains the Current Working Directory when executing commands in the Command or Script Window.

Column Justify

The property "wks.col#.justify" used to control left-center-right justification.

In new versions, use:

DoMenu 35152; // Left
DoMenu 35153; // Center
DoMenu 35154; // Right