2.4.1.2 X-Function Input and Output

X-Function Variables

X-Functions accept LabTalk variable types (except StringArray) as arguments. In addition to LabTalk variables, X-Functions also use special variable types for more complicated data structures.

These special variable types work only as arguments to X-Functions, and are listed in the table below (Please see the Special Keywords for Range section below for more details about available key words.):

Variable Type Description Sample Constructions Comment
XYRange

A combination of X, Y, and optional Y Error Bar data

  1. (1,2)
  2. <new>
  3. (1,2:end)
  4. (<input>,<new>)
  5. [book2]sheet3!<new>
 For graph, use index directly to indicate plot range
(1,2) means 1st and 2nd plots on graph
XYZRange

A combination of X, Y, and Z data

  1. (1,2,3)
  2. <new>
  3. [book2]sheet3!(1,<new>,<new>)
ReportTree

A Tree based object for a Hierarchical Report
Must be associated with a worksheet range or a LabTalk Tree variable

  1. <new>
  2. [<input>]<new>
  3. [book2]sheet3
ReportData

A Tree based object for a collection of vectors
Must be associated with a worksheet range or a LabTalk Tree variable. Unlike ReportTree, ReportData outputs to a regular worksheet and thus can be used to append to the end of existing data in a worksheet. All the columns in a ReportData object must be grouped together.

  1. <new>
  2. [<input>]<new>
  3. [book2]sheet3
  4. [<input>]<input>!<new>

To understand these variable types better, please refer to the real examples in the ReportData Output section below, which have shown some concrete usages.

Special Keywords for Range

<new>
Adding/Creating a new object
<active>
Use the active object
<input>
Same as the input range in the same X-Function
<same>
Same as the previous variable in the X-Function
<optional>
Indicate the object is optional in input or output
<none>
No object will be created

ReportData Output

Many X-Functions generate multiple output vectors in the form of a ReportData object. Typically, a ReportData object is associated with a worksheet. Usually by default, it's the new sheet of same workbook as input data.

Sending ReportData to Worksheet

If the output is set to a range, either the above special range, or regular worksheet or column range, or mix of both, the ReportData will output to a worksheet.

The following script puts ReportData output to worksheets E.g. 

//To Sheet2 of Book2
//If the sheet doesn't exist, create it, 
//If the sheet already exists, output from the 1st empty column
fft1 rd:=[book2]sheet3!; 
// To new sheet of Book2 
fft1 rd:=[book2]<new>!;      
// To column 4 of active sheet in active book
fft1 rd:=[<active>]<active>!Col(4);  
// To a new sheet in input data's workbook
fft1 rd:=[<input>]<new>!;

Subsequent access to the data is more complicated, as you will need to write additional code to find these new columns.

Realize that output of the ReportData type will contain different amounts (columns) of data depending on the specific X-Function being used. If you are sending the results to an existing sheet, be careful not to overwrite existing data with the ReportData columns that are generated.

Sending ReportData to Tree Variable

Send ReportData to a Tree variable can avoid overhead of creating an worksheet to hold such output.

If the output is not one of the following range specification forms: [Book]Sheet!, <new>, or <active>, then it's automatically considered to be a LabTalk Tree name.

E.g. the avecurves X-Function contains a ReportData output with two leaves: aveX and aveY.

The script below does average on data in worksheet and output ReportData to a tree variable. The tree variable contains two vector leaves. Assign these two leaves to dataset variables and then plot the dataset variables as line graph. No extra worksheet or columns are created for output the average result. 

col(1)=data(1,20);  //fill col 1 with 1, 2, ... 20
int nn = 5; 
loop(i,2,nn){wcol(i)=normal(20);};  //fill column 2 to 5 with normalized data

//do average curves of columns from 2 to 5. Put output to a Tree variable tr
avecurves (1,2:$(nn)) rd:=tr; 
tr.=; // to see the tree structure with contents, aveX and aveY are vectors
//assign tree leaves to a temporary dataset variables
dataset avX = tr.Result.aveX;  
dataset avY = tr.Result.aveY;    

// Plot col2 to 5 as scatter plot, using the default-X column in worksheet
plotxy (?,2:nn) p:=201;   

//Add line plot with dataset variable avX as X and avY as Y to active graph
plotxy (avX, avY) o:=<active> p:=200;

Assigning Literal Strings to X-function Input

<[< and >]> are introduced to assign labtalk literal string to input variables of x-function. It is useful if the input strings include string registers or special characters, such as ', " or $ etc.

The scripts below show the difference of using <[< and >]> or not in x-function variables 

%A = "Mysplit";
wsplit mode:=ref ref:=[Book1]Sheet1!A"Fish" name:="%A";  //Result sheet name is Mysplit
wsplit mode:=ref ref:=[Book1]Sheet1!A"Fish" name:=<[<%A>]>; //Result sheet name is Fish 
//the name is set as %A, which is a predefined variable as the name of reference column in XF

The example below shows the usage of using "" in x-function input 

patternT text:=<[<"Sample A" "Sample B" "Sample C">]>;
English | Deutsch | 日本語