2.5.1.2 From Files

From-Files

Run Script from FileLabTalk script usually requires an Origin Object and are thus restricted to an open project. Scripts can also be saved to a file on disk to be called from any project. Script files can be called with up to five arguments. This section outlines the use of LabTalk scripts saved to a file.

Creating and Saving Script FilesSave Script Filescript files, creating/savingCreate Script File

LabTalk scripts can be created and saved from any text editor, including Origin's Code Builder. To access Code Builder, select the icon from the Standard Toolbar. Create a new document of type LabTalk Script File and type or paste your code into the editor window and then save with a desired filename and path (use the default OGS file extension).

The OGS File Extension

LabTalk scripts can be saved to files and given any extension, but for maximum flexibility they are given the OGS file extension, and are therefore also known as OGS files. You may save script files to any accessible folder in your file system, but specific locations may provide additional advantages. If an OGS file is located in your User Files Folder, you will not have to provide a path when running your script.

An OGS file can also be attached to the Origin Project (OPJ) rather than saving it to disk. The file can be added to the Project node in Code Builder and will then be saved with the project. Drag the filename from the User folder and drop into the Project folder. Script sections in such attached OGS files can be called using the run.section() object method similar to calling sections in a file saved on disk. Only the file name needs to be specified, as Origin will first look for the file in the project itself and execute the code if filename and section are found as attachments to the project.

Sections in an OGS FileSectionScript Section

Script execution is easier to follow and debug when the code is written in a modular way. To support modular scripting, LabTalk script files can be divided into sections, which are declared by placing the desired section name in square brackets [ ] on its own line:

[SectionName]

Lines of script under the section declaration belong to that section. Execution of LabTalk in a section ends when another section declaration is met, when a return statement is executed or when a Command Error occurs. The framework of a typical multi-section OGS file might look like the following:

[Main]
// Script Lines
ty In section Main;

[Section 1]
// Script Lines
ty In section 1;

[Section 2]
// Script Lines
ty In section 2;

Note here that ty issues the type command, which is possible since no other commands in Origin begin with the letters 'ty'.

Running an OGS File

Run an OGS File

Use the run object to execute script files.

run.section(OGSFileName, SectionName[,arg1 arg2 ... arg5])

run.file(OGSFileName)

Thus, if you save a file called test.ogs to your Origin User Files folder:

// Runs test.ogs with run.file() syntax:
run.file(test)
// Runs only section1 of test.ogs with run.section() syntax:
run.section(test, section1)

if the file test.ogs is saved under D:\OgsFiles:

// Runs test.ogs with run.file() syntax:
run.file(D:\OgsFiles\test)
// Runs only section1 of test.ogs with run.section() syntax:
run.section(D:\OgsFiles\test, section1)

Note: A different means to run an OGS file is to recognize it as an object. After saving the OGS file, you need to run the cd X-Function (cd 1;) to change to the folder where the file was saved or use dir to list files in the current working folder - if that is where the file is. Otherwise, Origin does not detect the file and will not see it as a runnable command.

After Origin recognizes an OGS filename as an object, run the OGS file by entering its name or name.sectionname into the Script Window or Command Window. If either the file name or section name contains a space quotes must surround both. For example:

// Run a LabTalk Script named 'My Script.ogs' located in the folder 
//'D:\OgsFiles'.

// Change the current directory to 'D:\OgsFiles'
cd D:\OgsFiles; // This causes Origin to scan that folder for OGS files
// This runs the code in section 'Beta Test' of 'My Scripts.ogs'
// passing three arguments separated by spaces (protected by quotes where needed)
"My Scripts.Beta Test" "Redundant Test" 5 "Output Averages";

There are many examples in Origin's Samples\LabTalk Script Examples folder which can be accessed by executing:

cd 2;

Passing Arguments in ScriptsArgument, Script FilePass Arguments in Script

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

When passing arguments to script file sections or to macros:

• The section call or the macro call must include a space between each argument being passed. When using run.section, a comma must separate the section name from the first argument only.

• When you pass literal text or string variables as arguments, each argument must 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, separated by Space, 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 like string variables in that they are substituted prior to execution of the command in which they are embedded. The number of arguments passed is contained in macro.narg.

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);

Here, %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 ReferencePass 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 column B 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 column B (starting at the current last row), 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.

See example:

If a TEST.OGS file includes the following section:

[adddata]	
	loop (n, 1, 5)
	{
	    %1[%2 + n] = 100;
	};
	%2 = %2 + (n - 1);
	return 0;

And you execute the following script:

col(b) = data(1, 10);   // fill data1_b with values
get col(b) -e lastrow;  // store last row of values in lastrow
run.section(test.ogs, adddata, col(b) lastrow);
lastrow = ;

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

Passing Numeric Variables by ValuePass 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, the entire expression would require calculation each time it was interpreted.

In the following script file example, numeric variable var 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.

[typing]
	type -b "The value of %1 = %2 %3";
	return 0;

Save the section to Test.OGS and run the following script on command window:

var = 22;
%A = "degrees Celsius";
run.section(test.ogs, typing, var $(var) "%A");

Then a dialog box pop-up and says: "The value of var = 22 degrees Celsius".

Guidelines for Naming OGS Files and Sections

Naming rules for OGS script files differ based on how they will be called. The section above discusses the two primary methods: calling using the run.section() method or the command method which entails calling directly from the Script or Command window (not recommended).

When Using the Run.section() Method

• There is no restriction on the length or type of characters used to name the OGS file.
• Specifying the filename extension is optional for files with the OGS extension.
• When using run.section( ) inside an OGS file to call another section of that same OGS file, the filename may be omitted, for instance:

[main]
run.section( , calculate);

[calculate]
cc = aa + bb;

When Using the Command Method

• The name of the OGS file must conform to the restrictions on command names: 25 characters or fewer, must not begin with a number or special character, must not contain spaces or underscore characters.
• The filename extension must be OGS and must not be specified.

Section Name Rules (When Using Either Method)

• When SectionName is omitted,

1. Origin looks for a section named [Main] and executes it if found
2. If no [Main] section is found, but code without a section name exists at the beginning of the file, then that code is executed.
3. Otherwise Origin does nothing and does not report an error.

Do not give an OGS file the same name as an existing Origin function or X-Function!

Setting the Path

In Origin 7.5, script files (*.OGS) could be run from both the Origin System and User Files folders, and these are the current working directorycurrent working folder by default. If your script file resides there, there is no need to change the pathSet Path. If the script file was not located in either of these two folders, the full path needed to be specified in the run.section() object method. Since Origin 8, the idea of the Current Working Folder (CWF) was introduced, allowing you to run your own script files and X-Functions located in the CWF you have specified.

Per MS-DOS convention, Origin uses the cdcd X-Function to display the CWF:

// Entering this command displays the current working folder 
// in the Script Window. 
cd

and unless it has been changed, the output is similar to:

current working directory:
C:\Documents and Settings\User\My Documents\OriginLab\Origin8.1\User Files\ 

However, if you write many scripts, you will want to organize them into folders, and call these scripts from where they reside. Also, Origin provides sample scripts that you may want to run from their respective directories.

In the case or run.section( ) scripts can reside in subfolders of the User Files Folder and you can use relative referencing such as:

run.section(subfolder1\scriptA,main); // ScriptA.ogs is in subfolder1
run.section(subfolder2\scriptA,main); // ScriptA.ogs is in subfolder2

You can set the Current Working Folder from script. For example, to run an OGS file named ave_curves.ogs, located in the Origin system sub-folder Samples\LabTalk Script Examples, enter the following:

// Create a string variable to hold the complete path to the desired
//script file
// by appending folder path to Origin system path:
path$ = system.path.program$ + "Samples\LabTalk Script Examples\";
// Make the desired path the current directory.
cd path$;
// Call the function
ave_curves;

You can create a set of pre-defined paths. The cdset X-Function is used to list all the pre-defined paths and add/change the CWF. By typing

// The 'cdset' command displays pre-defined paths 
//in the Script Window. 
cdset

you should see three paths like below if you have not changed them yet.

1 = C:\Documents and Settings\User\My Documents\OriginLab\Origin8.1\User Files\
2 = C:\Program Files\OriginLab\Origin81\Samples\LabTalk Script Examples\
3 = C:\Program Files\OriginLab\Origin81\ 

If you want to set the second path above to be the CWF, just type:

// Changes the CWF to the folder path specified
// by pre-defined path #2.
cd 2

To add a new path to pre-defined folder set, first change to the new path, making it the CWF, then add it to the set by using cdset X-Function with the specified index. For example:

cd D:\Files\Filetype\Script;  // Set this new path as CWF
// Add this path to pre-defined folder list, to the 4th postion (index 4)
// If there already is a path with index 4, it will be over-written
cdset 4;
// If the CWF is changed manually, it can now be reset to 
// 'D:\Files\Filetype\Script\' by entering 'cd 4'.

A few tips for working with the cdset command: Folder paths added to the pre-defined set in one project are saved for use with other projects. To see the current paths displayed to the Script Window, enter 'cdset' by itself on a line in the Script Window. Up to 9 pre-defined paths are supported. Indices can be assigned out of order. A new path, assigned to an index for which a current path exists, will overwrite the current path.

As the three default pre-defined paths show above, the second one contains several sample script files (with the OGS extension). Similar to DOS, you can go to this folder by cd 2, then see the valid OGS using the dir X-Function, and then run any available script file in this folder, such as:

// Set 2nd folder as the CWF
cd 2;
// List all ogs and X-Function in the CWF
dir;
// Run a script file
// Note that the file extension is not needed when calling it
autofit;

You can also load the script file in the CWF into Code Builder by using ed.open() method. Such as:

// In this case, the OGS extension on the filename is required!
ed.open(pick_bad_data.ogs)

Running LabTalk from Origin C

Besides running .OGS files directly, LabTalk commands and scripts can also be run from Origin C. For more information, please refer to LabTalk Interface global function of Origin C help document.