4. Prepared Statement Function Descriptions

This chapter describes the functions available for prepared statement processing by using statement handle in great detail.

altibase_stmt_affected_rows()

altibase_stmt_affected_rows() may be called immediately after executing a statement. It returns the number of rows changed, deleted, or inserted by the last statement if it was an UPDATE, DELETE, or INSERT. It is like altibase_affected_rows() but for prepared statements.

Syntax

ALTIBASE_LONG  altibase_stmt_affected_rows (
    ALTIBASE_STMT stmt );

Syntax

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

Return Value	Description
Greater than 0	An integer indicates the number of rows affected or retrieved.
0	No record affected by the SQL statement
ALTIBASE_INVALID_AFFECTEDROW	Error during UPDATE, DELETE, or INSERT

Description

altibase_stmt_affected_rows() returns the value that it would return for the last statement executed within the procedure

• UPDATE statements: the affected-rows value by default is the number of rows actually changed

• DELETE statements: the affected-rows value is the number of deleted rows

• INSERT statements: the affected-rows value is the number of existing rows which are updated

For SELECT statements, the affected-rows value is 0, and altibase_stmt_affected_rows() works like altibase_num_rows() which returns the number of rows selected by a SELECT statement.

Example

char *qstr = "UPDATE t1 SET val = val * 1.1 WHERE type = 1";

rc = altibase_stmt_prepare(stmt, qstr);
/* ... check return value ... */

rc = altibase_stmt_execute(stmt);
/* ... check return value ... */

printf("%ld updated\n", altibase_stmt_affected_rows(stmt));

altibase_stmt_bind_param()

altibase_stmt_bind_param() is used to bind input data for the parameter markers in the SQL statement.

Syntax

int  altibase_stmt_bind_param (
    ALTIBASE_STMT    stmt,
    ALTIBASE_BIND *  bind );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle
ALTIBASE_BIND *	bind	Input	The array of data to bind and its information

Return Values

altibase_stmt_bind_param() returns ALTIBASE_SUCCESS if the bind operation was successful, or ALTIBASE_ERROR if an error occurred.

Description

altibase_stmt_bind_param() binds variables to a prepared statement as the parameter marker in the SQL statement. The values of parameter markers are substitued for the question marks in SQL statement.

The client library expects the array to contain one element for each "?" parameter marker that is present in the query. If three parameter markers are declared, the array of ALTIBASE_BIND structures must contain three elements. The bind argument is available before the user calls altibase_stmt_reset(), altibase_stmt_close() or altibase_close(). Therefore, if inputting several data in the SQL statement, you can Prepared Statement substitue the bound data for the values and then call altibase_stmt_execute() multiple times after passing the SQL statement to altibase_stmt_prepare() and altibase_stmt_bind_param(). altibase_stmt_bind_param() must be called after calling altibase_stmt_prepare() and altibase_stmt_set_array_bind(), and before calling altibase_stmt_execute().

Example

#define PARAM_COUNT 2
#define STR_SIZE    50
#define QSTR        "INSERT INTO t1 VALUES (?, ?)"

int           int_dat;
char          str_dat[STR_SIZE];
ALTIBASE_LONG length[PARAM_COUNT];

ALTIBASE      altibase;
ALTIBASE_STMT stmt;
ALTIBASE_BIND bind[PARAM_COUNT];
int           rc;
int           i;

/* ... omit ... */

int_dat = 1;
strcpy(str_dat, "test1");

length[0] = sizeof(int);
length[1] = ALTIBASE_NTS;

memset(bind, 0, sizeof(bind));

bind[0].buffer_type   = ALTIBASE_BIND_INTEGER;
bind[0].buffer        = &int_dat;
bind[0].length        = &length[0];

bind[1].buffer_type   = ALTIBASE_BIND_STRING;
bind[1].buffer        = str_dat;
bind[1].buffer_length = STR_SIZE;
bind[1].length        = &length[1];

stmt = altibase_stmt_init(altibase);
/* ... check return value ... */

rc = altibase_stmt_prepare(stmt, QSTR);
/* ... check return value ... */

rc = altibase_stmt_bind_param(stmt, bind);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
    for (i = 0; i < PARAM_COUNT; i++)
    {
        printf("bind %d : %d\n", i, bind[i].error);
    }
    /* ... error handling ... */
}

rc = altibase_stmt_execute(stmt);
/* ... check return value ... */

altibase_stmt_bind_result()

altibase_stmt_bind_result() is used to bind output columns in the result set.

Syntax

int  altibase_stmt_bind_result (
    ALTIBASE_STMT   stmt,
    ALTIBASE_BIND * bind );

Arguments

Data Type	Argument	In/Outpu	Description
ALTIBASE_STMT	stmt	Input	Statement handle
ALTIBASE_BIND *	bind	Input	An array of buffers to receive data and data related information

Return Values

altibase_stmt_bind_result() returns ALTIBASE_SUCCESS if the bind operation was successful, or ALTIBASE_ERROR if an error occurred.

Description

altibase_stmt_bind_result() binds variables to a prepared statement for result storage.

The client library expects the array to contain one element for each column of the result set. If three parameter markers are declared, the array of ALTIBASE_BIND structures must contain three elements.

The bind argument is available before the user calls altibase_stmt_reset(), altibase_stmt_close() or altibase_close(). When altibase_stmt_fetch() is called to fetch data, the Altibase protocol places the data for the bound columns into the specified buffers. Therefore, the user can know the values returned by altibase_stmt_bind_result() in this way. altibase_stmt_bind_result() must be called after calling altibase_stmt_prepare() and altibase_stmt_set_array_fetch(), and before calling altibase_stmt_store_result() or altibase_stmt_fetch().

Example

#define FIELD_COUNT 2
#define STR_SIZE    50
#define QSTR        "SELECT * FROM t1"

ALTIBASE      altibase;
ALTIBASE_STMT stmt;
ALTIBASE_BIND bind[FIELD_COUNT];
int           int_dat;
char          str_dat[STR_SIZE];
ALTIBASE_LONG length[FIELD_COUNT];
ALTIBASE_BOOL is_null[FIELD_COUNT];
int           rc;
int           row;

/* ... omit ... */

stmt = altibase_stmt_init(altibase);
/* ... check return value ... */

rc = altibase_stmt_prepare(stmt, QSTR);
/* ... check return value ... */

rc = altibase_stmt_execute(stmt);
/* ... check return value ... */

memset(bind, 0, sizeof(bind));

bind[0].buffer_type   = ALTIBASE_BIND_INTEGER;
bind[0].buffer        = &int_dat;
bind[0].length        = &length[0];
bind[0].is_null       = &is_null[0];

bind[1].buffer_type   = ALTIBASE_BIND_STRING;
bind[1].buffer        = str_dat;
bind[1].buffer_length = STR_SIZE;
bind[1].length        = &length[1];
bind[1].is_null       = &is_null[1];

rc = altibase_stmt_bind_result(stmt, bind);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
    for (i = 0; i < FIELD_COUNT; i++)
    {
        printf("bind %d : %d\n", i, bind[i].error);
    }
    /* ... error handling ... */
}

/* altibase_stmt_store_result() is optional */
rc = altibase_stmt_store_result(stmt);
/* ... check return value ... */

for (row = 0; (rc = altibase_stmt_fetch(stmt)) != ALTIBASE_NO_DATA; row++)
{
    if (ALTIBASE_NOT_SUCCEEDED(rc))
    {
        /* ... error handling ... */
        break;
    }

    printf("row %d : ", row);
    if (is_null[0] == ALTIBASE_TRUE)
    {
        printf("{null}");
    }
    else
    {
        printf("%d", int_dat);
    }
    printf(", ");
    if (is_null[1] == ALTIBASE_TRUE)
    {
        printf("{null}");
    }
    else
    {
        printf("(%d) %s", length[1], str_dat);
    }
    printf("\n");
}

rc = altibase_stmt_free_result(stmt);
/* ... check return value ... */

altibase_stmt_close()

altibase_stmt_close() closes the prepared statement.

Syntax

int  altibase_stmt_close (
    ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

altibase_stmt_close() returns ALTIBASE_SUCCESS if the statement was freed successfully, or ALTIBASE_ERROR if an error occurred.

Description

altibase_stmt_close() closes the prepared statement and also deallocates the statement handle. The function removes entire resources allocated to connection handle.

Example

Refer to the example in altibase_stmt_init().

altibase_stmt_data_seek()

altibase_stmt_data_seek() seeks to an arbitrary row in a statememt result set and moves its position.

Syntax

int  altibase_stmt_data_seek (
    ALTIBASE_STMT  stmt,
    ALTIBASE_LONG  offset );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle
ALTIBASE_LONG	offset	Input	This is a row number which starts at 0.

Return Values

altibase_stmt_data_seek() returns ALTIBASE_SUCCESS if successful, or ALTIBASE_ERROR if an error occurred.

Description

altibase_stmt_data_seek() moves the row position in a stateiment result set to the specified place, The offset value is a row number and should be in the range from 0 to altibase_stmt_num_rows(stmt) - 1.

altibase_stmt_data_seek() may be used only in conjunction with altibase_stimt_store_result().

Example

#define QSTR "SELECT last_name, first_name FROM friends"

/* ... omit ... */

rc = altibase_stmt_store_result(stmt);
/* ... check return value ... */

row_count = altibase_stmt_num_rows(stmt);
for (i = 0; i < row_count; i++)
{
    rc = altibase_stmt_data_seek(stmt, i);
    if (ALTIBASE_NOT_SUCCEEDED(rc))
    {
        printf("ERR : %d : ", i, altibase_error());
        continue;
    }

    rc = altibase_stmt_fetch(stmt);
    /* ... check return value ... */

    /* ... omit ... */
}

rc = altibase_stmt_free_result(stmt);
/* ... check return value ... */

altibase_stmt_errno()

altibase_stmt_errno() returns the error code for the most recently invoked statement.

Syntax

unsigned int  altibase_stmt_ errno (
    ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Result Values

altibase_stmt_errno() returns 0 if the most recently invoked statement was successful and no error occurred. The function returns an error code value if an error occurred.

Description

altibase_stmt_errno() returns the error code for the most recently invoked statemenf function that can fail.

Even if the function just executed fails, no error code is returned for every function. An error code is generated only if the function executed just before was a function mainly related to SQL statement execution. For more information about error codes, refer to Error Message Reference.

If an error occurs while executing a function, calling the other function without checking the error immediately removes the information about the error. Therefore, when an error occurs, the user should use this function to check the error information.

The value returned by altibase_stmt_errno() is an Altibase self-defined error code that is different from the SQLSTATE defined in the ODBC specification. The user must use altibase_stmt_sqlstate() to get the SQLSTATE. It is generally not recommended to write an error handling routine by checking the return value of altibase_errno().

Example

rc = altibase_stmt_execute(stmt);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
    printf("error no  : %05X\n", altibase_stmt_errno(stmt));
    printf("error msg : %s\n", altibase_stmt_error(stmt));
    printf("sqlstate  : %s\n", altibase_stmt_sqlstate(stmt));
    return 1;
}

/* ... omit ... */

altibase_stmt_error()

altibase_stmt_error() returns error message for the most recently invoked statement.

Syntax

const char *  altibase_stmt_error (
ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Result Values

altibase_error() returns the error text from the last function, or an empty string if no error occurred.

Description

This function returns an error message indicating the reason for the failure if the previously executed function failed. If the previously executed function did not fail, an empty string or error messages related to errors that occurred earlier will be returned.

If an error occurs while executing a function, calling the other function without checking the error immediately removes the information about the error. Therefore, when an error occurs, this function must be used to check the error information.

The memory pointed to by the char pointer returned by this function is managed inside the library and should never be changed or released by the user.

Example

Refer to the example in altibase_stmt_errno().

altibase_stmt_execute()

altibase_stmt_execute() executes the prepared query associated with the statement handle.

Syntax

int  altibase_stmt_execute (
    ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

Return Value	Description
ALTIBASE_SUCCESS	Execution was successful.
ALTIBASE_NEED_DATA	There is data to send to the server using altibase_stmt_send_long_data().
ALTIBASE_ERROR	An error occurred.

Description

This function executes a prepared statement on the statement handle.

If the statement is an UPDATE, DELETE, or INSER statement altibase_stmt_affected_rows can be used to check how many rows have changed since executing this function.

If the statement returns a result set like a SELECT statement, the user must use altbase_stmt_fetch() to fetch data, and then use altbase_stmt_free_result() to free the result set after the user have finished using the result set.

Example

Refer to the examples in altibase_stmt_bind_param() and altibase_stmt_bind_result().

altibase_stmt_fetch()

altibase_stmt_fetch() fetches a row from the result set in a prepared statement.

Syntax

int  altibase_stmt_fetch (
    ALTIBASE_STMT stmt );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

Return Value	Description
ALTIBASE_SUCCESS	Successful, the data has been fetched.
ALTIBASE_SUCCESS_WITH_INFO	The data has been fetched. However, error also occurred.
ALTIBASE_NO_DATA	No more data exists.
ALTIBASE_ERROR	An error occurred.

Description

altibase_stmt_fetch() returns a row data from the result set in a prepared statement using the buffers bound.

Example

Refer to the example in altibase_stmt_bind_result().

altibase_stmt_fetch_column()

altibase_stmt_fetch_column() fetches one column from the current result set row.

Syntax

int  altibase_stmt_bind_result (
    ALTIBASE_STMT    stmt,
    ALTIBASE_BIND    *  bind,
    int              column,
    ALTIBASE_LONG    offset );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle
ALTIBASE_BIND *	bind	Input/Output	This denotes a buffer storing data.
int	column	Input	This is the number of a returned column. Its value starts at 0.
ALTIBASE_LONG	offset	Input	Start position (starting at zero) within the column data to be imported

Return Values

altibase_stmt_fetch_columns() returns ALTIBASE_SUCCESS in case of success, or ALTIBASE_ERROR if an error occurred.

Description

altibase_stmt_fetch_column() returns one column from the current result set row to the bind argument.

The offset argument is the offset within the data value at which to begin retrieving data. This can be used for fetching the data value in pieces. The beginning of the value is offset 0. If the offset argument is set to ALTIBASE_FETCH_CONT, altibase_stmt_fetch_column() returns columns which are placed after the returned one previously. If altibase_stmt_fetch_column() has not returned one column before, the function returns it at the starting position.

Depending on whether the user has previously called altibase_stmt_store_result(), the usage is slightly different.

altibase_stmt_store_result()	The bind argument	The offset argument
Yes (that is, bringing all the result set to the client)	The value of its buffer_type should be same as that returned by altibase_stmt_bind_result().	Any value can be used
No	Any buffer type can be used	Data must be imported sequentially using ALTIBASE_FETCH_COUNT

An error will be returned if the constraints of the bind and offset arguments described in the table above are not met.

Example

#define STR_SIZE 50

char           str_dat[STR_SIZE];
ALTIBASE_LONG  length;
ALTIBASE_BOOL  is_null;
ALTIBASE_BIND  bind;
int            rc;
int            i;

/* ... omit ... */

rc = altibase_stmt_execute(stmt);
/* ... check return value ... */

memset(bind, 0, sizeof(bind));

bind.buffer_type   = ALTIBASE_BIND_STRING;
bind.buffer        = str_dat;
bind.buffer_length = STR_SIZE;
bind.length        = &length;
bind.is_null       = &is_null;

while (1)
{
    rc = altibase_stmt_fetch(stmt);
    if (rc == ALTIBASE_NO_DATA)
    {
        break;
    }
    if (ALTIBASE_NOT_SUCCEEDED(rc))
    {
        /* ... error handling ... */
    }

    for (i = 0; ; i++)
    {
        rc = altibase_stmt_fetch_column(stmt, &bind, 0, ALTIBASE_FETCH_CONT);
        if (ALTIBASE_NOT_SUCCEEDED(rc))
        {
            /* ... error handling ... */
        }

        printf("%d : (%d) %s\n", i, length, str_dat);
    }
}

altibase_stmt_fetched()

altibase_stmt_fetched() returns the number of the exisitng rows fetched previously after fetching new result as an array.

Syntax

ALTIBASE_LONG  altibase_stmt_fetched (
    ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

altibase_stmt_fetched() returns the number of the exisitng rows fetched previously after fetching new result as an array in case of success, or ALTIBASE_INVALID_FETCHED if an error occurred.

Description

This function can be used after retrieving several rows from the result set into an array variable at once (called array fetch), which returns the number of rows retrieved. Array When fetching data from a result set using fetch, the user can use the return value of this function to check the condition of altibase_stmt_fetch() iterations.

altibase_stmt_fetched() returns the number of the exisitng rows fetched previously only after fetching new result as an array.

Example

Refer to Array Fetching in Chapter 5: Using Array Binding and Array Fetching.

altibase_stmt_field_count()

altibase_stmt_field_count() returns the number of columns for the most recent statement for the statement handler.

Syntax

int  altibase_stmt_field_count (
    ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

Return Value	Description
Greater than 0	The number of columns in the result set of the most recently prepared statement.
0	This means that the prepared statement is one that does not produce a result set.
ALTIBASE_INVALID_FIELDCOUNT	Error while executing function.

Description

altibase_stmt_field_count() returns the number of columns for the most recent statement for the statement handler. The function returns 0 for statements such as INSERT, DELETE and UPDATE which do not return a result set. altibase_stmt_field_count() can be called after the user has prepared a statement by invoking().

Example

Refer to the example in altibase_stmt_prepare().

altibase_stmt_free_result()

altibase_stmt_field_count() returns the number of columns for the most recent statement for the statement handler.

Syntax

int  altibase_stmt_free_result (
    ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

If the function succeeds, ALTIBASE_SUCCESS is returned. Otherwise, ALTIBASE_ERROR is returned.

Description

This function frees resources allocated for the result set produced by the execution of a prepared statement on the statement handle.

Example

Refer to the examples in altibase_stmt_bind_result() and altibase_stmt_data_seek().

altibase_stmt_get_attr()

altibase_stmt_get_attr() can be used to get the current value for a statement attribute.

Syntax

int  altibase_stmt_get_attr (
    ALTIBASE_STMT               stmt,
    ALTIBASE_STMT_ATTR_TYPE     option,
    void *                      arg );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle
ALTIBASE_STMT_ATTR_TYPE	option	Input	The option argument is the option that you want to get.
void *	arg	Input	The arg is the output buffer.

Return Values

altibase_stmt_get_attr() returns ALTIBASE_SUCCESS if successful, or ALTIBASE_ERROR if an error occurred.

Description

This function returns the value of a specific attribute currently set on the statement handle.

The client library assumes that the size of the arg buffer is large enough, so the user must pass as a parameter the maximum size of the buffer that the desired attribute value can have.

For more information about statement attributes, refer to "enum AlTIBASE_STMT_ATTR_TYPE" in Chapter 2.

Example

Refer to the example in altibase_stmt_set_attr().

altibase_stmt_init()

altibase_stmt_init() creates an ALTIBASE_STMT handle.

Syntax

ALTIBASE_STMT  altibase_stmt_init (
    ALTIBASE  altibase );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE	altibase	Input	Connection handle

Return Values

altibase_stmt_init() returns an ALTIBASE_STMT handle in case of success, or null if out of memory.

Description

altibase_stmt_init() creates an ALTIBASE_STMT handle with using a connection handle.

When you have finished using the statement handle, the user must use altibase_stmt_close() to release it.

Example

stmt = altibase_stmt_init(altibase);
if (stmt == NULL)
{
    /* ... error handling ... */
}

/* ... omit ... */

rc = altibase_stmt_close(stmt);
if (! ALTIBASE_SUCCEEDE(rc))
{
    /* ... error handling ... */
}

altibase_stmt_next_result()

altibase_stmt_next_result() accesses the next result set.

Syntax

int altibase_stmt_next_result ( ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

Return Value	Description
ALTIBASE_SUCCESS	Successful and there are more result sets
ALTIBASE_NO_DATA	Successful and there are no more result sets
ALTIBASE_ERROR	An error occurred

Description

This function is used to access the next result set when a command that returns multiple result sets has been executed using a prepared statement.

If there is a previously retrieved result set, it must be freed using altibase_stmt_free_result() before calling altibase_stmt_next_result().

Executing this function puts the statement in the same state as if altibase_stmt_execute() had been called. This means that users can call altibase_stmt_bind_result() and altibase_stmt_affected_rows().

Example

sRC = altibase_stmt_prepare(sStmt, "EXEC PROC_RESULTSET");
/* ... omit ... */
sRC = altibase_stmt_execute(sStmt);
/* ... check return value ... */
while (1)
{
    sFieldCount = altibase_stmt_field_count(sStmt);

    sRC = altibase_stmt_bind_result(sStmt, bind);
    /* ... check return value ... */

    while ((sRC = altibase_stmt_fetch(sStmt)) != ALTIBASE_NO_DATA)
    {
        /* ... check return value ... */
        for (i = 0; i < sFieldCount; i++)
        {
            /* ... omit ... */
        }
    }
    sRC = altibase_stmt_free_result(sStmt);
    /* ... check return value ... */
    sRC = altibase_stmt_next_result(sStmt);

    if (sRC == ALTIBASE_NO_DATA)
    {
        break;
    }
    CDBC_TEST_RAISE(ALTIBASE_NOT_SUCCEEDED(sRC), stmt_error);
}

altibase_stmt_num_rows()

altibase_stmt_num_rows() returns the number of rows in the result set.

Syntax

ALTIBASE_LONG altibase_stmt_num_rows (
    ALTIBASE_STMT stmt );

Argument

Data Type	Argument	In/Out	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Value

altibase_stmt_num_rows() returns the number of rows in the result set.

Description

altibase_stmt_num_rows() returns the number of rows in the result set. The use of altibase_stmt_num_rows() depends on whether you used altibase_stmt_store_result() to buffer the entire result set. If you use altibase_stmt_store_result(), altibase_stmt_num_rosw() may be called immediately. Otherwise, the row count is unavailable unless the user counts the rows while fetching.

altibase_stmt_num_rows() is intended for use with statements that return a result set, such as SELECT. For statements such as INSERT, UPDATE, or DELETE, the number of affected rows can be obtained with altibase_stmt_affected_rows().

Example

Refer to the example in altibase_stmt_data_seek().

altibase_stmt_param_count()

altibase_stmt_param_count() returns the number of parameter markers present in the prepared statement.

Syntax

int  altibase_stmt_param_count (
    ALTIBASE_STMT  stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Value

altibase_stmt_param_count() returns the number of parameter markers if successful, or ALTIBASE_INVALID_PARAMCOUNT if an error occurred.

Description

altibase_stmt_param_count() returns the number of parameter markers present in the prepared statement. If no parameter marker exists, the function returns 0.

This function must be used after calling altibase_stmt_prepare().

Example

Refer to the example in altibase_stmt_prepare().

altibase_stmt_prepare()

altibase_stmt_prepare() prepares the SQL statement and returns a status value.

Syntax

int  altibase_stmt_prepare (
    ALTIBASE_STMT       stmt,
    const char *        qstr );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle
const char *	qstr	Input	The SQL statement pointed to by the null-terminated string.

Return Values

altibase_stmt_prepare() returns ALTIBASE_SUCCESS if the statement was successful. The function returns ALTIBASE_ERROR if an error occurred.

Description

altibase_stmt_prepare() prepares a SQL statement for execution. The SQL statement must be pointed to by null-terminated string. Normally the string must consist of a single SQL statement and you should not add a terminating semicolon(";"). Therefore, multiple-statement execution has not been enabled because the string cannot contain several statements separated by semicolons. To enable multiple-statement execution, you can process stored procedure that produce result sets.

The application can include one or more parameter markers in the SQL statement by embedding question mark ("?") characters into the SQL string at the appropriate positions. If embedding question mark ("?") characters into the SQL string, you must bind input data for the parameter markers by using altibase_stmt_bind_param() before calling altibase_stmt_execute().

Once prepared, the statement is valid until another SQL statement executes altibase_stmt_prepare() with the statement handle of this prepared statement, or by calling altibase_stmt_close() or altibase_close() to release the associated handle.

When altibase_stmt_prepare() is executed, all previous information related to the statement handle is initialized. That is, all previously set binding information and array related information disappear. Therefore, if necessary, the binding information and array related information for the new SQL statement should be reset.

If the user executes multiple SQL statements of the same structure with only data, using altibase_stmt_prepare(), altibase_stmt_bind_param(), and altibase_stmt_execute() can provide better performance than executing the SQL statement every time with altibase_query().

Example

rc = altibase_stmt_prepare(stmt, qstr);
if (ALTIBASE_NOT_SUCCEEDED(rc))
{
    /* ... error handling ... */
}

printf("field count : %d\n", altibase_stmt_param_count(stmt));
printf("field count : %d\n", altibase_stmt_field_count(stmt));

altibase_stmt_processed()

altibase_stmt_processed() returns the number of rows after using the array binding.

Syntax

ALTIBASE_LONG  altibase_stmt_processed (
    ALTIBASE_STMT  stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

altibase_stmt_processed() returns the number of rows after using the array binding in case of success, or ALTIBASE_INVALID_PROCESSED if an error occurred.

Description

This function returns the number of elements processed in the array when the array variable is used for input binding (called array binding). If successful, the return value will be the size of the bound array.

This function can be used only when array binding is performed.

Example

Refer to Array Binding in Chapter 5: Using Array Binding and Array Fetching.

altibase_stmt_reset()

altibase_stmt_reset() resets statement handle for a prepared statement on client and server to state after prepare.

Syntax

int  altibase_stmt_reset (
    ALTIBASE_STMT  stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Value

altibase_stmt_reset() returns ALTIBASE_SUCCESS if the statement was successful. The function returns ALTIBASE_ERROR if an error occurred.

Description

This function initializes the information set in the statement handle. In other words, when this function is executed, all previously set binding information and array related settings are lost. But the prepared state It stays the same.

Therefore, if necessary, the binding information for the new SQL statement and the array fetch related information should be reset.

If a result set is returned before using the function, the user must call altibase_stmt_free_result() first. Otherwise, an error occurs.

altibase_stmt_result_metadata()

If the SQL statement passed to the server with altibase_stmt_prepare() is a statement that generates a result set, this function returns the metadata of the result set.

Syntax

ALTIBASE_RES  altibase_stmt_result_metadata (
    ALTIBASE_RES  stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

The handle of the result set containing the metadata is returned. If an error occurs, NULL is returned.

Description

The statement prepared by altibase_stmt_prepare() is a statement that generates a result set like a SELECT statement. In this case, this function returns a handle to the result set that contains column information from the result set.

The user can get multiple column information by passing the result set handle returned by this function as an argument to the following functions:

• altibase_num_fields()

• altibase_field()

• altibase_fields()

The result set returned by this function must be freed using altibase_free_result().

altibase_stmt_send_long_data()

This function is not currently supported.

altibase_stmt_set_array_bind()

altibase_stmt_set_array_bind() specifies the size of array when you want to use the array binding.

Syntax

int  altibase_stmt_set_array_bind (
    ALTIBASE_ STMT     stmt,
    int                array_size );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle
int	array_size	Input	The size of array

Return Values

altibase_stmt_set_array_bind() returns ALTIBASE_SUCCESS if the statement was successful. The function returns ALTIBASE_ERROR if an error occurred.

Description

This function is used to set the size of array when you want to bind array. Array binding is set only when array_size is greater than 1. To unbind an array, pass array_size as 1.

The configured array binding information is valid until altibase_stmt_reset(), altibase_stmt_prepare(), or altibase_stmt_close() are called.

This function should be used after altibase_stmt_prepare() is called but before altibase_stmt_bind_param() is called.

Example

Refer to Array Binding in Chapter 5: Using Array Binding and Array Fetching.

altibase_stmt_set_array_fetch()

altibase_stmt_set_array_fetch() specifies the size of array when you want to fetch an array.

Syntax

int  altibase_stmt_set_array_fetch (
    ALTIBASE_ STMT     stmt,
    int                array_size );

Arguments

Data Type	Argument	In/Out	Description
ALTIBASE_STMT	stmt	Input	Statement handle
int	array_size	Input	The size of array

Return Values

altibase_stmt_set_array_fetch() returns ALTIBASE_SUCCESS if the statement was successful. The function returns ALTIBASE_ERROR if an error occurred.

Description

This function is used to set the size of an array when the user wants to fetch an array. An array fetch is set only when array_size is greater than 1. To release the array fetch, pass the value of array_size to 1.

It is available to fetch an array only before calling altibase_stmt_reset(), altibase_stmt_prepare() and altibase_stmt_close(). altibase_stmt_set_array_bind() can be used after calling altibase_stmt_prepare() and before calling altibase_stmt_bind_result().

Example

Refer to Array Binding in Chapter 5: Using Array Binding and Array Fetching.

altibase_stmt_set_attr()

altibase_stmt_set_attr() can be used to affect behavior for a prepared statement. This function may be called to set the value for a statement attribute.

Syntax

int  altibase_stmt_bind_result (
    ALTIBASE_STMT               stmt,
    ALTIBASE_STMT_ATTR_TYPE     option,
    void *                      arg );

Arguments

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle
ALTIBASE_STMT_ATTR_TYPE	option	Input	The option argument is the option that you want to set.
void *	arg	Input	The arg argument is the value for the option. arg should point to a variable that is set to the desired attribute value.

Return Values

altibase_stmt_set_attr() returns ALTIBASE_SUCCESS if successful, or ALTIBASE_ERROR if an error occurred.

Description

Once set, the statement attribute is valid until the same attribute is reset using altibase_stmt_set_attr() or the handle is released with altibase_stmt_close() or altibase_close().

For more information about statement attributes, refer to "enum ALTIBASE_STMT_ATTR_TYPE" in Chapter 2.

Example

int atomic_array = ALTIBASE_ATOMIC_ARRAY_ON;

rc = altibase_stmt_set_attr(stmt, ALTIBASE_STMT_ATTR_ATOMIC_ARRAY,
                            (void*)atomic_array);
/* ... check return value ... */

rc = altibase_stmt_get_attr(stmt, ALTIBASE_STMT_ATTR_ATOMIC_ARRAY,
                            &atomic_array);
/* ... check return value ... */

printf("Atomic array : %d\n", atomic_array);

altibase_stmt_sqlstate()

altibase_stmt_sqlstate() returns a null-terminating string containing the SQLSTATE error code for the most recently invoked prepared statement function that can succeed or fail.

Syntax

const char *  altibase_stmt_sqlstate (
    ALTIBASE_STMT  stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

altibase_stmt_sqlstate() returns a null-terminating character string containing the SQLSTATE error code in case of success.

Description

altibase_stmt_sqlstate() returns a null-terminating string containing the SQLSTATE error code for the most recently invoked prepared statement function that can succeed of fail. The error code consists of five characters. "00000" means "no error". For a list of possible values, refer to Error Message Reference.

Make sure you check the value before calling another function becuase it is initialized or new one is created instead if you call another function. The value returned by altobase_stmt_errno() is different from that of SQLSTATE. You should use altobase_sqlstate() to find a specific SQLSTATE when handling errors. It is recommended not to check the values returned by altibase_stmt_errno() but those of SQLSTATE if you need error code.

Not all Altibase error number returned by altibase_stmt_errno() are mapped to SQLSTATE error codes. Therefore, you cannot know the values of SQLSTATE by checking those returned by altibase_stmt_errno(), or you cannot know the values returned by altibase_stmt_errno() by checking those of SQLSTATE exactly. You must not change or cancel it as you please because it is managed within procedure.

Example

Refer to the example in altibase_stmt_errno().

altibase_stmt_status()

altibase_stmt_status() returns the results returned after uisng the array binding or fetching an array.

Statement

unsigned short *  altibase_stmt_status (
    ALTIBASE_STMT  stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Return Values

altibase_stmt_status() returns an array from an Altibase result set of a query using the array binding or fetching an array in case of success.

Description

This function returns the result of array binding or array fetch depending on whether fetch is performed. This function can only be used if the user has enabled array binding or array fetch.

If the user did not retrieve the result set, this function returns the result of array binding. The array returned by this function stores the result of executing an SQL statement using the values of each element of the bound array. The state value will be one of the following values.

Return Value	Description
ALTIBASE_PARAM_SUCCESS	Successfully executed
ALTIBASE_PARAM_SUCCESS_WITH_INFO	Successfully executed, but a warning occurred
ALTIBASE_PARAM_ERROR	An error occurs when executing with the value of a parameter variable
ALTIBASE_PARAM_UNUSED	The value of this parameter variable is not used. Perhaps an error occurs when running with the previous parameter value, and further processing stops.

After fetching the result set, this function returns the result of the array fetch. The array returned by this function stores the result of fetching each row of the result set into a bound array variable. The state value will be one of the following values.

Return Values	Description
ALTIBASE_ROW_SUCCESS	Execution was successful.
ALTIBASE_ROW_SUCCESS_WITH_INFO	Execution was successful. However, error also occurred.
ALTIBASE_ROW_NOROW	This is an array element which is not fetched when the number of the fetched rows is lower than the size of array.
ALTIBASE_ROW_ERROR	An error occurred when fetched a row.

The user must not change or release the values as you please because they are managed within procedure.

Example

Refer to Chapter 5: Using Array Binding and Array Fetching.

altibase_stmt_store_result()

altibase_stmt_store_result() is called to buffer the complete result set.

Syntax

int  altibase_stmt_store_result (
    ALTIBASE_STMT  stmt );

Argument

Data Type	Argument	In/Output	Description
ALTIBASE_STMT	stmt	Input	Statement handle

Result Values

altibase_stmt_store_result() returns ALTIBASE_SUCCESS if the results are buffered, or ALTIBASE_ERROR if an error occurred.

Description

This function retrieves the entire result set of the query execution.

When this function is executed, all query execution results are retrieved from the server and stored in the client. When calling altibase_stmt_fetch() after calling this function, all result sets have already been received from the server, so they are not communicated with the server and the data of the result set is returned.

When executing this function, all result sets are taken. If the user has a large column such as LOB or GEOMETRY, or if the number of result rows is large, memory may be used excessively, so be careful when using this function.

altbase_stmt_store_result() can be used after calling altibase_stmt_bind_result() and before calling altibase_stmt_fetch(). If calling altibase_stmt_store_result(), the user can use the followings additionally.

• altibase_stmt_num_rows()

• altibase_stmt_data_seek()

The result set obtained through this function should be freed with altibase_stmt_free_result() after it is finished using.

Example

Refer to the examples in altibase_stmt_bind_result() and altibase_stmt_data_seek().