|
public static CursorInsert ( |
||
| handle | ||
| keyData | byte | |
| recordData | byte | |
| flags | int | |
| return | int | |
/// <summary>
/// Inserts a Database item and points the Cursor to the new item
/// </summary>
/// <remarks>
/// This method wraps the native ups_cursor_insert function.
/// <br />
/// This function inserts a key/record pair as a new Database item.
/// If the key already exists in the Database, error
/// <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.)
/// By default, the duplicate key is inserted after all other duplicate
/// keys (<see cref="UpsConst.UPS_DUPLICATE_INSERT_LAST"/>). This
/// behaviour can be overwritten by specifying
/// <see cref="UpsConst.UPS_DUPLICATE_INSERT_FIRST"/>,
/// <see cref="UpsConst.UPS_DUPLICATE_INSERT_BEFORE"/> or
/// <see cref="UpsConst.UPS_DUPLICATE_INSERT_AFTER"/>.
/// <br />
/// Specify the flag <see cref="UpsConst.UPS_HINT_APPEND"/> if you
/// insert sequential data and the current key is higher than any
/// other key in this Database. In this case upscaledb will optimize
/// the insert algorithm. upscaledb will verify that this key is
/// the highest; if not, it will perform a normal insert. This is
/// the default for Record Number Databases.
/// <br />
/// Specify the flag <see cref="UpsConst.UPS_HINT_PREPEND"/> if you
/// insert sequential data and the current key is lower than any
/// other key in this Database. In this case upscaledb will optimize
/// the insert algorithm. upscaledb will verify that this key is
/// the lowest; if not, it will perform a normal insert.
/// <br />
/// After inserting, the Cursor will point to the new item. If inserting
/// the item failed, the Cursor is not modified.
/// </remarks>
/// <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, combined
/// with bitwise OR. 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 after the already existing duplicates.
/// Same as <see cref="UpsConst.UPS_DUPLICATE_INSERT_LAST" />.
/// </item>
/// <item><see cref="UpsConst.UPS_DUPLICATE_INSERT_BEFORE" />
/// If the key already exists, a duplicate key is inserted before
/// the duplicate pointed to by this Cursor.</item>
/// <item><see cref="UpsConst.UPS_DUPLICATE_INSERT_AFTER" />
/// If the key already exists, a duplicate key is inserted after
/// the duplicate pointed to by this Cursor.</item>
/// <item><see cref="UpsConst.UPS_DUPLICATE_INSERT_FIRST" />
/// If the key already exists, a duplicate key is inserted as
/// the first duplicate of the current key.</item>
/// <item><see cref="UpsConst.UPS_DUPLICATE_INSERT_LAST" />
/// If the key already exists, a duplicate key is inserted as
/// the last duplicate of the current key.</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(byte[] key, byte[] record, int flags)
{
int st;
lock (db) {
st = NativeMethods.CursorInsert(handle, key, record, flags);
}
if (st != 0)
{
throw new DatabaseException(st);
}
}
