2.4.1.2 X-Function Input and Output

XF-Input-and-Output

X-Function Variables

X-Function VariablesX-Function InputInput, X-FunctionX-Function OutputOutput X-Function 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 argumentsX-Function ArgumentArgument, X-Function 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.):

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

Keyword for RangeRange Keyword

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