SINKFILE

Interactively Output data from a Midas file/pipe to a FILE

<in>       Name of the input file/pipe (source)
<out>      Name of the output file (destination)
<start>    Start OFFSET into file [DEF=0] (0->size-1)
<duration> Length of buffer to play/split input file

Keyword Only Parameters:
[CUTOPTIONS] - Table of optional arguments for the /CUT switch.
               { 
                DIGITS=<int>,         ! Number of digits in the output filename
                NAMESCHEME=<String>,  ! Schema of output filename must be
                                      ! 'STD', 'YMD', or 'HMS'
                NEWFILEMSG=<String>,  ! Info message displayed when a new
                                      ! file is cut
                STARTNUM=<int>        ! Initial number used in output filename
               }
               
 
SINKFILE is designed for interactive use in a piped macro.  The buffer of
interest can be offset and lengthened/shortened interactively.  The device
can play in File mode, Oneshot, or Continuous (circular).  The routine comes
up by default in File mode and starts processing data as soon as the pipes
are up.

<start> and <duration> are the beginning and length of the replay buffer.  If
duration is negative, it represents an index amount of samples.

The /RTFILE switch causes the pipe fields in the output file header to be
updated with the current output byte pointer.  This can be used to effectively
'pipe' data to one or more independent macros.  The reader macro issues a
SOURCEFILE/RTFILE which reads the data throttled by the output pointer.

Cutting Multiple Output Files From a Single Input File
=======================================================
Since NeXtMidas 3.3.0, SINKFILE has the ability to cut an input file into a 
series of new files using the /CUT switch. The /CUT switch splits the provided 
input file based on the DURATION specified into new files per elements or 
time (seconds). The /CUT switch, when used with no /CUT options, will split 
the files per the number of elements similar to /CUT=ELEMENTS. /CUT=TIME splits 
a real time file for the duration specified based on the input file time and 
/CUT=CLOCK_TIME is based on current system (clock) time.

The /CUT switch has an options Table (CutOptions=) that can be used to provide
greater control over the output filenames. The STARTNUM option designates the 
initial sequence number for the first spawned file (e.g. myfile_00003.tmp).
The DIGITS option designates how may digits are used when creating the sequence
numbers of the output filename. The NAMESPACE option designates what format to
use for the date/time in the output filename. The available NAMESPACE option
values are: "STD" (YYYYMMDD_HHMMSS), "YMD" (YYMMDD), or "HMS" (HHMMSS). 
Note that these options apply only to the name of the output files, NOT 
the data itself.  

Examples:

  1. Continuously sink a file every 5K elements from the output of a waveform.
    nM> sd360/bg inf
    Open the debug terminal within the sd360 screen.
    nM> SINKFILE _waveb sfTab 0 50K
      sfTab.tmp

  2. Split a file every 10000 elements using 5-digit numeric sequence naming.
    nM> RAMP myramp1 elem=100k
    nM> SINKFILE/CUT=ELEMENTS myramp1 sfTab1_ 0 10000 cutOptions={DIGITS=5}
      sfTab1_00000.tmp
      sfTab1_00001.tmp
      ... and so on.

  3. Split a file every 100000 elements using time-based naming.
    nM> RAMP myramp2 elem=1000000
    nM> SINKFILE/CUT=ELEMENTS myramp2 sfTab2_ 0 100000 &
                              cutOptions={DIGITS=10,NAMESCHEME=HMS} 
      sfTab2_00000000_160449.tmp
      sfTab2_00000001_160449.tmp
      ... and so on.

  4. Split a file every 5.5 seconds using time-based naming displaying a message
     each time a new file is cut.
    nM> sd360/bg inf
    Open the debug terminal within the sd360 screen.
    nM> SINKFILE/CUT=CLOCK_TIME _waveb sfTab3_ 0 5.5 
                    cutOptions={NAMESCHEME=STD,NEWFILEMSG="Spawning new file"}
      sfTab3_0000_121024_160449.tmp
      INFO: "Spawning new file"
      sfTab3_0001_121024_160449.tmp
      ... and so on.

Messages:
  NAME       - (IN/OUT) DESCRIPTION
  ----------------------------------------------------------------------
  CUT        - (I)    Spawn a new file. [DATA=<new_filename>]
  

Switches:
  /TL                - Input transfer length in elements
  /RTFILE            - Enables the Real Time File mode
  /CUT=<spec>        - Split input file based on DURATION= (Since 3.3.0)
    ELEMENTS         - number of elements
    TIME             - number of seconds from input file
    CLOCK_TIME       - number of seconds based on system/clock time