# File-Based I/O in MATLAB

The user-defined functions feature (UDF) gives you the ability to perform file-based IO. This lets you apply a function to a longer memory depth than would otherwise be allowed. (The limits for the number of points in input waveforms for MATLAB scripts and compiled MATLAB applications are 64 M points for a one-input operator, 32 M points for a two-input operator, 22.369621 M points for a three-input operator, and 16 M points for a four-input operator.)

For deep waveforms, you can instead use a file to pass the data in and out of a UDF. To use file-based IO, the MATLAB script needs to read from and write to a file.

In most cases, you will want to process a part of the source data at a time so as to not create internal MATLAB arrays that are too large.

Also, the .XML file must contain a keyword to tell the oscilloscope to use file IO. This line should be added to the .XML file that configures the oscilloscope:

    <FileIO>true</FileIO>

Instead of passing SrcData variables to MATLAB, the oscilloscope passes SrcDataFile variables. These variables are strings that are the file name and path to the files that contain source data.

In the MATLAB script, create a variable 'FiltDataFile' that is the path and file name of the resultant data.

The source and function data files are binary files of type 'float'.

Here is an example XML configuration file for a file-based I/O user-defined function:

RealScale.xml
Drag the mouse over this listing, enter Ctrl-C to copy, and paste it into the XML text editor.
    <?xml version="1.0" encoding="utf-8"?>
    <Function xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       Application="Infiniium" MinimumSoftwareVersion="22.1">
       <Name>RealScale</Name>
       <Abbreviation>Scale</Abbreviation>
       <Comments>Scales the input waveform.</Comments>
       <Script>RealScale.m</Script>
       <Icon></Icon>
       <FileIO>true</FileIO>
       <FunctionType>1 Source</FunctionType>
       <Control Name = "ScaleFactor">
          <Double>
             <Min>-100</Min>
             <Max>100</Max>
             <Resolution>1e-3</Resolution>
             <Units>None</Units>
             <Default>3</Default>
          </Double>
       </Control>
    </Function>

Here is an example script that uses file-based I/O:

RealScale.m
Drag the mouse over this listing, enter Ctrl-C to copy, and paste it into the MATLAB editor.
    % This script demonstrates how to use file-based I/O.

    % ScaleFactor is a variable specified in the XML config file
    % for this filter.
    if (~exist('ScaleFactor'))
       ErrorMsg = ['Please configure the operator by loading the XML configuration file '...
          'rather than loading the MATLAB script directly.'];
       return;
    end

    % Set the file location to the same directory but a new name.
    [filepath, name, ext] = fileparts(SrcDataFile);
    FiltDataFile = fullfile(filepath, 'Scaled.bin');

    % Define the chunk size (100,000 bytes)
    chunkSize = 100000;

    % Open the respective files for reading/writing.
    srcDataFileID = fopen(SrcDataFile, 'rb');
    filtDataFileID = fopen(FiltDataFile, 'wb');

    while ~feof(srcDataFileID)
       fileBytes = fread(srcDataFileID, chunkSize, '*uint8');  % Read all bytes
       floats = typecast(fileBytes, 'single');    % Convert to 4-byte floats
       floats = floats .* ScaleFactor;
       fwrite(filtDataFileID, floats, 'single');   % Write back as 4-byte floats
    end

    fclose(srcDataFileID);
    fclose(filtDataFileID);