Copyright: ® Axon Instruments


Help Contents
Contents

Overview

Status

Purpose

History

What You Need To Know

File Types

Organization Of The Axon File Support Pack

Existing Applications

File Naming Conventions Used By Axon Instruments

Using the ABF Functions

Technical Support

Axon Binary Files (ABF)

ABF File Format

ABF Header Section

The ABF Synch Array

The ABF Tag Section

The ABF Deltas Section

The ABF File I/O Functions by category

The ABF File I/O Functions

The ABF Header Function API by category

The ABF Header Functions

The ABF File Information Functions by category

The ABF File Information Functions

Axon Text Files (ATF)

ATF File Format

ATF Function API


Status

Version 1.3.2 of the Axon File Support pack is still under development.  Third parties using these modules should understand that there might be minor changes to the functional interface in future releases.  Axon Instruments will attempt to document these interface changes in the change history but cannot accept any liability for inconvenience caused by changes that are made, whether documented fully or not.


Purpose

The purpose of the Axon File Support Pack is to help third party and independent developers incorporate reading and writing support for Axon Instruments' data files into their products.

Axon's data file formats, which have evolved incrementally since their introduction in 1985, are optimized for rapid access to huge amounts of binary and ASCII (text) data such as are acquired in neurophysiological and other experiments.

Axon's data acquisition programs offer a broad range of acquisition types that cover most experimental requirements.  However, there are more types of analysis than can possibly be catered for by the products of one company, so Axon Instruments decided that it was in the best interest of the neurophysiological research community to put its file formats into the public domain.


History

Prior to pCLAMP 6 and AxoTape 2.0, Axon's programs used two data file formats known as the Clampex and Fetchex formats.  In 1993 these were combined into a single ABF format.  The ABF reading routines in the Axon File Support Pack read all previous versions of Clampex, Fetchex and ABF files and promote them to the current ABF version so that applications programmers do not have to have any knowledge of the details of previous versions.

For a detailed description of old FETCHEX and CLAMPEX files refer to the manual for pCLAMP V5.x or earlier.

Similarly, prior to pCLAMP 6 and AxoTape 2.0, Axon's programs stored ASCII data in the PAF format.  The ATF reading routines in the Axon FSP read all previous PAF and ATF versions and promote them to the current ATF or ABF version.


What You Need To Know

One of the goals of the ABF reading routines is to isolate the applications programmer from the need to know anything other than the most basic information about the file format.  If when working with the ABF reading routines you find that you are overwhelmed by details, stop -- this is a sign that you are not using the proper functions.

Related Topics:

Using This Help File

Compilers and Environments

Copyright

Future Compatibility


Using This Help File

All of the ABF and ATF functions are fully documented in this help file and nowhere else.  That is, Axon Instruments does not provide a printed manual for the File Support Pack.

Constructive comments on the organization of this help file would be much appreciated.  Please forward your comments by e-mail to tech@axonet.com.


Compilers and Environments

The Axon File Support Pack routines are written in C++.  Compatibility has been tested with the Microsoft C/C++ and the Borland C/C++ compilers.  The ABF and ATF source code can be compiled for use in either a DOS or Windows operating environment.  Other additional environments may be supported in the future.


Copyright

These libraries are copyrighted by Axon Instruments, Inc.

Axon Instruments permits the use of these libraries for the addition of file I/O support to third-party programs.  Modified libraries retain their original copyright.


Future Compatibility

From time to time the various Axon file formats will be enhanced. It is Axon Instruments' intention to update the Axon File Support Pack soon after new file formats are released.

Developers should keep in mind that it will be simpler for them to upgrade to the latest file format if the existing support libraries are used without modification.


File Types

Axon Binary File (ABF) Format

The Axon File Support Pack supports the reading and writing of ABF format files, which are used for the storage of acquired data.  These files can be created and read on IBM PC compatible computers and on Macintosh computers.  For optimal acquisition performance the binary data are written in the byte order convention of the acquisition computer and the reading routines automatically implement byte swapping if required.

A header describes the acquisition details and the location of the various components of the file.

Axon Text File (ATF) Format

The Axon File Support Pack supports the reading and writing of ATF format files.  All derived data are written as ASCII text to ATF format files.  A simple header ensures that the files can be intelligently read by ATF-aware programs.  Non-ATF-aware programs, such as spreadsheets and some general purpose graphics and analysis programs, can still read the file and ignore the header.

Axon Events List (EVL) Format

The Axon File Support Pack also supports the reading and writing of a special purpose binary file format known as EVL, for EVents Lists.  Events lists contain idealized representations of membrane ionic-channel data.

AxoData File Format

Axon's AxoData format is NOT supported in the Axon File Support Pack.  Developers interested in reading or writing AxoData files should see the programmers support folder that ships with AxoData itself.

Axon Imaging File (AIF) Format

Axon's AIF format is NOT supported in the Axon File Support Pack.  Developers interested in reading or writing AIF format files should contact Axon Instruments' technical support department.  At the time of writing this help file, arrangements for providing AIF support to third-party developers had not been made.


Organization Of The Axon File Support Pack

Source Code

Example Data Files


Source Code

The files included in this package provide DOS and Windows libraries for accessing data files stored in Axon's ABF file format.  Support for Axon's ATF and EVL formats will be incorporated into later versions.

The package consists of two .ZIP files (ABF.ZIP and COMMON.ZIP).  These should have been unzipped into two separate directories adjacent to each other in the directory tree.

The ABF directory contains Microsoft make files (.MAK) for the following:

ABFDLL.MAK

Creates a Windows 3.x DLL containing routines for accessing ABF data files. The header files (*.h) provide prototypes of the functions exported by this DLL.

ABFLIB.MAK

Creates a static library suitable for linking with a large model DOS program. Provides the same exported functions as ABFDLL.DLL.

HEADER.MAK

Creates a stand alone DOS program for displaying header information from ABF files. Type HEADER <enter> for help.

WINHEAD.MAK

Creates a Windows "QuickWin" version of the HEADER program that dynamically links to the ABFDLL dynamic link library.

Verification of ABF Function Usage

To verify data read by the ABF functions, it is recommended that developers make use of the HEADER.EXE program or the ABFINFO.EXE program (provided in both source and executable form).  These will compile under either Microsoft C/C++ or Borland C/C++.  By compiling either of these programs with debugging support you can single step through the reading of data files and see how the ABF routines can be used to retrieve episodes from data files.  The code in HEADER.CPP for displaying episodes (procedure ShowEpisode) and copying files (procedure CopyToABF) shows the correct use of the ABF routines.


Example Data Files

VARIABLE.DAT    (Dec 12, 1994, 10:29 am)

Single ADC channel (#0) containing ionic channel data acquired in Fetchex 6.0 demo using variable-length event-driven mode.  200 samples pre-trigger.  Sampled at 5 kHz (200 µs sampling interval).  35,383 samples in the file.

GAPFREE.DAT    (Feb 25, 1994, 1:32 am)

Single ADC channel (#0) containing ionic channel data acquired in Fetchex 6.0 demo using gap-free acquisition.  Sampled at 10 kHz (100 µs sampling interval).  51,200 samples in the file.

FIXED.DAT    (Feb 25, 1994, 1:32 am)

Single ADC channel (#0) containing ECG data acquired in Fetchex 6.0 demo using fixed-length event-driven mode.  10 samples pre-trigger.  Sampled at 20 kHz (50 µs sampling interval).  23,040 samples in the file.

DACFILE.DAT    (Feb 25, 1994, 1:32 am)

Single ADC channel (#0) acquired in Clampex 6.0.  Waveform was described by the contents of a data file.  The analog output was sampled, so the data portion of the file is related to the stimulus waveform stored in the DAC file section.

2CHTAPE.DAT    (Feb 25, 1994, 1:32 am)

Two ADC channels acquired by AxoTape 2.0 in gap-free mode.  ADC channel #0 contains a triangle wave;  ADC channel #1 contains a sine wave.  Sampled at 2 kHz/channel (500 µs sampling interval/channel).  The multiplexed sampling rate was 4 kHz (250 µs).  20,000 samples total in the file corresponding to 10,000 samples/channel.

3CHCLMPX.DAT    (Feb 25, 1994, 1:32 am)

Three ADC channels acquired by Clampex 6.0 in hierarchical waveform mode.  ADC channel #0 contains a series of ramps of incrementing amplitudes.  ADC channel #1 contains non-synchronized sine waves.  ADC channel #4 contains non-synchronized, undersampled triangle waves.  A Math Channel is present, containing the sum of ADC channels #1 and #4.  The trial consists of one run, containing four episodes each of 2048 samples/channel.  The sampling interval changed halfway through from 12 µs/channel to 20 µs/channel.  A user list was used to describe the amplitude of epoch E in the stimulus waveform parameters.


Existing Applications

Third party

So far, support for Axon's Binary File (ABF) format has been incorporated into the following categories of third-party (i.e. non-Axon) products.

(i)	Special purpose analysis programs written in laboratories by individual researchers.

(ii)	Special purpose commercial analysis programs.

(iii)	General purpose commercial graphics and scientific analysis programs.

(iv)	Public domain acquisition programs that run on Axon Instruments' digitizers.

(v)	VCR and DAT laboratory tape recorders that transfer digital data in ABF format to a host computer for subsequent analysis by Axon and other software.

Axon Instruments

Raw data acquired by Axon's DOS programs are stored in ABF format.  These programs are AxoTape and the two pCLAMP acquisition programs (Clampex, Fetchex).  All of the pCLAMP programs read ABF data files.  ABF data files may contain data in either two-byte integer format or four-byte IEEE floating point format.  The ABF read routines transparently cope with either format.

For data exchange to other programs, the pCLAMP analysis programs (Clampfit, Fetchan, pSTAT), AxoTape, AxoData, and Axon's imaging programs (Axon Imaging Workbench, AxoVideo) create ATF files.

Axon's Fetchan event-detection program (part of the pCLAMP suite) stores the idealized record of data transitions in EVL format files.


File Naming Conventions Used By Axon Instruments

ABF data files acquired by Axon Instruments programs always end in a .DAT suffix.  ABF data files extracted during analysis from raw data files end in a .DAn suffix, where n is an integer from 0 to 9.

Data files acquired under the DOS FAT system consist of a maximum of eight characters, of which the acquisition program reserves the last three characters for an automatically incremented sequence number.

Other aspects of the data file names are optional and cannot be relied upon by analysis programs.  The naming conventions used by Axon Instruments for ABF and ATF files are fully documented in the File Formats and Naming Conventions chapter in the pCLAMP 6 manual.


Using the ABF Functions

The ABF file support routines provide functions for accessing ABF files at both high and low levels.  The low level routines are normally used only by data acquisition programs, and provide a mechanism for fast access to the raw data that resides in ABF files.  The high level access routines return time arrays, acquired data arrays, stimulus waveforms and derived data arrays in fully scaled, demultiplexed floating point arrays in user units.

The low level ABF routines are much more complex to use than the high level routines, requiring manual combination of up to five scaling and offset values to convert from ADC values (2-byte integers) to scaled data in user units (4-byte floats).  The high level routines provide a wrapper around the low level routines, doing all conversions and only returning fully scaled 4-byte floats.

Axon Instruments STRONGLY recommends that all third party developers use the high level routines for accessing ABF data files.

In case there is any doubt, we will say it again.

Axon Instruments STRONGLY recommends that all third party developers use the high level routines for accessing ABF data files.

Related Topics:

Advantages of accessing ABF files through the High-level routines.

Altering Existing Raw Data Files


Advantages of accessing ABF files through the High-level routines.

Episodic Timebase Information

Retrieving Stimulus Waveform Descriptions

Retrieving Math Channel Data

Calculating Composite Values


Episodic Timebase Information

The calculation of time-axis values from the header parameters can be complicated due to the possibility of a transition within the episode from one sampling rate to another faster or slower rate.  The ABF routines provide a function (ABFH_GetTimebase) that can return the complete timebase in time units from the data file. The ABFH_GetTimeBase function can be used for any type of data format: episodic, gap-free, variable-length, etc. Since all types of data are treated as episodic with the ABF routines it is much clearer and consistent to use the ABFH_GetTimeBase in conjunction with the ABF_GetStartTime function to determine the time in which a sample was acquired.


Retrieving Stimulus Waveform Descriptions

To retrieve the stimulus waveform may be difficult if just the low level ABF routines are used.  This is because the waveform may be described either by the Epoch definitions in the header, or by a "DACFile" block at the end of the file.  The high level routines, however, handle either of these cases transparently, and will return the stimulus waveform from either of two forms: ABF_GetWaveform will form the stimulus waveform array as an array of samples corresponding to the time base.  If higher speed plotting is required, the stimulus waveform can also be returned (by ABF_GetWaveformVector) as a set of X-Y coordinates that describe just the transitions of the waveform.


Retrieving Math Channel Data

The Math Channel is an algebraic combination of two ADC channels, described by parameters in the Math Channel section of the ABF header.  Math channel data may be retrieved through the ABF_ReadChannel function, using a channel number of -1. (This channel is only available if the nArithmeticEnable flag is set in the file header.)


Calculating Composite Values

If the low level ABF routines alone are used, the following calculations must be performed to convert the data from raw integers into scaled floating-point values and to determine the effective lowpass filter cutoff frequency applied during acquisition.

Composite ADC scale factor =
fInstrumentScaleFactor() * fAutosampleAdditGain * fADCProgrammableGain() * fSignalGain().

Note, the fAutosampleAdditGain only applies to the autosampled ADC channel.

Composite ADC offset = fInstrumentOffset() + fSignalOffset()

Composite lowpass filter -3 dB frequency =

A complex function of fSignalLowpassFilter and fAutosampleFilter, for the autosampled ADC channel.

On other ADC channels, only the fSignalLowpassFilter contributes to the composite value.


Altering Existing Raw Data Files

Axon Instruments does not easily allow users to change or append data to ABF raw data files, in the belief that raw data is sacrosanct and will often need to be analyzed many times in the future.  We recommend that third-party developers do not allow users to easily delete or modify ABF files.


Technical Support

Technical support for the Axon File Support Pack is available from:

Axon Instruments Inc.
1101 Chess Drive,
Foster City,
CA  94404,
USA

Fax:	+1 (415) 571-9500
e-mail:	tech@axonet.com
ftp site:	ftp.axonet.com


ABF File Format

Overview

What Kind Of Data Are Stored In ABF Files?

ABF Hardware And Storage Limits

ADC Channel Numbering

Definitions

Autosampling

Composite Values

Names, Units And Signal Conditioners

Data Types

File Version Numbers


Axon Binary Files (ABF) - ABF File Format - Overview
Overview

Change History

Version 1.1 was released in April 1993 with AxoTape 2.0.

Version 1.2 was released in November 1993 with pCLAMP 6.0.

(1)	Added nDataFormat so that data can optionally be stored in floating point format.

(2)	Added lClockChange to control the multiplexed ADC sample number after which the second sampling interval commences.

Version 1.3 is currently under development.

(1)	Added support for Bells during before or after acquisitions.

(2)	Enhanced for Microsoft Windows compatibility.

(3)	Dropped support for BASIC and Pascal.

(4)	ABF functional interface reworked and expanded to provide both high and low level access, and to be compatible with multi-tasking, multi-threaded operating systems.

Discrepancies

This file structure is complex and is used by many programs.  Please report all discrepancies, even if they seem trivial.

File Structure

The AXON BINARY FILE is made up of a number of sections as follows:

The header and data sections appear in the order shown.  The other sections may appear in any order since they are pointed to by parameters in the header.  All sections are buffered in blocks of 512 bytes each.  The starting location of a section is given as a block number.  Block number 0 represents the start of the file.  If the block-number pointer to a section (other than the header) is zero, the corresponding section is not written.


What Kind Of Data Are Stored In ABF Files?

Axon Instruments data acquisition programs acquire five types of data, all of which are stored in ABF format files.

(1) Gap Free.  (nOperationMode = 3)

Gap-free ABF files contain a single episode of up to 4 GB of multiplexed data.  A uniform sampling interval is used throughout.  To date, there is no stimulus waveform associated with gap-free data.

Gap-free mode is usually used for the continuous acquisition of data in which there is a fairly uniform activity over time.

(2) Variable-Length Event-Driven.  (nOperationMode = 1)

(3) Fixed-Length Event-Driven.  (nOperationMode = 2)

In these two event-driven data acquisition modes, data acquisition is initiated in segments whenever a threshold-crossing event is detected.  To date, there is no stimulus waveform associated with gap-free data.

Fig.  Graphical comparison of gap-free acquisition with the event driven modes of acquisition.

In variable-length event-driven acquisition, pre-trigger and trailing portions below threshold are also acquired.  The length of the segment of data is determined by the nature of the data, being automatically extended according to the amount of time that the data exceeds the threshold.  If the pre-trigger portion of the next event would overlap the trailing portion of the current event, the current segment is extended.  There is no storage of overlapping data.  The precise start time and length of each segment is stored in the Synch Array.

Variable-length event-driven acquisition is usually used for the continuous recording of "bursting" data in which there are bursts of activity separated by long quiescent periods.

In fixed-length event-driven acquisition, a pre-trigger portion below threshold is acquired.  Unlike variable-length event-driven acquisition, the length of each segment of data is a pre-specified constant for all segments.  For this reason, the segments are often referred to as episodes.  In this mode, every threshold crossing triggers an episode, therefore fixed-length event-driven mode is also sometimes referred to as loss-free oscilloscope mode.  If a second event occurs before the current episode is finished, a second episode is acquired triggered from the second event.  This occurrence is referred to as overlap.  In this case, consecutive episodes in the data file contain redundant data.

The precise start time and length of each episode is stored in the Synch Array.  Although the length of each episode is redundant in this mode, it is stored in order to simplify reading and writing of the Synch Array.  Similarly, the storage of redundant data during overlap is not strictly necessary, but it simplifies analysis and display for each episode to be returned as a fixed-length episode with a known and constant trigger time.  Since no triggers are lost, fixed-length event-driven acquisition is ideal for the statistical analysis of constant-width events such as action potentials.

(4) High-Speed Oscilloscope Mode.  (nOperationMode = 4)

Like fixed-length event-driven acquisition, in high-speed oscilloscope mode a pre-trigger portion below threshold is acquired.  Unlike fixed-length event-driven acquisition, in high-speed oscilloscope mode not every threshold crossing triggers an episode.  The emphasis is on allowing the digitizer to be used at the highest possible sampling rate.  Like a real high-speed oscilloscope, there is a "dead time" at the end each sweep during which the display is updated and the trigger circuit is re-armed.  Threshold crossings that arrive during this dead time are simply ignored.  Similarly, second and subsequent threshold crossings during a sweep do not start a new episode.  Thus there is no storage of overlapping (redundant) data.

Although the acquisition conditions are different for fixed-length event-driven and high-speed oscilloscope modes, in practice the data file formats are identical and analysis programs can treat them identically.  The only caution is that because of the storage of overlapping data that is possible in fixed-length event-driven acquisition, the start time of a sweep might occur before the end of the previous sweep.

(5) Hierarchical Waveform Mode.  (nOperationMode = 5)

In this mode, a number of equal-length episodes (also known as sweeps) are acquired.  A set of parametrically related episodes is called a run.  Runs can be repeated a specified number of times to form a trial.  If runs are repeated, the corresponding episodes in each run are automatically averaged and the trial contains only the average.  The trial is stored in a file.  Only one trial can be stored in an ABF file.

Within each episode a complex stimulus waveform consisting of up to ten epochs can be generated.  One output sample is generated for each A/D conversion.  Note that this refers to the multiplexed A/D conversions.  For example, if there are three multiplexed A/D channels and the episodes contain 500 samples for each channel, the D/A converter generates 1500 samples.  Thus there is a stimulus waveform sample corresponding to every sample in the de-multiplexed A/D waveform.

The amplitudes and durations of the steps, ramps and digital (i.e. TTL) pulses comprising the epochs can be automatically incremented from episode to episode (see the Epoch Waveform and Pulses section of the ABF header).  Instead of creating epoch-based waveforms, the user can choose to read the stimulus waveform from a file. Whichever method is used, a full array containing the stimulus waveform is provided by the ABF routines when the applications programmer requests the stimulus waveform array associated with any episode.

The sampling interval (fADCSampleInterval) can change once within the episode to a second interval (fADCSecondSampleInterval).  If the applications programmers requests the X (i.e. time) array for the episode, the ABF reading routines provide an array that contains the properly spaced time intervals taking into account the shift in the sampling interval.  Note that irrespective of whether the acquisition program specifies the sampling interval on a per-channel or a multiplexed basis, the value stored in the ABF file is the multiplexed value.  In the three channel example used previously, if each channel were sampled at 21 µs, the multiplexed sampling interval would be 7 µs.

ABF hierarchical waveform data files may also contain a special pseudo channel known as the Math Channel.  This channel is the result of an arithmetic manipulation of two acquired data channels.  In actual fact, the math channel data are not stored in the file.  Instead, the formula and the acquired data channels are stored.  However, as a practical matter the applications programmer need not know that the math channel data are not stored, since if the math channel is requested, the ABF routines calculate the result and return the math channel array.  On the other hand, for more flexible analysis purposes, the applications programmer can take advantage of the fact that the math channel is created on the fly during reading by altering the parameters of the formula before requesting the math channel array.

A correction technique called P/N leak subtraction can be applied to one selected ADC channel during acquisition.  This sophisticated technique is specific to intracellular voltage-clamp measurements.  Using this technique, passive cell membrane responses are removed from the signal on the selected ADC channel before storage.  Although P/N leak subtraction is an important acquisition technique, it does not directly affect data analysis because from the data handling and storage perspective the P/N leak subtracted ADC channel is not different to the other ADC channels.

Another acquisition technique that does not directly affect data analysis is the application of conditioning trains.  These are trains of pulses that are applied to condition the cell membrane before the episode commences.  No data are stored during the conditioning trains.

Many of the parameters of an acquisition can be arbitrarily specified for each episode by a comma-separated list of variables.  These are stored in the Variable Parameter User List.  The user list (sParamValueList) can only be applied to a single selected parameter (nParamToVary).  Analysis programs should consider reading and parsing the user list since it is sometimes useful to plot extracted results in an X-Y plot with the user list values determining the X axis.  When a user list is enabled (nListEnable) it overrides the usual specification for the selected parameter.


ABF Hardware And Storage Limits

Some of the more important limitations in the range of hardware supported and the size of components in ABF formatted files are listed here.

•	Sixteen physical ADC channels, numbered 0-15.

•	Up to sixteen bits per ADC word.

•	Up to 16 K (16,384) multiplexed samples per episode in high-speed oscilloscope mode, fixed-length event-driven mode and hierarchical waveform mode.

•	Up to 2 G multiplexed samples per segment in variable-length event-driven mode and gap-free mode.

•	Stimulus waveform generated on one DAC channel only.

•	Conditioning train generated on one DAC channel only.

•	One Math Channel.

•	One Autosampled instrument.

•	One Leak Subtracted ADC channel.

•	One set of display amplifications and offsets.

•	Only one averaged Run per file!


ADC Channel Numbering

Axon's data acquisition programs distinguish between physical and logical channel numbers. Physical channel numbers are the channel numbers used internally to communicate with the acquisition hardware.  Logical channel numbers are the external connector labels on the front panel of the acquisition hardware.  Logical channel numbers are used only for presentation to the user.  Physical channel numbers are used everywhere else.  For example, parameters are stored using physical channel number order (0 to 15) for such structures as the sampling sequence array and the entries for the external lowpass and highpass filters.  Similarly, a physical channel number is used for the Trigger channel.  At the time of printing this document, the only digitizer known to have different physical and logical channel numbering is the (now obsolete) TL-2 interface.

Indexing Arrays in the ABF Header

To get a Logical channel number from a Physical channel number, simply index the nADCPtoLchannelMap array by the Channel number you wish to convert.  Thus nADCPtoLchannelMap[0] provides the Logical Channel Number for Physical Channel Number 0. This array is always symmetrical, so it can be used in the same way to convert back to Physical Channel Numbers from Logical Channel Numbers.

The first thing to look at is the nADCSamplingSeq array. This tells you which physical ADC channels were acquired and in what order.  The first entry in this array is the Physical channel number of the first ADC channel acquired, followed by the second etc.  There are nADCNumChannels channels in this array.  All ADC arrays except for the nADCSamplingSeq are indexed through Physical channel numbers. These include: sADCChannelName, sADCUnits, etc.

Special Note: All array indexing within the header and within the ABF routines start at 0, except Episode number, which starts at 1.

Example

/* Get first physical channel number and name*/

FirstPhysicalChannel = nADCSamplingSeq[0];

ChannelName = sADCChannelName[FirstPhysicalChannel];

/* Get channel number to show to user */

FirstLogicalChannel = nADCPtoLchannelMap[FirstPhysicalChannel];

fprint("The channel # is %d\n",FirstLogicalChannel);

/*  Get start time of first episode of first channel */

FirstEpisode = 1;

ABF_GetStartTime(nFile, pHeader, FirstPhysicalChannel, FirstEpisode,

                 &fStartTime, NULL);


Axon Binary Files (ABF) - ABF File Format - Definitions
Definitions

Term	Definition
Instrument	Refers to the external measurement equipment.  For example, an Axopatch, an Axoclamp, or a SmartProbe.
ADC  A/D	Analog-to-Digital converter.
DAC  D/A	Digital-to-Analog converter.
Sample	The datum produced by one A/D conversion or the datum describing one D/A output.
Sequence	A set containing one sample from each of the actively sampled input channels and one sample for each of the actively generated output channels.
Trace	A continuous set of data samples from a single A/D channel.
Episode	A continuous set of data samples multiplexed from all A/D channels.
Sweep	Synonym for "episode".  AxoTape uses "sweeps";  Clampex uses "episodes".
Run	A group of related episodes.
Trial	Non waveform files:  A group of one or more episodes acquired at one time.  The start time and length of each episode are described in the SYNCH array. Waveform files:  If there was no averaging, a trial is the same as the single acquired run.  If there was averaging, the trial contains the average of the two or more acquired runs.
File	Each data file contains one trial.
Hierarchy	A file contains one trial.  A Trial contains one or more runs.  A run contains one or more episodes.  An episode contains one or more ADC channels.


Autosampling

Axon Instruments' acquisition programs can automatically read the gain and lowpass filter settings of the analog instrument (e.g. patch clamp) on one ADC channel (nAutosampleADCNum).  If the ABF reading routines are used the autosampled gain must be taken into account when calculating the signal scale factor for the autosampled channel, as must the autosampled lowpass filter setting.  Both of these factors are automatically taken into account by the high level ABF reading routines.


Composite Values

In some cases, several parameters must be considered together to correctly interpret the data.

Composite ADC scale factor	fInstrumentScaleFactor[n] * fAutosampleAdditGain * fADCProgrammableGain[n] * fSignalGain[n]. Note, the fAutosampleAdditGain only applies to the autosampled ADC channel.
Composite ADC offset	fInstrumentOffset[n] + fSignalOffset[n]
Composite lowpass filter -3 dB frequency	A complex function of fSignalLowpassFilter and fAutosampleFilter, for the autosampled ADC channel.  On other ADC channels, only the fSignalLowpassFilter contributes to the composite value.
The functions ABFH_GetADCtoUUFactors() and ABFH_GetDACtoUUFactors() should be used to get the combined scale factors required for converting ADC/DAC values to UserUnits and vice versa.


Names, Units And Signal Conditioners

Names and Units for the ADC and DAC channels are stored in the Multi-Channel Information section of the ABF header.

A signal conditioner is a programmable analog device for applying filtering, gain and offset to the signal before digitization.  ABF formatted files store signal conditioning information for each channel in the following arrays: fSignalGain(), fSignalOffset(), fSignalLowpassFilter(), fSignalHighpassFilter().


Data Types

float	IEEE floating point format, 4 bytes long.
long	32-bit signed integer.
DWORD	32-bit unsigned integer
short	16-bit signed integer.
WORD	16-bit unsigned integer.
int	signed integer of the native size of the CPU
UINT	unsigned integer of the native size of the CPU
nn*char	String containing nn one-byte characters.  (Not NULL terminated.)
Unused real parameters should be filled with zeros.  Unused strings should be filled with the space character (ASCII #32).

Parameters for unsampled ADC channels should be filled with the indicated default.


File Version Numbers

The file version number consists of a major and a minor number.  For example, the "1" in Version 1.0 is the major number, and the "0" is the minor number.

In general, the major version number is updated when changes affect the byte offset of the existing parameters or would otherwise make the file unusable by existing programs.  The minor version number is updated when unused parameters are utilised.  In most cases, existing programs will not be affected since they should not be dependent upon the unused parameters.


ABF Header Section

Overview

File ID and Size information

File Structure

Trial Hierarchy Information

Display Parameters

Hardware Information

Environmental information

Multi-channel information

Synchronous timer outputs

Epoch Waveform and Pulses

DAC Output File

Conditioning pulse train

Variable Parameter User List

Autopeak measurement

Channel Arithmetic

On-line Subtraction

Unused space at end of header block


Axon Binary Files (ABF) - ABF Header Section - Overview
Overview

The ABF file header fully describes the contents of the ABF file, providing version information, and a complete set of the experimental parameters in effect during the acquisition.

The total header length = 2048 bytes.
Offsets in the lists which follow are Byte offsets.


File ID and Size information

(40 bytes)

These ten entries represent two types of information:  (1) File identification information;  (2) Parameters whose actual value may be different to the value requested before the acquisition commenced, e.g. due to a user abort.  The requested values are located elsewhere.

Offset	Header Entry Name	Type	Description
0	sFileType	4char	File type used for format identification.  Possible values are:   "ABF ", "CLPX" and "FTCX".  Used to create the numbers in nFileType. (In old pCLAMP and Axotape data files, the first four bytes were a float:    1 = CLAMPEX,    10 = FETCHEX/AxoTape. This is translated on reading into either CLPX or FTCX as appropriate.)
4	fFileVersionNumber	float	File format version stored in the data file during acquisition.  The present version is 1.2.  (In old pCLAMP and Axotape data files, this parameter is in the range 2.0-5.3)
8	nOperationMode	int	Operation mode: 1 = Event-driven, variable length;  2 = Oscilloscope, loss free (Same as Event-driven, fixed length);  3 = Gap-free;  4 = Oscilloscope, high-speed;  5 = Waveform, fixed length (Clampex only).
10	lActualAcqLength	long	Actual number of ADC samples (aggregate) in data file.  See lAcqLength.  Averaged episodes are included.
14	nNumPointsIgnored	int	Number of points ignored at data start.  Normally zero, but non-zero for gap-free acquisition using AXOLAB configurations with one or more ADS boards.
16	lActualEpisodes	long	Actual number of episodes in the file including averaged episodes.  See lEpisodesPerRun.  If nOperationMode = 3 (gap-free) the value of this parameter is 1.
20	lFileStartDate	long	Date when data portion of this file was first written to.  Stored as YYMMDD.  If YY is in the range 80-99, prefix with "19" to get the year.  If YY is in the range 00-79, prefix with "20" to get the year.
24	lFileStartTime	long	Time of day in seconds past midnight when data portion of this file was first written to.
28	lStopwatchTime	long	Time since the stopwatch was zeroed that the data portion of this file was first written to.  Not supported by all programs.  Default = 0.
32	fHeaderVersionNumber	float	Version number of the header structure returned by the ABF_ReadOpen function.  Currently 1.2.  This parameter does not identify the data file format.  See fFileVersionNumber.
36	nFileType	int	Numeric equivalent of file type.  1 = ABF file;  2 = Old FETCHEX file (FTCX);  3 = Old Clampex file (CLPX).  See sFileType.
38	nMSBinFormat	int	Storage method for real numbers in the header.  Also see nDataFormat.  0 = IEEE format;  1 = Microsoft Binary format (old files only).


File Structure

(80 bytes)

Header entries describing the structure of the file.

Offset	Header Entry Name	Type	Description
40	lDataSectionPtr	long	Block number of start of Data section.
44	lTagSectionPtr	long	Block number of start of Tag section.
48	lNumTagEntries	long	Number of Tag entries.
52	lUnused52	long	(was block number of start of Long Description section.)
56	lUnused56	long	(was number of lines of Long Description.)
60	lDACFilePtr	long	Block number of start of DAC file section.
64	lDACFileNumEpisodes	long	Number of episodes in the DAC  file section.  Episodes are not multiplexed.
68	sUnused68	4char	Unused.
72	lDeltaArrayPtr	long	Block number of start of Delta Array section.
76	lNumDeltas	long	Number of entries in Delta Array section.
80	lUnused80	long	(was block number of start of Notebook section)
84	lUnused84	long	(was number of manual entries in Notebook section)
88	lUnused88	long	(was number of automatic entries in Notebook section)
92	lSynchArrayPtr	long	Block number of start of the Synch Array section.
96	lSynchArraySize	long	Number of pairs of entries in the Synch Array section.  If averaging is enabled, this includes the entry for the averaged episode.
100	nDataFormat	int	Data representation.  0 = 2-byte integer;  1 = IEEE 4 byte float.
102	sUnused102	18char	Unused.


Trial Hierarchy Information

(80 bytes)

Header entries describing the trial hierarchy.

Offset	Header Entry Name	Type	Description
120	nADCNumChannels	int	Number of analog input channels sampled.
122	fADCSampleInterval	float	Interval between multiplexed A/D samples (us).  In Clampex, this is also known as the first clock interval.
126	fADCSecondSample Interval	float	Second definition of the interval between multiplexed A/D samples  (us).  If this interval is zero, the first clock interval is used for the whole of each episode.  If this interval is non-zero, the second clock interval starts at the sample number specified by lClockChange.
130	fSynchTimeUnit	float	Time unit for start time in the Synch Array section: 0 = Value in sample intervals;  nn = Value in us.  See notes below for the Synch Array section.  pCLAMP 6.0 and AxoTape 2.0 use value in sample intervals only.
134	fSecondsPerRun	float	Requested acquisition length in seconds.  0 means use available disk space.  -1 means ignore this parameter and refer to lEpisodesPerRun.
138	lNumSamplesPerEpisode	long	Number of multiplexed ADC samples per episode if nOperationMode is 2, 4, or 5.  Undefined if nOperationMode is 1 or 3.
142	lPreTriggerSamples	long	Pre-trigger interval stored as number of multiplexed ADC samples (note that this is the underlying number of ADC samples, not the number of pre-trigger samples in the trigger channel).  FETCHEX uses the same value for the post-trigger interval.  Undefined if nOperationMode is 3 or 5.
146	lEpisodesPerRun	long	Requested number of episodes/run.  If nOperationMode = 3 (gap free), this parameter is 1 and the requested acquisition length is set in fSecondsPerRun.
150	lRunsPerTrial	long	Requested number of runs/trial.  Runs are averaged.  If nOperationMode = 3 (gap free), the value of this parameter is 1.  See lAverageCount.
154	lNumberOfTrials	long	Number of trials to be acquired.  Note, only one trial is contained in a data file.  This parameter is used for Clampex acquisition control.  -1 = continuous.
158	nAveragingMode	int	Data averaging strategy: 0 = No averaging; 1 = Average but don't save raw data; 2 = Average and save raw data.
160	nUndoRunCount	int	Frequency with which temporary undo file created during averaging is updated.  -1 = Disabled;  0 = after each pseudo-doubling;  N = after every N runs.
162	nFirstEpisodeInRun	int	First episode number (normally 1).
164	fTriggerThreshold	float	Trigger threshold value for Event or Oscilloscope mode (user units).
168	nTriggerSource	int	Trigger source:  N (>=0) = Physical channel number selected for threshold detection;  -1 = external trigger;  -2 = keyboard;  -3 =  use start-to-start interval. If nOperationMode=-3 (gap-free)  0= start immediately.
170	nTriggerAction	int	Trigger start strategy: 0 = start one episode;  1 = start one run;  2 = start one trial.
172	nTriggerPolarity	int	Trigger on:  0 = rising edge of waveform;  1 = falling edge.  The terms "rising" and "falling" refer to the direction of the data transitions on the screen during acquisition.
174	fScopeOutputInterval	float	Interval between digital output used for external oscilloscope, or equivalent, and the start of each episode (ms)
178	fEpisodeStartToStart	float	Time between start of episodes (seconds).  Use when nTriggerSource = "start-to-start".
182	fRunStartToStart	float	Time between start of runs (seconds).
186	fTrialStartToStart	float	Time between trials (seconds).
190	lAverageCount	long	The actual number of runs contributing to each average.  See lEpisodesPerRun or lRunsPerTrial.
194	lClockChange	long	The multiplexed ADC sample number after which the second sampling interval commences.  0 = lNumSamplesPerEpisode/2.  See fADCSecondSampleInterval.
198	sUnused198	2char	Unused.


Display Parameters

(44 bytes)

Header entries describing display options in effect during acquisition.

Offset	Header Entry Name	Type	Description
200	nDrawingStrategy	int	Strategy for the drawing of raw data:   0 = not at all;  1 = update immediately as data is acquired;  2 = update at the end of each episode or trace;  3 = update at the end of each run;
202	nTiledDisplay	int	ADC channel display arrangement:  0 = Superimposed;  1 = Tiled.
204	nEraseStrategy	int	Automatically erase screen: 0 = not at all;  1 = before each episode;  2 = before each run.
206	nDataDisplayMode	int	Data display mode: 0 = Points;  1 = Lines.
208	lDisplayAverageUpdate	long	Display averaged data:  -1 = at end of trial;  0 = after each pseudo-doubling;  N = after N runs.
212	nChannelStatsStrategy	int	Show channel statistics in gap-free mode: 0 = No;  1 = Yes.
214	lCalculationPeriod	long	Length of the real-time statistics update period in samples.  Conventionally a multiple of 1024.  Default = 16384.
218	lSamplesPerTrace	long	Number of multiplexed ADC samples in displayed trace.
222	lStartDisplayNum	long	Starting sample number for episode display:  N = starting sample number.  (Use N = 1 to start from the first sample.)
226	lFinishDisplayNum	long	Finishing sample number for episode display:  0 = finish at end of episode;  N = finishing sample number.
230	nMultiColor	int	Color control for multi-trace displays.  0 = single color for all traces;  1 = two or more colors for traces.
232	nShowPNRawData	int	0 = display corrected data;  1 = display raw data.
234	sUnused234	10char	Unused.


Hardware Information

(16 bytes)

Description of hardware properties of digitiser used for acquisition.

Offset	Header Entry Name	Type	Description
244	fADCRange	float	ADC positive full-scale input in volts (e.g. 10.00V).
248	fDACRange	float	DAC positive full-scale range in volts.
252	lADCResolution	long	Number of ADC counts corresponding to the positive full-scale voltage in ADCRange (e.g. 2000, 2048, 32000 or 32768).
256	lDACResolution	long	Number of DAC counts corresponding to the positive full-scale voltage in DACRange.


Environmental information

(118 bytes)

Offset	Header Entry Name	Type	Description
260	nExperimentType	int	Experiment type:  0 = Voltage Clamp;  1 = Current Clamp.
262	nAutosampleEnable	int	Enable storage of autosample information:  0 = Disabled;  1 = Automatic;  2 = Manual.
264	nAutosampleADCNum	int	Physical ADC channel number to which autosampled parameters apply.
266	nAutosampleInstrument	int	Autosample instrument: 1 = Axopatch-1 with CV-4-1/100; 2 = Axopatch-1 with CV-4-0.1/100; 3 = Axopatch-1B(inv.) CV-4-1/100; 4 = Axopatch-1B(inv) CV-4-0.1/100; 5 = Axopatch 200 with CV 201; 6 = Axopatch 200 with CV 202; 7 = GeneClamp. 8 = Dagan 3900 9 = Dagan 3900A 10 = Dagan CA-1  Im=0.1 11 = Dagan CA-1  Im=1.0 12 = Dagan CA-1  Im=10 13 = Warner OC-725 (IHS-1 telegraphs are not supported.)   Note, for most programs this is an information-only field.  For example, in Clampex the autosample instrument is chosen as a configuration item and copied into this field.
268	fAutosampleAdditGain	float	Additional gain multiplier of Instrument connected to nAutosampleADCNum.  (Optionally autosampled by some acquisition programs.)   (Default = 1)
272	fAutosampleFilter	float	Lowpass filter cutoff frequency of Instrument connected to nAutosampleADCNum.  (Optionally autosampled by some acquisition programs.)   (Default = 100000)
276	fAutosampleMembraneCap	float	Patch-clamp membrane capacitance compensation.  (Optionally autosampled by some acquisition programs.)
280	nManualInfoStrategy	int	Strategy for writing the manually entered information:  0 = Do not write;  1 = Write each trial;  2 = Prompt each trial..
282	fCellID1	float	Numeric identifier #1, e.g. cell identifier.
286	fCellID2	float	Numeric identifier #2, e.g. temperature in °C.
290	fCellID3	float	Numeric identifier #3.
294	sCreatorInfo	16char	Name and version of program used to create the file.  For example, "AxoTape 2.0" or "Clampex 6.0".
310	sFileComment	56char	56 byte ASCII comment string.
366	sUnused366	12char	Unused.


Multi-channel information

((160 + 384 + 488 + 12)=1044  bytes).

Offset	Header Entry Name	Type	Description
378	nADCPtoLChannelMap (0-15)	int	ADC physical-to-logical channel map.  The entries are in the physical order 0, 1, 2, ... 14, 15.  If there are fewer than 16 logical channels in the system, the array is padded with -1.  All channels supported by the hardware are present, even if only a subset is used.  For example, for the TL-2 the entries would be 7, 6, 5, 4, 3, 2, 1, 0, -1 ... -1.
410	nADCSamplingSeq (0-15)	int	ADC channel sampling sequence.  This is the order in which the physical ADC channels are sampled.  If fewer than the maximum number of channels are sampled, pad with -1.  For example, if two channels are sampled on the TL-2, this array will contain 6, 7, -1 ... -1.  If two channels are sampled on the TL-1, this array will contain 14, 15, -1 ... -1.
442	sADCChannelName (0-15)	10char	ADC channel name in physical channel number order.  Default = spaces.
602	sADCUnits(0-15)	8char	The user units for ADC channels in physical channel number order.  Default = spaces.
730	fADCProgrammable Gain(0-15)	float	ADC programmable gain in physical channel number order (dimensionless).  Default = 1.
794	fADCDisplay Amplification(0-15)	float	ADC channel display amplification in physical channel number order (dimensionless.)   Default = 1.
858	fADCDisplayOffset (0-15)	float	ADC channel display offset in physical channel number order (user units).  Default = 0.
922	fInstrumentScaleFactor (0-15)	float	Instrument scale factor in physical ADC channel number order (Volts at ADC / user unit).  (Programs would normally display this information to the user as user units / volt at ADC).
986	fInstrumentOffset(0-15)	float	Instrument offset in physical ADC channel number order (user units corresponding to 0 V at the ADC).  Default is zero.
1050	fSignalGain(0-15)	float	Signal conditioner gain in physical ADC channel number order (dimensionless).  Default = 1.
1114	fSignalOffset(0-15)	float	Signal conditioner offset in physical ADC channel number order (user units).  Default = 0.
1178	fSignalLowpassFilter (0-15)	float	Signal-conditioner lowpass filter corner frequency in physical ADC channel number order (Hz).  100000 means lowpass filter is bypassed (i.e. wideband).  Default = 100000.
1242	fSignalHighpassFilter (0-15)	float	Signal-conditioner highpass filter corner frequency in physical ADC channel number order (Hz).  0 means highpass filter is bypassed (i.e. DC coupled).  -1 means inputs are grounded.  Default = 0.
1306	sDACChannelName (0-3)	10char	DAC channel name.  Default = spaces.
1346	sDACChannelUnits (0-3)	8char	The user units for this DAC channel.  Default = spaces.
1378	fDACScaleFactor(0-3)	float	DAC channel gain (user units / V at DAC).  Default = 1
1394	fDACHoldingLevel(0-3)	float	DAC channel holding level (user units).  Default = 0.
1410	nSignalType	12char	Type of signal conditioner that was used.  0 = None;  1 = CyberAmp 320/380.
1412	sUnused1412	10char	Unused.


Synchronous timer outputs

(14 bytes)

Synchronous timer outputs were dropped from pCLAMP version 6.  These parameters have been kept in the ABF 1.0 specification for compatibility when reading old data files.  New programs should write zeros to all of the parameters in this group.

Offset	Header Entry Name	Type	Description
1422	nOUTEnable	int	Enable synchronous timer outputs:  0 = No;  1 = Yes.
1424	nSampleNumberOUT1	int	Sample number for pulse on synchronous timer OUT #1.
1426	nSampleNumberOUT2	int	Sample number for pulse on synchronous timer OUT #2.
1428	nFirstEpisodeOUT	int	First episode at which synchronous timer OUT #1 and #2 fire.
1430	nLastEpisodeOUT	int	Last episode at which synchronous timer OUT #1 and #2 fire.
1432	nPulseSamplesOUT1	int	Duration and polarity of pulse on synchronous timer OUT #1 (DAC samples).
1434	nPulseSamplesOUT2	int	Duration and polarity of pulse on synchronous timer OUT #2 (DAC samples).


Epoch Waveform and Pulses

(184 bytes)

Offset	Header Entry Name	Type	Description
1436	nDigitalEnable	int	Enable digital outputs:  0 = No;  1 = Yes.
1438	nWaveformSource	int	Analog waveform source:  0 = Disable;  1 = Generate waveform from epoch definitions;  2 = Generate waveform from a DAC file.
1440	nActiveDACChannel	int	Active DAC channel, i.e. the one used for waveform generation.
1442	nInterEpisodeLevel	int	Inter-episode holding level:  0 = Use holding level;  1 = Use last epoch amplitude.
1444	nEpochType(0-9)	int	Epoch type:  0 = Disabled;  1 = Step;  2 = Ramp
1464	fEpochInitLevel(0-9)	float	Epoch initial level (user units)
1504	fEpochLevelInc(0-9)	float	Epoch level increment (user units)
1544	nEpochInitDuration (0-9)	int	Epoch initial duration (in sequence counts).
1564	nEpochDurationInc(0-9)	int	Epoch duration increment (in sequence counts)
1584	nDigitalHolding	int	Holding value for digital output.
1586	nDigitalInterEpisode	int	Inter-episode digital holding value:  0 = Use holding value;  1 = Use last epoch value.
1588	nDigitalValue(0-9)	int	Epoch value for digital output.
1608	sUnavailable1608 (was fWaveformOffset)	4char	This parameter was used by CLAMPFIT 6.0, do not reuse. Offset (in active DAC user units) in instrument command pathway, usually due to a non-zero holding potential or current.
1612	sUnused1612	8char	Unused.


DAC Output File

(98 bytes)

Note that DAC output status is controlled by nWaveformSource.

Offset	Header Entry Name	Type	Description
1620	fDACFileScale	float	Scaling factor to apply to DACfile contents.
1624	fDACFileOffset	float	Offset (in user units) to apply to DACfile contents.
1628	sUnused1628	2char	Unused.
1630	nDACFileEpisodeNum	int	Episode (or column) number to replay from waveform file:  -1 = all episodes except the first (which is skipped), repeating last if necessary;  0 = all episodes;  N = Episode number.
1632	nDACFileADCNum	int	Logical ADC channel number to replay from waveform file.
1634	sDACFileName	12char	Name of DAC file located in data directory.  Must be ABF or ATF format.
1646	sDACFilePath	60char	Drive and directory for sDACFileName.
1706	sUnused1706	12char	Unused.


Conditioning pulse train

(44 bytes)

Offset	Header Entry Name	Type	Description
1718	nConditEnable	int	Conditioning pulse train activation status:  0  = Disable;  1 = Enable
1720	nConditChannel	int	DAC channel used for conditioning pulses.
1722	lConditNumPulses	long	Number of pulses in conditioning pulse train
1726	fBaselineDuration	float	A single pulse in the conditioning train consists of a baseline followed by a step.  This parameter is the baseline duration in ms
1730	fBaselineLevel	float	Baseline level (user units)
1734	fStepDuration	float	Step duration (ms)
1738	fStepLevel	float	Step level (user units)
1742	fPostTrainPeriod	float	At the end of the conditioning train there is a post-train steady-state output.  This parameter is the post-train duration in ms.
1746	fPostTrainLevel	float	Post-train level (user units)
1750	sUnused1750	12char	Unused.


Variable Parameter User List

( 82 bytes)

Offset	Header Entry Name	Type	Description
1762	nParamToVary	int	Holds the index of the parameter that varies from episode to episode in one run. CONDITNUMPULSES=0 CONDITBASELINEDURATION=1 CONDITBASELINELEVEL=2 CONDITSTEPDURATION=3 CONDITSTEPLEVEL=4 CONDITPOSTTRAINDURATION=5 CONDITPOSTTRAINLEVEL=6 EPISODESTARTTOSTART =7 INACTIVEHOLDING=8 DIGITALINTEREPISODE=9 PNNUMPULSES=10 PARALLELVALUE(0-9)=11-20 EPOCHINITLEVEL(0-9)=21-30 EPOCHINITDURATION(0-9)=31-40
1764	sParamValueList	80char	List of comma-separated values.  If the number of entries in the list is fewer than the requested number of episodes, the last list value is re-used.  If there are more values in the list, the excess list values are ignored.
			See also nListEnable in Group #16.


Autopeak measurement

(36 bytes).

Offset	Header Entry Name	Type	Description
1844	nAutopeakEnable	int	Autopeak activation status:  0  = Disabled;  1 = Enabled.
1846	nAutopeakPolarity	int	-1 = search for negative peaks;  0 = search for absolute peak;  1 = search for positive peaks.
1848	nAutopeakADCNum	int	Physical ADC channel number to measure.
1850	nAutopeakSearchMode	int	Search mode:  0-9 = epoch A-J;  -1 = All;  -2 = Use specified region.
1852	lAutopeakStart	long	Start of specified autopeak region.  Only valid if nAutopeakSearchMode = -2.
1856	lAutopeakEnd	long	End of specified autopeak region.  Only valid if nAutopeakSearchMode = -2.
1860	nAutopeakSmoothing	int	Number of samples averaged in boxcar smoothing window when looking for a peak.
1862	nAutopeakBaseline	int	Baseline for autopeak measurements:  -2 = None; -1 = Average the first (lNumSamplesPerEpisode/64) samples;  0-9 = epoch A-J
1864	nAutopeakAverage	int	0 = search average and data;  1 = search average only.
1866	sUnused1866	14char	Unused.


Channel Arithmetic

(52 bytes)

Several standard arithmetic expressions are supported:

Expression #0 (general purpose)
Result = (K1*A + K2) <op> (K3*B + K4)

Expression #1 (ratio dyes)
Result = (K1*R + K2) <op> (K3*R + K4)
where
R = (A + K5)/(B + K6)

In both cases:
A and B are ADC channel numbers.  A = B is allowed.
K1 .. K6 are constants.
<op> is an arithmetic operator.

Offset	Header Entry Name	Type	Description
1880	nArithmeticEnable	int	Arithmetic activation status:  0  = Disable;  1 = Enable
1882	fArithmeticUpperLimit	float	Display upper limit for arithmetic Results channel.
1886	fArithmeticLowerLimit	float	Display lower limit for arithmetic Results channel.
1890	nArithmeticADCNumA	int	Physical ADC channel number used for A.
1892	nArithmeticADCNumB	int	Physical ADC channel number used for B.
1894	fArithmeticK1	float	Numeric constant K1
1898	fArithmeticK2	float	Numeric constant K2
1902	fArithmeticK3	float	Numeric constant K3
1906	fArithmeticK4	float	Numeric constant K4
1910	sArithmeticOperator	2char	Arithmetic operator:  "+ ", "- ", "* " or "/ ".
1912	sArithmeticUnits	8char	Units for Results channel.
1920	fArithmeticK5	float	Numeric constant K5
1924	fArithmeticK6	float	Numeric constant K6
1928	nArithmeticExpression	int	The expression to evaluate:  N = Expression #N.
1930	sUnused1930	2char	Unused.


On-line Subtraction

(34 bytes).

Offset	Header Entry Name	Type	Description
1932	nPNEnable	int	P/N activation status:  0  = Disable;  1 = Enable
1934	nPNPosition	int	P/N subpulse execution:  0 = Before waveform;  1 = After waveform.
1936	nPNPolarity	int	-1 = opposite polarity to the waveform;  1 = same polarity as the waveform.
1938	nPNNumPulses	int	Number of P/N subpulses.
1940	nPNADCNum	int	Physical ADC channel number for P/N subtraction.
1942	fPNHoldingLevel	float	Subpulse holding level.
1946	fPNSettlingTime	float	Settling time at subpulse holding level (ms).  Wait this interval after changing to subpulse holding level before starting subpulses;  wait this interval after returning to normal holding level before starting epochs.
1950	fPNInterpulse	float	Timing interval between end of one subpulse and start of next (ms).
1954	sUnused1954	12char	Unused.


Unused space at end of header block

(82 bytes).

Offset	Header Entry Name	Type	Description
1966	nListEnable	int	Parameter list activation status:  0 = Disable;  1 = Enable
1968	nBellEnable(0-1)	int	Auditory tone activation status:  0 = Disable;  1 = Enable
1972	nBellLocation(0-1)	int	Location of bell relative to trial: 0 = Before;  1 = After
1976	nBellRepetitions(0-1)	int	Number of sounds to produce.
1980	sUnused1980	68char	Unused.
TOTAL  2048 bytes


The ABF Synch Array

Overview

The ABFSynch Structure


Axon Binary Files (ABF) - The ABF Synch Array - Overview
Overview

The ABF Synch array is used to store synchronisation information for acquisitions consisting of multiple episodes of events. It is created and used in the following acquisition modes: ABF_VARLENEVENTS, ABF_FIXLENEVENTS & ABF_HIGHSPEEDOSC.

The acquisition modes ABF_GAPFREEFILE and ABF_WAVEFORMFILE do not use a Synch array.

The ABF Synch array contains an entry for each Episode or Event in the data file.


The ABFSynch Structure

(8 bytes).

Offset	Header Entry Name	Type	Description
0	lStart	long	Start time of episode in fSynchTimeUnit units.
4	lLength	long	Length of the episode in fSynchTimeUnit units.


The ABF Tag Section

Overview

The ABFTag Structure


Axon Binary Files (ABF) - The ABF Tag Section - Overview
Overview

During an acquisition, some programs allow the user to tag points of interest in the input data stream. These tags are saved in the Tag Section.


The ABFTag Structure

(64 bytes).

Offset	Header Entry Name	Type	Description
0	lTagTime	long	Time at which the tag was entered in fSynchTimeUnit units.
4	sComment	56char	Optional comment to describe the tag.
60	lEpisodeNum	long	Episode in which the tag was entered. =0 for ABF_GAPFREEFILE files and for ABF_VARLENEVENTS files.


The ABF Deltas Section

Overview

The ABFDelta Structure


Axon Binary Files (ABF) - The ABF Deltas Section - Overview
Overview

When acquisition parameters are changed during an acquisition, the changes are tracked and entered in the ABF deltas section. Each entry is time stamped in fSynchTimeUnit units, so that the value of the parameter can be determined at any point during the acquisition.


The ABFDelta Structure

(64 bytes).

Offset	Header Entry Name	Type	Description
0	lDeltaTime	long	Time at which the parameter was changed in fSynchTimeUnit units.
4	lParameterID	long	Identifier for the parameter changed. Legal parameter values are: ABF_DELTA_XXXXXXXX
8	lNewParamValue fNewParamValue	long float	Depending on the value of lParameterID this entry may be either a float or a long.


The ABF File I/O Functions by category

Initialisation/Cleanup

File Open/Close

High Level File Reading

Low Level File Read/Write

Miscellaneous Functions


Initialisation/Cleanup

The initialisation and cleanup functions are only necessary when the ABF functions ARE NOT bound into a Windows DLL. In the Windows DLL version the initialise and cleanup functions are called automatically when the DLL is loaded/unloaded.

DOS programs and Windows programs that bind the ABFFILES.CPP module in directly must call ABF_Initialize() before calling any other ABF function. Similarly, ABF_Cleanup() should be called when the ABF functions are no longer required (prior to program termination).

Routine	Use
ABF_Initialize	Initialises the ABFFILES module.
ABF_Cleanup	Cleans up after use of ABF routines.


File Open/Close

The ABF API functions provides two functions for opening files, one for opening files for reading, the other for opening files for writing. Files opened for writing may not be read from, and files opened for reading may no be written to. The ABF_Close function must always be called to close a file successfully opened with either ABF_ReadOpen or ABF_WriteOpen.

Routine	Use
ABF_ReadOpen	Opens an ABF file for reading.
ABF_WriteOpen	Opens an ABF file for writing.
ABF_Close	Closes an ABF file that was previously opened with either ABF_ReadOpen or ABF_WriteOpen.


High Level File Reading

The high level file reading routines return data from the ABF file in fully scaled 4-byte floats, in the units specified by the user (UserUnits) at the preparation.

Routine	Use
ABF_ReadChannel	Reads an episode/chunk of data from a particular ADC channel, returning the data as fully scaled UserUnits.
ABF_GetWaveform	Gets the Waveform that was put out for a particular episode on a particular ADC channel in UserUnits.


Low Level File Read/Write

The low level file I/O routines read  and write raw data in two byte ADC/DAC samples.

Axon strongly recommends that third party developers use the High Level file reading routines in preference to these low level routines to avoid the complexity of doing the ADC to UserUnits conversion.

If the low level routines are used, the functions ABFH_GetADCtoUUFactors() and ABFH_GetDACtoUUFactors() should be used to retrieve the composite scale and offset factors used to convert ADC/DAC values to UserUnits.

Routine	Use
ABF_MultiplexRead	Reads an episode of multiplexed multi-channel ADC samples from the ABF file.
ABF_MultiplexWrite	Writes an episode of multiplexed multi-channel ADC samples to the ABF file.
ABF_ReadDACFileEpisode	Reads an episode of multiplexed multi-channel DAC samples from the DACFile section of the ABF file. (only valid if a DAC file was used for waveform generation)
ABF_WriteDACFileEpisode	Writes an episode of multiplexed multi-channel DAC samples to the DACFile section of the ABF file. This function should only be used after all acquired data has been written to the file.


Miscellaneous Functions

Routine	Use
ABF_BuildErrorText	Build an error string from an error number and a file name.
ABF_FindEpisode	Find the episode that contains a particular sample.
ABF_FindEpisodeStart	Find the sample at which a particular episode started.
ABF_GetMissingSamples	Get the count of samples missing before the start of this episode and the end of the previous episode.
ABF_GetNumSamples	Get the number of samples in this episode.


The ABF File I/O Functions

Overview

Error Return Values

ABF_BuildErrorText

ABF_Cleanup

ABF_Close

ABF_FindEpisode

ABF_FindEpisodeStart

ABF_GetMissingSamples

ABF_GetNumSamples

ABF_GetStartTime

ABF_GetWaveform

ABF_Initialize

ABF_MultiplexRead

ABF_MultiplexWrite

ABF_ReadChannel

ABF_ReadDACFileEpi

ABF_ReadOpen

ABF_ReadTags

ABF_UpdateHeader

ABF_WriteDACFileEpi

ABF_WriteOpen

ABF_WriteTag


Axon Binary Files (ABF) - The ABF File I/O Functions - Overview
Overview

The ABF file routines are a set of functions for creating and/or accessing ABF data files. Some functions are low level functions that will only be required by users acquiring ABF data files. Other functions provide higher level access to ABF data, returning fully scaled data values in the units of the acquired data.

NOTE:	Axon STRONGLY recommends that the ABF header structure should be accessed through the published header files, NOT by byte offsets within the binary image of the file header. In addition the ABFH_nnn functions should be used to extract data from the header where available.


Error Return Values

The return type for all ABF API functions is "BOOL". The interpretation of this value is that TRUE = Success, and FALSE = Failure of the function. Should a function call fail, an error number indicating the reason for failure is returned in the pnError parameter. If the reason for the error is not required, NULL may be passed for the pnError parameter.


ABF_BuildErrorText

#include "abffiles.h"

BOOL ABF_BuildErrorText( int nError, char *szFileName,
char *szTxtBuf, UINT uMaxLen );

The ABF_BuildErrorText function builds an error message for the specified error number.

Parameter	Description
nError	Error number to create message from.
szFileName	Name of file.
szTxtBuf	Buffer for error text.
uMaxLen	Size of szTxtBuf.
Returns

If nErrorNum contains a valid error number, this function places the generated text into szTxtBuf and returns TRUE, otherwise it returns FALSE.

Comments

The ABF_BuildErrorText function builds an error message based on nErrorNum and szFileName.

Example

#include "abffiles.h"

BOOL ShowABFError( char *szFileName, int nError )

{

   char szTxt[80];

   if (!ABF_BuildErrorText( nError, szFileName, szTxt, sizeof(szTxt) ))

      sprintf( szTxt, "Unknown error number: %d\r\n", nError );

   printf( "ERROR: %s\n", szTxt );

   return FALSE;

}


ABF_Cleanup

#include "abffiles.h"

void ABF_Cleanup( void );

Performs clean-up of the ABF file I/O module after use.

Comments

The ABF_Cleanup function removes all vestiges of the file I/O module from the system. It should be called once after file I/O processing is completed and no longer required.

Example

#include "abffiles.h"

void main( int argc, char **argv )

{

   ABFFileHeader FH;

   ABF_Initialize();

   ABFH_Initialize(&FH);

   Acquisition( argv[1], &FH );

   ABF_Cleanup();

}

See Also

ABF_Initialize


ABF_Close

#include "abffiles.h"

BOOL ABF_Close( int hFile, int *pnError );

Closes the specified data file.

Parameter	Description
hFile	ABF file handle.
pnError	Address of error return code. May be NULL.
Comments

The ABF_Close function closes the data file specified in hFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
ABF_EBADFILE	Could not close file.
Example

#include "abffiles.h"

int ReadChannelEpisode( char *pszFileName, int nChannel,

                        DWORD dwEpisode, float *pfBuffer,

                        UINT *puNumSamples )

{

   int hFile;

   int nError;

   ABFFileHeader FH;

   DWORD dwMaxEpi = 0;

   UINT uMaxSamples = 16 * 1024;

   if (!ABF_ReadOpen(pszFileName, &hFile, ABF_DATAFILE, &FH,

                     &uMaxSamples, &dwMaxEpi, &nError))

      return ShowABFError(pszFileName, nError);

   if (!ABF_ReadChannel( hFile, &FH, nChannel, dwEpisode, pfBuffer,

                         puNumSamples, &nError ))

   {

      ABF_Close( hFile, NULL );

      return ShowABFError(pszFileName, nError);

   }

   if (!ABF_Close( hFile, &nError ))

      return ShowABFError(pszFileName, nError);

   return TRUE;

}

See Also

ABF_ReadOpen
ABF_WriteOpen


ABF_FindEpisode

#include "abffiles.h"

BOOL ABF_FindEpisode( int hFile, ABFFileHeader *pFH,
DWORD *pdwSampleNumber, DWORD *pdwEpisode,
int *pnError );

Finds the episode number that contains a specified sample number.

Parameter	Description
hFile	ABF file handle.
pdwSampleNumber	Address of sample number to search for.
pdwEpisode	Address of episode number that contains the requested sample.
pnError	Address of error return code. May be NULL.
Comments

The ABF_FindEpisode function finds the episode number for the specified sample point number, and stores it in *pdwEpisode.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
Example

#include "abffiles.h"

BOOL FindAnEpisode( char *pszFileName, DWORD *pdwSample,

                    DWORD *pdwEpisode )

{

   int hFile;

   int nError = 0;

   ABFFileHeader FH;

   DWORD dwMaxEpi = 0;

   UINT uMaxSamples = 16 * 1024;

   if (!ABF_ReadOpen( pszFileName, &hFile, ABF_DATAFILE,

                      &FH, &uMaxSamples, &dwMaxEpi, &nError ))

      return ShowABFError(pszFileName, nError);

   if (!ABF_FindEpisode( hFile, &FH, pdwSample, pdwEpisode, &nError ))

   {

      ABF_Close( hFile, NULL );

      return ShowABFError(pszFileName, nError);

   }

   if (!ABF_Close( hFile, &nError ))

      return ShowABFError(pszFileName, nError);

   return TRUE;

}

See Also

ABF_FindEpisodeStart
ABF_GetMissingSamples
ABF_GetNumSamples


ABF_FindEpisodeStart

#include "abffiles.h"

BOOL ABF_FindEpisodeStart( int hFile, DWORD dwEpisode,
DWORD *pdwSampleNumber, int *pnError );

Finds the sample point number for the start of the specified episode number.

Parameter	Description
hFile	ABF file handle.
dwEpisode	Episode number that is being searched for.
pdwSampleNumber	Sample point number of the first point in the episode.
pnError	Address of error return code. May be NULL.
Comments

The ABF_FindEpisodeStart function finds the sample point number for the start of the specified episode number. It sets *pdwSampleNumber to the sample point number of the first point in the episode.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EEPISODERANGE	Episode number out of range.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
Example

#include "abffiles.h"

BOOL CopyDataFile(char *pszFileIn, int nFileIn, ABFFileHeader *pFI,

                  char *pszFileOut, int nFileOut, ABFFileHeader *pFO)

{

   UINT uNumSamples = (UINT)pFI->lNumSamplesPerEpisode;

   DWORD dwEpiStart, dwMissingSamples;

   short *pnBuffer = (short *)malloc(uNumSamples * sizeof(short));

   if (!pnBuffer)

   {

      printf("Out of memory!\n");

      return FALSE;

   }

   for (DWORD i=1; i<=(DWORD)pFI->lActualEpisodes; i++)

   {

      UINT uFlag = 0;

      int nError = 0;

      if (!ABF_MultiplexRead( nFileIn, pFI, i, pnBuffer, &uNumSamples,

                              &nError ))

         return ShowABFError(pszFileIn, nError);

      if (!ABF_FindEpisodeStart( nFileIn, pFI, i, &dwEpiStart,

                                 &nError ))

         return ShowABFError(pszFileIn, nError);

      if (pFI->nOperationMode == ABF_VARLENEVENTS)

      {

         if (!ABF_GetMissingSamples( nFileIn, pFI, I,

                                     &dwMissingSamples, &nError ))

            return ShowABFError(pszFileIn, nError);

         if (dwMissingSamples == 0)

            uFlag = ABF_APPEND;

      }

      if (!ABF_MultiplexWrite( nFileOut, pFO, uFlag, pnBuffer,

                               dwEpiStart, uNumSamples, &nError ))

         return ShowABFError(pszFileOut, nError);

   }

   return TRUE;

}

See also

ABF_FindEpisode
ABF_GetMissingSamples
ABF_GetNumSamples


ABF_GetMissingSamples

#include "abffiles.h"

BOOL ABF_GetMissingSamples( int hFile, DWORD dwEpisode,
DWORD *pdwMissingSamples, int *pnError );

Returns the number of samples missing before the specified episode (event detected files only).

Parameter	Description
hFile	ABF file handle.
dwEpisode	Interesting episode number.
pdwMissingSamples	Number of data points absent prior to this episode.
pnError	Address of error return code. May be NULL.
Comments

The ABF_GetMissingSamples function finds the number of samples missing for event detected data for the specified episode, and stores it in *pdwMissingSamples.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EEPISODERANGE	Episode number out of range.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
Example

#include "abffiles.h"

BOOL CopyDataFile(char *pszFileIn, int nFileIn, ABFFileHeader *pFI,

                  char *pszFileOut, int nFileOut, ABFFileHeader *pFO)

{

   UINT uNumSamples = (UINT)pFI->lNumSamplesPerEpisode;

   DWORD dwEpiStart, dwMissingSamples;

   short *pnBuffer = (short *)malloc(uNumSamples * sizeof(short));

   if (!pnBuffer)

   {

      printf("Out of memory!\n");

      return FALSE;

   }

   for (DWORD i=1; i<=(DWORD)pFI->lActualEpisodes; i++)

   {

      UINT uFlag = 0;

      int nError = 0;

      if (!ABF_MultiplexRead( nFileIn, pFI, i, pnBuffer, &uNumSamples,

                              &nError ))

         return ShowABFError(pszFileIn, nError);

      if (!ABF_FindEpisodeStart( nFileIn, pFI, i, &dwEpiStart,

                                 &nError ))

         return ShowABFError(pszFileIn, nError);

      if (pFI->nOperationMode == ABF_VARLENEVENTS)

      {

         if (!ABF_GetMissingSamples( nFileIn, pFI, I,

                                     &dwMissingSamples, &nError ))

            return ShowABFError(pszFileIn, nError);

         if (dwMissingSamples == 0)

            uFlag = ABF_APPEND;

      }

      if (!ABF_MultiplexWrite( nFileOut, pFO, uFlag, pnBuffer,

                               dwEpiStart, uNumSamples, &nError ))

         return ShowABFError(pszFileOut, nError);

   }

   return TRUE;

}

See also

ABF_GetNumSamples


ABF_GetNumSamples

#include "abffiles.h"

BOOL ABF_GetNumSamples( int hFile, DWORD dwEpisode,
UINT *puNumSamples, int *pnError );

Finds the number of samples in the specified episode.

Parameter	Description
hFile	ABF file handle.
dwEpisode	Interesting episode number.
puNumSamples	Number of data points in this episode.
pnError	Address of error return code. May be NULL.
Comments

The ABF_GetNumSamples function finds the number of samples in the specified episode, and returns it in *puNumSamples.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EEPISODERANGE	Episode number out of range.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
Example

#include "abffiles.h"

BOOL HowManySamples( char *pszFileName, DWORD dwEpisode)

{

   int hFile;

   int nError;

   ABFFileHeader FH;

   DWORD dwMaxEpi = 0;

   UINT uMaxSamples = 0;

   UINT uNumSamples;

   uMaxSamples = 16 * 1024;

   if (!ABF_ReadOpen( pszFileName, &hFile, ABF_DATAFILE, &FH,

                      &uMaxSamples, &dwMaxEpi, &nError ))

      return ShowABFError(pszFileName, nError);

   if (!ABF_GetNumSamples( hFile, &FH, dwEpisode, &uNumSamples,

                           &nError ))

   {

      ABF_Close( hFile, NULL );

      return ShowABFError(pszFileName, nError);

   }

   ABF_Close( hFile, NULL );

   printf( "The number of samples is %u\n", uNumSamples );

   return TRUE;

}

See also

ABF_GetMissingSamples


ABF_GetStartTime

#include "abffiles.h"

BOOL ABF_GetStartTime(int nFile, ABFFileHeader *pFH, int nChannel,
DWORD dwEpisode, float *pfStartTime, int *pnError);

Gets the start time in ms for the specified episode.

Parameter	Description
hFile	ABF file handle.
pFH	File header for the file as returned by ABF_ReadOpen.
nChannel	ADC channel of interest.
dwEpisode	Episode number to return the start time for.
pfStartTime	Location in which to return the start time in ms.
pnError	Address of error return code. May be NULL.
Comments

The ABF_GetStartTime function returns the time at which the episode of interest in the channel specified started.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EEPISODERANGE	Episode number out of range.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
Example

#include "abffiles.h"


ABF_GetWaveform

#include "abffiles.h"

BOOL ABF_GetWaveform(int nFile, ABFFileHeader *pFH, int nChannel,
DWORD dwEpisode, float *pfBuffer, int *pnError);

Gets the DAC output waveform for the specified episode.

Parameter	Description
hFile	ABF file handle.
pFH	File header for the file as returned by ABF_ReadOpen.
nChannel	ADC channel of interest.
dwEpisode	Episode number to return the start time for.
pfBuffer	Address of buffer to fill with DAC output waveform.
pnError	Address of error return code. May be NULL.
Comments

The ABF_GetWaveform function returns the DAC output waveform for a particular episode, in DAC UserUnits.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EEPISODERANGE	Episode number out of range.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
Example

#include "abffiles.h"

BOOL ShowWaveforms(char *pszFileName, int nFile,

                   ABFFileHeader *pFH, int nChannel)

{

   int nError;

   DWORD I;

   UINT uNumSamples = (UINT)pFH->lNumSamplesPerEpisode /

                      pFH->nADCNumChannels;

   float *pfBuffer = (float *)malloc(uNumSamples *

                                     sizeof(float));

   if (!pfBuffer)

   {

      printf("Out of memory!\n");

      return FALSE;

   }

   for (DWORD i=1; i<=(DWORD)pFH->lActualEpisodes; I++)

   {

      if (!ABF_GetWaveform(nFile, pFH, nChannel, i, pfBuffer,

                           &nError))

      {

         free(pfBuffer);

         return ShowABFError(pszFileName, nError);

      }

      printf("Episode %lu\n", i);

      for (UINT j=0; j<uNumSamples; j++)

         printf("%g\n", pfBuffer[j]);

   }

   free(pfBuffer);

   return TRUE;

}


ABF_Initialize

#include "abffiles.h"

void ABF_Initialize( void );

Initialises the ABF file I/O module.

Comments

The ABF_Initialize function is used to perform initialisation of the file I/O module. This function must be called prior to the use of any other functions in the I/O module. In the Windows DLL version this function is called automatically when the DLL is loaded, and hence is not exported by the DLL.

Example

#include "abffiles.h"

void main( int argc, char **argv )

{

   ABFFileHeader FH;

   ABF_Initialize();

   ABFH_Initialize(&FH);

   Acquisition( argv[1], &FH );

   ABF_Cleanup();

}

See also

ABF_Cleanup


ABF_MultiplexRead

#include "abffiles.h"

BOOL ABF_MultiplexRead( int hFile, ABFFileHeader pFH,
DWORD dwEpisode, void *pvBuffer, UINT *puNumSamples,
 int *pnError );

Reads an episode of data from a previously opened data file. The data is returned with all channels multiplexed together.

Parameter	Description
hFile	ABF file handle.
pFH	File header for the file being read.
dwEpisode	Episode number to be read.
pvBuffer	Data buffer for the data.
puNumSamples	Number of valid points returned in the data buffer.
pnError	Address of error return code. May be NULL.
Comments

The ABF_MultiplexRead function reads episode number dwEpisode from hFile into pvBuffer. The actual number of points read into the buffer is returned in *puNumSamples. Only in the case of ABF_VARLENEVENTS mode or at the end of an ABF_GAPFREEFILE file will *puNumSamples differ from the value returned by ABF_ReadOpen in *puMaxSamples.

It is up to the user of this routine to ensure that the buffer passed in as pvBuffer points to an array of at least pFH->lNumSamplesPerEpisode samples in length. Where the file header pFH was returned by the ABF_ReadOpen command.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EEPISODERANGE	Episode number out of range.
ABF_EREADDATA	Could not read episode data from file.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
Example

#include "abffiles.h"

BOOL CopyDataFile(char *pszFileIn, int nFileIn, ABFFileHeader *pFI,

                  char *pszFileOut, int nFileOut, ABFFileHeader *pFO)

{

   UINT uNumSamples = (UINT)pFI->lNumSamplesPerEpisode;

   DWORD dwEpiStart, dwMissingSamples;

   short *pnBuffer = (short *)malloc(uNumSamples * sizeof(short));

   if (!pnBuffer)

   {

      printf("Out of memory!\n");

      return FALSE;

   }

   for (DWORD i=1; i<=(DWORD)pFI->lActualEpisodes; i++)

   {

      UINT uFlag = 0;

      int nError = 0;

      if (!ABF_MultiplexRead( nFileIn, pFI, i, pnBuffer, &uNumSamples,

                              &nError ))

         return ShowABFError(pszFileIn, nError);

      if (!ABF_FindEpisodeStart( nFileIn, pFI, i, &dwEpiStart,

                                 &nError ))

         return ShowABFError(pszFileIn, nError);

      if (pFI->nOperationMode == ABF_VARLENEVENTS)

      {

         if (!ABF_GetMissingSamples( nFileIn, pFI, I,

                                     &dwMissingSamples, &nError ))

            return ShowABFError(pszFileIn, nError);

         if (dwMissingSamples == 0)

            uFlag = ABF_APPEND;

      }

      if (!ABF_MultiplexWrite( nFileOut, pFO, uFlag, pnBuffer,

                               dwEpiStart, uNumSamples, &nError ))

         return ShowABFError(pszFileOut, nError);

   }

   return TRUE;

}

See also

ABF_MultiplexWrite
ABF_ReadChannel


ABF_MultiplexWrite

#include "abffiles.h"

BOOL ABF_MultiplexWrite( int hFile, ABFFileHeader *pFH,
UINT uFlags, void *pvBuffer, DWORD dwEpiStart,
UINT uNumSamples, int *pnError );

Writes an episode of data into a previously opened data file. The data buffer must contain all channels multiplexed together.

Parameter	Description
hFile	ABF file handle.
pFH	File header for the file being written.
uFlags	Flags governing the write process.
pvBuffer	Data buffer for the data.
dwEpiStart	Start time in samples of this episode.
uNumSamples	Number of valid points in the data buffer.
pnError	Address of error return code. May be NULL.
Comments

The ABF_MultiplexWrite function writes the episode of data from pvBuffer into hFile. If the ABF_APPEND flag is set for an ABF_VARLENEVENTS mode file the data is appended to the previous episode in the data file being written.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EDISKFULL	Not enough space on disk.
Example

#include "abffiles.h"

BOOL CopyDataFile(char *pszFileIn, int nFileIn, ABFFileHeader *pFI,

                  char *pszFileOut, int nFileOut, ABFFileHeader *pFO)

{

   UINT uNumSamples = (UINT)pFI->lNumSamplesPerEpisode;

   DWORD dwEpiStart, dwMissingSamples;

   short *pnBuffer = (short *)malloc(uNumSamples * sizeof(short));

   if (!pnBuffer)

   {

      printf("Out of memory!\n");

      return FALSE;

   }

   for (DWORD i=1; i<=(DWORD)pFI->lActualEpisodes; i++)

   {

      UINT uFlag = 0;

      int nError = 0;

      if (!ABF_MultiplexRead( nFileIn, pFI, i, pnBuffer, &uNumSamples,

                              &nError ))

         return ShowABFError(pszFileIn, nError);

      if (!ABF_FindEpisodeStart( nFileIn, pFI, i, &dwEpiStart,

                                 &nError ))

         return ShowABFError(pszFileIn, nError);

      if (pFI->nOperationMode == ABF_VARLENEVENTS)

      {

         if (!ABF_GetMissingSamples( nFileIn, pFI, I,

                                     &dwMissingSamples, &nError ))

            return ShowABFError(pszFileIn, nError);

         if (dwMissingSamples == 0)

            uFlag = ABF_APPEND;

      }

      if (!ABF_MultiplexWrite( nFileOut, pFO, uFlag, pnBuffer,

                               dwEpiStart, uNumSamples, &nError ))

         return ShowABFError(pszFileOut, nError);

   }

   return TRUE;

}

See also

ABF_MultiplexRead


ABF_ReadChannel

#include "abffiles.h"

BOOL ABF_ReadChannel( int hFile, ABFFileHeader *pFH,
int nChannel, DWORD dwEpisode, float *pfBuffer,
UINT *puNumSamples, int *pnError );

Reads an episode of data for a particular channel from a previously opened data file.

Parameter	Description
hFile	ABF file handle.
pFH	File header for the file being read.
nChannel	Physical channel number to be read.
dwEpisode	Episode number to be read.
pfBuffer	Data buffer for the data.
puNumSamples	Number of valid points in the data buffer.
pnError	Address of error return code. May be NULL.
Comments

The ABF_ReadChannel function reads episode number dwEpisode of channel nChannel from hFile into pfBuffer. The actual number of points read into the buffer is returned in *puNumSamples. If the data in the file is in two-byte binary format, it is converted into fully scaled 4-byte floats in UserUnits.

It is up to the user of this routine to ensure that the buffer passed in as pvBuffer points to an array of sufficient size to contain the returned episode.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EBADFILEINDEX	Invalid ABF file handle specified.
ABF_EWRITEONLYFILE	This file is write-only.
ABF_EINVALIDCHANNEL	Channel number is invalid.
Example

#include "abffiles.h"

int ReadChannelEpisode( char *pszFileName, int nChannel,

                        DWORD dwEpisode, float *pfBuffer,

                        UINT *puNumSamples )

{

   int hFile;

   int nError;

   ABFFileHeader FH;

   DWORD dwMaxEpi = 0;

   UINT uMaxSamples = 16 * 1024;

   if (!ABF_ReadOpen(pszFileName, &hFile, ABF_DATAFILE, &FH,

                     &uMaxSamples, &dwMaxEpi, &nError))

      return ShowABFError(pszFileName, nError);

   if (!ABF_ReadChannel( hFile, &FH, nChannel, dwEpisode, pfBuffer,

                         puNumSamples, &nError ))

   {

      ABF_Close( hFile, NULL );

      return ShowABFError(pszFileName, nError);

   }

   if (!ABF_Close( hFile, &nError ))

      return ShowABFError(pszFileName, nError);

   return TRUE;

}

See Also

ABF_MultiplexRead


ABF_ReadDACFileEpi

#include "abffiles.h"

BOOL ABF_ReadDACFileEpi( int hFile, ABFFileHeader *pFH,
short *pnDACArray, DWORD dwEpisode, int *pnError );

Reads an episode from the DAC file section of an ABF file.

Parameter	Description
hFile	ABF file handle.
pFH	Pointer to acquisition parameters.
pnDACArray	Data buffer for the data.
dwEpisode	Episode number to be read.
pnError	Address of error return code. May be NULL.
Comments

The ABF_ReadDACFileEpi function reads episode number dwEpisode from the DAC file section of hFile into pnDACArray..

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EREADDACEPISODE	Could not read data.
Example

#include "abffiles.h"

BOOL ShowDACFileData(char *pszFileName, int nFile, ABFFileHeader *pFH,

                     short *pnBuffer)

{

   int nError;

   DWORD i;

   UINT j;

   UINT uNumSamples = (UINT)pFH->lNumSamplesPerEpisode;

   for (i = 0; i < (DWORD)pFH->lDACFileNumEpisodes; i++)

   {

      if (!ABF_ReadDACFileEpi( nFile, pFH, pnBuffer, i, &nError ))

         return ShowABFError(pszFileName, nError);

      for (j = 0; j < uNumSamples; j++)

         printf( "%d\n", pnBuffer[j] );

   }

   return TRUE;

}

See also

ABF_WriteDACFileEpi


ABF_ReadOpen

#include "abffiles.h"

BOOL ABF_ReadOpen( char *szFileName, int *phFile, UINT uFlags,
ABFFileHeader *pFH, UINT *puMaxSamples,
DWORD *pdwMaxEpi, int *pnError );

Opens an existing ABF data file for reading. Reads the acquisition parameters from the file header into the passed ABFFileHeader structure.

Parameter	Description
szFileName	Name of data file to open.
phFile	Pointer to ABF file handle of this file.
uFlags	Flag to indicate whether file is parameter file or not.
pFH	Pointer to acquisition parameters read from data file.
puMaxSamples	Pointer to requested size of data blocks to be returned.
pdwMaxEpi	Pointer to number of episodes that exist in the data file.
pnError	Address of error return code. May be NULL.
Legal values for uFlags
ABF_DATAFILE	File is data file.
ABF_PARAMFILE	File is parameter file.
ABF_ALLOWOVERLAP	Permit return of overlapping data.
Comments

The ABF_ReadOpen function opens the data file szFileName, allocates an ABF file handle for it and assigns this number to *phFile. Data is read from the file header into *pFH. If ABF_PARAMFILE is set in uFlags then no further processing is performed, otherwise internal buffers are allocated in preparation for file reading.

For ABF_GAPFREEFILE and ABF_VARLENEVENTS files, *puMaxSamples is passed in as a requested maximum size of the blocks of data returned by the ABF_ReadMultiplex and ABF_ReadChannel routines. For all modes, the actual value that will be used is returned in this location.

For Event Detected modes, on calling ABF_ReadOpen, the parameter pdwMaxEpi points to a the maximum number of episodes to read from the file. If it is zero the maximum will be 8192 episodes, depending on RAM availability.  The total number of data blocks of the size returned in *puMaxSamples is returned in *pdwMaxEpi.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_TOOMANYFILESOPEN	Too many files are already open.
ABF_EOPENFILE	Failed DOS open file.
ABF_EUNKNOWNFILETYPE	Could not recognise file type, possibly not an ABF file.
ABF_EBADPARAMETERS	Could not read parameter header, possibly corrupted header.
ABF_EEPISODESIZE	*pdwMaxSamples out of range i.e. below 128.
ABF_OUTOFMEMORY	Could not allocate internal buffer.
Example

#include "abffiles.h"

BOOL FindAnEpisode( char *pszFileName, DWORD *pdwSample,

                    DWORD *pdwEpisode )

{

   int hFile;

   int nError = 0;

   ABFFileHeader FH;

   DWORD dwMaxEpi = 0;

   UINT uMaxSamples = 16 * 1024;

   if (!ABF_ReadOpen( pszFileName, &hFile, ABF_DATAFILE,

                      &FH, &uMaxSamples, &dwMaxEpi, &nError ))

      return ShowABFError(pszFileName, nError);

   if (!ABF_FindEpisode( hFile, &FH, pdwSample, pdwEpisode, &nError ))

   {

      ABF_Close( hFile, NULL );

      return ShowABFError(pszFileName, nError);

   }

   if (!ABF_Close( hFile, &nError ))

      return ShowABFError(pszFileName, nError);

   return TRUE;

}

See also

ABF_WriteOpen
ABF_Close


ABF_ReadTags

#include "abffiles.h"

BOOL ABF_ReadTags( int hFile, ABFFileHeader *pFH,
DWORD dwFirstTag, ABFTag *pTagArray, UINT uNumTags,
int *pnError );

Reads a segment of the tag array from the TAGArray section.

Parameter	Description
hFile	ABF file handle.
pFH	Pointer to acquisition parameters.
dwFirstTag	Index of the start of the sub array to retrieve
pTagArray	Data buffer for the tag array.
uNumTags	Number of tag entries to retrieve.
pnError	Address of error return code. May be NULL.
Comments

The ABF_ReadTags function reads a segment of the tag array from the TagArray section of hFile into pTagArray.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EREADTAG	Could not read data.
Example

#include "abffiles.h"

#define TAG_BLOCKSIZE  10

int PrintTags( int hFile, char *pszFileName, ABFFileHeader *pFH )

{

   ABFTag *pTagArray;

   UINT i;

   int nError;

   if (pFH->lNumTagEntries < 1)

      return TRUE;

   pTagArray = (ABFTag *)calloc( TAG_BLOCKSIZE, sizeof(ABFTag) );

   DWORD dwTagCount = pFH->lNumTagEntries;

   DWORD dwFirstTag = 0;

   while (dwTagCount)

   {

      UINT uTags = (TAG_BLOCKSIZE > dwTagCount ?

                   (UINT)dwTagCount : TAG_BLOCKSIZE);

      if (!ABF_ReadTags( hFile, pFH, dwFirstTag, pTagArray, uTags,

                         &nError ))

      {

         free(pTagArray);

         return ShowABFError(pszFileName, nError);

      }

      for (i = 0; i < uTags; i++)

         printf( "\nTime: %ld Episode: %ld\n%56.56s\n",

              pTagArray[i].lTagTime, pTagArray[i].lEpisodeNum,

              pTagArray[i].sComment );

      dwTagCount -= uTags;

      dwFirstTag += uTags;

   }

   free(pTagArray);

   return TRUE;

}

See also

ABF_WriteTag


ABF_UpdateHeader

#include "abffiles.h"

BOOL ABF_UpdateHeader( int hFile, ABFFileHeader *pFH, int *pnError );

Updates the file header to reflect the data newly written into an ABF data file.

Parameter	Description
hFile	ABF file handle.
pFH	Pointer to acquisition parameters.
pnError	Address of error return code. May be NULL.
Comments

The ABF_UpdateHeader function updates the file header and writes the synch array out to disk if required. This function should always be called before closing a file opened with ABF_WriteOpen.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EWRITEPARAMETERS	Could not write header parameters.
Example

#include "abffiles.h"

BOOL Acquisition( char *pszFileName, ABFFileHeader *pFH )

{

   int hFile;

   int hHandle;

   int nError = 0;

   DWORD dwEpisodes, dwSamples;

   if (!ABF_WriteOpen( pszFileName, &hFile, ABF_DATAFILE, pFH,

                       &nError ) )

      return ShowABFError(pszFileName, nError);

   AcquireAndWriteData( hFile, pFH );

   if (!ABF_UpdateHeader( hFile, pFH, &nError ))

   {

      ABF_Close( hFile, NULL );

      return ShowABFError(pszFileName, nError);

   }

   if (!ABF_Close( hFile, &nError ))

      return ShowABFError(pszFileName, nError);

   return TRUE;

}

See also

ABF_WriteOpen
ABF_Close


ABF_WriteDACFileEpi

#include "abffiles.h"

BOOL ABF_WriteDACFileEpi( int hFile, ABFFileHeader *pFH,
short *pnDACArray, int *pnError );

Writes an episode to the DAC file section.

Parameter	Description
hFile	ABF file handle.
pFH	Pointer to acquisition parameters.
pnDACArray	Data buffer of the data.
pnError	Address of error return code. May be NULL.
Comments

The ABF_WriteDACFileEpi function writes an episode from pnDACArray to the DAC file section of hFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EWRITEDACEPISODE	Could not write data.
See also

ABF_ReadDACFileEpi


ABF_WriteOpen

#include "abffiles.h"

BOOL ABF_WriteOpen( char *szFileName, int *phFile, UINT uFlags,
ABFFileHeader *pFH, int *pnError );

Opens an existing data file for writing. Writes the acquisition parameters.

Parameter	Description
szFileName	Name of data file to open.
phFile	Pointer to ABF file handle of this file.
uFlags	Flag to indicate whether file is parameter file or not.
pFH	Pointer to acquisition parameters to be written to data file.
pnError	Address of error return code. May be NULL.
Comments

The ABF_WriteOpen function opens the data file szFileName, allocates an ABF file handle for it and assigns this number to *phFile. The contents of *pFH are written to the file header.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_TOOMANYFILESOPEN	Too many data files are already open.
ABF_EOPENFILE	Failed DOS open file.
ABF_EWRITEPARAMETERS	Could not write parameter header.
ABF_OUTOFMEMORY	Could not allocate decollation buffer.
ABF_EDISKFULL	Not enough space on disk.
Example

#include "abffiles.h"

BOOL Acquisition( char *pszFileName, ABFFileHeader *pFH )

{

   int hFile;

   int hHandle;

   int nError = 0;

   DWORD dwEpisodes, dwSamples;

   if (!ABF_WriteOpen( pszFileName, &hFile, ABF_DATAFILE, pFH,

                       &nError ) )

      return ShowABFError(pszFileName, nError);

   AcquireAndWriteData( hFile, pFH );

   if (!ABF_UpdateHeader( hFile, pFH, &nError ))

   {

      ABF_Close( hFile, NULL );

      return ShowABFError(pszFileName, nError);

   }

   if (!ABF_Close( hFile, &nError ))

      return ShowABFError(pszFileName, nError);

   return TRUE;

}

See also

ABF_ReadOpen
ABF_Close


ABF_WriteTag

#include "abffiles.h"

BOOL ABF_WriteTag( int hFile, ABFFileHeader *pFH, ABFTag *pTag,
int *pnError );

Writes a tag array to the TAGArray section.

Parameter	Description
hFile	ABF file handle.
pFH	Pointer to acquisition parameters.
pTag	Data buffer of the tag array.
pnError	Address of error return code. May be NULL.
Comments

The ABF_WriteTag function writes a single ABFTag structure to the ABF file. All tags are internally buffered to disk inside the ABFFILES module and written out to the file when ABF_UpdateHeader() is called.

Possible Error Codes

One of the following error codes may be returned on error (defined in ABFFILES.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABF_EWRITETAG	Could not write data.
See also

ABF_ReadTags


The ABF Header Function API by category

Header Reading and Writing

Miscellaneous Header Functions

User Units Conversions

Waveform Functions


Header Reading and Writing

Routine	Use
ABFH_ParamReader	Read the header from the file, translating old file headers into ABF 1.X format.
ABFH_ParamWriter	Write the header to the file.


Miscellaneous Header Functions

ABFH_Initialize	Initialise an ABF header to contain all default parameters.
ABFH_GetMathValue	Calculate a math channel value from two floating point values given the Math channel parameters in the header.
ABFH_GetChannelOffset	Get the multiplex offset in the data stream for a particular ADC channel.
ABFH_GetErrorText	Build an error string from an error number.
ABFH_GetADCDisplayRange	Get the display range stored in the header, in UserUnits.


User Units Conversions

ABFH_GetADCtoUUFactors	Get the conversion factors for converting from ADC samples to UserUnits at the preperation.
ABFH_ClipADCUUValue	Clip an ADC UserUnit value to the range of the ADC converter.
ABFH_GetDACtoUUFactors	Get the conversion factors for converting from DAC samples to UserUnits at the preperation.
ABFH_ClipDACUUValue	Clip a DAC UserUnit value to the range of the DAC converter.


Waveform Functions

ABFH_GetHoldingDuration	Get the duration of the first holding period, in samples.
ABFH_GetEpochLimits	Get the bounds of a particular epoch in a particular episode, in samples.
ABFH_GetWaveform	Fill a buffer with the DAC waveform as described by the ABF header (in DAC UserUnits)
ABFH_GetWaveformVector	Get a vector description of the waveform as described by the ABF header.
ABFH_IsConstantWaveform	Returns TRUE if the waveform does not vary from episode to episode.
ABFH_GetTimebase	Fills a buffer with the timebase that matches the waveform, in ms.


The ABF Header Functions

ABFH_Initialize

ABFH_GetADCtoUUFactors

ABFH_GetADCDisplayRange

ABFH_ClipADCUUValue

ABFH_GetDACtoUUFactors

ABFH_ClipDACUUValue

ABFH_ParamReader

ABFH_ParamWriter

ABFH_GetMathValue

ABFH_GetErrorText

ABFH_GetEpochLimits

ABFH_GetChannelOffset

ABFH_GetWaveform

ABFH_GetWaveformVector

ABFH_GetTimebase

ABFH_GetHoldingDuration

ABFH_IsConstantWaveform

Error Values


ABFH_Initialize

#include "abfheadr.h"

void ABFH_Initialize( ABFFileHeader *pFH );

Initialises an ABFFileHeader structure to contain a minimum consistent set of parameters.

Parameter	Description
pFH	Pointer to an ABFFileHeader structure.
Comments

The ABFH_Initialize function may be used to initialise an ABFFileHeader structure. All strings will be space filled, all gains set to 1.0, and all offsets set to 0.

Example

#include "abfheadr.h"

ABFFileHeader FH;

ABFH_Initialize(&FH)


ABFH_GetADCtoUUFactors

#include "abfheadr.h"

void ABFH_GetADCtoUUFactors( ABFFileHeader *pFH, int nChannel,
float *pfADCToUUFactor, float *pfADCToUUShift );

Calculates the scaling factors used to convert ADC values to UserUnits.

Parameter	Description
pFH	Pointer to an ABFFileHeader structure.
nChannel	Physical ADC channel number to get the factors for.
pfADCToUUFactor	Returns the multiplier used in the conversion.
pfADCToUUShift	Returns the offset used in the conversion.
Comments

The ABFH_GetADCtoUUFactors function can be called to obtain two factors for converting ADC values to "User Units" and vice versa. The factors are used as follows:

UU = ADCValue * fADCtoUUFactor + fADCtoUUShift;

or

ADCValue = (UU - fADCtoUUShift) / fADCtoUUFactor;

Example

#include "abfheadr.h"

void ShowADCValues(ABFFileHeader *pFH, UINT uChannel,

                   short *pnADCValues, UINT uCount)

{

   UINT i;

   float fADCtoUUFactor, fADCtoUUShift;

   ABFH_GetADCtoUUFactors( pFH, uChannel, &fADCtoUUFactor,

                           &fADCtoUUShift );

   for (i=0; i<uCount; i++)

   {

      fUU = *pnADCValues++ * fADCtoUUFactor + fADCtoUUShift;

      printf("%g", fUU);

   }

}


ABFH_GetADCDisplayRange

#include "abfheadr.h"

void ABFH_GetADCDisplayRange( ABFFileHeader *pFH, int nChannel,
float *pfUUTop, float *pfUUBottom );

Calculates the upper and lower limits of the display given the display amplification and offset in the ABF header for this channel.

Parameter	Description
pFH	Pointer to an ABFFileHeader structure.
nChannel	Physical ADC channel number to get the display limits for.
pfUUTop	Returns the UserUnit value of the top of the display.
pfUUBottom	Returns the UserUnit value of the bottom of the display.
Example

#include "abfheadr.h"


ABFH_ClipADCUUValue

#include "abfheadr.h"

int ABFH_ClipADCUUValue( ABFFileHeader *pFH, int nChannel,
float *pfUUValue );

Limits the UU value to the range of the A/D converter.

Parameter	Description
pFH	Pointer to an ABFFileHeader structure.
uChannel	Physical ADC channel number corresponding to the UU value.
pfUUValue	Passes in and returns the clipped UserUnit value.
Comments

Example

#include "abfheadr.h"


ABFH_GetDACtoUUFactors

#include "abfheadr.h"

void ABFH_GetDACtoUUFactors( ABFFileHeader *pFH, int nChannel,
float *pfDACToUUFactor, float *pfDACToUUShift );

Calculates the scaling factors used to convert DAC values to UserUnits.

Parameter	Description
pFH	Pointer to an ABFFileHeader structure.
nChannel	DAC channel number to get the factors for.
pfDACToUUFactor	Returns the multiplier used in the conversion.
pfDACToUUShift	Returns the offset used in the conversion.
Comments

The ABFH_GetDACtoUUFactors function can be called to obtain two factors for converting DAC values to "User Units" and vice versa. The factors are used as follows:

UU = DACValue * fDACtoUUFactor + fDACtoUUShift;

or

DACValue = (UU - fDACtoUUShift) / fDACtoUUFactor;

Example

#include "abfheadr.h"

void ShowDACValues(ABFFileHeader *pFH, UINT uChannel,

                   short *pnADCValues, UINT uCount)

{

   UINT i;

   float fDACtoUUFactor, fDACtoUUShift;

   ABFH_GetDACtoUUFactors( pFH, uChannel, &fDACtoUUFactor,

                          &fDACtoUUShift );

   for (i=0; i<uCount; i++)

   {

      fUU = *pnDACValues++ * fDACtoUUFactor + fDACtoUUShift;

      printf("%g", fUU);

   }

}


ABFH_ClipDACUUValue

#include "abfheadr.h"

int ABFH_ClipDACUUValue( ABFFileHeader *pFH, int nChannel,
float *pfUUValue );

Limits the UU value to the range of the D/A converter.

Parameter	Description
pFH	Pointer to an ABFFileHeader structure.
uChannel	Physical DAC channel number corresponding to the UU value.
pfUUValue	Passes in and returns the clipped UserUnit value.
Comments

Example

#include "abfheadr.h"


ABFH_ParamReader

#include "abfheadr.h"

BOOL ABFH_ParamReader( int hFile, ABFFileHeader *pFH,
int *pnError );

Reads a parameter structure from an ABF file, translating old file headers into an equivalent ABFFileHeader structure.

Parameter	Description
hFile	DOS file handle  <== N.B.
pFH	Pointer to ABFFileHeader structure to receive  parameters.
pnError	Address of error return code. May be NULL.
Comments

The ABFH_ParamReader function is called internally by ABF_ReadOpen when an existing ABF file is opened for reading.

Possible Error Codes

One of the following manifest constants (defined in ABFHEADR.H).

Constant	Meaning
ABFH_EHEADERREAD	End of file or disk error during header read.
ABFH_EINVALIDFILE	Invalid DOS file handle.
ABFH_EUNKNOWNFILETYPE	File is not an ABF file.
Example

#include "abfheadr.h"

BOOL ReadABFHeader(char *szFileName, ABFFileHeader *pFH)

{

   int nFile = open(szFileName, O_BINARY, O_READONLY);

   if (nFile < 0)

      return FALSE;

   int nError = 0;

   if (!ABFH_ParamReader( nFile, pFH, &nError ))

      return ShowABFHError(nError);

   close(nFile);

   return TRUE;

}

See also

ABFH_ParamWriter


ABFH_ParamWriter

#include "abfheadr.h"

BOOL ABFH_ParamWriter( int hFile, ABFFileHeader *pFH,
int *pnError );

Writes a parameter structure to an ABF file.

Parameter	Description
hFile	DOS file handle  <== N.B.
pFH	Pointer to ABFFileHeader structure to receive  parameters.
pnError	Address of error return code. May be NULL.
Comments

The ABFH_ParamWriter function is called internally by ABF_WriteOpen(), and ABF_UpdateHeader() to write an ABFFileHeader structure to a file.

Possible Error Codes

One of the following manifest constants (defined in ABFHEADR.H).

Constant	Meaning
ABF_SUCCESS	Function was successful.
ABFH_EHEADERWRITE	Disk full or disk error during header write.
ABFH_EINVALIDFILE	Invalid DOS file handle.
Example

#include "abfheadr.h"

BOOL WriteABFHeader(char *szFileName, ABFFileHeader *pFH)

{

   int nFile = open(szFileName, O_BINARY, O_WRITEONLY);

   if (nFile < 0)

      return FALSE;

   int nError = ABFH_ParamWriter( nFile, pFH );

   close(nFile);

   return (nError == ABFH_SUCCESS);

}

See also

ABFH_ParamReader


ABFH_GetMathValue

#include "abfheadr.h"

BOOL ABFH_GetMathValue(ABFFileHeader *pFH, float fA, float fB,
float *pfRval);

Takes two floating point values and combines them according to the Math Channel equation and constants contained in the ABF header.

Parameter	Description
pFH	Pointer to ABFFileHeader structure containing the math channel parameters.
fA	Value for channel A
fB	Value for channel B
pfRval	Points to the location in which to return the result of the combination of fA & fB.
Comments

The ABFH_GetMathValue function is called internally by ABF_ReadChannel() when a channel number of -1 is passed - signifying the math channel is to be read.

Returns

TRUE is returned if the expression could be evaluated OK.
FALSE is returned if a divide by zero occurred while evaluation the expression.

Example

#include "abfheadr.h"


ABFH_GetErrorText

#include "abfheadr.h"

int ABFH_GetErrorText( int nError, char *pszBuffer, int nBufferSize );

Builds an error description string for a given ABFH_ error number.

Parameter	Description
nError	The error number of interest.
pszBuffer	A character buffer to fill with the error message.
nBufferSize	The size in characters of the buffer passed as pszBuffer.
Comments

ABFH_GetErrorText should only be used to build error messages from error numbers returned by ABFH_XXXX functions

Returns

The length of the string placed in the passed buffer is returned. If an invalid error number is passed in, or there is no string available for it, 0 is returned.

Example

#include "abfheadr.h"


ABFH_GetEpochLimits

#include "abfheadr.h"

BOOL ABFH_GetEpochLimits(ABFFileHeader *pFH, int nChannel,
DWORD dwEpisode, int nEpoch, UINT *puEpochStart,
UINT *puEpochEnd, int *pnError);

The function ABFH_GetEpochLimits is used to retreive information for a particular epoch in a particular episode of the output waveform.

Parameter	Description
pFH	Pointer to ABFFileHeader structure containing the waveform epoch definitions.
nChannel	The particular channel of interest.
dwEpisode	The episode for which to calculate the epoch position.
nEpoch	The epoch number for which to calculate the start & finish point. Epochs are numbered from 0-9. The limits of the first and last holding regions may also be returned by passing ABFH_FIRSTHOLDING or ABFH_LASTHOLDING as the epoch number.
puEpochStart	Points to location in which to return the starting offset of the epoch.
puEpochEnd	Points to location in which to return the ending offset of the epoch.
pnError	Address of error return code. May be NULL.
Comments

The epoch start and end positions are calculated as sample offsets into the multiplexed episode data.

Possible Error Codes

One of the following manifest constants (defined in ABFHEADR.H).

Constant	Meaning
ABFH_CHANNELNOTSAMPLED	The requested sample is not present in the sampling sequence.
ABFH_EPOCHNOTPRESENT	The requested epoch is not present in the episode specified.
Example

#include "abfheadr.h"


ABFH_GetChannelOffset

#include "abfheadr.h"

BOOL ABFH_GetChannelOffset( ABFFileHeader *pFH, int nChannel,
UINT *puChannelOffset );

The function ABFH_GetEpochLimits is used to convert an ADC channel number into an offset into the multiplexed data stream.

Parameter	Description
pFH	Pointer to ABFFileHeader structure containing the channel mapping and sampling sequence.
nChannel	The particular channel of interest.
puChannelOffset	Points to location in which to return the offset to the data for this channel.
Returns

TRUE is returned if the offset is found OK.
FALSE is returned if the requested channel is not in the sampling sequence.

Example

#include "abfheadr.h"


ABFH_GetWaveform

#include "abfheadr.h"

BOOL ABFH_GetWaveform( ABFFileHeader *pFH, int nChannel,
DWORD dwEpisode, float *pfBuffer, int *pnError);

The function ABFH_GetWaveform fills a buffer with the values that correspond to the DAC values output at the same time that a particular ADC channel was being sampled.

Parameter	Description
pFH	Pointer to ABFFileHeader structure containing the waveform epoch definitions.
nChannel	The particular ADC channel of interest.
dwEpisode	The episode for which build the waveform.
pfBuffer	Points to a buffer to fill with the waveform (in DAC UserUnits).
pnError	Address of error return code. May be NULL.
Comments

The waveform built is the waveform that corresponds to a particular ADC channel, and hence the length of the waveform returned is
pFH->lNumSamplesPerEpisode / pFH->nADCNumChannels.

Possible Error Codes

One of the following manifest constants (defined in ABFHEADR.H).

Constant	Meaning
ABFH_ENOWAVEFORM	Either there was no waveform specificication in the header, or the episode number is out of range.
ABFH_EDACFILEWAVEFORM	The waveform was taken from a DAC file, not from epoch definitions in the header.
ABFH_ENOMEMORY	Insufficient memory is available for a temporary buffer needed to  build the waveform.
ABFH_CHANNELNOTSAMPLED	The requested sample is not present in the sampling sequence.
Example

#include "abfheadr.h"

See Also

ABFH_GetWaveformVector


ABFH_GetWaveformVector

#include "abfheadr.h"

BOOL ABFH_GetWaveformVector(ABFFileHeader *pFH,
DWORD dwEpisode, UINT uStart, UINT uFinish, float *pfLevels,
float *pfTimes, int *pnVectors, int *pnError);

The function ABFH_GetWaveformVector builds a description of the output waveform as a set of Level/Time pairs.

Parameter	Description
pFH	Pointer to ABFFileHeader structure containing the waveform epoch definitions.
dwEpisode	The episode for which build the waveform.
uStart	The vectors will be clipped to start at this time.
uFinish	The vectors will be clipped to finish at this time.
pfLevels	Pointer to an array ABFH_MAXVECTORS long of floats to receive the level components.
pfTimes	Pointer to an array ABFH_MAXVECTORS long of floats to receive the time components.
pnVectors	Points to location in which to return the number of vectors generated.
pnError	Address of error return code. May be NULL.
Possible Error Codes

One of the following manifest constants (defined in ABFHEADR.H).

Constant	Meaning
ABFH_ENOWAVEFORM	Either there was no waveform specificication in the header, or the episode number is out of range.
ABFH_EDACFILEWAVEFORM	The waveform was taken from a DAC file, not from epoch definitions in the header.
Example

#include "abfheadr.h"

See Also

ABFH_GetWaveform


ABFH_GetTimebase

#include "abfheadr.h"

void ABFH_GetTimebase(ABFFileHeader *pFH, float fTimeOffset,
float *pfBuffer, UINT uBufferSize);

The function ABFH_GetTimebase builds a time array from the sampling rate parameters in the ABF header.

Parameter	Description
pFH	Pointer to ABFFileHeader structure containing the sampling rate parameters.
fTimeOffset	An offset that is added to all generated time values. This may be used to adjust the time array so that the first epoch starts at 0.
pfBuffer	Points to a floating point buffer to fill with values.
uBufferSize	To get the complete timebase for the episode the size of the buffer should be pFH->lNumSamplesPerEpisode pFH->nADCNumChannels.
Example

#include "abfheadr.h"


ABFH_GetHoldingDuration

#include "abfheadr.h"

UINT ABFH_GetHoldingDuration(ABFFileHeader *pFH);

The function ABFH_GetHoldingDuration returns the number of points that make up the first holding section of the waveform.

Parameter	Description
pFH	Pointer to ABFFileHeader structure.
Returns

The number of samples that make up the first holding region will be returned.

Example

#include "abfheadr.h"


ABFH_IsConstantWaveform

#include "abfheadr.h"

BOOL ABFH_IsConstantWaveform(ABFFileHeader *pFH);

The function ABFH_IsConstantWaveform checks to see if the waveform specification in the ABF header contains any varying epochs.

Parameter	Description
pFH	Pointer to ABFFileHeader structure.
Returns

TRUE is returned if the waveform does not have any varying epoch specifications.

Example

#include "abfheadr.h"


Error Values

The following is a table of error values that may be returned by functions in the ABFH_XXX set of functions.

Constant	Meaning
ABFH_EHEADERREAD	An error occurred while reading the header (EOF).
ABFH_EHEADERWRITE	An error occurred while writing the header (Out of disk space)
ABFH_EINVALIDFILE	The header version number of this file is invalid.
ABFH_EUNKNOWNFILETYPE	The file is not an ABF file.
ABFH_EPOCHNOTPRESENT	The requested epoch was not present for the episode specified.
ABFH_ENOWAVEFORM	Either there was no waveform specificication in the header, or the episode number is out of range.
ABFH_EDACFILEWAVEFORM	The waveform was taken from a DAC file, not from epoch definitions in the header.
ABFH_ENOMEMORY	Insufficient memory is available for a temporary buffer needed to  build the waveform.
ABFH_CHANNELNOTSAMPLED	The requested sample is not present in the sampling sequence.


The ABF File Information Functions by category

File Information Functions

Routine	Use
INFO_GetBufferSize	Get the size of the buffer required by INFO_GetInfo for a particular header.
INFO_GetInfo	Fill a passed buffer with a textual version of information contained in an ABF header. Options are terse, long or verbose.


The ABF File Information Functions

INFO_GetBufferSize

INFO_GetInfo


INFO_GetBufferSize

#include "abfinfo.h"

UINT INFO_GetBufferSize( ABFFileHeader *pFH, char *szDataFile,
int nDisplayMode);

Returns the size (in characters) of the buffer required by INFO_GetInfo with the same parameters.

Parameter	Description
pFH	Pointer to ABFFileHeader structure to be described.
pszFileName	String containing the name of the file associated with the ABFFileHeader structure.
nDisplayMode	Flag to specify the type of information required: Valid flags are: INFO_TERSE, INFO_LONG, INFO_VERBOSE.
Comments

The parameters passed into INFO_GetBufferSize must be passed unchanged into INFO_GetInfo for the buffer size returned by INFO_GetBufferSize to be valid. If parameters are changed (different file name, or midified header) the buffer size will not necessarily correspond to that required by INFO_GetInfo, resulting in truncated information.

Returns

The number of characters that will be written by INFO_GetInfo when passed the identical parameters.

Example

#include "abfheadr.h"

#include "abfinfo.h"

BOOL ShowABFFileInfo(char *szFileName)

{

   ABFFileHeader FH;

   int nFile = open(szFileName, O_BINARY, O_READONLY);

   if (nFile < 0)

      return FALSE;

   int nError = ABFH_ParamReader( nFile, &FH );

   close(nFile);

   if (nError != ABFH_SUCCESS)

      return FALSE;

   UINT uBufSize = INFO_GetBufferSize( &FH, szFileName, INFO_LONG);
   char *pszInfoBuf = malloc(uBufSize);

   if (!INFO_GetInfo(&FH, szFileName, INFO_LONG, pszInfoBuf, uBufSize))

      return FALSE;

   puts(pszInfoBuf);

   return TRUE;

}

See also

INFO_GetInfo


INFO_GetInfo

#include "abfinfo.h"

UINT INFO_GetInfo(ABFFileHeader *pFH, char *pszFileName,
int nDisplayMode, char *pszGetInfoBuf, UINT uBufSize);

Fills a text buffer with information found in the passed ABFFileHeader structure.

Parameter	Description
pFH	Pointer to ABFFileHeader structure to receive  parameters.
pszFileName	String containing the name of the file associated with the ABFFileHeader structure.
nDisplayMode	Flag to specify the type of information required: Valid flags are: INFO_TERSE, INFO_LONG, INFO_VERBOSE.
pszGetInfoBuf	Pointer to text buffer to be filled.
uBufSize	Size of the buffer pointed to by pszGetInfoBuf
Comments

The INFO_GetInfo function takes the information in the passed ABFFileHeader and generates a block of text that describes the parameters. The function INFO_GetBufferSize should be called prior to INFO_GetInfo to determine the size of the buffer required by INFO_GetInfo.

Returns

The number of characters placed into the passed buffer.

Example

#include "abfheadr.h"

#include "abfinfo.h"

BOOL ShowABFFileInfo(char *szFileName)

{

   ABFFileHeader FH;

   int nFile = open(szFileName, O_BINARY, O_READONLY);

   if (nFile < 0)

      return FALSE;

   int nError = ABFH_ParamReader( nFile, &FH );

   close(nFile);

   if (nError != ABFH_SUCCESS)

      return FALSE;

   UINT uBufSize = INFO_GetBufferSize( &FH, szFileName, INFO_LONG);
   char *pszInfoBuf = malloc(uBufSize);

   if (!INFO_GetInfo(&FH, szFileName, INFO_LONG, pszInfoBuf, uBufSize))

      return FALSE;

   puts(pszInfoBuf);

   return TRUE;

}

See also

INFO_GetBufferSize


ATF File Format

Overview

Definitions

ATF Description

Conventions

ATF 1.0 Specification


Axon Text Files (ATF) - ATF File Format - Overview
Overview

The ATF file format (previously known as the PAF file format) is a structured text file format that can be used for data export and import by all of Axon's programs,  whether for the PC or the Mac.

The formatted file is easy for common third party graphics and spreadsheet programs to read,  and it enables users of these programs to select traces for graphical display.

The file format as such does not contain specific knowledge of the data hierarchy.   For example,  the format does not impose a specific order for writing sweeps and runs.

A set of conventions will be presented to be used by programs when creating an ATF file.  These conventions contain specific knowledge of the data hierarchy.


Axon Text Files (ATF) - ATF File Format - Definitions
Definitions

A "line terminator" is a carriage return on a Mac,  but a carriage return and line feed on a PC.   When reading a text file,  programs should accept either version of the line terminator.

A "record" is string of text terminated by a line terminator.

A "field" is a single numeric value or a text string.   Within each record,  there may be several fields,  separated by field separators.

A "field separator" is either a comma or a tab.   During file reading,  a field separator may include any number of spaces with the comma or tab.

"Header" records located at the start of the file describe the file structure and the data.   Header records sometimes contain fields bearing a one-for-one correspondence with the fields in the data records (e.g. a header record containing the column titles) but in many cases there is no correspondence (e.g. a free-format comment record.)

A "trace" is a vector of related data points.   (For example,  A/D channel #1 from a single sweep.

"Quotes" are double quotes.


ATF Description

In the ATF format,  a specified number of records of header information (in exactly the format described) precedes the data values.   If the header records contain multiple fields,  these are separated by field separators.

The data is written in columnar format,  with each row being one record.   There may be multiple data values in each record separated by field separators.

Optional records may be included before the data set.   The last record before the data set is a required record called the titles and units record.   The titles and units record contains one field for each column.   For example,  "Time (ms)" or "Current (nA)".

Strings must be surrounded by double quotes.   This is because the strings could include tabs or commas that would be mistakenly identified as separators.   All program-generated text strings should use only the printable ASCII character set.   For example,  use "us" instead of "µs".   Note,  this restriction does not apply to the user comment or the user-entered user units.

An optional comment can be added to individual records in the last column position.


Conventions

1.	If the data set contains X-Y data,  the columns of X-Y pairs are in the order X,  Y.

2.	If the data are binned,  the first value is the lower (i.e. left) limit for each bin followed by the number of items in the bin.

3.	PC programs should not rely on the extension ATF or ASC to indicate the file type.   Instead,  see the separate document titled "DOS File Naming Conventions" for suggested extensions.

4.	Records should be added to the beginning of each run to define column-specific parameters.

Examples are:
(a)	A/D channel number.
(b)	Sweep (episode) number.
(c)	First incrementing variable value
(d)	Second incrementing variable value
etc.

These lines of information are helpful to spreadsheet users.   They would not normally be relied upon by an importing program.

5.	The default field separator will generally be a tab.   An export option will be offered to use commas.

When importing ATF data,  programs should accept tabs and commas as field separators without requiring the user to indicate which type of separator is in the file.

6.	If the exporting program can potentially export traces from multiple sweeps (episodes) and multiple A/D channels simultaneously,  the exporting program should offer choices for the column arrangement:
[ ] Export all displayed A/D channels.  Choose sweep: ___
[ ] Export all displayed sweeps.  Choose A/D channel: ___
[ ] Export all displayed A/D channels and sweeps.

Offering these choices may be relevant in some programs (AxoData) but not in others (Axotape,  Clampfit,  etc.).

If the exported data has multiple sweeps consisting of multiple A/D channels,  the columns should be arranged in "sweep-major" order.   For example:

	"Sweep #1"	"Sweep #1"	"Sweep #2"	"Sweep #2"
	"A/D #1"	"A/D #2"	"A/D #1"	"A/D #2"
"t(ms)	"Currt (pA)"	"Potl (mV)"	"Currt (pA)"	"Potl (mV)"
1.1	data	data	data	data
1.2	data	data	data	data
1.3	data	data	data	data
1.4	data	data	data	data
7.	Some analysis programs cannot read records that are more than a few hundred characters long.   The exporting program will not warn the user.   It is up to the user to specify a reasonable range of sweeps or A/D channels.

8.	The X column will always be included.

9.	The optional header records will usually contain information presented in a consistent fashion based on reserved words.   Examples of reserved words and their use are:

"AcquisitionMode=High-Speed Oscilloscope."
"AveragesLocation=Data start + 63"
"DataOrganization=Binned / Not binned"
"BinAlignment=Left"
"BinWidth=2.0"
"Comment=This is an example of an exported comment."
"DataFileModified=Yes"
"DataFileName=DEMOFTX.DAT"
"Heading="
"PulseCount=65"
"Reduction=x3 using Average Substitution"
"EpiCount=180"
"AvgEpisodes=1,3,5,7,9,11,12,13,21,22,27,31,32"
"Type=All-Points Amplitude Histogram"
"Type=Clampfit Buffer"
"Type=Results Array"
"Type=Cumulative Statistics"
"Type=Cursor Measurements"
"Type=Data Segment"
"Type=Integrated Activity"
"Type=Peak Detection"
"Type=Pulse Average"
"Type=Segmented Sum"
"Type=Spike Analysis"
"Type=Sums File"
"XYName=2CH.DAT"
"YRange=8000"

10	The resolution of the numbers in each column should be appropriate to the data.   For example,  if the column contains sample time,  where the acquisition was at 100 kHz,  there should be five digits after the decimal point if the number is in seconds,  or 2 digits after the decimal point if the number is in ms.

11	The obsolete version 5.0 PAF file format is documented in the pCLAMP 5.5 and the AxoTape 1.2 manuals.


ATF 1.0 Specification

This new format is almost identical to PAF 5.0,  but the titles and units have been combined into one record,  as have the n and m values.

Description	Details
First header record	ATF 1.0
Second header record	n m
1st optional record	'optional record
2nd optional record	'optional record
.	'optional record
.	'optional record
nth optional record	'optional record
(n + 3)th record	'Required record containing m fields.   Each field contains the column title and units.   The units are in parentheses.
n Data Records	'm columns of data
where "n" is the number of optional header records and "m" is the number of columns in each record.

Example

ATF	1.0

5	3

"Type=Sums File"

"DataFileName=SINGLES.DAT"

"Comment="

"SumCount=18"

"SumsEpisodes=1,3,5,7,9,11,12,13,14,21,22,23,25,27,29,31,32,33"

"Time (ms)"	"Amplitude (pA)"	"Comment ()"

 0	-1.75665	""

 .2	-1.796178	""

 .4	-1.834542	""

 .6	-1.848493	""

 .8	-1.774089	""

 1	-1.700846	"Applied pulse"

 1.2	-1.728748	""

 1.4	-1.817104	""

 1.6	-1.822917	""

 1.8	-1.805478	""

 2	-1.655506	"Removed pulse"

 2.2	-1.683408	""

 2.4	-1.738049	""

 2.6	-1.683408	""

 2.8	-1.762463	""

 3	-1.736886	""

 3.2	-1.665969	""


ATF Function API

Overview

Notes

ATF_BuildErrorText

ATF_Cleanup

ATF_CloseFile

ATF_CountDataLines

ATF_GetColumnTitle

ATF_GetColumnUnits

ATF_GetFileDateTime

ATF_GetNumHeaders

ATF_Initialize

ATF_IsAppending

ATF_OpenFile

ATF_ReadDataColumn

ATF_ReadDataRecord

ATF_ReadDataRecordArray

ATF_ReadHeaderLine

ATF_ReadHeaderNoQuotes

ATF_RewindFile

ATF_SetColumnTitle

ATF_SetColumnUnits

ATF_WriteDataComment

ATF_WriteDataRecord

ATF_WriteDataRecord1

ATF_WriteDataRecordArray

ATF_WriteEndOfLine

ATF_WriteHeaderRecord


Axon Text Files (ATF) - ATF Function API - Overview
Overview

The ATF file routines are a set of functions for creating or accessing plain ASCII text files formatted according to the ATF File Format specification.


Notes

•	The process of writing an ATF file with the ATF API functions is modal with respect to writing the file headers. When the file is first opened for writing headers can be written, but once the first call to write data into the file has been made, the user cannot go back to writing headers again.

•	Headers can only be read once from an ATF file. Each call to ATF_ReadHeaderLine() returns an ATF header anf moves internal pointers on to the next header, previous headers cannot be re-read without re opening the file.

•	The ATF reading routines process a complete line of an ATF file in each call. This means that concecutive read calls will always take data from concecutive lines in the file. Thus ATF_ReadDataColumn, if called twice concecutively with different column numbers wilol read data from different lines NOT from the same line.


ATF_BuildErrorText

#include "atffiles.h"

BOOL ATF_BuildErrorText( int nErrorNum, char *szFileName, char *szTxtBuf,
 int nMaxLen );

Builds an error message for the specified error number.

Parameter	Description
nErrorNum	Error number to create message from.
szFileName	Name of file.
szTxtBuf	Buffer for error text.
nMaxLen	Size of szTxtBuf.
Comments

The ATF_BuildErrorText function builds an error message based on nErrorNum and szFileName.

Returns

TRUE is returned if nErrorNum contains a valid error number.
FALSE is returned otherwise.

Example

#include "atffiles.h"

static BOOL ShowATFError( int nErrorNum, char *szFileName )

{

   char szTxt[80];

   if (!ATF_BuildErrorText( nErrorNum, szFileName, szTxt, 80 ))

      sprintf( szTxt, "Unknown error number: %d\r\n", nErrorNum );

   printf( "ERROR: %s\n", szTxt );

   return FALSE;    // always return FALSE.

}


ATF_Cleanup

#include "atffiles.h"

void ATF_Cleanup(void);

Performs clean-up of the text file I/O module.

Comments

The ATF_Cleanup function removes all vestiges of the text file I/O module from the system. It should be called once after text file I/O processing is completed and no longer required.

Example

#include "atffiles.h"

int TheAnalysisProgram(int argc, char *argv[])

{

   int nErrorNum;

   ATF_Initialize();

   nErrorNum = Analysis(argv[1]);

   ATF_Cleanup();

   return nErrorNum;

}

See Also

ATF_Initialize


ATF_CloseFile

#include "atffiles.h"

BOOL ATF_CloseFile(int hATFFile);

Closes a previously opened ATF file.

Parameter	Description
hATFFile	ATF file handle.
Comments

The ATF_CloseFile function closes the ATF file specified in hATFFile.

Returns

TRUE is returned if the file is closed successfully, otherwise FALSE is returned.

See Also

ATF_OpenFile
ATF_RewindFile

Example

#include "atffiles.h"

int ShowHeaders(char *pszFileName)

{

   int hATFFile, I, nError = 0;

   int nNumHeaders;

   int nErrorNum;

   int nColumns;

   char sBuf[ATF_IOBUFFERLEN];

   if (!ATF_OpenFile(szFileName, TRUE, FALSE, &nColumns, &hATFFile,

                     &nError))

      return ShowATFError(nError, szFileName);

   if (!ATF_GetNumHeaders(hATFFile, &nNumHeaders, &nError))

   {

      ATF_CloseFile(hATFFile);

      return ShowATFError(nError, szFileName);

   }

   for (i=0; i < nNumHeaders; i++)

   {

      if (!ATF_ReadHeaderLine(hATFFile, sBuf, &nError))

      {

         printf("Error reading header %d\n", i+1);

         continue;

      }

      printf("%s\n", sBuf);

   }

   ATF_CloseFile(hATFFile);

}


ATF_CountDataLines

#include "atffiles.h"

BOOL ATF_CountDataLines(int hATFFile, long *plNumLines, int *pnError);

Counts the number of lines of data in the data section.

Parameter	Description
hATFFile	ATF file handle.
plNumLines	Pointer to number of lines found.
pnError	Address of error return code. May be NULL.
Comments

The ATF_CountDataLines function reads and count text lines until either a blank line is found, or EOF is reached.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
Example

int CountATFLines(char *pszFileName, long *plNumLines)

{

   int hATFFile;

   int nErrorNum;

   int nColumns;

   if (ATF_OpenFile(szFileName, TRUE, FALSE, &nColumns,

                    &hATFFile) != ATF_SUCCESS)

      return ATF_GetLastError();

   nErrorNum = ATF_CountDataLines(hATFFile, &plNumLines);

   ATF_CloseFile(hATFFile);

   return nErrorNum;

}


ATF_GetColumnTitle

#include "atffiles.h"

BOOL ATF_GetColumnTitle(int hATFFile, int nColumn, char *pszText, int nMaxTxt
int *pnError);

Get the title of a column from an ATF file.

Parameter	Description
hATFFile	ATF file handle.
nColumn	Column number to retreive the title of.
pszText	Pointer to column title text.
nMaxTxt	Length of the pszText buffer.
Comments

The ATF_GetColumnTitle function gets the next sequential column title from the specified file hATFFile and stores it in pszText.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
See Also

ATF_GetColumnUnits

ATF_SetColumnTitle

ATF_SetColumnUnits

Example

#include "atffiles.h"

int GetColumnText(int hATFFile, char *pszTitleText, char *pszUnitsText)

{

   int nErrorNum;

   nErrorNum = ATF_GetColumnTitle(hATFFile, pszTitleText);

   if (nErrorNum == ATF_SUCCESS)

      nErrorNum = ATF_GetColumnUnits(hATFFile, pszUnitsText);

   return nErrorNum;

}


ATF_GetColumnUnits

Get the units of a column from an ATF file.

#include "atffiles.h"

int ATF_GetColumnUnits(int hATFFile, char *pszText);

Parameter	Description
hATFFile	ATF file handle.
pszText	Pointer to column units text.
Comments

The ATF_GetColumnUnits function gets the next sequential column units from the specified file hATFFile and stores it in pszText.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
See Also

ATF_GetColumnTitle

ATF_SetColumnTitle

ATF_SetColumnUnits

Example

#include "atffiles.h"

int GetColumnText(int hATFFile, char *pszTitleText, char *pszUnitsText)

{

   int nErrorNum;

   nErrorNum = ATF_GetColumnTitle(hATFFile, pszTitleText);

   if (nErrorNum == ATF_SUCCESS)

      nErrorNum = ATF_GetColumnUnits(hATFFile, pszUnitsText);

   return nErrorNum;

}


ATF_GetFileDateTime

Get the date and time that the ATF file was last modified.

#include "atffiles.h"

int ATF_GetFileDateTime(int hATFFile, long *plDate, long *plTime);

Parameter	Description
hATFFile	ATF file handle.
plDate	Date at which file was last modified.
plTime	Time at which file was last modified.
Comments

The date and time retrieved by ATF_GetFileDateTime are the same as those maintained by DOS and shown with a DIR command. Time is returned in seconds since midnight. Date is returned as YYMMDD digits in a long.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.


 ATF_GetNumHeaders

Finds the number of headers in an ATF file.

#include "atffiles.h"

int ATF_GetNumHeaders(int hATFFile, int *piNumHeaders);

Parameter	Description
hATFFile	ATF file handle.
piNumHeaders	Pointer to number of headers.
Comments

The ATF_GetNumHeaders function finds the number of headers in the specified file hATFFile, and stores this value to *piNumHeaders.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
See Also

ATF_WriteHeaderRecord

ATF_ReadHeaderLine

ATF_ReadHeaderNoQuotes

Example

#include "atffiles.h"

int ShowHeaders(int hATFFile)

{

   int nNumHeaders;

   int nErrorNum;

   char sBuf[ATF_IOBUFFERLEN];

   if (ATF_GetNumHeaders(hATFFile, &nNumHeaders) != ATF_SUCCESS)

   return (ATF_GetLastError());

   for (i=0; i < nNumHeaders; i++)

   {

      if (ATF_ReadHeaderLine(hATFFile, sBuf) != ATF_SUCCESS)

      {

         printf("Error reading header %d\n", i+1);

         continue;

      }

      printf("%s\n", sBuf);

   }

}


ATF_Initialize

Initializes the text file I/O module.

#include "atffiles.h"

void ATF_Initialize(void);

Parameter	Description
nUseCommas	Define separator as comma or TAB.
Comments

The ATF_Initialize function is used to perform initialization of the text file I/O module. This function must be called prior to the use of any other functions in the I/O module.

See Also

ATF_Cleanup

Example

#include "atffiles.h"

int TheAnalysisProgram(int argc, char *argv[])

{

   int nErrorNum;

   ATF_Initialize(TRUE);	// Use commas.

   nErrorNum = Analysis(argv[1]);

   ATF_Cleanup();

   return nErrorNum;

}


ATF_IsAppending

Checks whether the ATF file was opened for appending.

#include "atffiles.h"

int ATF_IsAppending(int hATFFile);

Parameter	Description
hATFFile	ATF file handle.
Comments

If an ATF file is opened for appending, it is not possible to add header lines or column titles. A call to ATF_IsAppending can be used to prevent illegal calls.

Returns

This function returns TRUE or FALSE  (1 or 0).

See Also

ATF_OpenFile


ATF_OpenFile

Opens an  ATF file.

#include "atffiles.h"

int ATF_OpenFile(char *szFileName, unsigned wFlags, int *piColumns, *piFileNum);

Parameter	Description
szFileName	Name of file to open.
wFlags	Combined flags to control options.
piColumns	Pointer to number of columns.
piFileNum	Pointer to ATF file handle.
Comments

The ATF_OpenFile function opens the data file szFileName for reading or writing allocates an ATF file handle for it and assigns this number to *piFileNum. The header is read from the file or written to the file.

Flags that can be combined and passed in the wFlags parameter include:

Flag	Meaning
ATF_READONLY	Open the file with read access
ATF_WRITEONLY	Open the file with write access
ATF_OVERWRTIFEXIST	If file exists, overwrite it (only for ATF_WRITEONLY)
ATF_APPENDIFEXIST	If file exists, append to it (only for ATF_WRITEONLY)
Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_TOOMANYFILES	MAX_ATF_FILES files are already open.
ATF_ERROR_NOMEMORY	Could not allocate memory for ATFFile.
ATF_ERROR_NOFILE	Could not open file.
ATF_ERROR_TOOMANCOLS	*piColumns is greater than ATF_MAXCOLUMNS.
ATF_ERROR_FILEEXISTS	Overwrite not permitted on existing file.
See Also

ATF_CloseFile

ATF_RewindFile

Example

#include "atffiles.h"

int ShowHeaders(char *pszFileName)

{

   int hATFFile;

   int nNumHeaders;

   int nErrorNum;

   int nColumns;

   char sBuf[ATF_IOBUFFERLEN];

   if (ATF_OpenFile(szFileName, TRUE, FALSE, &nColumns, &hATFFile) !=

                      ATF_SUCCESS)

      return (ATF_GetLastError());

   if (ATF_GetNumHeaders(hATFFile, &nNumHeaders) != ATF_SUCCESS)

      return (ATF_GetLastError());

   for (i=0; i < nNumHeaders; i++)

   {

      if (ATF_ReadHeaderLine(hATFFile, sBuf) != ATF_SUCCESS)

      {

         printf("Error reading header %d\n", i+1);

         continue;

      }

      printf("%s\n", sBuf);

   }

   ATF_CloseFile(hATFFile);

}


ATF_ReadDataColumn

Read data from a given column in an ATF file.

#include "atffiles.h"

int ATF_ReadDataColumn(int hATFFile, int nColumn, float *pfValue);

Parameter	Description
hATFFile	ATF file handle.
nColumn	Column to read data from. (first column is 0)
Comments

The ATF_ReadDataColumn function reads a line of data from the specified file hATFFile and returns the value located in the column nColumn. This function always reads the next line of the data file, so concecutive calls with different nColumn parameters will retrieve data from different lines.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_BADHEADER	Failed reading header.
ATF_ERROR_IOERROR	Error reading from file.
See Also

ATF_WriteDataRecord1..6

ATF_WriteDataRecordArray

ATF_WriteDataComment

ATF_WriteDataRecord

ATF_ReadDataRecord

ATF_ReadDataRecordArray

Example

#include "atffiles.h"

int ShowDataColumn(char *pszFileName, int nColumn)

{

   int hFile, nColumns;

   long lNumLines;

   if (ATF_OpenFile(pszFileName, ATF_READONLY, &nColumns, &hFile)!=ATF_SUCCESS)

   {

      printf(stderr, "Error opening file '%s'.\n", pszFileName);

      return FALSE;

   }

   if (nColumn >= nColumns)

   {

      printf(stderr, "Column number %d is out of range.\n", nColumn);

      ATF_CloseFile(hFile);

      return FALSE;

   }

   if (ATF_CountDataLines(hFile, &lNumLines)!=ATF_SUCCESS)

   {

      printf(stderr, "Error reading file '%s'.\n", pszFileName);

      ATF_CloseFile(hFile);

      return FALSE;

   }

   while (lNumLines--)

   {

      if (ATF_ReadDataColumn(hFile, nColumn, &fValue) != ATF_SUCCESS)

      {

         printf(stderr, "Error reading file '%s'.\n", pszFileName);

         ATF_CloseFile(hFile);

         return FALSE;

      }

      printf("%g\n", fValue);

   }

   ATF_CloseFile(hFile);

}


ATF_ReadDataRecord

Read data from an ATF file.

#include "atffiles.h"

int ATF_ReadDataRecord(int hATFFile, char *pszText);

Parameter	Description
hATFFile	ATF file handle.
pszText	Pointer to data record text.
Comments

The ATF_ReadDataRecord function reads a data record from the specified file hATFFile into pszText.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_BADHEADER	Failed reading header.
ATF_ERROR_IOERROR	Error reading from file.
See Also

ATF_WriteDataRecord1..6

ATF_WriteDataRecordArray

ATF_WriteDataComment

ATF_WriteDataRecord

ATF_ReadDataRecord

ATF_ReadDataRecordArray

Example

#include "atffiles.h"

int ATF_ReadDataRecordArray(int hATFFile, int nCount, float *pfVals, char *pszComment)

{

   int i;

   char psReadBuffer[ATF_IOBUFFERLEN], *ps;

   // Perform the necessary checks and read the data record

   if (ATF_ReadDataRecord(hATFFile, psReadBuffer) != ATF_SUCCESS)

      return(nLastError);

   // Read out the requested numbers

   ps = psReadBuffer;

   for (i=0; i<nCount; i++)

      ps = GetNumber(ps, pfVals+i);

   if (pszComment != NULL)

   {

      GetComment(ps, &ps);

      strcpy(pszComment, ps);

   }

}


ATF_ReadDataRecordArray

Read floating point data values from an ATF file.

#include "atffiles.h"

int ATF_ReadDataRecordArray(int hATFFile, int nCount, float *pfVals,
char *pszComment);

Parameter	Description
hATFFile	ATF file handle.
nCount	Number of floating point values to read.
pfVals	Pointer to the floating point values.
pszComment	Pointer to comment text.
Comments

The ATF_ReadDataRecordArray function reads nCount floating point values from the specified file hATFFile into pfVals. It also reads the comment into pszComment.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_BADHEADER	Failed reading header.
ATF_ERROR_IOERROR	Error writing to file.
See Also

ATF_WriteDataRecord

ATF_WriteDataRecord1..6

ATF_WriteDataComment

ATF_ReadDataRecord

ATF_WriteDataRecordArray

Example

#include "atffiles.h"

i = 0;

while (1)

{

   i++;

   if (ATF_ReadDataRecordArray(hATFFile, nColumns, afVals, sBuf) !=

                               ATF_SUCCESS)

   {

      printf("END OF FILE found reading data record %d.\n", i);

      break;

   }

   printf("\n%s\n", sBuf);

   printf("%g", afVals[0]);

   for (j=1; j<nColumns; j++)

      printf(", %g", afVals[j]);

   printf("\n");

}


ATF_ReadHeaderLine

Reads a header record from an ATF file.

#include "atffiles.h"

int ATF_ReadHeaderLine(int hATFFile, char *pszBuf, int nMaxLength);

Parameter	Description
hATFFile	ATF file handle.
pszBuf	Pointer to header record text.
nMaxLength	Maximum length to read.
Comments

The ATF_ReadHeaderLine function reads a header record line from the specified file hATFFile, strips the EndOfLine character, and stores it into pszBuf.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
ATF_ERROR_NOMORE	No header records left to read.
ATF_ERROR_BADHEADER	Failed reading header.
See Also

ATF_GetNumHeaders

ATF_WriteHeaderRecord

ATF_ReadHeaderNoQuotes

Example

#include "atffiles.h"

int ShowHeaders(int hATFFile)

{

   int nNumHeaders;

   int nErrorNum;

   char sBuf[ATF_IOBUFFERLEN];

   if (ATF_GetNumHeaders(hATFFile, &nNumHeaders) != ATF_SUCCESS)

      return (ATF_GetLastError());

   for (i=0; i < nNumHeaders; i++)

   {

      if (ATF_ReadHeaderLine(hATFFile, sBuf,

                             ATF_IOBUFFERLEN) != ATF_SUCCESS)

      {

         printf("Error reading header %d\n", i+1);

         continue;

      }

      printf("%s\n", sBuf);

   }

}


ATF_ReadHeaderNoQuotes

Reads a header record from an ATF file, and strips off any quotes.

#include "atffiles.h"

int ATF_ReadHeaderNoQuotes(int hATFFile, char *pszT1);

Parameter	Description
hATFFile	ATF file handle.
pszT1	Pointer to header record text token.
Comments

The ATF_ReadHeaderNoQuotes functions read a header record line from the specified file hATFFile, parses the line the token into pszT1.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
ATF_ERROR_NOMORE	No header records left to read.
ATF_ERROR_BADHEADER	Failed reading header.
See Also

ATF_GetNumHeaders

ATF_WriteHeaderRecord

ATF_ReadHeaderLine

Example

#include "atffiles.h"

int ShowHeaders(int hATFFile)

{

   int nNumHeaders;

   int nErrorNum;

   char sBuf[ATF_IOBUFFERLEN];

   if (ATF_GetNumHeaders(hATFFile, &nNumHeaders) != ATF_SUCCESS)

      return (ATF_GetLastError());

   for (i=0; i < nNumHeaders; i++)

   {

      if (ATF_ReadHeaderNoQuotes(hATFFile, sBuf, ATF_IOBUFFERLEN) !=
            ATF_SUCCESS)

      {

         printf("Error reading header %d\n", i+1);

         continue;

      }

      printf("%s\n", sBuf);

   }

}


ATF_RewindFile

Moves the file pointer associated with the specified ATF file to the beginning of the data contained in the file.

#include "atffiles.h"

int ATF_RewindFile(int hATFFile);

Parameter	Description
hATFFile	ATF file handle.
Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File already closed.
See Also

ATF_OpenFile

ATF_CloseFile

Example

#include "atffiles.h"

int XVT_OpenFile(char *szFileName, ABFFileHeader *pFH)

{

   WORD wMaxEpi, wMaxSamples = 16384;

   char ATFReadBuf[ATF_IOBUFFERLEN];

   nLastError = XVT_SUCCESS;

   if (nFileHandle < 0)           // close any file currently open

      XVT_CloseFile();

   // Firstly try to open the file as an ABF file

   nIsABFFile = TRUE;              // set ABF flag

   if (ABF_ReadOpen(szFileName, &nFileHandle, ABF_DATAFILE, pFH,

                    &wMaxSamples, &wMaxEpi) != ABF_SUCCESS)

   {

      nLastError = ABF_GetLastError();

      if (nLastError != ABF_EUNKNOWNFILETYPE)

         return(nLastError);

      // Now try to open the file as an ATF file

      nIsABFFile = FALSE;

      nLastError = XVT_SUCCESS;

      if (ATF_OpenFile(szFileName, TRUE, FALSE, (int *)&wMaxEpi,

                       &nFileHandle) != ATF_SUCCESS)

         return(nLastError = ATF_GetLastError() + ATFERROROFFSET);

      // Get the number of samples in the ATF file.

      wMaxSamples = 0;

      while (ATF_ReadDataRecord(nFileHandle, ATFReadBuf) == ATF_SUCCESS)

         ++wMaxSamples;

      ATF_RewindFile(nFileHandle);

      SetATFHeader(pFH, wMaxEpi, wMaxSamples);

   }

   return(nLastError);

}


ATF_SetColumnTitle

Set a title for a column of an ATF file.

#include "atffiles.h"

int ATF_SetColumnTitle(int hATFFile, char *pszText);

Parameter	Description
hATFFile	ATF file handle.
pszText	Pointer to column title text.
Comments

The ATF_SetColumnTitle function sets the next sequential column title from pszText for the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_TOOMANYCOLS	This column number exceeds the maximum.
ATF_ERROR_NOMEMORY	Could not allocate string memory.
See Also

ATF_SetColumnUnits, ATF_GetColumnTitle, ATF_GetColumnUnits

Example

#include "atffiles.h"

int SetColumn(int hATFFile, char *pszTitleText, char *pszUnitsText)

{

   int nErrorNum;

   nErrorNum = ATF_SetColumnTitle(hATFFile, pszTitleText);

   if (nErrorNum == ATF_SUCCESS)

      nErrorNum = ATF_SetColumnUnits(hATFFile, pszUnitsText);

   return nErrorNum;

}


ATF_SetColumnUnits

Set the units for a column of an ATF file.

#include "atffiles.h"

int ATF_SetColumnUnits(int hATFFile, char *pszText);

Parameter	Description
hATFFile	ATF file handle.
pszText	Pointer to column units text.
Comments

The ATF_SetColumnUnits function sets the next sequential column units from pszText for the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_TOOMANYCOLS	This column number exceeds the maximum.
ATF_ERROR_NOMEMORY	Could not allocate string memory.
See Also

ATF_SetColumnTitle, ATF_GetColumnTitle, ATF_GetColumnUnits

Example

#include "atffiles.h"

int SetColumn(int hATFFile, char *pszTitleText, char *pszUnitsText)

{

   int nErrorNum;

   nErrorNum = ATF_SetColumnTitle(hATFFile, pszTitleText);

   if (nErrorNum == ATF_SUCCESS)

      nErrorNum = ATF_SetColumnUnits(hATFFile, pszUnitsText);

   return nErrorNum;

}


ATF_WriteDataComment

Write a comment to an ATF file.

#include "atffiles.h"

int ATF_WriteDataComment(int hATFFile, char *pszText);

Parameter	Description
hATFFile	ATF file handle.
pszText	Pointer to comment text.
Comments

The ATF_WriteDataComment function writes the comment from pszText to the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
The function returns the value of nLastError.

See Also

ATF_WriteDataRecord

Example

#include "atffiles.h"

int WriteComment(int hATFFile, char *pszText, int nCommentNum,

                 int bIncludeNum)

{

   int nErrorNum;

   char sBuf[ATF_IOBUFFERLEN];

   if (bIncludeNum)

      sprintf(sBuf, "Comment number %d: %s", nCommentNum, pszText);

   else

      strcpy(sBuf, pszText);

   nErrorNum = ATF_WriteDataComment(hATFFile, sBuf);

   if (nErrorNum == ATF_SUCCESS)

      nErrorNum = ATF_WriteEndOfLine(hATFFile);

   return nErrorNum;

}


ATF_WriteDataRecord

Write data to an ATF file.

#include "atffiles.h"

int ATF_WriteDataRecord(int hATFFile, char *pszText);

Parameter	Description
hATFFile	ATF file handle.
pszText	Pointer to data record text.
Comments

The ATF_WriteDataRecord function writes the data record from pszText for the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
See Also

ATF_WriteDataRecord

ATF_WriteDataRecordArray

ATF_WriteDataComment

ATF_ReadDataRecord

ATF_ReadDataRecordArray

Example

#include "atffiles.h"

int ATF_WriteDataComment(int hATFFile, char *pszText)

{

   char psWriteBuffer[ATF_IOBUFFERLEN];

   strcpy(psWriteBuffer, "\"");

   strcat(psWriteBuffer, pszText);

   strcat(psWriteBuffer, "\"");

   return(ATF_WriteDataRecord(hATFFile, psWriteBuffer));

}


ATF_WriteDataRecord1

ATF_WriteDataRecord2

ATF_WriteDataRecord3

Write floating point data values to an ATF file.

#include "atffiles.h"

int ATF_WriteDataRecord1(int hATFFile, float fNum1);

int ATF_WriteDataRecord2(int hATFFile, float fNum1, float fNum2);

int ATF_WriteDataRecord3(int hATFFile, float fNum1, float fNum2, float fNum3);

Parameter	Description
hATFFile	ATF file handle.
fNum1..3	The floating point values to be written.
Comments

The ATF_WriteDataRecord1..6 functions write the corresponding number of floating point values from fNum1..3 to the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
See Also

ATF_WriteDataRecord

ATF_WriteDataRecordArray

ATF_WriteDataComment

ATF_ReadDataRecord

ATF_ReadDataRecordArray

Example

#include "atffiles.h"

int SaveSomeData(int hATFFile, int nCount, float *pfVal1, float *pfVal2)

{

   for (i = 0 i < nCount) i++)

      ATF_WriteDataRecord2(hATFFile, pfVal1[i], pfVal2[i]);

}


ATF_WriteDataRecordArray

Write floating point data values to an ATF file.

#include "atffiles.h"

int ATF_WriteDataRecordArray(int hATFFile, int nCount, float *pfVals);

Parameter	Description
hATFFile	ATF file handle.
nCount	Number of floating point values to be written.
pfVals	Pointer to the floating point values to be written.
Comments

The ATF_WriteDataRecordArray function writes nCount floating point values from pfVals to the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
See Also

ATF_WriteDataRecord, WriteDataRecord1..6, WriteDataComment,

ATF_ReadDataRecord, ATF_ReadDataRecordArray

Example

#include "atffiles.h"

int SaveSomeMoreData(int hATFFile, int nCount, float *pfVals, float fConst)

{

   for (i = 0 i < nCount) i++)

      *pfVals *= fConst;

   ATF_WriteDataRecordArray(hATFFile, nCount, pfVals);

}


ATF_WriteEndOfLine

Writes an EndOfLine character to an ATF file.

#include "atffiles.h"

int ATF_WriteEndOfLine(int hATFFile);

Parameter	Description
hATFFile	ATF file handle.
Comments

The ATF_WriteEndOfLine function writes an EndOfLine character to the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
Example

#include "atffiles.h"

int WriteHeader(int hATFFile, char *pszText, int nHeaderNum, int bIncludeNum)

{

   int nErrorNum;

   char sBuf[ATF_IOBUFFERLEN];

   if (bIncludeNum)

      sprintf(sBuf, "Header number %d: %s", nHeaderNum, pszText);

   else

      strcpy(sBuf, pszText);

   nErrorNum = ATF_WriteHeaderRecord(hATFFile, sBuf);

   if (nErrorNum == ATF_SUCCESS)

      nErrorNum = ATF_WriteEndOfLine(hATFFile);

   return nErrorNum;

}


ATF_WriteHeaderRecord

Writes a header record to an ATF file.

#include "atffiles.h"

int ATF_WriteHeaderRecord(int hATFFile, char *pszText);

Parameter	Description
hATFFile	ATF file handle.
pszText	Pointer to header text.
Comments

The ATF_WriteHeaderRecord function writes a header record from pszText to the specified file hATFFile.

Possible Error Codes

One of the following error codes may be returned on error (defined in ATFFILES.H).

Constant	Meaning
ATF_SUCCESS	Function was successful.
ATF_ERROR_BADFILENUM	Invalid file number specified.
ATF_ERROR_BADSTATE	File is not in the correct state.
ATF_ERROR_IOERROR	Error writing to file.
See Also

ATF_GetNumHeaders

ATF_ReadHeaderLine

ATF_ReadHeaderNoQuotes

Example

#include "atffiles.h"

int WriteHeader(int hATFFile, char *pszText, int nHeaderNum, int bIncludeNum)

{

   int nErrorNum;

   char sBuf[ATF_IOBUFFERLEN];

   if (bIncludeNum)

      sprintf(sBuf, "Header number %d: %s", nHeaderNum, pszText);

   else

      strcpy(sBuf, pszText);

   nErrorNum = ATF_WriteHeaderRecord(hATFFile, sBuf);

   if (nErrorNum == ATF_SUCCESS)

      nErrorNum = ATF_WriteEndOfLine(hATFFile);

   return nErrorNum;

}