The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
vsDB-1.3.9
River stage zero No dependents
++
/ vsDB

NAME

vsDB - Simple interface to text-delimited data files

SYNOPSIS

        use vsDB;

        # create the object
        my (objDB) = new vsDB(filename=>'C:\\datafile.txt', delimiter=>'\t');

        # open the datafile     
        $objDB->Open;

        # add a new record
        $objDB->AddNew;         

        # update the first name field for the new record 
        $objDB->FieldValue('FirstName','Jason');

        # commit the changes to disk
        $objDB->Commit;

        # move the cursor to the beginning of the resultset
        $objDB->MoveFirst;

        # print all of the first name fields
        while (!$objDB->EOF) {
                print $objDB->FieldValue('FirstName');
                $objDB->MoveNext;
        }

        # close the datafile (optional)         
        $objDB->Close;

DESCRIPTION

vsDB provides a simple object-oriented interface for delimited text files. The object model is based off of Microsoft's ADO RecordSet object, so anyone familiar with this will find vsDB somewhat familiar. vsDB has been tested on Win32 and Linux.

OBJECT MODEL REFERENCE: PROPERTIES

AbsolutePosition([nNewPosition])

AbsolutePosition returns the current cursor position in the RecordSet. If [nNewPosition] is specified, then AbsolutePosition attempts to move the cursor to that position. If [nNewPosition] is out of range, AbsolutePosition will be set to the closest valid position (usually the last record)

ActivePage([nNewPage])

ActivePage returns the current "Page" in the RecordSet. If [nNewPage] is specified, then ActivePage attempts to move the cursor to the first record on the given page. If [nNewPage] is out of range, The cursor will be set to the closest valid position (usually the first record of the last page)

ActivePage is used along with PageSize. See PageSize for more information.

CR([strCR])

CR is a character or string that vsDB uses to replace a Carriage Return character that is inserted in the database. Default is "<CR>". The value is used only during storage in the file and is converted back into a Carriage Return when you request the field value. See also: LF

Delimiter([strNewDelimiter])

Delimiter returns the delimiter character that is used to separate fields in the datafile. If strNewDelimiter is specified, then the delimiter is changed.

Warning: changing the delimiter property after calling the Open method is a very bad thing to do! Your file may become corrupted.

EOF()

EOF (End Of File) indicates that there are no more records in the RecordSet. If you have applied a filter, this indicates when you have reached the end of the matching records. This property is commonly used to loop through a recordset, for example: while (!$objDB->EOF) { $objDB->MoveNext; }

Note: unlike the MS RecordSet object, FieldValue will not give an EOF error if you try to access a FieldValue when the RecordSet is at EOF. Instead is will continue to return values for the last record in the RecordSet

FieldValue(FieldName,[NewValue])

If [NewValue] is NOT specified, then FieldValue returns the value of the field specified (FieldName) for the record at the current cursor position.

If [NewValue] is specified, then the value of the field specified (FieldName) for the record at the current cursor position is updated to [NewValue] and 1 is returned.

Note: any changes you make to the data will not be saved to disk until you call the Commit method.

FieldNames()

FieldNames returns an array containing all of the field names in the datafile. For example:

        my (@fieldNames) = $objDB->FieldNames;

File([strNewFilePath])

File specifies the full path to the datafile. This can be specified when the object is created or anytime before calling the Open method. Once the file has been opened the RecordSet will not change if you change the File property. However, if you change the File property and then call the Commit method, this will save the current RecordSet to the new filepath. In other words, it will copy the original file.

Warning: Changing the File property then calling Open again may produce unexpected results. If you need to access another datafile, it is recommended that you create another vsDB object instead.

ID()

Returns module identification

LastError()

When a non-fatal error has occured, the LastError property may contain information decribing the error. Most methods will return 1 or 0 to indicate success or failure. You do not need to check these return values, but should in cases where you suspect the method could fail.

LF([strLF])

LF is a character or string that vsDB uses to replace a Line Feed character that is inserted in the database. Default is "<LF>". The value is used only during storage in the file and is converted back into a Line Feed when you request the field value. See also: CR

Max(fieldName, [alpha])

Max returns the maximum value for he specified fieldName. alpha is an optional value that is set to 1 or 0 to indicate alphabetical characters. By default, alpha is set to 0, indicating that the field is numeric.

Warning: if your field contains non-numeric values, you must set alpha=1 or Max will produce a type-mismatch error.

Min(fieldName, [alpha])

Min returns the minimum value for he specified fieldName. alpha is an optional value that is set to 1 or 0 to indicate alphabetical characters. By default, alpha is set to 0, indicating that the field is numeric.

Warning: if your field contains non-numeric values, you must set alpha=1 or Min will produce a type-mismatch error.

PageCount()

PageCount returns the number of pages in the RecordSet. This is essentially the RecordCount devided by the PageSize. If you have applied a filter, the PageCount will indicate only matching records.

PageSize([nNewSize])

PageSize returns the current page size. If [nNewSize] is specified, then the PageSize is set to the new value. PageSize is used along with ActivePage to simplify displaying a subset of the total records. For example, the file contains 1,000 rows, but you want to display them to the user only 10 at a time. The PageSize is set to 10 and you can navigate through the results by changing the ActivePage.

RecordCount()

Returns the number of records in the RecordSet. If you have applied a filter, RecordCount will indicate the number of matching records.

Row()

Row returns an array containing all of the values of the current record. For example:

        my (@row) = $objDB->Row;

Version()

Returns current version

xml([strRootName] [,strElementName])

Returns current recordset as xml. strRootName and strElementName are optional. Default values are "vsDB" and "Record"

OBJECT MODEL REFERENCE: METHODS

AddNew()

Adds a new record to the RecordSet and moves the cursor to this new record. The default values for all fields is an empty string. After you add a new record, you will want to change the FieldValues as needed.

If you are using one of the fields as a primary key, you can use the Max property to obtain the highest ID number.

Note: any changes you make to the data will not be saved to disk until you call the Commit method.

AddNewField(strFieldName [,strDefaultValue])

Adds a new field to the RecordSet. strFieldName is the name of the new field. The new field will be added to all records and set to strDefaultValue. If strDefaultValue is not specified, then the field will be empty.

Note: any changes you make to the data will not be saved to disk until you call the Commit method.

Close()

In theory this would close the file, however vsDB does not keep the file handle open. Currently this method simply marks the object as closed. This method is also called automatically when the object is destroyed.

Although it is not necessary to call this method, it is recommended that you do in case vsDB is later modified to keep the file handle open. This might be useful for a persistent connection to the file...?

Commit([blnUseFLock])

Commit writes the current RecordSet in memory to the filepath specified by the File property. This method should be called any time there have been data modifications. blnUseFLock is an optional argument that should be 1 if flock should be used while writing to the file.

Commit re-opens the datafile with the least amount of privledges required. If you have not made any changes to the RecordSet, calling Close will not access the datafile at all. If you have only added new records, Commit will open the datafile for appending and append the new record. If you have modified existing records, the file will be opening for writing and the entire file will be updated.

Delete()

Deletes the current record in the RecordSet.

Note: any changes you make to the data will not be saved to disk until you call the Commit method.

Filter(strFieldName,strOperator,strCriteria)

Filter provides a way to either search the RecordSet or to get a specific record based on a primary key field. strFieldName indicates the field that you want to filter. strOperator is one of the following "eq", "ne", "like", "<" or ">" to indicate how the field is to be compared. strCriteria indicates the search pattern that you wish to find.

You can apply the Filter method more than once to further filter out records. The filters are applied as "AND." Currently there is no support for "OR" filtering.

If you are using a primary key field, you can use the Filter method to locate the row that you want. For example:

        $objDB->Filter("ID","eq","25")

The Filter method moves the cursor to the first matching record in the recordset as well as updates RecordCount and PageCount accordingly.

Note: calling Sort will remove any filters that you have applied. Call Sort first if you need to sort and filter the results.

MoveNext()

Advances the cursor to the next row in the RecordSet. In other words, it "moves" to the next record.

MovePrevious()

Moves the cursor to the previous row in the RecordSet. In other words, it "moves" to the previous record.

MoveFirst()

Moves the cursor to the first row in the RecordSet.

MoveLast()

Moves the cursor to the last row in the RecordSet.

Open()

Opens the datafile for reading and populates the RecordSet bases on the data in the file. The datafile handle is actually closed immediately after reading the file, however the RecordSet is stored in memory. (To sync the datafile up with the RecordSet, refer to the Commit method.)

Warning: calling Open more than once may cause unexpected results.

RemoveFilter()

RemoveFilter removes any filtering that you have done using the Filter method and moves the cursor to the first row in the RecordSet.

Sort(strFieldName [,Descending])

Sort sorts the RecordSet by the strFieldName. You can sort by multiple fields by calling the Sort method more than once with a different fieldname each time.

Descending should be 1 if you want the sort to be in descending order instead of the default ascending order.

Note: Calling Sort will remove any Filters that you have applied. If you want to sort and filter, then call Sort first, then Filter.

Warning: If you call the Commit method after sorting, the records will be saved to the datafile in the order in which they are sorted. This may be desirable if you always sort the same way, but proceed with caution.

VERSION HISTORY

        1.3.9: don't allow FieldValue or Delete if EOF is true
        1.3.8: added UseFLock argument to Commit method
        1.3.7: Updated error messages
        1.3.6: AddNew now moves to the last record properly
        1.3.5: fixed record jumbling bug in xml property
        1.3.4: filter "like" option made case-insensitive, updated ActivePage
        1.3.3: fixed EOF not being set properly when filtering
        1.3.2: added xml Property
        1.3.1: added Desc option to sort routine
        1.3.0: added AddNewField
        1.2.7: CR and LF properties added.  fixed bug with line breaks
               in the data.  Added filename security check to ->Open
        1.2.6: resolved filter + sort problem.  cleaned up documentation
        1.2.5: added destructer, removed file locking code
        1.2.4: fixed PageCount and RecordCount bug when using filter
        1.2.3: optimized AddNew, fixed null field bug in FieldValue
        1.2.2: optimized file access, added more error checking
        1.2.1: Fixed ActivePage/Filter bug filtering out 1st record
        1.2.0: Added ActivePage, PageSize, PageCount properties
        1.1.4: Updated Max property to deal with numbers
        1.1.3: Added Filter method
        1.1.2: Added Sort, Min, Max methods
        1.0.1: Original Release

KNOWN ISSUES & LIMITATIONS

vsDB loads the entire datafile into an array which could cause performance problems if your datafile grows large. (largest test file was 17,000 records)

ActivePage and possibly other page-related properties may return unexpected values when used in combination with filtering.

AUTHOR

Jason M. Hinkle

COPYRIGHT

Copyright (c) 2001 Jason M. Hinkle. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.