Items vsDB

vsDB

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.

PROPERTIES

Property	Description
`AbsolutePosition([nNewPosition])`	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])`	AReturns 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])`	A character or string that vsDB uses to replace a Carriage Return character that is inserted in the database. Default is "". 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()`	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 occurred, the `LastError` property may contain information describing 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 "". 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()`	Returns the number of pages in the `RecordSet`. This is essentially the `RecordCount` divided by the `PageSize`. If you have applied a filter, the `PageCount` will indicate only matching records.
`PageSize([nNewSize])`	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"

METHODS

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

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.

There is a know issue with numeric sorting to fix this, change lines starting with 615 from

if ($desc) {
            return $bVals[$fieldNumber] cmp $aVals[$fieldNumber];
        }
        else {
            return $aVals[$fieldNumber] cmp $bVals[$fieldNumber];
        }

TO

if ($sortMode eq "1") {
		    # alpha descending
			return lc($bVals[$fieldNumber]) cmp lc($aVals[$fieldNumber]);
		} elsif ($sortMode eq "2") {
		    # numeric ascending
			return $bVals[$fieldNumber] < $aVals[$fieldNumber];
		} elsif ($sortMode eq "3") {
		    # numeric descending
			return $bVals[$fieldNumber] > $aVals[$fieldNumber];
		} else {
		    # alpha ascending
			return lc($aVals[$fieldNumber]) cmp lc($bVals[$fieldNumber]); 
		}

AUTHOR

Jason M. Hinkle

Main page

Provide feedback

Saved searches

Use saved searches to filter your results more quickly