1 Note For Upgrade UsersUpgrade-LT-Note
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
|