Introduction:

The DbLib library contains functions that manipulate a pdb file or the directory contents of internal memory or an external memory card. Most of the functions work at the database or directory level, not on specific records in a database.

In order to use the DbLib Library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the program's Startup code so that the functions will be available throughout the program. The LoadLibrary statement has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions. The examples in this document use "Db" for this reference name. Example:

Program's Startup code:

	Sub main()
	    LoadLibrary "DbLib", "Db"
	End Sub

Also, in order to use the DbLib Library, the DbLib.INF file must be present in your "nsbasic\lib" directory and the DbLib.prc file should be added to your project as a resource, with the type changed from the default of DBIM to libr (must be all lowercase).

Except for the functions that return version numbers, all the parameter and return data types are either "Integer" or "String". Version numbers are returned as a "Double".

Note that in this TechNote, files are referred to as databases. There is no difference in meaning.

DbLib Function Reference:

Version Information

The version information functions provide information about the version of the DbLib Library.

Version

	version = Db.Version()

Returns the version number of the DbLib Library.

Returns:

	version as Double

Example:

	Dim version as Double

	version = Db.Version()

CompileInfo

	compileDateTime = Db.CompileInfo()

Returns the date and time that the DbLib was compiled.

Returns:

	compileDateTime as String

Example:

	Dim compileDateTime as String

	compileDateTime = Db.CompileInfo()

Register

	Db.Register part1, part2

Validates the registration code.

Parameters:

	part1 as String
	       Registration Code part one (case sensitive).

	part2 as String
	       Registration Code part two (case sensitive).

Example:

	Dim part1 as String
	Dim part2 as String

	Db.Register part1, part2

This function is deprecated and no longer required, though it is included for backward compatibility with previous releases.

Database Level Functions

The database level functions operate on the entire database as a whole, as opposed to record level access.

KeySort

	err = Db.KeySort(dbName, keyType)

Sorts a database into key order.

Parameters:

	dbName as String
	       Name of database to be sorted.
	keyType as String
	       Type of key field.  Must be one of the following values,
	       but may be given in either upper or lowercase:
	         B = Byte, a 8-bit character value
	         D = Date, a 8-byte float in NSB's format
	         F = Float, a 8-byte float
	         H = sHort, a 16-bit short integer
	         I = Integer, a 32-bit long integer
	         N = siNgle, a 4-byte float
	         S = String, a null terminated string
	         T = Time, a 8-byte float in NSB's format

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim keyType as String

	err = Db.KeySort(dbName, keyType)

The database may be open or closed, but must exist on card 0.

KeyInsSort

	err = Db.KeyInsSort(dbName, keyType)

Sorts a database into key order.

Parameters:

	dbName as String
	       Name of database to be sorted.
	keyType as String
	       Type of key field.  Must be one of the following values,
	       but may be given in either upper or lowercase:
	         B = Byte, a 8-bit character value
	         D = Date, a 8-byte float in NSB's format
	         F = Float, a 8-byte float
	         H = sHort, a 16-bit short integer
	         I = Integer, a 32-bit long integer
	         N = siNgle, a 4-byte float
	         S = String, a null terminated string
	         T = Time, a 8-byte float in NSB's format

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim keyType as String

	err = Db.KeyInsSort(dbName, keyType)

The database may be open or closed, but must exist on card 0.

LoadDirToDB

	err = Db.LoadDirToDB(dbName, Dir)

Loads a VFS directory contents into a database and sorts it. Each database record will consist of 6 string fields: Filename Type (Vol, Dir, File, or Link) Unused (empty string) File creation date and time File modification date and time File last accessed date and time

Parameters:

	dbName as String
	       Name of database to contain directory entries.
	Dir as String
	       Full path to desired directory.

Returns:

	err as Integer
	       Error code indicator:
	           0 = No error
	           1 = VFS not supported
	           2 = No card detected
	       other = Another error occured.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim Dir as String

	err = Db.LoadDirToDB(dbName, Dir)

The database may be opened or closed. If it does not exist, it will be created with the type 'data' and a creator ID matching the current application.

LoadDbListToDB

	err = Db.LoadDbListToDB(dbName, dbType, dbCreator, dbLike)

Loads a database with a list of databases in internal memory limited by database type, creator ID, and / or filename pattern. Each database record will consist of 6 string fields: Database name Type (eg data, appl, libr, ...) Creator ID DB creation date and time DB modification date and time or "Never" DB backup date and time or "Never"

Parameters:

	dbName as String
	       Name of database to contain directory entries.
	dbType as String
	       String containing type of databases to include, or "" for all
	dbCreator as String
	       String containing creator ID of database to include, or "" for all
	dbLike as String
	       String containing name pattern to match, or "" for all names
	       
	           Pattern matching special characters:
	       
	           ? - any single character
	           * - zero or more characters
	           # - any single digit (0-9)
	           [list] - any single character in list
	           [!list] - any single character not in list
	       
	               "list" matches a group of characters in pattern to a single
	               character in string and can contain almost all available
	               characters, including digits.
	       
	               Use a hyphen (-) in "list" to create a range of characters to
	               match a character in string; for example [A-D] matches A,B,C,
	               or D in that character position in string.
	       
	               Multiple ranges of characters can be included in "list"
	               without the use of a delimiter.  For example:  [A-CX-Z]
	       
	               Ranges of characters must appear in sort order; example: [c-k]
	       
	               Use an exclamation mark before a character or range of
	               characters in "list" to match all but that character.  For
	               example, [!A-G] matches all characters except those from A to G.
	       
	               To use any special character as a matching character, enclose it
	               in brackets.  For example:  [?]

Returns:

	err as Integer
	       Error code indicator:
	           0 = No error
	       other = Som error occured.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbType as String
	Dim dbCreator as String
	Dim dbLike as String

	err = Db.LoadDbListToDB(dbName, dbType, dbCreator, dbLike)

The database may be opened or closed. If it does not exist, it will be created with the type 'data' and a creator ID matching the current application.

BeamDatabase

	err = Db.BeamDatabase(dbName, dbDesc)

Beams a database to another device via IR.

Parameters:

	dbName as String
	       Name of database to be beamed.
	dbDesc as String
	       Description to be displayed during beaming.  If an empty
	       string is supplied, the database name is used.

Returns:

	err as Integer
	       Completion status.  A (perhaps) partial list of codes possible:
	          0 = Successful
	        519 = Database not found
	       5379 = Canceled by sender, or beam interrupted
	       5380 = Could not find receiving computer
	       5388 = Beam disconnected
	       5392 = Receiver currently busy and cannot receive now (this can
	              happen if the sender starts a second beam prior to the
	              receiver approving or declining the first beam)
	       5394 = Not enough power to perform requested operation

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbDesc as String

	err = Db.BeamDatabase(dbName, dbDesc)

Only one database at a time may be sent with this method. The receiver does not need any special application, and in fact does not even need to be at the application launcher provided the database to be beamed is not already open on the receiver. That is, they cannot receive a copy of the program they are currently executing, nor any database it happens to have open at the time.

SendDatabase

	err = Db.SendDatabase(dbName, dbDesc, method)

Sends a database to another device using Bluetooth, SMS, etc.

Parameters:

	dbName as String
	       Name of database to be sent
	dbDesc as String
	       Description to be displayed during exchange.  If an empty
	       string is supplied, the database name is used.
	method as String
	       Method to send database.  Should be one of the following:
	         empty string = Prompt for method, based on device capabilities.
	         BT or bt	 = Send via Bluetooth
	         SMS or sms   = Send via SMS

Returns:

	err as Integer
	       Completion status.  A partial list of codes possible:
	           0 = Successful
	         519 = Database not found
	        5377 = Memory error
	        5379 = Canceled by sender, or send was interrupted
	        5380 = Could not find receiving device
	        5383 = Operation not allowed
	        5388 = Send disconnected
	        5392 = Receiver currently busy and cannot receive now
	        5394 = Not enough power to perform requested operation
	       12583 = No bluetooth devices found

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbDesc as String
	Dim method as String

	err = Db.SendDatabase(dbName, dbDesc, method)

The method(s) supported depend on the capability of the device. Typically you would leave the third argument empty and let the OS decide. If the device only has one method available it will be used automatically. If more than one is possible, a list will be presented and the user may select their preference. If no methods are available, a result of 5383 is returned.

CopyDatabase

	err = Db.CopyDatabase(dbName, dbNewName, PreserveDates)

Creates a copy of a database with a new name.

Parameters:

	dbName as String
	       Name of database to be copied.  It is left unchanged.
	dbNewName as String
	       New name of database copy.
	PreserveDates as Integer
	       0 to assign current dates; 1 = preserve original dates

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbNewName as String
	Dim PreserveDates as Integer

	err = Db.CopyDatabase(dbName, dbNewName, PreserveDates)

Destination database must not exist yet. The destination will be given the same creator ID and type as the source.

MoveAllRecords

	err = Db.MoveAllRecords(dbName, dbNewName)

Moves all records from one database to the end of another database.

Parameters:

	dbName as String
	       Name of database with records to be moved.  Upon completion, the
	       database will still exist but will be empty.
	dbNewName as String
	       Name of database to receive the records.  This database must
	       exist.  Records are added to the end of existing records.

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbNewName as String

	err = Db.MoveAllRecords(dbName, dbNewName)

Both databases must exist, and neither can be open at the time this routine is called.

After completion, you may want to delete the original database, sort the receiving database, or whatever else is appropriate for the purpose records are being moved.

One use for this function is to merge records to create a larger database. For example, two databases under 64K may be stored in application resources when the program is compiled, then each extracted via NSB's DbCreateDatabaseFromResource() function. The second may then have the records moved to the end of the first, creating a single database over 64K. Another possibility may be to create a database with a subset of records meeting some criteria, beam it to another device, and have that device merge it with other records already on the device in another database.

DeleteDatabase

	err = Db.DeleteDatabase(dbName)

Deletes a database from internal memory.

Parameter:

	dbName as String
	       Name of database to be deleted

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String

	err = Db.DeleteDatabase(dbName)

An open database can not be deleted.

ClearDatabase

	err = Db.ClearDatabase(dbName)

Removes all records from a database, leaving it empty.

Parameter:

	dbName as String
	       Name of database to be cleared

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String

	err = Db.ClearDatabase(dbName)

The database may be open or closed, but must exist on card 0.

RenameDatabase

	err = Db.RenameDatabase(dbName, dbNewName)

Renames a database in internal memory.

Parameters:

	dbName as String
	       Name of database to be renamed.
	dbNewName as String
	       New name of the database.

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbNewName as String

	err = Db.RenameDatabase(dbName, dbNewName)

The new name must not already be used on some other database.

Database Info Functions

The database information functions provide or alter information on a specific database, as opposed to a specific record.

GetDBAttribute

	result = Db.GetDBAttribute(dbName, attrMask)

Retrieve specific attribute bit(s) for a database. Generally used to obtain a single attribute at a time, or all of them collectively.

Parameters:

	dbName as String
	       Name of database to be have attributes return.
	attrMask as Integer
	       Combination of attribute bits to retrieve.  Add together the
	       values below for each attribute to be returned.
	       	0	Obtain all attributes as a composite value
	          	1	Resource database
	       	2	Read only database
	       	4	AppInfo block is dirty
	       	8	Backup to desktop using system conduit
	          16	OK to install newer even while DB is open
	          32	Force reset after installing this database
	          64	Copy Prevention (disallow beaming from app launcher)
	         128	File Stream (cannot be used as general database)
	         256	Hidden (disallow app display by launcher, or record count)
	         512	Launchable Data (not applicable)
	        1024	Recyclable (on OS4+, database will get deleted by OS)
	        2048	Bundle (on OS4+, app launcher will beam with application)
	       32768	Open (database now open, or previously not closed properly)

Returns:

	result as Integer
	       When the attribute mask (parameter 2) is zero, the complete set of
	       attributes for the database is returned.  This is useful for saving
	       and restoring later, or applying to a different database.  When the
	       attribute mask is not zero, only the values one or zero can be
	       returned.  The value one inidicates the each attribute bit requested
	       is on.  If any of the attribute bit(s) requested are off, a zero
	       value is returned.

Example:

	Dim result as Integer
	Dim dbName as String
	Dim attrMask as Integer

	result = Db.GetDBAttribute(dbName, attrMask)

You may combine more than one attribute value if all you care about is whether all the specified attributes are set, and not whether any given one is set. For example, 320 will tell you if the database is BOTH copy protected and hidden, but not if it is copy protected OR hidden.

Some attributes only have meaning on OS4 or later.

SetDBAttribute

	err = Db.SetDBAttribute(dbName, attrMask, newVal)

Sets or clears specific attribute bit(s) for a database, or all atributes at once.

Parameters:

	dbName as String
	       Name of database to be have attributes changed.
	attrMask as Integer
	       Combination of attribute bits to change.  Add together the values
	       below for each attribute to be changed, or specify 0 for all.
	       	0	Change all attributes
	          	1	Resource database (never change this one)
	       	2	Read only database
	       	4	AppInfo block is dirty
	       	8	Backup to desktop using system conduit
	          16	OK to install newer even while DB is open (rare!)
	          32	Force reset after installing this database
	          64	Copy Prevention (disallow beaming from app launcher)
	         128	File Stream (cannot be used as general database)
	         256	Hidden (disallow app display by launcher, or record count)
	         512	Launchable Data (not applicable to NS Basic)
	        1024	Recyclable (on OS4+, database will get deleted by OS)
	        2048	Bundle (on OS4+, app launcher will beam with application)
	       32768	Open (database now open, or previously not closed properly)
	       
	       Values can be combined.  For example, 8 + 256 = 264 so 264 means
	       to change both the backup and hidden attribute bits.
	newVal as Integer
	       New value for attribute.  When the attribute mask (above) is zero,
	       this value represents the composite attribute value and completely
	       replaces the existing attributs.  When the attribute mask (above)
	       is not zero, the mask identifies which attributes to change and
	       this value should be 1 to set the attribute(s) on, or 0 to clear
	       the specified attribute(s).

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim attrMask as Integer
	Dim newVal as Integer

	err = Db.SetDBAttribute(dbName, attrMask, newVal)

The resource vs data attribute bit is ignored and not modified by this call because changing it with existing databases causes fatal errors and memory corruption, potentially leading to a hard reset as the only recourse. Some attributes only have meaning on OS4 or later.

GetDBType

	dbType = Db.GetDBType(dbName)

Retrieve the "type" of a database.

Parameter:

	dbName as String
	       Name of database to check.

Returns:

	dbType as String
	       When an empty string if the database does not exist, or the type
	       of the database if it does exist.  Example types are "appl", "libr",
	       "data", etc.

Example:

	Dim dbType as String
	Dim dbName as String

	dbType = Db.GetDBType(dbName)

Types under are case sensitive, 4-character values typically comprised of letters or digits but which may include other symbols as well.

SetDBType

	err = Db.SetDBType(dbName, dbType)

Changes the "type" of a database.

Parameters:

	dbName as String
	       Name of database to alter.
	dbType as String
	       New database type.

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbType as String

	err = Db.SetDBType(dbName, dbType)

Types under Palm OS are case sensitive, 4-character values typically comprised of letters or digits but which may include other symbols as well.

GetDBCreator

	dbCreator = Db.GetDBCreator(dbName)

Retrieve the "creator ID" of a database.

Parameter:

	dbName as String
	       Name of database to check.

Returns:

	dbCreator as String
	       When an empty string if the database does not exist, or the creator
	       ID of the database if it does exist.

Example:

	Dim dbCreator as String
	Dim dbName as String

	dbCreator = Db.GetDBCreator(dbName)

Creator IDs under are case sensitive, 4-character values typically comprised of letters or digits but which may include other symbols as well.

SetDBCreator

	err = Db.SetDBCreator(dbName, dbCreator)

Changes the "creator ID" of a database.

Parameters:

	dbName as String
	       Name of database to alter.
	dbCreator as String
	       New database creator ID.

Returns:

	err as Integer
	       0 if successful, 519 if not found, etc.

Example:

	Dim err as Integer
	Dim dbName as String
	Dim dbCreator as String

	err = Db.SetDBCreator(dbName, dbCreator)

Creator IDs under are case sensitive, 4-character values typically comprised of letters or digits but which may include other symbols as well in the range of ASCII 33 to 127.

Open Database Functions

The FindOpenDB() function is a prerequisite to using either the record key functions or record level functions described below. It's purpose is to allow the library to interoperate with NSB by sharing a database already opened with NSB's DbOpen() statement. This allows it to circumvent the limitation of only permitting a database to be opened once at a time for update.

FindOpenDB

	dbRef = Db.FindOpenDB(dbName)

Find the reference number of a database already open. Typically, this will be due to use of DbOpen() in the underlying NS Basic application. This reference number is required for the other record level functions in this library. The reference number will remain valid until the database is closed (e.g., DbClose).

Parameter:

	dbName as String
	       Name of database previously opened.

Returns:

	dbRef as Integer
	       Reference number of an open database; which will be a positive
	       number.  A negative number indicates an error condition, such as
	       the value -519 indicating a database was not found.

Example:

	Dim dbRef as Integer
	Dim dbName as String

	dbRef = Db.FindOpenDB(dbName)

Record Key Functions

This group of functions allows you to find the record number which contains a given key value in a database, or the position where the would occur if it were present. All the functions are identical except for the data type of the key for the database. Use the proper function for the type of key in the database, for example a string.

The record number can then be used for additional operations, such as NSB's DbPostion() followed by DbGet() or DbPut(), or for other operations in this library as described later.

Each of the following record key functions, Rrn...Key(), returns a record number which may be positive, negative, or zero as follows: positive number = Key match found at specified record (comparable to DbRead() result code of 0) negative number = No exact match, absolute value has next key (comparable to DbRead() result code of 2) zero = Key is higher than any if database, or error (comparable to DbRead() result code of 1)

To find the record number of an existing key, treat any positive number as valid and a zero or negative number as an error. To find the record number of a key which is greater than or equal to the specified key, treat only zero as an error and use the absolute value of the record number returned as the desired record. That is use Abs( rrn ) as the desired record number.

RrnStringKey

	dbRrn = Db.RrnStringKey(dbRef, dbKey)

Find the relative record number for a string key data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as String
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as String

	dbRrn = Db.RrnStringKey(dbRef, dbKey)

See explanation under Record Key Functions above.

RrnByteKey

	dbRrn = Db.RrnByteKey(dbRef, dbKey)

Find the relative record number for a byte key data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as Integer
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as Integer

	dbRrn = Db.RrnByteKey(dbRef, dbKey)

See explanation under Record Key Functions above.

RrnShortKey

	dbRrn = Db.RrnShortKey(dbRef, dbKey)

Find the relative record number for a short key (16-bit) data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as Integer
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as Integer

	dbRrn = Db.RrnShortKey(dbRef, dbKey)

See explanation under Record Key Functions above.

RrnIntegerKey

	dbRrn = Db.RrnIntegerKey(dbRef, dbKey)

Find the relative record number for a integer key (32-bit) data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as Integer
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as Integer

	dbRrn = Db.RrnIntegerKey(dbRef, dbKey)

See explanation under Record Key Functions above.

RrnSingleKey

	dbRrn = Db.RrnSingleKey(dbRef, dbKey)

Find the relative record number for a single float key (4-byte) data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as Integer
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as Integer

	dbRrn = Db.RrnSingleKey(dbRef, dbKey)

See explanation under Record Key Functions above.

RrnDoubleKey

	dbRrn = Db.RrnDoubleKey(dbRef, dbKey)

Find the relative record number for a double float (8-byte) key data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as Double
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as Double

	dbRrn = Db.RrnDoubleKey(dbRef, dbKey)

See explanation under Record Key Functions above.

RrnDateKey

	dbRrn = Db.RrnDateKey(dbRef, dbKey)

Find the relative record number for a date key data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as Double
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as Double

	dbRrn = Db.RrnDateKey(dbRef, dbKey)

See explanation under Record Key Functions above.

RrnTimeKey

	dbRrn = Db.RrnTimeKey(dbRef, dbKey)

Find the relative record number for a time key data type.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbKey as Double
	       Key value to search for.  Must be a string.

Returns:

	dbRrn as Integer
	       Record number as described above.

Example:

	Dim dbRrn as Integer
	Dim dbRef as Integer
	Dim dbKey as Double

	dbRrn = Db.RrnTimeKey(dbRef, dbKey)

See explanation under Record Key Functions above.

Record Level Functions

The record level functions allow you to manipulate a complete record in a database. They do not work at the field level. In general, these routines will be used in combination with field aware database operations such as NSB's DbGet() or DbPut(), or with another library which provides field level access to data.

To use any of the record level functions, the database should first be opened in NS Basic using the standard DbOpen() operation. This allows NSB to open the database in update mode so that changes to the database will be allowed from your project using regular DbXxx() operations. After the DB has been opened in NSB, use this library's FindOpenDB() call to obtain a "reference" to the DB. The value thus obtained is required for the other record level functions in this library so that they can share the open already performed by NS Basic's DbOpen() operation. This method is utilized because a database can only be opened for update by one process at a time. To get around that limitation and allow updates from both the application itself and this library, this library locates and then "references" the open previously performed using DbOpen().

ArchiveRecord

	result = Db.ArchiveRecord(dbRef, dbRrn)

Marks a record as archived for the next sync by setting the delete bit but leaving the data intact. Used by some conduits to save the record data on the PC before permanently removing the record entry and data from the device database. Contrast with DeleteRecord() and RemoveRecord() below.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to archive.  See Rrn...Key functions above.

Returns:

	result as Integer
	       Result codes as documented under NSB's DbOpen(), e.g. 0 is success.

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.ArchiveRecord(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code.

DeleteRecord

	result = Db.DeleteRecord(dbRef, dbRrn)

Marks a record as deleted for the next sync by setting the delete bit and removes the record data. Used by some conduits to inform the PC a record has been deleted on the device. The conduit then removes the record on the PC, and removes the database header entry on the device. Note that this is NOT the same as NSB's DbDelete() operation, which is similar to RemoveRecord() below. Contrast with DeleteRecord() above and RemoveRecord() below.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to delete.  See Rrn...Key functions above.

Returns:

	result as Integer
	       Result codes as documented under NSB's DbOpen(), e.g. 0 is success.

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.DeleteRecord(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code.

RemoveRecord

	result = Db.RemoveRecord(dbRef, dbRrn)

Removes a record from a database, including the data and the header entry for the record. Typically used when a conduit does not need to archive the record contents, or be informed the record has been deleted on the device. RemoveRecord() is similar to NSB's DbDelete(), except RemoveRecord() takes a record number and DbDelete() takes a record key. Contrast with ArchiveRecord() and DeleteRecord() above.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to remove.  See Rrn...Key functions above.

Returns:

	result as Integer
	       Result codes as documented under NSB's DbOpen(), e.g. 0 is success.

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.RemoveRecord(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code.

NewRecord

	at = Db.NewRecord(dbRef, dbRrn)

Creates a new record in a database where requested, and returns the record number of the location assigned. The new record consists of only a single null character. Operations like NSB's DbPosition() and DbPut() may be used to add data to the record.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number desired.  See also Rrn...Key functions above.  If
	       less than the existing record count, the remaining records are
	       all shuffled down one position.  Pass 65535 to add the record to
	       the end of the database.

Returns:

	at as Integer
	       Record number added.  Primarily useful when parameter 2 is
	       given as 65535 to add to the end of the database.  A negative
	       number indicates an error condition.

Example:

	Dim at as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	at = Db.NewRecord(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.

MoveRecord

	result = Db.MoveRecord(dbRef, dbFrom, dbTo)

Moves a record from one position to another.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbFrom as Integer
	       Record number to be moved.  See also Rrn...Key functions above.
	dbTo as Integer
	       Where to move the record.

Returns:

	result as Integer
	       0 if successful or an error code if it fails (see NSB DbOpen).

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbFrom as Integer
	Dim dbTo as Integer

	result = Db.MoveRecord(dbRef, dbFrom, dbTo)

Inserts the record at the TO location (parameter 3), and moves any remaining records down. The TO location may be up to one greater than the current number of records in the database, which moves the record to the end of the database. In cases where TO is greater than FROM, the new record number of the record becomes TO - 1 after the move is complete.

IsRecordBusy

	result = Db.IsRecordBusy(dbRef, dbRrn)

Determines whether a given record in a database is "busy" and thus not available for update. In normal operations, this should not return a 1 (true) value.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to test.  See Rrn...Key functions above.

Returns:

	result as Integer
	       0 if record is not busy; 1 if record is busy; or an error number.

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.IsRecordBusy(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.

IsRecordDeleted

	result = Db.IsRecordDeleted(dbRef, dbRrn)

Determines whether a given record in a database is marked as deleted. Contrast ArchiveRecord(), DeleteRecord(), and RemoveRecord() for information on how a record may be deleted yet still have a valid record number within the database.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to test.  See Rrn...Key functions above.

Returns:

	result as Integer
	       0 if record is not deleted; 1 if record is deleted; or an error code.

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.IsRecordDeleted(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.

IsRecordDirty

	result = Db.IsRecordDirty(dbRef, dbRrn)

Determines whether a given record in a database is "dirty", that is whether the record has changed since the last sync backup.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to test.  See Rrn...Key functions above.

Returns:

	result as Integer
	       0 if not dirty; 1 if record is dirty; or an error code.

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.IsRecordDirty(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.

IsRecordPrivate

	result = Db.IsRecordPrivate(dbRef, dbRrn)

Determines whether a given record in a database is "private" or "secret".

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to test.  See Rrn...Key functions above.

Returns:

	result as Integer
	       0 if not private; 1 if record is private; or an error code.

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.IsRecordPrivate(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.

RecordUniqueID

	result = Db.RecordUniqueID(dbRef, dbRrn)

Returns the unique ID for a given record in a database. Each record is assigned an arbitrary number useful to conduits to synchronize data between the desktop and the device. The number is generally unique within the database, but is not guaranteed to necessarily be so. The number should be considered artitrarily assigned, but a given record will retain the same unique ID value even as the data contents are changed.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to test.  See Rrn...Key functions above.

Returns:

	result as Integer
	       1 - 16777215 if no error occurs; negative numbers are errors

Example:

	Dim result as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	result = Db.RecordUniqueID(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.

RecordCategoryID

	category = Db.RecordCategoryID(dbRef, dbRrn)

Returns the category number for a given record in a database. The category number is always between 0 and 15, where 0 typically means "unfiled". The names of values 1 - 15 may vary with the database.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to test.  See Rrn...Key functions above.

Returns:

	category as Integer
	       Category ID as a value from 0 - 15.  Negative numbers are errors.

Example:

	Dim category as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	category = Db.RecordCategoryID(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.

RecordSize

	size = Db.RecordSize(dbRef, dbRrn)

Returns the length in bytes of a given record in a database.

Parameters:

	dbRef as Integer
	       Reference number of an open database.  See FindOpenDB() above.
	dbRrn as Integer
	       Record number to test.  See Rrn...Key functions above.

Returns:

	size as Integer
	       0 - 65535 if no error occurs; negative numbers are errors

Example:

	Dim size as Integer
	Dim dbRef as Integer
	Dim dbRrn as Integer

	size = Db.RecordSize(dbRef, dbRrn)

Some OS releases may display a fatal error message instead of returning an error code if invalid input is detected.