Daqarta
Data AcQuisition And Real-Time Analysis
Scope - Spectrum - Spectrogram - Signal Generator
Software for Windows
Science with your Sound Card!
The following is from the Daqarta Help system:

Features:

Oscilloscope

Spectrum Analyzer

8-Channel
Signal Generator

(Absolutely FREE!)

Spectrogram

Pitch Tracker

Pitch-to-MIDI

DaqMusiq Generator
(Free Music... Forever!)

Engine Simulator

LCR Meter

Remote Operation

DC Measurements

True RMS Voltmeter

Sound Level Meter

Frequency Counter
    Period
    Event
    Spectral Event

    Temperature
    Pressure
    MHz Frequencies

Data Logger

Waveform Averager

Histogram

Post-Stimulus Time
Histogram (PSTH)

THD Meter

IMD Meter

Precision Phase Meter

Pulse Meter

Macro System

Multi-Trace Arrays

Trigger Controls

Auto-Calibration

Spectral Peak Track

Spectrum Limit Testing

Direct-to-Disk Recording

Accessibility

Applications:

Frequency response

Distortion measurement

Speech and music

Microphone calibration

Loudspeaker test

Auditory phenomena

Musical instrument tuning

Animal sound

Evoked potentials

Rotating machinery

Automotive

Product test

Contact us about
your application!

Macro Array File Operations

Introduction:

Any BufN array Buf0-Buf7 can be saved or loaded as a 1024-point file. You may use Daqarta's binary .BUF format, or a plain ASCII text .TXT format. The full 64-bit buffer resolution (32-bit integer and 32-bit fraction) is preserved for .BUF format, while the .TXT format allows you to specify the number of decimal places.

You may also choose to save or load .DAT, .WAV, or .DQA file types as signed 16-bit integers. .DAT files may be also be saved as 32-bit integers, or loaded as 8, 16, 24, or 32-bit integers using various formats.

You can append 1024 points to an existing file of any of these formats. For special purposes, you can save or append as little as one point to any file.

You may specify the starting point in the file for loading the next 1024 points. You can also query the results of a load operation to determine the actual number of points loaded, which may be less than 1024 if you start too near the end of the file.

Additionally, 2-, 4-, or 8-channel files may be saved and loaded in any of these formats. In this case a point or sample is regarded as one set of 2, 4, or 8 values.

The included WAV_to_Mono stereo-to-mono macro and the WAV_to_16bit file converter macro demonstrate the use of many of these commands.

All of the above file types are stored by default in Daqarta's User_Data folder. You can also load and store .CRV Weighting Curve Files (a special type of text file) in the App_Data folder.


Command Summary:

Buf0="<Save"           Save dialog with Buf.BUF default
Buf0="<Save:"          Save dialog with no default
Buf0="<Save:MyFile"    Save dialog with MyFile.BUF default
A.Buf0="<Save:MyFile"  Save MyFile.BUF; no dialog
Buf0="<SAve:MyFile"    Append to existing MyFile.BUF
Buf0="<SaveDQA"        As above, but save in DQA format
Buf0="<SaveWAV"        As above, but save in WAV format
Buf0="<SaveDAT"        As above, but save in DAT format
Buf0="<SaveTXT"        As above, but save in TXT format
Buf0="<SaveCRV"        As above, but save in CRV format

Buf0="<Load"           Open dialog with Buf.BUF default
Buf0="<Load:"          Open dialog with no default
Buf0="<Load:MyFile"    Open dialog with MyFile.BUF default
A.Buf0="<Load:MyFile"  Load MyFile.BUF; no dialog
Buf0="<LoadDQA"        As above, but load DQA format
Buf0="<LoadWAV"        As above, but load WAV format
Buf0="<LoadDAT"        As above, but load DAT (or any) format
Buf0="<LoadTXT"        As above, but load TXT format
Buf0="<LoadCRV"        As above, but load CRV format

Buf0="<tD3Sc"          Set .TXT save Decimal places and Separator
Buf0#N=n              Preset n = 0,1,2,4,8 Save/Load chans
Buf0#M=n              Bitmap n specifies buffers for Save
Buf0#S=n              Save/Append n = 1-1024 samples/chan
Buf0#SO=n             Save from n = 0-1023 Offset in buffer
Buf0#Rf=n             Set WAV/DQA Save sample rate n
Buf0#Vf=n             Set DQA chan 0 vertical range to n
Buf0#Uf="Deg"          Set DQA Units to "Deg" (4 chars max)
Buf0#Zf=n             Set n = 1 to force main Zero on at Open
Buf0#L=n              Load starting at file sample n
Buf0#K=1               Keep old data, no clear before Load
Buf0#H=n              Set Header bytes to skip for DAT load
Buf0#W=n              Set data Width for DAT save/load (multiple of 8)
Buf0#WO=n             Set load Width as above, in Offset binary format
Buf0#WU=n             Set load Width as above, in Unsigned binary format
Buf0#w=n              Set valid bit width for DAT load

UC=Buf0?N              UC = Channels in loaded file (1,2,4,8)
UX=Buf0?L              UX = Samples/channel loaded, 0-1024
US=Buf0?S              US = Samples/channel saved/appended, 0-1024
UB=Buf0?B              UB = Total bytes in saved/appended/loaded file
UW=Buf0?W              UW = Loaded WAV file data width (multiple of 8)
UD=Buf0?w              UD = Loaded WAV bit width (8,16,20,24,32)
UR=Buf0?R              UR = Sample rate of loaded WAV/DQA file

AutoInc#Bu=1           Auto-Increment next Save filename
AutoInc#Bu=2           Apply current main Auto-Increment to next Save
AutoInc#Bu=-1          Reset Auto-Increment for BufN Saves

Saving Buffers To Files:

Buf0="<Save" will open a standard Windows Save As dialog to save Buf0 in binary .BUF format. All .BUF files in Daqarta's User_Data folder are shown by default, but you can navigate to other folders.

At the bottom of the Save dialog under Save as type you can select .DQA, .WAV, .DAT, or .TXT instead of the default .BUF file type. (See below for more on .TXT.)

The default filename shown will be "Buf", which would mean a file named "Buf.BUF". Using Buf0="<Save:" (note the colon) will show an empty default name.

Buf0="<Save:MyFile" works as above, but shows MyFile as the default.

Buf0="<Save:MyFile" + "123" shows MyFile123 as the default. You can use any legal string expression in place of the "123" here, including normal variables. For example, if VarA = 123, you could use Buf0="<Save:MyFile" + VarA to get the same result. To use a numeric variable or string variable as the start of the filename, use Buf0="<Save:" + VarA + "MyFile".

You may specify the filename entirely via string expression, as in Buf0="<Save:" + Field1 + VarA, where Field1 holds a previously-entered base name. Note the colon in "<Save:".

When numeric variables like VarA appear in filename string expressions, the default behavior is to use only the rounded integer portion. If you want to include decimal places, you must supply an explicit format such as Buf0="<Save:MyFile" + Q(0.3). (That will use all of the integer digits, plus 3 decimal places.) Note, however, that this name will then have an extra decimal point, not just the period before the file extension.

You may want to pad the integer with leading zeros to get names that sort properly. For example, use Q(4) or Q(4.0) in the above to get "MyFile0123".

After any of the above commands that invokes a Save As dialog, you may use IF.Posn?f=0 to see if the user has hit Cancel to exit without choosing a file name. This allows your macro to exit gracefully or take other action.

Using an 'A.' prefix as in A.Buf0="<Save:MyFile" + "123" saves MyFile123.BUF directly, without opening any dialog or showing any user prompt. If a file of the same name already exists, it will be automatically overwritten.

Note: In general, you can supply a file extension with the Save command, as in Buf0="<Save:MyFile.WAV" and it will be saved with that format. However, that doesn't work when using the 'A.' prefix; the '.BUF' extension is automatically added, saving "MyFile.WAV.BUF". Instead, use A.Buf0="<SaveWAV:MyFile" as discussed below.

To append to an existing file (or start a new file if none currently exists), use a capital 'A' in 'SAve', as in A.Buf0="<SAve:MyFile".


Saving Multi-Channel Files:

To save a .BUF file with 2 channels, first use Buf0#N=2, then give the normal Save command. The first point in the file will come from Buf0, the second from Buf1, the third from Buf0 again, and so on. You can specify any starting buffer up to Buf6, which will save Buf6 and Buf7.

For 4 channels, use Buf0#N=4. This will save points from the specified buffer and the next three, in a "round robin" sequence. You can specify any starting buffer up to Buf4, which will save Buf4 through Buf7.

Buf0#N=8 will save 8 channels, and can only be used with Buf0.

You should explicitly set the number of channels to 1, 2, 4, or 8 before any buffer Save or Load operation. The only exception is setting 0 for a dummy Load to test for existence, which will return 1 if it exists, or for a .WAV or .DQA file will return the number of channels from its header. (See below.)

The normal Save assumes the channels are sequential, starting with the buffer specified on the left. Alternatively, you can use Buf0#M=n to specify the channels as bits set in bitmap n. The number of bits set there must be at least as great as the number set via Buf0#N. The only exception is when Buf0#N=8, which ignores the bitmap and uses all 8 buffers in sequence.

Note that when using the bitmap method you must always use Buf0 in the Save statement, regardless of which bits are actually set.

The bit number indicates the Buf number. For example, if you use Buf0#M=b01101010 (with Buf0#N=4) the buffers saved will be Buf1, Buf3, Buf5, and Buf6.


Saving Short Files:

If you want to save or append less than 1024 points, you can specify the number of points n before the save operation with Buf0#S=n, where n is 1 to 1024. Values of 0 or less are regarded as 1024, which is the default if no command is given. Note that this command affects the next save of any buffer, not necessarily the specified buffer, and that after the save the value automatically returns to the default of 1024. Note also that n is a count of time points, not values, so for 2-, 4-, or 8-channel files each increment of n adds another set of 2, 4, or 8 values, one from each specified buffer.

The above command assumes that the save will start with point 0. To specify a different start point (Start Offset), use Buf0#SO=n, where n is 0 (default) to 1023 (last point only). The specified point and all those after it up to the final point 1023 will be saved, unless there is also a Buf0#S=n command and it specifies less total points.

Immediately after any save operation, Buf0?S returns the number of samples actually saved. This is not buffer- or extension-specific and will return the value for the most-recent save of any buffer. The returned value will be zero for any file error (in which case an error message will be displayed), or if the save operation is cancelled from the Save dialog.

For file append operations (using 'SAve' instead of 'Save'), Buf0?S returns the number of samples appended, not the total samples in the file.


Saving DAT, WAV, or DQA Files:

To save using the .DAT, .WAV, or .DQA format, replace the 'Save' (or 'SAve') in the above examples with 'SaveDAT', 'SaveWAV', or 'SaveDQA'. For example, to save a 4-channel .WAV file you could use Buf0#N=4 followed by A.Buf0="<SAveWAV:MyFile". This will save MyFile.WAV with 4 channels using Buf0 through Buf3. There will be no file dialog or user prompt. If MyFile.WAV does not already exist, it will be created. If it exists and it is a 4-channel .WAV file, the new data will be appended to the end. If the number of channels is different, the command will fail.

As for .WAV files, .DQA files also require that the number of channels match when appending to an existing file. These file types allow this safety check because the number of channels is encoded into the file format header. That's not the case with .BUF or .DAT files (or .TXT files, discussed later), which are headerless.

Note: Although you can use Buf0#N=8 to save 8-channel .WAV, .DQA, or .DAT files (as well as .BUF files), when you later open the file from the toolbar DD / Open or the File menu the normal Daqarta display only supports up to 4 channels at a time. For an 8-channel file, an up/down scroll button pair appears to the right of the normal Display Channel buttons when the file is open, and the buttons change to Ch0-Ch3 instead of L.In to R.Out. You can then use the up button to scroll to Ch1-Ch4, Ch2-Ch5, Ch3-Ch6, or Ch4-Ch7. The down button scrolls back.

You can determine the number of channels in an existing .WAV or .DQA file by first setting the number of channels to 0 with Buf0#N=0, then doing a dummy Load (see below) and reading the number of actual channels as Buf0?N.

If you use 'SaveDAT', 'SaveWAV', or 'SaveDQA' (or the 'SAve' versions for appending) without the A. prefix, as in Buf0="<SaveWAV:", the Windows Save As dialog will open. However, unlike for the above-mentioned .BUF files the Save as type: drop-down will only allow a choice of these three formats, not .BUF or .TXT.

By default, .DAT files are saved as signed 16-bit integers, as are .DQA and .WAV files. However, you can optionally save .DAT files as 32-bit signed integers by preceding the operation with Buf0#W=32. (You can load .DAT files with 8, 16, 24, 32, or "packed" 64 bits per sample.)

After saving from a buffer command, 16-bit .DAT, .WAV, or .DQA files can be opened as normal Daqarta files using the DD / Open button in the toolbar. Note, however, that such files must be at least 1024 points long for Daqarta to open them. You can use the previously-discussed Buf0?S to get the number of samples saved. Also note that 32-bit .DAT files can't be opened this way, although they can be loaded into buffers. (See Loading Buffers From .DAT (Or Any) Files, below.)

Immediately after a save or append, Buf0?B returns the total number of bytes in the entire file, including .WAV or .DQA header information if present. This value will be overwritten by subsequent saves or appends, or by .BUF or .DAT loads.


Auto-Increment File Names:

Buffer file saves can use Daqarta's Auto-Increment filenames feature to append a 3-digit number which is incremented for each new Save. Instead of using the global Auto-Increment Filenames option in the File menu, or the equivalent AutoInc macro, you must give AutoInc#Bu=1 just before the Save. For example:

    AutoInc#Bu=1
    Buf0="<SaveDQA:MyFile"

This will open a Save As dialog with a default filename of MyFile-000 (with the .DQA extension assumed). After the save, the next time the same macro is run the default name will be MyFile-001, and so on up to MyFile-999.

If you change the base name from the Save As dialog at any time in the series, the sequence will continue with the next number being applied to the new name. After that the new base name will continue to be used, ignoring the "MyFile" name that actually appears in the macro.

If you give a new macro command with a different name, a new series will be started at -000 with the new name.

An AutoInc#Bu=0 before the Save will prevent Auto-Increment action on that save, but since the AutoInc#Bu state is automatically cleared to 0 after each save, there is no need to use this explicit command. Instead, you may wish to use a macro variable like AutoInc#Bu=QI to determine whether to use Auto-Increment. You can set that variable at the start of the macro for easy editing, and change it as needed between runs.

Alternatively, AutoInc#Bu=2 (or a variable or expression that evaluates to 2) just before the buffer save will apply whatever state has been set via the main AutoInc, either using the macro commands above, or using the File Menu toggle. That allows you to toggle Auto-Increment on and off between runs of the macro save, without having to edit the macro itself.

You can reset the Auto-Increment system by giving AutoInc#Bu=-1 at any time. This not only resets the count to zero, but also resets the base name to the name given in the macro (if any), in case it has been changed manually in the Save As dialog.

Note that Auto-Increment only applies to file Saves, not to Loads.

Also note that Auto-Increment is never applied when using "SAve" (instead of "Save") to Append to a file.


Setting Axes And Units For .DQA Files:

When you save buffers using the .DQA format, you can specify the horizontal and vertical display axis ranges, plus the vertical units, to be used when the file is later opened. These are analogous to the corresponding commands discussed under Display Axes and Units in the buffer display topic. The file commands have no effect on the current display. Unlike the display commands, which had separate versions for waveform and spectrum magnitude displays, these affect the entire file.

Buf0#Rf=n sets the effective sample Rate for the file. You can use any Buf0-7 here; there is only a single effective rate for the whole file. Note that unlike the main Sample Rate control for live data acquisition, which has a minimum of 120 Hz, this effective file rate can go much lower. That's because it automatically sets a corresponding Decimate Factor, which acts as a divisor for sample rate, to produce the specified effective rate.

Buf0#Vf=n sets the Vertical range to +/-n for channel 0 of the file, which would normally be Left In. Use Buf1 for channel 1 (Right In) through Buf3 for channel 3 (Right Out). For file reads, these #Vf settings only take effect when User Units are on, which is done automatically on file open. Please note that a prior BufN#Vx=2 command will override the #Vf value and use the current #V or #VU values.

Likewise, Buf0#Uf="Deg" sets the Units for file channel 0, while Buf1 to Buf3 set units for channels 1-3.

You can use Buf0#Zf=1 to force the main screen Zero on when the saved file is subsequently opened. You would typically use this when saving multiple channels, or a single unipolar channel where you want to offset the display to omit the empty negative portion. You'd set ZeroScrnAdj for each channel that will be displayed. See the _DC_Chart_Chans subroutine listing for the DC_Chart_Recorder macro mini-app.

Note that although you use Buf0-3 to specify the saved file channel ranges and units, these buffer numbers are not necessarily related to the actual buffer numbers you may be saving. If you use Buf0#N=4 to specify saving Buf0 through Buf3 then they will be the same. But if you use (for example) Buf3#N=4, then Buf3 will be saved as channel 0 and its range and units must be set via Buf0#Vf and Buf0#Uf commands. Buf4 will become channel 1, Buf5 will be channel 2, and Buf6 will be channel 3, and must be set using the Buf1-3 command versions.


Loading Buffers From Files:

To load a .BUF binary file to an array, use Buf0="<Load" instead of Buf0="<Save" in the above examples.

As with Save, you can change the file type selector at the bottom of the Open dialog to load .DQA, .WAV, .DAT, or .TXT instead of the default .BUF file type. (See below for more on .TXT.)

Alternatively, you can specify the file extension along with the name, as in Buf0="<Load:MyFile.WAV".

To load .DAT, .WAV, or .DQA files, use 'LoadDAT' 'LoadWAV', or 'LoadDQA'.

After any of the above commands that invokes a File Open dialog, you may use IF.Posn?f=0 to see if the user has hit Cancel to exit without choosing a file name. This allows your macro to exit gracefully or take other action.

You can also load a file directly, without the Open dialog, by using an 'A.' prefix as in Buf0="<Load:MyFile", but in this case the .BUF extension will always be appended. If you use A.Buf0="<Load:MyFile.WAV" the file "MyFile.WAV.BUF" will be opened, if it exists. Instead, use the specific A.Buf0="<LoadWAV:MyFile".

If the file is longer than 1024 samples, you can specify the starting point with Buf0#L=n, where n is the desired starting point. This command is not specific to the designated buffer, but will apply to the next buffer Load command for any buffer of any file format. As soon as that buffer is loaded, the effective n is reset to 0.

If the file is shorter than 1024 samples, the remaining samples are set to nulls by default. If you want to keep the old data there and only overwrite the initial portion with file data, use Buf0#K=1 before the load. As with the above #L command, this applies to whatever buffer is next loaded, and is cleared immediately after.

If the file has 2, 4, or 8 channels you must specify that ahead of time via Buf0#N=2, Buf0#N=4, or Buf0#N=8. In this case, a starting point specified by Buf0#L=n refers to the number of complete 2-, 4-, or 8-value time points. You may not use Buf0#M=n to specify a bitmap of buffers to be loaded, as you can during Save.

For .WAV or .DQA files, the specified number of channels must match that of the existing file, or the load will fail. To avoid that, you can specify Buf0#N=0 before the Load command. This will perform a dummy load that sets the number of channels to match the file, then returns without actually loading any data. If the file does not exist, the number of channels will remain at 0.

For .BUF, .DAT, or .TXT files there is no header to allow determination of number of channels. For these, setting Buf0#N=0 before Load will return 1 channel if the file exists, otherwise 0.

The number of channels can be read as Buf0?N, as in UC=Buf0?N. This value can be tested to provide different handling as needed, or to show an error message if the number is incompatible or the file does not exist. Assuming the file exists, the internal value (whether you read it or not) will be correct for subsequent loads to that buffer without the command failing. But for safety you should always test that it exists.

After a load operation, the number of points actually loaded can be read from Buf0?L, as in UX=Buf0?L. This may be less than 1024 if the starting point was near the end of the file. You can use this to determine when you reach the end of a file. Note that this value is specific to the specified buffer, and is not changed until that same buffer is loaded again.

For .BUF or .DAT files only, Buf0?B returns the total number of bytes in the file loaded. (Not just the bytes actually loaded, if the file is longer.) This value will be overwritten by subsequent loads, saves, or appends.

The relevant buffers are completely cleared before each load, so if less than 1024 points are loaded the remainder in each buffer will be zeros. (They are not cleared for dummy loads with the number of channels set to 0.)


Loading Buffers From .WAV Files:

The LoadWAV operation can handle all standard WAV formats: 8-bit offset, and 16-, 20-, or 24-bit signed data. Samples are automatically converted to signed 32-bit integer values for storage in the selected buffer(s). However, the full-scale value depends upon the "container size", not the nominal bit width. Data values are always high-justified in their containers, so the value ranges depend only on the container size.

8-bit data is always stored in bytes, with a full-scale range of +/-2^7 (actually +127 to -128) after converting to signed integer. Likewise 16-bit data is always stored in 2-byte words with a +/-2^15 range.

But 20- and 24-bit samples may be stored as 3 or 4 bytes each, so the container size is either 24 bits with a range of +/-2^23, or 32 bits with a range of +/-2^31.

After loading a .WAV file you can read the data width from Buf0?W, as in UW=Buf0?W. You can use this value to convert arbitrary input formats to a standard range for your computations. For example, to convert to 16-bit format you could use Buf0="<*(2^(16-UW))". If UW is 8, then this multiplies each value by 2^(16-8) = 2^8 = 256. If UW is 16, then it multiplies by 2^0 = 1. 24 and 32-bit values of UW result in scaling down by 2^(-8) and 2(-16) respectively.

The actual number of "active" bits in the raw data determines the true resolution. You can read that from Buf0?w as in UD=Buf0?w.

You can read the sample rate of loaded .WAV or .DQA file data from Buf0?R, as in UR=Buf0?R. If you are loading the file to manipulate it and re-save it in a modified form, you can then use Buf0#Rf=UR before the save so that the saved file will have original sample rate. (Otherwise, it would have the current Daqarta sample rate, which might be quite different.)

The WAV_to_16bit file converter macro included with Daqarta demonstrates the rescaling of data using Buf0?W and re-saving with the original sample rate using Buf0#Rf=UR.


Loading Buffers From .DAT (Or Any) Files:

DAT is the name that Daqarta uses for headerless raw data files, or for any file type that it doesn't recognize. Since this means that the file format and number of channels are unknown to Daqarta, the Buf0="<LoadDAT" command requires that you specify these parameters ahead of time.

LoadDAT offers much more flexibility than the similar DAT File Format Dialog you get when opening such files manually using the DD/Open button in the toolbar. For example, if you know the header format you can write a macro that first extracts parameters from the header, then uses them to re-load the file with the appropriate settings.

The Buf0="<LoadDAT" command (without an A. prefix to Auto-load) will by default show all files that have an explicit .DAT file extension. But you can use the "Files of type:" drop-down control at the bottom of the Open dialog to select "All Files" instead of "Buffer Data Files (.DAT)" to see everything else.

NOTE that the LoadDAT command behaves differently than Load, LoadWAV, LoadDQA, or LoadTXT. If, for example, you give a LoadTXT command but select a .WAV file type, it will be loaded using the WAV file header that Daqarta recognizes. LoadDAT, on the other hand, will ignore the header and do exactly what you specified ahead of time.

Just as for .BUF and .TXT files, you specify the number of channels via Buf0#N=n, where n is 1, 2, 4, or 8 to indicate the adjacent buffers to use for each channel.

Buf0#W=n specifies the width of each sample in bits. Daqarta will round n up to the nearest multiple of 8, because data is assumed to be stored in one or more integer 8-bit bytes. LoadDAT supports 8, 16, 24, 32, and 64 bit formats.

The default assumes the data is in "two's complement" signed binary format. Alternatively, you can specify Offset signed binary via Buf0#WO=n, or Unsigned via Buf0#WU=n. (Note that 8-bit .WAV files use offset binary, but all other .WAV files, plus .DQA and .BUF files, use 2s-complement. Daqarta automatically detects 8-bit .WAV files and handles them accordingly.)

One exception to the above is with Buf0#W=64, which is typically used to "pack" a buffer with text at 8 characters per index position, or up to 8192 characters per buffer. This is the format used for Buf0-7 String Storage.

The above #W, #WO, and #WU commands specify the "container size" of one sample of data from one channel. But some lab-type instrumentation systems don't use all these bits for valid data; older systems with 12-bit ADCs, for example, stored each sample in a 16-bit word, leaving 4 bits that did not hold sampled data. In multi-channel systems, these bits typically held the channel number.

When the number of valid data bits is less than the container size, the data may be justified to the high or the low end of the container. Daqarta allows you to specify the number of valid bits via Buf0#w=n, where n is positive to indicate they are at the high end, and negative for the low end. You can use Buf0#w=0 to specify that all bits in the container size are valid, instead of specifying the number explicitly.

Note that the above Width discussion only applies to LoadDAT, not SaveDAT. By default SaveDAT saves signed 16-bit integers, but you can specify 32-bit via Buf0#W=32. You can't specify any other width, and you can't use #WO or #WU to specify Offset or Unsigned... 32-bit saves are always signed binary.

As noted earlier, a .DAT file may be headerless, or it may have a header that Daqarta doesn't recognize. In the latter case, if you know the size of the header you can use Buf0#H=n to tell Daqarta to skip n header bytes to get to the actual data.

The #H parameter is independent from the #L parameter, which tells LoadDAT how many samples (of 1, 2, or 4 channels each) to skip, after skipping the header bytes.

Note: All of the above parameters are per-buffer, and are persistent for the duration of the Daqarta session until explicitly changed. You must set them as desired before using LoadDAT the first time for each buffer, but if you are processing a long file in 1024-sample chunks you only need to set the header and format parameters once for that buffer. Then you just advance #L to read each successive chunk using the same format.

If you know the actual layout of the header, you can use LoadDAT to read one or more desired parameters from the header, then set those parameters and re-load to get the data itself.

For example, suppose the header holds the number of channels in a single-byte value at byte 17, and gives the start of the actual (non-header) data as a 4-byte value starting at byte 34. You could first set Buf0#N=1, Buf0#H=0, Buf0#WU=8, and Buf0#w=0. Then after Buf0="<LoadDAT" you can read the number of channels via UN=Buf0[17].

Reading the data start (which is also the header size) can be done using either of two different approaches. With the existing buffer loaded as above, you can construct the start position by reading 4 successive bytes at indexes 34-37 and combining them to get the total size. Assuming that the size entry is "little-endian" (low byte first, as is used throughout the Windows and sound card worlds), you could read the value as:

UH=Buf0[34] + Buf0[35] << 8 + Buf0[36] << 16 + Buf0[37] << 24

Alternatively, your macro could re-load the file after first using Buf0#H=34 and Buf0#WU=32, and read the data start as UH=Buf0[0]. This is a "tricky" use of #H just to get a single value at a known location.

You can use the same approaches to read other parameters, such as number of channels, sample rate, calibration data, etc.

Finally, you would use Buf0#H=UH to skip over the header, then set the actual data format and number of channels, and do the final LoadDAT to get just the data.

Note that LoadDAT always reads 1024 samples (per specified channel), or until the end of the file. The initial loads to determine header parameters may thus result in a buffer whose later elements are full of junk (data read with the wrong format, or misaligned). This is no problem, since it will be overwritten by the final load.

You can use LoadDAT to load files that are much less than 1024 samples per channel; the remaining elements will be filled with zeros.

You can extract short sections from a larger file using a different format or number of channels. For example, a 256-color .BMP (bitmap) file includes a palette of 256 4-byte entries in the header to define which color is represented by each byte in the actual bitmap. Palette entries are in the Windows "RGBQUAD" format, which consists of a Blue byte, a Green byte, and a Red byte, followed by a null byte. You can load the palette by setting the proper #H to skip earlier parts of the header, then using either Buf0#N=1 with Buf0#WU=32, or Buf0#N=4 and Buf0#WU=8.

In the first case, Buf0[0] holds the full RGB color triplet for the 0th palette entry, as a 32-bit value whose individual color bytes UR, UG, and UB can be extracted via UR=int(Buf0[0] >> 16), UG=int(Buf0[0] >> 8) & 255 and UB=Buf0[0] & 255. (Note that you can also set the current Spectrogram palette from from this loaded palette via Buf0#Ps=0. See Copy Spectrogram Palette To/From Buffer Block under Macro Array Copy/Swap Operations.)

In the second case, the colors will be in separate buffers, with the same palette index positions. Since the Blue byte is the first of the triplet as given in the RGBQUAD, then for the 0th palette entry UB=Buf0[0], UG=Buf1[0], and UR=Buf2[0]. Buf3 will hold zeros for all palette index positions 0-255.

To load the actual image pixels, you'd set Buf0#N=1 and Buf0#WU=8. You'd of course need to learn about how .BMP images are stored, and adjust #H to where the data starts; the bottom of the image is stored first, as a row of pixels as wide as the image. If that width (which can be read from the header) is 1024 or less, you can load the entire row in one buffer. Then you can add the width to the #H value to read the next-higher row, and so on.


Saving And Loading Text Files:

Text files may be saved and loaded in a manner similar to saving and loading the formats discussed above. Use A:Buf0="<SaveTXT:MyFile" to save the contents of Buf0 to MyFile.TXT as a list of 1024 values, without an overwrite prompt or a file save dialog.

Note that these .TXT files are not the same format as those created with the Save Trace as .TXT Text File option in the File menu, or the normal SaveTXT macro that does the same thing. Those have headers, and have an initial column giving the time or frequency (X-axis) value for the data that follows on each line.

BufN text files have no header, and no X-axis column. They are simply lists of numbers.

By default, BufN text files are saved with 3 decimal places for each element value, one value per line in a single column. You can specify the number of decimal places from 0 to 9, and you can change the element separator from a newline to a comma plus 3 spaces.

Buf0="<tD5Sc" sets the TXT save Decimal places to 5, and the Separator to a comma (plus 3 spaces). The default is equivalent to Buf0="<tD3Sn" for 3 Decimal places and newline separator. Note that the BufN used is arbitrary, since this command applies equally to text files saved from Buf0-Buf7.

Alternatively, you can use the string variable format options. For example, where you might ordinarily use Msg=VarA(4.3) to display VarA with 4 integer and 3 decimal places, to use that same format for saving a BufN text file you would use Buf0="<t(4.3)". If you additionally want to use a comma separator, you'd use Buf0="<t(4.3)Sc".

The string variable formats include hexadecimal, binary, exponential, scientific, alphanumeric, and binary state options besides normal decimal display. However, if you use hexadecimal or binary, note that no 'h' or 'b' prefix is inserted such as would be needed to read such values back with Daqarta. If you need that, consider instead creating a log file using LogTxt to insert such characters or any other formatting you require.

Note that buffers can hold integer values from -2147483648 to +2147483647.999999999, all of which can be saved as text. However, if you intend to later open the resulting file for display by Daqarta (such as via the DD / Open button in the toolbar, or the Open macro), the integer portion must be limited to +/-131071. It also must be a single-channel file.

As with the other formats, you can append to an existing file (or start a new file if none exists with that name), using A:Buf0="<SAveTXT:MyFile".

You can also specify 2, 4, or 8 buffers for saving, by preceding the save with Buf0#N=2, Buf0#N=4, or Buf0#N=8. You may optionally use Buf0#M=n to specify non-sequential buffers, as for .BUF, .DQA, and .WAV file saves. (Discussed in the Saving Buffers To Files subtopic earlier.)

Each line of text will hold values for a single buffer index, for each of the specified buffers. The next line will hold the values of these buffers for the next index, etc. The buffer values on a single line are separated by commas (and 3 spaces) by default.

However, you can specify column spacing instead of comma separators by enclosing the value (or expression) in parentheses in the text format command. For example Buf0="<tD5S(20)" specifies that columns will start at 0 and 20 for a 2-buffer file, and 0, 20, 40, and 60 for a 4-buffer file. If the specified column spacing is too narrow for the data, the comma-and-3-spaces separator will be used instead.

Also as with the other formats, you can use Buf0#S=n ahead of the save command to save or append only n time points to the file. You can use Buf0#SO=n to set the start offset to a specified point n, and save from there to the end (1023) unless Buf0#S=n is used to set a smaller total.

Immediately after any save operation, Buf0?S returns the number of samples actually saved. This is not buffer- or extension-specific and will return the value for the most-recent save of any buffer. The returned value will be zero for any file error (in which case an error message will be displayed), or if the save operation is cancelled from the Save dialog.

Alternatively, Buf0?B returns the total number of bytes in the entire file.


Use A.Buf0="<LoadTXT:MyFile" to load MyFile.TXT. Precede it with Buf0#N=2, Buf0#N=4, or Buf0#N=8 to load 2-, 4-, or 8-channel files. Use Buf0#N=0 for a dummy load that will return 1 channel (which you can read as Buf0?N) if the file exists, or else remain at 0. (Unlike .WAV or .DQA files, there is no header from which to read the actual number of channels. If the file exists, you will then need to set the expected number before the actual load.)

LoadTXT does not need any format command like Buf0="<tD3Sc", since it accepts any number of places up to 9, and accepts either newline or comma as the data separator, as well as spaces or tabs. It also ignores comments, from the leading semicolon to the end of the line.

After the load, you can read the number of time points loaded via Buf0?L, as in X=Buf0?L.


Loading Multiple Text Files To One Buffer:

You can load two or more short text files to one buffer. The trick is to load the first normally, such as via A.Buf0="<LoadTXT:MyFile_1", then set the Start Offset to where you want the second file to go, such as Buf0#SO=512. Then use Buf0#K=1 to prevent the buffer from being automatically cleared on load. Finally, load the second file.

Alternatively, you can load the second file right after the first, by reading the number of points from the first load. Here's the whole sequence:

A.Buf0="<LoadTXT:MyFile_1"     ;Load first file
UL=Buf0?L                      ;Points loaded = next index
Buf0#SO=UL                     ;2nd file right after 1st
Buf0#K=1                       ;Prevent clear on load
A.Buf0="<LoadTXT:MyFile_2"     ;Load second file

Loading Text Files From Notes:

Sometimes it may be more convenient to copy a list (or a selected part of a list) of values from a text file open in another program, paste them into Daqarta's Notes area, and use Buf0="<Notes" to copy the values to the buffer. This can be much quicker than copying the list to a file, saving the file, and loading it as above. Due to the limit on Notes size (2047 characters) this method is only useful for partial buffer fills... typically 200 values or less, depending on how many characters each takes.

The Notes copy does allow you to fill a buffer in sections using the same Buf0#SO command (as for file saves) to advance the Start Offset between section copies. You can use Buf0#S to restrict the number of points copied, and you can use Buf0#N to copy to 1, 2, 4, or 8 sequential buffers. After the Notes copy Buf0?L returns the number of points.


Saving And Loading .CRV Files:

Weighting Curve Files are special text files that are stored in Daqarta's App_Data folder, instead of the User_Data folder, because they are regarded as general resources instead of data.

.CRV files always contain 2 columns (channels) of data. The first column is frequency, and the second is the corresponding dB weighting at that frequency. A raw .CRV file can contain an arbitrary number of these frequency/dB pairs, with arbitrary spacing between frequencies. When loaded into the Spectrum Curves Dialog as Curve0 to Curve3, these values are interpolated to align with the 512 spectrum line frequencies resulting from a 1024-point FFT at the current sample rate.

This interpolated Curven can be copied to a Macro Array Buffer such as Buf0 via Buf0="<=Vn", where n = 0 to 3 to specify Curve0 to Curve3. Only the dB values are copied to the buffer; for a given buffer index I = 0 to 511, the corresponding frequency is always understood to be I * SmplRate / 1024.

The buffer can then be manipulated, such as by adding it to another Curve in Buf1 via Buf1="<+B0". The combined curve can then be saved back to a .CRV file for subsequent loading as a Weighting Curve. You might want to do this to create a noise source with a desired spectrum (which you supply as the Curve copied to Buf0), that is also equalized to compensate for real-world sound system frequency response irregularities (supplied as a Mirror Curve in Buf1). See the Arbitrary-Spectrum Noise subtopic under Noise Band Shape - Taps.

Note, however, that the .CRV file requires a frequency column, which was not included during the Buf0="<=Vn" copy operation. The list of frequencies to go with each dB value must be put back into Buf0 after the dB values have been added to Buf1. This list is "reconstituted" by first filling Buf0 with index values I via Buf0="<=#", then multiplying each index by Buf0="<*(SmplRate / 1024)" as noted previously.

Then Buf0 and Buf1 can be saved together as a two-channel file in the standard .CRV file format. The following Curve_Sum macro (included with Daqarta) accomplishes all of the above. It assumes that Curve0 and Curve1 files have been previously loaded in the Spectrum Curves Dialog:

;<Help=H4919
Buf0="<=V0"        ;Copy Curve0 dB values to Buf0
Buf1="<=V1"        ;Copy Curve1 dB values to Buf1
Buf1="<+B0"        ;Add Buf0 to Buf1
Buf0="<=#"         ;Replace Buf0 with index (0-1023)
Buf0="<*(SmplRate / 1024)"     ;Convert index to frequency
Buf0="<tD3S(16)"   ;Set 3 decimal places, 16-column spacing
Buf0#S=512         ;Set to save only the first 512 entries
Buf0#N=2           ;Set to save 2 channels (Buf0 and Buf1)
Buf0="<SaveCRV:CurveSum"   ;Save file to CurveSum.CRV

The above will present a Save dialog with 'CurveSum' as the default filename, which you can accept or change. The .CRV extension is added automatically. The file will go to Daqarta's App_Data folder by default, where it will be available for loading as a Weighting Curve File in the Spectrum Curves Dialog, just as the two original curves were loaded.

Note that it is possible to load a .CRV file directly into two adjacent buffers (such as Buf0 and Buf1) without loading into a Weighting Curve first:

Buf0#N=2           ;Set to save 2 channels (Buf0 and Buf1)
Buf0="<LoadCRV"    ;Prompt for .CRV file to load

However, this is not generally recommended because the .CRV file will not go through the automatic interpolation process that aligns Weighting Curves to spectral line frequencies. Since the .CRV format allows arbitrary frequency spacing, your macro would need to be aware of the details for the particular file. The file could easily have only a few entries... see the example under Weighting Curve Files.


See also Macro Overview, Macro Arrays Buf0-Buf7

GO:

Questions? Comments? Contact us!

We respond to ALL inquiries, typically within 24 hrs.
INTERSTELLAR RESEARCH:
Over 35 Years of Innovative Instrumentation
© Copyright 2007 - 2023 by Interstellar Research
All rights reserved