Mimer SQL C API

Mimer SQL C API is a native C library suitable for tool integration and application development in environments where API standardization is not a requirement. The following characteristics describe the API:

• Simplicity

• Platform independence

• Small footprint

• Tight fit with the Mimer SQL application/database communication model.

Hereinafter, the Mimer SQL C API is referred to as the Mimer API.

The Mimer SQL C API also comes in a micro environment edition under the name Mimer SQL Micro C API, which is mainly targeted for memory and CPU constrained environments. This variant is referred to as the Micro API. In most cases, the Mimer API and the Micro API are identical, but where there are differences, these are noted below.

Architecture

The Mimer API routines may be divided into four major categories, depending on how they are used. These routine categories are:

•Session management - These routines manages a database session including connect, disconnect and transaction handling. See Session Management.

•Statement management - Once a session has been established, an application uses statements to interact with the database. Statements are defined using the SQL language and may be specified directly or created on the server in advance using the CREATE STATEMENT command. See Statement Management.

•Input data management - Used to supply input parameter data to statements. See Data Input Routines.

•Output data management - Obtains result sets and statement output parameter data. See Data Output Routines.

Character String Formats

API routines having string parameters come in different flavors depending on which character string format is used. The rationale is that the base routine considers all strings to be null terminated wchar_t * strings.

If a routine has string parameters, there is a companion routine suffixed with C, which accepts the string parameters as null terminated char * strings, where the character set is defined by the current locale.

Companion routines suffixed with 8 have the string format UTF-8, regardless of locale settings.

Session Management

In the Mimer API, the following routines are used for managing sessions; beginning and ending sessions, and beginning and ending transactions:

•MimerBeginSession[C|8]

•MimerEndSession

•MimerBeginTransaction

•MimerEndTransaction

The flow of calls should be according to the below. First, a session is started using a call to MimerBeginSession (or MimerBeginSession8 or MimerBeginSessionC, depending on the data types supplied).

Then database operations take place, either separately (in auto-committed transactions), or grouped in explicit transactions. The boundaries of an explicit transaction are marked using the calls to MimerBeginTransaction and MimerEndTransaction. (See Transactions for more information about transactions in the Mimer API.)

This process continues until the application terminates its database session through a call to MimerEndSession.

MimerBeginSession[C|8]

loop

{

    MimerBeginTransaction

    <statement and data management routines>

    MimerEndTransaction

}

MimerEndSession

Statement Management

The routines used to manage statements are:

•MimerAddBatch

•MimerBeginStatement[C|8]

•MimerEndStatement

•MimerExecute

•MimerOpenCursor

•MimerFetch

•MimerFetchScroll

•MimerFetchSkip

•MimerCloseCursor

•MimerCurrentRow

•MimerExecuteStatement[C|8]

Which routines to use basically depends on if the statement has input or output parameters, and if a result set is returned or not.

No input or output parameters, no result set

The MimerExecuteStatement[C|8] routine is mainly intended for DDL statements (i.e. data definition language statements, e.g. create and drop table.) However, it can also be used for UPDATE, INSERT, DELETE and CALL statements without parameters.

MimerExecuteStatement[C|8]

Input or output parameters, but no result set

The MimerExecute routine is used for INSERT, UPDATE and DELETE statements, assignments (SET), and procedure calls which do not return a result set.

MimerBeginStatement[C|8]

<data input routines>

MimerExecute

<data output routines>

MimerEndStatement

Result set producing statements

Result sets are returned by SELECT statements, as well as by calls to result set procedures. A result set is accessed using a cursor.

MimerBeginStatement[C|8]

<data input routines>

MimerOpenCursor

loop

{

    MimerFetch/MimerFetchSkip/MimerFetchScroll

    <data output routines>

}

MimerCloseCursor

MimerEndStatement

Data Input Routines

Input data management routines are used to supply input parameter data to statements. The data management routines to set input parameter data are:

•MimerSetBinary

•MimerSetBlobData

•MimerSetBoolean

•MimerSetDouble

•MimerSetFloat

•MimerSetInt32

•MimerSetInt64

•MimerSetLob

•MimerSetNclobData[C|8]

•MimerSetNull

•MimerSetString[C|8]

•MimerSetStringLen[C|8]

•MimerSetUUID

Data Output Routines

The output data management routines used to obtain statement results are:

•MimerGetBinary

•MimerGetBlobData

•MimerGetBoolean

•MimerGetDouble

•MimerGetFloat

•MimerGetInt32

•MimerGetInt64

•MimerGetLob

•MimerGetNclobData[C|8]

•MimerGetString[C|8]

•MimerGetUUID

•MimerIsNull

Array Operations

The Mimer API supports the use of array fetch operations. Array fetching means that multiple rows are fetched from the server in one request. This will improve performance at the expense of memory consumption. MimerSetArraySize may be used to control the minimum number of rows to be fetched in each request. MimerRowSize may be used to determine the maximum number of bytes each row consumes. By multiplying the array size with the maximum row size a maximum array fetch memory consumption value can be obtained.

MimerFetch will internally fetch as many rows as possible and refill the internal buffer when needed. MimerNext on the other hand will return rows until all the rows in the internal buffer have been returned, it will not call the server to fetch more rows. The purpose of MimerNext is to have a fetch routine that is guaranteed context switch free.

The Mimer API also supports supplying parameters in arrays. Parameter arrays are specified by call MimerAddBatch during the parameter buildup sequence. MimerAddBatch adds the current set of parameters to be executed on the next MimerExecute call making room for another set of parameters to be specified by subsequent calls to for example MimerSetString.

Transactions

All operations on the database participate in a transaction. By default, operations are committed as soon as possible, which in practice means immediately after each INSERT, UPDATE or DELETE. A common term for this is that statements are automatically committed (autocommit).

If several operations are to be grouped together into one single transaction, the transaction boundaries must be defined by calls to MimerBeginTransaction and MimerEndTransaction.

Transactions may abort. A transaction abort is a rollback forced by the system. A transaction abort occurs when a conflict with another session has been detected, for example when two transactions have been reading and updating the same data. The database system must decide to abort one of them and to save the other one to storage. The session seeing the aborted transaction must take some action depending on this, perhaps trying to update the database once again.

Issuing large transactions puts a special burden on the database server since read- and write-sets may grow large, thus consuming memory. The read- and write-sets are logs maintaining a record of what active transactions have done. Large read- and write-sets also has the implication that they put a larger overall burden on the database server since it may take time to manage them, particularly if they grow so large that they are written to flash or magnetic memories.

Data Types

The C acronym for each SQL data type is listed in the below table.

The data types marked with an asterisk (*) are not supported by the Mimer API’s data input and data output routines. To use these data types, convert the data using the SQL function CAST.

The following table describes which API calls may be used to set or get parameters and column values of the corresponding SQL data type.

Data types which do not have a corresponding manipulation method according to the above table must be explicitly casted to a data type which does.

Detecting Data Types at Run-time

If the data type of a column or parameter is not known until runtime it is possible to detect them and dynamically choose which getter or setter function to use. For this purpose the functions MimerColumnType and MimerParameterType are used to obtain the type of a column or parameter.

 

A range of macros may be used to determine which getter/setter which matches the data type obtained from MimerColumnType or MimerParameterType. These are:

Error Handling

Upon return, all routines return an integer value. In most cases the value zero (MIMER_SUCCESS) is used to indicates success. In some cases a positive value is used to indicate success with additional information. Negative values always indicate an error condition. The negative values are standard Mimer SQL error codes, which are listed in Return Codes.

Errors between -24000 and -24299 are specific to Mimer API, where errors in the -24100 to -24199 range occur because of programming mistakes. Errors in the -24200 to -24299 range are of internal nature caused by system problems.

The Mimer API specific return codes are listed in Mimer SQL C API Return Codes. The acronyms for the Mimer API specific return codes can be found in the mimerrors.h header file.

The macro MIMER_SUCCEEDED may be used to detect a call which has either succeeded, or succeeded with additional information (a positive value). Negating this macro may be used to detect an error.

The error condition MIMER_SEQUENCE_ERROR has a special meaning. It will be returned when an illegal call has been made. The Mimer API will enforce a strict sequence of allowed calls. For example, MimerGetString may not be called before MimerFetch has been called. MIMER_SEQUENCE_ERROR is returned when illegal sequences of calls are detected.

Error Handling Example

The below example function shows how a function uses the return value from a Mimer API function call to determine success or failure.

/**

* Function which executes the statement OUR_STATEMENT

*

* On failure, the error code is written to stdout.

*/

#include "mimerapi.h"

int example1(MimerSession session)

{

 int32_t err,end_err=MIMER_SUCCESS;

 MimerStatement statement;

  

 err = MimerBeginStatement(session,L"OUR_STATEMENT",0,&statement);

 if (MIMER_SUCCEEDED(err)) {

   err = MimerExecute(statement);

   end_err = MimerEndStatement(&statement);

  }            

 if (!MIMER_SUCCEEDED(err) || !MIMER_SUCCEEDED(end_err)) {

printf("Error %d, end error %d.\n",err,end_err);

  }    

}

Memory Management

Throughout the Mimer API, routines are designed and implemented to allow callers not to worry about memory management. The rule is that the required buffers are allocated to their minimum size, and released as soon as they are not needed anymore.

For example, when starting a statement, information about its parameters, if it returns a result set, result set columns and their type are attached to the statement handle. This block of memory is released when the statement is released.

Memory for keeping parameters and result set columns are allocated either when the applications starts setting input parameters (see Data Input Routines), or when the statement is executed (MimerExecute), or the cursor is opened (MimerOpenCursor).

When the statement is executed, the database server reads the parameters that have been set, and if there are no result set or output parameters returned, the Mimer API will release the memory promptly. If there are output parameters, or result set data, memory to keep this information is retained until the statement or cursor is closed.

Header Files Provided

When using the Mimer API, the mimerapi.h header file should always be included. For example, this file declares the API routines and also the handle types to be used, i.e. MimerSession, MimerStatement, MimerLob and MimerHandle. In addition, it defines a number of symbols that can be used for a convenient and instructive C coding.

Other files that are provided are the mimerror.h and mimstdint.h files, which both are automatically included by the mimerapi.h file. The mimstdint.h file arranges the necessary measure for using the int16_t, int32_t and int64_t data types that are recommended for, and used by, the Mimer API. The mimerrors.h file defines C symbols for a couple of error codes that may be used when programming with the Mimer SQL C API, see Mimer SQL C API Return Codes.

C symbols used in example code are defined in these header files.

Mimer API Examples

The Mimer SQL distribution contains a set of complete Mimer API based example programs; mimerapiex1.c, mimerapiex2.c and mimerapiex3.c.

Querying the database

The following table is used in this example:

create table THE_IDENT.FIRST_TABLE (

  COL1 integer primary key,

  COL2 varchar(20));

 

The example is about retrieving all rows in the table THE_IDENT.FIRST_TABLE where COL1 is larger than a supplied integer value. The rows are returned in COL1 order.

int err=0;

MimerSession sessionhandle;

MimerStatement statementhandle;

wchar_t res1[100];

int res2;

unsigned char res3[100];

err = MimerBeginSession(L"THE_DATABASE",L"THE_IDENT",L"THE_PASSWORD",

                        &sessionhandle); // 1

if (!err) {

  err = MimerBeginStatement(sessionhandle,

  L"select COL1,COL2 from THE_IDENT.FIRST_TABLE where COL1 > ? ORDER BY COL1",

                            MIMER_FORWARD_ONLY,&statementhandle); // 2

  if (!err) {

    err =  MimerSetInt32(statementhandle,1,42); // 3

    if (!err) {

      err = MimerOpenCursor(statementhandle); // 4

      if (!err) {

        do {

          err = MimerFetch(statementhandle); // 5

          if (!err) {

            MimerGetInt32(statementhandle,1,&res2); // 6

            MimerGetString(statementhandle,2,res1,

                           sizeof(res1)/sizeof(res1[0]));

            // You probably want to do something useful with the result here.

         }

        } while (!err);

        MimerCloseCursor(statementhandle); // 7

      }

    }

    MimerEndStatement(&statementhandle); // 8

  }

  MimerEndSession(&sessionhandle); // 9

}

 

This is an example of retrieving data from a result set. The following major events occur:

1The MimerBeginSession call will start a session with the database. When a session is started we always specify which database ident (a database namespace) is the default. Above we use the THE_IDENT ident, which in practice means that we can refer to all database objects in that schema without the qualifying THE_IDENT.

2The next thing is that we prepare the SELECT statement for execution. This call will load the statement into memory, along with its metadata.

3This SELECT statement has one input parameter, an integer. This parameter is supplied, in this case 42.

4A cursor is opened using MimerOpenCursor. We are now ready to receive data from the database.

5Immediately when the cursor is opened, it is located before the first row (aka on row 0 of the result set). To advance the cursor position to the next row, we call MimerFetch.

6Once the fetch succeeded, we may retrieve data from the row. MimerFetch returns a non-zero value if an error occurred or the end of the result set was reached.

7When we have finished reading, the result set is closed.

8If we wish to do so, we may execute the query again by calling the appropriate data input functions, MimerOpenCursor, MimerFetch etc. again. But in this example we are done and will close things down. MimerEndStatement is called to release the resources held by the statement.

9Finally the database session is ended.

Retrieving a binary large object

The following table is used in this example.

create table PICTURES (

  ID int primary key default next value for id_sequence,

  CREATED timestamp,

  PICTURE blob);

 

In this example we have a table PICTURES with three columns; one primary key column, one column for creation timestamp and one column for a picture. We wish to return all pictures created within the last week, and with recent pictures first.

int err=0;

MimerSession sessionhandle;

MimerStatement statementhandle;

MimerLob blobhandle;

void *blobdata;

size_t bloblen;

int res2;

err = MimerBeginSession(L"THE_DATABASE",L"THE_IDENT",L"THE_PASSWORD",

                        &sessionhandle);

if (!err) {

  err = MimerBeginStatement(sessionhandle,

L"select CREATED,PICTURE from PICTURES where CREATED >= localtimestamp -interval'7' days order by CREATED desc",

                            MIMER_FORWARD_ONLY,&statementhandle);

  if (!err) {

    err = MimerOpenCursor(statementhandle);

    if (!err) {

      while (!err) {

        err = MimerFetch(statementhandle);

        if (!err) {

          MimerGetInt32(statementhandle,1,&res2);

          MimerGetLob(statementhandle,2,&bloblen,&blobhandle);

          blobdata = malloc(bloblen);

          if (blobdata) {

            err = MimerGetBlobData(&blobhandle,blobdata,bloblen);

            if (!err) {

            // You probably want to do something useful with the blob here

            }

            free(blobdata);

          }

        }

      }

      MimerCloseCursor(statementhandle);

    }

    MimerEndStatement(&statementhandle);

  }

  MimerEndSession(&sessionhandle);

}

Inserting a binary large object into the database

The following table is used in this example.

create table THIRD_TABLE (

  COL1 integer primary key,

  COL2 blob);

 

This example features binary large objects which are numbered. We have created a new object whose identity number is 42411 that we want to insert into the database.

int err=0;

MimerSession sessionhandle;

MimerStatement statementhandle;

MimerLob blobhandle;

char *blobdata;

int bloblen;

int param1 = 42411;

unsigned char res3[100];

// Below, the location of the binary large object data is obtained.

blobdata = _some_interesting_location_; // 1

bloblen = 47110;

err = MimerBeginSession(L"THE_DATABASE",L"THE_IDENT",L"THE_PASSWORD",

                        &sessionhandle);

if (!err) {

  err = MimerBeginStatement(sessionhandle,

            L"insert into THIRD_TABLE(COL1,COL2) values (?,?)",

            MIMER_FORWARD_ONLY,&statementhandle);

  if (!err) {

     MimerSetInt32(statementhandle,1,param1);

    err = MimerSetLob(statementhandle,2,bloblen,&blobhandle); // 2

    if (!err) {

      err = MimerSetBlobData(&blobhandle,&blobdata[0],10000); // 3

      err = MimerSetBlobData(&blobhandle,&blobdata[10000],10000);

      err = MimerSetBlobData(&blobhandle,&blobdata[20000],10000);

      err = MimerSetBlobData(&blobhandle,&blobdata[30000],10000);

      err = MimerSetBlobData(&blobhandle,&blobdata[40000],7110); // 4

      err = MimerExecute(statementhandle); // 5

    }

    MimerEndStatement(&statementhandle);

  }

  MimerEndSession(&sessionhandle);

}

 

The following interesting things takes place in this example:

1In some way we obtain the location and length of the data to store in the database.

2The process of storing the blob is started. The total size of the blob is supplied.

3In this case the object data is supplied in chunks of 10 000 bytes. MimerSetBlobData is therefore called five times. Error handling is omitted here for clarity.

Choosing the chunk size is a compromise between memory consumption and performance. If it is important to reduce memory usage, it may be appropriate to process the object sequentially in smaller pieces, rather than to read everything into memory.

4The final call to MimerSetBlobData supplies the remaining 7110 bytes.

5The actual INSERT operation is performed.

Scrolling through a result set

The following table is used in this example:

create table THE_IDENT.FIRST_TABLE (

  COL1 integer primary key,

  COL2 varchar(20));

 

This example is basically the same as in Querying the database, except that we are performing some scrolling operations on the result set. The number of rows in the result set in this example is 10.

Retrieve all rows in the table THE_IDENT.FIRST_TABLE whose primary key (an integer) is larger than a supplied value, and scroll through the result set.

int err=0;

MimerSession sessionhandle;

MimerStatement statementhandle;

int current_row;

err = MimerBeginSession(L"THE_DATABASE",L"THE_IDENT",L"THE_PASSWORD",

                        &sessionhandle);

if (!err) {

  err = MimerBeginStatement(sessionhandle,

  L"select COL1,COL2 from THE_IDENT.FIRST_TABLE where COL1 > ? ORDER BY COL1",

                            MIMER_SCROLLABLE,&statementhandle); // 2

  if (!err) {

    err =  MimerSetInt32(statementhandle,1,42);

    if (!err) {

      err = MimerOpenCursor(statementhandle);

      if (!err) {

        current_row = MimerCurrentRow(statementhandle); // current_row=0

        do {

          err = MimerFetchScroll(statementhandle,MIMER_NEXT,0); // 1

          current_row = MimerCurrentRow(statementhandle); // current_row=1

          [...]

          err = MimerFetchScroll(statementhandle,MIMER_RELATIVE,-3); // 2

          current_row = MimerCurrentRow(statementhandle); // current_row=0

          [...]

          err = MimerFetchScroll(statementhandle,MIMER_ABSOLUTE,10); // 3

          current_row = MimerCurrentRow(statementhandle); // current_row=10

          [...]

          err = MimerFetchScroll(statementhandle,MIMER_PREVIOUS,0); // 4

          current_row = MimerCurrentRow(statementhandle); // current_row=9

          [...]

          err = MimerFetchScroll(statementhandle,MIMER_ABSOLUTE,20); // 5

          current_row = MimerCurrentRow(statementhandle); // current_row=11

          [...]

          err = MimerFetchScroll(statementhandle,MIMER_LAST,0); // 6

          current_row = MimerCurrentRow(statementhandle); // current_row=10

          [...]

          err = MimerFetchScroll(statementhandle,MIMER_FIRST,0); // 7

          current_row = MimerCurrentRow(statementhandle); // current_row=1

          [...]

        } while (!err);

        MimerCloseCursor(statementhandle);

      }

    }

    MimerEndStatement(&statementhandle);

  }

  MimerEndSession(&sessionhandle);

}

 

1We scroll one row forward, into the first row of the result set. The current row is now 1.

2We now scroll three rows backwards. The current row is now before the result set. Even though we scroll three rows backwards, we cannot get further back than the row before the result set. The fetch call will return MIMER_NO_DATA and the current row is 0.

3Now, we scroll to the tenth row. The current row is now 10.

4One row backwards. The current row is now 9.

5We try to scroll to the twentieth row. Since there are only 10 rows in the result set, the scroll operation will return MIMER_NO_DATA, and the current row is now 11.

6We wish to see the last row. The current row is now 10.

7Now, we scroll back to the first row. The current row is now 1.

Mimer API Specification

The following routines are included in the Mimer API:

 

 

MimerAddBatch

Add the currently set parameters to the statement be executed on the next call to MimerExecute. If this call succeeds, the statement is ready to accept another set of parameters to be executed during the same server call. The benefit of executing several parameter sets at the same time is beneficial to performance.

Statements which may accept multiple parameter sets include DML statement and procedure calls, such as INSERT, UPDATE, DELETE and CALL. MimerAddBatch cannot be used with statements which return result sets.

Parameters

int32_t MimerAddBatch (

            MimerStatement statementhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerBeginSession

Starts a session with the database. (wchar_t version.)

Parameters

int32_t MimerBeginSession (

            const wchar_t *database,

            const wchar_t *ident,

            const wchar_t *password,

            MimerSession *sessionhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

A session handle may or may not have been returned. MimerEndSession should therefore always be called to avoid handle leaks.

Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerBeginSession8

Starts a session with the database. (UTF-8 version.)

Parameters

int32_t MimerBeginSession8 (

            const char *database,

            const char *ident,

            const char *password,

            MimerSession *sessionhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

A session handle may or may not have been returned. MimerEndSession should therefore always be called to avoid handle leaks.

Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerBeginSessionC

Starts a session with the database. (char version.)

Parameters

int32_t MimerBeginSessionC (

            const char *database,

            const char *ident,

            const char *password,

            MimerSession *sessionhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

A session handle may or may not have been returned. MimerEndSession should therefore always be called to avoid handle leaks.

Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerBeginStatement

Prepares an SQL statement for execution. (wchar_t version.)

Between the preparation and the time of execution, the application may supply any number of input parameters to be used when executing the statement.

The same statement does not need to be prepared again, even if it is executed multiple times. However, all input parameters have to be set again before each execution.

There is no need to prepare all statements at the start of the application.

Parameters

int32_t MimerBeginStatement (

            MimerSession sessionhandle,

            const wchar_t *sqlstatement,

            int32_t options,

            MimerStatement *statementhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerBeginStatement8

Prepares an SQL statement for execution. (UTF-8 version.)

Between the preparation and the time of execution, the application may supply any number of parameters to be used when executing the statement.

The same statement does not need to be prepared again, even if it is executed multiple times.

There is no need to prepare all statements at the start of the application.

Parameters

int32_t MimerBeginStatement8 (

            MimerSession sessionhandle,

            const char *sqlstatement,

            int32_t options,

            MimerStatement *statementhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerBeginStatementC

Prepares an SQL statement for execution. (char version.)

Between the preparation and the time of execution, the application may supply any number of parameters to be used when executing the statement.

The same statement does not need to be prepared again, even if it is executed multiple times.

There is no need to prepare all statements at the start of the application.

Parameters

int32_t MimerBeginStatementC (

            MimerSession sessionhandle,

            const char *sqlstatement,

            int32_t options,

            MimerStatement *statementhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerBeginTransaction

Starts a transaction.

This routine only needs to be called if two or more database operations should participate in the transaction. (If the transaction consists of one single operation, simply use the auto-commit functionality, which is the default. See Transactions.)

Parameters

int32_t MimerBeginTransaction (

            MimerSession sessionhandle,

            int32_t transoption)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Not Micro API compatible.

MimerCloseCursor

Closes an open cursor.

When the cursor is closed, all resources held by the result set are released.

After the cursor is closed, the cursor may either be reopened using a call to MimerOpenCursor or the statement should be released using a call to MimerEndStatement. Before the cursor is reopened, a new set of parameters may be supplied using any of the data input functions.

Parameters

int32_t MimerCloseCursor (MimerStatement statementhandle)

Returns

A negative value indicating an error, or zero if successful.

 

Notes

This routine interacts with the database server.

Micro API compatible.

MimerColumnCount

Obtains the number of columns in a result set.

Parameters

int32_t MimerColumnCount (MimerStatement statementhandle)

Returns

If zero or positive, the number of result set columns. If negative a standard Mimer error code.

 

Notes

Not Micro API compatible.

MimerColumnName

Obtains the name of a column. (wchar_t version.)

Parameters

int32_t MimerColumnName (

            MimerStatement statementhandle,

            int16_t column,

            wchar_t *columnname,

            size_t maxlen)

Returns

Returns the number of characters in the column name. If this value is larger than maxlen-1, a truncation occurred. If a negative value was returned, there was an error.

Notes

Not Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerColumnName8

Obtains the name of a column. (UTF-8 version.)

Parameters

int32_t MimerColumnName8 (

            MimerStatement statementhandle,

            int16_t column,

            char *columnname,

            size_t maxsiz)

Returns

Returns the size of the column name in bytes. If this value is larger than maxsiz-1, a truncation occurred. If a negative value was returned, there was an error.

Notes

Not Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerColumnNameC

Obtains the name of a column. (char version.)

Parameters

int32_t MimerColumnNameC (

            MimerStatement statementhandle,

            int16_t column,

            char *columnname,

            size_t maxsiz)

Returns

Returns the size of the column name in bytes. If this value is larger than maxsiz-1, a truncation occurred. If a negative value was returned, there was an error.

Notes

Not Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerColumnType

Returns the type of a column.

Parameters

int32_t MimerColumnType (

            MimerStatement statementhandle,

            int16_t column)

Returns

Returns the column type or a negative value if an error occurred.

Notes

Not Micro API compatible.

MimerCurrentRow

Returns the current row of a result set.

Parameters

int32_t MimerCurrentRow (MimerStatement statementhandle)

Returns

A negative value indicate an error code. Zero or a positive value indicates the current cursor position.

Notes

Not Micro API compatible.

MimerEndSession

Ends a database session.

If there are any active transactions, these are rollbacked.

Parameters

int32_t MimerEndSession (MimerSession *sessionhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

MimerEndStatement

Closes a prepared statement.

If there is an open cursor on this statement, it is automatically closed.

Parameters

int32_t MimerEndStatement (MimerStatement *statementhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

MimerEndTransaction

Commits or rollbacks a transaction.

Open cursors are automatically closed.

Parameters

int32_t MimerEndTransaction (

            MimerSession sessionhandle,

            int32_t commit_rollback)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Not Micro API compatible.

MimerExecute

Execute a statement that does not return a result set.

Statements that do not return a result set include data manipulation statements (INSERT, UPDATE, DELETE), assignments (SET) and procedure calls (CALL). (Statements that return a result set are handled using cursors. See Result set producing statements.)

Before calling MimerExecute, set all input parameters of the statement using data input routines. (See Data Input Routines.)

If this call returns successfully, any output parameters may be retrieved using data output routines. (See Data Output Routines.)

Parameters

int32_t MimerExecute (MimerStatement statementhandle)

Returns

A negative value indicating an error, or zero if successful. A positive value indicates an update row count returned by the database.

Notes

This routine interacts with the database server.

Micro API compatible.

MimerExecuteStatement

Executes a statement directly without parameters. (wchar_t version.)

This routine is mainly intended for data definition statements (e.g. CREATE TABLE), but can also be used for regular INSERT, UPDATE and DELETE statements with no input or output parameters.

Parameters

int32_t MimerExecuteStatement (

            MimerSession sessionhandle,

            const wchar_t *sqlstatement)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerExecuteStatement8

Executes a statement directly without parameters. (UTF-8 version.)

This routine is mainly intended for data definition statements (e.g. CREATE TABLE), but can also be used for regular INSERT, UPDATE and DELETE statements with no input or output parameters.

Parameters

int32_t MimerExecuteStatement8 (

            MimerSession sessionhandle,

            const char *sqlstatement)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerExecuteStatementC

Executes a statement directly without parameters. (char version.)

This routine is mainly intended for data definition statements (e.g. CREATE TABLE), but can also be used for regular INSERT, UPDATE and DELETE statements with no input or output parameters.

Parameters

int32_t MimerExecuteStatementC (

            MimerSession sessionhandle,

            const char *sqlstatement)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerFetch

Advances to the next row of the result set.

If the routine returns successfully, the current row has been advanced one row down the result set. Column data may be retrieved using data output routines.

Parameters

int32_t MimerFetch (MimerStatement statementhandle)

Returns

A negative value indicating an error, or zero if successful. A value of MIMER_NO_DATA indicates that the end of the result has been reached.

Notes

This routine interacts with the database server.

Micro API compatible.

MimerFetchScroll

Moves the current cursor position on a scrollable cursor.

A non-scrollable cursor (MIMER_FORWARD_ONLY) may only be read using scroll operation MIMER_NEXT.

Parameters

int32_t MimerFetchScroll (

            MimerStatement statementhandle,

            int32_t operation,

            int32_t offset)

Returns

A negative value indicating an error, or zero if successful. A value of MIMER_NO_DATA indicates that the end of the result has been reached.

Notes

This routine interacts with the database server.

Not Micro API compatible.

MimerFetchSkip

Advances to the next row of the result set but optionally skips a number of rows in the result set.

If the routine returns successfully, the current row has been advanced the specified number of rows down the result set. Column data may be retrieved using any of the data output functions.

Parameters

int32_t MimerFetchSkip (

            MimerStatement statementhandle,

            int32_t count)

Returns

A negative value indicating an error, or zero if successful. A value of MIMER_NO_DATA indicates that the end of the result has been reached.

Notes

This routine interacts with the database server.

Micro API compatible.

MimerGetBinary

Gets binary data from a result set or an output parameter.

Only SQL data types BINARY and BINARY VARYING may be retrieved using this routine.

Parameters

int32_t MimerGetBinary (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            void *dest,

            size_t dest_maxsiz)

Returns

A negative value indicating error, or a non-negative value indicating the number of bytes in the binary column.

Notes

Micro API compatible.

MimerGetBlobData

Retrieves the content of a binary large object.

If the binary large object is to be retrieved in multiple chunks, chunks are retrieved in sequence, where the length of each chunk is specified by the length parameter of each call to this routine. Chunks may only be retrieved sequentially through the binary large object.

Parameters

int32_t MimerGetBlobData (

            MimerLob *blobhandle,

            void *data,

            size_t size)

Returns

A negative value indicating error, or a non-negative value indicating the number of bytes available to return.

Notes

This routine interacts with the database server.

Not Micro API compatible.

MimerGetBoolean

Gets boolean data from a result set or an output parameter.

Only the database data type BOOLEAN may be retrieved using this call.

Parameters

int32_t MimerGetBoolean (

            MimerStatement statementhandle,

            int16_t paramno_colno)

Returns

The value 0 for FALSE, the value 1 for TRUE, or a negative value indicating an error.

Notes

Micro API compatible.

MimerGetDouble

Gets double precision floating point data from a result set or an output parameter.

Only the SQL data types DOUBLE PRECISION and REAL may be retrieved using this call.

Parameters

int32_t MimerGetDouble (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            double *value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Not Micro API compatible.

MimerGetFloat

Gets single precision floating point data from a result set or an output parameter.

Only the SQL data types DOUBLE PRECISION and REAL may be retrieved using this call.

Parameters

int32_t MimerGetFloat (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            double *value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerGetInt32

Gets integer data from a result set or an output parameter.

Only the SQL data types INTEGER, BIGINT and SMALLINT may be get using this call.

Parameters

int32_t MimerGetInt32 (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            int32_t *value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerGetInt64

Gets int64_t integer data from a result set or an output parameter.

Only the SQL data types INTEGER, BIGINT and SMALLINT may be retrieved using this call.

Parameters

int32_t MimerGetInt64 (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            int64_t *value)

 

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerGetLob

Obtains a large object handle.

Only the SQL data types BINARY LARGE OBJECT, CHARACTER LARGE OBJECT and NATIONAL CHARACTER LARGE OBJECT may be retrieved using this call.

Whenever a large object is about to retrieved from the database, this routine obtains the object from the result set row, and the length is returned. Subsequent calls to MimerGetBlobData or MimerGetNclobData retrieves the actual object from the database.

If there are any other open large object handles on this statement, these are closed before returning the new one.

Note that if this routine returns a size or length of 0, it is strictly not required to call the MimerGetBlobData or MimerGetNclobData routines for the large object contents, thus a database server round-trip may be saved.

Parameters

int32_t MimerGetLob (

            MimerStatement statementhandle,

            int16_t colno,

            size_t *size_length,

            MimerLob *lobhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

Not Micro API compatible.

MimerGetNclobData

Retrieves the contents of a character large object. (wchar_t version.)

A character large object may be retrieved in one or more chunks.

If the character large object is to be retrieved in multiple chunks, chunks are retrieved in sequence, where the length of each chunk is specified by the length parameter of each call to this routine. Chunks may only be retrieved sequentially through the character large object.

Parameters

int32_t MimerGetNclobData (

            MimerLob *clobhandle,

            wchar_t *data,

            size_t size)

Returns

A negative value indicating error, or a non-negative value indicating the number of characters available to return. This includes the number of characters returned in this call (excluding terminating null) and all data that are left in the character object. When the returned value is less than the length input parameter, all data of the character object has been returned.

This value may be used to calculate how many characters (excluding terminating zero) that were returned using this formula:

returned_characters = min(length_input_parameter-1,return_value)

 

The following formula may be used to calculate the number of characters left to return:

left_to_return = return_value-length_input_parameter+1

 

Notes

This routine interacts with the database server.

Not Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerGetNclobData8

Retrieves the contents of a character large object. (UTF-8 version.)

A character large object may be retrieved in one or more chunks.

If the character large object is to be retrieved in multiple chunks, chunks are retrieved in sequence, where the length of each chunk is specified by the length parameter of each call to this routine. Chunks may only be retrieved sequentially through the character large object.

Parameters

int32_t MimerGetNclobData8 (

            size_t *returned,

            MimerLob clobhandle,

            char *data,

            size_t size)

Returns

A negative value indicating error, or a non-negative value indicating the number of characters available to return. This includes the number of characters returned in this call (excluding terminating null) and all data that are left in the character object. When the returned value is less than the length input parameter, all data of the character object has been returned.

This value may be used to calculate how many characters (excluding terminating null) that were returned using this formula:

returned_characters = min(length_input_parameter-1,return_value)

 

The following formula may be used to calculate the number of characters left to return:

left_to_return = return_value-length_input_parameter+1

 

Notes

This routine interacts with the database server.

Not Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerGetNclobDataC

Retrieves the contents of a character large object. (char version.)

A character large object may be retrieved in one or more chunks.

If the character large object is to be retrieved in multiple chunks, chunks are retrieved in sequence, where the length of each chunk is specified by the length parameter of each call to this routine. Chunks may only be retrieved sequentially through the character large object.

Parameters

int32_t MimerGetNclobDataC (

            size_t *returned,

            MimerLob clobhandle,

            char *data,

            size_t size)

Returns

A negative value indicating error, or a non-negative value indicating the number of characters available to return. This includes the number of characters returned in this call (excluding terminating null) and all data that are left in the character object. When the returned value is less than the length input parameter, all data of the character object has been returned.

This value may be used to calculate how many characters (excluding terminating null) that were returned using this formula:

returned_characters = min(length_input_parameter-1,return_value)

 

The following formula may be used to calculate the number of characters left to return:

left_to_return = return_value-length_input_parameter+1

 

Notes

This routine interacts with the database server.

Not Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerGetStatistics

Obtains server statistics information.

Statistics is returned in the form of counters. Counters may either be an absolute value representing the current status or a monotonically increasing value representing the number of occurred events since the server started. An example of the former is current number of users and an example of the latter is number of server page requests.

The available counter values are:

 

Parameters

int32_t MimerGetStatistics (

            MimerSession sessionhandle,

            int32_t *counters,

            int16_t nr_of_counters)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

MimerGetString

Gets character data from a result set or an output parameter. (wchar_t version.)

Only the SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER and NATIONAL CHARACTER VARYING may be retrieved using this function.

Parameters

int32_t MimerGetString (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            wchar_t *dest,

            size_t dest_maxlen)

Returns

A negative value indicating an error, or a zero or positive value indicating the number of characters in the column (not counting the terminating zero).

Notes

Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerGetString8

Gets character data from a result set or an output parameter into a multi byte character string, where the character set is UTF-8.

Only the SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER and NATIONAL CHARACTER VARYING may be retrieved using this function.

Parameters

int32_t MimerGetString8 (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            char *dest,

            size_t dest_maxsiz)

Returns

A negative value indicating an error, or a zero or positive value indicating the number of bytes in the column (not counting the terminating zero).

Notes

Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerGetStringC

Gets character data from a result set or an output parameter into a multi byte character string, where the character set is defined by the current locale. (char version.)

Only the SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER and NATIONAL CHARACTER VARYING may be retrieved using this function.

Parameters

int32_t MimerGetStringC (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            char *dest,

            size_t dest_maxsiz)

Returns

A negative value indicating an error, or a zero or positive value indicating the number of bytes in the column (not counting the terminating zero).

Notes

Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerGetUUID

Gets a Universally unique identifier from a result set or output parameter. Only the SQL data type BUILTIN.UUID can be retrieved using this function.

Parameters

int32_t MimerGetUUID (

            MimerStatement statementhandle,

            int16_t paramno_colno,

            unsigned char uuid[16])

Returns

A negative value indicating an error or zero indicating success.

Notes

Micro API compatible.

MimerIsNull

Checks if a result set column or output parameter has the SQL null value.

Parameters

int32_t MimerIsNull (

            MimerStatement statementhandle,

            int16_t paramno_colno)

Returns

If the column or parameter is the SQL null value, a positive value is returned. If it is not the SQL null value zero is returned. If an error occurred, a negative error code is returned.

Notes

Micro API compatible.

MimerNext

Advances the current row to the next row, but only within the current array.

If the end of the array is reached, end of data is returned, and a new request must be made to the server for additional rows.

The difference between calling this function and MimerFetch or MimerFetchSkip is that this routine is guaranteed to never make server requests and therefore guaranteed not to require any context switches.

Parameters

int32_t MimerNext (MimerStatement statementhandle)

Returns

Returns MIMER_SUCCESS if the row was advanced one row. MIMER_NO_DATA was returned if the end of the array was reached.

Notes

Not Micro API compatible.

MimerOpenCursor

Opens a cursor to be used when reading a result set.

Result sets are produced either by SELECT queries, or by calls to result set procedures.

All input parameters must be set prior to calling MimerOpenCursor, or else an error will occur.

If this routine returns successfully, the cursor is opened and positioned before the first row.

The first row can then be fetched by calling MimerFetch. After that column data may be retrieved using data output routines.

If the statement does not return a result set, this routine will return with a failure.

Parameters

int32_t MimerOpenCursor (MimerStatement statementhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerParameterCount

Obtains the number of parameters of a statement.

Parameters

int32_t MimerParameterCount (MimerStatement statementhandle)

Returns

If zero or positive, the number of parameters. If negative a standard Mimer error code.

Notes

Not Micro API compatible.

MimerParameterMode

Detects the input/output mode of a parameter.

Parameters

int32_t MimerParameterMode (

            MimerStatement statementhandle,

            int16_t paramno)

Returns

If zero or positive, the number of parameters. If negative a standard Mimer error code.

Notes

Not Micro API compatible.

MimerParameterName

Obtains the name of a parameter. (wchar_t version.)

Parameters

int32_t MimerParameterName (

            MimerStatement statementhandle,

            int16_t parameter,

            wchar_t *parametername,

            size_t maxlen)

Returns

Returns the number of characters in the parameter name. If this value is larger than maxlen-1, a truncation occurred. If a negative value was returned, there was an error.

Notes

Not Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerParameterName8

Obtains the name of a parameter. (UTF-8 version.)

Parameters

int32_t MimerParameterName8 (

            MimerStatement statementhandle,

            int16_t parameter,

            char *parametername,

            size_t maxsize)

Returns

Returns the number of bytes in the parameter name. If this value is larger than maxsize-1, a truncation occurred. If a negative value was returned, there was an error.

Notes

Not Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerParameterNameC

Obtains the name of a parameter. (char version.)

Parameters

int32_t MimerParameterNameC (

            MimerStatement statementhandle,

            int16_t parameter,

            char *parametername,

            size_t maxsize)

Returns

Returns the number of bytes in the parameter name. If this value is larger than maxsize-1, a truncation occurred. If a negative value was returned, there was an error.

Notes

Not Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerParameterType

Obtains the data type of a parameter.

Parameters

int32_t MimerParameterType(

            MimerStatement statementhandle,

            int16_t parameter)

Returns

Returns the parameter type or a negative value if an error occurred.

Notes

Not Micro API compatible.

MimerRowSize

Returns the maximum number of bytes required to hold one row of data. This routine might be used to calculate the maximum number of rows allowed in an array fetching scenario under certain memory restrictions.

For example, if it was determined that the fetching buffer must use no more than 20 000 bytes, although it would be desirable to use array fetching for performance reasons, calling this function would obtain a value to divide 20 000 with obtaining a reasonable maximum array set size.

Parameters

int32_t MimerRowSize (MimerStatement statementhandle)

Returns

If positive, the minimum number of bytes required to be guaranteed to hold one row of data. If negative, an error condition.

Notes

Not Micro API compatible.

MimerSetArraySize

Set the array size.

By default the Mimer API routines MimerFetch and MimerFetchSkip uses an internal fetch buffer equal to the maximum size of one row. Depending on the actual size of the data, this buffer may hold more than one row. By increasing the array size, more data is retrieved in each server request.

Parameters

int32_t MimerSetArraySize (

            MimerStatement statementhandle,

            int32_t arraysize)

Returns

MIMER_SUCCESS if successful. A negative value indicate an error.

Notes

Not Micro API compatible.

MimerSetBinary

Sets a binary data parameter.

Only the SQL types BINARY and BINARY VARYING may be set using this call.

This routine may allocate additional memory to hold the parameter value, along with future output parameters and result set columns. This memory is freed when it is no longer needed, no later than when MimerEndStatement is called. This memory is also freed after a call to MimerExecute and MimerCloseCursor if there were no output parameters or result set columns.

Parameters

int32_t MimerSetBinary (

            MimerStatement statementhandle,

            int16_t param_no,

            const void *value,

            size_t size)

Returns

A negative value indicating an error, or zero if successful.

Notes

Not Micro API compatible.

MimerSetBlobData

Sets the data of a binary large object.

Whenever a binary large object has been created using a call to MimerSetLob, it has to be filled with data. This is done using a call to this routine. A call to this routine must always be preceded by a call to MimerSetLob.

The total length of all the chunks supplied by one or more calls to this routine must coincide with the length supplied in the preceding call to MimerSetLob, or else an error will occur.

When the entire binary large object has been set, the handle is automatically released.

Parameters

int32_t MimerSetBlobData (

            MimerLob *blobhandle,

            const void *data,

            size_t size)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Not Micro API compatible.

MimerSetBoolean

Sets a boolean data parameter.

Only the database type BOOLEAN may be set using this call.

Parameters

int32_t MimerSetBoolean (

            MimerStatement statementhandle,

            int16_t param_no,

            int32_t value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerSetDouble

Sets a double precision floating point parameter.

Only the SQL data types REAL and DOUBLE PRECISION may be set using this call.

This routine may allocate additional memory to hold the parameter value, along with future output parameters and result set columns. This memory is freed when it is no longer needed, no later than when MimerEndStatement is called. This memory is also freed after a call to MimerExecute and MimerCloseCursor if there were no output parameters or result set columns.

Parameters

int32_t MimerSetDouble (

            MimerStatement statementhandle,

            int16_t param_no,

            double value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerSetFloat

Sets a single precision floating point parameter.

Only the SQL data types REAL and DOUBLE PRECISION may be set using this call.

This routine may allocate additional memory to hold the parameter value, along with future output parameters and result set columns. This memory is freed when it is no longer needed, no later than when MimerEndStatement is called. This memory is also freed after a call to MimerExecute and MimerCloseCursor if there were no output parameters or result set columns.

Parameters

int32_t MimerSetFloat (

            MimerStatement statementhandle,

            int16_t param_no,

            float value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerSetInt32

Sets an integer parameter.

Only the SQL data types INTEGER, BIGINT and SMALLINT may be set using this call.

This routine may allocate additional memory to hold the parameter value, along with future output parameters and result set columns. This memory is freed when it is no longer needed, no later than when MimerEndStatement is called. This memory is also freed after a call to MimerExecute and MimerCloseCursor if there were no output parameters or result set columns.

Parameters

int32_t MimerSetInt32 (

            MimerStatement statementhandle,

            int16_t param_no,

            int32_t value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerSetInt64

Sets an int64_t (long long) parameter.

Only the SQL data types INTEGER, BIGINT and SMALLINT may be set using this call.

This routine may allocate additional memory to hold the parameter value, along with future output parameters and result set columns. This memory is freed when it is no longer needed, no later than when MimerEndStatement is called. This memory is also freed after a call to MimerExecute and MimerCloseCursor if there were no output parameters or result set columns.

Parameters

int32_t MimerSetInt64 (

            MimerStatement statementhandle,

            int16_t param_no,

            int64_t value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerSetLob

Sets a large object in the database.

This routine is used to create a large object (BINARY LARGE OBJECT, a CHARACTER LARGE OBJECT, or a NATIONAL CHARACTER LARGE OBJECT) in the database.

Whenever a large object is about to the inserted in the database as a parameter to a statement, this routine is called for that specific parameter.

Upon successful return, a handle to a large object is stored in the database. The contents of the object may be set at a later time using one or more calls to MimerSetBlobData or MimerSetNclobData.

If the size/length of the object is 0, MimerSetBlobData or MimerSetNclobData need not be called. If the size is larger than 0, MimerSetBlobData or MimerSetNclobData must be called to complete the creation of the large object.

To set the parameter to the SQL null value, use the MimerSetNull function.

Parameters

int32_t MimerSetLob (

            MimerStatement statementhandle,

            int16_t param_no,

            size_t size_length,

            MimerLob *lobhandle)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerSetNclobData

Sets the data of a character large object. (wchar_t version.)

Whenever a character large object has been created using a call to MimerSetLob, it has to be filled with data. This is done using a call to this routine. A call to this routine must always be preceded by a call to MimerSetLob.

When the entire character large object has been set, the handle is automatically released.

Parameters

int32_t MimerSetNclobData (

            MimerLob *clobhandle,

            const wchar_t *data,

            size_t length)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Not Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetNclobData8

Sets the data of a character large object. (UTF-8 version.)

Whenever a character large object has been created using a call to MimerSetLob, it has to be filled with data. This is done using a call to this routine. A call to this routine must always be preceded by a call to MimerSetLob.

When the entire character large object has been set, the handle is automatically released.

Parameters

int32_t MimerSetNclobData8 (

            MimerLob *clobhandle,

            const char *data,

            size_t size)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Not Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetNclobDataC

Sets the data of a character large object using a multibyte character pointer. (char version.)

Whenever a character large object has been created using a call to MimerSetLob, it has to be filled with data. This is done using a call to this routine. A call to this routine must always be preceded by a call to MimerSetLob.

When the entire character large object has been set, the handle is automatically released.

Parameters

int32_t MimerSetNclobDataC (

            MimerLob *clobhandle,

            const char *data,

            size_t size)

Returns

A negative value indicating an error, or zero if successful.

Notes

This routine interacts with the database server.

Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetNull

Sets an input parameter to the SQL null value.

Parameters

int32_t MimerSetNull (

            MimerStatement statementhandle,

            int16_t paramno)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

MimerSetString

Sets a string parameter. (wchar_t version.)

This call sets a string parameter of a statement call. The SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL and NUMERIC may be set using this call.

Parameters

int32_t MimerSetString (

            MimerStatement statementhandle,

            int16_t param_no,

            const wchar_t *value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetString8

Sets a string parameter using a UTF-8 character string.

The SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL and NUMERIC may be set using this call.

Parameters

int32_t MimerSetString8 (

            MimerStatement statementhandle,

            int16_t param_no,

            const char *value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetStringC

Sets a string parameter using a multibyte character string.

The SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL and NUMERIC may be set using this call.

Parameters

int32_t MimerSetStringC (

            MimerStatement statementhandle,

            int16_t param_no,

            const char *value)

Returns

A negative value indicating an error, or zero if successful.

Notes

Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetStringLen

Sets a string parameter. (wchar_t version.)

This call sets a string parameter of a statement call. The SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL and NUMERIC may be set using this call.

Parameters

int32_t MimerSetStringLen (

            MimerStatement statementhandle,

            int16_t param_no,

            const wchar_t *value,

            size_t length)

Returns

A negative value indicating an error, or zero if successful.

Notes

Not Micro API compatible.

wchar_t version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetStringLen8

Sets a string parameter using a UTF-8 character string. (UTF-8 version.)

The SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL and NUMERIC may be set using this call.

Parameters

int32_t MimerSetStringLen8 (

            MimerStatement statementhandle,

            int16_t param_no,

            const char *value,

            size_t length)

Returns

A negative value indicating an error, or zero if successful.

Notes

Not Micro API compatible.

UTF-8 version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetStringLenC

Sets a string parameter using a multibyte character pointer. (char version.)

The SQL data types CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL and NUMERIC may be set using this call.

Parameters

int32_t MimerSetStringLenC (

            MimerStatement statementhandle,

            int16_t param_no,

            const char *value,

            size_t length)

Returns

A negative value indicating an error, or zero if successful.

Notes

Not Micro API compatible.

char version of the routine. See Character String Formats for more information about character formats and the different routine versions.

MimerSetUUID

Sets a Universally unique identifier parameter. Only the SQL data type BUILTIN.UUID can be set using this function.

Parameters

int32_t MimerSetUUID (

            MimerStatement statementhandle,

            int16_t param_no,

            const unsigned char uuid[16])

Returns

A negative value indicating an error or zero indicating success.

Notes

Micro API compatible.