DocExchangeDataFiles

DocExchangeDataFiles executes a data exchange for a complete document.

hDoc = DocExchangeDataFiles(hDoc, smMatrix)

hDoc = DocExchangeDataFiles(hvPage, smMatrix)

hDoc = DocExchangeDataFiles(hvPage, smMatrix, oPara)

Return Value

Document handle hDoc is returned. Returns 0 in case of error.

Parameters

hDoc

hDoc is a handle of an UniPlot document. hvPage is a vector with page handles.

smMatrix

smMatrix is a matrix with 7 columns:

Column	Alias	Description
1	DS_FILE_ORIGIN	Original data file name. For Excel files the sheet name can be added to the file name in square brackets.
2	DS_FILE_NCNAME	Name of the NC file.
3	DS_FILE_ACTION	Action string.
4	DS_FILE_STYLEPROPS	2D style attributes.
5	DS_FILE_STYLEPROPS3D	3D style attributes.
6	DS_FILE_COMMENT	Comment string.
7	DS_FILE_RECORDFILTER	Record filter: See auto_SetFilter

Valid values for the action string (see example and Data=>Data Exchange (Page)):

Value (String)	Description
""	(empty string), Exchange data.
"X"	Adds a data file based on file "X". X is the index of the reference file as given per DocGetDataFileList(hDoc)
"UNCHANGED"	ignore datasets.
"SETTOZERO"	set to 0.
"SETSTYLEONLY"	Only style properties will be set. The data points will not be modified.

oPara

oPara is an object created with obj_create. The object can be used to pass parameters. The default values are the last interactive specified values.

Element	Description
bUpdatePlaceholder	If TRUE (1): Dollar placeholders will be updated..
nRecordFilter	Value = 1: Use Record Filter specified in Data files, Value = 2:Use Record Filter specified in Datasets (Curve), Value = 3: Do not use Record Filter.
bAutoscale	If TRUE (1): All axes will be auto scaled.
bResetDatasetScaling	If TRUE (1): Scale factor and offset will be set to default values (1, 0).
bDisplayChannelReplaceDialog	If set to TRUE (1), a dialog box is displayed to replace missing channels by valid channels.

Example

RegisterCommand("Data", "MyDataExchange", "My Data Exchange");
UserBar_Add("MyDataExchange");
def MyDataExchange()
{
    hDoc = AppGetActiveDocument();
    if (hDoc == 0) {
        MessageBoxError("No active Document");
        return FALSE;
    }
    smF = DocGetDataFileList(hDoc);
    //File to be replaced
    smF[1;DS_FILE_ORIGIN] = "c:/programme/uniplot/samples/TEST4.xls [data]";
    smF[1;DS_FILE_COMMENT] = "This is a comment";
    smF[1;DS_FILE_ACTION] = "";  // Exchange data

    //File to be added
    rsMainFiletoCopy = 2 //The added file will be a copy of File 2
    smF_add = strempty(1;nc(smF)) //We create a new entry in smF
    smF_add[DS_FILE_ACTION] = ltostr(rsMainFiletoCopy);  // Base file to copy (index entered as string)
    smF_add[DS_FILE_ORIGIN] = "c:/programme/uniplot/samples/TEST5.xls [data]";
    smF = [smF;smF_add]

    //Setting up parameter object
    obj = [.];
    obj.nRecordFilter = 1;
    obj.bAutoscale = TRUE;

    //Execute data exchange
    DocExchangeDataFiles(hDoc, smF, obj);

   PageReplot(DocGetActivePage(hDoc));
    return TRUE;
}

History

Version	Description
R2025.1	Adding the possibility to add data file, not only exchange.
R2015.5	New column added: DS_FILE_RECORDFILTER
R2012.3	New parameter oPara
5.15.6	Can be invoked with a page handle to exchange the data for one or more pages.
5.11.0	New.

See also

Overview Documents, DocCreate, Data=>Data Exchange (Page), DocGetDataFileList, DocSetDataFileList, DocAddDatafiles

_id-608347