Titus Information Systems CCommaFile Class

Titus Information Systems, Inc.

Standard Library
CCommaFile Class

This class is inherited from CFile and provides several additional member functions and variables that access comma-delimited or comma-separated-value text files. This base class must be inherited by a class to access a specific CSV file. The file is maintained as new-line-delimited rows of comma-delimited columns. The first column of each row contains the row key, which does not change once the row has been created. While new rows may be inserted anywhere in the file, the key for a new row will always be one more than the highest key of any current row. The inherited class must create arrays of variables for each column of data. These arrays should be public so they can easily be accessed and modified by the user interface maintenance function. It may even be expedient to specify elements of these arrays directly to the DDX_Text macros in the DoDataExchange() dialog box member function. The member functions and variables are as follows:

CCommaFile::CCommaFile(): This is the default constructor. It initializes the data members. If this constructor is used, one of the CCommaFile::Name() member functions must be called to set the file name before any file access may be attempted.
CCommaFile::CCommaFile(CString FileName): This constructor initializes the data members and sets the name of the data file as specified.
void CCommaFile::Delete(int Position): This member function deletes the row at the specified position. Note that the position in the file should be specified, not the key of the row.
DWORD CCommaFile::FindKey(DWORD Key): This member function returns the position of the row with the specified Key.
DWORD CCommaFile::GetKey(DWORD Index): This member function returns the Key for the row in the position specified by Index.
void CCommaFile::Insert(int Position): This member function inserts a new row at the specified position. Note that the position in the file should be specified, not the key of the row.
virtual void CCommaFile::LoadCount(): This member function must be overridden in the inherited class to set the sizes of the arrays that will contain the data from the file. The number of elements in each array should be set to the value of the CCommaFile::LineCount data member. This function will be called once when the CCommaFile::LoadFile() member function is called. Be sure to call the base class function so that the size of the key array will be properly set.
virtual BOOL CCommaFile::LoadData(): This member function must be overridden in the inherited class to set the value in each column array. It will be called once for every column in every row when the CCommaFile::LoadFile() member function is called. The column is determined by the value of the CCommaFile::FieldCount data member, and the row is determined by the value of the CCommaFile::LineIndex data member.
BOOL CCommaFile::LoadFile(): This member function opens the file specified in the constructor or one of the CCommaFile::Name() member functions. If the file is not successfully opened, the function returns FALSE. If successful, the function then loads the entire file into CCommaFile::Buffer and closes the file. It then determines the number of rows in the data file and calls the CCommaFile::LoadCount() member function so the inherited class may set the size of the storage arrays. It then scans CCommaFile::Buffer and calls CCommaFile:LoadData() once for every column of every row so the inherited class may store the data in the appropriate data arrays.
void CCommaFile::Name(CString FileName): This member function stores the name of the data file. Use this function with the default constructor. The file name is not validated by this function. Rather, the CCommaFile::LoadFile() and CCommaFile::SaveFile() functions will return FALSE if there are any access problems with the file name specified.
void CCommaFile::Name(CString HomeDirectory, CString FileName): This member function stores the name of the data file by concatenating HomeDirectory, a backslash, and Filename. If there are multiple files in the application database, it may be easier to store the HomeDirectory of the data base in a separate variable and call this member function for each of the files. Use this function with the default constructor. The file name is not validated by this function. Rather, the CCommaFile::LoadFile() and CCommaFile::SaveFile() functions will return FALSE if there are any access problems with the file name specified.
void CCommaFile::SaveData(CString Value): This member function appends the specified Value as a double-quoted string to the CCommaFile::LineData data member after a separating comma. If there are any double-quotes (") in Value, they will be duplicated. This function may be used in the overridden CCommaFile::SaveLine(). It should be called once for every column of string data in the row.
void CCommaFile::SaveData(DWORD Value): This member function appends the specified Value as a character string to the CCommaFile::LineData data member after a separating comma. This function may be used in the overridden CCommaFile::SaveLine(). It should be called once for every column of numeric data in the row.
BOOL CCommaFile::SaveFile(): This member function saves the data in memory to the file specified with the CCommaFile::Name() member function. Note that any existing data will be overwritten. The function clears CCommaFile::Buffer and calls CCommaFile::SaveLine() once for each row. Then the file is opened for output, CCommaFile::Buffer is written to the file, and the file is closed. If there are any access problems with the file, the function returns FALSE.
virtual void CCommaFile::SaveLine(): This member function must be overridden in the inherited class to create the CCommaFile::LineData data member for each row. The current row is determined from the value of the CCommaFile::LineIndex data member. After calling CCommaFile::SaveData() for each column in the row, call the base class function to append the key value, CCommaFile::LineData, and new-line separators to CCommaFile::Buffer.
CString CCommaFile::Buffer: This data member is used to store the complete contents of the data file in memory for analysis and modification by the base class and inherited member functions. While this variable may be modified directly by the inherited class, this is not recommended as other member functions may modify this variable and produce undesirable results.
CString CCommaFile::EmptyText: This data member is initialized by the base class to a null string. It may be modified or used by an inherited class. When the CCommaFile::Insert() member function is called, the string fields will be initialized to the value of this data member.
DWORD CCommaFile::FieldCount: This data member is used by the CCommaFile::LoadData() member functions of the base and inherited classes to determine the column presently being processed. While the value of this data member may be adjusted by the inherited class, doing so will normally produce undesirable results.
CString CCommaFile::FileName: This data member is used to store the path name of the data file. It may be accessed and/or modified as required. Also, the CCommaFile::Name() member functions may be used to initialize this data member.
DWORD CCommaFile::FileSize: This data member contains the size in bytes of the data file. It is equivalent to the CFile::GetLength() member function.
CDWordArray CCommaFile::Key: This data member contains the Keys for all the rows of data. This data member is maintained by the base class functions. While this data member may be adjusted by the inherited class, doing so will normally produce undesirable results.
DWORD CCommaFile::LineCount: This data member contains the number of rows of data in the file. This data member is maintained by the base class functions. While this data member may be adjusted by the inherited class, doing so will normally produce undesirable results.
CString CCommaFile::LineData: This data member is used by the CCommaFile::LoadData() and CCommaFile::SaveData() member functions. It contains the raw text of the current row of data. Use the appropriate member functions to maintain this data member. While this data member may be adjusted directly by the inherited class, doing so will normally produce undesirable results.
DWORD CCommaFile::LineIndex: This data member is used by the CCommaFile::LoadData() and CCommaFile::SaveData() member functions. It contains the position of the current row of data. This data member is maintained by the base class functions. While this data member may be adjusted by the inherited class, doing so will normally produce undesirable results.
DWORD CCommaFile::NextKey: This data member contains the next available key for a new row of data added to the file by the CCommaFile::Insert() member function. This data member is maintained by the base class functions. While this data member may be adjusted by the inherited class, doing so will normally produce undesirable results.
enum {CCommaFile::NOT_FOUND = 0xFFFFFFFF}: This enumerated value is returned by the CCommaFile::FindKey() and CCommaFile::GetKey() member functions when they are unable to satisfactorily complete the requested look up. Every time these functions are used, the results should be checked for failure using this enumerated value.