1.4.4 Using Compiled Functions

Functions, ExecutionOnce Origin C functions have been compiled, linked and loaded, they are ready to be used in Origin. This means calling the function by its name and providing the necessary arguments from any location in Origin that accepts LabTalk script commands. Common locations include the script window, the command window, or a custom button in the Origin GUI. Running Scripts chapter of the LabTalk Scripting Guide details all of the locations in Origin from which script, and therefore Origin C functions, can be used.

Accessing Origin C Functions from LabTalk ScriptFunctions, Calling Origin C Function from Script

Origin C functions can be called from other Origin C functions and from LabTalk scripts. This section talks about how to control the access to Origin C functions from LabTalk.

For information about accessing LabTalk from your Origin C code, refer to the Accessing LabTalk chapter.

Origin C Access from LabTalkFunctions, Control LabTalk Access

You can control LabTalk access to your Origin C code by putting a pragma statement in your Origin C code before your function definitions.

#pragma labtalk(0) // Disable OC functions in LabTalk 
void foo0()
{
}

#pragma labtalk(1) // Enable OC functions in LabTalk (default)
void foo1()
{
}

#pragma labtalk(2) // Require '''run -oc''' LabTalk command 
void foo2()
{
}

The above code prevents foo0 from being called from LabTalk, allows foo1 to be called from LabTalk, and allows foo2 to be called from LabTalk using the run -oc command. If you were to comment out the second pragma, then both foo0 and foo1 would be prevented from being called from LabTalk. This is because a single pragma statement applies to all functions after the pragma and up to the next pragma or the end of the file.

There is also a LabTalk system variable that controls LabTalk access to all Origin C functions. The variable is @OC, and it defaults to 1, which enables access. Setting the variable to 0 disables access.

Listing Functions that can be Called from LabTalkFunctions, List All LabTalk Callable Origin C Functions

The LabTalk list command can be used to output all the names of Origin C functions that can be called from LabTalk. Options let you modify which type of functions is listed:

list f;  // List functions callable from LabTalk
list fs; // List only those returning a string
list fv; // List only those returning a vector
list fn; // List only those returning a numeric
list fo; // List only those returning void

Note that setting @OC=0 will make Origin C functions effectively invisible to LabTalk, such that the list fList Labtalk Callable Functions command will give no result.

Passing Arguments to Functions

Functions, Pass LabTalk Variable to Origin C by ReferenceFunctions, Pass LabTalk Variable to Origin C by ValueLabTalk script does not support all of the data types used internally by Origin C. The following table lists the LabTalk variable types that should be passed (or returned) when calling an Origin C Function with the given argument (or return) type. The final column indicates whether or not that argument type can be passed by reference.

* string arrays cannot be passed by reference

As the table above indicates, arguments of Origin C functions of type string, int, and double may be passed by value or by reference from LabTalk. Note, however, that the Origin C function must be written for the type of pass being performed.

Passing by Value

Below are examples of passing arguments by value from LabTalk to Origin C. The format for each example is to give the Origin C function declaration line, and then the LabTalk code used to call it. The Origin C function body is left out since it is unimportant for demonstrating variable passing.

The simple case of a function accepts an argument of type double and returns a double.

double square(double a)  // Origin C function declaration

double dd = 3.2;         // LabTalk function call
double ss = square(dd);
ss =;                    // ss = 10.24

Here, an Origin C function that takes a vector argument and returns a vector, is called by LabTalk using data set variables, or ranges that are assigned to data types.

vector<string> PassStrArray(vector<string> strvec)

Can be called three ways from LabTalk:

dataset dA, dB;
dB = Col(B);
dA=PassStrArray(dB);

Col(A)=PassStrArray(Col(B));  // Or, use Col directly, Col = dataset

// Or, LabTalk ranges may also be used
range ra = [Book1]1!1, rb = [Book1]1!2;
ra = PassStrArray(rb);

Passing by Reference

For the Origin C function below, note the ampersand & character in the argument declaration, indicating that the argument will be passed by reference.

double increment(double& a, double dStep)

double d = 4;
increment(d, 6);
type -a "d = $(d)";  // d = 10

The following example demonstrates some arguments being passed by reference and others being passed by value.

int get_min_max_double_arr(vector<double> vd, double& min, double& max)

dataset ds = data(2, 30, 2);
double dMin, dMax;
get_min_max_double_arr(ds, dMin, dMax);

//Or use a data set from a column; be sure to put data in Col(A)
get_min_max_double_arr(Col(A), dMin,  dMax);

The following example shows passing a LabTalk matrix range variable by reference to an Origin C function.

// set data from vector to matrix
void set_mat_data(const vector<double>& vd, matrix& mat)
{
	mat.SetSize(4,4);
	mat.SetByVector(vd);
}

range mm = [MBook1]1!1;
dataset ds = data(0, 30, 2);
set_mat_data(ds, mm);

Precedence Rules for Functions with the Same NameFunctions, Precedence Rules for the Same Name Functions

When a user-defined or global Origin C function has the same name as a built-in LabTalk function, the Origin C function has higher precedence, except when using LabTalk vector notation.

Precedence:

1. LabTalk Function (vector)
2. Origin C Function
3. LabTalk Function (scalar)

Thus, LabTalk functions like Normal and Data (which return a range of values and are thus used in vector notation) would have higher precedence than Origin C functions of the same name. In all other cases, the Origin C function is called.

Defining Functions for the Set Values DialogFunctions, Adding for Set Values Dialog F(x) menu

You may want to define a function using Origin C, that will appear in the Set Values menu of either a column or a matrix.

If an Origin C function is built as part of an Origin project---either automatically by being placed in the Project or System folder of Code Builder, or manually by building a function in the User folder---it will be available in the User-Defined section of the F(x) menu in the Set Values dialogs (for both Columns and Matrices). To assign a function to a different section of the F(x) menu, issue a pragma containing the new section name as part of the function header. For instance, the following code will add function add2num to the Math section and function mean2num to the Statistics section:

#pragma labtalk(1,Math)
double add2num(double a, double b)
{
	  return a + b;
}

#pragma labtalk(1,Statistics)
double mean2num(double a, double b)
{
	  return (a + b)/2;
}

In this way, many functions can be defined in a single source file and, upon building, be immediately available in the desired locations of the F(x) menu.

Functions to be added to the F(x) menu must conform to the following additional restrictions:

• The return type of the function cannot be void
• The function should not have reference or pointer (&) for argument type