batchresult.h File Reference

A batchresult object holds the results of a single batch of operations returned by tibdgSession_GetRows , tibdgSession_PutRows , tibdgSession_UpdateRows , or tibdgSession_DeleteRows. More...

Functions
TIBDG_API tibbool_t	tibdgBatchResult_AllSucceeded (tibEx e, tibdgBatchResult batchResult)
	Find whether or not every operation in the batch succeeded. More...
TIBDG_API void	tibdgBatchResult_Destroy (tibEx e, tibdgBatchResult batchResult)
	Destroy the Batch Result. More...
TIBDG_API tibdgRow	tibdgBatchResult_GetRow (tibEx e, tibdgBatchResult batchResult, tibint32_t index)
	Get the Row at index from batchResult returned by tibdgSession_GetRows. More...
TIBDG_API tibint32_t	tibdgBatchResult_GetRowUpdateCount (tibEx e, tibdgBatchResult batchResult, tibint32_t index)
	Get the number of rows updated (0 or 1) for the row at index in batchResult. More...
TIBDG_API tibint32_t	tibdgBatchResult_GetSize (tibEx e, tibdgBatchResult batchResult)
	Get the number of rows in batchResult. More...

Detailed Description

A batchresult object holds the results of a single batch of operations returned by tibdgSession_GetRows , tibdgSession_PutRows , tibdgSession_UpdateRows , or tibdgSession_DeleteRows.

Upon obtaining a batchResult from one of the listed functions, tibdgBatchResult_AllSucceeded should be called to determine whether the entire batch was successful and additional information is available, or if the batch failed and some additional action must be taken.

If tibdgBatchResult_AllSucceeded returns true, the following functions may be called as described below.

tibdgBatchResult_GetSize may be called on any batchResult to get the number of rows in the batch.

For results returned from tibdgSession_GetRows , tibdgBatchResult_GetRow may be called to get individual rows.

For results returned from tibdgSession_UpdateRows , tibdgBatchResult_GetRowUpdateCount may be called to determine whether each row required an update.

When no longer needed, batchresult objects should be destroyed with tibdgBatchResult_Destroy .

Function Documentation

tibdgBatchResult_AllSucceeded()

TIBDG_API tibbool_t tibdgBatchResult_AllSucceeded	(	tibEx	e,
		tibdgBatchResult	batchResult
	)

Find whether or not every operation in the batch succeeded.

This function must be called prior to retrieving any result information from a batchResult object returned by tibdgSession_GetRows , tibdgSession_PutRows , tibdgSession_UpdateRows , or tibdgSession_DeleteRows. If this function returns false, no further information about failures is available.

Parameters

e	The exception object captures information about failures.
batchResult	The batch result object from the batched operation

Returns

bool

tibdgBatchResult_Destroy()

TIBDG_API void tibdgBatchResult_Destroy	(	tibEx	e,
		tibdgBatchResult	batchResult
	)

Destroy the Batch Result.

Parameters

e	The exception object captures information about failures.
batchResult	The batch result object to destroy

Returns

void

tibdgBatchResult_GetRow()

TIBDG_API tibdgRow tibdgBatchResult_GetRow	(	tibEx	e,
		tibdgBatchResult	batchResult,
		tibint32_t	index
	)

Get the Row at index from batchResult returned by tibdgSession_GetRows.

Example:

tibEx               ex;
tibdgConnection     connection;
tibdgSession        session;
tibdgTable          table;
 
ex = tibEx_Create();
 
tibdg_Open(ex, TIBDG_COMPATIBILITY_VERSION);
 
defaultProperties = tibProperties_Create(ex);
 
connection = tibdgGrid_Connect(ex, realmURL, gridName, defaultProperties);
 
session = tibdgConnection_CreateSession(ex, connection, defaultProperties);
 
// Fill in rows here.
 
tibdgBatchResult batch = tibdgSession_GetRows(ex, session, rows, numRows, defaultProperties);
 
if (tibdgBatchResult_AllSucceeded(ex, batch))
{
    tibint32_t size = tibdgBatchResult_GetSize(ex, batch);
    printf("Batch contains %d results:\n", size);
    for (tibint32_t i = 0; i < size; i++)
    {
        tibdgRow getRow = tibdgBatchResult_GetRow(ex, batch, i);
        if (getRow)
            // print row information here
        else
            printf("Row does not exist \n");
    }
}
else
{
    printf("Batched GET failed.");
}

Note: only valid for GET batches. You must call AllSucceeded() to verify that all the operations in the batch completed successfully.

The row returned is owned by the BatchResult object, and must be copied using tibdgRow_Copy to modify or use after the batch is destroyed.

Parameters

e	The exception object captures information about failures.
batchResult	The batch result object from the batched operation
index	The index of the row to retrieve

Returns

On success, this call returns the row corresponding to the _index_th key in the batch, which can be NULL if there is no row with that key.
On failure, this call returns NULL.

tibdgBatchResult_GetRowUpdateCount()

TIBDG_API tibint32_t tibdgBatchResult_GetRowUpdateCount	(	tibEx	e,
		tibdgBatchResult	batchResult,
		tibint32_t	index
	)

Get the number of rows updated (0 or 1) for the row at index in batchResult.

Example:

tibEx               ex;
tibdgConnection     connection;
tibdgSession        session;
tibdgTable          table;
 
ex = tibEx_Create();
 
tibdg_Open(ex, TIBDG_COMPATIBILITY_VERSION);
 
defaultProperties = tibProperties_Create(ex);
 
connection = tibdgGrid_Connect(ex, realmURL, gridName, defaultProperties);
 
session = tibdgConnection_CreateSession(ex, connection, defaultProperties);
 
// Fill in rows here.
 
tibdgBatchResult batch = tibdgSession_UpdateRows(ex, s, rows, numRows, defaultProperties);
 
if (tibdgBatchResult_AllSucceeded(ex, batch))
{
    tibint32_t size = tibdgBatchResult_GetSize(ex, batch);
    printf("Batch contained %d update requests:\n", size);
    
    tibint32_t numUpdated = 0;
    for (tibint32_t i = 0; i < size; i++)
    {
        numUpdated += tibdgBatchResult_GetRowUpdateCount(ex, batch, i);
    }
 
    printf("%d rows required updating.\n", numUpdated);
}
else
{
    printf("Batched UPDATE failed");
}

Note: only valid for UPDATE batch results returned from the tibdgSession_UpdateRows call. You must call AllSucceeded() to verify that all the operations in the batch completed successfully.

Parameters

e	The exception object captures information about failures.
batchResult	The batch result object from the batched operation
index	The index of the row to retrieve

Returns

On success, this call returns the number of rows updated by the request at index in the requested batch.
The tibdgSession_UpdateRows function updates a single row per key specified, so the number of rows updated will be 0 or 1.
On failure, this call returns 0 and sets the exception.

tibdgBatchResult_GetSize()

TIBDG_API tibint32_t tibdgBatchResult_GetSize	(	tibEx	e,
		tibdgBatchResult	batchResult
	)

Get the number of rows in batchResult.

If the batch was successful as indicated by tibdgBatchResult_AllSucceeded, the value returned will match the number of rows passed in to tibdgSession_GetRows , tibdgSession_PutRows, tibdgSession_DeleteRows , or tibdgSession_UpdateRows .

Parameters

e	The exception object captures information about failures.
batchResult	The batch result object from the batched operation

Returns

number of successful results