Copyright: Copyright


Help Contents
Contents

Welcome to LabTalk!

LabTalk

Command Reference

Object Reference

Built-in Function Reference

Macro Reference


Welcome to LabTalk!

Introduction

Help File Conventions


LabTalk

Script Execution

Identifiers

Data Types

Operators

Substitution Notation

Keywords

Programming


Command Reference

Introduction

Command Reference by Category

Alphabetical Listing of Commands


Object Reference

Introduction

Object Properties and Methods

Internal Object Overview

External Object Overview

Alphabetical Listing of Objects


Built-in Function Reference

Introduction

Utility Functions

Mathematical Functions

Statistical Functions


Macro Reference

Introduction

Defining and Displaying Macros

Executing LabTalk Macros

Listing and Deleting Macros

Special Event Driven Macros

Predefined System Macros


Welcome to LabTalk! - Introduction
Introduction

What is LabTalk?

Advantages of using LabTalk


What is LabTalk?

LabTalk® is a full-featured programming language which has access to all of Origin®'s operation.  Its syntax and structure are similar, but not identical, to C.  LabTalk incorporates DOS-style commands with option switches and arguments.  It also includes object properties and methods comparable to those in Visual Basic.

A complete LabTalk instruction is called a statement.  Any block of text, whether one statement or several, which is sent to the LabTalk interpreter is referred to as a script.  Most LabTalk scripts are executed from the Script window, a script file, or from an object, such as a button.  The following examples illustrate what different types of LabTalk script look like.

The following script uses the type command to print the message enclosed in quotations to the Script window.

type "This will print out in the Script window!";

The next script sets the width and height properties of the page object.  This script changes the width of the active page to 1000 pixels and the height to 2000 pixels.

page.width=1000; page.height=2000;

The following script uses the if command.  If the variable num is less than 100, the script enclosed in brackets executes.  The executed script uses the delete command, modified by the -v option, to delete the num variable.

if (num < 100) { delete -v num; };


Advantages of using LabTalk

The Origin software is written so that it can be used successfully without ever writing a LabTalk script.  The majority of data analysis and plotting functions can be accessed through Origin's point-and-click interface.  However, using LabTalk script provides a greater degree of automation, customization, and flexibility when using Origin.

LabTalk allows you to control every aspect of Origin.  For example, you can perform the following using LabTalk:

Add or customize menu commands.

Create buttons to execute any built-in or user-defined task.

Define macros for actions such as sorting data by time or making a specialized legend.

Perform batch processing of datasets on import.

Interpret your data using a user-specified function or look-up table.

Arrange Dynamic Data Exchange (DDE) with other Windows applications.


Help File Conventions

The following conventions are observed in this Help file:

Italicized text indicates the information is not literal.  Rather, the italicized text serves as a placeholder for literal text.  Supply or interpret the appropriate literal text.  For example, Plot:Scatter.  (Note:  Text may also be italicized for emphasis.  This difference should be clear by context.)

The names of datasets are displayed in bold.

Menu commands are displayed in bold.  Levels are separated by a colon.

File names are displayed in uppercase characters.

Keyboard keys are displayed in uppercase characters.

Bold font indicates LabTalk script that can be entered verbatim.

Italicized + bold font indicates a user-supplied argument that cannot be entered verbatim.  Serves as a placeholder for literal text.  Usually used in syntax examples.

Statements which are commented are marked by // comment .  These are not functional parts of the script and can be omitted.

Items in brackets are optional.

Parentheses are used to enclose text strings.

Braces are used around a script, when associating the script with a command.

Angle brackets indicate that the argument(s) to a command can only be used when no option is given.

[range] may appear in the command syntax line of commands that take a dataset as an argument.  It indicates that the range modification options can be used to set the active range of the dataset.  The command affects only the active range of the dataset.

There are three range modification options:  -b, -e, and -t.  They offer two methods of implementation:

-b firstPoint -e endPoint

Sets the beginning and final index numbers of the active range.

-b firstPoint -t totalPoints

Sets the total number of points in the active range, beginning at firstPoint.


Script Execution

Once you have written your LabTalk script, it can be sent to the interpreter for execution from a variety of sources.  The most important sources are:

The Script window.

The Label Control dialog box.

Command arguments.

Script files.

Menu commands.

More:

The Script Window

Associating a Script with an Object

Script as a Command Argument

Script Files

Menu Selection


The Script Window

The Script window is a standard text editor with the additional feature of carrying out LabTalk script execution.  To open the Script window, perform one of the following operations:

Select Window:Script Window.

Click the Script Window button on the Standard toolbar.

Press ALT+3.

To execute a script, the Script window must be in script execution mode.  To enter script execution mode, select Edit:Script Execution from the Script window menu bar.  The menu command is checked when in script execution mode.

The Script window executes a single script at a time.  There are two ways to execute a script from the Script window:

Type the text into the Script window and press ENTER.  The text from the beginning of the line to the current cursor position is sent to the interpreter as a single script.  After pressing ENTER, Origin appends a semicolon to the end of the line to indicate the script was executed.  (Caution:  When executing a single line script in the Script window, do not end the line with a semicolon.  If you do, the script will not execute.)

Highlight the text to be executed and press ENTER.  The entire highlighted text is sent to the interpreter as a single script.  If the Script Execution menu command is disabled and you highlight the script and press ENTER, the script is deleted.  Select Edit:Undo from the Script window menu bar to re-display the script.


Associating a Script with an Object

A script can be placed in the Label Control dialog box of any object, including arrows, text labels, and UIM objects (UIM objects are provided in the Origin Professional package).  This is a powerful method of script execution as the associated script can be executed under a variety of conditions.  In addition, the object and its script can be saved as part of a template, window, or project.

To open the Label Control dialog box, hold down the ALT key and double-click on the object.  (Alternatively, click on the object and select Format:Label.)  Enter the desired script in the associated text box of the Label Control dialog box.

The script executes according to the selection made in the 'Script, Run After' drop down list of the Label Control dialog box.  The options include, but are not limited to:

Execute when the object is clicked with the mouse.

Execute when a window is opened, closed, or moved.

Execute before the project is saved.

Execute when graph axes are rescaled.

Execute when the object's child window becomes active.


Script as a Command Argument

Several LabTalk commands take a script as an argument.  These include:  define, for, if, menu, queue, and repeat.  The script argument must be enclosed in braces.  For example:

define macroName {script};

illustrates the general form of the define command.

Note:  When using commands that take a script as an argument, remember that the argument is sent to the interpreter as a single script, and follows the same syntax rules for scripts.


Script Files

A script file is an ASCII text file.  Script files are external to the Origin application.  As such, they are easy to edit or replace, and do not require that you recompile the application each time you make a change.

There are several ways to execute a script file:

You can execute a section of a script file by creating a user-defined toolbar button on a new or existing toolbar.  User-defined toolbar buttons are created and modified on the Commands tab of the Customize Toolbars dialog box.  To create a button, select View:Toolbars, select the Commands tab, and then select User Defined from the Categories list box.  You can then click a button in the Buttons group and click the Modify button.  This action opens the Button Settings tab.  Specify a script file section, arguments to pass to the script file, and the window sensitivity in this dialog box.

Origin includes a Custom Routine button on the Standard toolbar.  Click this button to run custom script that you have added to the [Main] section of the CUSTOM.OGS file.

A configuration file, for example, is a script file with a .CNF file extension.  On start-up, Origin reads the ORIGIN.INI initialization file and executes the configuration file(s) associated with the current menu level.

The run command offers another way to execute a given script file.  This command uses the following syntax:

run ScriptFileName;

The run object has two methods (file and section) which can be used to execute a script file.  The run.file(FileName) method executes the file FileName, where FileName contains LabTalk script.  The run.section(FileName,SectionName) method expects a file that is divided into sections of LabTalk script, each having section names.

For example, the file, EXAMPLE.SCR could contain the following sections:

[SectionA]

...include lines of LabTalk script here...

[SectionB]

...more lines of LabTalk script...

[SectionC]

...still more lines of LabTalk script...

To execute the script following SectionB, use the following run.section( ) method:

run.section(example.scr,sectionb);


Menu Selection

Most Origin menu commands are written in LabTalk.  The text of each menu command is a single script, which is associated with a menu command name.  The script is executed when you select the menu command.

To display the script associated with a particular menu command, perform the following:

1)	Open the Script window by selecting Window:Script Window.

2)	Press the CTRL and SHIFT keys and select the desired menu command.

If there is a script associated with that item, it displays in the Script window (but does not execute).  The menu ID# for the menu command also displays.

Use the menu command and menu object to alter menu scripts or add your own scripts to the Origin menus.


Identifiers

Variable, dataset, command, and macro names are known as identifiers.  Identifiers are composed of any combination of letters and numbers, but cannot be more than 25 characters in length.  In addition, the first character cannot be a number.

Note:  The underscore character "_" has a special meaning in dataset names and should be avoided.

Use the exist(identifier) function to check if an identifier is being used to name a window, macro, tool, dataset, or variable.


Data Types

Data objects represent values that can be combined into mathematical expressions.  Origin recognizes four classes of data objects:  numeric variables, string variables, datasets, and functions.

More:

Numeric Variables

String Variables

Datasets

Functions


Numeric Variables

A variable is a space set aside for data in the computer's memory.  Each variable is given a name, or identifier, with which its data can be assigned or accessed.  LabTalk numeric variables hold double precision real numbers which can accurately represent the standard variable types:  integer, long, and float.

A LabTalk variable CANNOT:

Start with a number.

Start with an operator.

Contain a period (.).

The assignment operator "=" is used to simultaneously create a variable (if it does not already exist) and assign to it a value.  For example, entering the following assignment statement in the Script window:

A=52

creates the variable A, and sets A equal to 52.

To see the value of a variable, type the variable in the Script window, followed by an equal sign:

A=

Press ENTER and Origin responds with:

A=52

Note:  When entering a single line script in the Script window, do not end the line with a semicolon.  Origin appends a semicolon to the end of the line during script execution.


String Variables

String variables are named spaces in computer memory which hold strings, which are one-dimensional arrays of characters.  String variables are used to store text.  All string variable names are comprised of a % character followed by a single alphabetic character (a letter from A to Z).

More:

Assigning Values to a String Variable

Expressing the Variable Before Assignment

String Comparison

Substring Notation

Long-term String Storage


Assigning Values to a String Variable

Entering the following assignment statement in the Script window:

%A=John

defines the contents of the string variable %A to be John.  String variables may also be used in substitution notation.  Using substitution notation, enter the following assignment statement in the Script window:

%B=%A F Smith

to set %B equal to John F Smith.  Thus, the string variable to the right of the assignment operator is expressed, and the result is assigned to the identifier on the left of the assignment operator.  For more information, see  Substitution Notation.

As with numeric variables, if you enter the following assignment statement in the Script window:

%B=

Origin returns the value of the variable:

John F Smith


Expressing the Variable Before Assignment

In the previous example (%B=%A F Smith), the string variable on the left of the assignment operator (%B) was not expressed.  By using parentheses, the string variable on the left of the assignment operator can be expressed before the assignment is made.

For example, enter the following assignment statement in the Script window:

%B=Data1_A

This statement assigns the string variable the value Data1_A.  If Data1_A is a dataset name, then entering the following assignment statement in the Script window:

(%B)=2*%B

results in the dataset being multiplied by 2.  %B, however, still contains the string Data1_A.


String Comparison

When comparing string variables, use the equal to operator (==).  If the string variables are surrounded by quotation marks (for example, "%a"), then Origin compares the string characters.  If the string variables are not surrounded by quotation marks (for example, %a), then Origin compares the values of the string variables.

For example:

aaa=4;

bbb=4;

%A=aaa;

%B=bbb;

if (%A==%B)

    type "YES";

else

   type "NO"

The result will be YES, because in this case the values of the variables (rather than the strings) are compared, and aaa==bbb==4.

However, in the following example:

aaa=4;

bbb=4;

%A=aaa;

%B=bbb;

if ("%A"=="%B")

    type "YES";

else

    type "NO";

The result will be NO, because in this case aaa != bbb.


Substring Notation

Substring notation returns the specified portion of a string.  The general form of this notation is:

%[string,argument];

where string contains the string, and argument specifies which portion of the string to return.  For the examples which follow, enter this assignment statement in the Script window (the open and close quotations are optional):

%A="Results from Data2_Test"

The following examples illustrate the use of argument in substring notation:

To do this:  Search for a character and return all text to the left of the character.

Enter this script in the Script window:  %[%A,'_']=

Return value:  Results from Data2

To do this:  Search for a character and return all text to the right of the character.

Enter this script in the Script window:  %[%A,>'_']=

Return value:  Test

To do this:  Return all text to the left of the specified character position.

Enter this script in the Script window:  %[%A,8]=

Return value:  Results

To do this:  Return all text between two specified character positions (inclusive).

Enter this script in the Script window:  %[%A,14:18]=

Return value:  Data2

To do this:  Return the #n token, counting from the left.

Enter this script in the Script window:  %[%A,#2]=

Return value:  from

To do this:  Return the length of the string.

Enter this script in the Script window:  ii=%[%A];ii=

Return value:  ii=23

Other examples of substring notation follow:

To do this:  Return the iith token separated by a specified separator (in this case, a tab).

Enter this script:

%A=123   342   456;

for (ii=1;ii<=3;ii+=1){

data1_a[ii]=%[%A,#ii,\t]

};

Return value:  Places the value 123 in data1_a[1], 342 in data1_a[2], and 456 in data1_a[3].

To do this:  Return the @n line.

Enter this script:

%Z="First line

second line";

%A=%[%Z,@2];

Return value:  Places the second line of the %Z string into %A.  To verify this, type %A= in the Script window.

Note:  For more information on typing script on multiple lines in the Script window, see  Using Semicolons in LabTalk.

When using substring or substitution notation, space characters are not ignored when quotation marks are used.  Furthermore, the string length notation includes space characters.  For example, to set %A equal to <space>5<space>, type the following in the Script window:

%A = " 5 "    (ENTER)

To find the length of %A, type the following in the Script window:

ii=%[%A];ii=    (ENTER)

Origin returns ii=3.

A Note on Tokens

A token can be a word surrounded by white space (spaces or TABS), or a group of words enclosed in any kind of brackets.  For example, if:

%A=These (are all) "different tokens"

then entering the following in the Script window:

%[%A,#1]= 	returns These

%[%A,#2]= 	returns are all

%[%A,#3]= 	returns different tokens


Long-term String Storage

String variables are generally intended for use in short-term storage.  To store a string variable for longer periods, save the string in a worksheet.  Alternatively, string variables may be stored in Origin Professional UIM objects.  Origin Professional provides a variety of specialized graphic objects, such as check boxes, radio buttons, and gauges.


Datasets

A dataset is an object consisting of a one-dimensional array that can contain numeric and/or text values.

The individual values in a dataset are called elements.  Each element in a dataset is associated with an index number, by which individual elements can be accessed.  In a worksheet, the index number corresponds to the row number.

A dataset is often associated with a worksheet column and/or one or more data plots.  Datasets are defined such that, when a dataset is deleted, associated worksheet columns and data plots are also deleted.

More:

Creating a Dataset

Dataset and Worksheet Names

Assigning Values to a Dataset

Accessing Text Datasets

Using Datasets as Functions

Working with Excel Workbook Datasets in Origin


Creating a Dataset

Origin provides a number of ways to create datasets:

When a worksheet is created, Origin creates one dataset object for each worksheet column.  The datasets take their names from the worksheet name followed by an underscore character and the column name.

A worksheet with an X and Y dataset can be created with the worksheet command.  Use worksheet -t winType template [winName] to create a worksheet named winName based on the template template.

Datasets can be created using the create command.  By default, the create command creates a numeric dataset.  To create a dataset that can store strings, use create -s.

Datasets can also be created using the data( ) function.  For example, entering the following script in the Script window:

Sample1=data(100,800,3)

creates the dataset Sample1, with values that begin at 100, end at 799 (802 exceeds 800), and increment by three.  To display the dataset in the Sample1 worksheet, enter the following script in the Script window:

edit Sample1


Dataset and Worksheet Names

Every dataset is associated with a unique name, which follows the naming conventions for identifiers.  For information on identifier naming conventions, see  Identifiers.

If the dataset name contains an underscore character " _ ", the part of the name that precedes the underscore becomes the worksheet name, while the part that follows the underscore becomes the column name.  If there is no underscore, the column is not named.  For example, entering the following command in the Script window:

create ExperimentalData_Series1 1000

creates a dataset named ExperimentalData_Series1, which has 1000 values.  By default, the dataset values are zero.  When you associate a worksheet with this dataset, for example, by entering the following command in the Script window:

edit ExperimentalData_Series1

Origin creates a worksheet named ExperimentalData containing an A(X) and Series1 column.  The data markers for the worksheet are set to display 1000 values.


Assigning Values to a Dataset

Assign values to a dataset by performing one of the following:

1)	Enter values directly into a worksheet column.  For example, when you open a worksheet, each worksheet column is associated with a dataset.  Entering values in the worksheet necessarily assigns those values to the associated dataset.

2)	Use the dataset in an assignment statement.

To create a dataset with multiple known values use the following syntax:

datasetname={v1, v2,...vn};

where v1, v2, ... vn are literal values, meaning the actual values are entered.  For example:

data1_a={2,5,9,17,32}

Entering the following assignment statement in the Script window:

data1_b=data1_a

sets every value in data1_b equal to the value at the corresponding index number in data1_a.

Entering the following assignment statement in the Script window:

data1_a=9

sets every value in data1_a equal to 9.

You can also use datasets in expressions in an assignment statement.  The following example illustrates this option:

data1_a=data1_a*data1_b+2

Origin supports direct arithmetic operations on datasets from the Script window.  (You can not use this feature from any location but the Script window.)

For example, to add 5 to all highlighted cells in a worksheet column, enter the following in the Script window:

+5

Origin applies this arithmetic operation to %C.

To access specific dataset elements, use the following syntax:

datasetname[i]=value;

or

%(WorksheetName,ColumnNumber,RowNumber)=value;

For example, enter the following assignment statement in the Script window:

data1_a[3]=9

to set the element at index number (row number) 3 in data1_a to 9.

The col(colname) function may also be used to assign values to a dataset.  Colname is the name or numerical position of a worksheet column.  To use the col(colname) function, the dataset must be associated with a worksheet, and the worksheet must be the active window.  For example, if the data1 worksheet is active, entering the following assignment statement in the Script window:

col(a)=col(b)

is identical to entering:

data1_a=data1_b

If column a and column b are the first two columns in the worksheet, the following assignment statement can be entered in the Script window:

col(1)=col(2)

In addition, the col( ) function can use brackets to access a specific worksheet element.  For example, entering the following script in the Script window:

n=col(A)[2];n=

returns the element in row 2 of column A (in the active worksheet).

The col( ) function can also be used to assign values to a dataset.  The following example creates the dataset NewData_B (if necessary) containing the sum of the values in columns 2 and 3 in the active worksheet:

NewData_B=col(2)+col(3);

The next example fills each cell (from ii=1 to ii=109) in column A of the active worksheet with the square of the row number:

for (ii=1;ii<110;ii+1){col(a)[ii]=ii^2};


Accessing Text Datasets

The following examples illustrate the syntax used to access text datasets (or those set to Text & Numeric).  Note the addition of the $ character.  Replace i for the actual row number.

col(A)[i]$="any text";

%A="any text";col(A)[i]$=%A;

Data1_A[i]$="any text";

%A=col(A)[i]$;

%A=Data1_A[i]$;


Using Datasets as Functions

Origin allows a dataset to be used as a function.  When using a dataset as a function, the X column of the worksheet holds the search values, while a specified Y column holds the return values.  To use datasets as functions, use the following syntax:

Variable=WksName_ColName(Xvalue);

where WksName_ColName is the name of the Y dataset you want to extract a value from.  Xvalue is the X value you are searching for (in the X dataset).  If Xvalue is found in the X column, the command assigns the corresponding value in the Y column (WksName_ColName) to Variable.  If Xvalue was not found in the X column, this command uses linear interpolation between the two nearest values to find a Y value to return.

The following example illustrates the command:

1)	Enter the following values into the Data1 worksheet:

A	B

1.1	0.78

2.5	0.89

3.9	0.86

4.7	0.65

5.6	0.72

2)	Enter the following assignment statement in the Script window:

var=Data1_B(4.7)

3)	Enter the following statement in the Script window:

var=

Origin returns the value 0.65.


Working with Excel Workbook Datasets in Origin

Datasets in the Excel workbook can be accessed using LabTalk.  However, accessing workbook datasets differs from accessing Origin worksheet datasets.

When a workbook contains multiple sheets, each workbook sheet has an associated hidden Origin worksheet layer in the workbook window.  If you change the active workbook sheet, before issuing a LabTalk command to access a dataset on the sheet, you must update Origin regarding the sheet change.  To update Origin after changing sheets, enter the following command in the Script window:

layer -s

This command makes the hidden Origin worksheet layer (that is associated with the currently active sheet) active and receptive to LabTalk commands.

The layer -s command must also be executed if you add a sheet to your workbook.  After executing the command, Origin creates a hidden Origin worksheet layer that is associated with the new workbook sheet.

When data is typed or pasted into a workbook sheet, you must update the hidden Origin worksheet layer before you can read cell values using LabTalk.  To update the hidden Origin worksheet layer associated with a workbook, use the following syntax:

set WorkbookName -ui

For example, to update the hidden Origin worksheet layer for the active sheet of the Book1 workbook, enter the following command in the Script window:

set Book1 -ui

Note:  To update a specific column (dataset), without updating the entire sheet, use the following syntax:  set WorkbookName_ColumnName -ui

When plotted workbook data is modified, for example, by an analysis option, you must update the data in the workbook.  To update the workbook, use the following syntax:

set WorkbookName -ue

Note:  To update a specific column (dataset), without updating the entire sheet, use the following syntax:  set WorkbookName_ColumnName -ue

Workbook Dataset Naming Convention

Excel workbook datasets are named using the following syntax:

WorkbookName_ColumnName@SheetNumber

Where WorkbookName is the workbook name, ColumnName is the workbook column name, and SheetNumber is the numeric value reflecting the order in which data was plotted from the sheets in the workbook.  (Do not include @1 for datasets from the first plotted sheet.)

In addition to referencing Excel workbook datasets using the WorkbookName_ColumnName@SheetNumber syntax, you can reference workbook datasets using substitution notation.  Substitution notation is the preferred syntax for referencing workbook datasets.  When you use this syntax, you do not have to keep track of the order in which you plotted data from the workbook sheets.  Origin executes the command for the active sheet.

To reference a workbook dataset, use the following substitution notation syntax:

%(WorkbookName,@DN,ColumnName)

To reference a workbook dataset cell, use the following substitution notation syntax:

%(WorkbookName,@DN,ColumnName,RowNumber)

Where WorkbookName is the workbook name, ColumnName is the workbook column name, and RowNumber is the row index number.  Type @DN literally.

Setting a Workbook Cell Value

To set a workbook cell value in the active workbook sheet, use the following syntax:

WorkbookName_ColumnName@SheetNumber[RowNumber]=value

or

%(WorkbookName,@DN,ColumnName,RowNumber)=value

Setting a Cell Value in the First Workbook Sheet from which Data was Plotted

To set the value of the fourth cell in column C of the first sheet (from which data was plotted) in the Book1 workbook to 245, enter the following in the Script window:

Book1_C[4]=245

or

%(Book1,@DN,C,4)=245

Note that in the first script example, the @1 is not included.

Setting a Cell Value in Another Workbook Sheet

If you change the active sheet from Sheet1 to another sheet, you must update Origin with this sheet change before setting a cell value.  To update Origin with the sheet change, enter the following in the Script window:

layer -s

To set the value of the third cell in column D of the currently active sheet in the Book1 workbook to 579, enter the following in the Script window:

%(Book1,@DN,D,3)=579

Alternatively, if we assume that the currently active sheet is the second sheet from which data was plotted, you could also enter the following in the Script window:

Book1_D@2[3]=579

The first script example is preferred, as this syntax does not require knowledge of the order in which data was plotted from the sheets.  The second script example requires that you know that the currently active sheet is the second sheet from which data was plotted.

Before you can plot the data values added using script, you must update the hidden Origin worksheet layer with the new cell values.  To do this, use the following syntax:

Set WorkbookName -ui

For example, enter the following in the Script window:

Set Book1 -ui

Reading a Workbook Cell Value

To read a workbook cell value in the active workbook sheet, use the following syntax:

WorkbookName_ColumnName@SheetNumber[RowNumber]=

or

%(WorkbookName,@DN,ColumnName,RowNumber)=

Reading a Cell Value in the First Workbook Sheet from which Data was Plotted

To read the value of the fourth cell in column C of the first sheet (from which data was plotted) in the Book1 workbook, enter the following in the Script window:

Book1_C[4]=

or

%(Book1,@DN,C,4)=

Note that in the first script example, the @1 is not included.

Reading a Cell Value in Another Workbook Sheet

If you change the active sheet from Sheet1 to another sheet, you must update Origin with this sheet change before reading a cell value.  To update Origin with the sheet change, enter the following in the Script window:

layer -s

To read the value of the third cell in column D of the currently active sheet in the Book1 workbook, type the following in the Script window:

%(Book1,@DN,D,3)=

Alternatively, if we assume that the currently active sheet is the second sheet from which data was plotted, you could also enter the following in the Script window:

Book1_D@2[3]=


Functions

A function is a dataset that contains no values.  Instead, a function contains the formula by which it is defined.  For example, the following assignment statement defines the function f1:

f1(x)=1+sin(x);

Origin provides a number of built-in functions.  For example, the list function searches the specified dataset for a particular value and returns its index number.  Entering the following assignment statement in the Script window:

ii=list(7,Data1_B)

assigns to ii the index number of the first occurrence of the value 7 in Data1_B.


Operators

Operators are symbols which cause a script to act on a data object.  For example, the arithmetic operator + causes the script to add two numbers.  LabTalk supports assignment operators, arithmetic operators, logical and relational operators, and conditional operators.

Origin also provides a variety of numeric, trigonometric, and statistical built-in functions which can act on datasets.

When evaluating an expression, Origin observes the following precedence rules:

1)	Exposed assignment operators (not within brackets) are evaluated.

2)	Operations within brackets are evaluated before those outside brackets.

3)	Multiplication and division are performed before addition and subtraction.

4)	The (>, >=, <, <=) relational operators are evaluated, then the (== and !=) operators.

5)	The logical operators && and || are evaluated in the order listed.

6)	Finally, any conditional expressions (?:) are evaluated.

For information on the order of evaluation for other types of script statements, see  Order of Evaluation in Statements.

More:

Arithmetic Operators

Assignment Operators

Logical and Relational Operators

Conditional Operators


Arithmetic Operators

Origin recognizes the following arithmetic operators:

+	Addition

-	Subtraction

*	Multiplication

/	Division

^	Exponentiate (X^Y raises X to the Yth power)

&	Bitwise And operator (see Logical and Relational Operators).  Acts on the binary bits of a number.

Bitwise Or operator (see Logical and Relational Operators).  Acts on the binary bits of a number.

The following example illustrates the use of the exponentiate operator.  Enter the following script in the Script window:

1.3^4.7=

After pressing ENTER, 3.43189 is printed in the Script window.

The next example illustrates the use of the 'bitwise and' operator.  Enter the following script in the Script window:

if (27&41==9){type "Yes!"}

After pressing ENTER, Yes! is printed in the Script window.

Note:  27&41==9 because

27=	0000000000011011
41=	0000000000101001
with bitwise & yields:	0000000000001001 (which does equal 9)

Note:  Multiplication must be explicitly included in an expression (for example, 2*X rather than 2X to indicate the multiplication of the variable X by the constant 2).

More:

A Note about Logarithmic Conversion


A Note about Logarithmic Conversion

To convert a dataset to a logarithmic scale, use the following syntax:

col(c)=log(col(c));

To convert a dataset back to a linear scale, use the following syntax:

col(c)=10^(col(c));


Assignment Operators

The = operator can be used to create and assign values to a numeric variable, a string variable, or a dataset.  The = operator can also be used to find the value of a variable.  For more information on using assignment operators in this way, see  Numeric Variables,  Assigning Values to a String Variable, and  Assigning Values to a Dataset.

Origin recognizes the following assignment operators:

=	Assign the argument to the variable.

+=	Add the argument to the variable contents and assign to the variable.

-=	Subtract the argument from the variable contents and assign to the variable.

*=	Multiply the argument by the variable contents and assign to the variable.

/=	Divide the variable by the argument and assign the result to the variable.

^=	Raise the variable contents to the argument and assign to the variable.

++	Add 1 to the variable contents and assign to the variable.

--	Subtract 1 from the variable contents and assign to the variable.

--O	Performs interpolation outside of the domain of the second dataset for all X values of the first dataset.  For example:
data1_b --O data2_b;

#=	Copy the contents of a vector to another vector.  The destination is overwritten.  For example:
DestinationVector #= SourceVector
To get the size of a vector, use the following notation:
NumericVar=Vector+

#+=	Add the contents of a vector to another vector.  The destination vector is not overwritten.  For example:
DestinationVector #+= SourceVector
To get the size of a vector, use the following notation:
NumericVar=Vector+

Note:  B*=A produces the same result as B=A*B.  This is a convenient shorthand notation and also produces script that executes faster.

The following examples illustrate the use of assignment operators.  In the first example, 5 is subtracted from the value of A and the result is assigned to A:

A-=5;

In the next example, each value in Data1_B is divided by the corresponding value in Data1_A, and the resulting values are assigned to Data1_B.

Data1_B/=Data1_A;

The loop expression also illustrates a common use of assignment operators.  The following script types the first ten values in the second column of the Data1 worksheet to the Script window:

for (ii=1;ii<=10;ii+=1)

{type "%(Data1,2,ii)"; }

For information on %( ) substitution notation, see  %( ) Substitution.


Logical and Relational Operators

Origin recognizes the following logical and relational operators:

>	Greater than

>=	Greater than or equal to

<	Less than

<=	Less than or equal to

==	Equal to

!=	Not equal to

&&	And

||	Or

Note:  A single equal sign, =, is an assignment operator.  For example, A=52 assigns the value of 52 to A.

An expression involving logical or relational operators evaluates to either true (non-zero) or false (zero).

Use the == and != operators to compare two strings.  String comparison (rather than numeric comparison) is indicated by open and close double quotations (" ") either before, or after, the operator.  For example, the following script determines if the %A string is empty.:

if (%A==""){type "empty"};

The following example illustrates the use of the 'equal to' operator:

x=1;     // variable x is set to 1

%a=x;  // string a is set to "x"

if (%a==1);

  type "yes";

else

  type "no";

The result will be yes, because Origin looks for the value of %a (the value of x), which is 1.

In the following script:

x=1;     // variable x is set to 1

%a=x;  // string a is set to "x"

if ("%a"==1)

   type "yes";

else

   type "no";

The result will be no, because Origin finds the quotation marks around %a, and therefore treats it as a string, which has a character x, rather than the value 1.


Conditional Operators

The ternary operator  ?:  can be used in the form:

Expression1 ? Expression2 : Expression3

This expression first evaluates Expression1.  If Expression1 is true (non-zero) then Expression2 is evaluated.  The value of Expression2 becomes the value for the conditional expression.  If Expression1 is false (zero), then Expression3 is evaluated and becomes the value for the entire conditional expression.

Note that Expressions1 and 2 can themselves be conditional operators!

The following example assigns the value which is greater (m or n), to variable:

m=2;

n=3;

variable=(m>n?m:n);

variable=

LabTalk returns:  variable=3


Substitution Notation

When a script is executed, it is sent to the LabTalk interpreter.  Among other tasks, the interpreter searches for two types of special substitution notation which are identified by their initial characters, % or $.  When a substitution notation is found, it is sent to the substitution processor, which replaces the original string with another string, as described in the following section.  The value of the substituted string is unknown until the statement is actually executed.  Thus, this procedure is called a run-time string substitution.

Note:  Both %( ) and $( ) substitution notation are always substitution-processed, even when enclosed in quotes as part of a text string.

More:

%( ) Substitution

$( ) Substitution


%( ) Substitution

During script execution, a 'worksheet information expression' surrounded by %( ) is evaluated and replaced with the worksheet information it represents.

To return individual cell contents, use the following syntax:

%(worksheetName,columnNumber,rowNumber);

For example, if the third cell in the fourth column in the data1 worksheet contains the value 25, then entering the following statement in the Script window:

A=%(data1,4,3)

sets A equal to 25.

The %( ) substitution notation can be combined with system variables.  For example, entering the following script in the Script window:

%(%H,selc1,selr1)=

returns the element in the top left cell of the current selection range.

To return the contents of a text cell, use a string variable.

For example:

%A=%(data1,4,3);%A=

To return a dataset name, use the following syntax:

%(worksheetName,columnNumber);

For example, enter the following assignment statement in the Script window:

%B=%(%H,1);%B=

In this example, the name of the dataset in column 1 in the active worksheet is substituted for the expression on the right, and then assigned to %B.

Note:  If the assignment is made to a dataset, rather than a dataset name, LabTalk assigns the data, rather than the name of the dataset.

To return a column label, use the following syntax:

%(columnNumber,@L);

For example, the following script returns the column label for the first column in the active worksheet:

%N=%(1,@L); %N=;

To return other information about worksheet columns, use the following syntax:

%(worksheetName,@option,columnNumber);

where option is one of the following:

@#	Returns the total number of worksheet columns.  ColumnNumber may be omitted.

@C	Returns the column name.

@D	Returns the dataset name.

@E#	If columnNumber=1, returns the number of Y error columns in the worksheet.  If columnNumber=2, returns the number of Y error columns in the current selection range.  If columnNumber is omitted, LabTalk defaults to columnNumber=1.

@H#	If columnNumber=1, returns the number of X error columns in the worksheet.  If columnNumber=2, returns the number of X error columns in the current selection range.  If columnNumber is omitted, LabTalk defaults to columnNumber=1.

@O	Returns the offset from the left-most selected column to the columnNumber column in the current selection.

@OY	Returns the offset from the left-most selected Y column to the columnNumber column in the current selection.

@OYX	Returns the offset from the left-most selected Y column to the columnNumber Y column counting on Y columns in the current selection.

@OYY	Returns the offset from the left-most selected Y column to the columnNumber X column counting on X columns in the current selection.

@T	Returns the column type.  1=Y , 2=disregarded, 3=Y error, 4=X , 5=label, 6=Z, and 7=X error.

@X	Returns the number of the worksheet's X column.  Columns are enumerated from left to right, starting at 1.  Use the syntax:  %(worksheetName,@X);

@Xn	Returns the name of the worksheet's X column.  Use the syntax:  %(worksheetName,@Xn);

@Y-	Returns the column number of the first Y column to the left.  Returns columnNumber if the column is a Y column, or returns 0 when the Y column doesn't exist.  Use the syntax:  %(worksheetName,@Y-,ColumnNumber);

@Y#	If columnNumber=1, returns the number of Y columns in the worksheet.  If columnNumber=2, returns the number of Y columns in the current selection range.  If columnNumber is omitted, LabTalk defaults to columnNumber=1.

@Y+	Returns the column number of the first Y column to the right.  Returns columnNumber if the column is a Y column, or returns 0 when the Y column doesn't exist.  Use the syntax:  %(worksheetName,@Y+,ColumnNumber);

@YS	Returns the number of the first selected Y column to the right of (and including) the columnNumber column.

@Z#	If columnNumber=1, returns the number of Z columns in the worksheet.  If columnNumber=2, returns the number of Z columns in the current selection range.  If columnNumber is omitted, LabTalk defaults to columnNumber=1.

Note:  To access more information on X values, use the xindex( ) and xvalue( ) built-in functions.

The following script returns the column name of the first column in the current selection range:

%N=%(%H,@col,selc1);%N=;

The next script returns the column type for the first column in the current selection range:

%N=%(%H,@type,selc1);%N=;

The script which follows returns the column number of the worksheet X column:

%N=%(%H,@X,selc1);%N=;

If the currently active worksheet window has six columns (XYYYYY) and columns 2, 4, and 5 are selected, then the following script returns the number of the first selected Y column to the right of (and including) the columnNumber column (third argument):

%(%H,@YS,1)=2

%(%H,@YS,2)=2

%(%H,@YS,3)=4

%(%H,@YS,4)=4

%(%H,@YS,5)=5

%(%H,@YS,6)=0


$( ) Substitution

The $( ) notation is used for numeric to string conversion.  This notation evaluates the given expression at run-time, converts the result to a numeric string, and then substitutes the string for itself.

The notation has the following form:

$(expression);

where expression can be any math expression.

This type of substitution is essential when outputting a numeric result.  Consider the following Script window example:

K=9;

type "K";

In the first statement, the value 9 is assigned to the variable K.  The second statement causes the given string to be printed to the Script window.  The Script window prints K.

Use the numeric-to-string conversion notation to convert K to a value before printing to the Script window, as in the following example:

type "$(K)"

which finds the value of K first, and then prints the result, which is 9.

In this example, if you assign a negative value to the variable K, you must protect the variable by enclosing it in parentheses when you use the type command.  For example:

K=-5;

type "($(K))";

The following script defines a macro that takes two arguments (%1 and %2), adds them, and outputs the sum to a dialog box:

def add {type -b "(%1+%2)=$(%1+%2)"}

Once defined, the macro is run by typing:

add 2 3;

The output string reads:

(2+3)=5

Thus, the expression $(%1+%2) resolves to 5.

Note that in assignment statements, the $( ) notation is substitution-processed and resolved to a value regardless of which side of the assignment operator it is located.  The following script examples illustrate the use of the $( ) notation.

Script:  A=2;

Result:  Creates a variable (A) with the value 2.  Verify by entering A= in the Script window.

Script:  A$(A)=3;

Result:  Creates a variable A2 (since $(A) resolves to 2) with the value 3.  Verify by entering A$(A)= in the Script window.

Script:  A$(A+2)=1;

Result:  Creates a variable A4 with the value 1.  Verify by entering A$(A+2)= in the Script window.

More:

The $( ) Notation and C Formatting Conversion Specifications


The $( ) Notation and C Formatting Conversion Specifications

The $( ) notation can be used together with C formatting conversion specifications.

Note:  In the following examples, the *, E, S, and D conversion specifiers must directly follow the comma, with no intervening white space.

Use the * notation to set significant digits.

For example, in the command:

type "x=$(x,*2)";

x is followed by *2, which sets x to display two significant digits.

If x equals 1.23456, the output result is:

x=1.2

Use the . notation to set decimal places.

For example, in the command:

type "x=$(x,.2)";

x is followed by .2, which sets x to display two decimal places.

If x equals 1.23456, the output result is:

x=1.23

Use E notation to change the variable to engineering format.  The E notation follows the variable it modifies, like the * notation.

For example, if you define x:

x=1e6;

then the result of the following command:

type "x=$(x,E%4.2f)";

is:

x=1.00M

where % indicates the start of the substitution notation, 4 specifies the total number of digits, .2 specifies 2 decimal places, and f is an indicator for floating notation.

To convert from engineering to scientific notation, use the $(x,S*n) notation where n specifies the total number of digits.

For example, if x=1.23456, the following command:

type "x=$(x,S*3)";

returns:

x=1.23E0

The D notation converts a numeric date value into a date time string.

The following example illustrates this notation:

type "$(@D,D10)";

returns the current date and time.  For example:

5/6/99 10:50:27

The number after the D character is the index entry (from 0) in the Date Format drop-down list of the Worksheet Column Format dialog box.


Keywords

LabTalk reserves certain identifiers for its own use.  These reserved identifiers are called keywords.  All LabTalk command names are keywords.  LabTalk also includes a number of macros and variables which have a special meaning in Origin.  These system macros and system variables also use keyword identifiers.

LabTalk provides no protection against using keywords as user-defined identifiers.  Using a keyword to name a variable or dataset will not create a conflict.  However, using a LabTalk command or system macro identifier to name a new macro overrides the original macro or command.

More:

Commands

System Macros

Numeric System Variables

String System Variables


Commands

The following command names are keywords.  Using any of these keywords to name your own macro overwrites the Origin command.

Average	axis	break	clipboard
continue	copy	create	dde
define	delete	derivative	dll
document	dotoolbox	draw	edit
exit	file	for	get
getfilename	getnumber	getpts	getsavename
getstring	getyesno	if	integrate
label	layer	legend	limit
list	loop	lr	mark
math	matrix	menu	nlsf
open	page	plot	print
queue	repeat	return	run
save	second	select	set
sort	switch	timer	type
undo	window	worksheet


System Macros

A number of macros are pre-defined in Origin.  To view a list of these macros, see the list command.  To see the script associated with a defined macro, use the following syntax in the Script window:

define MacroName


Numeric System Variables

The following variables are restricted for internal use by Origin, and should not be used for other purposes.  Although they will not cause conflicts, these variables are in frequent use, and may cause your script to fail.

X1, X2, Y1, Y2, Z1, Z2

These variables contain the initial and final X, Y, and Z axis scale values for the active layer.  Changing these values resets the X, Y, or Z scale.  For example, entering the following script in the Script window:

X1=-3;X2=12;Y1=0.3

sets the 2D X axis scale range to plot from -3 to 12.  The Y axis scale begins at 0.3.

MKS1, MKS2

When data markers are displayed in the graph window, MKS1 and MKS2 are set to the first and second data markers respectively.  When they are displayed, both variables equal -1.

Echo

This variable prints scripts or error messages to the Script window.  To enable echo, type echo=# in the Script window, where # is one of the following:

1	Display commands that generate an error.

2	Display scripts that have been sent to the queue for delayed execution.

4	Display scripts that involve commands.

8	Display scripts that involve assignments.

16	Display macros.

To disable echo, type echo=0 in the Script window.

Note:  These values are bits that can be combined to produce cumulative effects.  For example, echo=12 displays both command and assignment scripts.  Echo=7 (includes echo=1, echo=2, and echo=4) is useful for following script execution during menu command selection.

X, Y, Z

These variables contain the current X, Y, and Z coordinates of the Screen Reader, Data Reader, or Data Selector tools.

Each time you double-click the cursor or press ENTER when one of these tools is selected, Origin executes the PointProc macro.  The following script defines PointProc such that double-clicking on the page sets X1 and Y1 equal to X and Y:

doToolbox 2;#Select the Screen Reader.

Def PointProc {X1=x;Y1=y;doToolbox 0};

i

The variable i is used to store the index number to a dataset.  In most cases, this is also the row number of a worksheet.

SELC1, SELC2, SELR1, SELR2

These variables contain the column and row numbers that delineate the current worksheet selection range.  If no range is selected, the values are set back to 0.

COUNT

This variable is used by different Origin routines.  It can be the number of selected files in the Open Multiple Files dialog box, or the number of times the PointProc macro has been executed since the Screen Reader tool or the Data Reader tool has been selected.

@Letter Variables

Variable:  @A

Use:  Angular unit, 0=radian, 1=degree, 2=gradian.

Variable:  @B

Use:  Enables (1) and disables (0) debugging statements that start with #! In a script.

Variable:  @D

Use:  Current date and time in numeric values (Julian days).  Use the $(@D,Dn) notation to display the date and time formats provided in the Date Format drop down list in the Worksheet Column Format dialog box (numbered from zero).  For example, $(@D,D10) shows displays M/D/YYYY HH:MM:SS.  Origin supports the associated Julian day values for the range:  1/1/0100 to 12/31/9999.

Variable:  @G

Use:  Set @G=0 to display the page color within the entire graph window (including beyond the page) in page view mode.  Set @G=1 to display the area outside the page as gray.

Variable:  @L

Use:  The current menu level.  1=full menus, 2=short menus.

Variable:  @MC

Use:  Mask color.  Follows the colors in the color palette:  1=black, 2=red, 3=green, 4=blue, etc.  Use mark -u to update all windows.

Variable:  @MM

Use:  Enable or disable mask.  0=enable (masked points are not included in analysis).  1=disable (masked points are included in analysis).  Use mark -u to update all windows.

Variable:  @MP

Use:  Show or hide masked data points in graph.  0=show.  1=hide.  Use mark -u to update all windows.

Variable:  @NSV

Use:  For backwards compatibility, enable setting the count variable when fdlog.multiopen( ) is used.  1=enable, 0=disable.

Variable:  @O

Use:  Set or get the current printer driver's page orientation.  @O=1 for portrait.  @O=2 for landscape.  Use the following page object method to update the printer setup:  page.dimupdate( );

Variable:  @P

Use:  Page numbers in worksheet printing.  @PC for current page number column-wise and @PR for current page number row-wise.

Variable:  @PB

Use:  Set @PB=1 to enable gray-scaling on a black and white printer.  Set @PB=0 to print all non-white colors as black when a black and white printer is selected.

Variable:  @U

Use:  Set @U=0 to align the fonts in a text label with the baseline.  Set @U=1 to disable this option.  @U is the same as the system.print.fontbaseline property.  (See Chapter 4, "Object Reference".)

Variable:  @V

Use:  Origin version number.

Variable:  @W

Use:  Font size scaling for display in Window view mode (which normally ignores font scaling).  @W is the same as the system.winviewfsize property.  (See Chapter 4, "Object Reference".)


String System Variables

The following string variables are system variables that have a special meaning for Origin.  Each variable contains the text value indicated in the Description field.  You may use these string variables for your own strings.  However, Origin attributes special meaning to these variables.

%A	Used extensively by Origin, and are commonly used in development scripts.

%B	Used extensively by Origin, and are commonly used in development scripts.

%C	The name of the current active dataset.

%D	The name of the last dataset set as active with the set command.

%E	The name of the window containing the latest worksheet selection.

%F	The name of the dataset currently in the fitting session.

%G	The current project name.

%H	The current active window title.

%I	The current baseline dataset.

%X	The DRIVE:PATH of the current project.  The '\' character can be displayed from the %X or %Y system string variable.  For example, if the following text is typed in the Text Control dialog box (with 'Link to Variables' enabled in the Label Control dialog box):
The file path for this document is \v(%X).
Origin displays:
The file path for this project is C:\MyDir\MyFile.

%Y	The DRIVE:PATH for the ORIGIN60.INI file.  To display the '\' character, see %X.

%Z	A long string for temporary storage.

These string variables can be used anywhere a name can be used, as in the following example:

del %C;

which deletes the current active dataset.


Programming

Origin's LabTalk language has a C-like structure, comprised of loops and decision structures.  To automate and customize Origin, you may make use of a combination of mathematical operations, commands, macros, object properties, and object methods.  This section reviews LabTalk syntax, and helps you gain proficiency writing your own scripts.

More:

Syntax

Structure

When Scripts do not Work


Syntax

A script is a single block of LabTalk text that is received by the LabTalk interpreter.  A LabTalk script is composed of one or more statements.  A statement is a complete programming statement which performs an action.  Each statement in a script should end with a semicolon, which separates it from other statements.  However, single statements typed into the Script window for execution should not end with a semicolon.

Each statement in a script is composed of words.  Words are any group of text separated by white space.  Text enclosed in parentheses is treated as a single word, regardless of white space.  For example:

This is a statement; 	is a single LabTalk statement, while

statement 1;  statement 2;  statement 3 	represents three statements.

Parentheses are used to create long words containing white space.  For example, in the script:

menu 3 (Long Menu Name);

the open parenthesis signifies the beginning of a single word, and the close parenthesis signifies the end of the word.

Note:  LabTalk is case-insensitive.

More:

Statement Types

Using Semicolons in LabTalk

Extending a Statement over Multiple Lines

Comments

Order of Evaluation in Statements

Passing Arguments


Statement Types

LabTalk supports five types of statements:  assignment, macro, command, arithmetic, and function.

Assignment Statements

The assignment statement takes the general form:

dataObjectName=expression;

expression is evaluated and put into dataObjectName.  If dataObjectName does not exist, it is created.

When a new data object is created with an assignment statement, the object created is:

A string variable if dataObjectName is %A - %Z.

A variable if expression evaluates to a scalar.

A dataset if expression evaluates to a range.

When new values are assigned to an existing data object, the following conventions apply:

If dataObjectName is a dataset and expression is a scalar, every value in dataObjectName is set equal to expression.

If dataObjectName is a variable, then expression must evaluate into a scalar.  If expression is a dataset, dataObjectName retrieves the first element of the dataset.

If both dataObjectName and expression represent datasets, each value in dataObjectName is set equal to the corresponding value in expression.

One special case of the assignment statement is the object.property notation.  This notation is used to read or set object properties, such as the number of rows in a worksheet.  To set object properties, use the following syntax:

ObjectName.property=expression;

To read an object property in the Script window, use the syntax:

ObjectName.property=

The following examples illustrate the use of assignment statements:

Example:  B=2;

Description:  Assign the variable B equal to the value 2.

Example:  Test=B^3;

Description:  Assign Test equal to 8.

Example:  %A=Austin TX;

Description:  Assign %A equal to Austin TX.

Example:  Data1_B=4;

Description:  Assign every value in Data1_B to 4.

Example:  Data1_B=Data2_B;

Description:  Assign each value in Data2_B to the corresponding position in Data1_B.

Example:  Data1!wks.rhw=100;doc -uw;

Description:  Sets the row heading width for the Data1 worksheet to 100, using the worksheet object's rhw property.  doc -uw refreshes the window.

Example:  myData=3*more+yetmore;

Description:  The calculation is carried out for the values at the corresponding index numbers in more and yetmore.  The result is put into myData at the same index number.

Note:  If a string variable to the left of the assignment operator is enclosed in parentheses, the string variable is substitution processed before assignment.  For example:

%B=DataSet;

(%B)=2*%B;

The values in DataSet are multiplied by 2 and put back into DataSet.  %B still holds the string "DataSet".

Macro Statements

Macros provide a way to alias a script, that is, to associate a given script with a specific name.  This name can then be used as a command that invokes the script.

The define command is used to create macros.  This command takes the general form:

define macroName {script};

This command creates the macro macroName that invokes the script script.  A statement beginning with macroName is called a macro statement.  A macro statement precedes command statements in recognition order.  Otherwise, the macro statement is like any other command statement.

For information on passing arguments to a macro, see  Passing Arguments.

Command Statements

The third statement type is the command statement.  LabTalk offers a rich set of commands to control or modify most program functions.

Each command statement begins with the command itself, which is a unique identifier that can be abbreviated down to two letters (as long as the abbreviation remains unique, which is true in most cases).  Most commands can take options, which are single letters that modify the operation of the command.  Options are always preceded by the dash "-" character.  Commands may also take arguments.  Arguments are either a script or a data object.  In many cases, options can also take their own arguments.

Command statements take the general form:

command [option] [argument(s)];

The brackets [ ] indicate that the enclosed component is optional;  not all commands take both options and arguments.  The brackets are not, however, typed with the command statement.

Object methods are another form of command statement.  They execute immediate actions relating to the named object.  Object method statements use the following syntax:

ObjectName.Method ([options]);

For example, the following script adds a column named new to the active worksheet and refreshes the window:

wks.addcol (new);doc -uw;

The following examples illustrate different forms of command statements:

Example:  integ myData;

Description:  Integrate the dataset myData from zero.

Example:  integ -r baseline myData;

Description:  Adding the -r option and its argument, baseline, causes myData to be integrated from a reference curve named baseline.

Example:  repeat 3 {type -b "Hello World"};

Description:  The repeat command takes two arguments to execute:  number of times, and a script.  This command statement prints "Hello World" in a dialog box three times.

Arithmetic Statement

The arithmetic statement takes the general form:

dataObject1 operator dataObject2;

where dataObject1 is a dataset or a numeric variable.  dataObject2 is a dataset, variable, or a constant.  operator can be +, -, *, /, or ^.  The result of the calculation is put into dataObject1.  Note that dataObject1 cannot be a function.  For example, col(3) + 25 is an illegal usage of this statement form.

The following examples illustrate different forms of arithmetic statements:

Example:  myData/10;

Description:  If myData is a dataset, this divides each value in myData by 10.

Example:  myData-otherData;

Description:  Subtract otherData from myData, and put the result into myData.  Both datasets must be Y or Z datasets (see note).

Example:  A+1;

Description:  If A is a variable, increment A by 1.  If A is a dataset, increment each value in A by 1.

Note:  There is a difference between using datasets in arithmetic statements vs. using datasets in assignment statements.  For example, data1_b+data2_b is computed quite differently from data1_b=data1_b+data2_b.  The later case yields the exact result no matter how the two datasets are associated with the X datasets, but the former arithmetic statement depends on the interpolation based on the first dataset's X dataset.

Function Statements

The final statement type is the function statement.  This type includes any statement that begins with the characteristics of a function, that is, an identifier followed by open and close parentheses.

An example of a function statement is:

sum(dataset);


Using Semicolons in LabTalk

LabTalk's use of semicolons to separate statements is similar to C syntax.  In general, every statement should end with a semicolon.  However, the following rules clarify semicolon usage:

Do not use a semicolon when executing a single statement script in the Script window.  An example of the proper syntax is:  type "hello" (ENTER).  The interpreter places a semicolon after the statement to indicate that it has been executed.

To enter multiple line script in the Script window, include a semicolon after every statement.  To execute the script, select the entire script with the mouse and press ENTER.  Note that pressing ENTER before typing the statement-ending semicolon accidentally causes immediate execution of the specific line.  To avoid this, you can turn off Script Execution by selecting Edit:Script Execution from the Script window menu bar.  After typing the script, turn Script Execution back on again by selecting Edit:Script Execution, then highlight the script and press ENTER.

If you turn off Script Execution, it is not necessary to use a semicolon after the last statement of a multiple line script.  The statement will be properly executed with or without a semicolon.

Use a semicolon at the end of each statement when writing a script for an object, menu command, or script file.

Some commands take a script as an argument, including if, for, and define.  Do NOT use a semicolon between the command and the script argument.  The command is not a complete statement without the script.  For example:

if (m>2) {type "hello"};

is correct syntax.

Semicolons should be used within the script argument and after the last bracket of the statement.  For example:

if (counter>200)

{

counter=0;

type "Resetting the counter";

};

is also correct syntax.


Extending a Statement over Multiple Lines

There are times when, for the sake of readability, you want to extend a single statement over several lines.  One way to do this is with braces { }.  When an open brace is encountered in a script file, Origin searches for a close brace and executes the entire block of text as one statement.  For example, the following macro statement:

def openDialog {layer -s 1;axis x;};

can also be written:

def openDialog {

layer -s 1;

axis x;

};

Both scripts are executed as a single statement, even though the second statement extends over four lines.

Note:  There is a limit to the number of tokens that can be included between a set of { }.  The tokens between the { } in a LabTak script are translated internally and the translated tokens must be less than 1140 bytes (after substitution).  In place of long unwieldy blocks of LabTalk code, programmers can use LabTalk macros or the run.section( ) and run.file( ) object methods.

Another way to extend a script over multiple lines is with the backslash " \ ".  When a backslash is placed at the end of a line, the carriage return is ignored and the two lines are executed as a single script.  For example:

type "we have a very long line to dis\

play here."

is passed to the interpreter as a single statement.


Comments

Use the " # " or "//" character to ignore all text from # or // to the end of the line.  These characters must follow a semicolon.  For example, # and // can be used as follows:

type "Hello World"; #Place comment text here.

type "Hello World"; //Place comment text here.

Note:  Use the "#!" characters to begin debugging lines of script.  The lines are only executed if system.debug=1.


Order of Evaluation in Statements

When a script is executed, it is sent to the LabTalk interpreter and evaluated as follows:

1)	The script is broken down into its component statements.

Statements are identified as to type using the following recognition order:  assignment, macro, command, arithmetic, and function.  The interpreter first looks for an exposed (not hidden in parentheses or quotation marks) assignment operator.  If none is found, it looks to see if the first word is a macro name.  It then checks if the first word is a command name.  The interpreter then looks for an arithmetic operation, and finally, the interpreter checks whether the statement is a function.

The recognition order can have significant effect on script function.  For example, the following assignment statement:

type=1;

assigns the value 1 to the variable type.  This occurs even though type is (also) a LabTalk command, since assignment comes before commands in recognition order.  However, since commands precede arithmetic expressions in recognition order, in the following statement:

type+1;

the command is carried out first, and the string, +1, prints out.

2)	The statements are executed in the order received, using the following evaluation priority:

Assignment statement:  String variables to the left of the assignment operator are not expressed unless enclosed by parentheses.  Otherwise, all string variables are expressed, and all special notation (%( ) and $( )) is substitution processed.

Macro statement:  Macro arguments are substitution processed and passed.

Command statement:  If a command is a raw string, it is not sent to the substitution processor.  Otherwise, all special notation is substitution processed.

Arithmetic statement:  All expressions are substitution processed and expressed.


Passing Arguments

When you use the run.section( ) object method (to call a script file section) or when you call a macro, you can pass arguments to the script file section or to the macro.  Arguments can be literal text, numbers, numeric variables, or string variables.

When you pass arguments to script file sections or to macros, the section call or the macro call must include a space between each argument being passed.  Furthermore, when you pass literal text or string variables as arguments, each argument should always be surrounded by quotation marks (in case the argument contains more than one word, or is a negative value).  Passing numbers or numeric variables doesn't require quotation mark protection, except when passing negative values.

You can pass up to five arguments to script file sections or macros.  In the script file section or macro definition, argument placeholders receive the passed arguments.  These placeholders are %1, %2, %3, %4, and %5.  The placeholder for the first passed argument is %1, the second is %2, etc.  These placeholders work just like string variables in that they are always substituted prior to execution of the command in which they are embedded.

As an example of passing literal text as an argument that is received by %1, %2, etc., suppose a TEST.OGS file includes the following section:

[output]

type "%1 %2 %3";

and you execute the following script:

run.section(test.ogs,output, "Hello World" "from" "LabTalk");

Then %1 holds "Hello World", %2 holds "from", and %3 holds "LabTalk".  After string substitution, Origin outputs Hello World from LabTalk to the Script window.  If you had omitted the quotation marks from the script file section call, then %1 would hold "Hello", %2 would hold "World", and %3 would hold "from".  Origin would then output Hello World from.

Passing Numeric Variables by Reference

Passing numeric variable arguments by reference allows the code in the script file section or macro to change the value of the variable.  For example, suppose your application used the variable LastRow to hold the row number of the last row in the data1_b column that contains a value.  Furthermore, suppose that the current value of LastRow is 10.  If you pass the variable LastRow to a script file section whose code appends five values to data1_b (starting at the current last row), then after appending the values, the script file section could increment the value of the LastRow variable so that the updated value of LastRow is 15.

Thus, if a TEST.OGS file includes the following section:

[adddata]

loop (n, 1, 5)

{

data1_b[%1+n]=100;

};

%1=%1+(n-1);

return 0;

And you execute the following script:

data1_b=data(1,10);   //fill data1_b with values 1-10

get data1_b -e lastrow;   //store last row of values in lastrow

run.section(test.ogs, adddata, lastrow);

Then the LastRow variable is passed by reference and then updated to hold the value 15.

Passing Numeric Variables by Value

Passing numeric variable arguments by value is accomplished by using the $( ) substitution notation.  This notation forces the interpreter to evaluate the argument before sending it to the script file section or macro.  This technique is useful for sending the value of a calculation for future use.  If the calculation were sent by reference, then the entire expression would require calculation each time it was interpreted.

In the following script file example, the [main] section includes a call to the [Part1] section in which the numeric variable var1 is passed by reference and by value.  %1 will hold the argument that is passed by reference and %2 will hold the argument that is passed by value.  Additionally, a string variable (%A) consisting of two words is sent by value as a single argument to %3.

[main]

%A="degrees Celcius";

//Define a string variable to hold the units of the variable

//being output

run.section(,Part1,var1 $(var1) "%A");

//Pass 1st argument by reference, 2nd argument by value,

//3rd argument as a string variable

delete -v var1;

return 0;

[Part1]

//Assumed Input: 1st Arg=Variable, 2nd Arg=Value

type -b "The value of %1 = %2 %3";

//Example output: The value of var1 = 22 degrees Celcius

return 0;


Structure

The structure of the LabTalk language is similar to C.  LabTalk supports loops, which allow the program to repetitively perform a set of actions.  LabTalk also supports decision structures, which allow the program to perform different sets of actions depending on the circumstances.

More:

Loops

Decision Structures

Bracketing and Indentation Conventions in LabTalk


Loops

All LabTalk loops take a script as an argument.  These scripts are executed repetitively under specified circumstances.  LabTalk provides four loop commands:  repeat, loop, for, and doc -e.  The LabTalk for loop is similar to the for loop in other languages.  The repeat, loop, and doc -e loops are less familiar, but are simple and easy to use.

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

The loop loop is used when a single variable is being incremented between each repetition.

The doc -e loop is used when a script is being executed to affect objects of a specific type, such as graph windows.

The for loop is used for all other situations.

LabTalk provides a break command.  When executed, this causes an exit from the loop, and optionally, the script.  This is often used with a decision structure inside a loop.  It is used to protect against conditions which would invalidate the loop test conditions.

The continue command may be used within the loop script.  When executed, the remainder of the loop script is ignored and the interpreter jumps to the next iteration of the loop.  This is often used with a decision structure inside a loop and can exclude illegal values from being processed by the loop script.

Repeat

Use the repeat command to perform a set of actions a fixed number of times.  This command is the simplest possible loop.  The syntax for this command is as follows:

Repeat NumberTimes {script};

For example, the following script creates six graph windows from the TERNARY.OTP template with enumerated titles:

repeat 6 {win -t plot ternary};

Loop

The loop command increments the value of a single variable (by 1) before the next loop of code.  The syntax for this command is:

Loop (Variable,StartValue,EndValue) {script};

For example, the following command:

loop (num,1,4) {type "$(num)";};

produces the following output to the Script window:

1

2

3

4

The following command statement prints the values of rows 20-35 in column 2 of the NewData worksheet in the form "Row 20 is 547":

loop (num,20,35)

{

data=%(NewData,2,$(num));

type "Row $(num) is $(data)";

};

Doc -e

Use the doc -e command to execute a script for all objects of a specified type.  The syntax for this command is:

doc -e objectType {script};

Valid objectType values include S for datasets in the project, D for data plots in the active layer, L for layers in the project, LW for layers in the current window, and P for graph windows.

The doc -e command makes an object active and executes the associated script, looping until each object of the specified type has been active.  Most LabTalk commands, methods, and properties act on the active window.  Use system variables (such as %H and %C) when a name is required, so that the loop script affects the active object.

For example, the following command prints the contents of all graph windows in the project:

doc -e P {print;};

The next script rescales all layers in the project to show all data.  The script also types the window name and layer number of all layers to the Script window:

doc -e L

{

layer -a;

// page.active holds the number of the active layer

type "Window: %H, layer number: $(page.active)";

};

For

The for loop is the most flexible and complex of the LabTalk loop structures.  It includes three expressions and a script argument:

for (expression1; expression2; expression3) {script};

where expression1 is an initializing expression, expression2 is a conditional expression, and expression3 is typically an increment expression.

The order of evaluation is as follows:

expression1 is evaluated first.  expression2 is then evaluated, and if true (non-zero), script is executed.  expression3, usually an increment, is then evaluated.  Finally, expression2 is re-evaluated.  The loop terminates when expression2 tests to be false.

The LabTalk for loop is extremely flexible.  Any of the three expressions can consist of multiple statements separated by commas.  In addition, the expressions do not have to refer to the loop variable.  expression1 and/or expression3 may be left blank.  If the test expression does not contain a conditional operator, it is considered true if the result is non-zero.

For example, the following command:

for (ii=12;ii>5;ii-=2) {type "ii=$(ii)";};

types the following output to the Script window:

ii=12

ii=10

ii=8

ii=6

For a more complex example of the for loop's capabilities, the following script adds 11 new points to the A and B columns in the Data1 worksheet and refreshes the window:

for (xval=17,yval=2000;xval<50;xval+=3,yval/=5)

{

plot -n Data1_B $(xval) $(yval);

doc -uw;

};


Decision Structures

LabTalk has three decision-making structures:  if, if-else, and switch.

The if command is used when a script should be executed in a particular situation.

The if-else command is used when one script must be executed if a condition is true (non-zero), while another script is executed if the condition is false (zero).

The switch command is used when more than 2 possibilities are included in a script.

If

The if command is designed for situations in which a script should be executed only under a certain condition.  The syntax for this command follows:

if (TestCondition) {script};

First, the TestCondition expression is evaluated.  If it is true (non-zero), the script is executed.  If it is false (zero), the interpreter skips the script and moves on to the next statement.  If TestCondition does not include a conditional operator, it is considered true if the result is non-zero.

For example:

if (a>b) {type "a is greater"};

The following script types an explanation to the Script window and opens a dialog box to enter a value for the variable var:

if (var==0)

{

type "Division by zero is not allowed." ;

getnumber -s (Please enter a new value for var) var;

};

If-Else

The if-else command involves a branching decision structure.  Use the command when one specific situation should prompt one script, and all other situations must prompt another.  The syntax of the if-else command is as follows:

if (TestCondition) {script1} else {script2};

Note:  If-else is a single statement.  Remember not to put a semicolon between the if script and the else command.

An example of an if-else script follows:

If (a>b) {

type "a is greater";

}

else {

type "a is not greater";

};

The if-else command is useful within a loop.  For example, the following script searches through, and prints, the index numbers of the first 50 values in column 2 of the Data1 worksheet until it finds the first value greater than 100.  If it finds a value greater than 100, it prints out a message, assigns the index number to the variable first, and breaks out of the loop:

loop (ii,1,50)

{

    if (%(data1,2,ii) >100) {

type "Row $(ii)'s value is >100.";

first=ii;

break;

}

else {

         type "$(ii)";

};

};

Switch

The switch command is used when more than 2 possibilities are included in a script.  It is more complex than the other decision structures, but it is also more flexible and clear.  The command usually follows the syntax:

switch (switch expression);

{

case a:

          script

          break;

case b:

script

break;

case c:

script

break;

default:

script

break;

};

where the switch expression can be a variable or an expression, and a, b, and c must be constants or variables.

The switch command attempts to match switch expression with one of the case values (a, b, c).  If one of the values is equal to the switch expression, the script associated with the case is executed.  If none of the cases match the switch expression, the default script is executed.

Any number of cases may be defined.  A default case is not required, although it is good policy to create one.

The following switch statement example checks the current worksheet selection range.  The switch expression reports the column type of the first selected column: 1, 2, 3, or 4.  If the selected column is type 1 or 4, the matching case script is executed.  The script issues a message and creates a graph.  If the selected column is type 2 or 3 (error bar or disregarded), the default case script is executed.

switch ( %(%E,@type,selc1) ) {

case 1:

type "The first selected column is a Y column.";

type "Entire worksheet will be plotted.";

worksheet -s 0 0 0 0;  	//select whole worksheet

worksheet -p;	//plot

break;

case 4:

type "The first selected column is an X column.";

worksheet -p;	//plot worksheet selection

break;

default:

type "You selected an inappropriate col type.";

break;

};


Bracketing and Indentation Conventions in LabTalk

In the examples of loop and decision structures provided in this Help file, three different styles of bracketing and indentation are used:

if (a<b) {type "$(a) is less than $(b)"; "type hi";};

if (a<b) {

type "$(a) < $(b)";

type "hi";

};

if (a<b)

{

type "$(a) < $(b)";

type "hi";

};

The three examples above are functionally identical.  Most programmers prefer the second or third style because indenting a loop or decision script adds clarity.  This is important when working with nested loop and decision structures.


When Scripts do not Work

Common Mistakes

Debugging Tools


Common Mistakes

There are a few scripting mistakes that are very common, particularly among new LabTalk programmers.  If a script results in a #Command Error! message or does not appear to do anything, check the following:

Are all statements separated with semicolons?

Is there a semicolon where one should not be?  Do not use a semicolon for single statement scripts in the Script window.  Also, do not use them in the middle of statements.  Commands that take script as an argument, such as if, define, and for, should not have a semicolon between the command and the script.

Are there an equal number of open brackets and close brackets in the script?  Check both ( ) and { } brackets.

Is = used to test an equality relationship?  = is an assignment operator.  To test equality, use ==.

Is substitution notation ( $( ) or %( ) ) used everywhere a number must be evaluated from a variable or expression?  Is it used everywhere worksheet information is accessed?

Do the names in your project match those in the script?  Use system variables and substitution notation to avoid this problem.


Debugging Tools

The Script window provides the primary means of debugging in Origin.  Use the Script window to examine the environment and display debugging information.  The following tools are available:

The ECHO system variable

Change the value of this variable to instruct Origin to echo different types of scripts.  For example, set echo=1 to display any script that generates an error.  Set echo=7 to display all scripts that are executed.  During normal operation, echo=0.

The list command

The list command is used to examine your system environment.  For example, the list s command displays all datasets in the project.  This includes all temporary datasets.  Delete temporary datasets with the
del -a command.

Tracking values of variables

Examine the value of any variable by using the varName= notation.  Embed this in your script to display intermediate variable values in the Script window during script execution.

#!script

Embed debugging statements in your script using this notation.  The # character tells the LabTalk interpreter to ignore the text until the end of the line.  However, when followed by the ! character, the script is executed if the @B system variable (or system.debug) is set to 1.  The following example illustrates this option:

for (ii=1;ii<=10;ii+=1) {

#!ii=;Data1_A[ii]=;  // embedded debugging script

Data1_A[ii]+=ii*10;

};

If, before the previous script is run, you enter:

@B=1

in the Script window, the previous script then reports the cell value at each loop count.  During normal operation, when @B=0, the loop performs quietly.


Command Reference - Introduction
Introduction

The general form of a command statement is:

command [option] [argument(s)];

Spaces separate the command, option, and argument(s).  An option is usually a letter preceded by a dash.  Options affect the operation of a command.  Arguments are passed to, and may be modified by, the command.  The [ ] indicate an option or argument that may be omitted.

Where a command takes options, the options often take their own argument(s).  The syntax and effect of each option is described individually beneath the general command description and syntax.  In several cases, use of an option precludes use of the command arguments.  Where this is the case, the argument is surrounded by < > in the syntax description.  In some cases, multiple options and arguments can be included with a command for a cumulative affect.  See the draw and label commands for examples.


Command Reference by Category

Data Manipulation and Calculation

Display Control

Control Flow

Input/Output

Script Management

Object Management

External Access

User Interface

Time


Data Manipulation and Calculation

Command	Description
average	Perform a running average for a dataset.
copy	Copy one dataset to another.
create	Create worksheet, datasets, and functions.
delete	Delete a dataset, function, macro, or variable.
derivative	Take the derivative of a dataset.
edit	Open the worksheet for a dataset.  Open the color palette.
integrate	Integrate a dataset.
limit	Find X Y max/min values for a data plot.
list	List all datasets, macros, system variables, and data plot style holders.
lr	Perform linear regression on a dataset.
mark	Create an X dataset for the specified Y dataset.  Mask data from analysis.
math	Open the Math dialog box for dataset arithmetic.
nlsf	Nonlinear least squares fitting related functions and controls.
undo	Undo various procedures.


Display Control

Command	Description
axis	Open the specified tab of the Axis dialog box and other axis controls.
draw	Annotation and object-related operations.
label	Text label related operations.
layer	Layer manipulation, such as plotting data into a layer.  Graphic image caching.  Delete data plot style holders.
legend	Display or update the legend for the active layer.
page	All page related commands.
plot	Control window updating.
window	Window manipulation, mainly for the graph window.


Control Flow

Command	Description
break	Unconditional exit from a loop, and/or script or progress dialog box.
continue	Skip to the next iteration of the current loop.
document -e	Loop to execute a script that affects every object of the specified type.
exit	Exit Origin.
for	For loop for repeated operation.
if [else]	Test a condition and branch accordingly.
loop	Loop while incrementing a variable structure.
repeat	Execute the same script multiple times.
return	Return a value from a script and exit the script.
switch	Test an expression against a series of constant values, and branch accordingly.


Input/Output

Command	Description
clipboard	Copy the current page to the clipboard.
open	Data import from a file.
print	Print the page in the active window.
save	Save the project, child window, or dataset.
type	General text output to various windows and dialog boxes.


Script Management

Command	Description
define	Define a macro.
menu	Menu manipulation.
queue	Place a script at the end of the window update queue.
run	Execute the specified script file.


Object Management

Command	Description
document	Project manipulation.
file	Copy one project to another.
get	Get value of dataset, data plot, or worksheet attributes.
matrix	Get or set matrix parameters.
set	Set dataset, data plot, and worksheet attributes.
sort	Sort variables.
worksheet	Worksheet manipulation.


External Access

Command	Description
dde	Client DDE support.
dll	Execute a function from a user-supplied DLL.


User Interface

Command	Description
dotoolbox	Tools toolbar and tool manipulation.
getfilename	Open the Open, Open Multiple Files, and Import ASCII dialog boxes.
getnumber	Get user input of up to six numbers/strings.
getpts	Graphically get points/screen coordinates from a data plot.
getsavename	Open Save As dialog box.
getstring	Get user-supplied text string.
getyesno	Open Yes/No/Cancel dialog box.
select	Annotation and object selection controls.


Time

Command	Description
seconds	Elapsed time counter.  Perform timer-related operations.
timer	Define a script to be executed periodically.


Alphabetical Listing of Commands

When reviewing the reference information on the LabTalk commands, note the following:

The complete command name is provided for each command.  However, each command name can be abbreviated down to two letters as long as the abbreviation is unique.  For example, instead of using the print command in your script, you could use pr.

LabTalk commands are case-insensitive.

More:

Average

Axis

Break

Clipboard

Continue

Copy

Create

DDE

Define

Delete

Derivative

DLL

Document

DoToolbox

Draw

Edit

Exit

File

For

Get

GetFileName

GetNumber

GetPts

GetSaveName

GetString

GetYesNo

If

Integrate

Label

Layer

Legend

Limit

List

Loop

LR

Mark

Math

Matrix

Menu

NLSF

Open

Page

Plot

Print

Queue

Repeat

Return

Run

Save

Second

Selection

Set

Sort

Switch

Timer

Type

Undo

Window

Worksheet


Average

Syntax:	average [option] dataset [range]

Operates on the given dataset to find a running average.  This command changes the dataset on which it operates.

To find averages for a dataset without altering the original data, use the ave( ) function.

Options:

no option

Each value is the average of three values, the averaged value and its two neighboring values.

-l dataset [range]

Find the average of the first two points in dataset and last two points in dataset.  If the intervening points (third point through the n-2 point) fall outside the range defined by these two average values, then replace the intervening points with the closer of these two averages.  If an intervening point does not fall outside the range defined by these two averages, then leave the value unchanged.  (See the Examples section.)

-n N dataset [range]

Each value is the average of N points before and N points after.
ave -n 1 data1_B is equivalent to ave data1_B.

Examples:

The following script uses the six neighboring values plus itself (2*3+1) to find the average for each value in data1_b.

ave -n 3 data1_b;

The next script uses the four neighboring values plus itself (2*2+1) to find the average for each value in data1_b over the range of row index 10 to row index 20.

ave -n 2 data1_b -b 10 -e 20;

The last script calculates the averages of the first two points and last two points in data1_b.  It then replaces the intervening points that are outside the range of average values with the closer of these two averages.

ave -l data1_b;

For example, enter the following data in the Data1 worksheet:

A(X)	B(Y)

1	2

2	4

3	5

4	9

5	6

6	8

Enter the following script in the Script window:

ave -l data1_b   (ENTER)

The data1_b dataset is modified as follows:

A(X)	B(Y)

1	2

2	4

3	5

4	7

5	6

6	8

The average of the first two points in the original dataset is 3.  The average of the last two points in the original dataset is 7.  The only intervening point in the original dataset that is not between 3 and 7 is value 9 (row index 4).  Therefore, this value is replaced with the closest average value, which is 7.


Axis

Syntax:	axis [option] [xyzdialog]

Options:

no option xyzdialog

Open the Scale tab of the Axis dialog box with the X axis selected when xyzdialog is X.  Open the Scale tab of the Axis dialog box with the Y axis selected when xyzdialog is Y.  If xyzdialog is not included, open the Scale tab of the Axis dialog box with the Z axis selected.

-a axis

Open the Title & Format tab of the Axis dialog box for axis, specified as for -l.

-b axis

Open the Break tab of the Axis dialog box for axis, specified as for -l.

(Note:  axis = Z1 or Z2 is not supported for this option.)

-g axis

Open the Grid Lines tab of the Axis dialog box for axis, specified as for
-l.

-l axis

Open the Tick Labels tab of the Axis dialog box for the axis specified by axis:  X1=bottom X, X2=top X, Y1=left Y, Y2=right Y, Z1=front, and Z2=back.

-m axis

Open the Custom Tick Labels tab of the Axis dialog box for axis, specified as for -l.

-pg axis type varName

Get parameters for the specified axis (X or Y) and place the value into varName.  Type of parameter is either S (scale type:  0=linear, 1=log, etc.), G (grids displayed:  1=major, 2=minor, 3=both), A (axis display:  1=first, 2=second, 3=both), L (axis tick label display:  1=first, 2=second, 3=both), R (rescale margin:  in % of axis scale), or M (number of minor ticks).

Note:  The layer[n].axis object provides access to many more axis properties.

-ps axis type value

Set parameters for the specified axis (X or Y) to value.  Valid parameters are as described for the -pg option.  This option also includes type T (set tick labels from dataset where value specifies a dataset).

-s axis inc

Scroll the indicated axis (X or Y) by the specified increment inc.  Inc is given in major tick units, so axis -s x 3 scrolls the X axis by three major ticks.

Examples:

The following script sets the X axis to show both major and minor grids.

axis -ps X G 3;

The next script sets the X axis to a log scale.

axis -ps X S 1;


Command Reference - Alphabetical Listing of Commands - Break
Break

Syntax:	break [option] argument

Provides a visual interface to view the progress of a script with a loop.

Options:

no option [argument]

Unconditional exit from any loop.  If argument=1, also exit from the current script.

-b caption

Open the progress status dialog box with the caption caption.  This dialog box includes a Cancel button.  Click on the Cancel button to break from the entire script.  (Alternatively, use the break.open( ) method.)

-be caption

Open the progress status dialog box with the caption caption.  This dialog box includes an End button.  Click on the End button to break from the loop and continue the script after the loop.

-bm caption

Open the progress status dialog box with the caption caption.  All other controls in the dialog box are hidden.  Use this option to display the caption only.

-e

Close the progress status dialog box.

-p variable

Before using this option, you must use either the -b or -be option to open the progress status dialog box.  You must also use the -r option before using this option.

This command option updates the progress status dialog box with the value of variable converted to a percent using the min and max range set with the -r option.  For example, if min = 0 and max = 100 and the initial value of variable is 10, the percent completion display will start at 10%.  In general, variable is initialized and incremented in the loop.  (For an example using the -p and -r options, see the Examples section.)

-r min max

Before using this option, you must use either the -b or -be option to open the progress status dialog box.  Use this option before the -p option.  Set the range of values used in the percentage completion display in the progress status dialog box.

Examples:

In the following script, if a zero value is encountered in the data1_a dataset, the script displays an error message and breaks out of both the loop and the script.  If a negative value is encountered, the script breaks out of the loop.

myvar=0;

loop (ii, 1, 10) {

if (data1_a[ii]==0)  {

type -b "error";

break 1;  }

if (data1_a[ii]<0) break;

myvar+=(1/data1_a[ii]);

}

The next script utilizes the progress status dialog box.

break -b This is the caption for the dialog box;

break -r 500 1000;	// the range of values will be 500 - 1000

for (ii=500; ii<= 1000; ii++)  {

break -p ii;	// the current value is ii

// perform other tasks here   };

break -end;	// done, close the dialog box


Clipboard

Syntax:	clipboard [option] winName [path\filename]

Options:

no option winName

Copy to the clipboard the page in the winName graph window.

-c winName path\filename

Saves the specified graph window as a metafile with the specified filename.

Examples:

The following script creates the file WORKING.WMF as a metafile image of Graph1.

clip -c Graph1 c:\images\WORKING.WMF;


Continue

Syntax:	continue

Jump to the next iteration of a loop or for structure.

Examples:

In the following for loop, continue skips the type statement when ii is less than zero.

for (ii=-10;ii<=10;ii+=2)

{

   if (ii<0) {continue;};

   type "$(sqrt(ii))";

};

The next script adds a Real column to the Test1 worksheet.  It tests each value in the Test1_B dataset and adds the values that are not null to the Test1_Real dataset.

Test1!wks.addCol(Real);	//Add col name Real to end of Test1

get Test1_B -e EndIndex;	//EndIndex is # of last value in Test1

for (ii=1, jj=1; ii< EndIndex; ii++)

{

   if (Test1_B[ii] == 0/0)	//If ii index number value is null

{

   continue; 	//Skip the rest of this iteration of the loop

};

   Test1_Real[jj] = Test1_B[ii];

   jj++;	//Iterate Real index # after value has been added

};


Command Reference - Alphabetical Listing of Commands - Copy
Copy

Syntax:	copy [option] dataset1 dataset2 [dataset3]

Copy one dataset into another.  Increase the size of the destination dataset as necessary.  To determine the number of elements copied with the copy command, use the copy.n object property.

Note:  The copy command should not be used to move data within the same dataset.  Instead, create a duplicate of the worksheet and use that as the source dataset.

Options:

no option dataset1 dataset2

Copy the contents of dataset1 into dataset2.

-a dataset1 dataset2

Append contents of dataset1 to the end of dataset2.

-b rowIndex# dataset1 dataset2 -b start# -e end#

Copy from rowIndex# of dataset1 to dataset2, beginning at the dataset2 start# and ending at end#.  The destination range must be within the existing range of dataset2, and the source range must not go outside the existing range of dataset1.

-f dataset1 dataset2

Copy dataset1 to dataset2 but remove the last point and swap the two halves of dataset2.  This option reverses the effects of the -m option if applied to each of the new datasets.

-m dataset1 dataset2 dataset3

To use this command, there should be a multiple of 4 points in dataset1, the source dataset.  Copy the odd entries of dataset1 to dataset2 and the even entries to dataset3.  If n is the number of rows in dataset1, take the cell value in row index n/2+1 in dataset1 and copy this value to row index n/2+1 in dataset2.  Take the cell value in row index n/2+2 in dataset1 and copy this value to row index n/2+1 in dataset3.  Dataset2 and dataset3 now have n/2+1 points.  Excluding the last row in dataset2 and dataset3 (row index n/2+1), move the first half of each dataset to the end (n/2) of the dataset.

-s npts dataset1 dataset2

Set dataset2 to a size of npts.  Copy dataset1 into dataset2 such that the entire range of dataset1 is interpolated to fit into dataset2 with npts.  For example, if data1_a contains the integers from 1 to 10, then copy -s 5 data1_a temp; copies the values 1, 3.25, 5.5, 7.75, and 10 into temp.  To view the results of this script, type edit temp (ENTER) in the Script window.

Note that this command works only when the destination dataset does not have an associated X column.

-u dataset1 dataset2 dataset3

Split (unzip) dataset1 into dataset2 and dataset3 so that the first point in dataset1 becomes the first point in dataset2, the second point in dataset1 becomes the first point in dataset3, etc.   Reverse of the -z option.

-x dataset1 dataset2

Copy dataset1 to dataset2 where dataset2 is in a different worksheet.  Copy the corresponding X dataset if it exists.

-z dataset1 dataset2 dataset3

Combine (zip) dataset1 and dataset2 and copy into dataset3 such that the first point in dataset3 is the first point in dataset1, the second point in dataset3 is the first point in dataset2, etc.  Reverse of the -u option.

Examples:

The following script copies Data1_B to Data2_D and copies the X column of Data1_B to the X column of Data2_D.

copy -x Data1_B Data2_D;

The next script copies 20 points from Data1_B (74-55+1), beginning at the 13th point, to Data1_F beginning at the 55th cell.

copy -b 13 Data1_B Data1_F -b 55 -e 74;

The last script creates odd and even 'folded' datasets (data1_b and data1_c), then 'unfolds' them (data1_d and data1_e) and combines these to re-create the original dataset (data1_f=data1_a).

copy -m data1_a data1_b data1_c;

copy -f data1_b data1_d;

copy -f data1_c data1_e;

copy -z data1_d data1_e data1_f;


Command Reference - Alphabetical Listing of Commands - Create
Create

Syntax:	create name [option] [numPoints]

Creates a dataset or worksheet with name name with the number of points numPoints.  NumPoints should be the maximum number of points you anticipate requiring.  Each dataset is associated with values and attributes.  To change the attributes or values for a dataset, use the set command.  To view the worksheet for a dataset, use the edit dataset command.

Note 1:  The syntax of the create command requires that the name of the object to be created be included immediately after create, and before the option.

Note 2:  Datasets can also be created with the data( ) function.

Options:

-c numPoints

Create a Y dataset and associated X dataset containing all zero values.  To plot this data you must specify values for both X and Y.  The Y dataset is called name.  The X dataset is called name_A.  If name contains an underscore " _ ", it and subsequent characters are ignored when naming the X dataset.  So, if name is data1_test, X is called data1_A.

Note:  If a graph window is active when this command is executed, the data is automatically added to the active layer.

-d numpoints

Create a dataset and an associated X dataset named name_A.  Plot the datasets into the active graph layer as a scatter data plot.

Note:  If a graph window is active when this command is executed, the data is automatically added to the active layer.

-f

Create a function.  While you can use this notation to create a function, a simpler method is:  myFunc(x)=3+3*sin(x);

Note:  If a graph window is active when this command is executed, the data is automatically added to the active layer.

-m numPoints

Create a dataset associated with a double-headed vertical arrow as the data point symbol type.  Otherwise, same as -c above.

Note:  If a graph window is active when this command is executed, the data is automatically added to the active layer.

-n numPoints

Create an empty Y dataset with no associated X values.  When plotting, assume an initial X value of 1 and an increment of 1.  Use the set command to change these X attributes.  To view the dataset, use the edit datasetname command.

Note:  If a graph window is active when this command is executed, the data is automatically added to the active layer.

-s

Create a string dataset.

Note:  If a graph window is active when this command is executed, the data is automatically added to the active layer.

-t numpoints

Create a temporary dataset.  Temporary datasets cannot be plotted.

-w numPoints [colName(s)]

Create a worksheet.  You may specify column names after numPoints.  If you specify column names, you must specify at least two.  To view the worksheet, use the edit datasetname command.

Note:  Use the window command to open a worksheet created from a specific template.

-wd numPoints [colName(s)]

Same as -w, but create a worksheet that is not displayed.  You may specify column names after numPoints.  Use this option for storing intermediate data.

-x numPoints

Create a dataset associated with a vertical line as the data point symbol type.  Otherwise, same as -c above.

Note:  If a graph window is active when this command is executed, the data is automatically added to the active layer.

Examples:

The following script creates an empty dataset named data which is set to hold 1000 points.

create data -n 1000;

The next script creates an invisible worksheet named Hidden having four columns named aa, bb, cc, dd, with 117 cells each.

create Hidden -wd 117 aa bb cc dd;


DDE

Syntax:	dde [option] argument

The dde command provides Dynamic Data Exchange support with Origin as the client application.

Options:

-c application|topic [varID]

Connect to the specified application with the specified topic.  The Application|Topic string should have the application name and topic connected with a "|" character.  If the connection is successful, an ID (>=0) is assigned to the connection and is stored in the specified variable varID.  If varID is not specified, the system variable v1 is used.  If the connection is not successful, (-1) is stored in the variable.

-d varID

Disconnect the specified conversation.

-e varID string

Execute the specified command string string in the server application specified by varID.

-i application|topic [varID]

Find the conversation ID for the specified application with the specified topic.  The application|Topic string must have the application name and topic connected with a "|" character.  If the specified conversation is found, its ID is stored in the specified variable varID.  If varID is not specified, the system variable v1 is used.  If the conversation cannot be found, (-1) is stored in the variable.

-l [application]

List all DDE conversations and display them in the Script window.  If application is specified, only those conversations with the specified application are listed.

-lz [application]

List all DDE conversations and put the result into the %Z string, which can then be searched with substring commands.  If application is specified, only those conversations with the specified application are listed.

-p varID item string

Poke string to the server application as specified by the varID, under the specified item.

-pc varID ServerItem wksItem

Poke in column order the data from wksItem to the ServerItem with the specified varID.  The ServerItem should specify a range large enough to hold the data range specified by the wksItem.

-q n

Quiet Origin in terms of DDE warning message boxes.  If n=1, no warning message boxes are displayed.  If n=0, Origin is reset to its normal state.

-r varID item

Request the item item from the server application specified by varID.  The result is placed in the %Z string if the operation is successful.

-rc varID ServerItem wksItem

Receive in column order the ServerItem with the specified varID into the specified wksItem.  Column type should match the type of data being received.  If the wksItem is the dataset name, then data is appended to the first empty row.  If you specify a cell with Dataset!RiCj, then data replaces existing data.  Data above the replacement point is retained, data below is removed.  If you specify a range with Dataset!RiCj:RkCl, then data replaces the existing block of data without removing data below.

-rr varID ServerItem wksItem

Receive in row order (transpose rows and columns) the ServerItem with the specified varID into the specified wksItem.  See the -rc option for additional information.

Examples:

For the following examples, Excel needs to be running.  Either launch Excel manually or use the run -e command.

The following script connects to application Excel and topic Sheet1 and remembers the connection as idExcel.

dde -c excel|sheet1 idExcel;

The next script pokes the slope value (LR.B) of the most recent linear regression to Excel row 1, column 1.

dde -p idExcel R1C1 $(LR.B);

The last script requests the cell value of row 2, column 1 in Excel and assigns it to the variable value.

dde -r idExcel R2C1;value=%Z;


Define

Syntax:	define macroName {script}

This command defines a macro called macroName, and associates it with the given script.  MacroName can then be used like a command, and invokes the given script.

To see the script associated with a defined macro, use:

define macroName;

Macros can take up to five arguments.  Use the %1, %2, %3, etc., notation within the script to indicate that the macro expects one or more arguments.  A macro can accept a number, string, variable, dataset, function, or script as an argument.  These are similar to MS-DOS batch command arguments.

If arguments are passed to a macro, the macro can report the number of arguments using the macro.narg object property.

Examples:

The following script defines the autoexec macro to create a new Origin worksheet from the ORIGIN.OTW template.

def autoexec { window -T Data Origin; };

The next script defines a macro that uses a loop to print a text string three times.

def hello {

loop (ii, 1, 3) { type "$(ii). Hello World"; };

};

Once the hello macro is defined, typing the word hello in the Script window results in the printout:

1. Hello World

2. Hello World

3. Hello World

The following script defines a macro named double that expects a single argument.  The given argument is then multiplied by 2, and the result is printed.

def double { type "$(%1 * 2)"; };

If you define this double macro (previous example) and then type the following in the Script window:

double 5

Origin responds:  10

We could modify the double macro (previous example) to take two arguments:

def double { type "$(%1 * %2)"; };

Now, if you type the following in the Script window:

double 5 4

Origin responds:  20


Delete

Syntax:	delete [option] <name>

Delete the specified object.

Options:

no option name

Delete the given dataset or function.

-a

Delete all the temporary datasets, including all the axes datasets.

-m macroName

Delete the macro macroName.

-v variableName

Delete the numeric variable variableName.

Note:  To delete a string variable, assign a null string to the variable:  %M="";

Examples:

The following script deletes all variables that begin with "ex".

del -v ex*;


Derivative

Syntax:	derivative [option] dataset [range]

Takes the derivative of dataset.  Make a copy of dataset before using this command if you do not want to lose the original data.  The derivative is calculated by averaging the slopes to neighboring points.  Range allows you to specify that the derivative should be performed on a subset of the dataset.

Options:

no option dataset [range]

Take the derivative.

-p dataset [range]

If either slope value is zero, or if the two have opposite signs, the resulting derivative is considered to be zero.

Examples:

The following script takes the derivative of Data1_B within the range of row index 2 to row index 10.

der Data1_b -b 2 -e 10;


DLL

Syntax:	dll [options] dllName <dllFunctionName dllString>

Options:

no option dllName dllFunctionName dllString

Execute a function called dllFunctionName from a user-provided Dynamic Link Library named dllName.  The dllString is passed to the DLL, which uses the string to perform necessary tasks.

-a name dllName

Add the dllName DLL to the LabTalk command list as a new command object named name.  Do not reference a variable or DLL already in use by Origin.  This DLL must have been created using information provided by Microcal Software and conform to Origin's external DLL convention.  The DLL can also be added to Origin through the [AddOn] section in the ORIGIN.INI file.

Note:  A much more flexible DLL calling mechanism is available and described in Origin Professional.  For information on Origin Professional, contact Microcal Software or your Origin dealer.


Document

Syntax:	document option argument

Performs various operations on projects.  Special counting and looping options are available.

Options:

-a fileName

Appends the contents of fileName to the current project.  FileName must be a full path description, including the file extension.  FileName can be a project file or child window file.

-af fileName

Append the contents of fileName to the current project by first looking in the current directory and then in the software directory.  FileName can be a project file or child window file.

-cl

Count all layers in the active graph window.  Assign the result to the variable count.

-cp [name]

Count all graph windows in the current project that match exactly or begin with name.  Assign the result to the variable count.

-cs [name]

Count all datasets in the current project that match exactly or begin with name.  Assign the result to the variable count.  A matrix is also counted as a dataset.

-cw [name]

Count all worksheets in the current project that match exactly or begin with name.  Assign the result to the variable count.

-cws [name]

Count all worksheet and all datasets in the current project that match exactly or begin with name.  Assign the result to the variable count.

-d

Close the current project.  Execute the DocEnd macro.  Do not exit Origin.

-e object {script}

Execute the given script for all objects of the specified kind.  This command makes an object active and executes the associated script, looping until each object of the specified type has been active.  Most LabTalk commands, methods, and properties act on the active window.  Use system variables when a name is required so that the loop script affects the active object.

Object can one of the following:

D:  Data plot in the active layer.  %H contains the graph window name and %C the dataset name in each iteration.

DY:  Data plot in the active layer excluding error bars and labels.  %H contains the graph window name and %C the dataset name in each iteration.

G:  Labels and other named objects in the active layer.  %B contains the object name in each iteration.

L:  Layer (worksheet and matrix each have one layer).  %H contains the window name in each iteration.  Page.active holds the active layer number.

LW:  Layers in current window.  %H contains the window name in each iteration.  Page.active holds the active layer number.

M:  Matrix.  %H contains the matrix name in each iteration.

O:  Any non-minimized window.  %H contains the window name in each iteration.

P:  Graph window.  %H contains the graph window name in each iteration.

S:  Dataset in the project.  %C contains the dataset name in each iteration.

W:  Worksheet.  %H contains the worksheet window name in each iteration.

-l

Send an update message to all windows.

-n

Execute the DocEnd macro.  Close the current project.  Read the ORGSYS.CNF file.  Open a new project.  The new project does not contain any child windows.

-o projectName

Execute the DocEnd macro.  Close the current project.  Read the ORGSYS.CNF file and then execute the DocBegin macro.  Open the named project.  ProjectName must be a full path description, including the file extension.

-of projectName

Execute the DocEnd macro.  Close the current project.  Read the ORGSYS.CNF file and then execute the DocBegin macro.  Open the named project.  ProjectName must be a full path description, including the file extension.  Look for projectName first in the current directory and then in the software directory.

-r newName

Rename the current project to newName.

-s

Turn off the save flag so that no save prompt appears on exit.

-t path templateFilename

Open the template file templateFilename.  Use this command to open a template from any directory.  You must specify a full path description, including the file extension.  Similar to the Window -t command and Page -t command, except you must use a full path description.

-u

Set update flags for all layers in all windows.

-uw

Set update flags for all layers in the current window only.

Examples:

The following script prints the contents of all graph windows in the project.

doc -e P print;

The next script rescales all layers in the project to show all data, sets each initial X axis scale value to zero, and types the window name and layer number of each to the Script window.

doc -e L

{

layer -a;

x1 = 0;

type "Window: %H, layer number: $(page.active)";

};

The following script puts the name of the first worksheet into %A.

doc -e W

{

%A = %H;

break;

};

The last script refreshes the active window.

doc -uw;  clr;


DoToolbox

Syntax:	dotoolbox [option] < tool# [message1 message2 ...] >

Use this command for management of the Tools toolbar tools and tool control.  Most of these options perform their functions on the currently selected tool, so you may need to first select a tool before specifying an option for that tool.

Options:

no option tool# [message1 message2 message3 ...]

Select the tool tool# from the Tools toolbar.  Tool# must be a value from 0 (selects the Pointer tool) to 11 (selects the Circle tool).  Each message defines a line of help text for the tool tool# that can be displayed in the status bar.  Dotoolbox automatically displays message1 if specified.

-a

Equivalent to pressing the ALT key.  The function for this switch is not defined.

-b toolNumber

Block the Tools toolbar tool toolNumber.  This option makes the tool unavailable for selection.

-c

Equivalent to pressing the CTRL key.  Allows you to click-and-drag to move data points (the data must be movable - either drawn with the Draw Data tool, or set as movable with the set command).  This option has an effect only when the Data Reader tool is active.

-d

Make a single mouse click equivalent to double-clicking.

-h message

Append message to the end of the list of Tools toolbar status bar help messages for the selected tool.  The list is first-in-last-out.

Note:  dotool -h and dotool -n are intended to be used sequentially (-h first).

-k

After selecting the Data Reader tool and executing dotool -k, the cursor does not move with the current data point selection when using the left and right arrows on the keyboard.

-l

Restrict a Tools toolbar tool to the active layer.

-n

Advance to the next defined help message and display the text in the status bar.

Note:  dotool -h and dotool -n are intended to be used sequentially (-h first).

-p [WindowName]

Select a graph or worksheet window to be pasted to the layout page window.  If WindowName is specified, that window is used.  If no window is specified, the Select Worksheet Object dialog box opens.  Once the window is selected, click-and-drag an area within the layout page window for the object.

-pw [WindowName]

Select a worksheet window to be pasted to the layout page window.  If WindowName is specified, that window is used.  If no window is specified, the Select Worksheet Object dialog box opens.  Once the window is selected, click-and-drag an area within the layout page window for the object.

-pg [WindowName]

Select a graph window to be pasted to the layout page window.  If WindowName is specified, that window is used.  If no window is specified, the Select Graph Object dialog box opens.  Once the window is selected, click-and-drag an area within the layout page window for the object.

-q

Quit the Tools toolbar.  De-select the current tool and select the Pointer tool.

-r dataset [index]

When using the Data Selector or Data Reader tools, this option restricts the cursor to only select within dataset.  If index is included, the Data Selector or Data Reader tool moves to position index+1.

-s

Equivalent to pressing the SHIFT key.  Multiplies the cursor movement speed by 10.

-t show

Show or hide the Tools toolbar.  Show can be the following values:  1=show and 0=hide.

-u toolNumber

Unblock the tool toolnumber.  If toolNumber is not specified, unblock all tools.

-w

The dotoolbox -w commands are tool commands.

-x

When using the Screen Reader tool, this option restricts the cursor to horizontal-only movement at the current Y value.

-y

When using the Screen Reader tool, this option restricts the cursor to vertical-only movement at the current X value.

-z

Activates the Zoom tool while the current tool is still active.

Examples:

The following script displays a message in the status bar and uses the Screen Reader tool with restrictions to the current layer.

dotool 2 (Click a location to read X and Y values);

dotool -l;

The next script displays a message in the status bar and uses the Data Reader tool with (single) clicks causing double-clicks.  After a 5 second delay, another message displays and the tool reverts back to the Pointer tool.

dotool 3 (Select a point by clicking on it) (Time is up);

dotool -d;

sec -p 5;

dotool -n;

dotool 0;

More:

Programming the Screen Reader and Data Reader Tools

Programming the Data Selector Tool

Tool Controls


Programming the Screen Reader and Data Reader Tools

The Screen Reader and Data Reader tools are programmable.  If you double-click or press ENTER when one of these tools is active, the PointProc macro is executed.  You can define this macro to perform any function.

When you select one of these tools, related information is read into the following variables:

X, Y

The X and Y coordinate values of the current cursor position.  The values update each time you click the cursor.

px, py

The physical position of X and Y on the page, measured in pixels from the top left corner of the page.  The values update when you double-click or press ENTER.

count

Number of times the PointProc macro has been executed since this tool was selected.  The value updates when you double-click or press ENTER.

%C

Name of the dataset the Data Reader tool is currently reading (case sensitive).  The value updates when you double-click or press ENTER.

index

Index number for the data point currently selected by the Data Reader tool.  The value updates when you double-click or press ENTER.


Programming the Data Selector Tool

When you use the Data Selector tool to set the beginning and ending data markers, the internal variables mks1 and mks2 are set and can then be used in script.  When programmatically accessing the Data Selector, it is convenient to re-program the PointProc macro to automatically execute a script after you double-click or press ENTER to set the markers.

The following script reports the row index and the X and Y values for each marker.

dotool 4;

def pointproc {

   py=%C[mks1];

   %A=xof(%C);

   px=%A[mks1];

   type -a Left marker is at index $(mks1), X is $(px),Y is $(py);

   py=%C[mks2];

   %A=xof(%C);

   px=%A[mks2];

   type -a Right marker is at index $(mks2), X is $(px),Y is $(py);

   dotool 0;

};


Tool Controls

Tools (for example, the Linear Fit tool) are Origin objects.  Their structure and appearance are saved in *.OGO files.  The scripts associated with tools are saved as *.OGS files.  Each active element in a tool uses the run.section( ) method to run the applicable part of the *.OGS file.  The *.OGS files can be opened, altered, and saved in a text window or any other text editor.

The following commands are available for accessing built-in and custom-built tools.

-w name

Open a tool from the NAME.OGO file.  Full path can also be included in name.  If the same tool is already open from a menu command or previous script command, this option will result in an error.

Note:  Once a non-modal tool is open, it can only be toggled-off (made invisible) using the dotool -wc name command or by de-selecting the menu command.  To open a modal tool from script, use the dotool -wd name command.  If a tool has already been opened as non-modal, there is no way to open it as modal, unless you close it and restart Origin.

-wc name

Close the named tool.

-wl name

Allow script access to the tool's objects beyond the scope of the tool.  The tool must already be open to use this command.

-wl0 name

Disallow script access to the tool's objects beyond the scope of the tool.  The tool must already be open to use this command.

Examples:

The following script opens the Layer tool.

doTool -w1 layer;	// for the current window only


Command Reference - Alphabetical Listing of Commands - Draw
Draw

This command has two types of options:  options to draw and set formatting for lines, and options to perform various operations on named objects.  The syntax for each is slightly different.  Thus, they are documented separately.

More:

Draw Command, Line Options

Draw Command, Object Options


Draw Command, Line Options

Syntax:	draw [option(s)] -l [-h / -v] value

Create a line or alter a named line.  To create an arbitrary line, value should specify the beginning and ending X and Y values, as follows:  {X1,Y1,X2,Y2}.

If -h is specified, a horizontal line is created at the Y position of value.  If -v is specified, a vertical line is created at the X position specified by value.

Any of the following options can be used to set line characteristics.  Options are cumulative.

Note:  By default, lines created with the draw command are not movable.  Use the Label Control dialog box or LineName.Vmove=1; LineName.Hmove=1; to make the line movable.

Options:

no option

Create a line with default color, dash, and width settings.  The line will not have a name.  To alter an unnamed line, double-click on the line to open the Arrow Control dialog box or ALT+double-click to open the Label Control dialog box.

-c #

Set line color.  # equals the numeric position in the color list.

-d #

Set dash pattern.  # equals the numeric position in the dash pattern list.

-n LineName

Assign a name to a line being created, or alter the existing named line.  Only lines with names can be altered through script commands, including the draw command, object options (below), and object properties and methods.  The -n option must directly follow the draw command.

-w #

Set line width.  # equals point size.


Draw Command, Object Options

Syntax:	draw -n objectName [option(s)]

Alter an existing named object as specified by the options.  Options are cumulative.

Objects are graphic elements.  To create an object, select a tool from the Tools toolbar (such as the Arrow or Text tool) and click-and-drag in an open area within an Origin window.  A text label can also be created from script with the label command.

Only named objects can be altered by LabTalk script.  To name an object, hold down the ALT key and double-click on the object.  This action opens the Label Control dialog box.  Enter a name in the Object Name text box and click on the OK button to close the dialog box.

Options:

-f save  fileName

Save objectName to a fileName.OGO file.  FileName can contain the DRIVE:PATH specification.  When used on an object with script in the Label Control dialog box, this command copies the object's script and all settings along with the object.

-f read  fileName

Read objects from a file and paste them into the current layer.  If objectName has been specified with the -n option, the name of the new object is set to objectName.

-fb save  fileName

Save objectName to a file when it is a bitmap.  FileName can contain the DRIVE:PATH specification.

-fb read  fileName

Read a bitmap from a file into the named object objectName.  The objectName object must be a bitmap object.  FileName can contain the DRIVE:PATH specification.

Note:  This option allows you to import bitmaps.  However, you are limited to bitmaps of less than 64K.

-fm read  fileName

Read a metafile from a file into the named object objectName.  The objectName object must be a metafile object.  FileName can contain the DRIVE:PATH specification.

-i inverse

Set the objectName object to the inverse of the editing state if inverse is 1.  Editing state refers to the Button Edit Mode.  When the objectName object is set to the inverse of the editing state, it is in Button Edit Mode when the system is not in Button Edit Mode, and vice versa.

-r

Run the named object's script if there is one.  The objectName.run( ) method can also be used to execute an object's script.

-s value

Show or hide the objectName object.  Value=1 to show, 0 to hide.

-u

Update objectName.  The object is redrawn without redrawing the entire graph.  The objectName.draw( ) method can also be used to update a named object.

-uf

Update objectName.  The object is redrawn without redrawing the entire graph.  Only parts of the object that support this option are redrawn.

-v set

Set all numeric fields in the objectName's content to values in variables v1, v2, v3, etc.  Numeric fields must be proceeded by an "=" sign.

-v get

Assign the values in all numeric fields in the objectName's content to variables v1, v2, v3 and etc.  The reverse of -v set.

-x value

Set objectName's X position to the specified value in the current X axis scale.

-y value

Set objectName's Y position to the specified value in the current Y axis scale.

-z get

Copy the message of the objectName text label into the %Z string variable.  The specified object must be a text label or the command returns an error.

-z set

Copy the message of the %Z string variable to the objectName text label's content.  The specified object must be a text label or the command returns an error.  The reverse of -z get.

Examples:

The following script creates a dashed vertical line that runs the height of the layer frame.

draw -d 2 -l -v X;

The next script creates a horizontal line at the center of the graph, with the name YLine.

draw -n YLine -L -h [(y1+y2)/2];

The next script moves YLine (previous example) to the top of the graph.

draw -n YLine -L -h y2;

The following script creates a green, 4-point-wide line that runs from coordinates X1, Y1 to X4, Y6.

draw -c 2 -w 4 -l {1, 1, 4, 6};

The next script copies the metafile MYFILE.WMF into the named metafile object MyObject.

draw -n MyObject -fm read C:\MYDIR\MYFILE.WMF;

In the following script, assume myText is a named text label with the original content:  mean=8.2 and sd=1.2.

The script redraws the object to become:  mean=10.3 and sd=2.5.

v1 = 10.3;

v2 = 2.5;

draw -n myText -v set -u;

doc -uw;   // refresh the window


Edit

Syntax:	edit [options] <datasetName>

Options:

no option

Open the worksheet for the dataset datasetName.

Note:  Use this command to view a worksheet created with the create -w command.

-c

Open the Color Palette dialog box, allowing you to edit the color palette.

Examples:

The following script opens the worksheet for the active dataset.

edit  %C;


Exit

Syntax:	exit

Exit from Origin.  Prompts you to save changes before closing.  You can disable the save prompt with the doc -s command.


File

Syntax:	file option Path\FileName1 Path\FileName2

Options:

-c Path\FileName1 Path\FileName2

Copy FileName1 to FileName2.  If no path is specified, the default Origin path is used.


For

Syntax:	for (expression1; expression2; expression3) {script}

The for command is identical to the C For loop.  First, expression1 is evaluated.  This specifies initialization for the loop.  Second, expression2 is evaluated and if true, then script is executed.  (If no conditional operator is used in expression2, any non-zero value is accepted as true.)  Third, expression3, often an incrementation, is executed.  The process repeats at the second step.  The loop terminates when expression2 is found to be false.  Any expression can consist of multiple statements, each separated by a comma.

Note:  If your script loops endlessly, you can interrupt the script by pressing ESC.

Examples:

The following for loop:

for (ii=1; ii<=4;ii++) {type "ii=$(ii)";};

Produces the output:

ii=1

ii=2

ii=3

ii=4

The next for loop:

for (ii=1,jj=4;ii<=4;ii++,jj--)

{

type "ii=$(ii), jj=$(jj)";

};

Produces the output:

ii=1, jj=4

ii=2, jj=3

ii=3, jj=2

ii=4, jj=1

More:

While Loop Simulation


While Loop Simulation

LabTalk does not have a While command.  However, the While command may be easily simulated with the for loop.

The While loop syntax follows:

expression1;

while (expression2) {

statement

expression3;

};

The equivalent for loop syntax follows:

for (expression1; expression2; expression3)

statement

The following for loop script simulates a While loop.  This script continues to prompt for new values until you enter zero or a negative number.

p=1;

for ( ;p>0; ) {

getn -s (Enter 0 to quit) p (Next value);

};


Get

Syntax:	get name option [variableName]

Similar to the set command, this command gets the value of a certain attribute of the dataset, data plot, or worksheet specified by name, and places this value into variableName.  If variableName is absent, the value is placed into the variable v1.  The option switch determines what value is placed into variableName or v1.

Options:

-b [variableName]

Get the beginning of the display range (the value of variableName equals the first index number).

-c [variableName]

For data plots with symbols or lines, get the line color and the symbol edge color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-cf [variableName]

Fill color (for fill area graphs).  Get the fill color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-cl [variableName]

For data plots with lines, get the line color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-cmn [variableName]

Color for level n in a color mapped data plot.  Get the color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-cse [variableName]

For data plots with symbols, get the symbol edge color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-csf [variableName]

For data plots with symbols, get the symbol fill color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-czn [variableName]

Value for Z level n in a color mapped data plot.

-d [variableName]

Get the line style index number:  0=solid, 1=dash, etc. as in the line style list.

-e [variableName]

Get the end of the display range (the value of variableName equals the last index number).

-f [variableName]

Get the corresponding X value for the first data point when X values are from an initial value and an increment.

-hbb [variableName]

For a histogram, get the lower limit of the binned data.

-hbe [variableName]

For a histogram, get the upper limit of the binned data.

-hbs [variableName]

For a histogram, get the bin size.

-i [variableName]

Get the X increment for the name dataset when X values are from an initial value and an increment.

-k [variableName]

For graphs with symbols, get the symbol shape:  0=no symbol, 1=square, 2=circle, 3=up triangle, 4=down triangle, 5=diamond, 6=cross (+), 7=cross (x), 8=star (*), 9=bar (-), 10=bar (|), 11=number, 12=LETTER, 13=letter, 14=right arrow, 15=left triangle, 16=right triangle, 17=hexagon, 18=sphere, 19=star, 20=pentagon.

The numeric values of 56 and 58 display special symbol types:  56=data markers and 58=vertical lines that mark the X position of the data point.

-kb [variableName]

For graphs with data labels, check if the data labels display in bold font style.  1=bold on, 0=bold off.

-kf [variableName]

For graphs with symbols, get the symbol interior:  0=solid, 1=open, 2=dot center, 3=hollow, 4=+ center, 5=x center, 6=- center, 7= | center, 8=half up, 9=half right, 10=half down, 11=half left.

-ki [variableName]

For graphs with data labels, check if the data labels display in italic font style.  1=italic on, 0=italic off.

-kn [variableName]

For graphs with alphanumeric symbols (set DatasetName -k 12 or
set DatasetName -k 13), get the font index.  Use get DatasetName -kn variableName.  For example:  get data1_b -kn fontVariable;.

-ku [variableName]

For graphs with data labels, check if the data labels display with an underline.  1=underline on, 0=underline off.

-l [variableName]

Get the line connection method, numbered in order:  0=scatter, 1=line, 2=segment, 3=segment3, 8=Bspline, 9=spline, 11=step horz, 12=step vert, 13=step center, 15=Bezier.

-lh [variableName]

Check if horizontal drop lines are displayed:  1=show drop lines, 0=hide drop lines.

-lhc [variableName]

Get the horizontal drop line color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-lhs [variableName]

Get the horizontal drop line style:  0=solid, 1=dash, etc. as in the line style list.

-lhw [variableName]

Get the horizontal drop line width, with 500=1 point.

-lv [variableName]

Check if vertical drop lines are displayed:  1=show drop lines, 0=hide drop lines.

-lvc [variableName]

Get the vertical drop line color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-lvs [variableName]

Get the vertical drop line style:  0=solid, 1=dash, etc. as in the line style list.

-lvw [variableName]

Get the vertical drop line width, with 500=1 point.

-m [variableName]

Get dataset movability with the cursor.  1=movable, 0=not movable (default).

-nhw [variableName]

Get the frequency worksheet name associated with the histogram.

-nhwc [variableName]

Create the frequency worksheet associated with the histogram.

-pbc [variableName]

For data plots with bars or columns, get the border color of the bar or column following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-pbs [variableName]

For data plots with bars or columns, get the border line style of the bar or column:  0=solid, 1=dash, etc. as in the line style list.

-pbw [variableName]

For data plots with bars or columns, get the border line width of the bar or column, with 500=1 point.

-pd [variableName]

Check if vertical drop lines are displayed:  1=show drop lines, 0=hide drop lines.  (See also the -lh and -lv options.)

-pf [variableName]

Check if the fill area option is enabled:  1=fill area on,  2=fill area off.

-pfb [variableName]

For data plots with bars or columns, get the background color of the bar or column following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-pfc [variableName]

For data plots with bars or columns, get the foreground pattern color of the bar or column following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-pfp [variableName]

For data plots with bars or columns, get the fill pattern of the bar or column following the pattern drop-down list:  0=none, 1=dense, 2=medium, etc.

-pfw [variableName]

For data plots with bars or columns, get the fill pattern line width, with 500=1 point.

-pt [variableName]

Get the dataset's column designation.  X=200, Y=201, Z=202, Y error=231, label=232.

-s [variableName]

Get whether the data plot is hidden:  1=shown, 0=hidden.

-skip [variableName]

Get the skip value (if used) for a dataset.

-tf [variableName]

Get the data label font, where font is the index number in the current font list.

-tj [variableName]

Get the data label justification:  0 for left, 1 for center.

-tr [variableName]

Get the data label text rotation angle.

-ts [variableName]

Get the font size for the data label text.

-tx [variableName]

Get the Y offset for the data label plot.  Y offset is in percent of label text height.

-ty [variableName]

Get the X offset for the data label plot.  X offset is in percent of label text height.

-w [variableName]

Get the width of connecting lines, with 500=1 point.

-z [variableName]

Get the data point symbol size, in points.  One point=1/72 inch.

Examples:

The following script creates the variable EndIndex (if it does not already exist) and sets it equal to the index number of the end index in the display range.

get data1_b -e EndIndex;


GetFileName

Syntax:	getfilename [option] argument

Options:

no option file

File is the default file type specification.  This option opens the Open dialog box, with file displayed in the Files of Type drop-down list.  After editing the dialog box, %A contains the file name and %B contains the full path to the file.

-g n

Gets the nth file name with full path into the %A string variable from the file list created by getfile -m.

-m file

File is the default file specification and the default file type specification.  Opens the Import Multiple ASCII dialog box.  The number of files selected is stored in the variable count.

Examples:

The following script prompts for a file name and imports ASCII data into the active worksheet.

getfile *.dat;open -w %A;

The next script prompts for a file name with multiple types (Lotus and DIF files) of files to import into the worksheet.

getfile *.WKS *.DIF;open -wf %A;

The following script (placed in a button on a worksheet) prompts the user to select multiple files and prints the file names to the Script window.

type -a; //open the Script window

getfile -m *.*;  // prompt for multiple files

for ( ii = 1; ii <= count; ii ++)

{

getfile -g ii; // get the iith file into %A

type "%A"; // print it out in the Script window

};


GetNumber

Syntax:	getnumber [options] (text1) variable1 (text2) variable2 	 [dialog box title]

Opens a dialog box that allows user input of up to six numbers or strings, which are placed into variables variable1 through variable6.  Text1 through text6 are the dialog box text associated with each variable.  Dialog box title appears in the dialog box title bar.

To specify a string variable, you must use the double % notation.  For example:  %%A.  This is necessary to protect the integrity of the string variable.

To specify a binary variable with a check box instead of an edit box, insert ":2" after the name of the variable.  You can also show or hide items below by specifying ":2s" or ":2h".  The former shows all items below if the check box is enabled, while the latter hides them.

A drop down list can also be specified and the variable will represent the selection index in the list.  In this case, you must first put the list in a string variable, and specify the character for the string variable after the ":".

Standard lists like the color list may also be specified.  They are ":@C" for the color list, ":@D" for the dashed line list, ":@T" for the font list, ":@S" for the font size list, and ":@P" for the pattern list.

Note:  In addition to entering literal text for text1, text2... and dialog box title, you may specify $[OMGfileName].Section.Title.  This enables you to access a string title in a message file.  The OMGfileName extension is assumed to be OMG.  If OMGfileName is not specified, the ORIGIN.OMG file is assumed.  For an example using this syntax, see the Type command.

Options:

-s text1 variable1 [dialog box title]

For getting a single value, this option opens a smaller dialog box with a single entry.  This option is available for entering numbers only.

Examples:

The following script illustrates the use of the getnumber command.

%A=enter name; i = 1; j = 1;k=0;	// initialization

%B = "line1 line2 line3";	// drop down list with three entries

getn

(X Minimum)  MyVar 	// a variable

(my boolean)  k:2s 	// show remaining items if k = 1 (checked)

(my list)  i:B 	// use %B as the list items

(Color)   j:@C 	// color list, init j = 1

(Your Name) %%A  	// %% to preserve %A for holding the name

(Title of this dialog); 	 // end of getnumber

When the My Boolean check box is selected in the dialog box, the dialog box displays the My List, Color, and Your Name controls.

The following example illustrates how you can detect when a user clicks CANCEL in the GetNumber dialog box.

When a user clicks CANCEL in a GetNumber dialog box, Origin generates a #Command Error! which will stop your script.  If you need to continue processing and want to know which button in the dialog box was clicked, you can make use of the following general technique.

Use Notepad or another text editor to create a file called UTIL.OGS.  Type the following text in your text editor and save the file.

// Beginning of sample code

[getnumber]

flag=0;

var=%2;

getnumber (%1) var (%3);

flag=1;

return;

// End of sample code

Note that a variable named flag is set to 0 before the GetNumber command and set to 1 after the GetNumber command.  When this code is called via a run.section command, the two lines after the GetNumber command will execute only if the user clicks OK.  Since this code is executing in an external file, the #Command Error! that is generated by clicking CANCEL stops the external script from completing, but allows the script that called it to continue.  Your calling script can then check the value of the flag variable to determine what action the user took:

     flag = 1 indicates the user clicked OK

     flag = 0 indicates the user clicked CANCEL

Here is an example of how to call and use this routine:

sample = 10;

run.section(util,getnumber,"My Variable" sample "Enter your value");

if (flag==1)

{

   sample = var;

   type -a "You clicked OK or Enter and the value of sample is now $(sample)";

} else {

   type -a "You clicked Cancel. Value of sample will not be changed.";

}

This same technique can be applied with other 'GET...' dialog boxes also.


GetPts

Syntax:	getpts [options] npts [(message)]

This command uses a Tools toolbar tool to get dataset values of the active dataset from the current graph window.  The option determines which tool is used.  Variables are stored in properties of the getpts object.  Once a tool is selected, the PointProc macro is executed when the user double-clicks or presses ENTER.  When npts is reached, the EndToolbox macro is executed.  If another Tools toolbar tool is selected before npts is reached, the QuitToolbox macro is executed.

The message help text appears in the status bar.  Message is not sent to the substitution processor for string substitution until PointProc is executed.  This means that your message text can contain real-time information.  (To display a message with more than one word, surround the message words with parentheses.)

Note:  In addition to entering literal text for message, you may specify $[OMGfileName].Section.Title.  This enables you to access a string title in a message file.  The OMGfileName extension is assumed to be OMG.  If OMGfileName is not specified, the ORIGIN.OMG file is assumed.  For an example using this syntax, see the Type command.

Options:

no option

Use the Data Reader tool to get npts from the dataset the user clicks on.  Values are read into the following getpts object properties:

getpts.data$	Dataset name.

getpts.xdata	Dataset that holds each successive X position value.

getpts.indexdata	Dataset that holds the index value of each successive data point that is double-clicked.

-a npts [message]

Use the Screen Reader tool to get the XY coordinate value of points in a graph window.  Values are read into the getpts object properties.

-n dataset npts [message]

Plot each point up to and including npts, and put each successive XY value into dataset.  Dataset must already exist before you can use this option.

-x npts [message]

Same as -y, but restricts the cursor to horizontal-only movement.

-y npts [message]

Use the Screen Reader tool to get the XY coordinate value of points in a graph window.  Restricts the cursor to vertical-only movement.  Values are read into the getpts object properties.

Examples:

The following script is associated with the Pick1Pt macro.  It selects the Data Reader tool and displays the indicated help message.

GetPts 1 (Move cursor to any data point and press RETURN);


GetSaveName

Syntax:	getsavename [fileName] *.extension

Opens the Save As dialog box.  If fileName is specified, it is the default file name in the Save As dialog box.  Extension is the default file extension.  Although extension must be specified, * can be used to leave the choice open.

If you enter a file name and click on the OK button, the file name and the selected path are saved into the string variable %A.  If you click on the Cancel button, %A is unchanged.

Examples:

The following script opens the Save As dialog box and displays *.* in the File Name text box.

Getsave *.*;

The next script opens the Save As dialog box and displays the name of the active window .OGG in the File Name text box.

Getsave %H.ogg;


GetString

Syntax:	getstring (message) initialValue [(dialogTitle)]

Opens a dialog box in which the user can enter a text string.  Message is the dialog box message, initialValue is the initial text string value, and dialogTitle appears in the dialog box title bar.  The user-entered string is put into the string variable %B.

Note:  In addition to entering literal text for message, you may specify $[OMGfileName].Section.Title.  This enables you to access a string title in a message file.  The OMGfileName extension is assumed to be OMG.  If OMGfileName is not specified, the ORIGIN.OMG file is assumed.  For an example using this syntax, see the Type command.

Examples:

The following script creates a dialog box with a single text box.

getstring (Please enter your name below) (Your Name) Hello;


GetYesNo

Syntax:	getyesno (message) variable [(dialogTitle)]

Opens a dialog box (whose title is dialogTitle) that displays Yes, No, and Cancel buttons and the text string message.  Variable becomes 1 if the user clicks on the Yes button and 0 if the user clicks on the No button.  Variable remains unchanged if the user clicks on the Cancel button.  Additionally, a Command Error! prints in the Script window after clicking on the Cancel button.

Note:  In addition to entering literal text for message, you may specify $[OMGfileName].Section.Title.  This enables you to access a string title in a message file.  The OMGfileName extension is assumed to be OMG.  If OMGfileName is not specified, the ORIGIN.OMG file is assumed.  For an example using this syntax, see the Type command.

Examples:

The following script opens a dialog box that displays the message "Do you want to quit?" with associated Yes, No, and Cancel buttons.

getyesno (Do you want to quit?) MyVar (Stop Requested);


If

Syntax:	if (testCondition) sentence1; [else sentence2;]

if (testCondition) {script1} [else {script2}]

Evaluate testCondition and if true, execute script1.  Expressions without conditional operators are considered true if the result of the expression is non-zero.

If the optional else is present and testCondition is false (zero), then execute script2.  There should be a space after the else.  Strings should be quoted and string comparisons are not case sensitive.

Single statement script arguments should end with a semicolon.  Multiple statement script arguments must be surrounded by braces {}.  Each statement within the braces should end with a semicolon.  It is not necessary to follow the final brace of a script with a semicolon.

Examples:

The following script opens a message box displaying "Yes!".

%M=test;

if (%M=="TEST")  type -b "Yes!";

The next script finds the first point in data1_a that is greater than 100.

ii=1;

// get -e finds the # of points in the Data1_A dataset and places it

// in the numPoints variable

get Data1_A -e numPoints;

// repeat as many times as there are points

repeat $(numPoints)

{

if (data1_a[ii] > 100)  break;

else  ii++; // this semicolon ends the if-else statement

};

if (ii!=$(numPoints+1))

{

type -b "The index number of first value >100 is $(ii)";

type "first value > 100 is $(data1_a[ii])" ;

}


Integrate

Syntax:	integrate [-r basedataset] dataset [range]

This command integrates dataset using the trapezoidal rule.  (For information on the trapezoidal rule, see "Numerical Recipes in C" by Press et al. Cambridge University Press, NY, 1985)

The integration results are placed into the following integ object properties:

integ.area:  Area of the integration.

integ.y0:  Maximum height (measured from the baseline if present, otherwise measured from zero).

integ.x0:  X value of y0.

integ.dx:  Half width of the peak.

integ.x1:  Beginning X.

integ.x2:  Ending X.

A dataset named _integ_area is created to hold the integrated area data.  The leading underscore indicates that this is a temporary dataset that is deleted when printing or saving.  If you need to keep this data, copy it into another dataset that does not include the leading underscore.

Note:  The integ object properties are read in the same way as numeric variables.  For example:

integ.x0=  (ENTER)

returns:

INTEG.x0=120;

Options:

no options dataset [range]

Integrate dataset from zero as described above.

-a dataset [range]

Perform the integration without creating the _integ_area dataset.

-q dataset [range]

Integrate dataset from 0 but do not display the temporary shading of the integration area.

-r basedataset dataset [range]

Integrate from the given baseline dataset.  The Y values are calculated by interpolating the baseline.  If the baseline is a spline, the spline interpolation values are used.  Otherwise, the interpolation is linear.

Examples:

The following script integrates the Data2_D dataset from row index 4 to row index 8.

integrate Data2_D -b 4 -e 8;

The next script integrates the Data2_D dataset using Data2_B as a baseline to subtract.

integ -r Data2_B Data2_D;


Label

Syntax:	label [options] message

Places a text label on the page.  By adding one or more option switches you can modify the manner in which the label is created.  The message to be displayed by the label is always the final argument.  The label command allows multiple option switches.  When -xb, -yl, -xt, -yr, -zf, or -zb are used, they must be the final option (immediately preceding the label message).  Also, when -n is used, it must be the final option (immediately preceding the label message).  Options can be combined only when it makes sense to do so and when they do not conflict with each other.

Options:

no option message

Place an unnamed text label message in the default location on the page in the active window.

-a x y message

Place the label at coordinates xy, where x and y are actual Cartesian coordinate values.

-b n

Set the text label border style to the nth style in the Show Background drop down list of the Text Control dialog box.

-d x y message

Place the label at coordinates xy, as measured in screen pixels from the top left corner of the page.

-e message

Open the Text Control dialog box with message in the text box.  Click on the OK button to create a text label with the message.

-f fontName message

Change the label font type to fontName.  FontName can be abbreviated as long as the name remains unique.  For multi-word font names, you must include quotations around fontName.

-j n message

Justify the label message text.  n can be 0, 1, or 2 for left, center, or right. Justification options are preset for axis titles and cannot be altered.

-n labelName message

Create a new, or replace the existing, message of the named label.  LabelName specifies the name of the label, which appears in the Label Control dialog box.

-o dx dy message

Set the offset amount (in percent) for the label.  This option is only applicable for labels in which 'Layer and Scales' is selected in the Attach To group of the label's Label Control dialog box.

-p x y message

Place the label at coordinates xy, where x and y represent the percent distance from the top left corner of the layer frame.

-q n message

Place the label into one of the four active layer quadrants n.  The quadrants are numbered from 1 to 4, counterclockwise from the top right.

-r labelName

Delete (remove) the label named labelName.  If labelName is not specified, delete all labels on the page.  You need not supply a message argument to delete labels.  Note that issuing this command does not automatically update the screen display.

-s message

Enable the use of substitution notation (% and $) in the argument string.  By default, the label command does not substitute the % and $ notation.  This option allows you to insert numeric and string variables into the label message.

-sa message

Enable conversion of \r\n\t type of notation.  Use this option to create multiple line text labels (\r\n) without adding new lines to the script.  To also enable substitution, use -s -sa together.

-t message

Create a label with message and name the object TITLE.

-xb message

Create a new, or replace the existing, bottom X axis title.

-xt message

Create a new, or replace the existing, top X axis title.

-yl message

Create a new, or replace the existing, left Y axis title.

-yr message

Create a new, or replace the existing, right Y axis title.

-zb message

Create a new, or replace the existing, back Z axis title.

-zf message

Create a new, or replace the existing, front Z axis title.

Special Formatting Using Escape Sequences:

You can use escape sequences in a string to customize the text display.  These sequences begin with the backslash character (\).  All text objects (those created with the label command or with the Text tool) as well as text plotted from a Label column will display according to the rules of these sequences.

\+(text)

Format text as superscript.

\-(text)

Format text as subscript.

\=(text1,text2)

Format text1 as subscript, text2 as superscript.

\p%pointsize(text)

Change the point size of text.  200 doubles the size, 100 results in no change, etc.

\i(text)

Format text as italics.

\b(text)

Format text as bold.

\g(text)

Format text using the Symbol font.

\ab(text)

Display a bar above text.

\(ASCII character code)

Displays the specified ASCII symbol.

\f:fontname(text)

Displays text using the fontname font.  You can abbreviate fontname, as long as you use enough letters for the name to be unique.

\cnumber(text)

Displays text in the color located at position number in the Color drop-down lists.

For a list of the escape sequences for non-printable characters, see the Type command.

Examples:

The following script creates a label that reads New Label Text which is center justified and named MYLABEL.  It draws the label in quadrant 3 of the active layer of the active window.

label -q 3 -j 2 -n MYLABEL New Label Text;

The next script creates a bottom X axis label Maximum Current.

lab -xb (Maximum Current);

The next script updates the content of the label named myLabel with run time values.  Note that you could also set up the label with the same text with the 'Link to Variables' option enabled in the Label Control dialog box.

%A="position=$(x)";

label -s -n myLabel %A;


Command Reference - Alphabetical Listing of Commands - Layer
Layer

Syntax:	layer [option] <width  height  xOffset  yOffset>

Performs various operations on existing layers.  The layer command operates on the active layer, except where specified.

Options:

no option 	[width  height  xOffset  yOffset]

Width, height, xOffset, and yOffset specify layer width, height, and horizontal and vertical position on the page (measured in the current units, from the top left corner of the page to the top left corner of the layer), respectively.  A zero value for width or height retains their current settings.

A single zero argument (layer 0) fits the active layer to the page.  If no arguments are issued, the Select Columns for Plotting dialog box opens.

-3d m value

Perform the following options on a 3D graph for values of value:  P+1=increase the perspective angle plus three units, P-1=decrease the perspective angle minus three units, Rotation=reset the axis to their original rotational location, and Frame=fit the graph to the layer frame.  If value equals P+1, P-1, Rotation, or Frame, execute doc -uw to update the graph.

-3d r %A x

Set the 3D graph rotation.  %A is either the X, Y, or Z axis to be rotated.  X is the number of degrees +/- to rotate the graph.  After executing this command, execute doc -uw to update the graph.

-a

Rescale the X and Y axes of the active layer to show all the data plotted in that layer.  The range of the X axis includes the rescale margin and begins and ends on the nearest major or minor tick.  To rescale only the X or Y axis, set the other axis as fixed (for example, using layer.axis.rescale=1).  You can then save the graph window as a template.

-at

Rescale the X and Y axes of the active layer to show all the data plotted in that layer, but ignore tick settings.  The range of the X axis will be the data range plus the rescale margin.

-az

Rescale a 3D plot but do not rescale the Z axis.

-b parameter value

Flag the given parameter as on or off for the active layer or toggle its state.  Value must be 1=on, 0=off, or -1=toggle.  The possible parameters are:  x=exchange X and Y axes, s=stack data plots, a=draw the axes after (on top of) the data, g=draw grid lines after (on top of) the data, c=clip data, and f=show the frame.

-b 3DB value

Set graph display caching to none, raster, or vector.  Value=0 for no caching.  Value=1 for raster caching.  Value=2 for vector caching.

-b R value

Set worksheet as read-only.  Value=0 for editing worksheet.  Value=1 for read-only worksheet.

-c

Count how many datasets are plotted in the active layer.  Put the result into the count variable, and concatenate the names of all datasets into %Z.

-d

Delete the active layer.

-e dataset

Remove dataset from the active layer.

-g

Group all datasets in the active layer.

-gu

Ungroup all datasets in the active layer.

-h value

If value=1, hide the layer.  If value=0, show the layer.  This command does not automatically refresh the window display.

-i

Delete all data plot style holders in the active graph window layer.  Resave the graph window as a template to update the template settings.

-i dataset

Include dataset in the active layer, that is, add dataset to the Layer Contents list in the Layer n dialog box.  This is the standard method for plotting a dataset.  If dataset is omitted, this command removes all the data plot style templates within the layer.

-i# dataset

Replot into the graph type specified by #.  Note that there is no space between the i and #.  See the worksheet command for a listing of graph type numbers.  If dataset is omitted, this command removes all the data plot style templates within the layer.

-ie

Delete all data plot style holders that are not in use in the active graph window layer.  Resave the graph window as a template to update the template settings.

To find out which style holders are in use, use list o;.  This command returns three attributes of the objects (including data plot style holders) in the active graph window layer:  index   type*   name

Type=7 indicates a data plot style holder.  The asterisk indicates the style holder is in use.

-iu

Delete all data plot style holders that are in use in the active graph window layer.  Resave the graph window as a template to update the template settings.  See the -ie option for more information.

-j

Convert a single layer graph with multiple data plots into a multiple layer graph in which each data plot displays in its own layer.

-k value

If value=p, open the Plot Details dialog box for the active layer.  If value=c, open the Layer n dialog box for the active layer.  If value=d, open the Link Axes Scales tab of the Plot Details dialog box for the active layer.  (Note:  The active layer must be a linked layer to open this dialog box.)

-m

Open the Layer Clipping Margins dialog box for the active layer.

-n

Add a nonlinked layer to the active graph window displaying a bottom X and left Y axis.

-n Both

Add a linked layer to the active graph window displaying a top X and right Y axis.

-n X

Add a linked layer to the active graph window displaying a top X axis.

-n Y

Add a linked layer to the active graph window displaying a right Y axis.

-o layerNumber {script}

Execute (operate) the specified script for the specified layer.  The layerNumber layer is temporarily set internally as the active layer, the script is executed, then the original active layer is restored.

-p axisScale

Apply the X or Y scale of the active layer to all other layers in the active window.  Set axisScale to X to apply the X scale, or to Y to apply the Y scale.

-r

Reverse the order of the data plots in the active layer.

-s

Update Origin when you change sheet activity in an Excel workbook.  Execute after changing the active sheet, or after adding a new sheet to the workbook.

-s n

Select the active layer in the active window.  n specifies the layer number.

You can also set (and get) the active layer number using the page.active object property.

-t

Clear the effect of the -t nrow option.

-t nrow

Set the worksheet row that provides the axis title and the legend text for the data plot.  The X cell value provides the X axis title.  The Y cell value provides the legend text.

-u unit#

Change the units in which layer size and position are measured.  Unit# specifies the type of units in the order listed on the Size/Speed tab of the layer's Plot Details dialog box.  1=% of page, 2=inch, 3=centimeters, etc.

-w wks [c1 r1 c2 r2][GraphType]

When no range is specified, plot the entire worksheet wks into the active layer.  To select a worksheet range, specify the beginning and ending column and row numbers.

If c1 and c2=0, plot all columns.  If r1 and r2=0, plot all rows.  The graphType value determines graph type:  line, symbol, scatter, etc.  If a "?" is used, the graph type saved with the layer is used.  See the graph type listing under the worksheet command.

-x

Get the layer frame dimensions into variables v1 (left), v2 (top), v3 (width), and v4 (height).  The values are in the current unit for the layer.  To set the layer frame size, use the layer command without an option switch.

-y ?

Query the waterfall graph in the active graph window and assign the values of the X offset and Y offset to variables X and Y.  The X and Y offset amount is expressed as a percentage.

-y !

Disable the X and Y offsets in the waterfall graph in the active graph window.

-y x, y

Set the X and Y offset to produce a waterfall effect for all the data plotted in the layer.  The x and y offset amount is expressed as a percentage (you must include the comma between the x and y offset).

Note:  To assign these offset values to variables X and Y, execute the layer -y ? command after setting the offsets.

Examples:

The following script changes the units to pixels.

lay -u 5;

The next script exchanges the X and Y axes.

lay -b x 1;

The next script sets xOffset and yOffset to 45.  It retains the current values for width and height.

lay 0 0 45 45;

Given three layers, the following script sizes each layer to 20% of the page width and 80% of the page height.  It arranges the layers 10% from the top of the page, starting at 8% in from the left, and separated by 12% of the full page.

width=20;

height=80;

for (ii=1;ii<=3;ii++) {

layer -s ii;

layer width height (8+(ii-1)*(width+12)) 10;

};


Legend

Syntax:	legend

Creates a legend for the active graph window or updates the current legend if one exists.  This command takes no options and no arguments.


Command Reference - Alphabetical Listing of Commands - Limit
Limit

Syntax:	limit [option] dataset [range]

Options:

no option

Finds seven limiting values for dataset.  Each value is placed into limit object properties.  Use the limit command before checking the property values.  The limit object properties are set and read in the same way as numeric variables.  For example:

limit.xmax=

returns:  LIMIT.XMAX=120;

The limit object properties are as follows:

limit.size:  Total size (number of points) for dataset.  If range is included, then this property contains the size of the range.

limit.ymin:  Minimum Y value.

limit.imin:  Corresponding index for minimum Y value.

limit.ymax:  Maximum Y value.

limit.imax:  Corresponding index for maximum Y value.

limit.xmin:  Minimum X value.

limit.xmax:  Maximum X value.

-r beg end num inc

From the provided beginning beg, end, and number of points num values, calculate the appropriate inc value and adjust beg and end.  This is the same mechanism used in automatic increment calculation and rescaling.

Examples:

The following script finds the limits for data1_b from index number 10 to index number 30, inclusive.  The properties contain information for this range only.

limit data1_b -b 10 -e 30;

The next script calculates a step value of 2 and sets start to -3 and stop to 16.

start=-2.786;stop=15.901;ticks=9;step=0;

limit -r start stop ticks step;

The last script returns the greatest value in the Data1_C dataset to the Script window.

limit Data1_C;

limit.ymax=;


List

Syntax:	list argument

Lists various objects in the current project by typing the names of the objects to the Script window.  The list depends on the argument supplied.  You need only supply the first letter of the argument, without a "-".

Note that there is also a list( ) function which finds the index number of a specified value in a dataset.

Arguments:

macro

List all macros.

object

List all objects and labels in the current layer.

This command returns three attributes of the objects in the active graph window layer:  index   type*   name

Type=7 indicates the object is a data plot style holder.  The asterisk indicates the style holder is in use.

series

List all datasets (series).

variable

List all variables.

Examples:

The following script returns the names of all existing datasets to the Script window.

list s;


Loop

Syntax:	loop (variable, start, end) sentence;

loop (variable, start, end) {script}

A simple increment loop structure.  Initializes variable with a value of start.  Executes the script.  Increments variable and tests if it is greater than end.  If it is not, execute script and continue to loop.  This is the equivalent of one of the most common for loops:

for (Variable=Start; Variable<End; Variable=Variable+1) {script}

Single statement script arguments end with a semicolon.  Multiple statement script arguments should be enclosed in braces {}.  Each statement within the multiple statement script should end with a semicolon.

Note:  If your script loops endlessly, you can interrupt the script by pressing ESC.

Examples:

The following script:

loop (num, 1, 4)  {type "$(num)";};

Produces the following output to the Script window.

1

2

3

4

The next script prints the values of row index 20-35 in column 2 of the NewData worksheet in the form "Row 20 value is 547".

loop (num, 20, 35)

{

data = %(NewData, 2, $(num));

type "Row $(num) value is $(data)";

}

To find the number of the last row in the worksheet, use: $(NewData!wks.nrows);


Command Reference - Alphabetical Listing of Commands - LR
LR

Syntax:	lr [option] dataset [range]

This command performs a linear regression on dataset and its dependent X dataset.  If the data is plotted in an active graph window, lr adds the data plot of the fitted curve to the graph window.  If the Data Selector tool was used to set the range, then the fit is performed over the selected range and the resulting curve displayed for the full range.

LR Object Properties:

The fitting results are stored in lr object properties.  To read the value of these properties, use the following syntax:

lr.property=

The value of the property is returned in the Script window.

The properties return a null value until the lr command has been executed.  The lr object has the following properties:

lr.b:  Slope.

lr.a:  Intercept.

lr.sdB:  Standard deviation of slope.

lr.sdA:  Standard deviation of intercept.

lr.sd:  Standard deviation of the fit.

lr.r:  Correlation coefficient.

lr.n:  Number of points used in the fitting.

lr.chkLinearr:  Sets the amount of tolerance in the automatic determination of linear segments from the data.  (See the -b and -e options.)

lr.maxLRange:  Specifies the percentage of the entire data range to be examined by the find linear segment routine.  (See the -b and -e options.)

Options:

no option

Performs a linear regression on dataset.

-b dataset

-e dataset

Perform a linear regression on the beginning or ending linear region of dataset.

Note:  When you use the lr -b dataset or lr -e dataset commands to perform a linear regression on the beginning (b) or ending (e) linear region of dataset, the dataset is automatically searched for linearity, as determined by the following parameters that can be modified in the ORGSYS.CNF file:

lr.maxLRange:  The percentage of the entire data range to perform a linear regression on.  For example, when lr.maxLRange=40 (default) and dataset has 20 points, lr -b dataset performs a linear regression on the first 8 points in dataset, if these points meet the requirements of the lr.chkLinearR parameter.  Thus, if the fourth point is outside the tolerance set by lr.chkLinearR, then the lr -b dataset command would only perform a linear regression on the first three points in dataset.

lr.chkLinearR:  Sets the amount of tolerance in the automatic determination of linear segments.

-n dataset [range]

Perform a linear regression on dataset but do not create a data plot of the fit line.

-s dataset [range]

Use the axis scale function to transform the data before performing the linear regression.  This allows you to do an apparent linear fit on data that is plotted against a nonlinear scale, for example, a Log 10 scale.

-x xdataset dataset [range]

Perform a linear regression on dataset, using the dataset xdataset to supply the X values (independent variables).

Examples:

The following script performs a linear fit of dataset Data1_B beginning at the first data point and continuing until the end of the linear region.  It types the resulting slope and intercept to the Script window.

lr Data1_B;

type "Slope is $(lr.b)";

type "Intercept is $(lr.a)";


Mark

Syntax:	mark option dataset [range]

Options:

-d dataset [range]

Delete elements from dataset.  If dataset is in a worksheet, this command deletes the specified rows from the worksheet.

-m dataset [range]

Turn the dataset elements (cells) into missing values.

-st dataset -b firstPoint -e endPoint

After a range of data has been masked in the graph using set -w1, toggle the mask off and on for a range of dataset.  For example:  mark -st %C -b 1 -e 10;.

-sw dataset

Swap masked and unmasked points in dataset.  For example:  mark -sw %C;.

-u

Update all graphs with masked data.  Use this command after changing one of the global mask properties with the following system variables:

@MC:  Mask color.  Follows the colors in the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

@MM:  Enable or disable mask.  0=enable (masked points are not included in analysis).  1=disable (masked points are included in analysis).

@MP	:  Show or hide masked data points in graph.  0=show.  1=hide.

-wd

Remove the mask from a selected range either in the worksheet or graph.

-w1

Mask a selected range either in the worksheet or graph.  Masked data is excluded from analysis.

Note:  To determine if a data point in a data plot is masked, use the following notation:

datasetName<dataPointIndex>=

A return value of 0 indicates the point is not masked.  1 indicates the point is masked.

For example, to determine if the fourth data point in the data1_b data plot is masked, use:

ii=data1_b<4>;

ii=;

-x dataset [range]

If dataset is not associated with corresponding X values, this option creates an associated X dataset called dataset_X, which contains whatever X values are associated with the current worksheet.

Examples:

The following script deletes row index 10 to row index 20 from the Data1 worksheet if Data1_B is a column in the Data1 worksheet.  If the worksheet does not exist, only Data1_B's elements are deleted.

mark -d Data1_B -b 10 -e 20;


Math

Syntax:	math [option] dataset1 dataset2

Options:

no option	dataset1 dataset2 [dataset3]

Open the 'Math on/between Dataset' dialog box, with dataset1 selected as the Y1 dataset and dataset2 selected as the Y dataset.  If dataset3 is specified, it is selected as Y2.  Otherwise, the Y2 dataset is blank.

-o operator [dataset1 dataset2 dataset3]

Select an operator to display in the 'operator' text box of the 'Math on/between Dataset' dialog box.  The possible operators are:  +, -, *, /, and ^.  Dataset1 is selected as the Y1 dataset and dataset2 is selected as the Y dataset.  If dataset3 is specified, it is selected as Y2.  Otherwise, the Y2 dataset is blank.


Matrix

Syntax:	matrix option arguments

Get values from, or set values for, a matrix window.

Options:

-e

Open the Set Matrix Values dialog box.

-e d

Open the Matrix Properties dialog box.

-e m

Open the Matrix Dimensions dialog box.

-pg parameter varName1 varName2

Get the specified parameter, as described for the -ps option.

-ps parameter value1 value2

Set parameter to the specified range of values.  Possible values for parameter, value1, and value2 are shown below.  Only the first parameter letter is required.

Parameter:  DIM

Value1 Value2:  nCol nRow

Description:  Sets the matrix column by row size.

Parameter:  X

Value1 Value2:  xMin xMax

Description:  Sets the matrix X mapping range.

Parameter:  Y

Value1 Value2:  yMin yMax

Description:  Sets the matrix Y mapping range.

-t

Transpose the active matrix.

-v expression

Fill the matrix with values from the expression.  The current XY mapping relation is used.  You can use X and Y in the expression, as well as i and j (the row and column number value for any particular cell).

Examples:

The following script puts the X minimum and X maximum values into xmin and xmax.

matrix -pg X xmin xmax;

The next script fills the matrix with the given expression.

matrix -v sin(x)+cos(y);


Command Reference - Alphabetical Listing of Commands - Menu
Menu

Syntax:	menu [option] <argumentList [{script}]>

Add, remove, and edit menus, submenus, and menu commands.  For more information on menu manipulation, see the menu object.

The effects of the menu command may not be immediately apparent.  Make a different window type active and then return to the original window to view the result.

Select the Active Menu Bar:

The first step when using the menu command (or menu object) is to select the active menu bar - either the graph, worksheet, layout page, or matrix window menu bar.  To select the active menu bar, use the -g, -w, -p, or -m command options (see the "Options" section).

Note:  The window designations can be combined, so that:

menu -gp;

makes all subsequent menu modifications apply both to the graph and the layout page windows.

Select the Active Menu:

Next, select the active menu (for example, the Edit menu).  All subsequent commands operate on the active menu.   To select the active menu, perform one of the following:

Reference the current position in the menu bar (see the "When No Option is Given" section).

Use tags.  For example:

menu ?Ed;  	//makes the Edit menu active.

Only built-in menus can be referenced this way (for the user-defined menus, reference the position).  Tags must have two characters.  The following tags are used:

Menu:  Tag

File:  "Fi"

Layout:  "La"

Edit:  "Ed"

Matrix:  "Ma"

View:  "Vi"

Window:  "Wi"

Plot:  "Pl"

Tools:  "To"

Data:  "Da"

Column:  "Co"

Analysis:  "An"

Help:  "He"

Format:  "Fo"

Finding a Menu Command ID:

To find a menu command ID, perform one of the following:

Press CTRL+SHIFT and select the menu command.  The menu ID (and script) is typed to the Script window, but not executed.

Use the menu.lastID or the menu.lastExeID object properties.

The (LabTalk) Menu Command, When No Option is Given:

When no option is given, the menu command has four possible actions:

If argumentList consists of only a number, the menu in the numbered location is set as the active menu.  You must set a menu as active before it can be edited.  Menus are numbered sequentially, where 1=File, 2=Edit, etc.  A submenu can also be selected, such that 1.1 is the submenu from the first menu command of the File menu.

Example 1a:    menu 2;

Sets as active the menu at position number 2 in the active menu bar.

Example 1b:    menu 1.1;

Sets as active the submenu at position 1 of menu 1 in the active menu bar.

If argumentList is a number followed by a name, the named menu is created and inserted into the given position in the active menu bar, and set as the active menu.

When you add a new menu, Origin assigns an ID number, and stores the ID in the variable i.  The ID can be assigned to another variable for later use.  To find the value of i, type the following in the Script window:  i=(ENTER)

Example 2:    menu 2 (My Menu);

Inserts My Menu into position 2 in the active menu bar.  The "( )" ensure that My Menu is treated as a single word.

If argumentList does not start with a number, then it is taken to be the name of a new menu command, which is appended to the active menu (in the active menu bar).  The new menu command executes the script script.

Example 3:    menu (Add Text) {label -e NewText;}

Adds a new text label to the active window.

If no argumentList is given, a menu command separator is appended to the active menu (in the active menu bar).

Example 4:    menu 6; menu;

Appends a menu command separator to menu 6.

Options:

-d position

Delete the menu command at position position in the active menu (in the active menu bar).

-e ID

Execute the menu command with the specified ID by running its script immediately.  To find the ID of an existing menu command, open the Script window and then press CTRL+SHIFT and select the menu command.  The script and menu ID for the menu command are printed to the Script window (but the script does not execute).

-g

Select the graph window menu bar for menu manipulation.

-i position menuName {script}

Insert into the active menu at position position, a new menu command called menuName.  MenuName is associated with the script script.

-i position menuName ID

Insert into the active menu at position position, a new menu command called menuName with the menu ID ID.  This command option is used to create a menu command with a specific ID to link to a tool.

-l [-i position] (menuName) {script} ]

Construct a submenu at the end of the active menu.  The menu -l command must be issued twice, first to name and initialize the submenu, and the second time to construct the submenu that has been described.

This protocol is shown below:

menu -l (New Submenu);	// begin submenu

menu (submenu 1) {type "this is submenu 1"};

menu (submenu 2) {type "sub menu 2"};

menu -l;	 // terminate submenu

This script creates a submenu named New Submenu.  This submenu contains two menu commands.

Submenus can also be constructed at specific positions in the active menu if the -i position option is added between -l and menuName.

-m

Select the matrix window menu bar for menu manipulation.

-p

Select the layout page window menu bar for menu manipulation.

-q ID

Execute the menu command with the specified ID by queuing its script.  To find the ID of an existing menu command, press CTRL+SHIFT and select the menu command.  The menu ID and script of the menu command are printed to the Script window (but not executed).

-r position

Remove the entire menu located at position position.

-w

Select the worksheet menu bar for menu manipulation.

Examples:  Adding Menus and Submenus (without the -l option)

The following script inserts and makes active a NewDD menu at the third position in the active menu bar.

menu 3 (NewDD);

The next script inserts and makes active a Before Edit menu before the Edit menu in the active menu bar.

menu ?Ed (Before Edit);

The next script inserts a SubMenu submenu at the second position in the fourth menu and makes it active.

menu 4.2 (SubMenu);

Examples:  Adding Menus and Submenus (with the -l option)

The following script inserts a BeforeOpen submenu before the Open menu command in the active menu.  It then adds a menu command to the BeforeOpen submenu.

menu ?Fi; 	// Makes the File menu active.

menu -l -i 2 (BeforeOpen);	// Inserts a submenu.

menu (MyFiles) {type -b "MyFiles";};  // Append the menu

// command labeled MyFiles in the active (which is now the

// BeforeOpen) submenu.

menu -l;  	// Restore the previous active submenu.

Examples:  Removing Menus

The following script removes the fourth menu from the active menu bar.

menu -r 4;

The next script removes the Format menu from the active menu bar.

menu -r ?Fo;

Examples:  Making Menus and Submenus Active

The following script sets the graph window menu bar active.  It then makes the fourth menu from the left active.

menu -g;

menu 4;

The next script makes the View menu active (in the active menu bar).

menu ?Vi;

The next script makes the submenu at the first position in the File menu active.  This command fails if there is no submenu at the first position in the File menu.

menu ?Fi.1;

Examples:  Adding Menu Commands

Menu commands can only be added to the active menu.  Therefore, make the desired menu active before adding menu commands.

The following script appends the menu command labeled EndEdit to the Edit menu (in the active menu bar).

menu ?Ed;  // Makes Edit active

menu (EndEdit) {type -b "EndEdit";};

The next script inserts the menu command labeled BeforePaste before the Paste menu command in the active menu (in the active menu bar).

menu -i 4 (BeforePaste) {type -b "!!!";};

The next script inserts the MyItem menu command at the (currently) fifth position in the active menu (of the active menu bar).

menu -i 5 (MyItem) {type -b "My item text.";};

The following script inserts the Open Template menu command in the second position of the Graph menu in the graph menu bar.

menu -g;	//set the graph menu bar as active

menu 4;	//makes Graph active

menu -i 2 (Open Template) {win -t plot line;};

//Insert menu command in second position that will open

//the line template

To set the ID you must execute the new menu command by selecting it from the menu bar.  Then type in the Script window:

MyID = i  (ENTER)

You can later execute the menu command by using:

menu -e myId;

Examples:  Removing Menu Commands

The following script sets the graph window menu bar active.  It then sets the sixth menu from the left in the graph window menu bar active, and deletes the second menu command in this menu.

menu -g;

menu 6;

menu -d 2;

Examples:  Adding Menu Command Separators

The following script inserts a menu command separator in the third position in the active menu (of the active menu bar).

menu -i 3;

The next script adds a menu command separator to the end of the active menu (in the active menu bar).

menu;


Command Reference - Alphabetical Listing of Commands - NLSF
NLSF

Syntax:	nlsf [option] dataset

The nlsf object methods and properties provide greater control over curve fitting.  We recommend using the nlsf object instead of the nlsf command.

This command controls a number of functions associated with nonlinear least squares curve fitting and the fitting session.

Options:

no option dataset

Assign a dataset to the fitter and open the Fitting Session dialog box.

- #

Iterate the fitting routine # times.

-e

Open the Fitting Session dialog box.

-f funcName

Select the fitting function specified by funcName.  FuncName must be included.  The Fitting Session dialog box doesn't open.

-h dataset

Enter the fitting session and plot a trial fit curve for dataset.  This option does not display the Fitting Session dialog box.  The option will not work unless you first select a fitting function.

-r

Direct the fitting routine to display the fitting residues in layer 2 of the active window.  Layer 1 is assumed to contain the raw data and fit curve.  Layer 2 is set to the same X axis scale as layer 1 (as if you had issued the layer -p x command).  The layer 2 Y axis scale is set to +/- 15% of the Y scale range in layer 1.  You can issue this command only after issuing the nlsf dataset command to enter the fitting session.

-t

Terminate the fitting session.

-u

Update the fit curve according to the parameters in the dialog box.

-s dataset

Subtract the active fit curve from dataset.

-v value [init][inc]

Set parameters as fixed or variable during the fitting procedure.  A fixed parameter is held constant during the fitting, while a variable parameter varies.  Set all parameters to value, where 0=variable and 1=fixed.  Or start at parameter number init, and change each inc parameter thereafter.

-y value [init][inc]

Set parameter values.  Sets all parameters to value, unless you specify an initial parameter init, and an increment inc.

System Variables and Object Properties:

Note:  You are strongly recommended not to use the following variables.  Instead, use the nlsf object methods and properties to control curve fitting.

The fitting information is stored in the following system variables.  The equivalent nlsf object oriented properties are also given in parentheses.

FitWtMode	Weighting method used:  0=weight, 1=instrumental, and 2=statistical.  This value is initialized when the fitting session begins.  If there are error bars plotted with the data, the weight is set to instrumental, otherwise it is set to zero.  (nlsf.wtype)

Pn	The value of parameter n.  (nlsf.Pn)

Pen	The standard error of parameter n.  (nlsf.En)

PVn	Tells whether parameter n is fixed or allowed to vary during fitting:  1=vary, 0=fixed.  (You can fix a parameter using linear constraints.)  (nlsf.Vn)

PUn	The upper confidence limit of parameter n.  Use nlsf.paraconf( ) to make it first, otherwise you get zero values.

Pln	The lower confidence limit of parameter n.  Use nlsf.paraconf( ) to make it first, otherwise you get zero values.

Examples:

The following script selects the Guassian fitting function.

nlsf -f gauss;

The next script sets parameter 2 to 100.

P2 = 100;

The next script assigns the value of parameter 3 to the variable ttt.

ttt = P3;

The next script assigns the error value of parameter 7 to the variable sss.

sss = PE7;

The last script fixes parameter 3 so that it is not modified during fitting.

PV3= 0;


Open

Syntax:	open option filename

Open or import a data file.

Options:

-n fileName [winName]

Open the specified fileName text file into the specified (optional) winName notes window.

-p plottingDesignations fileName

Import the FileName file into the active graph window.  Specify the plotting designations for the columns in the import file using the following letters:  X=X values, Y=Y values, Z=Z values, D=disregarded values, E=Y error values, H=X error values, and L=label values.  Origin assumes that the last character in the arrangement is repeated for all remaining columns in the data file.  For example, plottingDesignations=DXY means that the first column is disregarded, the second column contains X values, and all other columns contain Y values.  To specify a "repeat unit" for plottingDesignations, include a number at the end of the entry that denotes the repeat unit.  For example, plottingDesignations=DXY2 specifies that the first column is disregarded, the second column contains X values, the third column contains Y values, and that the XY pattern is repeated for all remaining columns in the data file.

-w filename

Import the given ASCII file into the active window.

-wf filename

Import the given file into the active worksheet by using the appropriate import filter.  The file type is determined automatically.  The type of file can be one of the following:  WKS, WK1, WK3, WKQ, or DIF.

-we ext filename

Import the given file into the active worksheet by using the appropriate import filter.  The type of file is specified by ext, which can be one of the following:  XLS4, XLS3, XLS2, DBF4, DBF3PLUS, DBF3, or DBF2.  In each case, the (file) numbers refer to the version of the software that created the file.

Examples:

The following script opens the Open dialog box to import Lotus or DIF files into the worksheet.

getfile *.WKS *.WK1 *.WK3 *.DIF *.WKQ;

open -wf %B%A;

The last script opens the Open dialog box to import an Excel file.  Since these formats require special ext values in the open command options, the getnum command is used to get the version of the Excel file.

getfile *.XLS;

ver=4;

getnum (Version {2 to 4}) ver (Excel Import);

open -we XLS$(ver) %B%A;


Command Reference - Alphabetical Listing of Commands - Page
Page

Syntax:	page [option]

Perform various operations on the current page.

Options:

no option

Open the Plot Details dialog box with the page tabs active.

-c

Open the Page Color dialog box.

-f

Adjust the page dimensions to fit the current window aspect ratio.

-j

Convert a multiple layer graph into multiple graph windows in which each layer displays in its own graph window.

-l templateName

Read the specified template file and add all of its layers to the page in the active graph window.

-o type

Set the page to portrait (type=p), landscape (type=l), or rotate (type=r) the page.

-pg type varName

-ps type value

These two options set or get page related parameters.  Type can be one of the following:

C	Closing flags:  0=normal, 1=no close, and 2=no warning.

D	Document closing method.  When value=1, set the active window as a system window which remains open when the project is closed.  In addition, this window is not saved with the project.  For related information, see the page.syswin object property.

H	Height of the page in dots.  For a graph window, this value is the number of dots from the top to the bottom of the page.  For a worksheet window, this number is the vertical screen resolution in pixels.

P	Maximum show points:  0=show all data points.

S	Search flags:

bit (n)	value (2^n)	disable search on
0	1	axis
1	2	data plot
2	4	label
3	8	graphical object
4	16	layer frame
5	32	tick labels
W	Width of the page in dots.  For a graph window, this value is the number of dots across the page.  For a worksheet window, this number is the horizontal screen resolution in pixels.

-s object

Select the specified object on the page.  If no object is given, this command clears the current selection.

-sa object

Select the specified object on the page, leaving all current object selections selected.

-t templateName

Replace the page in the active graph window with the template templateName, without closing the active graph window.  All current layers are deleted.  Similar to the document -t and window -t commands (document -t lets you specify a complete path).

-v n

Set the page to the specified view mode:  0=Print view, 1=Page View, 2=Window View, and 3=Draft View.

-vx

Switch between the workbook view and the hidden Origin worksheet layer view for the active Excel workbook in Origin.

-w wksName c1 r1 c2 r2 [ID]

Same as the layer -w command but put each dataset (column) into separate layers in the page.  When the last layer is passed, cycles back to the first layer.  Note:  An active graph window with the correct number of layers must already exist.

Examples:

The following script disables the search on axes and labels for the page.

page -ps search 1;

Note:  You can also use: page.noclick=5;

The next script doubles the maximum display points for the page.

page -pg p npts;page -ps p (npts*2);

Note:  You can also use: page.maxpts *= 2;

The next script adds the layer from the scatter template to the page.

page -l Scatter;

The last script makes graph1 the active window.  It saves graph1 as a system window which remains open when the project is closed.  However, graph1 will not be saved with the project.

win -a graph1;

page -ps d 1;


Plot

Syntax:	plot [option] dataset

Use this command to control window updating of dataset.  To use this command, you must have previously used the layer command to plot dataset into this layer.

Options:

-a wksName nCol c1 c2 c3 ...

Append a row of numbers c1, c2, etc. starting at the given column position nCol (1, 2, 3..) to the specified wksName worksheet.  This command is especially useful in that the data is added to the graph without causing a complete redraw.  Therefore, you can use DDE as a data acquisition tool.  This command activates all the real-time related procedures.

-c

Force an update of the active window (clear screen).

-l

Update the active layer.  If there is a window update message in the queue for this window, remove it.

-n dataset xvalue yvalue

Append a new point to dataset at the XY position specified.

-p

Redraw the page without redrawing any objects off the page.

-s

This command can only be used with active graph windows.  The command draws the page using the full screen.  Terminate this mode by double-clicking.

-v

Remove any update message for the active window.

Examples:

The following script appends the value 2 into column 1 and the value 3 into column 2 in the Data1 worksheet.  If the columns are plotted in a data plot, they are updated accordingly.

plot  -a Data1 1 2 3;


Print

Syntax:	print [option]

Options:

no option

Print the page in the active window.  To print a named window, use the window command:  win -o windowName print;

-a

Open the Print dialog box before printing the page.

-s

Open the Page Setup dialog box.

Examples:

The following script opens the Print dialog box for the active window.

print -a;

The next script prompts a user for multiple projects and prints all the graphs in all the selected projects.

getfile -m *.org;	// opens the multifile dialog

loop (i, 1, count)

{	// number of files is in count

getfile -get I;	// get the ith file into %A

doc -open %A;	// opens the project

doc -e P

{

print;

// pause for 2 min to avoid overloading the print queue

sec -pause 120;

};

};

Note:  To print all graph windows in the current project, use the document command:  doc -e plot  print;


Queue

Syntax:	queue {script}

Delay the execution of the script.  Place the script at the end of the current window message queue.  Execution begins when the current window finishes redrawing.


Repeat

Syntax:	repeat numberTimes {script}

Execute the script the number of times specified by numberTimes, or until an error occurs, or until the break command is executed.

Examples:

The following script creates six graph windows from the TERNARY.OTP template with enumerated titles.

repeat 6 { win -t plot ternary; }


Return

Syntax:	return [value]

Immediately exit from a script or a macro without generating any error.  This command is particularly useful in an object script.  The return value is accessible only from an object script and only integers are supported.

Examples:

The following script defines a macro that takes an argument and types OK if the argument is greater than 2.  Otherwise, it types Not OK.

def test {

if (%1>2) {

type "OK";

return;

}

type "Not OK";

}

In this case, test 1.876; would respond with Not OK.

If an object named Test contains the following script:

if (var1+3*var3>1) return 0;

else return 1;

A script that accesses the object can use the return value as follows:

if (test.run( )==0) type "Result OK";

else type "Result too small";


Command Reference - Alphabetical Listing of Commands - Run
Run

Syntax:	run [option] argument

Execute a script file or run a Windows program.

Note:  The run command executes on a line-by-line basis.  Multi-line structures must include the line continuation character "{" as in the following example:

if (condition) {

// True condition statements

} else {

// False condition statements

}

Note:  The run object provides greater flexibility for script file execution.

Options:

no option scriptfileName

Run the script file scriptfileName.

-e text

Execute the following text as if it were typed into the Program Manager's Run menu (in Windows 95, this dialog box is accessed from the Start/Run buttons).  If the full path specification is included, it is used directly.  Otherwise, Origin assumes the software directory instead of the current directory.

Examples:

The following script opens Notepad and loads a file named README.TXT.

run -e notepad readme.txt;

The next script runs the specified script file.

run c:\c\test\mytest.ogs;


Save

Syntax:	save [option]

Options:

no option

Save the current project.  You can specify the path and the file name after the command.  For example:  save c:\mydir\myfilename;

Note:  This command option should not be used in the Label Control dialog box of an object, as the object will be disabled after closing the current Origin session.

-bs PlotName FileName Width Height [B]

Save the graph window as a bitmap file with the specified dimensions.  If B is included, save as a black-and-white bitmap.

-di fileName

Save the project as fileName.  Additionally, if you are using an Origin dialog box, save the comments from the Save As dialog box into the project.

-di2 fileName

Save the project as version 2.8 together with the comments (if you are using an Origin dialog box).

-i fileName

Save the active worksheet, graph, or matrix window to a file.  Name the file fileName.  Include the extension with the fileName:  OGW for worksheet, OGG for graph, and OGM for matrix windows.  You can include the full path with fileName.  Otherwise, the file is saved to the software directory.

-n winName fileName

Save the winName notes window to a file.  Name the file fileName.  Include the TXT extension with the fileName.  You can include the full path with fileName.  Otherwise, the file is saved to the software directory.

-t windowName fileName

Save windowName into a graph or worksheet template.  FileName must be a full path description.  In general, you should save your template to the Origin directory.

-w wksName fileName

Export the worksheet wksName into an ASCII file.  FileName must be a full path description.

-wh wksName fileName

Same as the -w option except this option uses the wks.export.cntrl object property to determine if headers are exported.  Additionally, this option allows for a specific data range for export, using the wks.export.c1, etc. object properties.

-v fileName

Save all system variables into fileName.

Examples:

The following script exports the worksheet into an ASCII file in the software directory.

save -w data1 %Ydata1.dat;


Second

Syntax:	second [option] [argument]

This command performs timer-related operations.

Options:

no option

Get the current time in seconds from Windows startup or the last time the second -i command was performed.

-e [variable]

Get the elapsed time from the last time the command was issued.  When no variable is given, v1 is used by default.

-i

Reset the timer to zero.

-p sec

Pause for the specified seconds.  The current script is suspended and then continued after the time elapses.  During this period, all other processes continue to execute.

-w sec

Wait for the specified seconds.  Similar to the -p option but does not allow other processes to run.

Examples:

The following script measures script execution time:

def HowLong {

sec;	//get current system time

%1;

//execute script typed as argument to HowLong macro

sec -e time;

//get elapsed time since the sec command

type (Elapsed time = $(time) sec.);

//type time to Script window

}

If you now supply the HowLong macro with a script for an argument, for example:

HowLong {repeat 100 (i+=1)};

then script execution time is measured, and the result is printed to the Script window:  Elapsed time=0.384 sec.


Selection

Syntax:	select [option] value

Object selection management.  This command is used in the Object Edit toolbar.  A selection of one or more objects must exist, otherwise this command fails.

Options:

-a param

Align objects according to the specified param:  t=top, b=bottom, l=left, r=right, c=center horizontally, v=center vertically, w=same width, h=same height, and s=same style.

-c param

Cycle the param colors:  l=line and f=fill.

-f s value

Increase (value) or decrease (-value) the font size of all selected text labels.  For example, if value=4, increase the font size of all selected text labels by a value of four.  Thus, if the original font size was 18, the font size will increase to 22.

-g char

Get the selected object name into the %char string variable.

-h param val

Adjust an arrow head param=angle or param=length.  Val is the amount to adjust the arrow head angle or length.  Positive values increase the angle or length.  Negative values decrease the angle or length.  The default step value used by the Object Edit tool is 5.

-o order

Set object orders.  Possible values for order are:  front, back, data 0 (in front of data plots), and data 1 (behind data plots).  This option determines which objects are drawn on top of others.  For RTM objects, this also determines the processing order for the objects.

-rg

Group the selected objects as one object.

-ru

Ungroup the object.  The selected object must be a grouped object.

-t direction

Snap the orientation of a line or arrow to direction=vertical or direction=horizontal.

Examples:

The following script draws the object(s) in front of the data.

select -o data 0;

The next script aligns the center of the objects in a horizontal line.

select -a center;

The next script gets the selected object's name into %A.

select -g A;

The next script snaps the selected line(s) to a vertical orientation.

select -t v;

The last script decreases the angle of the selected arrowhead by 10 units.

select -h angle -10;


Set

Syntax	set name [option] [value]

Change the attributes of the dataset, data plot, or worksheet specified by name.  If name is a dataset or data plot, only that dataset or data plot is affected.  If name is a worksheet, all datasets on the worksheet are affected.  The option switch determines which attribute is set to value.

Options:

no option

Open the Plot Details dialog box for name.

-a

Set the named dataset to be used for animation.  The data plot automatically removes its own trace when redrawn without generating an update message.

-at value

When name is a dataset and value=1, the dataset is not saved with the project.

-b value

Set the beginning of the display range (value equals first index number).  If name is a worksheet, the display range affects both the worksheet and the data plots of all datasets in the worksheet.  If name is a dataset, only the data plot display range is affected.

-bs value

Temporarily set the beginning of the range of a dataset to the index given by value.  This command is used with datasets to allow functions (such as sum( )) to work on a subset of a dataset.  Its temporary effect switches off with any window refresh.

-c color#

For data plots with symbols or lines, set the line color and the symbol edge color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

To map the symbol edge or line color to a dataset, use set DatasetName -c value, where value =101 + number-of-columns-to-the-right.  For example, to base the symbol edge color on a dataset located two columns to the right of the data plot's Y dataset in the worksheet, use value =103.  (Note:  There is a limit of four columns to the right.)

-cf color#

Fill color (for fill area graphs).  Set the fill color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-cl color#

For data plots with lines, set the line color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.  If the data plot includes lines and symbols, this command will also control the symbol edge color.

-cmn

Set the color for level n in a color mapped data plot following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-cse color#

For data plots with symbols, set the symbol edge color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.  If the data plot includes lines and symbols, this command will break the link (Automatic setting) between the symbol edge color and the line color.

-csf color#

For data plots with symbols, set the symbol fill color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-czn

Set the Z level for level n in a color mapped data plot.

-d style#

Line style, 0=solid, 1=dash, etc. as in the line style list.

-e value

Set the end of the worksheet display range (value equals last index number).  The data outside the end range is not changed, only hidden.  See also -em and -ez.

-em value

Set the end of the worksheet display range (value equals last index number).  When value=0, all data is set to missing value.  When value>0, the data outside the end range is not changed, only hidden.  See also -e and -ez.

-er value

Set the number of rows available on the named worksheet.  This command is used with a worksheet only.

-es value

Temporarily set the end of the range of a dataset to the index given by value.  This command is used with datasets to allow functions (such as sum( )) to work on a subset of a dataset.  Its temporary effect switches off with any window refresh.

-ez value

Set the end of the worksheet display range (value equals last index number).  When value=0, all data is set to zero.  When value>0, the data outside the end range is not changed, only hidden.  See also -e and -em.

-f xvalue

Set the corresponding X value for the first data point.  Use with set -i to create an associated X dataset.

-hbb value

For a histogram, set the lower limit of the binned data.

-hbe value

For a histogram, set the upper limit of the binned data.

-hbs value

For a histogram, set the bin size.

-i xinc

Set the X increment for this dataset.  You cannot use this option if there are already X values associated with this dataset.

-k shape#

For graphs with symbols, set symbol shape:  0=no symbol, 1=square, 2=circle, 3=up triangle, 4=down triangle, 5=diamond, 6=cross (+), 7=cross (x), 8=star (*), 9=bar (-), 10=bar (|), 11=number, 12=LETTER, 13=letter, 14=right arrow, 15=left triangle, 16=right triangle, 17=hexagon, 18=sphere, 19=star, 20=pentagon.  For any numeric values outside of this range (except 56 and 58), no symbol displays.

The numeric values of 56 and 58 display special symbol types:  56=data markers and 58=vertical lines that mark the X position of the data point.

To map the symbol shape to a dataset, use set DatasetName -k value, where value =100 + number-of-columns-to-the-right.  For example, to base the symbol shape on a dataset located two columns to the right of the data plot's Y dataset in the worksheet, use value =102.  (Note:  There is a limit of four columns to the right.)

For bar graphs, this option is used to set the color index.

-ka value#

For graphs with symbols, set symbol shape to a user-defined bitmap:  0=geometric, 1=first user-defined bitmap, 2=second user-defined bitmap, ... , 24=last user-defined bitmap.

-kb value

For graphs with data labels, display the data labels in bold font style.  1=bold on, 0=bold off.

-kf interior#

For graphs with symbols, set symbol interior:  0=solid, 1=open, 2=dot center, 3=hollow, 4=+ center, 5=x center, 6=- center, 7= | center, 8=half up, 9=half right, 10=half down, 11=half left.  For any numeric values outside of this range, no symbol displays.

To map the symbol interior to a dataset, use set DatasetName -kf value, where value =100 + number-of-columns-to-the-right.  For example, to base the symbol interior on a dataset located two columns to the right of the data plot's Y dataset in the worksheet, use value =102.  (Note:  There is a limit of four columns to the right.)

-ki value

For graphs with data labels, display the data labels in italic font style.  1=italic on, 0=italic off.

-kn font

For graphs with alphanumeric symbols (set DatasetName -k 12 or set DatasetName -k 13), select the font.  Use set DatasetName -kn font(FontName).  For example:  set data1_b -kn font(timesnewroman);.

-ku value

For graphs with data labels, display the data labels with an underline.  1=underline on, 0=underline off.

-l connection#

Line connection method, numbered in order:  0=scatter, 1=line, 2=segment, 3=segment3, 8=Bspline, 9=spline, 11=step horz, 12=step vert, 13=step center, and 15=Bezier.

-lh value

Show/hide horizontal drop lines:  1=show drop lines, 0=hide drop lines.

-lhc value

Set the horizontal drop line color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-lhs value

Set the horizontal drop line style:  0=solid, 1=dash, etc. as in the line style list.

-lhw value

Set the horizontal drop line width, with 500=1 point.

-lv value

Show/hide vertical drop lines:  1=show drop lines, 0=hide drop lines.

-lvc value

Set the vertical drop line color following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-lvs value

Set the vertical drop line style:  0=solid, 1=dash, etc. as in the line style list.

-lvw value

Set the vertical drop line width, with 500=1 point.

-m value

Set the specified data plot as movable with the cursor:  1=movable, 0=not movable (default).

-n name

Rename the dataset.

-o YDataset

Name must be a plotted dataset.  Plot the values in the name dataset as Y error bars for the plotted Ydataset.  For example, if Data1_B and Data1_C are displayed as line data plots in the active graph window, the set data1_c -o data1_b command displays data1_c as Y error bars for data1_b.

-om YDataset

Name must be a plotted dataset.  Plot the values in the name dataset as Y (minus) error bars for the plotted Ydataset.  For example, if Data1_B and Data1_C are displayed as line data plots in the active graph window, the set data1_c -om data1_b command displays data1_c as Y (minus) error bars for data1_b.

-op YDataset

Name must be a plotted dataset.  Plot the values in the name dataset as Y (plus) error bars for the plotted Ydataset.  For example, if Data1_B and Data1_C are displayed as line data plots in the active graph window, the set data1_c -op data1_b command displays data1_c as Y (plus) error bars for data1_b.

-or YDataset

Name must be a plotted dataset.  Plot the values in the name dataset as Y error bars (relative) for the plotted Ydataset.  For example, if Data1_B and Data1_C are displayed as line data plots in the active graph window, the set data1_c -or data1_b command displays data1_c as Y (plus) error bars for data1_b.

-ox YDataset

Name must be a plotted dataset.  Plot the values in the name dataset as X error bars for the plotted Ydataset.  For example, if Data1_B and Data1_C are displayed as line data plots in the active graph window, the set data1_c -ox data1_b command displays data1_c as X error bars for data1_b.

-oxm YDataset

Name must be a plotted dataset.  Plot the values in the name dataset as X minus error bars for the plotted Ydataset.  For example, if Data1_B and Data1_C are displayed as line data plots in the active graph window, the set data1_c -oxm data1_b command displays data1_c as X minus error bars for data1_b.

-oxp YDataset

Name must be a plotted dataset.  Plot the values in the name dataset as X plus error bars for the plotted Ydataset.  For example, if Data1_B and Data1_C are displayed as line data plots in the active graph window, the set data1_c -oxm data1_b command displays data1_c as X plus error bars for data1_b.

-pbc color#

For data plots with bars or columns, set the border color of the bar or column following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-pbs style#

For data plots with bars or columns, set the border line style of the bar or column:  0=solid, 1=dash, etc. as in the line style list.

-pbw width

For data plots with bars or columns, set the border line width of the bar or column, with 500=1 point.

-pd value

Show/hide vertical drop lines:  1=show drop lines, 0=hide drop lines.  (See also the -lh and -lv options.)

-pf value

Turn on or off the fill area option.  1=fill area on, 0=fill area off.

-pfb color#

For data plots with bars or columns, set the background color of the bar or column following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-pfc color#

For data plots with bars or columns, set the foreground pattern color of the bar or column following the color palette:  1=black, 2=red, 3=green, 4=blue, etc.

-pfp fillPattern#

For data plots with bars or columns, set the fill pattern of the bar or column following the pattern drop-down list:  0=none, 1=dense, 2=medium, etc.

-pfw width

For data plots with bars or columns, set the fill pattern line width, with 500=1 point.

-s value

Show/hide the data plot:  1=show, 0=hide.

-skip n

Display every nth symbol in a line+symbol data plot.  The drawn line, on the other hand, goes through all points, up to the page.maxpts display limit.

-tb value

When value=0, the data plot is rendered from metafile descriptions that are stored in memory.  When value=1, the data plot is rendered from an internal bitmap.  For large data plots, the "bitmap mode" provides a faster redraw than the "metafile mode".  However, if you resize the graph, the data plot can appear "blocky" in the bitmap mode.

-tf font

Set the font, where font is the index number in the current font list.  The font(fontName) function can be used to convert a text font name into the index number.

-tj just

Set the justification, with just=0 for left, just=1 for center.

-tr angle

Set the text rotation angle.

-ts size

Set the font size for the label text.

-tx yoffset

Set the Y offset for the data label data plot.  Yoffset is in percent of the label text height.

-ty xoffset

Set the X offset in percent of the label text height.

-u

Set (update) the current display range for name in the active layer to be true for name in all layers.

-ue

Update the Excel workbook when you set values in the associated Origin worksheet layer.

-ui

Update Origin when you type or paste data into an Excel workbook sheet.

-w width

Set the width of the connecting lines, with 500=1 point.

-x value

Value must be a dataset name and serves as the X values for the dataset name.  A graph window must be the active window.  Value can refer to any dataset.

-z

For data plots with symbols, set the data point symbol size, in points, with 1 point=1/72 inch.

To map the symbol size to a dataset, use set DatasetName -z value, where value =100 + number-of-columns-to-the-right.  For example, to base the symbol size on a dataset located two columns to the right of the data plot's Y dataset in the worksheet, use value =102.  (Note:  There is a limit of four columns to the right.)

Examples:

The following script sets the beginning of the display range for dataset data1_b to 10.

set data1_b -b 10;

The next script sets the line width to two points.

set data1_b -w 1000;

The next script hides data1_b.

set data1_b -s 0;

The following script opens the Plot Details dialog box for data1_b.

set data1_b;

The next script sets the active scatter data plot to display row numbers as data point symbols.

set %C -k 11;

The next script adds an XY data plot (data2_b as Y, data1_a as X) to the active layer.

layer -i data2_b; set data1_a -x data2_b; rescale;

In the last example, open a new project and import the WIND.DAT file from the Origin 6 TUTORIAL folder.  Select the Month column and then select Column:Move to Last.  Set this column to a label column.  Select the Power and Month column and select Plot:Scatter.  Then run the following script to set the label data plot display attributes.

ii=font(Arial);

//use the font function to find Arial font index #

set Wind_Month -tr 90;	//rotate 90 degrees

set Wind_Month -ty 50;	//50% y offset

set Wind_Month -tj 0;	//left justify

set Wind_Month -tf ii;	//set as Arial font


Command Reference - Alphabetical Listing of Commands - Sort
Sort

Syntax:	sort [option] object(s)

Sort the given variables, or sort all values in the worksheet against a dataset.

The built-in sort( ) function can also be used to sort a dataset.  For example:

data1_a = sort(data1_b);

sorts data1_b in ascending order, then assigns it to data1_a.

Options:

no option  variable1 variable2 ... variable10

Sort the given variables in ascending order by value.  Reassign the values such that variable1 contains the smallest value, and variable10 (or the last variable given) contains the highest value.

-c c1 c2 datasetName

Sort the current worksheet in ascending order between columns c1 and c2, inclusive, against the specified dataset within the worksheet.  Row integrity is maintained among the specified columns.

-cd c1 c2 datasetName

Same as -c, but sort in descending order.

-w worksheetName datasetName

Sort the entire worksheet in ascending order against values in the specified dataset.  Row integrity is maintained.

-wd worksheetName datasetName

Same as -w, but sort in descending order.

Examples:

If Data1 is the active window, the following script sorts the 2nd through the 7th columns against data1_c, in ascending order.  If data1_c is not in the specified range, the relationship between it and the other columns is destroyed.

sort -c 2 7 data1_c;

The next script sorts all columns in the Data1 worksheet against the data1_c dataset.

sort -wd Data1 data1_c;

The following script uses the wks.nrows object property to assign the number of rows in several worksheets to several variables.  The sort command is used to find the smallest value and place it in the A variable.  The value of the smallest number of rows is typed to the Script window.

A=$(Data1!wks.nrows);

B=$(Data2!wks.nrows);

C=$(Data3!wks.nrows);

D=$(Data4!wks.nrows);

sort A B C D;

type "The smallest worksheet has $(A) rows.";


Switch

Syntax:	switch (argument) {case1: . . . case2: . . . casen: . . . [default: . . .]}

The switch command is a special multi-way decision maker that tests whether an expression matches one of a number of values, and branches accordingly.  The value can be either a constant or an identifier.

Each case requires a break command, so the following commands are not executed.  A default case can also be used, and should come last (when nesting switch commands, the default case must come last).  The default case is executed only when no other case is matched.

Note:  Like all of LabTalk, the case and default keywords are case-insensitive.

Examples:

The following script uses the switch command.  Since the argument is 2, case 2 is executed.  The result from this script is b.

ii=2;

switch (ii)

{

case 1:

type "a"; break;

case 2:

type "b"; break;

case 3:

type "c"; break;

default:

type "none"; break;

}


Timer

Syntax:	timer <cycleLength>

This command executes the script named TimerProc every cycleLength seconds.  Before issuing this command, you must define the action TimerProc should perform.  Maximum cycleLength is 56 seconds.  To define the TimerProc macro, see the define command.

Options:

no option cycleLength

Execute the TimerProc macro every cycleLength seconds.

-k

Stop executing the TimerProc macro.  This removes the current timer.

Examples:

The following script prints "Hello" to the Script window every twenty seconds.

def TimerProc {type "Hello"};

timer 20;


Command Reference - Alphabetical Listing of Commands - Type
Type

Syntax:	type [option] message

Outputs a string to the specified device.  This command does not require the use of parentheses, unless an "=" is displayed in the message.  You must enclose a message with an "=" in parentheses.  Otherwise, the statement is interpreted as an assignment.

Note:  In addition to entering literal text for message, you may specify $[OMGfileName].Section.Title.  This enables you to access a string title in a message file.  For example:  Type -b $General.BadCalculation; types out the BadCalculation text contained in the General section of the ORIGIN.OMG file to a dialog box with an OK button.  The OMGfileName file extension is assumed to be OMG.  If OMGfileName is not specified, the ORIGIN.OMG file is assumed.

Options:

no option message

Print message to the Script window.

-a message

Open the Script window (if it is closed) and print message.

-b message

Display message in a dialog box with an OK button.  If the message is omitted, this command produces a beep.

-c message

Display message in a dialog box with Yes and Cancel buttons.  Click on the Cancel button to generate a break in the current script.

-h message

Hide the Script window.

-l message

Print to the Script window, but disable the carriage return and linefeed for this text.

-n message

Display message in a dialog box with Yes and No buttons.  Click on the No button to generate a break in the current script.

-o argument

Perform argument operation on the Script window.  Argument can be one of the following (you need only supply the first letter):

Argument:  execute

Description:  Turn Script Execution off.  This shifts the Script window out of script execution mode.

Argument:  new

Description:  Create a new Script window text file.  Erases any changes made since last saving the current text file.

Argument:  open [filename]

Description:  Print the filename file to the Script window.  If filename is not specified, open the Open dialog box.

Argument:  print

Description:  Print the contents of the Script window.

Argument:  save [filename]

Description:  Save the current Script window text.  Create a new file named filename if filename is specified.  This is the simplest way to create a script file.

Argument:  tab pixels

Description:  Set the tab spacing to pixels pixels.  The default value is 45 pixels.

Argument:  window title

Description:  Change the title of the Script window to title.

-q message

Display message in the status bar.

-qp n

Enable (n=1) or disable (n=0) the arithmetic status messages that show the progress of calculations.

-qs n

Enable (n=1) or disable (n=0) the status bar.  When the status bar is disabled, the last message displays until the status bar is enabled again.

-s message

Types message to a previously open Script window even if it has been hidden.

-tb object.property

Type the text property of the object to an attention box.  .

-tn object.property

Type the text property of the object to a Yes/No dialog box.

-tq object.property

Type the text property of the object to the status bar.

-ty object.property

Type the text property of the object to a Yes/No/Cancel dialog box.

-v -option message

Override using the escape sequence substitution so that \n is not recognized as New Line, \r is not recognized as Return, etc. (see the following "Non-printable Characters" section).  Use -v before (option) -b, -c, and -y.  This option allows the use of file paths in message.  For an example, see the Examples section.

-y message

Display message in a dialog box with YES, NO and CANCEL buttons.  Click on the YES button to set Origin's t variable to one.  Click on the NO button to set t to zero.  Click on the CANCEL button to generate a break in the current script.

Non-printable Characters:

To specify non-printable characters:

\n	New line.

\r	Return.

\d	Delete/backspace.

\t	Tab.

\xhh	Any characters, where hh are two hex digits.

For example:	type -b "Test A \r\n\Next Line\x0d\x0a";

Note:  You can also use escape sequences to format the output of text.  For a complete listing of the escape sequences, see the label command.

Examples:

The following script displays the message "I'm busy right now" in the status bar.

type -q "I'm busy right now";

The next script displays the message "Here is some text, and here is some more" on one line in the Script window.

type -l "Here is some text";

// other code

type ", and here is some more";

The next script prints "My file is stored in C:\TEMP\FILE1.OPJ." to a dialog box with an OK button.  Note:  \T is not interpreted as a tab.

type -v -b "My file is stored in C:\TEMP\FILE1.OPJ.";

The last script displays the Bottom X Axis Title text in the status bar.

type -tq "XB.text";


Undo

Syntax:	undo [option] [dataset]

This command provides a LabTalk interface to Origin's Edit:Undo menu command.  For an understanding of usage, review the sample scripts provided in the Examples section.

Note:  Some actions in Origin do not add anything to the undo stack and are therefore not reversible.  Other actions will clear the undo stack.  To find where this option is currently implemented, search the OGS files for "undo".

Options:

no option

Undo the last action.

dataset

Backup dataset by creating an internal copy of dataset.

-dr dataset i1 i2

Create an internal copy of the specified dataset range.  The dataset range includes rows i1 to i2.  To create an internal copy of a single data point, set i1 = i2.  (Origin executes this command internally when a data point is deleted from the graph window using the Data:Remove Bad Data Points menu command.)

-dx dataset

Create an internal copy of dataset.  (Origin executes this command internally when a data plot is (horizontally) translated using the Analysis:Translate:Horizontal menu command.)

-wa

Create an internal copy of the datasets in the active worksheet.  (Origin executes this command internally when Edit:Clear Worksheet is selected.)

-wc wks

Create an internal copy of the datasets in the specified worksheet wks.  (Origin executes this command internally when Analysis:Sort is selected.)

-wr

Create an internal copy of the selected dataset range in the active worksheet.  (Origin executes this command internally when Analysis:Normalize is selected.)

Examples:

The following script modifies worksheet column values in Data1_B.  It then restores the original column values.

undo Data1_B;    // Make an internal copy of Data1_B.

Data1_B+=4;

undo;    // Undo the dataset modification.

Assuming a range of data is selected in Data1_B, the next script modifies the values in the data range.  It then restores the original values.

undo -wr;    // Make an internal copy of the selected range.

Data1_B/=4;

undo;

The next script modifies worksheet column values in Data1_A and Data1_B.  It then restores the original column values.

undo -wc Data1;  // Make an internal copy of datasets in Data1.

Data1_A+=4;

Data1_B+=4;

undo;    // Undo the dataset modification.

The last script restores a deleted data point (in this example, the second point) in the Data1_B dataset.

undo -dr Data1_B 2 2;  // Make an internal copy of the second data point.

mark -d Data1_B -b 2 -e 2;  // Delete the second data point.

undo;


Window

Syntax:	window option

This command creates, opens, closes, activates, and performs several actions on graph and worksheet windows.  The option switch determines the action to be performed.

Options:

-a winName

Set winName as the active window.  This option also has the effect of a Windows Restore if the active window is maximized or minimized.

-an winName

Activate (restore) the winName notes window.

-b winName

Get the first window in the Window menu window list that begins with winName.  If the named window cannot be found, look for a template file called winName and open it.  If no template file is found, open ORIGIN.OTP.  If ORIGIN.OTP is not found, create a window from scratch, name it winName, and enumerate it.

-c winName

Close the winName window.  The window is closed without prompting the user.  If the window is a worksheet window, the datasets are not deleted.

-ca winName

Close the winName window as if the user selected the Close menu command from the child window system menu.  This option prompts the user with a dialog box.

-ch n

Hide the active window:  n=1 to hide the active window and n=0 to show the active window.  The window's Project Explorer view mode changes.  For example, if the window was in Normal view, it changes to Hidden view (Project Explorer View column) when n=1.  See also, win -h.

-cn winName

Close the winName notes window without prompting.

-d

Create a duplicate of the active window.  The new window is named Datan or Graphn, etc. , where n is the lowest available number.

-e winName

Open, or set as active, the graph window with the given name (if it is not already open or active), and empty the window of all data plots.  If the window does not exist, open the template of the same name, otherwise open the ORIGIN.OTP template.

-g

If the active window was opened from a template file, put the path and the template file name into %A.

-h n

Hide the active window:  n=1 to hide the active window and n=0 to show the active window.  The window's Project Explorer view mode remains set to its current view (for example, Normal or Maximized), but it does not display.  See also, win -ch.

-i

Minimize the active window.

-in winName

Minimize the winName notes window.

-l 0

Put the active window to the end of the Window menu window list.

-m

Merge all graph windows.

-ma

Prompt with a dialog box before merging all graph windows.

-n winType [winName]

Create a new window from scratch and name it winName.  If winType is plot, open a graph window.  If it is data or wks, open a worksheet.  If winType is n, open a Notes window.  If winName is not specified, use the next available default name (Graph1, Graph2, Data1, Data2, etc.).  Use the -n option to avoid opening a window from a template file.

-o winName {script}

Execute (operate) the specified script for the named window.  WinName is temporarily set internally as the active window, the script is executed, then the original active window is re-established.  Most commands operate on the active window.  The %H system variable can be used by commands that require a window name.

-oa winName {script}

Execute (operate) the specified script for the named hidden window.  WinName is temporarily set internally as the active window, the script is executed, then the original active window is re-established.  Most commands operate on the active window.  The %H system variable can be used by commands that require a window name.

-r windowName newName

Rename windowName with the given newName.

-ra

Open the Rename dialog box.

-s  T

Window system call to tile all windows.

-t winType template [winName]

Open a new window from the template file.  This command checks for a path in template and will use this path if specified.  If the path includes spaces, you must surround the path with quotation marks (" ").  For example, use win -t winType c:\MyDir\MyTemp winName to open a winType window based on the MyTemp template in the c:\MyDir directory.  Name this window winName.  Use win -t winType MyDir\MyTemp winName to open a winType window based on the MyTemp template in the MyDir subdirectory of the software directory.  Name this window winName.

Whenever loading is from the software directory, it will search first on the user's and then on the system's directory.

If winType is plot, open a graph window.  If it is data or wks, open a worksheet.  The window is named winName, or named by default (Graph1, Graph2, etc.) if winName is not given.

If winType, template, and winName are omitted, Origin opens a Datan worksheet based on ORIGIN.OTW.

-w winName

Temporarily set the active window to winName.  This allows commands that work with the active window to apply to winName.  You must eventually execute win -w to restore normal operation before using the command again.

-z

Maximize the active window.

-zn winName

Maximize the winName notes window.

Examples:

The following script opens a graph window from the MASTER template (in the software directory) and names the window Master.

win -t plot MASTER Master;

The next script opens a new worksheet from the FFT template (in the software directory) and names it by default (data1, data2, etc.).

win -t data FFT;

The next script opens a graph window from the MASTER template located in the C:\MYOWN directory and names the window Master.

win -t plot c:\MyOwn\MASTER Master;

The following script opens a graph window from the MASTER template located in the MYOWN subdirectory of the software directory and names the window Master.

win -t plot MyOwn\MASTER Master;

The next script finds the first window in the Window menu window list that begins with graph and sets it as the active window.  If no window is found, it creates a Graph1 window.

win -b graph;

The following script rescales the Graph2 window's X axis from -10 to 10.

win -o graph2 {

x1=-10;

x2=10;

};

The last script closes the current worksheet together with all associated datasets.

Page.CloseBits=2;  // uses the closebits page property

win -ca;


Worksheet

Syntax:	Worksheet option argument

Use this command to set various formatting options for, and plot data from, the active worksheet.

Options:

-a n

Add n columns to the active worksheet.

-b winName

Get the first worksheet that begins with winName.  If the named window cannot be found, look for a template file called winName and open that.  If no template file is found, open ORIGIN.OTW.  If ORIGIN.OTW is not found, create a window from scratch, name it winName, and enumerate it.

-c colName

Create a new Y column named colName and add it to the end of the worksheet.

-d [wksName]

Duplicate the active worksheet into a new worksheet named wksName.  The new worksheet becomes the active window after this command.  If wksName is not specified, a default name (data1, data2, etc.) is used.

-da [wksName]

Same as the -d option, but the original worksheet is kept active.

-dr [wksName]

Same as the -d option, but the worksheet script is executed automatically.

-e dialogbox

Open the specified worksheet dialogbox.  See the following list for dialogbox values.  (Note:  For Format, a column must be selected.)

dialogbox:  ASCII

Opens:  ASCII Import Options for Datan dialog box.

dialogbox:  DisplayControl

Opens:  Worksheet Display Control dialog box.

dialogbox:  Format

Opens:  Worksheet Column Format dialog box (first select a column).

dialogbox:  Par

Opens:  Import Verification dialog box.

dialogbox:  Script

Opens:  Worksheet Script dialog box.  If the user clicks on the Do It button, i is set to 1.  If the user clicks on the Update button, i is set to 0.

-f colRef colFormat

Set the colRef column to the given format:  1=numeric, 2=text, 3=time, 4=date, 5=month, 6=day of week, 7=text & numeric.

If a number is supplied for colRef, it is assumed to be the worksheet column number.  Any other value is assumed to be the column name.  Therefore, use the $(expression) substitution operator to evaluate an expression for colRef.

-fd colRef nDigits

Set the number of decimal digits (nDigits) to be used by the colRef column:  -3=free format.  If a number is supplied for colRef, it is assumed to be the worksheet column number.  Any other value is assumed to be the column name.  Therefore, use the $(expression) substitution operator to evaluate an expression for colRef.

-fi colRef internalType

Set the colRef column's internal type to the specified value:  1=double, 2=float, 3=short, 4=long.

If a number is supplied for colRef, it is assumed to be the worksheet column number.  Any other value is assumed to be the column name.  Therefore, use the $(expression) substitution operator to evaluate an expression for colRef.

-i n name

Insert the name column as the n+1 column in the worksheet.

-k n

Determines the number of lines of header to skip when importing an ASCII file.  When n=0, skip 0 lines.  When n=1, skip 1 line, etc.

-n colRef newName

Change the name of the colRef column to newName.

If a number is supplied for colRef, it is assumed to be the worksheet column number.  Any other value is assumed to be the column name.  Therefore, use the $(expression) substitution operator to evaluate an expression for colRef.

-p n template

Plot the current worksheet selection in the nth graph type into the template.  Opens the Select Columns for Plotting dialog box if there is no current worksheet selection.  Plots into the ORIGIN.OTP template if no template is specified.  Possible n values are shown below.  Certain templates are included with the Origin software, and the template name is provided where applicable.  You are not restricted to using the provided templates.

n Value	Graph Type	Provided Template
193	Bubble (indexed size)	scatter
194	Bubble + color mapped (2 Y columns selected)	scatter
200	Line	line
201	Scatter	scatter
202	Line+symbol	linesymb
203	Column	column
204	Area	area
205	High-Low-Close	hlclose
206	Box	box
207	Floating Bar	floatbar
208	XYAM Vector	vector
210	3D Walls	walls
211	3D Ribbons	ribbon
212	3D Bars	bar3d
213	Column Stack	column
214	Fill area	fillarea
215	Bar	bar
216	Stack Bar	bar
218	XYXY Vector	vectxyxy
225	Pie chart	pie
226	Contours	contour, contline, and contgray
227 - 229	DLL	none
240	3D space plots	3d and traject
242	3D surface plots	mesh, xconst, yconst, cmap, wirefrm, and wireface
245	Ternary	ternary
247	Color mapped	scatter
248	Bubble + color mapped (3 Y columns selected)	scatter
279	Histogram	hist
-r

Run the script in the Worksheet Script dialog box.

-s c1 r1 c2 r2

Set the specified range to be the current worksheet selection.  To select entire columns, set r1 and r2 to zero.  To select entire rows, set c1 and c2 to zero.

-t colRef colType

Set the colRef column as the given column type:  1=Y, 2=Disregard, 3=Y Error, 4=X, 5=Label, 6=Z, and 7=X Error.

If a number is supplied for colRef, it is assumed to be the worksheet column number.  Any other value is assumed to be the column name.  Therefore, use the $(expression) substitution operator to evaluate an expression for colRef.

-v colName

Verify that a named column exists.  Create the column if it does not exist.  Otherwise, do nothing.

Note:  If the column is created, the end display range is set to row 0.

Examples:

The following script adds 20 columns to the worksheet.

work -a 20;

The next script renames each column as C1, C2, C3, etc., and fills each column with 100 values.

for (ii=1;ii<=20;ii++)   {     // Loop over the first 20 columns

work -n $(ii) C$(ii);	    // Rename iith column to Ci

work -t $(ii) 1;	    // Set column as Y column

wcol(ii)=data(ii,100,ii);   // Fill column with values

}

The last script sets column 3 as a text column.

work -f 3 2;


Object Reference - Introduction
Introduction

LabTalk accesses many of Origin's functions through object methods and properties.  There are two basic classes of Origin objects:  internal objects and external objects.

Internal objects are objects which are constructed by Origin.

External objects are objects which exist in external DLLs.

Among the internal objects, there are two types of objects:  window objects and utility objects.

Window objects are visible objects in Origin windows, such as an axis or worksheet object.  Window object methods and properties affect a specific object within the project.  For example, the MajorTicks property of an axis object changes the number of ticks on that single axis.

Utility objects are generalized objects.  Utility object methods and properties allow you to set preferences for the entire Origin session.


Object Properties and Methods

LabTalk operates on objects with properties and methods.  Properties are specific attributes of an object, such as the color of a label or the number of columns in a worksheet.  LabTalk property statements set a particular object attribute or return its current value.  Methods are things that can be done to or with an object, such as updating its graphic image.  LabTalk method statements take arguments and perform operations which are directly related to an object.

Note:  All object property and method names are case-insensitive.

More:

Properties

Methods


Properties

A property either sets or returns a number or a text string associated with an object.  Not all properties are read/write accessible.

More:

Setting a Property Value

Reading a Property Value


Setting a Property Value

Numeric Property Values

Numeric properties are set by LabTalk scripts using statements with the following syntax:

objName.Property=value

objName is the name of the object.

Property is a valid property for the type of object.

value is a number.

Text Property Values

Text properties are set by LabTalk scripts using statements with the following syntax:

objName.Property$=value

objName is the name of the object.

Property is a valid property for the type of object.

value is a text string.


Reading a Property Value

Numeric Property Values

The current value of a numeric property is read and assigned to a variable using the following syntax:

variable=objName.Property

View the value of the property in the Script window using the following syntax:

objName.Property=

For example, entering the following script in the Script window:

page.active=

could return page.active=1 indicating that the first layer of the page is active.

Substitution notation may also be used to obtain the current value of a numeric property, as in the following script:

type -a "The property is $(page.active)";

This script obtains the current value of the page object property, substitutes it for the expression, and types it in the Script window.

Text Property Values

The value of a text property cannot be read directly.  The value must be assigned to a string variable and then displayed.  The current value of a text property is read and assigned to a string variable using the following syntax:

%letter=objName.Property$;

For example, enter the following script in the Script window to assign the value of the text property of a text label to the %Z string variable:

%Z=objName.text$

View the value of the text property by entering the following script in the Script window:

%Z=

Alternatively, display the text property using:

type -b "The property is %Z";


Methods

Methods are a form of immediate command.  When executed, they carry out a function related to the object and return a value.  Object methods use the following syntax:

objName.Method(arguments)

objName is the name of the object.

Method is a valid method for the type of object.

arguments determine how the method functions.  Some arguments are optional and some methods do not require any arguments.  However, the parentheses "( )" must be included in every object method statement.


Internal Object Overview

Internal objects are objects which are constructed by Origin.  Among the internal objects, there are two types of objects:  window objects and utility objects.

More:

Window Objects

Utility Objects


Window Objects

Window objects are visible parts of Origin child windows.  These include the visual objects created by Origin, as well as user-created visual objects.

More:

Visual Objects Created by Origin

User-created Visual Objects


Visual Objects Created by Origin

The visual objects created by Origin are hierarchical in nature.  For example, each Origin child window contains a visual page with an associated page object.  Though a page can be either a graph or worksheet page, most page object properties affect the visual graph page.

Each graph page contains at least one visual layer with an associated layer object.  Because a graph window can contain only one page, when accessing the layer object's properties or methods, the associated page object is not included or referenced.  Thus, the property and method syntax of the layer object does not include the syntax of the page object.

For example:  [winName!]layer[n].property=

NOT:  [winName!]page.layer[n].property=

The graph layer contains a set of X Y axes with associated X, Y, etc. objects.  Because a page can contain multiple layers, when accessing the X, Y, etc. object's properties or methods, the associated layer object is included or referenced.  Thus, the X, Y, etc. objects' method and property syntax includes the syntax of the layer object.  The X, Y, etc. objects are sub-objects of the layer object.

For example:  [winName!]Layer[n].X.property=

NOT:  [winName!]X.property=

The axes within an Origin child window can also contain graphic elements including tick labels, an axis break, and an axis grid.  These visual elements have associated objects (label, break, and grid).  The label, break, and grid objects are sub-objects of the respective X, Y, etc. object, which is a sub-object of the layer object.  The object method and property syntax of the sub-objects includes the syntax of the "main" object.

For example:  [winName!]Layer[n].Y.break.property=

NOT:  [winName!]break.property=

Each worksheet page contains no more than one visual worksheet with an associated wks object.  The worksheet page also contains no more than one layer with an associated layer object.  Because a worksheet window can contain only one page, and the page contains only one worksheet, when accessing the wks object's properties or methods, the associated page object is not included or referenced.  Likewise, because the worksheet page contains only one layer, when accessing the layer object's properties or methods, the associated page object is not included or referenced.  Thus, the syntax of the wks and layer objects does not include the syntax of the page object.

For example:  [winName!]wks.property=

NOT:  [winName!]page.wks.property=

For example:  [winName!]layer.property=

NOT:  [winName!]page.layer.property=

The worksheet contains visual columns with associated col objects.  The col object is a sub-object of the wks object.  Thus, the col object method and property syntax includes the syntax of the wks object.  Additionally, like the layer object, the col object is enumerated if the active column is not to be referenced.

For example:  [winName!]wks.col[n].property=

NOT:  [winName!]col[n].property=

The following window objects are available in Origin.

layer	page
(axis) X, Y,	wks
break	col
grid	export
label	import
plotn.boxchart
Property and Method Syntax

Properties and methods of Origin's window objects affect the object in a specific window.  If a window is not specified, the active window is used.  The window object syntax is as follows:

[WinName!]objName.Method(arguments)

[WinName!]objName.Property=value

[WinName!]objName.Property$=string

WinName! is optional.  However, if winName is specified, its name must be followed by an exclamation point "!".  If winName! is not specified, the named object in the active window is affected.

objName is the name of the object.  If objName is a sub-object, then the "main" object is specified before objName.  For more information, see  Visual Objects Created by Origin.

Method is one of the available objName methods.

arguments are specific to the method.

Property is a valid property for objName.

value is a number.

string is a text string or string variable.

Note:  Some window objects only exist in worksheet windows or graph windows.  Others have some properties which are valid for both window types.


User-created Visual Objects

Visual objects can also be created by the Origin user and placed in an Origin child window.  These objects include labels, arrows, lines, and other user-created graphic elements.  These objects are accessed from script by their name, as defined in the associated Label Control dialog box.  To open the Label Control dialog box, select Edit:Button Edit Mode to enter Button Edit Mode.  Click on the object, then select Format:Label Control.  Enter the desired name in the Object Name text box.  Click on the OK button to close the dialog box.

Scripts can be attached to these labels by typing the desired script into the text box of the Label Control dialog box.  Script execution is controlled by the selection from the 'Script, Run After' drop down list.

In general, only named objects can be accessed from LabTalk script.  However, an unnamed object can be accessed by a script from within its own Label Control dialog box with this. notation, as described in the following section.

Property and Method Syntax

Properties:

The syntax of the user-created visual object properties is as follows:

[winName!]objName.property=value

or

this.property=value

WinName! is optional.  It specifies the window that the named object resides in.  This is useful when there are several objects with the same name in a project.

objName is the object's name, as entered in the Object Name text box in the Label Control dialog box.

Property is one of the available objName properties.

The following list reviews the generic properties of these objects.

object.attach

Access:  Read, Set

'Attach to' method:  0=layer, 2=axes scales, and 1=page.

object.auto

Access:  Read, Set

Redraw automatically after property changes:  0=disable, 1=enable.

object.background

Access:  Read, Set

Control the background of an object as follows:  0=no background, 1=black line, 2=shadow, 3=dark marble, 4=white out, and 5=black out.

object.color

Access:  Read, Set

Line, text, or outline color index number.  Use the color( ) function, as in name.color=color(red);

object.dx, object.dy

Access:  Read, Set

Width and height in axes units.

object.enable

Access:  Read, Set

Enable hotspots on the object:  0=disable, 1=enable.

object.event

Access:  Read

The object's script execution:  1=run script when button is clicked, 0=all other events.

object.fillColor

Access:  Read, Set

Shape object fill color index number.  Use the color( ) function, as in name.fillcolor=color(red);

object.font

Access:  Read, Set

Text label font index number.  Use the font( ) function, as in name.font=font(arial);

object.fSize

Access:  Read, Set

Text label font size.

object.height

Access:  Read

Height in layer coordinate units.

object.hMove

Access:  Read, Set

Horizontal movement:  0=disable, 1=enable.

object.index

Access:  Read

Only applicable for objects composed of multiple items, such as the UIM objects.  Indicates which item in an object has been affected by a Windows action.  (Note:  The UIM is a component of Origin Professional.  For more information, contact Microcal Software or your Origin dealer.)

object.keepInside

Access:  Read, Set

Restrict object's movement to within the layer frame:  0=disable, 1=enable.

object.left

Access:  Read, Set

Left location of the object in physical coordinates.

object.lineType

Access:  Read, Set

Line and arrow object line type:  1=solid, 2=dash, and 3=dot.

object.lineWidth

Access:  Read, Set

Line or arrow object line width.

object.mouse

Access:  Read, Set

Mouse access to the object:  0=disable, 1=enable.

object.name$

Access:  Set

Object name.

object.realTime

Access:  Read, Set

Real-time update of substitution notation in a text label message:  0=disable, 1=enable.

object.revVideo

Access:  Read, Set

Reverse video display:  0=disable, 1=enable.

object.rotate

Access:  Read, Set

Text label rotation in degrees.

object.script

Access:  Read, Set

'Script, Run After' mode index number, from the drop-down list in the Label Control dialog box.

object.show

Access:  Read, Set

Object display:  1=visible, 0=hidden.  Hidden objects are not selectable.

object.text$

Access:  Read, Set

Message displayed by a text label.

object.top

Access:  Read, Set

Top of the object in physical coordinates.

object.vMove

Access:  Read, Set

Vertical movement:  0=disable, 1=enable.

object.width

Access:  Read

Width in layer coordinate units.

object.x, object.y

Access:  Read, Set

Axes X Y coordinates of the center of the object.

Methods:

The syntax of the user-created object methods is as follows:

[winName!]objName.Method(arguments)

or

this.Method(arguments)

WinName! is optional.  It specifies the window that the named object resides in.  This is useful when there are several elements with the same name in a project.

objName is the object's name, as typed in the Object Name text box in the Label Control dialog box.

Method is one of the available objName methods.

arguments are specific to the method.

The following list reviews the generic methods of these objects.

object.addText(stringVariable)

Append the stringVariable contents to a text label.  Requires a screen refresh to view the change.

object.click(n)

Simulate a click on the nth hot spot of the object.  Multiple hot spots are a feature of UIM objects.

object.draw(option)

Redraw the object.  Option=local to redraw hot spots.  Option=global to redraw the entire object.

object.run( )

Run the script of the object.

Examples:

The following script disables horizontal movement for the Arrow object in the Graph2 window.

Graph2!Arrow.hmove=0;

When entered in the Script window, the next script types the X and Y coordinates of the center of the Button object to the Script window.

Button.x=;

Button.y=;

The following script runs the script associated with an object named Mode in the Graph1 window.

Graph1!mode.run( );

The last script uses the draw( ) method to redraw the WksData object in the Data2 window.

Data2!Wks.Data.draw(global);


Utility Objects

Utility objects are generalized objects.  These objects do not have a visual counterpart in the Origin project.  Utility objects allow you to set preferences that affect the entire active Origin session.  The default values for most of these properties are set in the OPTION.CNF file which is read when Origin is launched.  Many of the default values may also be changed during an Origin session in the Options dialog box.  To open the Options dialog box, select Tools:Options.

More:

Property and Method Syntax


Object Reference - Utility Objects - Property and Method Syntax
Property and Method Syntax

Properties and methods of Origin's utility objects affect the entire Origin session.  The utility object syntax is as follows:

objName.Method(arguments)

objName.Property=value

objName.Property$=string

objName is the name of the object.

Method is one of the available objName methods.

arguments are specific to the method.

Property is a valid property for the objName object.

value is a number.

string is a text string or string variable.

The following tables display the utility objects available in Origin.

break	integ
copy	limit
create	lr
doc	macro
draw	menu
excel	rt
export	run
export.image	sort
fdlog	sum
getpts	type
ini
system	system.fileext	system.page
system.axis	system.font	system.path
system.copypage	system.graph	system.print
system.dash	system.grid	system.project
system.datadisplay	system.math	system.script
system.date	system.notes	system.symbol
system.dialog	system.numeric	system.tick
system.display	system.operations	system.wks
system.excel


External Object Overview

External objects are objects which exist in external DLLs.  External objects are not window specific- they affect the entire Origin session.  A number of external objects are already accessible in Origin.  Additionally, you can create your own objects in user-defined external DLLs.  This process is reviewed in the Origin Professional package.

More:

Property and Method Syntax

Common Properties and Methods


Object Reference - External Object Overview - Property and Method Syntax
Property and Method Syntax

Properties and methods of external objects affect the entire Origin session.  External object syntax is as follows:

objName.Method(arguments)

objName.Property=value

objName.Property$=string

objName is the name of the object.

Method is one of the available objName methods.

arguments are specific to the method.

Property is a valid property for the objName object.

value is a number.

string is a text string or string variable.

The following external objects are available in Origin.

curve	nlsf
fft	stat
mat


Common Properties and Methods

External objects share a number of properties and methods.  These properties and methods are listed and described in the following sections.

Note:  Replace object with the desired external object (for example, curve).

Properties:

object.apparent

Access:  Read, Set

If object=stat:  Use axes scale functions to perform apparent fitting.  1=enable, 0=disable.

object.data$

Access:  Read, Set

If object=stat:  The name of the input dataset in linear and polynomial regression.  If object=curve:  the name of the input dataset.

object.error

Access:  N/A

Not in use.

object.errorOut

Access:  N/A

Not in use.

object.errow

Access:  N/A

Not in use.

object.matrix$

Access:  N/A

Not in use.

object.msg$

Access:  N/A

Not in use.

object.name.datan$

Access:  Read, Set

New dataset name as generated by object.

object.name.worksheet$

Access:  Read, Set

New worksheet name as generated by object.

object.orgVer

Access:  N/A

Not in use.

object.sysErr

Access:  Read

System error.  Same as ERRNO defined in STDLIB.H.

object.version

Access:  N/A

Not in use.

object.warnMsg

Access:  N/A

Not in use.

object.worksheet$

Access:  Read

Name of the worksheet with the original data.

object.X$

Access:  N/A

Not in use.

Methods:

object.lastErrID( )

Not in use.

object.listErr( )

List all errors that occurred in the program (in reverse order of occurrence).

object.reset( )

Reset all DLL properties to their original, unassigned values.

object.test( )

Not in use.


Alphabetical Listing of Objects

A complete listing of all LabTalk objects is provided in the following pages of this Help file.

More:

Break

Copy

Create

Curve

Doc

Draw

Excel

Export

Export.Image

Fdlog

FFT

Getpts

Ini

Integ

Layer

Layer.Axis

Layer.Axis.Break

Layer.Axis.Grid

Layer.Axis.Label

Layer.Plotn.BoxChart

Limit

LR

Macro

Mat

Menu

NLSF

Page

RT

Run

Sort

Stat

Sum

System

System.Axis

System.CopyPage

System.Dash

System.DataDisplay

System.Date

System.Dialog

System.Display

System.Excel

System.FileExt

System.Font

System.Graph

System.Grid

System.Math

System.Notes

System.Numeric

System.Operations

System.Page

System.Path

System.Print

System.Project

System.Script

System.Symbol

System.Tick

System.Wks

Type

Worksheet (wks)

Wks.Col

Wks.Export

Wks.Import


Object Reference - Alphabetical Listing of Objects - Break
Break

Construct a progress/information dialog box that is under scripting control.

Properties:

break.abort

Access:  Read

1=the user pressed the Cancel button.  Otherwise, is 0.

break.max

Access:  Read, Set

Maximum value of the progress bar.  Note:  Must set this property value after using the break.open( ) method.

break.min

Access:  Read, Set

Minimum value of the progress bar.  Note:  Must set this property value after using the break.open( ) method.

break.style

Access:  Read, Set

0=default, 1=no progress bar, 2=End button instead of a Cancel button.

Methods:

break.close( )

Close the progress/information dialog box.

break.open(message)

Open a progress/information dialog box.  Message is displayed in the dialog box.

break.set(value)

Set the current value for the progress dialog box.  Note:  If you need a progress bar that shrinks, then you must precede every break.set( ) that causes shrinking with a break.set(break.min) to clear the progress bar.

Examples:

The following script opens a progress dialog box with an End button.  It uses a for loop to increment the progress bar values and executes a user script.  Once the progress bar has reached its maximum value, it closes the dialog box.

break.style=2; // use End button to allow script to continue

break.open(This is a test); // init min,max to 0 and 100

break.min=-10;break.max=10;

// MUST do these after break.open()

for (ii=break.min;ii<=break.max;ii++) {

break.set(ii);

if (break.abort==1) break;

sec -w 0.2;	//pause for .2 of a second

// execute some other user tasks

};

break.close();

type "ii=$(ii)";


Object Reference - Alphabetical Listing of Objects - Copy
Copy

The copy object is used in association with the copy command.

Properties:

copy.n

Access:  Read

Read the number of elements copied when using the copy command.

Examples:

The following script assumes that a Data1 worksheet exists with at least two columns, Data1_A and Data1_B.  The script copies the elements of Data1_A to Data1_B and prints (to the Script window) the number of elements copied.

copy Data1_A Data1_B;

type "$(copy.n)";


Object Reference - Alphabetical Listing of Objects - Create
Create

The create object is used to create a custom minimized worksheet.

Properties:

create.datan$

Access:  Read

Returns the nth created dataset created with the create.wks( ) method.

create.enumerate

Access:  Read, Set

Enumerate worksheet columns:  1=enable.  When using create.wks( ), if the columns passed already exist in the worksheet, then add new enumerated columns based on the column names.  0=disable.  If the columns already exist, overwrite them.

create.enumWks

Access:  Read, Set

Enumerate worksheet.  1=enable.  When using create.wks( ), if the worksheet set by create.wksname$ already exists, create a new enumerated one.  0=disable.  If the worksheet exists, use that worksheet.  Otherwise create it.

create.npts

Access:  Read, Set

Total number of rows in the worksheet.  Default is 60.  The minimum is 25.

create.numTypes

Access:  Read, Set

If specified, it determines the total number of column types.  If this is not specified, then the total number of column types is equal to the nth value in create.type.  The default is 0 and is user-assigned only (it is never set internally).

create.readOnly

Access:  Read, Set

Set the worksheet as read only.  1=enable. 0=disable.

create.template

Access:  Read, Set

Name of the worksheet template to use to create the worksheet.  Most Origin scripts use CREATE.OTW.
Example:  create.template$="Create"; will use CREATE.OTW to create the worksheet.

create.typen

Access:  Read, Set

n can be 1 to 20.  This specifies the column type for the columns created by create.wks( ).  If more columns are being created than the number of types, then the "pattern" is repeated unless typeN is specified.  Example:  Type1= 4; Type2=1:  this will make the columns X and Y repeatedly (unless TypeN is specified) until the total number of columns (specified in wks( ) method) are created.

create.typeN

Access:  Read, Set

This value is used if the number of columns being created is greater than the total number of types specified.  If typeN=0, then the rest of columns will get the same type as the first set of columns.  Default is 0.  Example:  create.type1=4; create.type2=1; create.typeN=6;  When create.wks( ) is executed, it will create one X column, one Y column, and the rest of the columns created will be Z columns.

create.wksLabel$

Access:  Read, Set

Set the label for the worksheet created with the create.wks( ) method.

create.wksName$

Access:  Read, Set

String property to specify the name of the worksheet.  After create.wks( ) is executed, it holds the name of the last worksheet created.

Methods:

create.delete(colName)

Deletes the column and the associated datasets.  If a Y column is specified, the associated X, Err, and Label columns will also be deleted.  If an X column is specified, the dependant Y columns will be deleted.  The worksheet this operates on is specified in create.wksName$.

create.reset( )

Currently not implemented.

create.wks(colName)

Create a minimized worksheet with the name set to the string stored in create.wksName$.  If colname equals an existing dataset, concatenate and truncate(if necessary) the name by removing the "_".

Examples:

The following script creates a hidden worksheet named Test1 with an X and Y column.

create.wksName$="Test";

create.enumwks=1;

//If the worksheet exists, truncate and enumerate the name of the
//next wks

create.wkslabel$="This is a test worksheet";

create.template$="CREATE";

//Use the CREATE.OTW

create.npts=30;

//Set the number of rows

create.enumerate=1;

//If the columns passed already exists, truncate and enumerate the
//newly created columns

create.numtypes=2;

//Only two types of columns will be used

create.type1=4;

//Only explicitly specify 1st type as X

create.type2=1;

//Set TypeN=Y column type

create.wks(A B);

//Create a wks named Test with X column=A and Y column=B

%A=create.data1$;

//Set %A to the first created dataset

%B=create.data2$;

// Set %B to the second created dataset

%K=create.wksname$;

//Set %K to the name of the last worksheet created


Curve

The curve object provides for the following math operations on a data plot:

Smoothing

Integration

Derivation

It also provides for baseline operations and peak selection.

The curve object is an external object.  For more information on external objects, see  External Object Overview.

Common Curve Object Properties:

curve.baselinePts

Access:  Read, Set

Number of points used in baseline creation.

curve.data$

Access:  Read, Set

Name of the Y column in the worksheet to perform the operations on.  This property must be set before performing an operation.

curve.derivDeg

Access:  Read, Set

Degree of differentiation:  0, 1, or 2.

curve.i1

Access:  Read, Set

Starting row index number of the selected range.

curve.i2

Access:  Read, Set

Ending row index number of the selected range.  When i1>0, i2 must be specified.

curve.plotName$

Access:  Read, Set

The name of the graph containing the data to be acted on by the curve object.  This property does not require setting.

curve.show

Access:  Read, Set

Display the integration area:  0=do not show, 1=show.

curve.smoothPts

Access:  Read, Set

Number of points on either side of the point to be smoothed.

curve.x0

Access:  Read

Value of X at i1.

curve.x1

Access:  Read

Value of X at i2.

curve.y0

Access:  Read

Value of Y at i1.

curve.y1

Access:  Read

Value of Y at i2.

curve.ymax

Access:  Read

Maximum value of the active dataset with respect to the baseline.

curve.ymax0

Access:  Read

Maximum value of the active dataset with respect to zero.

curve.ymax0i

Access:  Read

Row index number for ymax0.

curve.ymax0x

Access:  Read

Value of X corresponding to ymax0.

curve.ymaxi

Access:  Read

Row index number for ymax.

curve.ymaxx

Access:  Read

Value of X corresponding to ymax.

curve.ymin

Access:  Read

Minimum value of the active dataset with respect to the baseline.

curve.ymini

Access:  Read

Row index number for ymin.

curve.yminx

Access:  Read

Value of X corresponding to ymin.

Curve Object Properties Specific to Math Operations:

curve.base$

Access:  Read, Set

Name of the worksheet column that is used as a baseline.  For integration, you must set this property.  Set it to an existing dataset (curve.base$=wks_colName;) or specify the following:  (curve.base$=" ";).  When curve.base$ is set to " ", then the curve.integrate( ) method integrates from y=0.

curve.integrate.area

Access:  Read, Set

Integral.

curve.polyDeg

Access:  Read, Set

The degree of the underlying polynomial used for smoothing.  Values can range from 1 to 9.

curve.res

Access:  Read

Tolerance for deviation in X axis values.  This value is fixed at 5%.

curve.result$

Access:  Read, Set

Name of the (existing) dataset that stores the results.  This property must be set before performing the math operation.

curve.smoothLeftPts

Access:  Read, Set

The number of points on the right of the data point being smoothed when using curve.sgsmooth( ).  This property combined with curve.smoothRightPts make up the smoothing window and can not exceed 100 points.  The window can be asymmetric about a particular data point - i.e., the number of points to the left of the point of interest can be different from the number to the right.

curve.smoothRightPts

Access:  Read, Set

The number of points on the right of the data point being smoothed when using curve.sgsmooth( ).  This property combined with curve.smoothLeftPts make up the smoothing window and can not exceed 100 points.  The window can be asymmetric about a particular data point - i.e., the number of points to the left of the point of interest can be different from the number to the right.

curve.x$

Access:  Read, Set

Name of the X column to use for the math operation.

Curve Object Methods Specific to Math Operations:

curve.adjave( )

Smoothing using the adjacent averaging method.  The result is stored in curve.result$.

curve.deriv( )

Differentiate.  The result is stored in curve.result$.

curve.FFTSmooth( )

Smoothing using the Fourier transform method.  The result is stored in curve.result$.

curve.integrate( )

Integrate.  The result is stored in curve.result$.

curve.SGDeriv( )

Differentiate using the Savitzky-Golay method.  The result is stored in curve.result$.

curve.SGSmooth( )

Smoothing using the Savitzky-Golay method.  The result is stored in curve.result$.

Curve Object Properties Specific to Baseline Operations and Peak Selection:

curve.areas$

Access:  Read, Set

Worksheet column used for storing areas between base points.

curve.basex$

Access:  Read, Set

Worksheet column used for storing X coordinate for the base points.

curve.basey$

Access:  Read, Set

Worksheet column used for storing Y coordinate for the base points.

curve.centers$

Access:  Read, Set

Worksheet column used for storing the center points.

curve.halfWidths$

Access:  Read, Set

Worksheet column used for storing the half-widths.

curve.heights$

Access:  Read, Set

Worksheet column used for storing the heights.

curve.integrate.area

Access:  Read

Area under a single peak.

curve.integrate.center

Access:  Read

Center point of a single peak.

curve.integrate.halfwidth

Access:  Read

Half-width for a single peak.

curve.integrate.height

Access:  Read

Height of a single peak.

curve.markerIndex$

Access:  Read

Worksheet column used for storing the selected baseline points.

curve.maxPeakRange

Access:  Read, Set

The value of this property is used for peak picking only if curve.pickPeaks.simple=0.  Set this property to be the percentage of the total number of points in curve.data$ that the peak must not exceed in order to be recognized as a peak.  (You must also set curve.minPeakRange and curve.minHeight.)

curve.minDer

Access:  Read, Set

Minimum value of the first derivative below which a point is accepted.

curve.minHeight

Access:  Read, Set

The value of this property is used for peak picking only if curve.pickPeaks.simple=0.  Set this property to be the percentage of the total amplitude (difference between min and max values) of curve.data$ that a peak must have, to be considered a peak.  This property enables you to exclude noise when determining peaks.  (You must also set curve.minPeakRange and curve.maxPeakRange.)

curve.minPeakRange

Access:  Read, Set

The value of this property is used for peak picking only if curve.pickPeaks.simple=0.  Set this property to be the percentage of the total number of points in curve.data$ that the peak must have in order to be recognized as a peak.  (You must also set curve.maxPeakRange and curve.minHeight.)

curve.peakDirection$

Access:  Read, Set

Holds the name of the dataset that will have either a P (for positive) or an N (for negative) in the Peaks worksheet.  The indexes of the peaks will be loaded in curve.peakIndex$.

curve.peakIndex$

Access:  Read, Set

Worksheet column used for storing the index for the peak points.

curve.pickPeaks.minHeight

Access:  Read, Set

The value of this property is used for peak picking only if curve.pickPeaks.simple=1.  Set this property to be the percentage of the total amplitude (difference between min and max values) of curve.data$ that a peak must have, to be considered a peak.  This property enables you to exclude noise when determining peaks.  (You must also set curve.pickPeaks.rectHeight and curve.pickPeaks.rectWidth.)

curve.pickPeaks.rectHeight

Access:  Read, Set

The value of this property is used for peak picking only if curve.pickPeaks.simple=1.  When curve.pickPeaks.simple=1, the curve.pickPeaks( ) method uses a search rectangle for peak picking.  Curve.pickPeaks.rectHeight determines the height of the search rectangle.  Set this property to be the percentage of the difference between the maximum and minimum values in curve.data$.  (You must also set curve.pickPeaks.minHeight and curve.pickPeaks.rectWidth.)

curve.pickPeaks.rectWidth

Access:  Read, Set

The value of this property is used for peak picking only if curve.pickPeaks.simple=1.  When curve.pickPeaks.simple=1, the curve.pickPeaks( ) method uses a search rectangle for peak picking.  Curve.pickPeaks.rectWidth determines the width of the search rectangle.  Set this property to be the percentage of the total range of values in curve.data$.  (You must also set curve.pickPeaks.rectHeight and curve.pickPeaks.minHeight.)

curve.pickPeaks.simple

Access:  Read, Set

Set this property to 1 if curve.data$ does not have a definable baseline.  If curve.data$ has a definable baseline (even if irregular), then set curve.data$=0.

Curve Object Methods Specific to Baseline Operations and Peak Selection:

curve.baseline( )

Find all points that make a baseline.

curve.mrkIntegrate( )

Get the first baseline points on either side of the peak.

curve.pickPeaks( )

Get all the peak points.  The search method depends on property settings.  See curve.pickPeaks.simple, curve.maxPeakRange, curve.minHeight curve.minPeakRange, curve.pickPeaks.minHeight, curve.pickPeaks.rectHeight, curve.pickPeaks.rectWidth.

Examples:

The following script performs a differentiation using the Savitzky-Golay method.  (%Y holds the DRIVE:DIRECTORY for the ORIGIN60.INI file.)

//Open a new worksheet

win -t data Origin;

//Import sample file

open -w %YSample Data\Data with noise.dat;

//Create a column for results

wks.addcol(Result);

//Assign datasets

curve.data$=DataWithNoise_Signal;

curve.result$=DataWithNoise_Result;

curve.i1=-1;

curve.smoothpts=5;

curve.derivdeg=1;

//Perform differentiation, fill Result column of original worksheet

curve.sgderiv();

The next script performs an integration from a baseline.  (%Y holds the DRIVE:DIRECTORY for the ORIGIN60.INI file.)

//Open a new worksheet

win -t data Origin;

//Import sample file

open -w %YSample Data\Peaks with base.dat;

//Create a column for results

wks.addcol(Results);

curve.data$=PeaksWithBase_Amp;

curve.base$=PeaksWithBase_Base;

curve.result$=PeaksWithBase_Results;

//Perform integration, fill results column of original worksheet

curve.integrate();

//Send the total area to the script window

type "Area = $(curve.integrate.area)";


Doc

The doc object provides read only access to general project properties.

Properties:

doc.isNew

Access:  Read

This property has a value of 1 if the project is a new project (not loaded from a file) and has never been saved.  Once the project is saved, this property becomes 0.

doc.wksNamen$

Access:  Read

Returns the name of the nth worksheet.  n is the order in which the worksheets were created in the project (1, 2, etc.).

Examples:

If Data1 is the first worksheet created in the project, then the following (Script window) script returns Data1.

%Z=doc.wksname1$;

%Z=;


Object Reference - Alphabetical Listing of Objects - Draw
Draw

The draw object maintains properties for current settings in label object management.

Properties:

draw.auto

Access:  Read, Set

0=globally disable all object.auto properties.  For more information on the object.auto property, see  User-created Visual Objects.

draw.last$

Access:  Read, Set

Name of the last created label or named object.

draw.mode

Access:  Read, Set

1=Button Edit Mode, 0=normal mode.

draw.showProg

Access:  Read, Set

Real-time objects flash while processing data:  1=enable, 0=disable.  Mostly used with RTM objects.  For more information on RTM objects, contact Microcal Software or your Origin dealer.

Methods:

draw.get(GrpObj)

This method is the reverse of the draw.set( ) method.  Instead of updating all the properties of all the sub-objects in a tool from a source object, this method updates the source object properties from the tool sub-object property values.

GrpObj is the name of the tool containing the source sub-object property values.

The object which is updated with the tool's sub-object property values is specified by the tool sub-object's name.

The sub-object's name must start with an "_@".  It is assumed that the characters following the "_@", and before any numeric digits, are the name of the object to receive the sub-object property values.

The property values are assigned by matching the sub-object's control or label names with the object's property names.

Note:  The object's properties must be writable.

draw.set(GrpObj [, DefObj])

This method updates all the properties of all the sub-objects in a tool from a source object.

GrpObj is the name of the tool.  DefObj (optional) is the name of the default object that contains* the source values.
*The properties of the tool sub-objects are updated from one of the following source objects:

DefObj

An object specified by the sub-object's name.  If the sub-object's name starts with an "_@", then it is assumed that the characters following the "_@", and before any numeric digits, are the name of the source object to get the values from.  If the sub-object's name does not start with an "_@", then DefObj is used as the source.

The property values are assigned by matching the source object's property names with the sub-object's control or label names.

Note:  The tool's sub-object properties must be writable.

Examples:

The following script is equivalent to selecting Edit:Button Edit Mode.

draw.mode=1;


Excel

The excel object provides script access for running Excel macros and invoking Visual Basic application functions.

Methods:

excel.run(functionName,Arg1,Arg2,…,Arg5)

Run a Visual Basic application function from Origin.  You must supply the correct number of arguments with this method.  The method can accept up to five arguments.  The workbook containing the Visual Basic application function must be active.

FunctionName is the Visual Basic application function.

excel.runRange(sheetName,RangeName,Arg1,Arg2,…,Arg5)

Run a macro from Origin.  You must supply the correct number of arguments with this method.  The method can accept up to five arguments.  The workbook containing the macro must be active.

SheetName is the name of the sheet containing the macro.  Rangename is the name of the cell on the sheet where the macro starts (for example, C6).


Export

The export object provides script access for exporting graphs to graphic files.

Methods:

export.image(fileName, imageType)

This method exports the active graph to an image file.  The file name is specified in the fileName string argument.  The type of image file is specified in the imageType string argument.  For valid image type strings, see the export.image.types$ property for the export.image sub-object.


Export.Image

The image object is a sub-object of the export object.  It provides script access for the graphic export filters and filter properties.

Properties:

export.image.showDialog

Access:  Read, Set

During exporting, this property determines if a dialog box of image settings will be shown to allow the user to change image attributes.  A value of nonzero will show the dialog box and a value of zero will not show the dialog box.

export.image.types$

Access:  Read

This property is read-only and is used to get a list of all the image types currently supported.  The list contains file extensions.  Example:  "BMP EPS JPG".  The main use of this property is with the fdlog.useType( ) method.


Fdlog

The fdlog object provides for script access to Origin's Open and Save As dialog boxes.  These dialog boxes are a modification of the standard Windows dialog box that allows for a line of comments to be stored with Origin project files.  The 32 bit version of Origin running under Windows 95 allows you to choose this dialog box (@X=0 or system.explorer=0) or the standard Explorer dialog box (@X=1 or system.explorer=1).

Definitions for this object:

Extension:  The portion of text in the file name that follows the last period.  For example, BMP is the extension of the file named "MyImage.BMP".

Extension Description:  The text that appears in the Files of Type combination box in the Open and Save As dialog box.  This text is used to describe or identify the files that are named with a specific Extension.  Example:  Windows Bitmap (*.BMP)

Extension Group:  A list of Extension Descriptions.  Example:  Images

Properties:

fdlog.asReadOnly

Access:  Read

This property is used to get the check state of the "Open as read-only" check box.  The check box only appears on the dialog box displayed by the fdlog.open( ) method.

The "Open as read-only" check box will be enabled when the Files of Type is for Origin projects (.OPJ or .ORG).  When the "Files of type" is not set for Origin projects this check box will be unavailable (gray).

fdlog.checkName$

Access:  Read, Set

This property is used to show and hide an optional check box on the dialog box.  Set this property to any string to show the check box or to an empty string ("") to hide the check box.

Use the fdlog.checkStatus property to get and set the state of the optional check box.

fdlog.checkStatus

Access:  Read, Set

Get and set the state of the optional check box.  Zero indicates not selected and non-zero indicates selected.  Use the fdlog.checkName$ property to show and hide the optional check box.

fdlog.choice

Access:  Read

Get the index (starting with one) of the file type selected when the dialog box is closed.

Note:  It is recommended that the new property fdlog.defType be used instead of fdlog.choice.

fdlog.control

Access:  N/A

Not currently implemented.

fdlog.default$

Access:  Read, Set

This property is used to get and set the contents of the File Name text box in the dialog boxes displayed by the fdlog.open( ) and fdlog.saveAs( ) method.  Set this property to have a default file name appear when the dialog box opens and get this property after the dialog box closes for the name of the selected file.  This string may contain a path and a file name.  If a path is specified, then the fdlog.path$ property is set.  The File Name text box will not show the path.  Only the file name is shown.

fdlog.defType

Access:  Read, Set

This property is used to get the selected file type and set the default file type for the Files of Type combination box.  Valid values are in the range [0, fdlog.numTypes].  The value determines which fdlog.type$ is displayed in the Files of Type combination box.

There is currently a limit of 25 file types.

fdlog.defTypeExt$

Access:  Read, Set

Same as fdlog.defType except that it holds the extension of the type selected.

fdlog.dlgName$

Access:  Read, Set

Use this property to get and set the name of the dialog box.  Set to an empty string ("") to use the default names.

Dialog Method:  Open, Default Name:  Open

Dialog Method:  SaveAs, Default Name:  Save As

Dialog Method:  MultiOpen, Default Name:  Import Multiple ASCII

fdlog.expASCII

Access:  N/A

Not currently implemented.

fdlog.ext

Access:  N/A

This property is obsolete.

fdlog.message$

Access:  Read, Set

Set the text in the static control of the Multi-open dialog box.  It does not show a check box.

If fdlog.checkName$ is also set, it will supercede fdlog.message$.

fdlog.multiOpen.colView

Access:  Read, Set

The MultiOpen dialog box contains a list of the user's selected files.  By default, this list contains only the file's path and name.  With this property you can display additional file information and even enable a way for the user to specify the column designation (how to import the file) for a selected file.  This property is bit oriented and the following bits are used:

0 / 1  Show the Column Designation column.

1 / 2  Show the Template column.

2 / 4  Show the file's size.

3 / 8  Show the file's date of last modification.

fdlog.multiOpen.count

Access:  Read

After a MultiOpen dialog box closes, this property is set to the number of files selected.

This property replaces the count variable that was previously being set.

fdlog.multiOpen.sort

Access:  Read, Set

The list of user's selected files in the MultiOpen dialog box supports two types of sort.  The first type of sort is the "standard" sort, where files in the list can be sorted by file name, size etc. by clicking on the corresponding column.  This corresponds to fdlog.multiOpen.sort=0 and is the default value of the property.  fdlog.multiOpen.sort=1 specifies the second type of sort, where each group of files added is sorted within itself, but the groups are not intermixed.

fdlog.multiOpen.colToggle

Access:  Read, Set

When fdlog.checkName$ is set, this property will toggle list box columns in the MultiOpen dialog box based on the state of the check box.  It uses the same bits as fdlog.multiOpen.colView.  For example:  fdlog.multiOpen.colToggle=6 will toggle the template and the size columns.  If these columns were shown when opening the dialog box, then the first click on the check box will toggle them to not show, the next click will show them.  For example, if the template column was shown and the size column was hidden when opening the dialog box, then the first click on the check box will hide the template column and show the size column, and the next click will show the template and hide the size.

fdlog.numTypes

Access:  Read, Set

The number of extension types to appear in the Files of Type combination box.  You may set this value to decrease or increase the number of types in the active group.  This value must be in the range [0,25].  There is currently a limit of 25 file types.

fdlog.optionDlg$

Access:  Read, Set

This property is used to show and hide an Option button on the dialog box.  Currently, this is only used for the ASCII Import Options button when importing an ASCII file.  Set this property to "IMPASCII" to show the button or to an empty string ("") to hide the button.

fdlog.path$

Access:  Read, Set

This property is used to set the default path for when the dialog box opens and to get the path of the file selected when the dialog box closed.

fdlog.showComment

Access:  Read, Set

For the Open dialog box, this property is used to show and hide the Show Info check box.  The state of the Show Info check box determines if the Comments edit box is shown or hidden.

For the SaveAs dialog box, this property is used to show and hide the Comments edit box.

In both cases, the value 1 indicates show and the value 0 indicates hide.

fdlog.typen$

Access:  Read, Set

Get and set the nth file type.  These are the strings that appear in the Files of Type combination box.  The index must be in the range [1, NumTypes].  The strings must be entered in the format "[description] extension".

Example:  FDlog.Type1$ = "[Windows Bitmap (*.BMP)] *.BMP";

There is currently a limit of 25 file types.

Methods:

fdlog.addType(extType)

This method is used to create a new extension type.  The extension type must be in the format "[description] *.extension" where description is the text that appears in the Files of Type combination box and extension is the extension of the files to display.

On success, this method increments the fdlog.numTypes property.

A group can have a maximum of 25 file types.

fdlog.get(letter,n)

This method is used to get the names of the files selected in the MultiOpen dialog box.  The first argument is the string variable that will receive the name.  The second argument is the index of the selected file you want to receive the name of.  The first file has an index of one.  The number of files selected with the MultiOpen dialog box is stored in the numeric variable count.  Get returns 0 for failure and 1 for success.

fdlog.getColStr(letter,n)

This method is used to get the plot designation columns of the files selected in the MultiOpen dialog box.  The first argument is the string variable that will receive the plot designation columns.  The second argument is the index of the selected file you want to receive the plot designation columns of.  The first file has an index of one.  The number of files selected with the MultiOpen dialog box is stored in the numeric variable count.  fdlog.getColStr( ) returns 0 for failure and 1 for success.

fdlog.getTemplate(letter,n)

This method is used to get the templates of the files selected in the MultiOpen dialog box.  The first argument is the string variable that will receive the template name.  The second argument is the index of the selected file you want to receive the template name of.  The first file has an index of one.  The number of files selected with the MultiOpen dialog box is stored in the numeric variable count.  fdlog.getTemplate( ) returns 0 for failure and 1 for success.

fdlog.multiOpen( )

Display the MuliOpen dialog box.  This dialog box allows the user to select multiple files.  The default path is the path specified in the fdlog.path$ property.  The default file type is the type specified in the fdlog.defType property.

The fdlog.get( ) method is used to get the names of the selected files.  The number of files selected with the MultiOpen dialog box is stored in the numeric variable count.

fdlog.open(letter)

Display the Open dialog box.  The default path is specified in the fdlog.path$ property.  The default file type is specified in the fdlog.defType property.  This method returns zero for success or non-zero for failure.

fdlog.saveAs(letter)

Display the Save As dialog box.  The default path is specified in the fdlog.path$ property.  The default file type is specified in the fdlog.defType property.  This method returns zero for success or non-zero for failure.

fdlog.useGroup(groupName)

This method allows you to setup a dialog box using an Extension Group defined with the system.fileExt object.  The argument is the name of the group.  If successful, this method will have set the following properties:  fdlog.defType, fdlog.numTypes, fdlog.path$, and fdlog.type$.

fdlog.useType(extensions)

This method should be used when you want to use a File Extension group, but not all the File Types in the group.  You will still call UseGroup, but follow it with a call to UseType.  The argument is the list of extensions for the File Types you want to appear in the File of Type combination box.  All other file types will be removed.

For example:  If you have a group named Origin and this group contained the following types:

[Project (*.OPJ)] *.OPJ

[Old version (*.ORG)] *.ORG

[Worksheets (*.OGW)] *.OGW

[Graphs (*.OGG)] *.OGG

[Matrix (*.OGM)] *.OGM

The command fdlog.useGroup(Origin) will setup the fdlog object with the above types.  If you then call the command fdlog.useType("OPJ,ORG") the last three types will be removed.  The benefit gained from this method is that tracking will still occur.

Examples:

The following script opens the Open dialog box with *.OTP selected in the File Name text box and opens the selected graph template.

fdlog.ShowComment=0;

fdlog.UseGroup(Template);

fdlog.UseType(OTP);

if(fdlog.Open(A))

return 1;

%B=fdlog.Path$;

doc -t %B%A;

The next script opens the Open Multiple Files dialog box with *.DAT selected in the File Name text box and opens the selected ASCII files in new worksheets.

fdlog.ShowComment=0;

fdlog.UseGroup(Ascii);

fdlog.UseType(DAT);

if (fdlog.MultiOpen()!=0/0)

{

loop (ii,1,fdlog.MultiOpen.Count)

{

win -t data Origin;

FDlog.Get(A, ii);

open -w %A;

}

}


FFT

The fft object performs forward and backward (i.e., inverse) Fast Fourier Transforms.  It also handles correlation, convolution, and deconvolution functions.

The fft object is an external object.  For more information on external objects, see  External Object Overview.

More:

Fast Fourier Transforms

Correlation, Convolution, and Deconvolution Functions


Fast Fourier Transforms

Properties:

Note:  Some properties are shared by all external objects.  For a list and description of these properties, see  Common Properties and Methods.

fft.backward.fDelta

Access:  Read, Set

Sampling interval in the frequency domain to be used in backward FFT.

fft.backward.freqData$

Access:  Read, Set

Name of the sampling dataset in the frequency domain to be used in backward FFT.

fft.backward.imagData$

Access:  Read, Set

Name of the dataset for the imaginary components in the frequency domain to be used in backward FFT.

fft.backward.realData$

Access:  Read, Set

Name of the dataset for the real components in the frequency domain to be used in backward FFT.

fft.exponentSign

Access:  Read, Set

Switch the sign used in calculating FFT.

0= negative exponent for forward FFT, and positive for backward FFT.  This is the Electronic Engineering convention.

1= negative exponent for forward FFT, and positive for backward FFT.  This is the Physics convention.

fft.forward

Access:  Read, Set

(>0) for forward FFT.  Otherwise, backward FFT.

fft.forward.imagData$

Access:  Read, Set

Name of the dataset for the imaginary components in the time domain to be used in forward FFT.

fft.forward.realData$

Access:  Read, Set

Name of the dataset for the real components in the time domain to be used in forward FFT.

fft.forward.tDelta

Access:  Read, Set

Sampling interval in the time domain to be used in forward FFT.

fft.forward.timeData$

Access:  Read, Set

Name of the sampling dataset in the time domain to be used in forward FFT.

fft.nextPowerOf2

Access:  Read, Set

The next power of 2, compared to fft.size.

fft.normalize

Access:  Read, Set

(>0) to normalize FFT results.

fft.output.ampData$

Access:  Read, Set

Name of the dataset for the amplitude in the output.

fft.output.imagData$

Access:  Read, Set

Name of the dataset for the imaginary components in the output.

fft.output.interval

Access:  Read, Set

Sampling interval in the output.

fft.output.phaseData$

Access:  Read, Set

Name of the dataset for the phase (angle) in the output.

fft.output.powerData$

Access:  Read, Set

Name of the dataset for the power spectrum in the output.

fft.output.realData$

Access:  Read, Set

Name of the dataset for the real components in the output.

fft.output.samplingData$

Access:  Read, Set

Name of the sampling dataset in the output.

fft.real

Access:  Read, Set

(>0) for FFT on real numbers.

fft.resolution

Access:  Read, Set

Used when checking whether the sampling data is equally spaced.  This is the tolerance in percentage of the average spacing.

fft.shifted

Access:  Read, Set

(>0) shift the FFT results.

fft.size

Access:  Read, Set

The number of data points.

fft.spectrum

Access:  Read

1=display amplitude, 2=display power spectrum.

fft.start

Access:  Read, Set

The starting row number of the selected data for FFT.

fft.unwrap

Access:  Read, Set

(>0) unwrap the phase data.

fft.windowing

Access:  Read, Set

Window method:  1=rectangular, 2=Welch, 3=Hanning, 4=Hamming, and 5=Blackman.

Methods:

fft.backward( )

Performs backward FFT.

fft.chkres( )

Check whether the sampling data is equally spaced.  The tolerance is set by fft.resolution.

fft.forward( )

Performs forward FFT.

Return values of 0 and 1 represent the success and failure of the method.  A message also appears in the Script window when a failure occurs.

The following criteria are important for using the fft object:

All properties must be assigned before each transform.  Otherwise, the last assignments made may have an effect on the current transform.

The Time dataset always converts time to frequency in forward FFT transform, and frequency to time in backward FFT.

Inverse FFT does not calculate amplitude and phi of data.

Examples:

The following script illustrates a forward FFT.

fft.reset( );

fft.forward=1;

fft.forward.timeData$=Data1_A;

fft.forward.tdelta=Data1_A[2]-Data1_A[1];

fft.forward.realData$=Data1_B;

window -t W fft FFT1;

fft.output.samplingdata$=FFT1_Freq;

fft.output.realdata$=FFT1_Real;

fft.output.imagdata$=FFT1_Imag;

fft.output.ampdata$=FFT1_r;

fft.output.phasedata$=FFT1_Phi;

fft.output.powerdata$=FFT1_Power;

fft.real=1;

fft.normalize=1;

fft.shifted=1;

fft.windowing=1;

fft.spectrum=1;

fft.unwrap=1;

fft.forward( );


Correlation, Convolution, and Deconvolution Functions

The convolution and deconvolution functions require you to input two columns of datasets (the signal dataset and the response dataset).  The data should be formatted with numeric values.

The correlation and convolution functions output two new columns, one for "lag" or "index" variables, and one for the correlation, convolution, or deconvolution result.

Correlation Properties:

fft.corr.corrData$

Access:  Read, Set

Name of the dataset for the correlation result.

fft.corr.lagData$

Access:  Read, Set

Name of the dataset for the lag.

Convolution Properties:

fft.conv.convData$

Access:  Read, Set

Name of the dataset for the convolution result.

fft.conv.indexData$

Access:  Read, Set

Name of the dataset for the index.

Deconvolution Properties:

fft.deconv.deconvData$

Access:  Read, Set

Name of the dataset for the deconvolution result.

fft.deconv.indexData$

Access:  Read, Set

Name of the dataset for the index.

Methods:

fft.conv(signalData,responseData)

Performs a convolution of two datasets:  signalData and responseData.  Results are stored in fft.conv.convData$ and fft.conv.indexData$.

fft.corr(dataset1,dataset2)

Performs a correlation of two datasets:  dataset1 and dataset2.  If the datasets are the same, then it becomes an autocorrelation.  Results are stored in fft.corr.corrData$ and fft.corr.lagData$.

fft.deconv(signalData,responseData)

Performs a deconvolution of two datasets:  signalData and responseData.  Results are stored in fft.deconv.deconvData$ and fft.deconv.indexData$.

Examples:

The following script imports a sample data file and performs a convolution.

//Open a new worksheet

win -t data Origin;

//Import sample file

open -w %YSample Data\Data with noise.dat;

//Insert columns for results

wks.col=wks.ncols+1;

wks.insert(Index Conv);

//Response dataset must have odd number of points

//and less than half the number of points than the signal.

set DataWithNoise_Response -e 51;

fft.conv.indexdata$=DataWithNoise_Index;

fft.conv.convdata$=DataWithNoise_Conv;

fft.conv(DataWithNoise_Signal,DataWithNoise_Response);


Getpts

The getpts object is the object replacement for the getpts command.

Properties:

getpts.count

Access:  Read, Set

Contains the number of selected points.

getpts.data$

Access:  Read, Set

The name of the plotted dataset to use.

getpts.index

Access:  Read, Set

The index of the latest selected point.

getpts.indexData$

Access:  Read, Set

The dataset containing indexes.

getpts.max

Access:  Read, Set

The number of points to get.

getpts.xdata$

Access:  Read, Set

Dataset that holds each successive X position value.

getpts.ydata$

Access:  Read, Set

Dataset that holds each successive Y position value.


Ini

The ini object allows you to access any files that are formatted as INI files which include sections enclosed in square brackets and key names assigned to values.  For example:

[SectionName]

KeyName=StringOrNumber

Properties:

ini.get.fileName$

Access:  Read, Set

A string with the fileName to be accessed by the ini object.  The Origin directory is assumed if no path is specified.

ini.get.key$

Access:  N/A

This property is no longer in use.

ini.get.section$

Access:  N/A

This property is no longer in use.

ini.sectionName.keyName

Access:  Read, Set

Read or write a value in a file.  KeyNames are created if they do not exist.

Methods:

ini.check(SectionName)

Returns 0 if the sectionName exists, otherwise returns 1 and creates it.

ini.get(OGIFilename)

Link the contents of an OGI file to Origin objects.  The destination objects are determined by the OGI section names.  If a section name is prefixed with an "_@", then the name following the prefix identifies a destination object.  The section's entry names determine the properties to link.  All entries are linked.  There is no linking prefix for property names.  Section names that are not prefixed with an "_@" are skipped.

Examples:

The following script creates an additional menu level in the Origin INI file.

ini.get.filename$=Origin.ini;

ini.config.file4$=macros;

ini.config.title4$=Just Macros;

ini.config.numlevels=4;


Integ

The integration results from the integrate command are placed in the following integ object properties.

Properties:

integ.area

Access:  Read

Area of the integration.

integ.dx

Access:  Read

Half width of the peak.

integ.x0

Access:  Read

X value of y0.

integ.x1

Access:  Read

Beginning X.

integ.x2

Access:  Read

Ending X.

integ.y0

Access:  Read

Maximum height (measured from the baseline if present, otherwise measured from zero).

Examples:

The following script performs an integration from zero on the active data plot.  The integration results are printed to the Script window.

integ %C;

if (mks1>=0)

{

i1=mks1;

i2=mks2;

}

else

{

get %C -b i1;

get %C -e i2;

}

type -a "Integ of %C from zero";

type "i = $(i1) --> $(i2)";

type "x = $(integ.x1) --> $(integ.x2)";

type "Area\tPeak at\tWidth\tHeight";

type "$(integ.area)\t$(integ.x0)\t$(integ.dx)\t$(integ.y0)";


Object Reference - Alphabetical Listing of Objects - Layer
Layer

The layer object controls the appearance of the specified (or active) layer on the page.  The layer object contains the axis sub-object.  The axis object also contains sub-objects.

The layer object is a window object.  For more information on window objects, see  Window Objects.

Properties:

[winName!]layer[n].property=

WinName! is optional.  If winName! is not specified, a layer in the active window is affected.

n is the layer number.  If n is not specified, the active layer is used.

layer.3DCoor

Valid:  Graph

Access:  Read, Set

Coordinate system:  1=right-hand system, 0=left-hand system.

layer.border

Valid:  Graph

Access:  Read, Set

Layer border pattern:  0=off, 1=shadow, 2=marble, 3=white out, 4=black out.

layer.bounds.height

Valid:  N/A

Access:  N/A

Not currently implemented.

layer.bounds.left

Valid:  N/A

Access:  N/A

Not currently implemented.

layer.bounds.top

Valid:  N/A

Access:  N/A

Not currently implemented.

layer.bounds.width

Valid:  N/A

Access:  N/A

Not currently implemented.

layer.color

Valid:  Graph, Worksheet

Access:  Read, Set

Layer or worksheet heading color.  Numbers from the color list, or transparent (0).  The color function can be used, as in:  layer.color=color(blue);

layer.disp

Valid:  Graph

Access:  Read, Set

Display of column or bar graphs with zero values:  0=do not show zero-valued columns or bars as a line, 1=show zero-valued columns or bars as a line.

layer.factor

Valid:  Graph

Access:  Read, Set

Set scaling factor as on the Display tab of the layer's Plot Details dialog box.

layer.fixed

Valid:  Graph

Access:  Read, Set

Fixed factor scale of elements:  1=enable, 2=disable.  Same as on the Display tab of the layer's Plot Details dialog box.

layer.height

Valid:  Graph

Access:  Read, Set

Height of the layer frame, measured in units specified by layer.unit.

layer.include.group

Valid:  Graph, Worksheet

Access:  Read, Set

Used when the layer.include( ) method is operating on a vector.  1=group and 0=ungroup.

layer.include.useAll

Valid:  Graph, Worksheet

Access:  Read, Set

Used when adding datasets with the layer.include( ) method in a box chart.  1=disregard column designations, 0=use column designations.

layer.is3D

Valid:  Graph

Access:  Read

Returns 1 if the layer is from a 3D plot type (3D charts, 3D surfaces, and 3D wire frames).  Otherwise, returns 0.

layer.left

Valid:  Graph

Access:  Read, Set

Distance from the frame to the left edge of the page.  Measured in units specified by layer.unit.

layer.link

Valid:  Graph

Access:  Read, Set

Linked layer number, 0 if no link.

layer.name$

Valid:  Worksheet

Access:  Read, Set

The active layer name.  Useful when working with a workbook with multiple sheets.

layer.period

Valid:  N/A

Access:  N/A

This property is no longer in use.

layer.plot

Valid:  Graph

Access:  Read, Set

Active data plot number in the layer.

layer.showData

Valid:  Graph, Worksheet

Access:  Read, Set

Display of data plots and worksheet cell values:  1=show, 0=hide.

layer.showLabel

Valid:  Graph, Worksheet

Access:  Read, Set

Display of labels and other objects:  1=show, 0=hide.  Unlike objects hidden with the Visible check box in the Label Control dialog box, all labels remain selectable.

layer.showx, layer.showy

Valid:  Graph, Worksheet

Access:  Read, Set

Display of X and Y axes, and row and column headings:  1=show, 0=hide.

layer.tickL

Valid:  Graph

Access:  Read, Set

Tick length in units of .1 of a point.  When you set this property, it sets the tick length for all the ticks in the layer.  When you read this property, it returns the tick length for the first displayed X axis in the layer.

layer.tickW

Valid:  Graph

Access:  Read, Set

Tick thickness.  See layer.tickL for read and set conventions.

layer.top

Valid:  Graph

Access:  Read, Set

Distance from the frame to the top edge of the page.  Measured in units specified by layer.unit.

layer.unit

Valid:  Graph

Access:  Read, Set

Layer frame measurement units:  1=% page, 2=inches, 3=cm, 4=mm, 5=pixel, 6=points, and 7=% of linked layer.

layer.width

Valid:  Graph

Access:  Read, Set

Width of the layer frame, measured in units specified by layer.unit.

Methods:

layer.include(Dataset [,PlotType])

Dataset is the name of the dataset to be added to the active graph layer.  PlotType (optional) is the numeric value for the desired graph type.  For a list of possible PlotType values, see the Worksheet command.  If PlotType is not included, the default data plot type for the active graph window is used.

layer.include(Vector,PlotType,WksName)

Allows the use of object vectors as arguments.  An object vector is a special string array.  In Origin, the only object vector is wks.cname$ which is a read only property.  In Origin Professional, the ComboBox and ListBox objects include the object vector v.

PlotType (optional) is the numeric value for the desired graph type.  For a list of possible PlotType values, see the Worksheet command.  If PlotType is not included, the default data plot type for the active graph window is used.

WksName is the dataset source worksheet.

layer.plotxy(Xdataset,Ydataset[,PlotType])

Plot the specified X dataset and Y dataset into the active layer.  (This method only works with the active layer.)  Both datasets must come from the same worksheet.  Worksheet column designations are disregarded.  To plot the data into a specific template, include PlotType.  For the PlotType values for the graph templates, see the Worksheet command.

Examples:

The following script changes the color of layer 1 in the Graph1 window to green.

Graph1!layer1.color=color(green);

The next (Script window) script sets layer 2 of the Graph1 window active, and then types the height of the layer 2 frame to the Script window.

Graph1!page.active=2;

layer.height=;

The following script plots Data1_B as a column plot in the active layer.

Layer.include(Data1_B,203);


Layer.Axis

The axis object is a sub-object of the layer object.  The axis object also contains sub-objects:  break, grid, and label.

The axis object is a window object.  For more information on window objects, see  Window Objects.

Properties:

[winName!]Layer[n].axis.property=

WinName! is optional.  If winName! is not specified, an axis in the active graph window is affected.

n is the layer number.  If n is not specified, the active layer is used.

Axis is the axis specification:  X is the bottom X axis, X2 is the top X axis, Y is the left Y axis, Y2 is the right Y axis, Z is the front Z axis, and Z2 is the back Z axis.

layer.axis.atZero

Access:  Read, Set

Display a straight line at Y=0 for an X axis, X=0 for a Y axis:  1=show, 0=hide.

layer.axis.color

Access:  Read, Set

Axis color.  Numbers from the color list, or transparent (0).  The color function can be used, as in:
layer.x.color=color(blue);

layer.axis.decPlaces

Access:  Read, Set

Set the number of decimal places displayed in the tick labels.

layer.axis.firstTick

Access:  Read, Set

First tick value.

layer.axis.from

Access:  Read, Set

First axis scale value.

layer.axis.inc

Access:  Read, Set

Major tick increment.

layer.axis.labelSubtype

Access:  Read, Set

Tick label format:  1=decimal, 2=scientific, 3=engineering (1K), and 4=decimal (1,000).

layer.axis.labelType

Access:  Read, Set

Tick label type:  1=numeric, 2=text from dataset, etc.

layer.axis.link

Access:  Read, Set

Link type for the specified axis residing in a layer that is linked with the layern.link property.  0=no link, 1=one-to-one link.

layer.axis.majorTicks

Access:  Read, Set

Number of major ticks.  0=default number of ticks.

layer.axis.minorTicks

Access:  Read, Set

Number of minor ticks.

layer.axis.opposite

Access:  Read, Set

Line opposite the axis:  1=enable, 0=disable.

layer.axis.rescale

Access:  Read, Set

Rescale type:  1=manual, 2=normal, 3=auto, 4=fixed from, and 5=fixed to.

layer.axis.rescaleMargin

Access:  Read, Set

% of data range used to produce a margin around data.  Select Plot:Rescale to Show All to view the change.

layer.axis.reverse

Access:  Read, Set

Reverse axis direction:  1=enable, 0=disable.

layer.axis.showAxes

Access:  Read, Set

Axis and tick display:  0=hide axes, 1=show ticks on axis, 2=show ticks on opposite axis, and 3=show ticks on both axes.

layer.axis.showGrids

Access:  Read, Set

Grid display:  0=hide grids, 1=show major grids, 2=show minor grids, and 3=show both grids.

layer.axis.showLabels

Access:  Read, Set

Show tick labels on axes:  0=disable, 1=enable, 2=show the right or top labels, 3=show both top and bottom or left and right labels.

layer.axis.space

Access:  Read, Set

Same as layer.axis.type.

layer.axis.thickness

Access:  Read, Set

Width of axis in points.

layer.axis.ticks

Access:  Read, Set

Controls the major and minor ticks as follows:  0=no ticks, 1=major in, 2=major out, 4=minor in, and 8=minor out.  Numbers can be combined, so 3=major ticks in and out.

layer.axis.to

Access:  Read, Set

Last axis scale value.

layer.axis.type

Access:  Read, Set

Axis scale type:  0 or 1=linear, 2=log10, 3=probability, 4=probit, 5=reciprocal, 6=offset reciprocal, 7=logit, 8=ln, and 9=log2.

layer.axis.whiteout

Access:  Read, Set

White out around tick labels:  1=enable, 0=disable.

Examples:

The following (Script window) script types to the Script window the first value of the left Y axis in the second layer of the active window.

Layer2.y.from=

The next script sets the major ticks out and minor ticks in for the top X axis in the first layer of the Graph2 window.

Graph2!layer1.x2.ticks=6;


Layer.Axis.Break

The break object is a sub-object of the (layer) axis object.  It is also a window object.  For more information on window objects, see  Window Objects.

Properties:

[winName!]layer[n].axis.break.property=

WinName! is optional.  If winName! is not specified, an axis break in the active graph window is affected.

N is the layer number.  If n is not specified, the active layer is used.

Axis is the axis specification:  X is the bottom X axis, X2 is the top X axis, Y is the left Y axis, Y2 is the right Y axis, Z is the front Z axis, and Z2 is the back Z axis.

An axis break must exist for the following properties to be valid.

layer.axis.break.from

Access:  Read, Set

Starting axis break value.

layer.axis.break.inc

Access:  Read, Set

Major tick increment after the break.

layer.axis.break.minorTicks

Access:  Read, Set

Number of minor ticks after the break.

layer.axis.break.space

Access:  Read, Set

Logarithmic scale after axis break:  1=enable, 0=disable.

layer.axis.break.to

Access:  Read, Set

Ending axis break value.

Examples:

The following (Script window) script types to the Script window the value of the beginning of the axis break on the top X axis in layer 1 of the Graph2 window.

Graph2!.layer1.x2.break.from=

The next script checks if the bottom X axis in layer 1 of the active window has a logarithmic scale.  If so, the scale is set to logarithmic after the break.

If (layer1.x.type==2)

{

layer1.x.break.space=1;

};


Layer.Axis.Grid

The grid object is a sub-object of the (layer) axis object.  It is also a window object.  For more information on window objects, see  Window Objects.

Properties:

Grid lines can be accessed using the following syntax:

[winName!]layer[n].axis.grid.property=

WinName! is optional.  If winName! is not specified, grids in the active graph window are affected.

N is the layer number.  If n is not specified, the active layer is used.

Axis is the axis specification:  X is the bottom X axis, X2 is the top X axis, Y is the left Y axis, Y2 is the right Y axis, Z is the front Z axis, and Z2 is the back Z axis.

layer.axis.grid.majorColor

Access:  Read, Set

Major grid line color.  Numbers from the color list, or transparent (0).  The color( ) function can be used, as in:  .majorcolor=color(blue)

layer.axis.grid.majorType

Access:  Read, Set

Major grid line type number:  1=solid, 2=dash, 3=dot, etc., from the Line Type drop down list.

layer.axis.grid.majorWidth

Access:  Read, Set

Width of the major grid lines in points.

layer.axis.grid.minorColor

Access:  Read, Set

Minor grid line color.  Numbers from the color list, or transparent (0).  The color( ) function can be used, as in:  .minorcolor=color(blue)

layer.axis.grid.minorType

Access:  Read, Set

Minor grid line type number:  1=solid, 2=dash, 3=dot, etc., from the Line Type drop down list.

layer.axis.grid.minorWidth

Access:  Read, Set

Width of the minor grid lines in points.

Examples:

The following (Script window) script types to the Script window the width of the major grid lines of the X axis of layer 3 of the active window.

Layer3.x.grid.majorwidth=

The next script sets the color of the minor grid lines of the Y axis in the first layer of the Graph3 window to be purple.

Graph3!layer1.y.grid.minorcolor=color(purple);


Layer.Axis.Label

The (tick) label object is a sub-object of the (layer) axis object.  It is also a window object.  For more information on window objects, see  Window Objects.

Properties:

Tick labels can be accessed using the following syntax:

[winName!]layer[n].axis.label.property=

WinName! Is optional.  If winName! is not specified, tick labels in the active graph window are affected.

N is the layer number.  If n is not specified, the active layer is used.

Axis is the axis specification:  X is the bottom X axis, X2 is the top X axis, Y is the left Y axis, Y2 is the right Y axis, Z is the front Z axis, and Z2 is the back Z axis.

layer.axis.label.bold

Access:  Read, Set

Bold the tick labels:  1=enable, 0=disable.

layer.axis.label.color

Access:  Read, Set

Tick label color.  Numbers from the color list, or transparent (0).  The color( ) function can be used, as in:  .majorcolor=color(blue)

layer.axis.label.dataset$

Access:  Read, Set

Dataset name if the tick label is from a dataset.  To read, assign the value to a string variable.

layer.axis.label.decPlaces

Access:  Read, Set

Number of decimal points to display.  To disable, set to -1.

layer.axis.label.divideBy

Access:  Read, Set

Divide tick labels by this factor before displaying.

layer.axis.label.font

Access:  Read, Set

Font number.  Use the font( ) function, as in:  layer1.x.label.font=font(arial); to set to Arial font.

layer.axis.label.numFormat

Access:  Read, Set

Numeric display format:  1=decimal without commas, 2=scientific, 3=engineering, and 4=decimal with commas (for date).

layer.axis.label.offsetH

Access:  Read, Set

Horizontal offset from axis, in % of current font.

layer.axis.label.offsetV

Access:  Read, Set

Vertical offset from axis, in % of current font.

layer.axis.label.pre$

Access:  Read, Set

A string to display before each tick label.  To delete the prefix, set .pre$="";.

layer.axis.label.pt

Access:  Read, Set

Size of the tick labels in pts.

layer.axis.label.rotate

Access:  Read, Set

Tick label rotation, in degrees.

layer.axis.label.suf$

Access:  Read, Set

A string to display after each tick label.  To delete the suffix, set .suf$="";.

layer.axis.label.timeFormat

Access:  Read, Set

Tick label time and date format.

If layer.axis.label.type=4, 1=first selection from date format drop-down list, 2=second selection from date format drop-down list, etc.

If layer.axis.label.type=3, 1=first selection from time format drop-down list, 2=second selection from time format drop-down list, etc.

layer.axis.label.type

Access:  Read, Set

Tick label type:  1=numeric, 2=text from dataset, 3=time, 4=date, 5=month, 6=day of the week, 7=column headings, and 8=dataset indexed as tick #.

layer.axis.label.whiteout

Access:  Read, Set

Background for tick labels:  0=transparent background, 1=white background.

Examples:

The following script displays the tick labels of the left Y axis in layer 2 of the Graph1 window in scientific format.

Graph1!layer2.y.label.numformat=2;

The next script checks the tick label type of the bottom X axis of the active layer in the active window.  If the return value indicates the labels display text from a dataset, the script returns the name of the dataset to the Script window.

If (layer.x.label.type ==2)

{

%A=layer.x.label.dataset$;

%A=;

};


Layer.Plotn.BoxChart

The layer.plotn.boxchart object is a sub-object of the layer object.  It provides script access to the box chart options in the Plot Details dialog box.

The layer.plotn.boxchart object is a window object.  For more information on window objects, see  Window Objects.

Note:  Replace n with the data list number of the box chart you want to edit.

Properties:

layer.plotn.boxchart.binBegin

Access:  Read, Set

Minimum of the bin range.

layer.plotn.boxchart.binEnd

Access:  Read, Set

Maximum of the bin range.

layer.plotn.boxchart.binSize

Access:  Read, Set

Size of the bins.

layer.plotn.boxchart.boxRange

Access:  Read, Set

Box range, as in no box, SE, SD, Perc 25, 75, etc.  1=no box, 2=SE, 3=SD, etc.  See the Range drop-down list on the Plot Details Box tab.

layer.plotn.boxchart.type

Access:  Read, Set

Type of box chart, as in box, data, box and data, etc.  1=box, 2=data, 3=box and data, etc.  See the Type drop-down list on the Plot Details Box tab.

layer.plotn.boxchart.width

Access:  Read, Set

Box width, in points.


Object Reference - Alphabetical Listing of Objects - Limit
Limit

The limiting values resulting from the limit command are placed in the following limit object properties.

Properties:

limit.iMax

Access:  Read

Corresponding index for maximum Y value.

limit.iMin

Access:  Read

Corresponding index for minimum Y value.

limit.size

Access:  Read

Total size (number of points) for dataset.  If a range of dataset is used, then this property contains the size of the range.

limit.xMax

Access:  Read

Maximum X value.

limit.xMin

Access:  Read

Minimum X value.

limit.yMax

Access:  Read

Maximum Y value.

limit.yMin

Access:  Read

Minimum Y value.

Examples:

The following script gets the limits of the active dataset, and then creates a new worksheet with an X and Y dataset based on the limit object properties.

Limit %C;	//Get limits of current dataset

win -t data;	//Create a new worksheet

%(%H,1)=data(limit.xmin,limit.xmax,1);

//Set new X data to range from Xmin to Xmax in steps of 1

%(%H,2)=data(limit.ymin,limit.ymax,1);

//Set new Y data to range from Ymin to Ymax in steps of 1


Object Reference - Alphabetical Listing of Objects - LR
LR

The linear regression results from the lr command are placed in the following lr object properties.

Note 1:  For further control performing linear regression, see the stat object.

Note 2:  When you use the lr -b dataset or lr -e dataset commands to perform a linear regression on the beginning (b) or ending (e) linear region of dataset, the dataset is automatically searched for linearity, as determined by the following parameters that can be modified in the ORGSYS.CNF file:

lr.maxLRange:  The percentage of the entire data range to perform a linear regression on.  For example, when lr.maxLRange=40 (default) and dataset has 20 points, lr -b dataset performs a linear regression on the first 8 points in dataset, if these points meet the requirements of the lr.chkLinearR parameter.  Thus, if the fourth point is outside the tolerance set by lr.chkLinearR, then the lr -b dataset command would only perform a linear regression on the first three points in dataset.

lr.chkLinearR:  Sets the amount of tolerance in the automatic determination of linear segments.

Properties:

lr.a

Access:  Read

Intercept.

lr.b

Access:  Read

Slope.

lr.n

Access:  Read

Number of points used in the fitting.

lr.r

Access:  Read

Correlation coefficient.

lr.sd

Access:  Read

Standard deviation of the fit.

lr.sda

Access:  Read

Standard deviation of the intercept.

lr.sdb

Access:  Read

Standard deviation of the slope.

Examples:

The following script performs a linear fit of dataset Data1_B beginning at the first data point and continuing until the end of the linear region.  It types the resulting slope and intercept to the Script window.

Lr Data1_B;

type "Slope is $(lr.b)";

type "Intercept is $(lr.a)";


Macro

The macro object contains one property which, when inside a macro, contains the value for the number of arguments.

Properties:

macro.nArg

Access:  Read

Inside any macro, this property contains the value for the number of arguments passed to the macro.

Examples:

The following script defines a macro called TypeArgs.  If three arguments are passed to the TypeArgs macro, the macro types the three arguments to the Script window.

Def TypeArgs {

if (macro.narg!=3)

{

type "Error! You must pass 3 arguments!";

}

else

{

type "The first argument passed was %1.";

type "The second argument passed was %2.";

type "The third argument passed was %3.";

}

};

If you define the TypeArgs macro as in the previous example, and then type the following in the Script window:

TypeArgs  One;

Origin returns the following to the Script window:

Error! You must pass 3 arguments!

If you define the TypeArgs macro as in the first example, and then type the following in the Script window:

TypeArgs  One Two Three;

Origin returns the following to the Script window:

The first argument passed was One.

The second argument passed was Two.

The third argument passed was Three.


Mat

The mat object handles conversion between worksheets and matrices; mathematical operations on matrices such as inverse, transpose, and multiplication; and data preparation such as gridding for 3D and contour plotting.

The mat object is an external object.  For more information on external objects, see  External Object Overview.

Properties:

mat.exp2m.cols

Access:  Read, Set

When converting a worksheet to a matrix using the mat.exp2m( ) method, this property value controls the number of columns in the matrix.  The number of columns in the matrix is determined by the number of columns in the worksheet multiplied by this property value.

mat.expand.col

Access:  Read, Set

Column expansion factor when using the mat.expand( ) method.

mat.expand.row

Access:  Read, Set

Row expansion factor when using the mat.expand( ) method.

mat.grid.average

Access:  Read, Set

Used in correlation gridding.  Average all points in a grid unit:  1=enable, 0=disable.

mat.grid.dCluster

Access:  Read, Set

Used in correlation gridding.  When mat.grid.average is enabled, this property represents the minimum number of cluster points used in a given direction.  The maximum value allowed is 5 and the minimum is 3.

mat.grid.gcSize

Access:  Read, Set

Size of a grid unit in the X direction.  Choosing a smaller size gives better results but increases calculation time.

mat.grid.grSize

Access:  Read, Set

Size of a grid unit in the Y direction.  Choosing a smaller size gives better results but increases the calculation time.

mat.grid.maxSubpts

Access:  Read, Set

The maximum number of points (raw data or grid units) allowed in gridding.

mat.grid.maxUseAll

Access:  Read, Set

Used in correlation gridding.  When the total number of data points is less than this value, all the data points are used in gridding.  This speeds up the gridding process when the total number of points is less than 64 (default value).

mat.grid.minQuadra

Access:  Read, Set

Used in correlation gridding.  The minimum number of points used in a given direction in correlation gridding when mat.grid.average is disabled.  The maximum value is 5 and the minimum value is 3.

mat.grid.nMatCols

Access:  Read, Set

Number of columns in the matrix after gridding.

mat.grid.nMatRows

Access:  Read, Set

Number of rows in the matrix after gridding.

mat.grid.radius

Access:  Read, Set

If the distance between a data point and the gridding point is larger than this value, the contribution of this data point is set to a minimal value.

mat.grid.rule

Access:  Read, Set

Used in weighted average gridding.  This parameter determines the weight as a function of the distance between a data point and the gridding point:  1=linear, 2=power, 3=logarithmic, 4=exponential.

mat.grid.smooth

Access:  Read, Set

Used in correlation gridding.  The range is from 0 to 1.  Smaller values give smoother results.

mat.matName$

Access:  Read, Set

Name of the active matrix.  Specify the active matrix before executing a mat object method.

mat.res, mat.resolution

Access:  Read, Set

When converting a regular worksheet to a matrix, small variations in the data are allowed.  The tolerance for these variations is determined by this property.  The default value is 10, which allows up to a 10% variation in the step size in X or Y.  If you have very small variations of data, the default value may be too large (the conversion would still go through).  Likewise, if you have very large fluctuations in your data, then the default value could be too small (the conversion will fail).  Calculate a value appropriate for your data using:

(maximum variation from mean step size * 100 / mean step size)

mat.shrink.col

Access:  Read, Set

Column shrinkage factor when using the mat.shrink( ) method.

mat.shrink.row

Access:  Read, Set

Row shrinkage factor when using the mat.shrink( ) method.

mat.type

Access:  Read, Set

Used in conversion from a matrix to a worksheet in the  mat.m2xyz( ) method.  0=X column first, 1=Y column first.

mat.wksName$

Access:  Read, Set

Name of the active worksheet.

mat.xCol

Access:  Read, Set

The X column number in the worksheet.

mat.yCol

Access:  Read, Set

The Y column number in the worksheet.

mat.zCol

Access:  Read, Set

The Z column number in the worksheet.

Methods:

mat.exp2m()

Expand all columns of the active worksheet (mat.wksName$) by a factor and convert it to a matrix (mat.matName$).  The expansion factor is determined by mat.exp2m.cols.  For example, if the active worksheet has 3 columns and mat.exp2m.cols=2, the resultant matrix will have 6 columns.

mat.expand()

Expand the active matrix (mat.matName$).  The expansion factor is determined by mat.expand.row and mat.expand.col.

mat.grid(coo)

Correlation gridding.

mat.grid(ave)

Weighted average gridding.

mat.grid(check)

Check and set the consistency and validity of gridding smoothness vs. minimum points per direction.

mat.integrate( )

Integrate the matrix by starting from zero.

mat.inv( )

Inverse the active matrix (mat.matName$).

mat.m2w( )

Convert the active matrix (mat.matName$) to a worksheet (mat.wksName$) by the columns and rows directly.  The worksheet looks exactly like the original matrix, but the X Y coordinate mapping information is lost.

mat.m2xyz( )

Convert the active matrix (mat.matName$) to a worksheet (mat.wksName$).  This method creates a worksheet with X ,Y and Z columns.  The cell values of the matrix are converted to a Z column.  The corresponding X and Y column values in the worksheet are set by the X and Y coordinate mapping information in the matrix.

mat.multiply(matrix1,matrix2)

Multiply matrix1 by matrix2.  Mat.matName$ stores the name of the target matrix.  If this matrix is matrix1 or matrix2, the input matrix is overwritten.

mat.shrink()

Shrink the active matrix (mat.matName$).  The shrinkage factor is determined by mat.shrink.row and mat.shrink.col.

mat.w2m( )

Convert the active worksheet (mat.wksName$) to a matrix (mat.matName$) by the columns and rows directly.  The matrix looks exactly like the original worksheet.

mat.xyz2m( )

Convert the active worksheet (mat.wksName$) to a matrix (mat.matName$).  This method creates a matrix with cell values from the Z column.  The X and Y coordinate mapping information in the matrix is from the corresponding X and Y column values in the worksheet.

Examples:

The following script converts a matrix to a worksheet using the matrix to regular XYZ format.  The mat.type property determines the type of data transfer from the worksheet to the matrix.  When mat.type=0 or not specified (default), data copying follows the "X First" rule, i.e., the X axis of the matrix is the independent axis.  When mat.type is any integer greater than zero, data copying follows the "Y First" rule.

//Create a matrix

win -t mat;

//Set the dimensions to 10X10

matrix -ps DIM 10 10;

//Fill the cells of the matrix

(%H)=Data(1,100,1);

mat.matname$=%H;

//Create an XYZ worksheet

win -t wks xyz;

mat.wksname$=%H;

mat.type=1;

//Convert the matrix to regular XYZ format

mat.m2xyz( );

*Note:  %H is used only if the name of the window to be specified is the active window.  Otherwise, specify the name of the window enclosed in double quotes, such as "data1" and "matrix1".

The next script converts a worksheet to a matrix using the regular XYZ to matrix format.  X, Y, and Z columns for the matrix are specified within the worksheet.  The X column contains the independent data.  The Y column contains the dependent data.  The Z column contains data that are to be placed in the corresponding cells in the matrix.

mat.wksname$=%H;

mat.xcol=1;

mat.ycol=2;

mat.zcol=3;

//Create a new matrix

win -t mat;

mat.matname$=%H;

//Convert the XYZ data to a matrix

mat.xyz2m( );

*Note:  %H is used only if the name of the window to be specified is the active window.  Otherwise, specify the name of the window enclosed in double quotes, such as "data1" and "matrix1".

The following script converts a matrix to a worksheet using the column-row format.  The resultant worksheet is exactly the same as the matrix.

mat.matname$=%H;

//Create a new worksheet

win -t wks;

mat.wksname$=%H;

//Convert the matrix directly to a worksheet

mat.m2W( );

The next script converts a worksheet to a matrix by correlation gridding.

mat.grid.nmatcols=32;

mat.grid.nmatrows=32;

mat.grid.grsize=4;

mat.grid.gcsize=4;

mat.grid.average=0;

mat.grid.minquadra=3;

mat.grid.radius=2;

mat.grid.dcluster=3;

mat.grid.smooth=.8;

mat.xcol=1;

mat.ycol=2;

mat.zcol=3;

mat.wksname$=%H;

sum(wcol(mat.xcol));

xmax=sum.max;

xmin=sum.min;

limit -r xmin xmax 8;

sum(wcol(mat.ycol));

ymax=sum.max;

ymin=sum.min;

limit -r ymin ymax 8;

win -t m;

matrix -ps x xmin xmax;

matrix -ps y ymin ymax;

mat.matname$=%H;

mat.grid(coo);

*Note:  %H is used only if the name of the window to be specified is the active window.  Otherwise, specify the name of the window enclosed in double quotes, such as "data1" and "matrix1".


Object Reference - Alphabetical Listing of Objects - Menu
Menu

The menu object methods and properties are designed for menu manipulation.  They are most effective when used together with the menu command.

The effects of the menu object methods may not be immediately apparent.  It is sometimes necessary to make a different window type active before the result is visible.  Alternatively, shrink Origin to an icon, then restore the application.

Note:  Menu manipulation requires exact specification of the desired menu bar, menu, and menu commands.  For information on how to specify the active menu bar and the active menu, see the Menu command.

Properties:

menu.lastExeID

Access:  Read

Holds the ID number of the most recently executed menu command.

menu.lastID

Access:  Read

Holds the ID number of the most recently created menu command.

Methods:

menu.check(ID, num)

This method will only work for user-created menu commands.  If num=1, place a check mark next to the menu command with the specified menu ID.  If num=0, uncheck the menu command.

menu.cleanup( )

Remove all menu modifications, including those made in configuration files.  To recover configuration file modifications, select an option from Format:Menu.

menu.gray(ID, num)

Not currently implemented.

menu.itemDel(pos)

Delete the menu command at the specified pos position in the active menu.

menu.itemDelBelow(pos)

Delete the menu command at the specified pos position, and all the menu commands below it, from the active menu.

menu.rename(ID, name)

This method will only work for user-created menu commands.  Rename the menu command with the specified menu ID to the specified name.

Examples:

The following script deletes the Paste menu command and all menu commands below it in the Edit menu.

Menu -w;  	//make the Worksheet menu bar active

menu ?Ed;  	//make the Edit menu active

menu.itemDelBelow(4);

The next script creates a new menu command at the end of the Edit menu.

Menu -P; 	//make the Layout menu bar active

menu ?Ed; 	//make the Edit menu active

Menu (My List) {type -b "my list";};

// append My List menu command to the end of the Edit menu

The last script finds the ID of the most recently created menu command, and then executes the menu command.

MyId = menu.lastid;

// set the value of myID to the ID of the last menu command

menu -e myId;

// execute the menu command with ID 'myId'


Object Reference - Alphabetical Listing of Objects - NLSF
NLSF

The nlsf object performs operations on nonlinear least squares fitting.  Curve fitting from script should be handled through the this object's methods and properties.

The nlsf object is an external object.  For more information on external objects, see  External Object Overview.

Properties:

nlsf.c

Access:  Read

This is a vector value that stores values of the confidence interval for each parameter (Confidence Interval = Parameter Error * Chi-square Value).  All the elements of this vector are shown in the last column of the Parameter worksheet.  The column name is ConfInter.

nlsf.chiSqr

Access:  Read

Read the chi-square value.  This value is computed during iterations.

nlsf.cod

Access:  Read

Read the coefficient of determination (r^2 value).  The COD value is computed at the end of a round of fitting iterations.

nlsf.conf

Access:  Set

Set the confidence level value.

nlsf.confCol$

Access:  Read, Set

Same as nlsf.lconfcol$.

nlsf.constr$

Access:  Set

Set constraints to the fitting process.  If the property is not set, the fitting module defaults to no constraints.  If constraints are changed, use this property to set them again.  To clear the constraint, use an empty string, i.e., nlsf.constr$="";.  Since Origin always stores the constraints internally, this command may be necessary to clean up the memory.

nlsf.cor

Access:  Read

Read the correlation coefficient which is computed at the end of a round of iterations.

nlsf.covar$

Access:  Set

Set a matrix that is used to store the variance-covariance matrix.

nlsf.curRow

Access:  Read, Set

The current row number.  Access this number in the function scripts.  Note:  versions prior to 3.0 store this value into the system variable i.

nlsf.dataBegin

Access:  Read, Set

Set the beginning of the data range.  The actual fitting is performed only on the data within this range.  The default value is 1.  However, when fitting from the menu, the fitting module automatically searches for the data range if it was set manually, or defaults to the entire column.

nlsf.dataEnd

Access:  Read, Set

Set the end of the data range.  This value must be set if you fit from scripts, as its default value is 0.

nlsf.dataStep

Access:  Read, Set

Set the data interval, which is defined as an incremental step size when only a subset of data points are used.  This is a very useful feature when there are a large number of data points and you need a rough guess of the fit.  1=every data point is used, 2=every other data point is used, etc.  When using script for fitting, this value is defaulted to 1.  When you fit from the menu, this value is calculated so that only a limited number of data points are used.  However, you may reset its value.

nlsf.derivStep

Access:  Read, Set

Set the parameter change amount ( [image]) for calculating numeric derivatives.  A smaller value gives higher precision but may cause numeric round-off errors.  The default value is 0.005.

nlsf.dn

Access:  Read

Read the dependency of the nth parameter.

nlsf.dof

Access:  Read

Read the degree of freedom of the data and fitting function.

nlsf.en

Access:  Read

Read the standard error values of the nth parameter.

nlsf.err

Access:  Read

Read the error code (or error message number).  For more information, see the Origin User's Manual.

nlsf.fitColnum

Access:  Read

Number of columns used for fitting.

nlsf.fitData$

Access:  Read, Set

Read or set the full name(s) of the dependent variable(s).

nlsf.fitWksName$

Access:  Read

Read the name of the worksheet that contains the fitting datasets (columns).

nlsf.fType

Access:  Read

Read the internal ID of the function that is selected for fitting.

nlsf.func$

Access:  Read, Set

Set the specified function as the fitting function.  For example, nlsf.func$="gauss"; sets the Gaussian function as the fitting function.

nlsf.funcCol$

Access:  Read, Set

Set a column to store functional values.

nlsf.funcx$

Access:  Read, Set

Set a column as the X column to create datasets.  The values in this column are used as the independent variables to create a function set or confidence and prediction bands.  Refer to:  nlsf.xmode and nlsf.makecurve( ).

nlsf.isBadData

Access:  Read

Check the data:  1=enable, 0=disable.

nlsf.isBadFunc

Access:  Read

Check the function selected for fitting:  1=enable, 0=disable.

nlsf.isDialogOpen

Access:  Read, Set

Read/set the internal ID of the opened dialog box.

nlsf.keepParam

Access:  Read, Set

Show if the parameters should be saved after closing the fitting session and restored before opening:  1=enable, 0=disable.

nlsf.lb

Access:  Read, Set

This is a vector value.  For each parameter, it reads/sets the lower bound value.  These are the values that are displayed in the edit boxes in the Parameter Constraints dialog box.

nlsf.lbx

Access:  Read, Set

This is a vector value.  It reads/sets the sign of each low constraint.  Value 0 corresponds to <=, value 2 corresponds to <, …  These correspond to the button values displayed in the Parameter Constraints dialog box.

nlsf.lConfCol$

Access:  Read, Set

Set a column that is used to store the values of the lower confidence band.

nlsf.ln

Access:  Read

Read the lower confidence limit value of the nth parameter for a given confidence value (nlsf.conf).

nlsf.lPredCol$

Access:  Read, Set

Set a column that is used to store the values of the lower prediction band.

nlsf.maxDerivStep

Access:  Read, Set

The execution of fitting requires a calculation of derivatives of a selected function.  If the function is user-defined, the derivative is calculated numerically.  In this case, the maximum value of the step for the numeric derivative must be set for a "flexible (non-fixed) step" regime.  So nlsf.maxderivstep contains just this value.  For user defined functions, this value is read and set in the Derivative Delta group of the Control Parameters dialog box.

nlsf.minDerivStep

Access:  Read, Set

See nlsf.maxderivstep.  This property is for the minimum value of the step.

nlsf.msgPrompt

Access:  Read, Set

Set to suppress message prompts:  1=show all message prompts, 0=suppress all message prompts, 2=suppress parameter mutual dependency messages.

nlsf.mu

Access:  Read, Set

Set the value for diagonal magnification of the curvature matrix.  This value is very important in the Levenberg-Marquardt routine.  Its default value is 0.001.

nlsf.muMin

Access:  Read

Read the smallest MU value ever reached.

nlsf.n$

Access:  Read

This is a vector of strings.  It contains the names of all the parameters.

nlsf.names$

Access:  Read

Same as nlsf.n$.

nlsf.nConstr

Access:  Read

Read the number of constraints.  The linear constraints are parsed and translated into a matrix-vector format internally with the nlsf.nconstr as the number of linear equations.

nlsf.nConstrEff

Access:  Read

Read the number of effective constraints.  If some parameters are fixed, the fitter disables them in the constraint equations by moving them from the left side of the equations to the right side.  This may reduce the total number of equations.  As a result, the final number of linear constraint equations may be less and is denoted as nlsf.nconstreff.

nlsf.nIter

Access:  Read

Read the number of iterations that are actually performed.

nlsf.nn

Access:  Read

Read the name of the nth parameter.

nlsf.noFitCurve

Access:  N/A

Not currently implemented.  Read/set if the curve should be constructed.

nlsf.nParaVary

Access:  Read

Read the number of parameters that are allowed to vary.  Use nlsf.vn or PVn to set the nth parameter to fixed or vary.

nlsf.nPoints

Access:  Read

Read the number of data points that are actually used in the fitting.  This value is the actual value used to calculate the degree of freedom (nlsf.dof) and the chi-square value.  Because there may be bad data points or functional evaluations, this value may be less than the user-specified value.

nlsf.numDepend

Access:  Read

Read the total number of dependent variables.

nlsf.numFitSets

Access:  Read, Set

Read/set the total number of sets.

nlsf.numIndep

Access:  Read

Read the total number of independent variables.

nlsf.numReplica

Access:  Read, Set

Read/set the number of replicas.

nlsf.pasteToPlot

Access:  Read, Set

Paste results into the graph after fitting:  1=enable, 0=disable.

nlsf.pasteToScript

Access:  Read, Set

Same as nlsf.pastetoplot, but for the Script window.

nlsf.pn

Access:  Read, Set

Set or read the nth parameter values.

nlsf.predCol$

Access:  Read, Set

Same as nlsf.lpredcol$.

nlsf.singularCriterion

Access:  Read, Set

This property is applicable when the SVD (single value decomposition) method is used for the matrix inversion.  The SVD method's algorithm supposes to "ignore" (exactly, turn to 0 value = 1/element) the elements of the diagonal matrix, if these elements are very small (less than nlsf.singularcriterion).  The nlsf.singularcriterion variable contains the value that should be used as a criterion of how small the element (its relative value) is.  All elements smaller than nlsf.singularcriterion will be turned to 0 in the inverse matrix.  By default, nlsf.singularcriterion is equal to 1e-60.

nlsf.ssr

Access:  Read

Read the value of the sum of squares function SS(p).

nlsf.status

Access:  Read

0 after closing a fitting session.  1 after opening a fitting session and initializing.

nlsf.tolerance

Access:  Read, Set

Set the tolerance value to stop the iterations.  The tolerance value is a stop criterion.  The default value is 0.05.

nlsf.ub

Access:  Read, Set

Same as nlsf.lb, but for the upper bound.

nlsf.ubx

Access:  Read, Set

Same as nlsf.lbx, but for the upper bound sign.

nlsf.uConfCol$

Access:  Read, Set

Set a column that is used to store the values of the upper confidence band.

nlsf.un

Access:  Read

Read the upper confidence limit value of the nth parameter for a given confidence value (nlsf.conf).

nlsf.uPredCol$

Access:  Read, Set

Set a column that is used to store the values of the upper prediction band.

nlsf.vn

Access:  Read, Set

Set or read the nth parameter values.  Tells whether parameter n is fixed or allowed to vary during fitting:  1=vary, 0=fixed.  (You can fix a parameter using linear constraints.)

nlsf.w$

Access:  Read, Set

Set the weight column.  Weights designate the contributions from individual data points.  This designated column must exist before this operation can be performed.

nlsf.wType

Access:  Read, Set

Set weight type:  0=no weight, 1=instrumental, 2=statistical, and 3=a specified column for weighting.  In general, the default value of nlsf.wtype is 0 and there is no weight.  When error bars are plotted and the fitting is from the Fit menu, the weight is defaulted to instrumental type, using the error bars for weighting, with nlsf.wtype equal to 1.  Otherwise, this value always defaults to no weight.

nlsf.x$

Access:  Read, Set

Set the X column as the independent variable for the fitting function.  You typically have an X column to plot a dataset or a function.  This designated column must exist before this operation can be performed.  When there is no X column, Origin uses the default worksheet X values.  Set default X values using the Format:Set Worksheet X menu command.  This menu command allows you to set a start value and incremental step size for Y column plotting (or fitting) when no X column exists.

nlsf.xBegin

Access:  Read, Set

Set a start value for the curves created using the command nlsf.makecurve( ).  After a fit, you may want to create a dataset with the fitting function according to the parameters found from the fitting.  Use this command with nlsf.xpoints, nlsf.xstep, or nlsf.xend to create a function dataset.

nlsf.xEnd

Access:  Read, Set

Same as nlsf.xbegin but set the end value.

nlsf.xMode

Access:  Read, Set

This value determines how to use the independent variable X when creating a function set or confidence and prediction intervals.  Refer to the nlsf.makecurve( ) command for creating a dataset.  There are several modes:

nlsf.xmode=0:  Create the dataset according to the X values of the original Y dataset (the dataset which is used for fitting).

nlsf.xmode=1:  Create the dataset according to the given X starting value (nlsf.xbegin), the incremental step size (nlsf.xstep), and the total number of data points (nlsf.xpoints).

nlsf.xmode=2:  Create the dataset according to any given X column.  With this mode, you need to have an X column and set it using the command nlsf.funcx$="xxx".

nlsf.xmode=4:  Create the dataset according to the first and last X values of the fitting dataset.  The X values of the dataset are uniformly chosen reflecting the X-axis scale.  There are nlsf.xpoints data points for this curve.  With this mode, you must create an X column to store the X values.  Assign this column using the command nlsf.funcx$="xxx".  You also need to assign the number of data points using nlsf.xpoints.  If you want a uniform curve on the graph with a nonlinear X-axis scale, use this command.

nlsf.xmode=5:  Similar to mode 4, but create the dataset with X values starting at nlsf.xbegin and ending at nlsf.xend.  Otherwise, see the previous description.

nlsf.xPoints

Access:  Read, Set

Set the number of points for the function dataset.  Refer to nlsf.makecurve( ), nlsf.xbegin, and nlsf.xstep.

nlsf.xStep

Access:  Read, Set

Set the incremental step size for the independent variable X for the function dataset.  Refer to nlsf.make( ), nlsf.xbegin, and nlsf.xpoints.

nlsf.y$

Access:  Read, Set

Set the Y column as the dependent variable for the fitting function.  This is the dataset to be fitted.  You must have this column set before you can perform any fitting operations.  If you fit from the menu, Origin automatically sets the current active plotted dataset as the Y column, and its corresponding X column as the dependent variable (if there is an X column).  This designated column must exist before this operation can be performed.

Methods:

nlsf.begin( )

Start a fitting session.  A fitting session is defined as the duration of time in which various mathematical operations can be performed, including the most important operation, the Levenberg-Marquardt minimization or the simplex minimization.  In a fitting session, all storage space including the covariance matrix persists in the entire duration.

nlsf.category(arg)

Set the function's category.  Arg is the name of the category.  For example, nlsf.category(Exponential) sets the category to "Exponential" for the function's selection.  Arg should have the exact spelling as the nlsf category.

nlsf.control(arg)

( )  Open the NLSF dialog box at the current status.

(close)  Close the current dialog box.

(select)  Open the Select Function dialog box.

(dataset)  Open the Select Dataset dialog box.  In order to open this dialog box, you must have selected a function.

(new)  Open the Define New Function dialog box.

(edit)  Open the Edit Function dialog box.  In order to open this dialog box, you must have selected a function.

(fit)  Open the Fitting Session dialog box.  In order to open this dialog box, you must have selected a function and assigned fitting datasets.

(replicas)  Open the Replicas dialog box.  In order to open this dialog box, you must have selected a function which allows replicas, such as the Gauss function.

(simulate)  Open the Simulate Curves dialog box.  In order to open this dialog box, you must have selected a function.

(results)  Open the Generate Results dialog box.  In order to open this dialog box, you must have selected a function and assigned fitting datasets.

(init)  Open the Initializations dialog box.  In order to open this dialog box, you must have selected a function.

(after)  Open the After Fitting dialog box.  In order to open this dialog box, you must have selected a function.

(control)  Open the Control Parameters dialog box.  In order to open this dialog box, you must have selected a function.

(constraints)  Open the Parameter Constraints dialog box.  In order to open this dialog box, you must have selected a function.

nlsf.chkConstr( )

Check whether constraints are violated or not.  This method helps you determine if the constraints are self-consistent, which may be critical for smooth fitting.

nlsf.cleanUpFitData( )

Clean up all the internal objects.  This method should be called immediately before closing the fitting session.

nlsf.cmatrix(index1,index2)

Return the value of the element of the constraint's matrix with indexes (index1, index2).  Example:  nlsf.cmatrix(2,1)=; returns the value of the element that is located in the second column and first row.

nlsf.end( )

End a fitting session.  After this method, related internal storage space is destroyed.  You can start another fitting session using nlsf.begin( ).

nlsf.fit(n)

Similar to nlsf.iterate(n), except this method automatically generates a fitted curve named FitFunc_F with an X dataset named FitFunc_X.  These datasets are generated with nlsf.xPoints number of points and the X values are evenly spaced in the current X axis space.  The FitFunc datasets are not generated again if they already exist.  To open the worksheet for these datasets, use the script edit fitfunc;.

nlsf.funcVal(x)

Get the function value for a given independent value x.

nlsf.init( )

Initialize the fitting DLL and put Origin in a status that is ready to start a fitting session.  50 parameters are allocated by default.  All system variables are set to default values.

nlsf.iterate(n)

Iterate the fitting procedure for n iterations.  This is the kernel of the fitting module, in the sense that the actual fitting routines which are the Levenberg-Marquardt minimization and the corresponding constraint routines (if there are any constraints) are used to find the parameters.  If the tolerance value is satisfied, the fitter stops before the specified number of iterations are finished.  This operation can only be done within a fitting session.  If n=0, the fitter is not activated but the chi-square value as well as the fit are recalculated based on current parameters.

nlsf.make( )

Same as nlsf.makecurve( ).

nlsf.makecurve(type)

Make datasets according to the specification type.  The current implementation supports creating a function dataset, confidence bands, prediction bands, and a variance-covariance matrix.

The corresponding X values of these datasets are determined by nlsf.xmode.  These operations succeed only after you have supplied proper column names for the generated datasets.

nlsf.makecurve(func) makes a function dataset according to the fitting function, the given parameters, nlsf.xmode, nlsf.xbegin, nlsf.xend, nlsf.xstep, and nlsf.xpoints.

nlsf.makecurve(conf) makes confidence bands according to the fitting function, the given parameters, nlsf.xmode, nlsf.xbegin, nlsf.xend, nlsf.xstep, and nlsf.xpoints.  The default confidence value is 0.95, which can be changed using nlsf.conf.

nlsf.makecurve(pred) makes prediction bands according to the fitting function, the given parameters, nlsf.xmode, nlsf.xbegin, nlsf.xend, nlsf.xstep, and nlsf.xpoints.  The default confidence value is 0.95, which can be changed using nlsf.conf.

For nlsf.makecurve(func), nlsf.makecurve(conf), and nlsf.makecurve(pred), you must provide columns to store the resulting datasets and assign them using nlsf.funcCol$, nlsf.lPredCol$, and nlsf.uPredCol$.  Depending on nlsf.xmode, you may need to provide a corresponding X column (see nlsf.xmode).

nlsf.makecurve(v) creates the variance-covariance matrix.  Before you use this command, you must create a matrix and use nlsf.covar to set the matrix to store the variance-covariance matrix.

nlsf.paraConf( )

Create the confidence intervals for individual parameters.  View results using Pun for upper confidence limit of parameter n, and PLn for lower confidence limit.  Use nlsf.conf=xxx; to set the confidence level before this command.  This operation can only be done within a fitting session.

nlsf.paraRange( )

Set parameters to a region that satisfies constraints if they exist.  This method actually invokes constraint routines.

nlsf.parse( )

Parse constraints explicitly and set up related storage space for constraint operations.  Constraints must be parsed before they can be used.  The fitter checks for the constraints and calls this method internally if there are constraints and they are still not parsed.

nlsf.rsConstr( )

Not currently implemented.  This method restores the constraint's value saved after the last fitting session closing.

nlsf.setDepend(VarName,Dataset)

VarName is the variable name.  Dataset is the full dataset name.  This method sets Dataset as the variable varName.  Therefore, it has the same effect as an assignment in the Select Dataset dialog box.  For example: nlsf.setdepend(act,data1_activity)

nlsf.setIndep(VarName,Dataset)

Same as nlsf.setdepend( ) but for independent variables.

nlsf.setWeight(VarName,WVarName,Dataset)

VarName is the dependent variable name.  WVarName is the name of the weight variable related to VarName. Dataset is the full dataset name of the column to use as a weight for VarName.

nlsf.simplex(n)

Iterate to find parameters using the simplex method, according to the specified n iterations.  When parameter values are unknown at the beginning, the simplex method can be used to initialize them or to make a reasonable guess.  The simplex method typically needs more functional evaluations to reach the minimum.

nlsf.svConstr( )

Not currently implemented.  Save constraint values after closing a fitting session.

nlsf.unInit( )

Un-initialize the fitting module and free up all memory that was allocated during various fitting operations.  This method is necessary after fitting operations which use a lot of memory due to a large number of parameters and constraints.

nlsf.updateDialog( )

Update the Fitting Session dialog box.  Used during a fitting session when new values for parameters are computed and need to be displayed in the dialog box.

nlsf.varCovar(index1,index2)

Used like nlsf.cmatrix( ), but for the variance-covariance matrix.


Object Reference - Alphabetical Listing of Objects - Page
Page

A page is the base object that a window contains.  A page can be either a graph page or a worksheet page, although page object properties are most often used for a graph page.

The page object is a window object.  For more information on window objects, see  Window Objects.

Properties:

Page properties can be accessed using the following syntax:

[winName!]page.property=

WinName! is optional.  If winName! is not specified, the active window is affected.

page.active

Valid:  Graph

Access:  Read, Set

Active layer number.

page.baseColor

Valid:  Graph, Worksheet

Access:  Read, Set

Page color.  Numbers from the color list:  transparent (0).  The color( ) function can be used, as in: page.basecolor=color(blue);

page.closeBits

Valid:  Graph, Worksheet

Access:  Read, Set

Window closing behavior:  0=normal, 1=window will not close, and 2=no warning message on window close.

page.cntrlColor

Valid:  Graph

Access:  Read, Set

When the control region is displayed (page.cntrlregion=1), then page.cntrlcolor sets and reads the color of the control region using the numbers from the color list.  Set page.cntrlcolor=18 to display the control region using the graph window margin color (gray area).

page.cntrlHeight

Valid:  Graph

Access:  Read, Set

Set the height of the control region (if you want to display the control region at the top of the page).

page.cntrlRegion

Valid:  Graph

Access:  Read, Set

Set page.cntrlregion=1 to display a control region.  A control region provides a convenient location for placing tools.  Set page.contrlregion=0 to disable the display.

page.cntrlWidth

Valid:  Graph

Access:  Read, Set

Set the width of the control region (if you want to display the control region at the left of the page).

page.connect

Valid:  Graph

Access:  Read, Set

Connect missing values in line data plots:  0=enable, 1=disable.

page.dvHeight

Valid:  Graph

Access:  Read

When page.paperview=0 (viewpaper off), page.dvheight=pixel height of the page (white area).  When page.paperview=1 (viewpaper on), page.dvheight will be reduced by 2*page.dvtop.  The property value changes as the window is resized.

page.dvLeft

Valid:  Graph

Access:  Read

When page.paperview=0 (viewpaper off), page.dvleft=0.  When page.paperview=1 (viewpaper on), page.dvleft=12.  The property value changes as the window is resized.

page.dvTop

Valid:  Graph

Access:  Read

When page.paperview=0 (viewpaper off), page.dvtop=0.  When page.paperview=1 (viewpaper on), page.dvtop=9.  The property value changes as the window is resized.

page.dvWidth

Valid:  Graph

Access:  Read

When page.paperview=0 (viewpaper off), page.dvwidth=pixel width of the page (white area).  When page.paperview=1 (viewpaper on), page.dvwidth will be reduced by 2*page.dvleft.  The property value changes as the window is resized.

page.extInfo

Valid:  Worksheet

Access:  Read

Type of active worksheet window:  0=Origin worksheet, 1=Excel workbook.

page.gradColor

Valid:  Graph, Worksheet

Access:  Read, Set

When displaying the page with a gradient fill, page.gradColor determines the gradient color.  Use numbers from the color list:  transparent (0).  The color( ) function can be used, as in: page.basecolor=color(blue);

page.height

Valid:  Graph

Access:  Read, Set

Page height in pixels.

page.icons

Valid:  Graph

Access:  Read, Set

Layer icons:  1=show, 0=hide.

page.label$

Valid:  Graph, Worksheet

Access:  Set

Specify an arbitrary title for the window.  If page.title=1, this title is displayed instead of the window name.

page.layoutCntrl

Valid:  Graph, Worksheet

Access:  Read, Set

The Speed mode and View mode of all graph windows are controlled by the layout page window, if one exists:  1=enable, 0=disable.

page.layoutSpeed

Valid:  Layout page

Access:  Read, Set

The Show Picture Placeholders mode causes graph or worksheet pictures in the layout page window to be displayed as named, cross-hatched boxes:  1=enable, 0=disable.

page.maxPts

Valid:  Graph

Access:  Read, Set

Maximum number of data points to display for each data plot.  The displayed data points are evenly distributed throughout the data plot.  Increases screen display when working with large data plots.  Printing is not affected.

page.nLayers

Valid:  Graph, Worksheet

Access:  Read

Number of layers on the page.

page.nLinks

Valid:  Graph

Access:  Read

Total number of child layers on the page.

page.noClick

Valid:  Graph, Worksheet

Access:  Read, Set

Disable mouse clicking on various objects:  1=on axes and column headings, 2=on data plots and cells, 4=on labels, 8=on objects, 16=on layer frames, and 32=on tick labels.  Values are cumulative, so page.noclick=5 disables clicking on axes and labels.

page.resx

Valid:  Graph, Worksheet

Access:  Read, Set

Horizontal resolution.

page.resy

Valid:  Graph, Worksheet

Access:  Read, Set

Vertical resolution.

page.rtMaxPts

Valid:  Graph

Access:  Read, Set

Independent real-time calculation of maxpts:  0=disable and use maxpts.

page.smPlotGap

Valid:  N/A

Access:  N/A

Internal use only.

page.smPlotRev

Valid:  N/A

Access:  N/A

Internal use only.

page.speed

Valid:  N/A

Access:  N/A

Not currently implemented.

page.sysWin

Valid:  Graph, Worksheet

Access:  Read, Set

Set the window as a system window which remains open when the project is closed:  1=enable, 0=disable.

page.title

Valid:  Graph, Worksheet

Access:  Read, Set

Control the display of window names and labels:  0=display name, 1=display label, 2=display name (page.title=2 if the Rename dialog box was opened, the name was changed, and the Name radio button was selected), 3=display name and label.

page.unit

Valid:  Graph

Access:  Read, Set

Page measurement units, as on the Miscellaneous tab of the page's Plot Details dialog box:  0=inches, 1=cm, 2=mm, 3=pixels, and 4=points.

page.viewPaper

Valid:  Graph

Access:  Read, Set

Page is surrounded by background color:  1=enable, 0=disable.  The background color can be set with the System.ExtBackColor property.

page.width

Valid:  Graph

Access:  Read, Set

Page width in pixels (200 pixels/inch).

page.xnColumns

Valid:  N/A

Access:  N/A

Internal use only.

page.zoomIn, page.zoomOut, page.zoomWhole, page.zoomLayer

Valid:  Graph

Access:  Read, Set

Zoom mode:  0=zoom to page center, 1=zoom to last point clicked.

Note:  These are actually methods, not properties.  However, they are accessed as if they were properties.

Methods:

[winName!]page.method(argument)

page.dimUpdate( )

Update the active graph window to the printer setup mode.

page.getFileName(A)

Get the window label or, if there is no label, the window name into %A.  If the active window has a page.label (whether displayed or not), then the label is returned in the specified string variable.  Otherwise, the window name is returned.

page.layerNumber(layerName)

Returns the layer number of the LayerName layer.  Returns 0 if LayerName is not a valid name.  Useful when working with Excel workbooks with multiple sheets.

Note:  The active layer's name is stored in the object property layer.name$.

page.reorder(n[,m])

Layer number change.  If m is not specified, change current layer to nth position.  Otherwise, change nth layer to be the mth layer.

Caution:  If your graph includes linked layers, you should only change parent layer numbers.  Origin may still break links during the reordering process.

page.smCrossMatrix( )

Internal use only.

page.smSelfMatrix( )

Internal use only.

Examples:

The following script uses the active property to set layer 2 in the Graph1 window as the active layer.

Graph1!page.active=2;

The next script uses the reorder( ) method to change layer 1 to layer 2.  Layer 2 will move up a position to layer 1.  Use the Edit:Add & Arrange Layers menu command to physically move the positions.

Graph1!page.reorder(1,2);

The next script changes the displayed name of a window to an arbitrary title.  Any associated datasets are not renamed.  The window is script accessible using the original name, and when the window is saved, the original name is used.

Data1!page.label$=DisplayName;

Data1!page.title=1;

The last script loops over each layer in the active graph window and types the layer number to the Script window.

Loop (num,1,$(page.nlayers))

//loop from 1 to the # of layers in the page

{

type "layer number $(num)";

};


RT

The rt object stores the real-time data block for script access.  When real-time data comes into Origin, it is represented as a block with n x m cells of the same type.  n is the number of columns and m is the number of rows.  The data block can then be accessed through the rt object (the cells inside the block are not accessible).

Properties:

rt.bi

Access:  Read

i = 1 - 32.  First row of cell values.

rt.colBeg

Access:  Read

Contains the column number of the worksheet that the new block is appending from.

rt.ei

Access:  Read

i = 1 - 32.  Last row of cell values.

rt.nCols

Access:  Read

Number of columns in the block.

rt.nRows

Access:  Read

Number of rows in the block.

rt.rowBeg

Access:  Read

Contains the row number of the worksheet that the new block is appending from.

rt.update

Access:  Read, Set

Real-time events pass to labels:  1=enable, 0=disable.

When rt.update=1, real-time events pass to labels that have the Real-Time check box enabled in the associated Label Control dialog box.  Additionally, if Real-Time is selected from the label's 'Script, Run After' drop down list, the script in the Label Control dialog box is executed when a real-time event is passed to the label.


Object Reference - Alphabetical Listing of Objects - Run
Run

The run object executes script from a script file.  Origin tools use the run.section( ) method to execute sections of the appropriate *.OGS file.

Properties:

run.automate

Access:  N/A

Internal use only.  Not implemented in Origin.

Methods:

run.dialog(OGOName[,DLLObject])

General mechanism for tool launching.  OGOName is the tool OGO file name.  DLLObject is the object (existing in an external DLL) that contains source values for the tool sub-objects.  (For a full discussion of "source" and tool sub-objects, see the draw.set( ) method.

The run.dialog( ) method is equivalent to the following script:

dotool -w OGOName;

run.section(OGSName,INIT);

DLLObject.reset( );

draw.set(OGOName,DLLObject);

(Where the OGSName is named the same as OGOName.)

The run.dialog( ) method returns 0 if there is no error.  It returns 1 if there is an error.

run.file(fileName)

Execute the specified LabTalk script file.  This is the preferred mechanism for running user-defined script files (vs. using the run command).

run.section(fileName,sectionName[,arg1 arg2 arg3 arg4 arg5])

Execute the named section of the specified LabTalk script file.  Script file sections are separated by [section names].  For example, [Graph].  This method can pass up to five arguments to a section.  Arguments in the script can be referred to using the temporary string variables:  %1, %2, %3, %4, and %5.

Note:  When fileName is not included, the current running script file is assumed.  For example:  run.section( ,Init) executes a subroutine Sub1 which is included in the currently running script file.  This is a useful way to make a modular structure within a script file.

Examples:

The following script executes the script in the [SimpleFit] section of the LR.OGS file and performs a linear fit of the data in the current graph window.

run.section(lr.ogs,SimpleFit);


Object Reference - Alphabetical Listing of Objects - Sort
Sort

The sort object controls the sorting sequence, order, and range within a worksheet.

Properties:

sort.c1

Access:  Read, Set

The column number of the beginning range for sorting.  If this number is zero, then all columns in the worksheet are sorted.

sort.c2

Access:  Read, Set

The column number of the end range for sorting.  This is ignored if c1 is zero.

sort.cNamen$

Access:  Read, Set

An enumerated string specifying the sort sequence (primary, secondary, etc.) and order (ascending or descending).  The syntax is: sort.cnamen$={A|D}: ColumnName;

The space between : and ColumnName is required.  n is 1, 2, etc. for the primary, secondary, etc. sort sequence.  A for ascending order and D for descending order.  ColumnName is the name of the column.

sort.missing

Access:  Read, Set

Missing values:  0=treat missing values as the smallest values within a column, 1=treat missing values as the largest values within a column.

sort.r1

Access:  Read, Set

The row number of the beginning range for sorting.

sort.r2

Access:  Read, Set

The row number of the end range for sorting.

sort.wksName$

Access:  Read, Set

The name of the worksheet to be sorted.

Methods:

sort.rank(Dataset1,Dataset2[,n])

Dataset1 is the dataset to be ranked.  Dataset2 is the dataset that will hold the ranking results.  If n=0, rank in ascending order.  If n=1, rank in descending order.  If n is not included, rank in ascending order.  When this method is executed, Origin internally sorts Dataset1 in ascending (or descending, n=1) order.  It then finds the average rank (or row number) for each of the duplicate values.  This average value is then appended to Dataset2 in each of the corresponding duplicate cells.

sort.toggle(index)

Changes the sort order for the sequence specified by index.  Index is equivalent to n in the sort.cnamen$ property, so that index=1 for the primary sort sequence, index=2 for the secondary sort sequence, etc.

sort.wks( )

Executes the sort.

Examples:

The following script sorts all columns in the Data1 worksheet from row 3 to row 11, using column B as the primary sort column (descending) and column A as the secondary sort column (ascending).

sort.wksname$=Data1;	// For the worksheet Data1,

sort.c1=0;	// all columns,

sort.r1=3;	// from row 3 to

sort.r2=11;	// row 11,

sort.cname1$=D: B;	// using column B as the primary,
// sort in descending order,

sort.cname2$=A: A;	// and column A as the secondary,
// sort in ascending order:

sort.wks( );	// execute.

When you execute the following script, the secondary sort sequence is changed from ascending to descending.

sort.toggle(2);	// Changes the sort order for the

// secondary sorting sequence - here, changes column A from

// ascending to descending.

sort.wks( );	// execute.

The following script ranks Data1_A in descending order and places the ranking results in Data1_B.

sort.rank(data1_a,data1_b,1);


Stat

The stat object provides for the following operations:

Linear regression.

Polynomial regression.

Multiple regression.

Descriptive statistics.

The stat object is an external object.  For more information on external objects, see  External Object Overview.

Common Stat Object Properties:

stat.adrsq

Access:  Read

Adjust Coefficient of Determination (R squared).

stat.chiSqrErr

Access:  Read, Set

Multiply the error on the parameters with the reduced chi-square value.  1=enable, 0=disable.

stat.cod

Access:  Read

Coefficient of Determination (R squared).

stat.confLevel

Access:  Read, Set

Confidence level for calculating confidence and prediction limits.

stat.errBarData$

Access:  Read, Set

Name of the error bar column to be used for calculating weights.

stat.fitxData$

Access:  Read, Set

Name of the X column to be fitted.

stat.fityData$

Access:  Read, Set

Name of the Y column to be fitted.

stat.fValue

Access:  Read

F test value (MSR/MSE).

stat.lclData$

Access:  Read, Set

Name of the lower control line.

stat.lplData$

Access:  Read, Set

Name of the lower prediction line.

stat.makeX.fitnpts

Access:  Read, Set

Number of points for the fitted curve.

stat.makeX.fitX1

Access:  Read, Set

First X value to be used when making the FitX$ dataset with the MakeX( ) method.

stat.makeX.fitX2

Access:  Read, Set

Last X value to be used when making the FitX$ dataset with the MakeX( ) method.

stat.makeX.margin

Access:  Read, Set

Percent of the raw data's range, of which to extend the fit X dataset beyond.

stat.MSE

Access:  Read

Mean sum of squares of residuals.

stat.MSR

Access:  Read

Mean sum of squares due to regression.

stat.npts

Access:  Read

Number of valid data points.

stat.pvalue

Access:  Read

P-value for F test.

stat.r

Access:  Read

Correlation coefficient.

stat.resData$

Access:  Read

Name of the residual column.

stat.sd

Access:  Read

Standard deviation of the fit.

stat.SSE

Access:  Read

Residual sum of squares.

stat.SSR

Access:  Read

Sum of squares due to regression.

stat.SSTO

Access:  Read

Total sum of squares.

stat.uclData$

Access:  Read, Set

Name of the upper control line.

stat.uplData$

Access:  Read, Set

Name of the upper prediction line.

stat.wTotal

Access:  Read

Total weight.

stat.xMean

Access:  Read

Mean value of the X column.

stat.yMean

Access:  Read

Mean value of the Y column.

Common Stat Object Methods:

stat.makeX( )

Make an X dataset in fitX$ that spans from FitX1 to FitX2.

stat.name(CtrlBit,WksName_ColName,NewColNam1[,NewColNam2,...,NewColNamn])

CtrlBit is either 1 or 0.

When CtrlBit=1, concatenate WksName_ColName to WksNameColName.  This becomes the name of the new worksheet.  Scan for already existing datasets:  WksNameColName_NewColNam1, WksNameColName_NewColNam2, ..WksNameColName_NewColNamn.  If a dataset already exists, then generate a new worksheet name (WksNameColNamen, where n=1, 2, etc.) and scan again.  When no duplicate names are found, set stat.name.worksheet$ to WksNameColName or WksNameColNamen.

When CtrlBit=0, concatenate WksName_ColName to WksNameColName.  Do not search for previously existing datasets with identical names.  Set stat.name.worksheet$ to WksNameColName.

stat.reset( )

Reset all parameter values to their initial, unassigned values.

Stat Object Properties Specific to Linear Regression:

stat.lr.a

Access:  Read

Intercept.

stat.lr.ap

Access:  Read

P-value for the t test of a.

stat.lr.ase

Access:  Read

a's standard error.

stat.lr.b

Access:  Read

Slope.

stat.lr.bp

Access:  Read

P-value for the t-test of b.

stat.lr.bse

Access:  Read

b's standard error.

stat.lr.t

Access:  Read

t value corresponding to the confidence level.

Stat Object Methods Specific to Linear Regression:

stat.lr([z])

Linear regression for given datasets.  When "z" is specified, the fitting line goes through the origin.  For example:

stat.data$ = %H_B;

stat.errbardata$ = %H_C;

stat.fitxdata$ = %H_D; (optional)

stat.fitydata$ = %H_E; (optional)

stat.lr( );

Stat Object Properties Specific to Polynomial Regression:

stat.pr.a, stat.pr.b1, etc.

Access:  Read

Fitted parameters (a is the intercept).

stat.pr.ap

Access:  Read

P-value of the t-test for parameter a.

stat.pr.ase, stat.pr.bse1, etc.

Access:  Read

a and b[i]'s standard errors.

stat.pr.bp1, stat.pr.bp2, etc.

Access:  Read

P-values of the t-tests for parameters bi.

stat.pr.order

Access:  Read, Set

Order of the polynomial.

stat.pr.t

Access:  Read

t value according to the confidence level.

Stat Object Methods Specific to Polynomial Regression:

stat.pr( )

Polynomial regression for given datasets.  For example:

stat.data$ = %H_B;

stat.fitxdata$ = %H_D; (optional)

stat.fitydata$ = %H_E; (optional)

stat.pr( );

Stat Object Properties Specific to Multiple Regression:

stat.mr.a

Access:  Read

Intercept.

stat.mr.ap

Access:  Read

P-value of t-test for parameter a.

stat.mr.ase

Access:  Read

Intercept's error.

stat.mr.bestr2wks$

Access:  N/A

Internal use only.  Not implemented in Origin.

stat.mr.bi

Access:  Read

Fitting parameters (i = 1 .. 9).

stat.mr.bpi

Access:  Read

P-values of t-test for parameters bi (i = 1 ..9).

stat.mr.bsei

Access:  Read

b[i]'s errors (i = 1 .. 9).

stat.mr.NumX

Access:  Read

The total number of X columns.

stat.mr.pIn

Access:  Read

Critical P-value to enter a variable in stepwise regression.

stat.mr.pOut

Access:  Read

Critical P-value to remove a variable in stepwise regression.

stat.mr.t

Access:  Read

t value according to confidence level.

stat.mr.XDatai$

Access:  Read, Set

X column names (i = 1 ..9).

stat.mr.YData$

Access:  Read, Set

Y column name.

Stat Object Methods Specific to Multiple Regression:

stat.mr( )

Multiple regression for the given datasets.  For example:  stat.mr ( );

Stat Object Properties Specific to Descriptive Statistics:

stat.DS.ad

Access:  N/A

Not currently implemented.

stat.DS.CIL

Access:  Read

Lower confidence limit about the mean (with percentage set in stat.ds.interval).

stat.DS.CIU

Access:  Read

Upper confidence limit about the mean (with percentage set in stat.ds.interval).

stat.DS.cName1$

Access:  N/A

Not currently implemented.

stat.DS.confLev

Access:  Read, Set

Confidence level.  Set this property to load stat.ds.ciu and stat.ds.cil.

stat.DS.data$

Access:  Read, Set

Name of dataset used to calculate descriptive statistics.

stat.DS.geoMean

Access:  N/A

Not currently implemented.

stat.DS.interpolate

Access:  Read, Set

Use interpolation when finding the quartiles/percentiles.  1=enable, 0=disable.

stat.DS.kurt

Access:  Read

Kurtosis of the data.  Kurtosis measures the long-tailedness or peakedness of the distribution of a random variable relative to the normal or Gaussian distribution with the same mean and variance.

stat.DS.max

Access:  Read

Maximum of the data.

stat.DS.mean

Access:  Read

Mean value of the data.

stat.DS.medCIL

Access:  N/A

Not currently implemented.  Lower confidence limit about the median.

stat.DS.medCIU

Access:  N/A

Not currently implemented.  Lower confidence limit about the median.

stat.DS.median

Access:  Read

Median of the data.

stat.DS.min

Access:  Read

Minimum of the data.

stat.DS.missing

Access:  Read

Number of missing values in the dataset.

stat.DS.more

Access:  Read, Set

Perform advanced statistics.  1=enable, 0=disable.

stat.DS.percent

Access:  Read, Set

The percentile to calculate when stat.ds( ) is performed.  The percentile is loaded into stat.ds.percentile.

stat.DS.percentile

Access:  Read

Percentiles of the data.

stat.DS.quart75

Access:  Read

The upper quartile (75th percentile).

stat.DS.quartl25

Access:  Read

The lower quartile (75th percentile).

stat.DS.quartl50

Access:  Read

The middle quartile (75th percentile).

stat.DS.range

Access:  Read

Range of the data.

stat.DS.sd

Access:  Read

Standard deviation.

stat.DS.se

Access:  Read

Standard error of the mean.

stat.DS.size

Access:  Read

Number of data points in the dataset.

stat.DS.skew

Access:  Read

Skewness of the data.

stat.DS.ssq

Access:  Read

Sum of squares.

stat.DS.sum

Access:  Read

Sum of the data.

stat.DS.testNorm

Access:  N/A

Not currently implemented.

stat.DS.var

Access:  Read

Sample variance.

Stat Object Methods Specific to Descriptive Statistics:

stat.DS( )

Descriptive and basic statistics for given dataset.

Examples:

The following script concatenates Data1_B to Data1B.  It then seaches the project for worksheets named Data1Bn.  When the number n is found such that Data1Bn does not exist, the stat.name.worksheet$ property is set to Data1Bn.

stat.name(1,Data1_B,MyX,MyY);


Sum

The Analysis:Statistics on Columns menu command and the sum( ) function save statistics to the sum object.  When multiple columns are selected, the sum object holds the statistics from the last column.

Properties:

sum.max

Access:  Read

The maximum value in the selected dataset.

sum.mean

Access:  Read

The mean value in the selected dataset.

sum.min

Access:  Read

The minimum value in the selected dataset.

sum.n

Access:  Read

The number of points in the dataset.

sum.sd

Access:  Read

The standard deviation in the selected dataset.

sum.total

Access:  Read

The sum of all the values in the selected dataset.

Examples:

The following script uses the sum( ) function to perform statistics on data1_b.  The associated values are saved in sum object properties.  These values are printed to the Script window.

sum(data1_b);

type "max= $(sum.max)";

type "mean= $(sum.mean)";

type "min= $(sum.min)";

type "n= $(sum.n)";

type "sd= $(sum.sd)";

type "total= $(sum.total)";


System

The system object properties allow you to read and alter a variety of settings which are maintained in the OPTION.CNF file.

Note:  The system object includes the following sub-objects:  axis, copypage, dash, data display, date, dialog, display, excel, fileext, font, graph, grid, math, notes, numeric, operations, page, path, print, project, script, symbol, tick, and wks.

Properties:

system.bits

Access:  Read

The bit value of Origin.  Returns 16 or 32.

system.date

Access:  Read

The current date and time in numeric format.  Equivalent to the @D system variable.  To display the information as a date or time, use $(system.date,D#) where # is an index to the Origin date formats.  See also system.date( ).

system.debug

Access:  Read, Set

Debug mode executes LabTalk statements that begin with #!.  1=enable, 0=disable.

system.explorer

Access:  Read, Set

Controls the type of Open and Save As dialog boxes used in 32 bit Origin in Windows 95:  1=Standard Explorer dialog boxes,  0=Origin dialog boxes including a Show Info check box (and associated Comments text box).  The fdlog object controls the display of the Show Info check box.

system.extBackColor

Access:  Read, Set

Background color index, outside of page.  Default color is gray.  To set, use the color( ) function.  For example:  system.page.outColor.color(white)

To surround the page with a background color, use the page.viewpaper property.

system.level

Access:  Read

Starting menu level.

system.pageCol

Access:  Read, Set

Current page column number in worksheet printing.

system.pageRow

Access:  Read, Set

Current page row number in worksheet printing.

system.product

Access:  Read

Microcal Software product code:  0=Origin, 1=Origin Professional.

system.pureColor

Access:  Read, Set

Display control:  0=use dithered color, 1=use pure color.

system.resolution

Access:  Read

System X resolution.

system.saveControl

Access:  Read

File type to be saved:  0=project, 1=template.

system.sigDigitsL

Access:  Read, Set

Maximum number of significant digits displayed to the right of the decimal place for small numbers.  Should be specified in negative numbers, i.e. -3 specifies 3 significant digits to the right of the decimal place.

system.sigDigitsU

Access:  Read, Set

Maximum number of significant digits for large numbers.  For example, if this property is set to 4, 1234567.0 displays as 1.234 E 6.

system.templatepath

Access:  Read, Set

Not currently in use.  Use system.path.template$ instead.

system.version

Access:  Read

The version number of the Origin software.

system.winViewFSize

Access:  Read, Set

Font size scalar for display in Window View mode.  This is the same as the @W system variable.

Methods:

system.date( )

Returns the current date and time in numeric format.  To display the information as a date or time, use $(System.Date( ),D#) where # is an index to the Origin date formats.

system.loadPref([FileName])

Load Origin's preferences from the specified FileName.  If no file name is provided, then the OPTION.CNF file is used.  If "1" is specified for FileName, then the internal defaults are loaded.  The internal defaults are the values used in the event that the OPTION.CNF file doesn't exist.

system.savePref([FileName])

Save Origin's preferences to the specified FileName.  If no file name is specified, then the OPTION.CNF file is used.

Examples:

The following script displays the present date in MM/DD/YY format on an existing text label named Today.

Today.text$=$(system.date,D0);

//uses the label.text$ property


System.Axis

The axis object is a sub-object of the system object.  The axis object properties allow you to read and alter axis-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.axis.property=

system.axis.color

Access:  Read, Set

Axis color.  Numbers from the color list or set with the color( ) function.  For example:  system.axis.color(blue);

system.axis.oldDialog

Access:  Read, Set

Use pre-version 5.0 axis dialog boxes.  1=enable, 0=disable.

system.axis.width

Access:  Read, Set

Axis width in points.

system.axis.useUpdateDlg

Access:  Read, Set

Control the display of the Apply To dialog box that opens when switching the active axis in the Axis dialog box.  1=display Apply To dialog box, 0=do not display Apply To dialog box (changes are made automatically when switching axes in the Axis dialog box).


System.CopyPage

The copypage object is a sub-object of the system object.  The copypage object properties allow you to read and alter copy page and graphic export-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.copypage.property=

system.copyPage.clipBorderW

Access:  Read, Set

ClipBorderW and Closeness are related properties.  Both properties affect the amount of the page in the graph window that is copied or exported.  By default, all the objects within a "bounding box" plus a "border" are copied/exported.  ClipBorderW allows you to set a value for the "border" around the "bounding box".  This value is the percent of the width of the "bounding box".  The default value is 6.  Enable or disable the "border" with the closeness property.  (See the Examples section.)

system.copyPage.closeness

Access:  Read, Set

Closeness and ClipBorderW are related properties.  Both properties affect the amount of the page in the graph window that is copied or exported.

When closeness=1 (default), copy/export the page within the "bounding box" plus add the "border" set by clipBorderW.

When closeness=2, copy/export only the page within the "bounding box".

When closeness=4, copy/export the entire graph page.

(See the Examples section.)

system.copyPage.preview

Access:  Read, Set

Printer driver used when copying/exporting the page.

1=Use the current printer driver, regardless of the current view mode.

0=Use the driver applicable to the current view mode.  All view modes except Print View use the screen driver.  Print View uses the printer driver.  Character positioning is superior using the printer driver, however, a Postscript driver can take longer to generate the image.

system.copyPage.ratio

Access:  Read, Set

Size of the copied/exported page when pasted/inserted into another application.  Specify as a percent of the page size in Origin.  Set to 100 for 100%, etc.

system.copyPage.redraw

Access:  Read, Set

Redraw the page after copying/exporting:  1=enable, 0=disable.

Examples:

The following script sets the border around the graph page "bounding box" to 10% of the bounding box width.  It then sets the Copy Page and File:Export Page menu commands to copy/export the bounding box plus the border when selected.

system.copypage.clipborderw=10;

system.copypage.closeness=1;


System.Dash

The dash object is a sub-object of the system object.  The dash object properties allow you to read and alter dash line-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.dash.property=

system.dash.definen$

Access:  Read, Set

Set the dash definition for line, line+symbol, and scatter graphs.  Corresponds to the dash line types in the Plot Details dialog box.

system.dash.hatchGap

Access:  Read, Set

The gap between hatch lines in a column or bar data plot or hatch-filled object.  Units in 1/10 of a millimeter.  To display the default Windows hatch lines, set system.dash.hatchGap=0.

system.dash.hatchWidth

Access:  Read, Set

Width of hatch lines in a column or bar data plot or hatch-filled object.  If system.dash.hatchWidth=1, use 1 pixel black lines to draw the hatch lines.

If system.dash.hatchWidth=0, use the same line style as the border of the box.

system.dash.scaleByWidth

Access:  Read, Set

Scale the dash pattern according to the line width:  1=enable, 0=disable.  When disabled, the dash pattern is the same for all line widths.

system.dash.softInPgView

Access:  Read, Set

Source for dashed line:  1=use Origin's dashed line, 0=use the device driver's dashed line.


System.DataDisplay

The dataDisplay object is a sub-object of the system object.  The dataDisplay object properties allow you to read and alter Data Display tool settings.

Properties:

system.dataDisplay.property=

system.dataDisplay.autoFit

Access:  Read, Set

Automatically display all text in the Data Display tool, independent of the tool's size.  1=enable, 0=disable.  When autofit=0, the display of text with in the tool is controlled by the resize property.

system.dataDisplay.bkgColor

Access:  Read, Set

Background color of the Data Display tool.  Numbers from the color list or set with the color( ) function.

system.dataDisplay.docking

Access:  Read, Set

Control the Data Display tool's view:  1=enable docking view, 0=disable docking view.  If docking view is enabled, the tool can be docked on the edge of the workspace.

system.dataDisplay.font$

Access:  Read, Set

Name of font used for text display in the Data Display tool.

system.dataDisplay.resize

Access:  Read, Set

Control the display of the Data Display tool's text when autofit=0.

0=fix the size of the tool's text to the current size.

1=fix the size of the tool's text so that all the text displays within the horizontal constraints.

2=fix the size of the tool's text so that all the text displays within the vertical constraints.

system.dataDisplay.textColor

Access:  Read, Set

Text color for the Data Display tool.  Numbers from the color list or set with the color( ) function.


System.Date

The date object is a sub-object of the system object.  The date object property allows you to read and alter the default custom date formats.  This setting can also be accessed in the Options dialog box.

Properties:

system.date.property=

system.date.customFormat1$

Access:  Read, Set

Read or set the first custom date format.  Two custom date formats are available at the bottom of the Date Format drop-down list in the Worksheet Column Format dialog box.

system.date.customFormat2$

Access:  Read, Set

Read or set the second custom date format.  See system.date.customFormat1$.


System.Dialog

The dialog object is a sub-object of the system object.  The dialog object properties allow you to read and alter Options dialog box opening and closing settings which are set in the OPTION.CNF file.  These settings can also be accessed with in the Options dialog box.

Properties:

system.dialog.property=

system.dialog.activePageNum

Access:  Read, Set

Set the active tab on the Options dialog box.  1=File Locations, 2=Axis, 3=Graph, 4=Text Fonts, 5=Page, 6=Miscellaneous, 7=Excel, 8=Open/Close, and 9=Numeric Format.

system.dialog.closePrompt

Access:  Read, Set

Control the display of the "Save as Origin's startup options?" prompt after making changes and closing the Options dialog box.  1=display prompt, 0=do not display prompt.

system.dialog.saveOnClose

Access:  Read, Set

If the ClosePrompt property =0, then this property is active.  Automatically save settings in the Options dialog box to the OPTION.CNF file.  1=enable, 0=disable.


System.Display

The display object is a sub-object of the system object.  The display object properties allow you to read and alter display-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.display.property=

system.display.balloonHelp

Access:  Read, Set

Display balloon help:  1=enable, 0=disable.

To view balloon help, hold the mouse pointer over a toolbar button or tool element.

system.display.noWinUpdate

Access:  Read, Set

Do not update the window if it is more than noWinUpdate% covered by another window(s).

system.display.pasteMeta

Access:  Read, Set

Paste the Clipboard image as a bitmap or a metafile.  1=metafile, 0=bitmap.

system.display.selBlink

Access:  Read, Set

Control the blinking of the axis or tick labels when they are double-clicked.

1=enable blink, 0=disable blink.

system.display.wksGridNoShow

Access:  Read, Set

Available for video displays that don't draw the worksheet grids correctly.  1=enable, 0=disable.


System.Excel

The excel object is a sub-object of the system object.  The excel object properties allow you to read and alter settings related to using Excel in Origin, which are set in the OPTION.CNF file.  Most of these settings can also be accessed in the Options dialog box.

Properties:

system.excel.property=

system.excel.closeAfterPlot

Access:  Read, Set

Close the Select Data for Plotting dialog box after plotting the workbook data.  1=close the dialog box, 0=do not close the dialog box.

The Select Data for Plotting dialog box is only available when dlgPlot=0.

system.excel.dlgPlot

Access:  Read, Set

Plot by highlighting workbook data and assuming column designations appropriate to a selected graph type.  1=enable, 0=disable.

system.excel.dragDropPlot

Access:  Read, Set

Drag-and-drop plot method for adding workbook data (and Origin worksheet data) to an existing graph.  1=line, 2=scatter, 3=line+symbol, and 4=current data plot style holder.

system.excel.legendTxtSel

Access:  Read, Set

Automatically search the workbook for legend text.  Origin searches for text in the cell immediately above the cell that contains the first Y data values, and then continues to search upward in the workbook.  1=enable, 0=disable.

system.excel.openAsExcel

Access:  Read, Set

Control the selection in the Open Excel dialog box (when openAsPrompt=1).  1=open as Excel workbook, 0=open as Origin worksheet.

system.excel.openAsPrompt

Access:  Read, Set

Display the Open Excel dialog box after selecting File:Open Excel.  This dialog box determines how Excel files are opened in Origin (as workbooks or as Origin worksheets).  1=enable opening dialog box, 0=disable opening dialog box and always open as a workbook.

system.excel.plotMulti

Access:  Read, Set

When selecting multiple datasets for plotting in the Select Data for Plotting dialog box, control the display of the data plots.  0=plot all data into single layer graph, 1=plot each data plot into its own layer of the same graph window, 2=plot each data plot into its own graph window.

system.excel.saveAsExcel

Access:  Read, Set

Control how internal and external Excel workbooks are saved when you save the associated project.  0=do not open the Save Excel Workbooks dialog box.  External workbooks are automatically updated when the associated project is saved.  1=Open the Save Excel Workbooks dialog box when you select File:Save Project or click the Save button on the Standard toolbar.  2=Open the Save Excel Workbooks dialog box when you select File:Save Project As.


System.FileExt

The fileExt object is a sub-object of the system object.  The fileExt object property allows you to read and alter the file extension, file location, and file tracking settings, which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Definitions for this object:

Extension:  The portion of text in the file name that follows the last period.  For example, BMP is the extension of the file named "MyImage.BMP".

Extension Description:  The text that appears in the Files of Type combination box in the Open and Save As dialog box.  This text is used to describe or identify the files that are named with a specific Extension.  Example:  Windows Bitmap (*.BMP)

Extension Group:  A list of Extension Descriptions.  Example:  Images

Properties:

system.fileExt.property=

system.fileExt.activeGroup

Access:  Read, Set

This property returns the index of the group that is currently active.  If there are no groups, then this property will return zero.  You can change the active group by setting this property to the index of the group you want to make active.  Values used for setting this property must be in the range [1, numGroups].  Setting this property will be ignored when there are no groups.

system.fileExt.activeGroup$

Access:  Read, Set

This property returns the name of the group that is currently active.  If there are no groups, then this property will return an empty string ("").  You can change the active group by setting this property to the name of the group you want to make active.  Setting this property will be ignored when there are no groups.

This property and the Name$ property will always return the same value.

system.fileExt.defASCII$

Access:  Read, Set

This property is used for getting and setting the default extension to be appended to ASCII files when an extension is not specified by the user.

system.fileExt.defPath$

Access:  Read, Set

This property is used for getting and setting the default path for the file types of the active group.

system.fileExt.defType

Access:  Read, Set

The extension type used by default in the Files of Type combination box in the file dialog box.  This value must be in the range [1, numTypes].

system.fileExt.name$

Access:  Read, Set

The name of the active group.  Setting this property allows you to rename the active group.

The Name$ and ActiveGroup$ properties always return the same value.

system.fileExt.numGroups

Access:  Read, Set

The number of extension groups currently defined.  You can set this value to decrease or increase the number of groups to be handled by the System.FileExt object.  While increasing NumGroups is a way to add more groups, it is highly recommended that you use the AddGroup( ) method instead.

system.fileExt.numTypes

Access:  Read, Set

The number of extension types in the active group.  You can set this value to decrease or increase the number of types in the active group.  This value must be in the range [0,25].  While increasing NumTypes is a way to add more types, it is highly recommended that you use the AddType( ) method instead.

system.fileExt.tracking

Access:  Read, Set

Tracking default file paths:  0=no tracking, 1=track within an Origin session, 3=use settings that are current when you exit Origin as the default settings when you restart Origin.

system.fileExt.typen$

Access:  Read, Set

This array property is used for getting and setting the nth extension type for the active group.  The index must be in the range (1, NumTypes).

The extension type must be in the format "[description] *.extension" where description is the text that appears in the Files of Type combination box and extension is used to determine what files are displayed.

Methods:

system.fileExt.addGroup(groupName)

Add (create) a new File Extension group.  groupName is the name that will be used to identify the group and the types of files it will contain.  Each group name must be unique.  On success, the added group becomes the active group and the NumGroups property is incremented.

Return value is zero for success and non-zero for error.

system.fileExt.addType(extensionType)

Add (create) a new Extension type.  extensionType is the Extension type string.  The string must be in the format:  "[description] *.extension"
where description is the text displayed in the Files of Type combination box and extension is the extension of the files to display in the file list box.  On success, the NumTypes property is incremented.

Return value is zero for success and non-zero for error.

system.fileExt.delGroup(groupName|groupIndex)

Delete a File Extension group by name or index.  On success the NumGroups property is decremented.

Return value is zero for success and non-zero for error.

system.fileExt.reset( )

Delete all File Extension groups.  Numeric properties are set to zero and string properties are set to blank ("").

Return value is always zero.


System.Font

The font object is a sub-object of the system object.  The font object properties allow you to read and alter font-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.font.property=

system.font.default$

Access:  Read, Set

Font to be used when Default is selected from the font drop down list in the Text Control dialog box.

system.font.greekName$

Access:  Read, Set

Name of font to use for Greek characters in text labels.

system.font.labelColor

Access:  Read, Set

Default text label color.  Numbers from the color list or set with the color( ) function.

system.font.labelName$

Access:  Read, Set

Name of font to use for a text label's default font.

system.font.labelSize

Access:  Read, Set

Text label default font size.

system.font.lineSpace

Access:  Read, Set

The space between two lines of text in a text label, in percent of the currently selected font size.

system.font.pageViewAccurate

Access:  Read, Set

Use the printer driver to display the text labels in the graph window when Page View is selected.  1=enable, 0=disable.

system.font.subOffset

Access:  Read, Set

Position of subscript, in percent of the currently selected font size.

system.font.subSize

Access:  Read, Set

Subscript and superscript font size, in percent of the currently selected font size.

system.font.supOffset

Access:  Read, Set

Position of superscript, in percent of the currently selected font size.

system.font.tabSize

Access:  Read

Set the number of characters for the tab size in the Results Log.


System.Graph

The graph object is a sub-object of the system object.  The graph object properties allow you to read and alter graph-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.graph.property=

system.graph.barShowZero

Access:  Read, Set

Display a line at Y=0 (X=0) for zero values in a bar (column) graph:  1=enable, 0=disable.

system.graph.bisectionPts

Access:  Read, Set

Set the threshold to begin using a bisection search.  Origin uses a bisection search when using the Data Reader tool or double-clicking on a data plot.

system.graph.closePrompt

Access:  Read, Set

Display a prompt when closing a graph window:  0=hide only, 1=display prompt, 2=delete without prompt.

system.graph.closeLayPrt

Access:  Read, Set

Display a prompt when closing a layout page window:  0=hide only, 1=display prompt, 2=delete without prompt.

system.graph.displayChar

Access:  Read, Set

Display characters in the symbol gallery in the Plot Details dialog box.

system.graph.fillColor

Access:  Read, Set

Fill color that displays when Automatic is selected from Fill Color drop-down list.  Numbers from the color list or set with the color( ) function.

system.graph.log1IsFloor

Access:  Read, Set

Establish Y=1 as the "floor", or the Y value which alters the direction of column/bar graphs displayed on a logarithmic scale.  1=enable, 0=disable.

system.graph.percInterp

Access:  Read, Set

Percentile calculation for interpolation:  1=enable, 0=disable.


System.Grid

The grid object is a sub-object of the system object.  The grid object properties allow you to read and alter grid-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Note:  These grid-related properties only affect graph windows that are not created from a template.  If a graph window is created from a template, the template properties take precedence over the grid object properties.

Properties:

system.grid.property=

system.grid.majorColor

Access:  Read, Set

Major grid line color.  Numbers from the color list, or transparent (0).  The color( ) function can be used, as in:  .majorColor=color(blue)

system.grid.majorType

Access:  Read, Set

Major grid line type number:  1=solid, 2=dash, 3=dot, etc., from the Line Type drop down list.

system.grid.majorWidth

Access:  Read, Set

Width of the major grid lines in points.

system.grid.minorColor

Access:  Read, Set

Minor grid line color.  Numbers from the color list, or transparent (0).  The color( ) function can be used, as in:  .minorColor=color(blue)

system.grid.minorType

Access:  Read, Set

Minor grid line type number:  1=solid, 2=dash, 3=dot, etc., from the Line Type drop down list.

system.grid.minorWidth

Access:  Read, Set

Width of the minor grid lines in points.


System.Math

The math object is a sub-object of the system object.  The math object property allows you to read and alter the angular unit setting which is set in the OPTION.CNF file.  This setting can also be accessed in the Options dialog box.

Properties:

system.math.property=

system.math.angularUnits

Access:  Read, Set

Angular units:  0=radian, 1=degree, 2=grad.

Examples:

The following script prints a warning to an Attention box if radians are not being used as the angular units.

if (system.math.AngularUnits!=0)

{

type -b "Warning: units are not radians!" ;

};


System.Notes

The notes object is a sub-object of the system object.

To create a Notes window, see the window command.  To redirect output to the Notes window, see the type object.

Properties:

system.notes.property=

system.notes.closePrompt

Access:  Read, Set

Display a prompt when closing a notes window:  0=hide only, 1=display prompt, 2=delete without prompt.

system.notes.created$

Access:  Read

Returns the name of the last created Notes window.

system.notes.sizeCols

Access:  Read, Set

Default width of the notes window in characters.

system.notes.sizeRows

Access:  Read, Set

Default height of the notes window in characters.


System.Numeric

The numeric object is a sub-object of the system object.  The numeric object properties allow you to read and alter numeric settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.numeric.property=

system.numeric.numDecDigits

Access:  Read, Set

Number of digits displayed after the decimal point.  Data values that exceed this number are rounded off.  However, the actual values are used in calculations.

system.numeric.separators

Access:  Read, Set

Numeric separator for data display:  0=Windows Settings, 1=1,000.0, 2=1.000,0, 3=1 000,0, and 4=1'000.0.

system.numeric.sigDigitsL

Access:  Read, Set

Lower threshold for conversion from decimal to scientific notation.

system.numeric.sigDigitsU

Access:  Read, Set

Upper threshold for conversion from decimal to scientific notation.


System.Operations

The operations object is a sub-object of the system object.  The operations object properties allow you to read and alter a toolbar spacer setting and an OLE in-place activation setting which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.operations.property=

system.operations.inPlace

Access:  Read, Set

Use OLE in-place activation when editing an Origin object that is embedded in a destination application.

Note:  Microcal Software does not recommend using in-place activation to edit objects.

system.operations.useSpacer

Access:  Read, Set

Display a toolbar spacer below the menu bar.  The toolbar spacer ensures that the toolbar area remains at a fixed width when changing the active child window.  1=enable display, 0=disable display.


System.Page

The page object is a sub-object of the system object.  The page object properties allow you to read and alter axis and object grid-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.page.property=

system.page.axisSpacing

Access:  Read, Set

Set the spacing of the axis grid lines.  The grid sizes are in 1/1000 of the page width.

system.page.objSpacing

Access:  Read, Set

Set the spacing of the object grid lines.  The grid sizes are in 1/1000 of the page width.


System.Path

The path object is a sub-object of the system object.  The path object is provided for backward compatibility only.  For information on this object, see your Origin 5 LabTalk documentation.  For new scripts, use the system.fileExt object.


System.Print

The print object is a sub-object of the system object.  The print object properties allow you to read and alter print-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.print.property=

system.print.fontBaseline

Access:  Read, Set

Align the bottom of the letters and symbols in a line of a text label.  1=enable, 0=disable.

system.print.keepDevColor

Access:  Read, Set

Print non-white colors on a gray scale when printing to a black and white printer.  1=enable, 0=disable.

system.print.landscape

Access:  Read, Set

Page orientation for printing worksheets or matrices.  2=landscape, 1=portrait.

Note:  The graph template setting takes precedence over this property setting.

system.print.maxPlotPoints

Access:  Read, Set

The number of data points displayed in a graph printout when skipPlotPoint=1.

system.print.printControl

Access:  Read, Set

Page numbers currently being printed.

system.print.skipPlotPoint

Access:  Read, Set

Control the number of data points displayed in the printed graph.  1=enable, 0=disable.  When enabled, Origin prints maxPlotPoints data points in the printout.

system.print.XscaleFactor

Access:  Read, Set

X scale adjustment for printing.  Control this property if your printed graph is not the exact scale set on the Size/Speed tab of the layer's Plot Details dialog box.  For example, if you specify a width of 6 inches, and the graph prints 6.0625 inches wide, set system.print.XscaleFactor=1010 (because (6.0625*1000)/6=1010).

system.print.YscaleFactor

Access:  Read, Set

Y scale adjustment for printing.  See system.print.XscaleFactor.

Examples:

The following script checks the landscape property and types the printer orientation to the Script window.

if (system.print.landscape==2)

type "The printer is in Landscape mode.";

else

type "The printer is in Portrait mode.";


System.Project

The project object is a sub-object of the system object.  The project object properties allow you to create project file backups and to control the child window that displays when you open a new project.  Both options are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.project.property=

system.project.backup

Access:  Read, Set

Backup the project file to BACKUP.OPJ (in the Origin directory) before saving:  1=enable, 0=disable.

system.project.iconizedAsHidden

Access:  Read, Set

Control how windows that are saved as minimized in pre-version 6 projects open in Origin 6:  0=hidden, 1=minimized, 2=prompt.

system.project.showInDataList

Access:  Read, Set

Show datasets from worksheets in nonactive Project Explorer folder in Layer n dialog box data list:  1=show, 0=don't show.

system.project.showInNLSFDataList

Access:  Read, Set

Show datasets from worksheets in nonactive Project Explorer folder in NLSF Select Dataset dialog box:  1=show, 0=don't show.

system.project.startup

Access:  Read, Set

Select the child window or project you want to display when you open a new project.  1=worksheet, 2=Excel workbook, 3=graph, 4=matrix, 5=project (worksheet and graph), and 6=none.

system.project.startupPEViewMode

Access:  Read, Set

Control how the workspace view is effected by the Project Explorer folder selection:  0=show only windows in active Project Explorer folder, 1=show windows in active folder and subfolders, 2=don't show any windows.


System.Script

The script object is a sub-object of the system object.  The script object property allows you to control a Script window setting which is set in the OPTION.CNF file.  This setting can also be accessed in the Options dialog box.

Properties:

system.script.property=

system.script.closePrompt

Access:  Read, Set

Display a prompt when closing the Script window:  1=enable, 0=disable.


System.Symbol

The symbol object is a sub-object of the system object.  The symbol object properties allow you to read and alter symbol-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.symbol.property=

system.symbol.borderWidth

Access:  Read, Set

Control the border width of hollow or open symbols in a scatter or line and symbol data plot.  Set to n to set the width of the symbol border to n% of the symbol's half diameter.

system.symbol.lineGap

Access:  Read, Set

Control the line and symbol gap on a line and symbol data plot.  Set to n to set the line and symbol gap to n% of the symbol diameter.  0=no gap.  Maximum allowable value is 256.  Note:  To display the line and symbol gap, enable the associated check box in the data plot's Plot Details dialog box.


System.Tick

The tick object is a sub-object of the system object.  The tick object properties allow you to read and alter tick-related settings which are set in the OPTION.CNF file.  Some of these settings can also be accessed in the Options dialog box.

Properties:

system.tick.property=

system.tick.gapAxTitle

Access:  Read, Set

Distance between the tick labels and the axis title.  In percent of system.tick.majorLen.  50=no gap

system.tick.gapInside

Access:  Read, Set

When the ticks are displayed inside the axis, this is the distance between the tick labels and the ticks.  In percent of system.tick.majorLen.

system.tick.gapOutside

Access:  Read, Set

When the ticks are displayed outside the axis, this is the distance between the tick labels and the ticks.  In percent of system.tick.majorLen.

system.tick.labelColor

Access:  Read, Set

Tick label color, when creating a graph from scratch (no template).  Numbers from the color list or use the color( ) function, as in:  system.tick.labelColor=color(blue)

This property is not available in the Options dialog box.

system.tick.log1As10E

Access:  Read, Set

Control display of tick labels when using Scientific notation on a logarithmic scale.

1= display 10^0 as 1 and display 10^1 as 10.

0= display 10^0 as 10^0 and display 10^1 as 10^1.

system.tick.maxNumeric

Access:  Read, Set

Maximum number of major ticks allowed when Numeric is selected from the Type drop down list on the Tick Labels tab of the Axis dialog box.

system.tick.maxText

Access:  Read, Set

Maximum number of major ticks allowed when 'Text from dataset', Time, Date, etc. is selected from the Type drop down list on the Tick Labels tab of the Axis dialog box.

system.tick.minorLen

Access:  Read, Set

Minor tick length, when creating a graph from a template.  In percent of the template's major tick length setting.

This property is not available in the Options dialog box.


System.Wks

The wks object is a sub-object of the system object.  The wks object properties allow you to read and alter worksheet-related settings which are set in the OPTION.CNF file.  These settings can also be accessed in the Options dialog box.

Properties:

system.wks.property=

system.wks.autoDelCol

Access:  Read, Set

Automatically delete datasets from a worksheet when closing the worksheet.  1=enable, 0=disable (display a prompt).

system.wks.closeExlPrt

Access:  Read, Set

Display a prompt when closing an Excel workbook window:  0=hide only, 1=display prompt, 2=delete without prompt.

system.wks.closeMatPrt

Access:  Read, Set

Display a prompt when closing a matrix window:  0=hide only, 1=display prompt, 2=delete without prompt.

system.wks.closePrompt

Access:  Read, Set

Display a prompt when closing a worksheet window:  0=hide only, 1=display prompt, 2=delete without prompt.

system.wks.numericData

Access:  Read, Set

Set all columns in all new worksheets to Text & Numeric (default) or to Numeric:  1=Numeric, 0=Text & Numeric.

system.wks.transpDelEmptyCols

Access:  Read, Set

Controls whether columns are deleted after transposing the worksheet.  0=always delete columns, 1=never delete columns, 2=prompt for delete.


Object Reference - Alphabetical Listing of Objects - Type
Type

The type object provides formatted copying of a worksheet to the Script window.  It allows scripts to show or hide the Script window and the status bar.  Additionally, it allows text that is passed to the type object to be redirected to the Notes window, Script window, or both.

Properties:

type.notes$

Access:  Read, Set

The name of the Notes window the output is redirected to if indicated by type.redirection.

type.notesRemainIcon

Access:  Read, Set

Set the "View/Remain Iconized" for the notes window specified in type.notes$.

type.notesState

Access:  Read

Get the state of the notes window specified in type.notes$.  The return value is bit oriented.

Bit=0, Value=1:  Window is open, a physical window exists (hidden or visible).

Bit=1, Value=2:  Window is visible to the user (vs. hidden).

Bit=2, Value=4:  Window contains data (or text for notes and Script window).

Bit=3, Value=8:  Window has been modified since it was last saved.

Bit=4, Value=16:  Window is iconized (this will always be off for the Script window as it can't be iconized).

type.numCols

Access:  Read, Set

The number of columns in the Script window.  If the actual number of worksheet columns exceeds the value specified by this property, subsequent columns display below the first set of columns in the Script window after executing the type.wks(wksName) method.

type.redirection

Access:  Read, Set

By default, all text output goes to the Script window.  This property allows you to direct output to different windows:

Bit=0, Value=1:  Output goes to the Script window.

Bit=1, Value=2:  Output goes to the Notes window specified by type.notes$.

Bit=2, Value=4:  Send any error messages to the Script window (whether or not output is directed there).

Bit=3, Value=8:  Put carriage return after every string sent to the Notes window.

Bit=4, Value=16:  Output goes to the Results Log.

type.repeatCol

Access:  Read, Set

When printing worksheet data to the Script window using the type.wks(wksName) method, repeat the first column (=1) for each block.  Otherwise, start the next block with the next column (=0).  For example, if type.numcols=4 and type.repeatcol=1, the printing format would be as follows:

A	B	C	D

A	E	F	G

A	H	etc.

type.state

Access:  Read

Get the state of the Script window.  The return value is bit oriented.  See type.notesState.

type.tab

Access:  Read, Set

The number of characters in a tab field.  If type.tab=0, then the individual worksheet column widths are maintained in the Script window after executing the type.wks(wksName) method.

Methods:

type.beginResults( )

Notify the Results Log of a block of results.  When the Results Log receives this notification it appends a header in the Results Log.  Headers are used to separate different blocks of results.  Headers contain the date, time, active folder name, and active window name.

type.endResults( )

Notify the Results Log that the block of results has ended.  It is necessary to notify the Results Log that a block of results has ended so it can separate the logs with headers.

type.msgBox(Msg,Title[,Button,Icon])

Display a modal Windows message box.  Msg displays as the message in the window.  Title displays as the title.  Button:  0=OK, 1=OK and Cancel, 2=Yes and No, 3=Yes, No, and Cancel.  Icon:  0=None, 1=Question, 2=Information, 3=Stop, and 4=Exclamation.  Returns the value of the button clicked on:  0=Cancel, 1=OK, 2=Yes, and 3=No.

type.redirection(on,off)

This method allows you to turn on and off the bits for the type.redirection property.  The first argument switches the bits on.  The second argument switches the bits off.  See the type.redirection property for the bit assignments.  This method returns the current setting of type.redirection.

type.showScript(Value)

Script window display.  Value:  1=show, 0=hide.

type.showStatus(Value)

Status bar display.  Value:  1=show, 0=hide.

type.wks(WksName)

Copy the contents of the named worksheet to the Script window.

Examples:

The following script sets the Script window format to be 4 columns wide.

type.numcols=4;

The next script repeats the first column for each block.

type.repeatcol=1;

The next script sets the Script window tab spacing to 15.

type.tab=15;

The last script copies the Data1 worksheet to the Script window.

type.wks(Data1);


Worksheet (wks)

The wks object provides access to general worksheet manipulation.  It includes three sub-objects:  col, export, and import.

The wks object is a window object.  For more information on window objects, see  Window Objects.

Properties:

The wks object is accessed using the following syntax:

[winName!]wks.property=

WinName! is optional.  If winName! is not specified, the active worksheet is affected.

wks.cNameMode

Access:  Read, Set

Its value determines the columns that wks.cnamen$ operates on.  Set wks.cnamemode to the following values:  0=all columns, 1=numeric columns, 2=text columns, 4=text and numeric (mixed) columns, and 64=columns in the selection range.  Set wks.cnamemode=128 to return the full dataset name to wks.cnamen$.

wks.cNamen$

Access:  Read

Read the name of the nth worksheet column.  See wks.cnamemode to operate on specific column types.

wks.col

Access:  Read, Set

Current column.  See the col object for column object properties.

wks.col#

Access:  N/A

Not in use.

wks.colWidth

Access:  Read, Set

Column width.  Refresh the window after changing this property value.

wks.font

Access:  Read, Set

Font index number as returned by the LabTalk font(fontname) function.

wks.fSize

Access:  Read, Set

Font size.

wks.hGrids

Access:  Read, Set

Display horizontal grid:  1=enable, 0=disable.

wks.joinMode

Access:  Read, Set

Set/get the worksheet join mode.  Values may be the following:  0=enumerate when column names match.  Append when matching rows are not found.  1=drop when column names match.  Append when matching rows are not found.  2=enumerate when column names match.  Drop when matching rows are not found.  3=drop when column names match.  Drop when matching rows are not found.  See the wks.join( ) method.

wks.maxRows

Access:  Read

Maximum row index number that contains a value.

wks.multiX

Access:  Read, Set

Multiple X columns:  1=enable, 0=disable.

wks.nCols

Access:  Read

Number of columns in the worksheet.

wks.nRows

Access:  Read

Number of rows in the worksheet.

wks.r1,r2,c1,c2

Access:  Read

Selection range.  First and last columns and rows.

wks.rhw

Access:  Read, Set

Row heading width in units of 1/10 of cell height.

wks.sel

Access:  Read

Selection flags.  The hex return number indicates what is selected in the worksheet.  Values may be the following, or a combination of these bits:  0=none, 1=editing cell, 2=column, 4=row, 8=range, and 16=1 column.

wks.useFont

Access:  Read, Set

Font usage:  1=use selected font, 0=use system font.

wks.vGrids

Access:  Read, Set

Display vertical grid:  1=enable, 0=disable.

Methods:

wks.addCol(name)

Add a single named column to the end of the worksheet.  If name is not specified, a generic name is chosen.

wks.colSel(colNum,n)

Column selection.  If n=1, select the colNum column.  If n=0, deselect the colNum column.

wks.copy(strVarLetter,Col,Row)

Copy(A):  copy entire wks into %A.  When the data is pasted, it is pasted into one row.

Copy(A,n):  copy all rows of column n.

Copy(A,0,n):  copy all columns of row n.

wks.insert(name list)

Insert the list of columns at the current location.  The current column position is specified by wks.col.  The list consists of one or more desired column names separated by spaces.  If a column name is already used, it is automatically enumerated.

wks.isColSel([colNum])

If colNum is included as an argument, the method returns the selection state of colNum.  0=the column isn't selected.  1=entire column is selected.  2=a range of the column is selected.

If colNum is not included as an argument, this method returns the number of columns selected (partial and entire selections).

[ToWks!]wks.join(FromWks)

Join the worksheet specified by FromWks to the worksheet specified by ToWks.  This method adds the columns of FromWks to ToWks.  If ToWks is not specified, then the currently active worksheet is used.  For the join conditions, see the wks.joinmode property.

wks.labels( )

Display worksheet column labels.  No argument=display labels, 0 as argument=do not display labels.

wks.paste(strVarLetter,Col,Row)

Paste the contents of a string variable (specified without the %) into the cell beginning at (Col,Row).

wks.template(FileName[,[WinName],NumRows])

Open a template.  For example, open the Count template and name it MyCount:  wks.template(Count,MyCount);

Examples:

The following script adds a column named CO to the end of the Data1 worksheet.

Data1!wks.addcol(CO);


Wks.Col

The col object is a sub-object of the wks object.  It is also a window object.  For more information on window objects, see  Window Objects.

Properties:

The col object is accessed using the following syntax:

[winName!]wks.col[n].property=

WinName! is optional.  If winName! is not specified, the named object in the active window is affected.

n is the column number starting from 1.  If n is not provided, the current column is assumed.  The current column can be set with the wks.col property.

wks.col.digitMode

Access:  Read, Set

Set the digit display:  0=display all, 1=set the decimal places, and 2=set the significant digits.  When wks.col[n].digitmode=0, wks.col[n].digits is set to 0.  When wks.col[n].digitmode=1, wks.col[n].digits is set to 3.  When wks.col[n].digitmode=2, wks.col[n].digits is set to 6.

wks.col.digits

Access:  Read, Set

Number of decimal places when wks.col.digitMode=1, number of significant digits when wks.col.digitmode=2:  0=display all, n=display n.

wks.col.format

Access:  Read, Set

Column format:  1=numeric, 2=text, 3=time, 4=date, 5=month, 6=day of week, and 7=text and numeric.

wks.col.justify

Access:  Read, Set

Set the justification for worksheet cell values.  1=right, 2=left, and 3=center.

wks.col.label$

Access:  Read, Set

Column label.  To read, assign the value to a string variable.

wks.col.name$

Access:  Read, Set

Column name.  To read, assign the value to a string variable.

wks.col.subformat

Access:  Read, Set

Subformat options as listed in the Format drop down list of the Worksheet Column Format dialog box.

wks.col.tWidth

Access:  Read, Set

Number of characters allowed in a text column.

wks.col.type

Access:  Read, Set

Column type:  1=Y, 2=disregard, 3=Y Error, 4=X, 5=Label, 6=Z, and 7=X Error.

wks.col.width

Access:  Read, Set

Column width, in units of characters.

Examples:

The following script sets column 1 of the active window to be an X column.

wks.col1.type=4;

The next script loops over the selected columns in the Data1 worksheet.  The script prints the names of all of the columns to the Script window.

loop (var, Data1!wks.c1,Data1!wks.c2)

{

%A=Data1!wks.col$(var).name$;

type "%A";

};


Wks.Export

The export object is a sub-object of the wks object.  It is also a window object.  For more information on window objects, see  Window Objects.

Properties:

The export object is accessed using the following syntax:

[winName!]wks.export.property=

WinName! is optional.  If winName! is not specified, the active worksheet is affected.

wks.export.c1

Access:  Read, Set

First column in the data range to be included with the data file.  Set to 1, 2, ... n.  To include all data, set to 1 (default).

wks.export.c2

Access:  Read, Set

Last column in the data range to be included with the data file.  Set to 2, 3, ... n.  To include all data, set to 0 (default).

wks.export.cntrl

Access:  Read, Set

Include or exclude column names with the data file and export a range of data:  0=exclude column names and export a range of data, 1=include column names and export a range of data, 2=exclude column names and export all data, 3=include column names and export all data, and 4=include column names and labels and export all data.  The column names are copied to the first line of the data file, followed by <CR>, and then the data.

wks.export.r1

Access:  Read, Set

First row in the data range to be included with the data file.  Set to 1, 2, ... n.  To include all data, set to 1 (default).

wks.export.r2

Access:  Read, Set

Last row in the data range to be included with the data file.  Set to 2, 3, ... n.  To include all data, set to 0 (default).

wks.export.separator$

Access:  Read, Set

Specify the separator for use in the data file.  The default separator is "\t".  The syntax is as follows:  wks.export.separator$="," for a comma separator.

Examples:

The following script specifies the column range, row range, and separator for data export.  It also specifies that the column names be exported with the file.

wks.export.c1=2;

wks.export.c2=4;

wks.export.r1=2;

wks.export.r2=12;

wks.export.cntrl=1;

wks.export.separator$=",";

getfile *.dat;	// get a file name to use

save -wh %H %A;	// export the active window (must be wks)


Wks.Import

The import object is a sub-object of the wks object.  It is also a window object.  For more information on window objects, see  Window Objects.

Properties:

The import object is accessed using the following syntax:

[winName!]wks.import.property=

WinName! is optional.  If winName! is not specified, the active worksheet is affected.

wks.import.maxTest

Access:  N/A

Not currently implemented.

wks.import.minBlock

Access:  N/A

Not currently implemented.  The number of lines to be used for data file structure testing.

wks.import.partial

Access:  Read, Set

When importing an ASCII file using open -w fileName, open the Import Verification dialog box before importing the file:  1=enable, 0=disable.


Built-in Function Reference - Introduction
Introduction

Origin's built-in functions are classified into categories:  Utility, Mathematical, and Statistical.  Each function returns either a single value or a range of values (a dataset), depending on the type of function and the arguments supplied.  Unless otherwise specified, all functions will return a range if the first argument passed to the function is a range, and all functions will return a value if a value is passed.

Functions can be used anywhere a mathematical expression is used.  When calling a function, DO NOT leave a space between the function name and the open parenthesis.  For example, enter col(colname), not col (colname).


Utility Functions

Basic Worksheet Functions

Dataset Generation Functions

Dataset Manipulation Functions

Dataset Information Functions

Miscellaneous Functions


Basic Worksheet Functions

col(colname)

col(colname)[row#]

col(colname)[row#]$

wcol(colnumvariable)

wcol(colnumvariable) [row#]$


col(colname)

The col(colname) function returns the dataset which has the column name colname in the active worksheet.  The column number may be specified instead of the column name.  For example, if column A is the first column in the worksheet, col(1) and col(A) both return the dataset in column A.

Example:	col(C)=(1+col(A))/(1-col(B));


col(colname)[row#]

The col(colname)[row#] function returns the numeric value of a single dataset element.  The column name (or column number) is indicated in parentheses, while the row number is included in brackets.  Origin returns the value of the cell specified by the given row and column numbers.

Example 1:	myVar=col(B)[3];

In this example, the variable myVar is assigned the value in the third row of column B.

Example 2:	col(B)[4]=9;

In this example, the fourth cell of column B is assigned the value 9.


col(colname)[row#]$

The col(colname)[row#]$ function returns a single text dataset element.  Indicate the column name or column number in parentheses and the row number in brackets.  Origin returns the text of the cell specified by the given row and column numbers.

Example:	%W=col(A)[3]$;

In this example, the variable %W is assigned the text element in the third row of column A.


wcol(colnumvariable)

The wcol(colnumvariable) function returns the dataset from the active worksheet that corresponds to the given column number set in colnumvariable (counting from left to right with the first column as 1).  This function is different from the col(colname) function in that colnumvariable is always interpreted as a value, such that you may use any expression to specify the column number.

Example:

for (ii=1; ii<=10; ii+=1) {

wcol(ii)=data(ii,ii+10);

};


wcol(colnumvariable) [row#]$

The wcol(colnumvariable)[row#]$ function sets, or returns, a single text dataset element.  Indicate the column name (using a variable) or the explicitly specified column number in parentheses and the row number in brackets.  Origin returns the text of the cell specified by the given row and column numbers.

Example 1:	%W=wcol(k)[3]$;

In this example, the variable %W is assigned the value in the third row of the kth column.

Example 2:	wcol(k)[4]$="Apples";

In this example, the fourth element of the kth column is assigned the value "Apples".


Dataset Generation Functions

data(x1,x2,inc)

{v1,v2,...vn}

Fit(Xdataset)

Table(Dataset1,Dataset2,Dataset3)


data(x1,x2,inc)

The data(x1,x2,inc) function creates a dataset with an initial value of x1, a final value of x2, and an increment equal to inc.  If x1 is set equal to x2, inc number of points with values equal to x1 are returned.  If inc is omitted, inc=1 is assumed.

Example 1:	col(A)=data(10,10,5);

This function fills the first five rows of column A with the number 10.

Example 2:	col(A)=data(1,100);

This function fills column A with 100 numbers from 1 to 100, with an increment of one.


{v1,v2,...vn}

The {v1,v2,...vn} 'function' returns a range that consists of the specified values.  Note that v1,v2,...vn are literal values, meaning the actual values are entered.

Example:	col(A)={1,2,4,5,12,13};

In this example, the first six elements in column A are assigned the corresponding 'function' values.  If column A had more than six elements, only the first six elements would be changed.


Fit(Xdataset)

The Fit(Xdataset) function creates a dataset corresponding to the fitted line generated during nonlinear fitting.  The parameters and equation used in the most recently performed nonlinear fitting session are applied to the specified X dataset.  The function returns a value for each element of the X dataset.

For example, if you perform a fit on data with an X range from 0 to 100, then you could generate a new fit curve using the following lines of script:

Data1_C=data(0,100,20);

//Make dataset corresponding to same range

//but with different increment

Data1_D=fit(data1_C);

//Employ last fit parameters to this X dataset


Table(Dataset1,Dataset2,Dataset3)

The Table(Dataset1,Dataset2,Dataset3) function is used after performing linear or nonlinear fitting and returns a dataset of X or Y values, depending on the order of the dataset arguments.

Example:  The following script returns new Y values from a fit curve:

linearfit_Ynew=Table(linearfit_a,linearfit_data1b,linearfit_b)

where linearfit_a is the X fit dataset, linearfit_data1b is the Y fit dataset, and linearfit_b holds the X values for predicting Y values.

Example:  The following script returns new X values from a fit curve:

linearfit_Xnew=Table(linearfit_data1b,linearfit_a,linearfit_b)

where linearfit_data1b is the Y fit dataset, linearfit_a is the X fit dataset, and linearfit_b holds the Y values for predicting X values.


Dataset Manipulation Functions

sort(dataset)

diff(dataset)

peaks(dataset,width,minheight)

corr(dataset1, dataset2,k[,N])


sort(dataset)

The sort(dataset) function returns a dataset that contains dataset, sorted in ascending order.  This function only affects dataset.  It has no effect on other datasets in the worksheet.

This function contrasts with the Sort menu command in that the Sort menu command will rearrange the corresponding values in other columns in the worksheet.


diff(dataset)

The diff(dataset) function returns a dataset that contains the difference between adjacent elements in dataset.  If there are N elements in dataset, the returned range will have N-1 elements.  The first element in the returned range is equal to the difference between the second and the first element of the given range.


peaks(dataset,width,minheight)

The peaks(dataset,width,minheight) function returns a dataset containing indices of peaks found using width and minheight as a criteria.  Width is the number of points on either side of the test point and minheight is in Y axis units.  A peak at a given index i is minheight greater than the data value at i-width or i+width.


corr(dataset1, dataset2,k[,N])

The corr(dataset1,dataset2,k[,N]) function returns the correlation between two datasets using a lag size of k and an optional number of points N.

Example:	col(3)=corr(col(1),col(2),data(1,10),50);

This script results in the cross correlation of the first 50 points of col(1) with col(2) using lag sizes from 1 to 10.

Note:  The lag argument (k) can be a scaler or a vector.  When k is a vector, the correlation function returns a vector.  Similarly, when k is a scaler, the correlation function returns a scaler.


Dataset Information Functions

IsMasked(index,dataset)

FindMasks(dataset)

hasx(dataset)

xof(dataset)

errof(dataset)

xvalue(i,dataset)

xindex(x,dataset)

xindex1(x,dataset)

list(value,dataset)


IsMasked(index,dataset)

Returns the number of masked points in dataset if index=0.  If index is supplied, this function returns the "mask state" of the index number data point:  1=masked, 0=not masked.


FindMasks(dataset)

Returns a dataset that contains the indexes of the masked data points.


hasx(dataset)

Returns a 1 if dataset has a corresponding X column.  Otherwise, the function returns a 0.


xof(dataset)

Returns a string containing the X values of dataset.


errof(dataset)

Returns the dataset (error column) containing the error values of dataset.


xvalue(i,dataset)

Returns the corresponding X value for dataset at row number i in the active worksheet.


xindex(x,dataset)

Returns the index number of the first cell in the X dataset associated with dataset, where the cell value is less than or equal to x.  dataset must be a designated Y dataset.  Furthermore, the Y dataset name must correspond to an actual Y dataset.


xindex1(x,dataset)

Returns the index number of the first cell in the X dataset associated with dataset, where the cell value is greater than or equal to x.  dataset must be a designated Y dataset.  Furthermore, the Y dataset name must correspond to an actual Y dataset.


list(value,dataset)

Returns the index number in dataset where value first occurs.  If there is no match, the function returns 0.  Note that this function makes an "exact" comparison using the equal (==) operator.


Miscellaneous Functions

colnum(colname)

color(name)

date(MM/DD/YY HH:MM)

exist(name)

exist(name,n)

hex(string)

asc(character)

font(name)


colnum(colname)

The colnum(colname) function returns the column position number of the column specified by colname.

Example:	Variable=ColNum(B);

This script sets Variable to 2 if column B is the second column of the current worksheet.

The argument for this function can also be a dataset name.  For example, Data1_B or Book1_B@2 (for a dataset in a workbook).  When supplying a workbook dataset name as the argument, the dataset need not be in the active workbook sheet.  It also need not be in the active workbook.  If the dataset exists in a workbook that isn't active, this function sets the associated workbook layer active but doesn't set the workbook active.


color(name)

The color(name) function returns a number corresponding to the index in the color list of the color specified by name.


date(MM/DD/YY HH:MM)

The date(MM/DD/YY HH:MM) function returns the Julian-day value which Origin uses internally to represent dates.  The integer part is the number of Julian days and the fractional part is the fraction of a 24 hour day.

Example:	col(2)[3]=date(5/7/99);

This script sets the third cell of the second column to 5/7/99 if the column format is set to date.


exist(name)

The exist(name) function returns a single value indicating what 'object type' the given name is associated with:

Return Value	Specified Object Type

0	None.  Name is not defined.

1	dataset

2	worksheet

3	graph window

4	variable

5	matrix

6	macro

7	tool

9	notes window

Note:  A matrix is also a dataset.  If you delete a matrix window without deleting the data, the exist(name) function will return 5 before deleting the matrix window, and 1 after deleting the matrix window.


exist(name,n)

If n=0, this function returns a non-zero value if the given name is active and is not hidden.  Otherwise, it returns 0.

If n=10, this function returns a non-zero value if the given name is active.  Otherwise, it returns 0.


hex(string)

The hex(string) function returns the base 10 equivalent to the hexadecimal value represented by the given string.  The maximum number of hex characters in the given string is 4.

Example:	hex(A2)=162;


asc(character)

The asc(character) function returns the ASCII value of the uppercase character in parentheses.


font(name)

The font(name) function returns a number corresponding to the font list index of the font specified by name.


Mathematical Functions

Basic Mathematical Functions

Multi-parameter Functions

Special Functions

Random Number Generators


Basic Mathematical Functions

The functions referenced on the following Help pages may be used on datasets as well as on a single variable.

More:

prec(x,p)

round(x,p)

abs(x)

angle(x,y)

exp(x)

sqrt(x)

ln(x)

log(x)

mod(x,y)

rmod(x,y)

int(x)

nint(x)

sin(x), cos(x), tan(x)

asin(x), acos(x), atan(x)

sinh(x), cosh(x), tanh(x)


prec(x,p)

The prec(x,p) function returns a value (or a dataset) such that the numbers contain p places of significance.

Example 1:

x=1234567;

n=prec(x,3);

This script returns the value 1.23E6 for n.

Example 2:

data1_B=prec(data1_C,3);

In this example, the values in data1_C are assigned to data1_B to 3 places of significance.


round(x,p)

The round(x,p) function returns a value (or a dataset) with p decimal places accuracy.  See the prec(x,p) function for help with syntax.


abs(x)

Absolute value.


angle(x,y)

Angle in radians measured between the positive X axis and the line joining the origin (0,0) with the point given by (x,y).  The returned values range from zero to 2π.  Note that angle(0,0) returns a missing value because the result is undefined.


exp(x)

Exponential.  (If x is greater than 667, this function returns a missing value.)


sqrt(x)

Square root.


ln(x)

Natural logarithm.


log(x)

Base 10 logarithm.


mod(x,y)

Integer modulus (the remainder from division) of integer x divided by integer y.


rmod(x,y)

Real modulus (the remainder from division) of real number x divided by real number y.

Example:  	rmod(4.5,2)=0.5;


int(x)

Truncated integer, such that int(7.9)=7.


nint(x)

The result of nint(x) is identical to round(x,0).  Therefore, a value of 0.5 gets rounded up (nint(0.5)=1 and nint(-0.5)=-1).


sin(x), cos(x), tan(x)

These three functions return values of sine, cosine, or tangent for each value of the given x.  These and other trigonometric functions can take values in radians, degrees, and gradian.  The units are determined by the system.math.angularunits object property (which can also be set in the Options dialog box).


asin(x), acos(x), atan(x)

These functions return the inverse of the corresponding trigonometric function.  x must be within -1 and 1 for asin and acos, or a missing value is returned.  x can be any value for atan.  Values returned are in radians, degree or gradian, depending on the system.math.angularunits object property (which can also be set in the Options dialog box).


sinh(x), cosh(x), tanh(x)

These functions are the hyperbolic forms of sin, cos, and tan, respectively.


Multi-parameter Functions

Multi-parameter functions are used as built-in functions for Origin's nonlinear fitter.

More:

Gauss

Lorentz

Logistic

ExpDecay

ExpGrow

ExpAssoc

Boltzmann

Hyperbl

Dhyperbl

Pulse

Poly [image] or Poly


Gauss

center of the peak

w	equals 2 times the standard deviation of the Gaussian distribution (2*σ) or approximately 0.849 the width of the peak at half height

A	area under the peak

baseline offset


Lorentz

center of the peak

w	width of the peak at half height

A	area under the peak

baseline offset


Logistic

This function produces a sigmoidal curve.  See the Boltzmann function for details.


ExpDecay

This is a triple exponential decay function having the form:


ExpGrow

This is a double exponential growth function having the form:


ExpAssoc

This is a double exponential association function having the form:


Boltzmann

This function produces a sigmoidal curve using the Boltzmann equation:


Hyperbl

This is a rectangular hyperbola function having the form:


Dhyperbl

This is a double rectangular hyperbola function having the form:


Pulse

The pulse function has the form:


Poly
Poly [image] or Poly

This function evaluates an nth order polynomial for the given x and polynomial coefficients.  The order of the polynomial is always assumed to be 9, but you can pass fewer coefficients to the function.  All higher order coefficients are set to zero.

In the first form of the function, values of coefficients are given explicitly.  In the second form, a dataset is expected to contain the coefficients.

Example:	poly(2,1,3);

Returns:	1 + 3 * 2 = 7


Special Functions

Jn(x,n)

J0(x)

J1(x)

Yn(x,n)

Y0(x)

Y1(x)

gammaln(x)

incbeta(x,a,b)

incgamma(x,a)


Jn(x,n)

The Bessel function of order n (where n is an integer) has the following form:

See the gammaln(x) function for the definition of Γ.

Note:  When using the function Jn(x,n), the first n is typed literally while the second n is a place holder.


J0(x)

Zero order Bessel function.


J1(x)

First order Bessel function.


Yn(x,n)

The Bessel function of second kind, where n is an integer, has the following form:

 where

Note:  When using the function Yn(x,n), the first n is typed literally while the second n is a place holder.


Y0(x)

Zero order Bessel function of second kind.


Y1(x)

First order Bessel function of second kind.


gammaln(x)

This function returns the natural log of the gamma function Γ(x), where Γ(x) is given by:


incbeta(x,a,b)

This function is the incomplete beta function I(x,a,b).  It has the limiting values:

I(0,a,b)=0 and I(1,a,b)=1, and the symmetry relation

I(x,a,b)=1-I(1-x,b,a).


incgamma(x,a)

This function is the incomplete gamma function P(a,x).  It has the limiting values:

P(a,0)=0 and P(a,∞)=1.


Random Number Generators

Two functions in this category, rnd( ) and grnd( ), return a value.  All the other functions in this category return a range.

More:

rnd(seed) and ran(seed)

grnd( )

normal(npts,seed)

Poisson(npts,mean,seed)

uniform(npts,seed)


rnd(seed) and ran(seed)

The rnd(seed) and ran(seed) functions return a value between 0 and 1 from a uniformly distributed sample.  The initial starting value in the range is determined by seed.  If seed is a positive integer, the random number generator returns a particular value.  For example, if seed=1, the functions return 0.1711484.  If seed is zero or no argument is provided, the random number generator returns the next number in the random number sequence.

Note:  To generate random numbers, Origin uses the ran1 function in Numerical Recipes in C by Press, et al.  See the Reference section in the Origin User's Manual or Help file for more information.


grnd( )

The grnd( ) function returns a value from a normally (Gaussian) distributed sample, with zero mean and unit standard deviation.  The initial value returned, and the sequence of values, are the same for each Origin session.

No argument is needed.  To obtain a random number from a normal distribution with mean=m and standard deviation=sd, use grnd( )*sd+m.


normal(npts,seed)

The normal(npts,seed) function returns a range with npts number of values.  The initial starting value in the range is determined by seed.  The values are random numbers with a normal (zero mean and unit standard deviation) distribution respectively.  If seed is omitted, a different seed is used each time the function is called.

Example:  col(1)=normal(100)*2+5;

This script fills column 1 with 100 random numbers with a mean=5 and a sd=2.


Poisson(npts,mean,seed)

Returns npts number of random integers having a Poisson distribution with mean mean.  Seed is optional.  The algorithm for the Poisson distribution is from Numerical Recipes in C, 2nd edition, pages 293-295.


uniform(npts,seed)

The uniform(npts,seed) function returns a range with npts number of values.  The initial starting value in the range is determined by seed.  The values are random numbers with uniform (between 0 and 1) distribution.  If seed is omitted, a different seed is used each time the function is called.


Statistical Functions

Statistics on Datasets

Statistical Distributions


Statistics on Datasets

All of the following functions except ss( ) return a range.

More:

histogram(dataset,inc,min,max)

sum(dataset)

ave(dataset,size)

percentile(dataset1,dataset2)

ss(dataset,ref)

ss(dataset)

ss(dataset,4)

ss(dataset1,dataset2)

ss(dataset,A+B.x)

cov(dataset1,dataset2,ave1,ave2)


histogram(dataset,inc,min,max)

The histogram(dataset,inc,min,max) function generates data bins from dataset in the specified range from min to max.  The bin width is equal to inc.  The function will include values that fall on the lower edge of the bin, however the function will put data that falls on the upper edge into the next higher bin.


sum(dataset)

The sum(dataset) function returns a range whose ith element is the sum of the first i elements of the dataset dataset.  Therefore, the last element of the range returned by sum(dataset) is the sum of all elements in dataset.  This value is also returned in sum.total.

The sum(dataset) function also automatically assigns values to the following sum object properties:

sum.mean, sum.total, sum.min, sum.max, sum.sd, sum.n

Example:  sum(DATA1_A);

If DATA1_A contains 4 values (1, 2, 3, 4), this script returns the range (1, 3, 6, 10) where the second value in the returned range (3) is the sum of the first two values in DATA1_A, etc.  The last value in the returned range (10) is the sum of all the values in DATA1_A.  The value of 10 is also returned in sum.total.

This function can also be used across worksheet columns using the following syntax: sum(WorksheetName,col1,col2).  A range is returned that equals the sum of all the columns from col1 to col2.  Statistical values are also returned to the sum object properties.


ave(dataset,size)

The ave(dataset,size) function breaks dataset into groups of size size, finds the average for each group, and returns a range containing these values.


percentile(dataset1,dataset2)

The percentile(dataset1,dataset2) function returns a range comprised of the percentile values for dataset1 at each percent value specified in dataset2.

Example:

DATA1_A=normal(1000);

DATA1_B={1,5,25,50,75,95,99};

DATA1_C=percentile(DATA1_A,DATA1_B);

The result contains the percentiles of a normal distribution at 1%, 5%, .. and 99%.


ss(dataset,ref)

The ss(dataset,ref) function is the sum of squares function.  The following equation is used to calculate a value for each value in dataset:

The resulting values are added, and a single value is returned.  This function can take one of four forms, depending on the reference value ref.


ss(dataset)

The ss(dataset) function is the sum of squares function in which ref is omitted.  The function assumes the mean of the data as the reference value.


ss(dataset,4)

The ss(dataset,4) function is the sum of squares function in which ref is a constant.  The function uses the constant as the reference value.


ss(dataset1,dataset2)

The ss(dataset1,dataset2) function is the sum of squares function in which ref is a dataset.  The function uses the corresponding element in dataset2 as the reference value for each dataset1.


ss(dataset,A+B.x)

The ss(dataset,A+B.x) function is the sum of squares function in which ref is an expression involving i or x.  If x, the corresponding X value for each element in dataset is used to calculate the reference value.  If i, the corresponding row number for each element in dataset is used to calculate the reference value.

Example:  ss(dataset,A+B.x);

This script will calculate the sum of squares for the straight line formed by Y with intercept A and slope B.


cov(dataset1,dataset2,ave1,ave2)

The cov(dataset1,dataset2,ave1,ave2) function returns the covariance between two datasets.  Let X and Y be two datasets and [image] and [image] their respective means, then the covariance between the two is defined as:


Statistical Distributions

Ttable(x,n)

invt(value,n)

Ftable(x,m,n)

invf(value,m,n)

erf(x)

inverf(x)

prob(x)

invprob(x)

QCD2(n)

QCD3(n)

QCD4(n)


Ttable(x,n)

The Ttable(x,n) function is Student's t distribution with n degrees of freedom.  .

Student's t distribution is used in calculating the confidence bands in linear regression.  x is usually called the significance level.

Examples:

Ttable(0.95,15)=1.753

Ttable(0.99,10)=2.764


invt(value,n)

The invt(value,n) function is the inverse t distribution function with n degrees of freedom.  This function is used to calculate the p-value involving t distributions.

Examples:

invt(1.753,15)=0.95

invt(2.764,10)=0.99


Ftable(x,m,n)

The Ftable(x,m,n) function is the F distribution function with m and n degrees of freedom.  x is usually called the significance level.

The F distribution is used in calculating confidence limits for parameters in nonlinear regression.

Examples:

Ftable(0.95,2,15)=3.68232

Ftable(0.95,4,10)=3.47805


invf(value,m,n)

The invf(value,m,n) function is the inverse F distribution function with m and n degrees of freedom.  This function is used to calculate the p-value involving F distributions.

Example:

invf(3.682,2,15)=0.94999


erf(x)

The erf(x) function is the error function (or normal error integral).  The function has the limiting values erf(0)=0, and erf(∞)=1.  Mathematically:

erf(x) =

Note that erf(-x)=-erf(x) is an even function of x and erf(x)=2*(Normal Distribution Function evaluated at [image]) -1, where the Normal Distribution Function is [image].


inverf(x)

The inverf(x) function is the inverse error function.


prob(x)

The prob(x) function is the Probability Density (for a normal distribution) integrated from -x to +x.

It has the limiting values prob(0)=0, and prob(∞)=1.  Mathematically:

Prob(x) =

Note that prob(-x)=-prob(x),  prob(x)=erf( [image]), or

prob(x) = 2 * Normal Distribution Function -1.


invprob(x)

The invprob(x) function is the Inverse Probability Density function.

Examples:

prob(1.8)=0.92814

invprob(0.92814)=1.8

invprob(prob(1.8))=1.8


QCD2(n)

The QCD2(n) function returns a factor (Quality Control D2 Factor) which is used to estimate the standard deviation of a parent distribution (or population) from an average range when the sample size (or subgroup size) n is given.

The standard deviation of the parent distribution=average range/factor.

The returned factors assume sampling from a normal population.

Example:	QCD2(4)=2.05952

This script returns the factor for a sample size of 4.


QCD3(n)

The QCD3(n) function returns a factor (Quality Control D3 Factor) for determining the 3-sigma lower control limit for R charts (Range of Sample Charts) from the average range when the sample size (or subgroup size) n is given.

The Lower Control Limit for R=(factor)*(Average Range).

The calculations for the factors are based on the normal distribution.

Example:	QCD3(11)=0.25474

This script returns the factor for a sample size of 11.


QCD4(n)

The QCD4(n) function returns a factor (Quality Control D4 Factor) for determining the 3-sigma upper control limit for R charts (Range of Sample Charts) from the average range when the sample size (or subgroup size) n is given.

The Upper Control Limit for R=(factor)*(Average Range).

The calculations for the factors are based on the normal distribution.

Example:	QCD4(11)=1.74704

This script returns the factor for a sample size of 11.


Macro Reference - Introduction
Introduction

A macro is a convenient method of aliasing a LabTalk script.  When you define a macro you are associating an entire script with a specific name.  This name can then be used as a command that invokes the associated script.  Macros are useful for a number of reasons.  First, in Origin, there is a limit of the number of tokens that can be included between the set of curly braces which enclose a script.  This limit is currently set at 1140 bytes (after substitution).  If a script exceeds this limit it can be shortened by replacing a portion of its code with a macro command name that has been previously associated with the replaced code.  This works because when calculating the number of tokens included between the curly braces of a script, Origin counts the length of any included macro name and not the length of the macro's associated script.

Macros can also be a useful device when attempting to develop modular code.  Modular code is beneficial for many reasons.  Modular code can improve script readability by replacing unwieldy blocks of code with mnemonic macro names.  The readability and maintainability of a script can also be improved by replacing repetitive or similar blocks of code with multiple calls of the same macro.  Different arguments can be passed to each macro call, if need be, to individually tailor the code that gets executed.  Macros improve the maintainability of scripts by reducing the number of possible modifications required in the future.  If modifications to a script are required it is easier to change the code in one reused macro rather than the code in many repeated blocks of code.  Macro libraries can also be created which might reduce future development time and costs.  Once a macro is written and thoroughly debugged, it can confidently be used to perform its objective anywhere in any script.

One final use of macros is in overriding predefined LabTalk commands.  Since macros are executed prior to predefined LabTalk commands, if you want to override a LabTalk command (implement your own version of the command) you can accomplish this by creating a macro with the same name as the predefined command.  The overriding macro command can be deleted at any time and the predefined command will automatically be restored.


Defining and Displaying Macros

To define a new macro or to re-define an existing macro, use the define command.  Since macros are defined by executing the define command, macros can be defined anywhere in Origin that allows LabTalk scripts to be executed.  However, macros are generally defined in *.CNF files which get executed when Origin is started or in the Script window at run time.

The syntax for the define command is:

define macroName {script}

The define command defines a macro named macroName and associates it with the given script {script}.  MacroName can then be used like a command which when executed will invoke the given script.

The following script defines a macro named hello that uses a loop to print a text string three times in the Script window.

def hello {

  loop (ii, 1, 3) {

    type "$(ii). Hello World";

  };

};

To display a script that has been previously associated with a defined macro, use the define command without the {script} argument:

define macroName

For example, executing the command define hello in the Script window, after having defined the hello macro as described above, will cause the following text to be printed in the Script window:

define hello;

{

  loop (ii, 1, 3) {

    type "$(ii). Hello World";

  };

}

Macros can be passed up to five arguments.  Use the  %1, %2, %3, %4, and %5 notation within the script definition to indicate that the macro expects one or more arguments.  A macro can accept a number, string, variable, dataset, function, or even a script as an argument.  Arguments to an Origin macro function similarly to MS-DOS batch arguments.  An executing macro can access the number of arguments passed to it at run time via the marco.nArg object property.

The following script defines a macro named goodbye that uses a loop to print out a goodbye message to the Script window for each argument string (up to five) it is passed.  The script uses the macro.nArg object property to determine the number of times the loop should iterate.

def goodbye {

  %Z=%1 %2 %3 %4 %5;

  for (ii=1;ii<=macro.nArg;ii++) {

    type "$(ii). Goodbye %[%Z,#$(ii)]";

  };

};


Executing LabTalk Macros

Macros can be called or executed anywhere that LabTalk scripts can be executed including the Script window, the Worksheet Script dialog box, the Label Control dialog boxes, *.OGS files, user-defined Y-script fitting functions, and even other macros.  To execute the script associated with a defined macro inside the Script window, type the macro name and press ENTER.  If you type the hello macro command into the Script window and press ENTER (after having defined the hello macro as described above), the script associated with the hello macro executes and prints the following in the Script window:

hello;

1. Hello World

2. Hello World

3. Hello World

A script associated with a macro name can be passed up to five arguments.  To pass a macro arguments, type the macro name followed by a space separated list of the arguments into the Script window and then press ENTER.  The values of the arguments passed will be accessible to the executing script through the use of the variables %1, %2, %3, %4, and %5.  For example, if you type the macro command goodbye Liane Sarah Amanda into the Script window and press ENTER (after having defined the goodbye macro as described above), the script associated with the goodbye macro executes and prints the following in the Script window:

goodbye Liane Sarah Amanda;

1. Goodbye Liane

2. Goodbye Sarah

3. Goodbye Amanda

To call or execute a macro from someplace other than the Script window, place the macro name along with any arguments you are passing to it in the calling script (terminated with a semicolon) just as you would any other LabTalk command.  For example, to execute the hello macro from inside an OGS file, you include the line

hello;

inside the OGS file.  To execute the goodbye macro from inside a Label Control dialog box, include the line

goodbye Liane Sarah Amanda;

inside the Label Control dialog box.

If you want to design a macro that terminates its execution on a testable condition and then returns control back to the Script window or its calling script, use the return command.  For example, the following script defines a macro named test that takes an argument, types OK if the argument is greater than 2, and then terminates its execution with the return command.  If the argument is less than or equal to 2 then the macro types Not OK and continues executing until it reaches its last statement.

def test {

  if (%1>2) {

    type "OK";

    return;

  };

  type "Not OK";

  type "Keep running until you reach the end!";

};

If you type the command test 3, the macro will print OK and then terminate its execution.  If you type test 1, the macro types Not OK and continues to run until it reaches the end of the macro.

test 3;

OK

test 1;

Not OK

Keep running until you reach the end!


Listing and Deleting Macros

To print a list of all macros currently defined in the Script window, use the List m (without the -) command.  To delete a defined macro named macroName, use the Delete -m macroName (with the -) command.


Special Event Driven Macros

There are a number of special events in Origin which trigger the execution of prenamed macros at precise moments in time.  The names of the event driven macros are predetermined but the associated script of each event driven macro must be defined by you before the macro is triggered or no code will be executed.  You can program the triggered macro to execute any LabTalk commands you want.

More:

AutoExec

BeginSave

DocBegin

DocEnd

EndOpen

EndToolbox

ErrorProc

PointProc

QuitToolbox

TimerProc


AutoExec

To automatically open a file (of a supported file type) when starting Origin you specify the filename at the end of the command line in the Window's Start:Run dialog box or in the Target text box of an Origin shortcut's Properties window.  The supported file types include: graph templates (*.OTP), graphs (*.OGG), worksheets (*.OGW), matrices (*.OGM), projects (*.OPJ and *.ORG) and Excel files (*.XLS).

If Origin is not directed to open a specified file at start up and the AutoExec macro is defined, the AutoExec macro is triggered at the end of the Origin start up sequence.  The AutoExec macro is generally used to override internal default settings.  A minimal and commented out definition of the AutoExec macro can be found in the MACROS.CNF file (found in the Origin software folder).  Caution is advised when defining this macro as not defining this macro is part of the normal and recommended start up sequence of Origin.


Macro Reference - Special Event Driven Macros - BeginSave
BeginSave

The BeginSave macro is triggered when the current document (project) or a child window is saved.  The BeginSave macro is not triggered when a template is saved.  Saving a project or a child window by selecting File:Save Project, File:Save Project As, or File:Save Window As from the Origin main menu or by issuing the save command triggers the execution of the BeginSave macro.  Exiting Origin by selecting File:Exit from the Origin main menu, by clicking the Origin close window system icon, or by issuing the exit command (and then electing to save the modified project before exiting) also triggers the execution of the BeginSave macro.


DocBegin

The DocBegin macro is triggered just prior to opening an existing document (project).  Opening an existing project by selecting File:Open from the Origin main menu, by clicking the Open button, or by issuing the doc -o or doc -of commands triggers the execution of the DocBegin macro.  The DocBegin macro is unique in that a define statement for the DocBegin macro is contained in the file ORGSYS.CNF (found in the Origin software folder) which gets executed when projects are opened.  Since ORGSYS.CNF is executed just prior to the triggering moment for DocBegin, you must either comment out this definition or modify it to define DocBegin as you wish.  Otherwise, the default definition of DocBegin (which happens to do nothing) will be the one that gets executed upon being triggered.


DocEnd

The DocEnd macro is triggered when the current document (project) is closed.  The current project is closed when you exit Origin and when a new project is opened.  Origin only allows one project to be open at a time, so opening a new project necessitates closing the current project.  Consequently, opening a new project by selecting File:New or File:Open from the Origin main menu, by clicking the New Project button or the Open button, or by issuing the doc -d, doc -n, doc -o or doc -of commands triggers the execution of the DocEnd macro.  Exiting Origin by selecting File:Exit, by clicking the Origin close window system icon, or by issuing the exit command also triggers the execution of the DocEnd macro.  The DocEnd macro is unique in that a define statement for the DocEnd macro is contained in the file MACROS.CNF (found in the Origin software folder) which gets executed when Origin starts.  The default definition contained in MACROS.CNF (which happens to do nothing) can be commented out or modified as desired.


EndOpen

The EndOpen macro is triggered when Origin is directed to start by opening a specific project (files of type *.OPJ or *.ORG).  To automatically open a specific project when starting Origin you specify the project name in the Window's Start:Run dialog box or in the Target text box of an Origin shortcut's Properties window.  For example, typing

C:\Origin60\Origin60.exe MyProject.opj

in the Window's Start:Run dialog box and clicking OK, starts Origin and automatically opens the project MYPROJECT.OPJ.  When Origin is directed to start by opening a specific project, the EndOpen macro is executed immediately after Origin is started and the specified project is fully opened.  The EndOpen macro is unique in that a define statement for the EndOpen macro must be contained in a configuration file (files of type *.CNF) and be executed during the Origin start up procedure to ensure that the macro is defined in time for its triggering event.  The file MACROS.CNF (found in the Origin software folder) contains a commented out define statement for the EndOpen macro which can be uncommented and modified to insure timely definition.


EndToolbox

The EndToolbox macro is triggered after the getpts [options] npts [(message)] command has been issued and npts points have been selected.  A point is selected when you double-click on or select with the left or right ARROW key and press ENTER on a data point of the active dataset (for the Data Reader tool) or on any point in the active graph window (for the Screen Reader tool).  If you choose to define your own PointProc macro after issuing the getpts command, you must call the EndToolbox macro yourself after npts points have been selected or it will not be triggered.  This is because the call for the EndToolbox macro is contained in the PointProc macro that is defined by Origin when the getpts command is issued.  The EndToolbox macro is deleted immediately after it is triggered and executed.


ErrorProc

The ErrorProc macro is triggered when the LabTalk interpreter detects a #Command Error, when you click the Cancel button in any dialog box, or when you click the No button in dialog boxes that do not have a Cancel button.  The ErrorProc macro is deleted immediately after it is triggered and executed. The ErrorProc macro is useful for error trapping.


PointProc

The Data Reader tool or the Screen Reader tool must first be selected before the PointProc macro can be triggered.  These tools can be selected by clicking on their buttons (on the Tools toolbar) or by executing the getpts [options] npts (message)] or dotool tool# commands.  Note that the getpts command defines the PointProc macro for use itself when it is executed.  Consequently, if you use the getpts command and wish to define your own PointProc macro, you must define your version of the PointProc macro after you issue the getpts command.  After the Data Reader tool or the Screen Reader tool is selected, the PointProc macro is triggered whenever you double-click on or select with the left or right ARROW key and press ENTER on a data point of the active dataset (for the Data Reader tool) or on any point in the active graph window (for the Screen Reader tool).  The PointProc macro is deleted immediately after it is triggered and executed.


QuitToolbox

The QuitToolbox macro is triggered whenever a new Tools toolbar tool (other than the Data Reader tool, the Screen Reader tool, or the Data Selector tool) is selected and then used. The QuitToolbox macro is deleted immediately after it is triggered and executed.  For more information, see the getpts command.


TimerProc

The TimerProc macro is triggered every cycleLength seconds after executing the timer <cycleLength> command.  The maximum cycleLength is 56 seconds.  Use the timer -k command to turn off the timer and disable the TimerProc trigger.


Predefined System Macros

When Origin starts up it predefines a number of system macros.  The define commands for most of these macros are contained in *.CNF files (for example ORGSYS.CNF, MACROS.CNF, etc.) which can be found in the Origin software folder.  You can re-define system macros - although it is not recommended because Origin uses them as well.  At the very least, you should proceed with extreme caution when you modify a system macro so that no unintended consequences are created.

Some predefined system macros are specialized and are intended to only be used by Origin.  Predefined macros that have no practical value to you, that are anachronistic, or that are not entirely functional are not documented in the following sections.  Other predefined macros that are used by Origin may also be of general value or have practical value to you.  These macros are available to be called by your own scripts and are documented in the following pages of the Help file.

More:

ArrangeLayers numrows numcols

BeforeIterate

BeginSave

CheckMargins

CheckVar varname value

CheckWksSelection

ClearWorksheet worksheetName

Clr

DBCPage

DoButton objectName

Enlarger.Ctrl

FilterImport fileExtType

FormatFilterImport fileExtType fileExtType

GetEnumTempWks template winName

GetEnumWin winName

GetEnumWks winName

GetNamedPlot winName template

GetNamedWin winName

GetNamedWks winName template

Graph dataset

HelpMarker

HideMarker

IconizeNamedWks winName

LSqFit

MvPts dataset

New dataset numPoints

NewFunction

NotReady

NoYOffset

OneQCLine lineNameValue

Pick1Pt

QCLines average

Rescale

Separator numberOfTabs

SetDataRange dataset

SetXYOffset minimumOffset

TestColSet

TimerError

Watch


ArrangeLayers numrows numcols

Arranges all unlinked layers and linked layers having units % of linked layer into numrows rows and numcols columns.  Sets units of all layers to % of page.  Assumes that the CheckMargins macro is executed just prior to its execution.  Will not add layers to pad out up to numrows*numcols layers.

Def ArrangeLayers {

  x = 100 - Left - Right - (%2-1)*xGap;

  x/=%2;      	// calculate width in % of page

  y = 100 - Top - Bottom - (%1-1)*yGap;

  y/=%1;	// calculate height in % of page

  if (x < 5 || y < 5) {

    ty -b "Resulting layers are too small, operation aborted!";

    break 1;

  };

  k = 0;

  for (i = 1; i <= %1; i+=1) {	// loop for %1 rows of layers

    for (j = 1; j <= %2; j+=1) {	// loop for %2 columns of layers

      for (k+=1;k <=page.nlayers;k+=1) {

// loop through all layers in page

        #!k=;

        layer -s k;

        if (layer.link == 0 || layer.unit != 7) break;

// select unlinked layers

      };	// or linked layers having units

// % of linked layer

      layer -u 1;

      if (%2==1) { 	// if only 1 column

        layer x y [Left+(j-1)*(x + xGap)] [Top+(%1 - i)*(y + yGap)];

      }

      else {	// if more than 1 column

        layer x y [Left+(j-1)*(x + xGap)] [Top+(i-1)*(y + yGap)];

      };	// end else

    };	// end columns for loop

  };	// end rows loop

};	// end def

Example:

The following script arranges 12 unlinked layers in the active graph window into 4 rows and 3 columns.

CheckMargins;

ArrangeLayers 4 3;


BeforeIterate

Sets the active layer in the active window to 1.

Def BeforeIterate {Layer -S 1};

Example:

The following script counts the datasets in layer 1.

nlay1dats=0;

BeforeIterate;

doc -e D {

  nlay1dats+=1;

};


Macro Reference - Predefined System Macros - BeginSave
BeginSave

Moves the active window to the end of the Window menu window list.

Def BeginSave {Win -L 0};

Example:

The following script moves the active window to the end of the Window menu window list.

BeginSave;


CheckMargins

Checks to see if the variables Top, Left, Right, Bottom, xGap, and yGap are initialized.  If they are not initialized, it initializes them to the values 10, 15, 10, 15, 5, and 5 respectively.  CheckMargins is intended to be executed just prior to executing the ArrangeLayers macro.

Def CheckMargins {CheckVar Top 10;

  CheckVar Left 15;

  CheckVar Right 10;

  CheckVar Bottom 15;

  CheckVar xGap 5;

  CheckVar yGap 5;

};

Example:

The following script separately initializes the variables Left and Bottom to 10, initializes the variables Top, Bottom, xGap, and yGap to their default values described above, and then executes the ArrangeLayers macro.

Left=10;

Bottom=10;

CheckMargins;

ArrangeLayers 4 3;


CheckVar varname value

Checks to see if the variable varname exists.  If it does exist, Checkvar does nothing.  If it does not exist, Checkvar creates the variable varname and assigns it the value value.

Def CheckVar {if (exist(%1) != 4) %1=%2;};

Example:

The following script checks to see if the variable flag exists.  If flag exists, it does nothing.  If it doesn't exist, it creates flag and assigns it a value of 1.

CheckVar flag 1;


CheckWksSelection

Checks to see if you have selected all or part of a single Z column in the active worksheet.  If not, an error message is printed to a message box.  If so, it sets the variables nZcol, nYcol, and nXcol to their respective column number designations.

Def CheckWksSelection {

  if (wks.c1!=wks.c2 || wks.c1==0 || wks.col$(wks.c2).type!=6) {

    type -b "You must select a single Z column";

    break 1;

  };

  nZCol=wks.c2;	// z col is selected z col

  nYCol=%(%H,@Y-,wks.c2);

// y col is immediately to left of z col

  nXCol=%(%H,@X,nYCol);

// x col is first x col in worksheet

};

Example:

Given an active worksheet window with columns A(X1), B(X2), C(Y2), D(Y2), and E(Z2), the following script sets the variable nZcol equal to 5, nYcol equal to 4, and nXcol equal to 1.

CheckWksSelection;


ClearWorksheet worksheetName

Clears the worksheet worksheetName and sets the number of rows to 30.

Def { win -o %1 {work -s};  set %1 -er 30;  set %1 -begin 0;set %1 -end 0;

  set %1 -Update;doc -LP %1;

};

Example:

The following script clears the Data1 worksheet.

ClearWorksheet Data1;


Clr

Forces an update of the active graph window.

Def CLR {plot -CLEAR};

Example:

The following script forces an update of the active graph window.  This is the equivalent of the Window:Refresh command.

Clr;


DBCPage

Opens the Plot Details dialog box with the page icon selected on the left side of the dialog box.

Def  DBCPage {Page};

Example:

The following script opens the page's Plot Details dialog box.

DBCPage;


DoButton objectName

Run the associated script of the object objectName.

Def  DoButton {

  draw -n %1 -r;

};

Example:

The following script runs the associated script of the NewLabel object.

DoButton NewLabel;


Enlarger.Ctrl

Creates the ZoomRect object in the active graph window.  It also creates a graph window named Enlarged.  The Enlarged window represents the portion of the original active graph window covered by the ZoomRect object.  You can alter the portion of the original graph window that is covered by the ZoomRect object by clicking on the Enlarger tool while pressing CTRL and then dragging out the desired rectangle in the window.

Def  Enlarger.Ctrl {

  %B=%H;

  layer -c; //count datasets in active layer, concat names into %Z

  active = page.active;

  doc -e Open (win -i); // iconize non minimized windows

  GetNamedWin  Enlarged; // create or activate graph window

  layer -i;

// clean stored style to ensure proper plot info to be added

  UserPlot.text$="%B";

// Store User's Plot name into a memory object

  layer -i %Z; // plot all layers into Enlarged graph window

  win -a %B; // activate unenlarged graph window

  layer -s active; // activate layer active

  label -p 50 50; // create label in middle of layer

  draw -n ZoomRect -File Read ZoomRect.OGO; // read object

  win -system Tile;

  ZoomRect.script=0;

  ZoomRect.dx=(v3-v1);

  ZoomRect.dy=(v4-v2);

  ZoomRect.x=(v1+zoomrect.dx/2);

  ZoomRect.y=(v2+zoomrect.dy/2);

  ZoomRect.script=4;

  draw -n ZoomRect -Run;

};

Example:

The following script activates the ZoomRect object in the active graph window.

Enlarger.Ctrl;


FilterImport fileExtType

Opens the Open dialog box with the default file extension fileExtType and then imports the selected file.  This macro only works with Lotus *.WK? files, *.DIF files, and Quatro *.WKQ files.

Def FilterImport {

  GetFileName *.%1;

  open -WF %A

};

Example:

The following script opens the Open dialog box with the default file type extension of .wk1 and then imports the selected file.

FilterImport wk1;


FormatFilterImport fileExtType fileExtType

Opens the Open dialog box with the default file extension fileExtType and then imports the selected file.  This macro only works with Excel *.XLS? files and dBASE *.DBF? files.  You must type fileExtType twice.

Def  FormatFilterImport {

  GetFileName *.%2;

  open -WE %1 %A

};

Example:

The following script opens the Open dialog box with the default file type extension of .xls1 and then imports the selected file.

FormatFilterImport xls1 xls1;


GetEnumTempWks template winName

Counts the number of worksheet windows that exist and match exactly or begin with the name winName.  If no worksheet exists, it creates a worksheet with the name winName1 from the worksheet template template.  If n worksheets exist, it creates a worksheet with the name winName$(n+1) from the template template.

Def GetEnumTempWks {

  doc -cw %2;

  %A=%2$(count+1);  //Set %A to be the name of the new window

  win -th Wks %1 %A;

};

Example:

Assuming that no worksheet windows exist which begin with the name MyData, the following script creates three worksheets named MyData1, MyData2, and MyData3 from the template ORIGIN.OTW.

GetEnumTempWks Origin MyData;

GetEnumTempWks Origin MyData;

GetEnumTempWks Origin MyData;


GetEnumWin winName

Counts the number of graph windows that exist and match exactly or begin with the name winName.  If no graph window exists, it creates one with the name winName1.  If n graph windows exist, it creates one with the name winName$(n+1).  If winName also happens to be the name of a graph template, it will create the graph window from the template WINNAME.OTP.  Otherwise, it will use the default template ORIGIN.OTP.

Def GetEnumWin {

  doc -cp %1;win -T Plot %1 %1$(count+1)

};

Example:

Assuming that no graph windows exist which begin with the name MyGraph, the following script creates three graph windows named MyGraph1, MyGraph2, and MyGraph3 from the template ORIGIN.OTP, unless MYGRAPH.OTP exists, in which case it will be used.

GetEnumWin MyGraph;

GetEnumWin MyGraph;

GetEnumWin MyGraph;


GetEnumWks winName

Counts the number of worksheet windows that exist and match exactly or begin with the name winName.  If no worksheet window exists, it creates one with the name winName1.  If n worksheet windows exist, it creates one with the name winName$(n+1).  If winName also happens to be the name of a worksheet template, it will create the worksheet window from the template WINNAME.OTW.  Otherwise, it will use the default template ORIGIN.OTW.

Def GetEnumWks {

  doc -cw %1; win -T Wks %1 %1$(count+1)

};

Example:

Assuming that no worksheet windows exist which begin with the name MyData, the following script creates three worksheet windows named MyData1, MyData2, and MyData3 from the template ORIGIN.OTW, unless MYDATA.OTW exists, in which case it will be used.

GetEnumWks MyData;

GetEnumWks MyData;

GetEnumWks MyData;


GetNamedPlot winName template

Checks to see if the graph window winName exists.  If so, it makes the graph window winName the active window.  If not, it creates a graph window named winName from the template template.

Def GetNamedPlot {

  if (exist(%1)==3) win -active %1; else win -T Plot %2 %1;

};

Example:

Assuming that no graph window with the name MyGraph1 exists, the following script creates the graph window MyGraph1 from the template MYTEMPLATE.OTP.  After making the graph window SomeOtherGraph the active window, the script re-activates the graph window MyGraph1.

GetNamedPlot MyGraph1 MyTemplate;

Win -a SomeOtherGraph;

GetNamedPlot MyGraph1 MyTemplate;


GetNamedWin winName

Checks to see if the graph window winName exists.  If so, it makes the graph window winName the active window.  If not, it creates a graph window named winName from the default template ORIGIN.OTP.

Def GetNamedWin {

  if (exist(%1)==3) win -active %1; else win -T Plot %1 %1;

};

Example:

Assuming that no graph window with the name MyGraph1 exists, the following script creates the graph window MyGraph1 from the default template ORIGIN.OTP.  After making the graph window SomeOtherGraph the active window, the script re-activates the graph window MyGraph1.

GetNamedWin MyGraph1;

Win -a SomeOtherGraph;

GetNamedWin MyGraph1;


GetNamedWks winName template

Checks to see if the worksheet window winName exists.  If so, it makes the worksheet window winName the active window.  If not, it creates a worksheet window named winName from the template template.

GetNamedWks {

  if (exist(%1)==2) win -active %1; else win -T WKS %2 %1;

};

Example:

Assuming that no worksheet window with the name MyData1 exists, the following script creates the worksheet window MyData1 from the template MYTEMPLATE.OTW.  After making the worksheet window SomeOtherWks the active window, the script re-activates the worksheet window MyData1.

GetNamedWks MyData1 MyTemplate;

Win -a SomeOtherWks;

GetNamedWks MyData1 MyTemplate;


Graph dataset

Adds the dataset dataset to the layer contents in the active layer of the active graph window.  In effect, this plots the dataset dataset in the active layer of the active graph window.

Def  Graph {

set %1 -s 1;layer -i %1

};

Example:

The following script plots the dataset MyData1_C in the active layer of the active graph.

Graph MyData1_C;


HelpMarker

Puts instructions on how to use the Data Selector tool on the status bar.

Def  HelpMarker {

  doTool -h Move with Ctrl-ArrowKeys, shift with ArrowKeys, hit Enter when\  OK;doToolbox -next;

};

Example:

The following script puts instructions on how to use the Data Selector tool on the status bar.

HelpMarker;


HideMarker

Removes the Data Markers from the active graph window.  This macro is currently not operational.

Def  HideMarker {MkS1=-1};


IconizeNamedWks winName

Checks to see if a worksheet named winName exists.  If a worksheet with the name winName exists, it minimizes it.  If a worksheet with the name winName does not exist, it creates one and then minimizes it.

Def  IconizeNamedWks {

  if (exist(%1)==2) {

    win -o %1 {win -i};

  }

  else {

    win -n data %1;

    win -i;

  };

};

Example:

Assuming that no worksheet with the name MyData1 exists, the following script creates a worksheet named MyData1 and then minimizes it.

IconizeNamedWks MyData1;


LSqFit

Performs a nonlinear least squares fit of the active dataset.  The fitting function must be previously specified using the NLSF -f command.  Depending on the type of fit, additional parameters may also need to be specified.

Def  LSqFit {

  nlsf -H %C;nlsf -1;nlsf -2;nlsf -3;if(step > 4) (step/=2;nlsf -1;nlsf -2);

  if (step>1) (step=1;nlsf -2);nlsf -2;nlsf -t;

};

Example:

The following script performs an exponential decay fit (ExpDec1) on the active dataset.

NLSF -f ExpDec1;

LSqFit;


MvPts dataset

Opens the Data Reader tool and places it in the active graph window.  Writes usage information on the status bar.  If the dataset dataset has moveable points, it will allow you to move its data points by clicking and dragging them with the Data Reader tool.

Def  MvPts {

  def PointProc {{EndToolbox};doTool 0};

  doTool -cntrl 3 (Move with arrow keys, hit Enter when OK);

  doToolbox -r %1;doToolbox -key;

};

Example:

The following script sets the data points of the dataset MyData1 as moveable and then executes the MvPts macro allowing its data points to be moved with the Data Reader tool.

Set MyData1 -m 1;

MvPts MyData1;


New dataset numPoints

Creates an empty dataset named dataset having numPoints data points.  To verify the existence of the dataset dataset, use the List S command in the Script window.  To create a worksheet from the dataset dataset, use the Edit dataset command in the Script window.

Def  New {

  create %1 -n %2;

  set %1 -e %2;

};

Example:

The following script creates the dataset MyData1_B with 400 data points.  It then creates the worksheet MyData1 containing the column B.

New MyData1_B 400; // create dataset

Edit MyData1_B; // create worksheet


NewFunction

Counts the number of datasets that begin with the letter F (function datasets) and opens the function's Plot Details dialog box to create a new function named Fn where n is one more than the number of datasets counted.  If the FUNCTION.OTP graph template is not opened before executing NewFunction, then the function dataset Fn is created but not plotted.

Def NewFunction {

  doc -cs F;%B=F$(count+1);create %B -f 10;

  def ErrorProc [del %B];set %B;del -m ErrorProc;

};

Example:

The following script creates a new graph window from the FUNCTION.OTP template and then creates and plots a new function named F1 (assuming that no other function datasets already exist).

GetEnumWin Function;

NewFunction;


NotReady

Displays the message "This operation is still under development..." in a dialog box with an OK button.

Def  NotReady {

  ty -b "This operation is still under development...";

};

Example:

The following script displays the message "This operation is still under development..." in a dialog box with an OK button.

NotReady;


NoYOffset

Initializes the variables p1 and pv1 to zero.

Def  NoYOffset {

  p1=0;pv1=0

};

Example:

The following script initializes the variables p1 and pv1 to zero.

NoYOffset;


OneQCLine lineNameValue

Draws a horizontal line at Y=lineNameValue across the active graph window.  The line is labeled with its given name and its value (i.e. lineNameValue=$(lineNameValue) or CL=$(lineNameValue) ).  Window:Refresh or the doc -uw command should be executed after OneQCLine is run to update the graph window.  OneQCLine is used by the template QC.OTW which is used to create QC charts.

Def  OneQCLine {

  draw -Name QC.%1 -L %1;

  if (page.active==2&&%1=="Ave")

    label -Offset 2 (-10) -Coor X2 %1 -s -n TQC.%1 (CL =     $(%1,*4*));

  else

    label -Offset 2 (-10) -Coor X2 %1 -s -n TQC.%1 (%1 = $(%1,*4*));

}

Example:

The following script draws a horizontal line at Y=5 in the active graph window and then names and labels the line UCL=5.

UCL=5;

OneQCLine UCL;


Pick1Pt

Opens the Data Reader tool and places it in the active graph window.  Writes usage information on the status bar.  If you click on a data point and press ENTER (or double-click on a data point), the temporary datasets _INDX and _XPOS are created.  The dataset _INDX contains the row index of the data point clicked on and the dataset _XPOS contains the X value of the data point clicked on.

Def  Pick1Pt {

  GetPts 1 $EXEmessage.Pick1Pt

};

Example:

The following script executes the macro Pick1Pt.

Pick1Pt;

Executing the script:

XPOS=_XPOS;

INDX=_INDX;

edit XPOS;

edit INDX;

immediately after executing the Pick1Pt macro, copies the temporary datasets into permanent datasets and then displays the permanent datasets.


QCLines average

Draws, names, and labels three horizontal lines (in the active graph window) at Y=Ave=average, Y=UCL, and Y=LCL.  This macro is used by the QC.OTW worksheet template which is used to create QC charts.  The value Ave is passed as a parameter to the QCLines macro and the values UCL and LCL are normally calculated by invoking Plot:Statistical Graphs:QC (X bar R) Chart menu command.

Def  QCLines {

  Ave = %1;

  OneQCLine Ave;

  OneQCLine UCL;

  OneQCLine LCL;

};

Example:

The following example draws, names, and labels (in the active graph window) three horizontal lines at Y=1, 4 and 6.

UCL=6;

LCL=4;

QCLines 1;


Rescale

Rescales the X and Y axes of the active layer to show all data.

Def Rescale {layer -all};

Example:

The following script sets layer 2 as the active layer, plots the dataset MyData1_B into the layer, and then rescales the layer to show all data.

layer -s 2;                   // make layer 2 active

layer -i Mydata1_B;   // add MyData1 to layer 2

Rescale;                     // rescale layer 2


Separator numberOfTabs

Prints a separating line consisting of a series of dashes across the Script window.  NumberOfTabs is the approximate length of the line measured in tabs.

Def Separator {

  repeat %1 {

    type -L "---------------"

  };

  ty;

};

Example:

The following script prints a separator line (approximately 3 tabs in length) above and below some text which is written to the Script window.

Ave=7;

Npts=100;

Separator 3;

ty -a "Average          Number of Points";

ty -a  $(Ave)                $(Npts);

Separator 3;


SetDataRange dataset

Sets the X value for the first data point and the X increment for the dataset dataset.

Def  SetDataRange {

  set %1 -f fitX1;

  set %1 -i [(fitX2-fitX1)/(fitnpts-1)]

};

Example:

The following script creates a dataset named MyData1_B, fills it with data values starting at 10 and incrementing by 10 up to 1000, sets the X value for the first data point and the X increment for the dataset MyData1_B, and then displays the dataset in its worksheet.

Mydata1_B=data(10,1000,10);

fitX1=10;

fitX2=1000;

fitnpts=100;

SetDataRange MyData1_B;

edit MyData1_B;


SetXYOffset minimumOffset

Computes and sets the minimum X offset (x0) and the minimum Y offset (y0).  If the beginning X value or minimum Y value is less than minimumOffset*100 percent of the X (or Y) data range, then the minimum X (or Y) offset is set to zero.

Def  SetXYOffset {

  minoffset = %1;

  x0 = limit.xmin;

  if (abs(x0/(limit.xmax-x0)) < minoffset) {

    x0 = 0

  };

  y0 = limit.ymin;

  if (abs(y0/(limit.ymax-y0)) < minoffset) {

    y0 = 0

  };

  del -v minoffset;

  #!x0=;y0=;

};

Example:

The following script computes and sets the minimum X and Y offsets.  If the beginning X value or minimum Y value is less than 10 percent of the X (or Y) data range, then the minimum X (or Y) offset is set to zero.

SetXYOffset 0.1;


TestColSet

Checks to see if a single (or part of a single) dataset is selected.  If so, nothing is done.  If not, the currently executing script is terminated.

Def TestColSel {

  if (exist(%C)!=1 || SelC2 > SelC1) {

    type -b "$general.Only1YColumn";

    break 1;

  };

};

Example:

The following script checks to see if a single dataset is selected.  If so, it integrates the selected dataset and prints the results in the Script window.  If not, an error message is printed out and the script is terminated.

TestColSel;

integ %C;

if (MkS1>=0) {

  i1=MkS1;

  i2=MkS2;

}

else

{

  get %C -b i1;

  get %C -e i2;

};

ty -a Integ of %C from zero;

ty "i = $(i1) --> $(i2)";

ty "x = $(integ.x1) --> $(integ.x2)";

ty "Area    Peak at    Width    Height";

ty "$(integ.area)    $(integ.x0)    $(integ.dx)    $(integ.y0)";


TimerError

Displays the message "Timer Stop" in the status bar, stops executing the TimerProc macro, and removes the current timer.

Def  TimerError {ty -q $EXEmessage.TimerStop;timer -k};

Example:

The following script removes the current timer.

TimerError;


Watch

Displays the elapsed time in seconds in the Script window since Windows startup, since the previous time Watch was run, or since the second -i command was executed, which ever is most recent.

Def  Watch {seconds -e v1;type $EXEmessage.ElapsedTime};

Example:

The following script starts a timer, executes a long loop, and then executes the Watch macro displaying the elapsed time in seconds that it took the loop to complete itself.

Second -i;

Loop (ii,1,10000) {ty -q $(ii)};

Watch;


A numeric variable is an identifier that has a single value associated with it.


LabTalk string variables %A-%Y have a 266 character size limit.  %Z has an 8191 character size limit.


When expressing a string variable, the string variable is replaced with its current value.


A token is a group of characters surrounded by white space, enclosed by brackets, or separated by a separator.


In contrast to C convention, the LabTalk index number starts at 1.


Worksheet column names cannot exceed 11 characters.


The ternary operator can be used as a type of specialized if-else decision structure.


When referring to a worksheet, do not specify n.


The matrix window appearance is controlled by the page and worksheet object properties.