TCSV Component	help file	8th April 1999
-------------------------

CONTENTS
--------

1	Component Reference
	1.1	Description
	1.2	Properties
	1.3	Methods

2	Examples
	2.1	Reading a CSV file
	2.2	Writing a CSV file

3	Technical

4	File Distribution

5	Contact me

	***************************************************


1	TCSV Component
----------------------


1.1	Description

The TCSV Component lets you read and write CSV (Comma Separated
Variables) files just as you would a database table. The properties and
methods are similar to those of the TTable.


To Read a CSV file

Set the Filename property then call the Open method. Read FieldCount to
see how many fields are on the current line of the file. Read the files
using Fields[ ]. Use Next to move to the next line. Use EOF to test for
end of file. Use Close to close the file.

To Write a CSV file

Set the Filename property and the FieldCount property then call the Open
method. Write the the fields using the Fields[ ] property. Use the Next
method to move to the next line of the file. Use Close to close the
file.



1.2	Properties



1.2.1	Active Property

declaration	property Active : boolean

description

True indicates that a TCSV component is connected to the file in
FileName. When Active is True, the Fields and EOF properties and the
First, Next methods can be used. Use the Open method to set Active to
True. Use the Close method to set Active to False.


1.2.2	EOF Property

declaration	property EOF : boolean;

description

In read mode, indicates that the cursor is at the last record in the
file. Has no meaning in write mode.


1.2.3	FieldCount property

declaration	property FieldCount : integer;

description

Shows how many fields are in the CSV file.  

In write mode, sets the number of fields that will be written to each
line. The number of commas on a line is equal to the number of fields
minus one. Set FieldCount before calling the Open method - you cannot
change fieldcount while Active = True.

In read mode, tells the number of fields in the current line. Note that
the CSV format does not let us distinguish between a line with no fields
and a line with a single empty field. Each time Next is called,
FieldCount is updated to reflect the number of fields in the current
line.


1.2.4	Fields property

declaration	property Fields[ Index : integer ] : string;

description

Use the Fields property to read and write the fields of the current line
of the active CSV file. Use the Fields property only when Active = True.
The string accessed by Fields[ ] will contain any leading or trailing
spaces which exist in a comma delimited field in a CSV file. Any leading
or trailing spaces in a string assigned to Fields[ ] will be written to
to CSV file.


1.2.5	FileName property

declaration	property FileName : string;

description

Set the FileName property to the Windows name of the CSV file to be read
to or written from. Do not change FileName while Active = True. A full
drive/path/filename can be used.


1.2.6	ReadWrite property

declaration	property ReadWrite : TReadWrite

description

Set this property to csvRead or csvWrite before calling the Open method.
In read mode, an existing file is opened. In write mode, a new file is
created or an existing file is overwritten.


1.3	Methods


1.3.1	Close Method

declaration	procedure Close;

description

Use the Close procedure to disconnect the TCSV component from a the
file. 


1.3.2	Create method

declaration	constructor Create( AOwner : TComponent);

description

The Create method allocates memory to create the component and
initializes its data. 

Usually you don't need to create objects manually. Objects you design in
Delphi are automatically created for you when you run the application
and destroyed when you close the application.

The owner of the created component is passed in the AOwner parameter. If
you construct a component by calling Create, and give it an owner, the
owner disposes of the component when the owner is destroyed. If you
don't want another component to own the created component, pass Self in
the AOwner parameter. Set AOwner = NIL if you will destroy the component
explicitly, for example using a TRY FINALLY sequence.


1.3.3	Destroy method

Declaration	destructor Destroy;

Description

The Destroy method destroys the object, component, or control and
releases the memory allocated to it.

You seldom need to call Destroy. Objects designed with Delphi create and
destroy themselves as needed, so you don't have to worry about it. 

If you construct an object by calling the Create method, you should call
Free to release memory and dispose of the object.


1.3.4	First method

declaration	procedure First;

description

In read mode, use the First method to move to the first line in the CSV
file. Do not use this method in Write mode.


1.3.5	Next method

declaration	procedure Next;

description

Use the Next method to move to the next line in the CSV file. In write
mode, a line of fields is written to the file. In read mode, a line of
fields is read from the file.


1.3.6	Open method

declaration	procedure Open;

description

Call Open to connect a TCSV object to the file in the FileName property.
Sets the Active method to True. The file can be read from or written to
after a call to Open.



2	Example Code
--------------------

2.1	Reading a CSV file


procedure TForm1.ReadCSVTButtonClick(Sender: TObject);

var FieldIndex : integer;

begin

    TRY
        Memo.Visible := False;
        CsvFile.Close;
 
        CsvFile.Filename := FilenameTEdit.Text;
        CsvFile.ReadWrite := csvRead;
        CsvFile.Open;

        Memo.Lines.Add( 'start...' );

        { read all records in TCSV }
        while not CsvFile.EOF do begin
            FieldIndex := 0;
            while FieldIndex < CsvFile.FieldCount do begin
                Memo.Lines.Add(
                    Format( '(%d)%s',
                    [FieldIndex, CsvFile.Fields[FieldIndex]]) );
                Inc( FieldIndex );
            end;
            CSVFile.Next;
        end;
 
       { now read first record again }
        CsvFile.First;
        Memo.Lines.Add( '0 ' + CsvFile.Fields[0] );

    FINALLY
        CsvFile.Close;
        Memo.Visible := True;
    END;
end;


2.2	Writing a CSV File


procedure TForm1.MakeCSVClick(Sender: TObject);

begin

    TRY

        CsvFile.Filename := FilenameTEdit.Text;
        CsvFile.ReadWrite := csvWrite;
 
       { only need to set FieldCount when writing (ie defining) file }
        CsvFile.FieldCount := 3;
        CsvFile.Open;

        { Write to fields ]
        CsvFile.Fields[0] := 'hello';
        CsvFile.Fields[1] := 'world';
        CsvFile.Fields[2] := 'wide';
 
       { overwrite fields - to prove it can be done }
        CsvFile.Fields[0] := 'our';
        CsvFile.Fields[1] := 'sweet';
        CsvFile.Fields[2] := 'home';

        { save record }
        CsvFile.Next;
 
       { save a record with all fields empty }
        CsvFile.Next;

    FINALLY
        CsvFile.Close;

    END;
end;


3	Technical
-----------------

The CSV component has been used under D1 and D3.  It is unspectacular code 
which should work under any Delphi version.

The component is fairly fast, since it maintains a list of pointers to
comma positions on read and write, avoiding repeated scans for commas or
unnecessary transfer of fields into temporary string variables.


4	File Distribution
-------------------------

4.1	The component

CSV.PAS		Source code of the TCSV component 16 bit and 32 bit compatible.
CSV.DCR		Component resource file contains a bitmap for the TCSV component.
CSVD1.DCR	Rename to CSV.DCR when using component with Delphi 1.

4.2	A demo project

CSVTEST.RES
CSVTEST.DPR	
MAIN.PAS
MAIN.DFM


5	Contact me
------------------

Bug reports appreciated.
No licence conditions.

TCSV written by 

Roger Lascelles
88 Lake Avenue
Ocean Grove 3227
Victoria
Australia

Email : rogerl@datafast.net.au

Alternative Email : Point your browser to www.topyachtsoftware.com and
email me care of any of the support email addresses.

Alternative Email : mccubb@ozonline.com.au



