5.2 LabTalk Language Fundamentals

Summary

LabTalk supports variables of many data types. Using these variables with different statements is the basic idea of scripting. A variable used without a type declaration is by default type double or string and has project scope (exists as long as the Origin project is open and can be saved with the project).

As in the C language, a statement in LabTalk ends with a semi-colon (';'). There are flow control statements where you can define a block of code to be executed, where the block is delimited with curly braces ('{' and '}').

Variables declared in a block have a scope which is destroyed when leaving a block.

What You Will Learn

This tutorial will show you how to:

  • define and use variables of different data types
  • write command statements to control program functions
  • construct conditional or loop structures
  • use built-in/user-defined functions for operations

Basic Programming Syntax

LabTalk supports nine data types: double, integer, constant, dataset, string, stringarray, range, tree and graphic objects. LabTalk script is based on the definition (or declaration) of variables and the manipulation of them.

In LabTalk, five types of statements are used. They are assignment, macro, command, arithmetic and function statements.

Examples of basic programming syntax will be introduced in this section of tutorial.

  1. Define variables without declaration so that they will be project variables.
  2. // Define a project variable of type double:
    aa = 3.5;
    // Define a project variable of type string:    
    str$ = "Hello";
  3. Define numeric variables bb (as double), nn (as integer) and c1(as constant) as session variables.
  4. double bb = 1.234; // Declare and assign
    double cc; // Declare
    cc = 9.876; // Assign
    int nn;
    //You must assign a value when declaring a constant
    //And the constant value cannot be changed.
    const c1 = 0.5;
  5. Define a string variable and then store it in a string register.
  6. //Use the following scripts to define strings 
    string greeting$ = "Hello World";
    %A = greeting$;
    //Use the following script to get string value
    greeting$ =;
    %A =;
  7. Define another string with the texts "greeting$" without recognizing it as a string variable.
  8. //The "+" is an operator for string concatenation
    %B = "greeting" + "$";
    //Return the value in string register %B
    //It should return the texts greeting$
    %B =;
  9. Define a string variable with the text "%B" without recognizing it as a string register.
  10. //Normally, % plus any letter is interpreted as one of 26 string registers.
    //By prefixing a % symbol you can stop the substitution:
    string str1$ = %%B;
    //Return the value in string variable str1
    //It should return %B
    str1$ =;
  11. Declare a dataset as temporary loose dataset, i.e. it will not be associated with a worksheet, will not be saved with the Origin project and can be used for calculation but not plotting.
  12. //Declare this dataset as a numeric series from 1 to 10 with increment 0.5
    dataset aa = {1:0.5:10};
  13. Create a project-level loose dataset by assignment, or by using the create command.
  14. //By assignment
    temp = {10,9,8,7,6};
    //By create command
    //Create a XY loose dataset "tmpdata" and define row number as 5
    create tmpdata -wdn 5 X Y;

    Note: A command statement begins with the command itself or its abbreviation, as long as it's unique (in this example, "create" is the command). Most commands can take options, which are preceded by the dash "-" symbol (in this example, "-wdn" is the option or switch). Both the command itself and its option can take arguments (in this example, "tmpdata" is the argument for command and "5 X Y" are arguments for the -wdn option.)

  15. Two dataset variables will be created by the create command, they are tmpdata_X and tmpdata_Y. Pass numeric values to tmpdata_X one by one.
  16. tmpdata_X[1] = 1;
    tmpdata_X[2] = 2;
    tmpdata_X[3] = 2.5;
  17. Pass the values into dataset tmpdata_Y by existing dataset.
  18. tmpdata_Y = temp;

    You can use the project-level dataset (e.g. tmpdata_X and tmpdata_Y) for plotting, but you cannot use the session-level dataset (e.g. aa) for that purpose.

    To plot you can use the following script:

    plotxy iy:=tmpdata_Y plot:=202;
  19. Define a string array and add string members to it.
  20. StringArray stra;
    stra.Add("Hello");
    stra.Add("World");
  21. Use the following script (a loop structure, which will be further introduced in the section below) to print out the strings in string array stra.
  22. loop(ii,1,stra.GetSize())
    {
      string str$=stra.GetAt(ii)$;
      str$=;
    //It should return
    //Hello
    //World
    }

    You can use the "list" and "del" command to view and delete variables. There's also a LabTalk Variable Viewer which you can access by running the script:

    list;

Conditional and Loop Structure

Loops

A loop allows the program to repetitively perform a set of actions. LabTalk provides four loop commands: repeat, loop, doc -e and for.

The repeat loop is used when a set of actions must be repeated without any alterations.

The syntax is: repeat value {script}

  • Execute the following script to output a line in script window for 6 times and keep track on the times of repeated actions.
int count = 1;
repeat 6 {type "this is output line $(count)"; count = count + 1;}

The loop loop is used when a single variable is being incremented by 1 with each successive loop.

The syntax is: loop (variable, startVal, endVal) {script}

  • Execute the following loop to assign values to a newly created dataset.
//Create a dataset (50 rows) which is not associated with a worksheet
create loopdata -t 50;
//Pass values into the dataset with a loop
loop(ii, 1, 50)
{
  loopdata[$(ii)] = ii^2;
}

The for loop is the most general one, which can be used for all other conditions.

The syntax is:for (expression1; expression2; expression3) {script}

In this syntax, expression1 specifies the initialization, expression2 is evaluated to determine whether to execute the script(if true) or to terminate the loop (if false), expression3 is executed at the end of each loop, it is often the increment of a counter. Both expression1 and expression3 can consist of multiple statements separated by commas as in

for(ii = 1, jj = 9; ii <= 5 ; ii++, jj++)
{
ty $(ii), $(jj), $(ii+jj);
}
  • Execute the following loop to output every 10th value in the loose dataset loopdata we just created.
//You need to declare a dataset object ld first 
//in order to use the dataset.GetSize() method
dataset ld = loopdata;
for(jj = 1; jj <= ld.GetSize(); jj = jj + 10)
{
  ld[$(jj)] =;
}

The doc -e loop is used when a script is being executed to affect objects of a specific type, the different object types are documented with the document command.

The syntax is: doc -e object {script}

  • Execute the following loop to output the name of each dataset in the Origin project (including worksheet columns and project-level loose datasets).
doc -e S
{
  %C =;
}

Decision Structures

Decision structures allow the program to perform different sets of actions depending on the circumstances. LabTalk has three decision-making structures: if, if-else, and switch.

The if command is used when a script should be executed when a particular expression is true. If it's combined with the else command, another script will be executed if the particular expression is false.

The syntax is: if (testCondition) {script1} [else {script2}]

  • In an Origin project file, make sure there is one workbook, one graph window one matrix window and one Layout page. Activate them and run the following script one by one to determine window type:
if(exist(%H)==3)
      type -b "A graph window is active";
else
      if(exist(%H)==2)
            type -b "A worksheet is active";
      else
            type -b "Neither a graph nor worksheet is active";

The switch command is used when more than two possibilities are needed in a script.

For example the script above with the if-else structure can be modified as below:

switch(exist(%H))
{
    case 3:
       type -b "A graph window is active";
       break;
    case 2:
       type -b "A worksheet is active";
       break;
    case 5:
       type -b "A Matrix is active";
       break;
    default:
       type -b "Neither a graph, worksheet nor matrix is active";
       break;
}

LabTalk Functions

LabTalk supports many operations through built-in functions, which are called with the syntax:

outputVariable = FunctionName(Arg1 Arg2 ... ArgN);

Also, you can create user-defined functions with the syntax below:

function dataType funcName(Arg1 Arg2 ... ArgN) {script;}

In a function, both arguments and return values support string, double, int, dataset and tree data types.

  1. First declare a user-defined numeric function by calling built-in functions. This function will generate a Julian date value from a random numeric value.
  2. function double JDate(double num)
    {
       //Calculate an integral from the double number
       int x = int(exp(num)*1000); 
       //Generate the day, month and year integral with remainder function mod() 
       int iDay = mod(x, 27) + 1;
       int iMonth = mod(x, 11) + 1;
       int iYear = 2013 - mod(x, 5);
       //Define a string as MM/DD/YYYY
       string jd$ = $(iMonth)/$(iDay)/$(iYear);
       //Return the Julian date number from the string as the function result 
       //The string will be substituted with %() notation
       return date(%(jd$));
    }
  3. Call the user-defined function JDate to calculate a Julian date from a numeric value, e.g. 0.83.
  4. //calculate the Julian date and pass it to double variable jda
    double jda = JDate(0.83);
    //Output the numeric value of jda
    jda =;//Should return 2455373
    //Display the date with format MM/DD/YYYY
    type $(jda, D0);//Should display 6/26/2010
  5. Create a new workbook with 2 columns, right click on the first column (column A) and choose Fill Column With:Normal Random Numbers to fill in the column with random numeric values.
  6. Note: You can also run the following script to get the random values filled in the first column with the csetvalue x-function:

    newbook;
    wks.nCols = 2;
    csetvalue col:=1 formula:="grnd()";
  7. Use the JDate function to calculate a Julian date in column B.
  8. col(B) = JDate(col(A));
  9. Change the column format to Date.
  10. wks.col2.format = 4;