SQLEmptyLob

SQLEmptyLob

This function is used when inserting or updating an empty LOB.

Syntax

SQLRETURN SQLEmptyLob(SQLHSTMT     stmt,
                      SQLSMALLINT  locatorCType,
                      SQLUBIGINT   targetLocator);

Argument

Data Type	Argument	In/Output	Description
SQLHSTMT	stmt	Input	Statement handle for the searched result
SQLSMALLINT	locatorCType	Input	C data type identifier for the target LOB locator. - SQL_C_BLOB_LOCATOR - SQL_C_CLOB_LOCATOR
SQLUBIGINT	targetLocator	Input	Target LOB Locator

Return Values

SQL_SUCCESS
SQL_INVALID_HANDLE
SQL_ERROR

Description

This function inserts or updates a target LOB locator with an Empty LOB (length 0).

Inserting LOB Data

You can use this function to insert an Empty LOB into a LOB column using an INSERT statement.

Updating LOB Data

You can use this function to update a LOB column to an Empty LOB using UPDATE or SELECT FOR UPDATE statements. Only LOB locators that are valid and currently open within the active transaction can be used as arguments.

Cautions

• 1. Existing Data Conflict When using this function within a SELECT FOR UPDATE statement, it will return SQL_ERROR if LOB data with a length of 1 or greater already exists in the open LOB locator.

• Solution: When LOB data with a length of 1 or greater exists, SQLTrimLob() must be used to insert an empty LOB.

• 2. Transaction Scope The target LOB locator passed as an argument must have been created or retrieved within the current transaction.

Diagnosis

SQLSTATE	Description	Comments
08S01	Communication link failure (data transmission/reception failure)	Communication link failure before the completion of function processing between the Altibase CLI driver and the database server.
HY000		General error

Related Functions

SQLGetLobLength2

Example

Example of inserting an empty LOB using the SQLEmptyLob() function

#Given that the table was created as follows.
# CREATE TABLE T1 (i1 INTEGER PRIMARY KEY, i2 CLOB);

SQLINTEGER lobInd;
SQLUBIGINT lobLoc;

strcpy(query, "INSERT INTO T1 VALUES (5, ?)");
if (SQLPrepare(stmt, query, SQL_NTS) != SQL_SUCCESS)
{
    execute_err(dbc, stmt, "SQLPrepare : ");
    SQLFreeStmt(stmt, SQL_DROP);
    return SQL_ERROR;
}

/* 
Bind the LOB locator argument in the SQLBindParameter function to retrieve the LOB locator in the SQLExecute function. 
*/
if (SQLBindParameter(stmt, 1, SQL_PARAM_OUTPUT, SQL_C_CLOB_LOCATOR, SQL_CLOB_LOCATOR, 0, 0, &lobLoc, 0, &lobInd) != SQL_SUCCESS)
{
    execute_err(dbc, stmt, "SQLBindParameter : ");
    SQLFreeStmt(stmt, SQL_DROP);
    return SQL_ERROR;
}

/* 
Execute the SQLExecute function.
*/
if (SQLExecute(stmt) != SQL_SUCCESS)
{
    execute_err(dbc, stmt, "SQLExecute : ");
    SQLFreeStmt(stmt, SQL_DROP);
    return SQL_ERROR;
}

/* Insert an empty LOB using the SQLEmptyLOB function. */
if (SQLEmptyLob(stmt, SQL_C_CLOB_LOCATOR, lobLoc) != SQL_SUCCESS)
{
    execute_err(dbc, stmt, "SQLPutLob : ");
    SQLFreeStmt(stmt, SQL_DROP);
    return SQL_ERROR;
}


if (SQLFreeLob(stmt, lobLoc) != SQL_SUCCESS)
{
    execute_err(dbc, stmt, "SQLFreeLob : ");
    SQLFreeStmt(stmt, SQL_DROP);
    return SQL_ERROR;
}