/// <summary>
/// Creates a new Cursor in a Transaction
/// </summary>
/// <remarks>
/// This method wraps the native ups_cursor_create function.
/// <br />
/// Creates a new Database Cursor. Cursors can be used to traverse
/// the Database from start to end or vice versa. Cursors can also
/// be used to insert, delete or search Database items.
///
/// A newly created Cursor does not point to any item in the Database.
///
/// The application should close all Database Cursors before closing
/// the Database.
/// </remarks>
/// <param name="db">The Database object</param>
/// <param name="txn">The optional Transaction</param>
/// <exception cref="DatabaseException">
/// <list type="bullet">
/// <item><see cref="UpsConst.UPS_OUT_OF_MEMORY"/>
/// if the new structure could not be allocated</item>
/// </list>
/// </exception>
public void Create(Database db, Transaction txn)
{
this.db = db;
lock (this.db) {
int st = NativeMethods.CursorCreate(out handle, db.Handle,
txn != null ? txn.Handle : IntPtr.Zero, 0);
if (st != 0)
throw new DatabaseException(st);
db.AddCursor(this);
}
}
/// <summary>
/// Constructor which creates a new Cursor in a Transaction
/// </summary>
public Cursor(Database db, Transaction txn)
{
Create(db, txn);
}
/// <summary>
/// Inserts a Database Item
/// </summary>
/// <remarks>
/// This method wraps the native ups_db_insert function.
/// <br />
/// This function inserts a key/record pair as a new Database item.
/// <br />
/// If the key already exists in the Database, error code
/// <see cref="UpsConst.UPS_DUPLICATE_KEY" /> is thrown.
/// <br />
/// If you wish to overwrite an existing entry specify the flag
/// <see cref="UpsConst.UPS_OVERWRITE"/>
/// <br />
/// If you wish to insert a duplicate key specify the flag
/// <see cref="UpsConst.UPS_DUPLICATE" />. (Note that
/// the Database has to be created with the flag
/// <see cref="UpsConst.UPS_ENABLE_DUPLICATE_KEYS" /> in order
/// to use duplicate keys.)
/// The duplicate key is inserted after all other duplicate keys (see
/// <see cref="UpsConst.UPS_DUPLICATE_INSERT_LAST" />).
/// </remarks>
/// <param name="txn">An optional Transaction object</param>
/// <param name="key">The key of the new item</param>
/// <param name="record">The record of the new item</param>
/// <param name="flags">Optional flags for this operation. Possible
/// flags are:
/// <list type="bullet">
/// <item><see cref="UpsConst.UPS_OVERWRITE"/>
/// If the key already exists, the record is overwritten.
/// Otherwise, the key is inserted.</item>
/// <item><see cref="UpsConst.UPS_DUPLICATE"/>
/// If the key already exists, a duplicate key is inserted.
/// The key is inserted before the already existing duplicates.
/// </item>
/// </list></param>
/// <exception cref="DatabaseException">
/// <list type="bullet">
/// <item><see cref="UpsConst.UPS_INV_PARAMETER"/>
/// if the flags UpsConst.UPS_DUPLICATE <b>AND</b>
/// UpsConst.UPS_OVERWRITE were specified, or if
/// UpsConst.UPS_DUPLICATE was specified but the Database
/// was not created with UpsConst.UPS_ENABLE_DUPLICATE_KEYS</item>
/// <item><see cref="UpsConst.UPS_WRITE_PROTECTED"/>
/// if you tried to insert a key in a read-only Database</item>
/// <item><see cref="UpsConst.UPS_INV_KEYSIZE"/>
/// if key size is different than than the key size parameter
/// specified for Database.Create.</item>
/// </list>
/// </exception>
public void Insert(Transaction txn, byte[] key, byte[] record,
int flags)
{
int st;
lock (this) {
st = NativeMethods.Insert(handle,
txn != null ? txn.Handle : IntPtr.Zero,
key, record, flags);
}
if (st != 0)
throw new DatabaseException(st);
}
/// <summary>
/// Inserts a Database Item into a Record Number Database
/// </summary>
/// <returns name="key">The key of the new item</returns>
/// <remarks>
/// This method wraps the native ups_db_insert function.
/// <br />
/// This function inserts a record as a new Database item.
/// <br />
/// </remarks>
/// <param name="txn">An optional Transaction object</param>
/// <param name="record">The record of the new item</param>
/// <param name="flags">Optional flags for this operation.</param>
/// <exception cref="DatabaseException">
/// <list type="bullet">
/// <item><see cref="UpsConst.UPS_WRITE_PROTECTED"/>
/// if you tried to insert a key in a read-only Database</item>
/// </list>
/// </exception>
public byte[] InsertRecNo(Transaction txn, byte[] record, int flags)
{
int st;
byte[] key = null;
lock (this)
{
st = NativeMethods.InsertRecNo(handle,
txn != null ? txn.Handle : IntPtr.Zero,
ref key, record, flags);
}
if (st != 0)
throw new DatabaseException(st);
return key;
}
/// <summary>
/// Inserts a Database item
/// </summary>
/// <remarks>
/// This is an overloaded function for
/// Database.Insert(txn, key, record, 0).
/// </remarks>
public void Insert(Transaction txn, byte[] key, byte[] record)
{
Insert(txn, key, record, 0);
}
/// <summary>
/// Returns the number of keys in this Database
/// </summary>
/// <remarks>
/// This method wraps the native ups_db_count function.
/// <br />
/// You can specify UPS_SKIP_DUPLICATES if you do now want
/// to include any duplicates in the count.
/// </remarks>
public Int64 GetCount(Transaction txn, int flags)
{
int st;
Int64 count = 0;
lock (this) {
st = NativeMethods.GetCount(handle,
txn != null ? txn.Handle : IntPtr.Zero,
flags, out count);
}
if (st != 0)
throw new DatabaseException(st);
return count;
}
/// <summary>
/// Searches an item in the Database, returns the record
/// </summary>
/// <remarks>
/// This method wraps the native ups_db_find function.<br />
/// <br />
/// This function searches the Database for a key. If the key
/// is found, the method will return the record of this item.
/// <br />
/// Database.Find can not search for duplicate keys. If the
/// key has multiple duplicates, only the first duplicate is returned.
/// </remarks>
/// <param name="txn">The optional Transaction</param>
/// <param name="key">The key of the item</param>
/// <param name="flags">The flags of the operation</param>
/// <returns>The record of the item</returns>
/// <exception cref="DatabaseException">
/// <list type="bullet">
/// <item><see cref="UpsConst.UPS_KEY_NOT_FOUND"/>
/// if the item was not found</item>
/// </list>
/// </exception>
public byte[] Find(Transaction txn, ref byte[] key, int flags)
{
byte[] record = null;
lock (this) {
int st = NativeMethods.Find(handle,
txn != null ? txn.Handle : IntPtr.Zero,
ref key, ref record, flags);
if (st != 0)
throw new DatabaseException(st);
}
return record;
}
/// <summary>
/// Searches an item in the Database, returns the record
/// </summary>
public byte[] Find(Transaction txn, byte[] key)
{
return Find(txn, ref key, 0);
}
/// <summary>
/// Erases a Database Item
/// </summary>
/// <remarks>
/// This method wraps the native ups_db_erase function.
/// <br />
/// This function erases a Database item. If the item with the
/// specified key does not exist in the Database, error code
/// <see cref="UpsConst.UPS_KEY_NOT_FOUND" /> is thrown.
/// <br />
/// Note that this method can not erase a single duplicate key.
/// If the key has multiple duplicates, all duplicates of this key
/// will be erased. Use <see cref="Cursor.Erase" /> to erase a
/// specific duplicate key.
/// </remarks>
/// <param name="txn">The optional Transaction</param>
/// <param name="key">The key of the item to delete</param>
/// <exception cref="DatabaseException">
/// <list type="bullet">
/// <item><see cref="UpsConst.UPS_KEY_NOT_FOUND"/>
/// if the key was not found</item>
/// <item><see cref="UpsConst.UPS_WRITE_PROTECTED"/>
/// if you tried to insert a key in a read-only Database</item>
/// </list>
/// </exception>
public void Erase(Transaction txn, byte[] key)
{
int st;
lock (this) {
st = NativeMethods.Erase(handle,
txn != null ? txn.Handle : IntPtr.Zero, key, 0);
}
if (st != 0)
throw new DatabaseException(st);
}
