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.

Data type

SQL data type

MIMER_BINARY

BINARY

MIMER_BINARY_VARYING

BINARY VARYING

MIMER_BLOB

BINARY LARGE OBJECT

MIMER_BOOLEAN

BOOLEAN

MIMER_CHARACTER

CHARACTER

MIMER_CHARACTER_VARYING

CHARACTER VARYING

MIMER_CLOB

CHARACTER LARGE OBJECT

MIMER_DATE *

DATE

MIMER_DECIMAL *

DECIMAL

MIMER_FLOAT *

FLOAT(p)

MIMER_INTEGER

INTEGER(p)

MIMER_INTERVAL_DAY *

INTERVAL DAY

MIMER_INTERVAL_DAY_TO_HOUR *

INTERVAL DAY TO HOUR

MIMER_INTERVAL_DAY_TO_MINUTE *

INTERVAL DAY TO MINUTE

MIMER_INTERVAL_DAY_TO_SECOND *

INTERVAL DAY TO SECOND

MIMER_INTERVAL_HOUR *

INTERVAL HOUR

MIMER_INTERVAL_HOUR_TO_MINUTE *

INTERVAL HOUR TO MINUTE

MIMER_INTERVAL_HOUR_TO_SECOND *

INTERVAL HOUR TO SECOND

MIMER_INTERVAL_MINUTE *

INTERVAL MINUTE

MIMER_INTERVAL_MINUTE_TO_SECOND *

INTERVAL MINUTE TO SECOND

MIMER_INTERVAL_MONTH *

INTERVAL MONTH

MIMER_INTERVAL_SECOND *

INTERVAL SECOND

MIMER_INTERVAL_YEAR *

INTERVAL YEAR

MIMER_INTERVAL_YEAR_TO_MONTH *

INTERVAL YEAR TO MONTH

MIMER_NCHAR

NATIONAL CHARACTER

MIMER_NCHAR_VARYING

NATIONAL CHARACTER VARYING

MIMER_NCLOB

NATIONAL CHARACTER LARGE OBJECT

MIMER_T_BIGINT

BIGINT

MIMER_T_DOUBLE

DOUBLE PRECISION

MIMER_T_FLOAT

FLOAT

MIMER_T_INTEGER

INTEGER

MIMER_T_REAL

REAL

MIMER_T_SMALLINT

SMALLINT

MIMER_TIME *

TIME

MIMER_TIMESTAMP *

TIMESTAMP

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.

SQL data type

Routines

BIGINT

MimerGetInt64

MimerSetInt64

BINARY

MimerGetBinary

MimerSetBinary

BINARY LARGE OBJECT

MimerGetLob

MimerGetBlobData

MimerSetLob

MimerSetBlobData

BINARY VARYING

MimerGetBinary

MimerSetBinary

BOOLEAN

MimerGetBoolean

MimerSetBoolean

CHARACTER

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

CHARACTER LARGE OBJECT

MimerGetLob

MimerGetNclobData

MimerGetNclobData8

MimerGetNclobDataC

MimerSetLob

MimerSetNclobData

MimerSetNclobData8

MimerSetNclobDataC

CHARACTER VARYING

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

DATE

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

DECIMAL

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

DOUBLE PRECISION

MimerGetDouble

MimerSetDouble

INTEGER

MimerGetInt32

MimerGetInt64

MimerSetInt32

MimerSetInt64

NATIONAL CHARACTER

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

NATIONAL CHARACTER LARGE OBJECT

MimerGetLob

MimerGetNclobData

MimerGetNclobData8

MimerGetNclobDataC

MimerSetLob

MimerSetNclobData

MimerSetNclobData8

MimerSetNclobDataC

NATIONAL CHARACTER VARYING

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

NUMERIC

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

REAL

MimerGetDouble

MimerGetFloat

MimerSetDouble

MimerSetFloat

SMALLINT

MimerGetInt32

MimerGetInt64

MimerSetInt32

MimerSetInt64

TIME

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

TIMESTAMP

MimerGetString

MimerGetString8

MimerGetStringC

MimerSetString

MimerSetString8

MimerSetStringC

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:

Macro

Description

MimerIsBinary(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetBinary or MimerSetBinary.

MimerIsBlob(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetBlobData or MimerSetBlobData.

MimerIsBoolean(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetBoolean or MimerSetBoolean.

MimerIsClob(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetNclobData[C|8] or MimerSetNclobData[C|8].

MimerIsDouble(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetDouble or MimerSetDouble.

MimerIsFloat(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetFloat or MimerSetFloat.

MimerIsInt32(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetInt32 or MimerSetInt32.

MimerIsInt64(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetInt64 or MimerSetInt64.

MimerIsString(t)

Will yield true if the type (t) can be accessed or manipulated using MimerGetString[C|8] or MimerSetString[C|8].

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:

Routine

Description

Micro API compatible

MimerAddBatch

Add currently set parameters to statement.

Yes

MimerBeginSession

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

Yes

MimerBeginSession8

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

 

MimerBeginSessionC

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

Yes

MimerBeginStatement

Prepares a statement for execution. (wchar_t version.)

Yes

MimerBeginStatement8

Prepares a statement for execution. (UTF-8 version.)

 

MimerBeginStatementC

Prepares a statement for execution. (char version.)

Yes

MimerBeginTransaction

Starts a transaction.

 

MimerCloseCursor

Closes an open cursor.

Yes

MimerColumnCount

Obtains the number of columns in a result set.

 

MimerColumnName

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

 

MimerColumnName8

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

 

MimerColumnNameC

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

 

MimerColumnType

Returns the type of a column.

 

MimerCurrentRow

Returns the current row of a result set.

 

MimerEndSession

Ends a database session.

Yes

MimerEndStatement

Closes a prepared statement.

Yes

MimerEndTransaction

Commits or rollbacks a transaction.

 

MimerExecute

Executes a statement that does not return a result set.

Yes

MimerExecuteStatement

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

Yes

MimerExecuteStatement8

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

 

MimerExecuteStatementC

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

Yes

MimerFetch

Advances to the next row of the result set.

Yes

MimerFetchScroll

Moves the current cursor position on a scrollable cursor.

 

MimerFetchSkip

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

Yes

MimerGetBinary

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

Yes

MimerGetBlobData

Retrieves the content of a binary large object.

 

MimerGetBoolean

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

Yes

MimerGetDouble

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

Yes

MimerGetFloat

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

Yes

MimerGetInt32

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

Yes

MimerGetInt64

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

Yes

MimerGetLob

Obtains a large object handle.

 

MimerGetNclobData

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

 

MimerGetNclobData8

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

 

MimerGetNclobDataC

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

 

MimerGetStatistics

Obtains server statistics information.

Yes

MimerGetString

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

Yes

MimerGetString8

Gets character data from a result set or an output parameter. (UTF-8 version.)

 

MimerGetStringC

Gets character data from a result set or an output parameter into a multi byte character string. (char version.)

Yes

MimerGetUUID

Gets a Universally unique identifier from a result set or output parameter.

Yes

MimerIsNull

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

Yes

MimerNext

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

 

MimerOpenCursor

Opens a result set.

Yes

MimerParameterCount

Returns the number of parameters for a statement.

 

MimerParameterMode

Detects the input/output mode of a parameter.

 

MimerParameterName

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

 

MimerParameterName8

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

 

MimerParameterNameC

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

 

MimerParameterType

Obtains the data type of a parameter.

 

MimerSetArraySize

Sets the number of bytes to fetch in each server request.

 

MimerSetBinary

Sets a binary data parameter.

Yes

MimerSetBlobData

Sets the data of a binary large object.

 

MimerSetBoolean

Sets a boolean data parameter.

Yes

MimerSetDouble

Sets a double precision floating point parameter.

Yes

MimerSetFloat

Sets a single precision floating point parameter.

Yes

MimerSetInt32

Sets an int32_t integer parameter.

Yes

MimerSetInt64

Sets an int64_t integer parameter.

Yes

MimerSetLob

Sets a large object in the database.

 

MimerSetNclobData

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

 

MimerSetNclobData8

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

 

MimerSetNclobDataC

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

 

MimerSetNull

Sets an input parameter to the SQL null value.

Yes

MimerSetString

Sets a string parameter. (wchar_t version.)

Yes

MimerSetString8

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

 

MimerSetStringC

Sets a string parameter. (char version.)

Yes

MimerSetStringLen

Sets a string parameter. (wchar_t version.)

 

MimerSetStringLen8

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

 

MimerSetStringLenC

Sets a string parameter. (char version.)

 

MimerSetUUID

Sets a Universally unique identifier parameter.

Yes

 

 

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)

statementhandle

in

The statement whose parameters to batch.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

The statement was not ready to accept parameters.

MIMER_UNSET_PARAMETERS

All input parameters have not yet been set.

MIMER_OUT_OF_MEMORY

Enough memory to hold an additional set of parameters could not be allocated.

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)

database

in

The name of the database to connect to. If this is null, a connection to the default database is created.

ident

in

The ident associated with the session to create. This parameter may not be null.

password

in

The password of the ident. A null value is identical to a zero length password. Database servers which do not enforce authentication control may ignore the password.

sessionhandle

out

A session handle identifying the session when calling MimerEndSession, MimerBeginStatement, MimerBeginStatement8, MimerBeginStatementC, MimerBeginTransaction, MimerExecuteStatement, MimerExecuteStatement8, MimerExecuteStatementC and MimerEndTransaction.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_OUTOFMEMORY

Out of memory.

MIMER_ILLEGAL_CHARACTER

One of the string parameters database, ident or password contained an illegal character.

< 0

Any of the server error codes listed in Return Codes.

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)

database

in

The name of the database to connect to. If this is null, a connection to the default database is created.

ident

in

The ident associated with the session to create. This parameter may not be null.

password

in

The password of the ident. A null value is identical to a zero length password. Database servers which do not enforce authentication control may ignore the password.

sessionhandle

out

A session handle identifying the session when calling MimerEndSession, MimerBeginStatement, MimerBeginStatement8, MimerBeginStatementC, MimerBeginTransaction, MimerExecuteStatement, MimerExecuteStatement8, MimerExecuteStatementC and MimerEndTransaction.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_OUTOFMEMORY

Out of memory.

MIMER_ILLEGAL_CHARACTER

One of the string parameters database, ident or password contained an illegal character.

< 0

Any of the server error codes listed in Return Codes.

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)

database

in

The name of the database to connect to. If this is null, a connection to the default database is created.

ident

in

The ident associated with the session to create. This parameter may not be null.

password

in

The password of the ident. A null value is identical to a zero length password. Database servers which do not enforce authentication control may ignore the password.

sessionhandle

out

A session handle identifying the session when calling MimerEndSession, MimerBeginStatement, MimerBeginStatement8, MimerBeginTransaction, MimerExecuteStatement, MimerExecuteStatement8, MimerExecuteStatementC and MimerEndTransaction.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_OUTOFMEMORY

Out of memory.

MIMER_ILLEGAL_CHARACTER

One of the string parameters database, ident or password contained an illegal character.

< 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C], identifying the session.

sqlstatement

in

SQL statement string.

options

in

A bit mask of options identifying the characteristics of the statement. The following values specifies a cursor being scrollable, or forward only:

MIMER_FORWARD_ONLY (0x0)

MIMER_SCROLLABLE (0x1)

A value of 0 will indicate MIMER_FORWARD_ONLY.

statementhandle

out

A handle to the statement is returned here.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_ILLEGAL_CHARACTER

The statement string contained an illegal character.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_STATEMENT_CANNOT_BE_PREPARED

The statement was a DDL statement which cannot be prepared. Such statements should be executed using MimerExecuteStatement.

MIMER_TRUNCATION_ERROR

The statement string was too long.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C], identifying the session.

sqlstatement

in

SQL statement string.

options

in

A bit mask of options identifying the characteristics of the statement. The following values specifies a cursor being scrollable, or forward only:

MIMER_FORWARD_ONLY (0x0)

MIMER_SCROLLABLE (0x1)

A value of 0 will indicate MIMER_FORWARD_ONLY.

statementhandle

out

A handle to the statement is returned here.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_ILLEGAL_CHARACTER

The statement string contained an illegal character.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_STATEMENT_CANNOT_BE_PREPARED

The statement was a DDL statement which cannot be prepared. Such statements should be executed using MimerExecuteStatement.

MIMER_TRUNCATION_ERROR

The statement string was too long.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C], identifying the session.

sqlstatement

in

SQL statement string.

options

in

A bit mask of options identifying the characteristics of the statement. The following values specifies a cursor being scrollable, or forward only:

MIMER_FORWARD_ONLY (0x0)

MIMER_SCROLLABLE (0x1)

A value of 0 will indicate MIMER_FORWARD_ONLY.

statementhandle

out

A handle to the statement is returned here.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_ILLEGAL_CHARACTER

The statement string contained an illegal character.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_STATEMENT_CANNOT_BE_PREPARED

The statement was a DDL statement which cannot be prepared. Such statements should be executed using MimerExecuteStatement.

MIMER_TRUNCATION_ERROR

The statement string was too long.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C|8], identifying the session.

transoption

in

A bit mask of options identifying the characteristics of the transaction. The following values specifies a transaction being read/write, or read only:

MIMER_TRANS_READWRITE (0x0)

MIMER_TRANS_READONLY (0x1)

A value of 0 will indicate MIMER_TRANS_READWRITE.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open.

Other value < 0

Any of the server error codes listed in Return Codes.

 

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

Returns

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

Return value

Description

>= 0

The number of result set columns.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

The statement is not compiled.

Other value < 0

Any of the server error codes listed in Return Codes.

 

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

column

in

The column number, where the leftmost column is 1.

columnname

out

The area where to return the column name. The maximum column name length returned is maxlen-1.

maxlen

in

The size of the columnname area.

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.

Return value

Description

>= 0

Length of column name (in characters)

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

Statement is not compiled

MIMER_NONEXISTENT_COLUMN_PARAMETER

The column number does not exist

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

column

in

The column number, where the leftmost column is 1.

columnname

out

The are where to return the column name. The maximum column name length returned is maxsiz-1.

maxsiz

in

The size of the columnname area.

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.

Return value

Description

>= 0

Length of column name (in characters)

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

Statement is not compiled.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The column number does not exist.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

column

in

The column number, where the leftmost column is 1.

columnname

out

The are where to return the column name. The maximum column name length returned is maxsiz-1.

maxsiz

in

The size of the columnname area.

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.

Return value

Description

>= 0

Length of column name (in characters)

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

Statement is not compiled.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The column number does not exist.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

column

in

The column number, where the leftmost column is 1.

Returns

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

Return value

Description

> 0

Data type. See list in Data Types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

Statement is not compiled

MIMER_NONEXISTENT_COLUMN_PARAMETER

The column number does not exist

Other value < 0

Any of the server error codes listed in Return Codes.

Notes

Not Micro API compatible.

MimerCurrentRow

Returns the current row of a result set.

Parameters

int32_t MimerCurrentRow (MimerStatement statementhandle)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

Returns

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

Return value

Description

>= 0

Current cursor position.

If the current position is before the result set, 0 is returned. A value of 1 indicates the first row of the result set.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open.

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)

sessionhandle

in

A reference to a handle returned by MimerBeginSession[C|8], identifying the session.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

If there are open statements on the session. Use MimerEndStatement to release them.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C|8] identifying the session.

commit_rollback

in

An integer specifying the transaction operation to perform. MIMER_COMMIT and MIMER_ROLLBACK are recognized.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

No transaction has been started.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

Returns

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

Return value

Description

> 0

Success. Value indicates an update row count.

MIMER_SUCCESS

Success.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_SEQUENCE_ERROR

If this routine is called on a statement which returns a result set.

MIMER_UNSET_PARAMETERS

All input parameters have not yet been set.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C|8], identifying the session.

sqlstatement

in

An SQL statement.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_ILLEGAL_CHARACTER

The statement string contained an illegal character.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_STRING_TRUNCATION

The statement string was too long.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C|8], identifying the session.

sqlstatement

in

An SQL statement.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_ILLEGAL_CHARACTER

The statement string contained an illegal character.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_STRING_TRUNCATION

The statement string was too long.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

sessionhandle

in

A handle returned by MimerBeginSession[C|8], identifying the session.

sqlstatement

in

An SQL statement.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_ILLEGAL_CHARACTER

The statement string contained an illegal character.

MIMER_HANDLE_INVALID

The sessionhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_STRING_TRUNCATION

The statement string was too long.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement with an open cursor.

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.

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

If there is no open result set on this statement.

MIMER_NO_DATA

If there are no more rows in the result set.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

operation

in

A value describing the scroll operation to perform. This value may be either of the following:

MIMER_RELATIVE (0x00000000) - Move to a row number relative to the current position.

MIMER_NEXT (0x00000001) - Move on to the next row.

MIMER_PREVIOUS (0xffffffff) - Move to the previous row.

MIMER_ABSOLUTE (0x40000000) - Move to an absolute row number.

MIMER_FIRST (0x40000001) - Move to the first row of the result set.

MIMER_LAST (0xbfffffff) - Move to the last row of the result set.

offset

in

A parameter to MIMER_RELATIVE and MIMER_ABSOLUTE operation codes.

A relative value of n will move the cursor n rows relative to the current row. An absolute value of n will move to the n:th row of the result set. See Scrolling through a result set for an example of scroll operations.

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.

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

There is no open scrollable cursor this statement. Scrollability is determined at compile time with the options parameter to MimerBeginStatement or MimerBeginStatement8.

MIMER_NO_DATA

If the scroll operation ended up on a row without data, that is either before or after the result set.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement with an open cursor.

count

in

Number of rows to advance the current row down the result set.

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.

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NO_DATA

If there are no more rows in the result set.

MIMER_SEQUENCE_ERROR

If there is no open result set on this statement.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

dest

out

A memory location where to place output binary data. If this is null, no data will be returned, but the size of the binary data is still returned by this routine.

dest_maxsiz

in

The maximum size of the dest memory location in bytes.

Returns

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

Return value

Description

>= 0

The number of bytes in the binary column. If this value is larger than the dest_maxsiz parameter, the output data was truncated.

MIMER_CAST_VIOLATION

If the output parameter or column was not of the BINARY or BINARY VARYING data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

blobhandle

in

A reference to a binary large object handle created by MimerGetLob.

data

out

Where to place the entire or a part of the binary large object.

size

in

The size in bytes to retrieve in this chunk.

Returns

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

Return value

Description

>= 0

The number of bytes available to return. This includes the number of bytes returned in this call and all data that are left in the BLOB.

When the returned value is equal or less than the size input parameter, all data of the BLOB has been returned.

MIMER_HANDLE_INVALID

The blobhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

Returns

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

Return value

Description

1

Boolean value TRUE.

0

Boolean value FALSE.

MIMER_CAST_VIOLATION

If the output parameter or column was not of the BOOLEAN data type.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

value

out

A memory location where to place the double precision floating point value.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the output value was not of the DOUBLE PRECISION or REAL data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

value

out

A memory location where to place the floating point value.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the output value was not of the DOUBLE PRECISION or REAL data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

value

out

A memory location where to place the integer.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the output parameter or column was not of the INTEGER, BIGINT or SMALLINT data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

 

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

value

out

A memory location where to place the integer value.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the value was not of the INTEGER, BIGINT or SMALLINT data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

colno

in

The column number to get data from. First column is 1.

size_length

out

The size of a BINARY LARGE OBJECT in bytes or the length of a CHARACTER LARGE OBJECT or a NATIONAL CHARACTER LARGE OBJECT.

lobhandle

out

A handle to the binary large object.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the output parameter or column was not of the BINARY LARGE OBJECT, CHARACTER LARGE OBJECT or NATIONAL CHARACTER LARGE OBJECT data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

clobhandle

in

A handle to a character large object returned by a call to MimerSetLob.

data

out

Where to place the entire or a part of the character large object.

size

in

The maximum number of bytes to retrieve, including terminating null. That is, if this parameter is n, the next n-1 characters are retrieved from the large object.

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

 

Return value

Description

> 0

The number of characters left to return.

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The clobhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

returned

out

The number of bytes, excluding terminating zero, returned as a result of the operation.

clobhandle

in

A handle to a character large object returned by a call to MimerSetLob.

data

out

Where to place the entire or a part of the character large object.

size

in

The number of bytes to retrieve, including terminating null.

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

 

Return value

Description

>= 0

Success.

The number of characters to return. (See description above.)

MIMER_HANDLE_INVALID

The clobhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

returned

out

The number of bytes, excluding terminating zero, returned as a result of the operation.

clobhandle

in

A handle to a character large object returned by a call to MimerSetLob.

data

out

Where to place the entire or a part of the character large object.

size

in

The number of bytes to retrieve, including terminating null.

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

 

Return value

Description

>= 0

Success.

The number of characters to return. (See description above.)

MIMER_HANDLE_INVALID

The clobhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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:

 

BSI_4K_PAGES

The number of 4 K pages available in the system.

BSI_32K_PAGES

The number of 32 K pages available in the system.

BSI_128K_PAGES

The number of 128 K pages available in the system.

BSI_PAGES_USED

The total number of pages in use.

BSI_4K_PAGES_USED

The number of 4 K pages in use.

BSI_32K_PAGES_USED

The number of 32 K pages in use.

BSI_128K_PAGES_USED

The number of 128 K pages in use.

Parameters

int32_t MimerGetStatistics (

            MimerSession sessionhandle,

            int32_t *counters,

            int16_t nr_of_counters)

sessionhandle

in

A session handle opened through a call to MimerBeginSession[C|8].

counters

inout

An array containing the counter values to retrieve.

On output, the array contains the corresponding counter values.

On return, a value of -2 indicates that the counter type was unknown, -1 indicate that the counter type was known but its value was not available.

nr_of_counters

in

Specifies the number of counters supplied in counters.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

dest

out

A memory location where to place output wide character data. The character data is null terminated.

If this is a null pointer, no data will be returned, but the length is still returned by the routine.

dest_maxlen

in

The length of the dest memory location in characters.

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).

Return value

Description

>=0

Success.

The number of characters to be returned. (If > dest_maxlen, output data was truncated.)

MIMER_CAST_VIOLATION

If the output parameter or column was not of the CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER or NATIONAL CHARACTER VARYING data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

dest

out

A memory location where to place UTF-8 character data. The character data is null terminated.

If this is a null pointer, no data will be returned, but the length is still returned by the routine.

dest_maxsiz

in

The length of the dest memory location in bytes.

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).

Return value

Description

>= 0

Success.

The number of characters to be returned. (If > dest_maxlen, output data was truncated.)

MIMER_CAST_VIOLATION

If the output parameter or column was not of the CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER or NATIONAL CHARACTER VARYING data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to get data from. First parameter/column is 1.

dest

out

A memory location where to place locale dependent character data. The character data is null terminated.

If this is a null pointer, no data will be returned, but the length is still returned by the routine.

dest_maxsiz

in

The length of the dest memory location in bytes.

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).

Return value

Description

>= 0

Success.

The number of characters to be returned. (If > dest_maxlen, output data was truncated.)

MIMER_CAST_VIOLATION

If the output parameter or column was not of the CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER or NATIONAL CHARACTER VARYING data types.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value.

(This can also be detected using the MimerIsNull routine.)

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])

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to check for null in. First column/parameter is 1.

uuid

out

A memory location where 16 bytes will be written corresponding to the identifier.

Returns

A negative value indicating an error or zero indicating success.

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the output parameter or column was not of the BUILTIN.UUID data type.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

MIMER_SQL_NULL_VALUE

The column or output parameter contained the SQL null value. (This can also be detected using the MimerIsNull routine.)

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

paramno_colno

in

The parameter number or column number to check for null in. First column/parameter is 1.

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.

Return value

Description

> 0

Null is returned.

0

Not null.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The supplied column or parameter number did not exist.

MIMER_PARAMETER_NOT_OUTPUT

The referenced parameter is not an output or input/output parameter, which is required when calling a data output routine.

MIMER_SEQUENCE_ERROR

If the statement cursor is not open, or the current row is before the first row of the result set, or after the last row of the result set.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement with an open cursor.

Returns

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

Return value

Description

MIMER_NO_DATA

End of table reached.

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_SEQUENCE_ERROR

If the statement cursor is already open.

MIMER_UNSET_PARAMETER

All parameters has not yet been set.

Notes

Micro API compatible.

MimerParameterCount

Obtains the number of parameters of a statement.

Parameters

int32_t MimerParameterCount (MimerStatement statementhandle)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying the compiled statement which parameters to count.

Returns

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

Return value

Description

> = 0

Number of parameters.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

The statement is not compiled.

Other value < 0

Any of the server error codes listed in Return Codes.

Notes

Not Micro API compatible.

MimerParameterMode

Detects the input/output mode of a parameter.

Parameters

int32_t MimerParameterMode (

            MimerStatement statementhandle,

            int16_t paramno)

statementhandle

in

The statement whose parameter to look up.

paramno

in

The parameter to look up, where the first one is number 1.

Returns

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

Return value

Description

1

The parameter was input.

2

The parameter was output.

3

The parameter was input/output.

MIMER_SEQUENCE_ERROR

The statement was not in a prepared state.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The parameter does not exist.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying the compiled statement which parameters to count.

parameter

in

The parameter number, where the leftmost parameter is 1.

parametername

out

The area where to return the parameter name. The maximum parameter name length returned is maxlen-1.

maxlen

in

The length of the parametername area in characters, including room for terminating null.

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.

Return value

Description

> = 0

Number of characters in parameter name.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

The statement is not compiled.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The parameter number does not exist.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying the compiled statement which parameters to count.

parameter

in

The parameter number, where the leftmost parameter is 1.

parametername

out

The area where to return the parameter name. The maximum parameter name length returned is maxsize-1.

maxsize

in

The length of the parametername area in bytes, including room for terminating null.

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.

Return value

Description

> = 0

Number of bytes in parameter name.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

The statement is not compiled.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The parameter number does not exist.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying the compiled statement which parameters to count.

parameter

in

The parameter number, where the leftmost parameter is 1.

parametername

out

The area where to return the parameter name. The maximum parameter name length returned is maxsize-1.

maxsize

in

The length of the parametername area in bytes, including room for terminating null.

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.

Return value

Description

> = 0

Number of bytes in parameter name.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

The statement is not compiled.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The parameter number does not exist.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying the compiled statement which parameters to count.

parameter

in

The parameter number, where the leftmost parameter is 1.

Returns

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

Return value

Description

> 0

Data type. See list in Data Types

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

Statement is not compiled.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The parameter number does not exist.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying the compiled statement which maximum row size to obtain.

Returns

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

Return value

Description

>= 0

Number of bytes required to hold one row of data.

0 means that no input data

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

Statement is not compiled.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying the compiled statement which array size to change.

arraysize

in

The number of rows to retrieve in each request.

Returns

MIMER_SUCCESS if successful. A negative value indicate an error.

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_SEQUENCE_ERROR

Statement is not compiled.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A pointer to a memory location holding the binary data.

(If this pointer is a null pointer, the parameter is set to the SQL null value.)

size

in

The maximum size of the binary data in bytes.

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

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not BINARY or BINARY VARYING.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_TRUNCATION_ERROR

The input data was truncated.

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)

blobhandle

in

A reference to a binary large object handle created by MimerSetLob.

data

in

A pointer to the binary large object data.

size

in

Size of the chunk supplied in this call, in bytes.

The size of each chunk is limited to slightly less than 10 MB. If larger objects than this is to be set, multiple calls to this routine must be used, each supplying the large object in chunks.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The blobhandle parameter was not recognized as a handle.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A BOOLEAN value.

0 = false

1 = true

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not BOOLEAN.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A double precision floating point value.

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

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not FLOAT, REAL or DOUBLE PRECISION.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_UNDEFINED_FLOAT_VALUE

The supplied double was either a not-a-number or infinity.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A single precision floating point value.

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

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not REAL or DOUBLE PRECISION.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_UNDEFINED_FLOAT_VALUE

The supplied double was either a not-a-number or infinity.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

An integer value.

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

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not an INTEGER, BIGINT or SMALLINT parameter.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

An integer value.

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

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not an integer parameter.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

size_length

in

The size of the BINARY LARGE OBJECT in bytes, or the length of CHARACTER LARGE OBJECT or NATIONAL CHARACTER LARGE OBJECT in characters.

lobhandle

out

The handle to the created large object. If the object was of size 0, a handle is not created. This condition may be detected by comparing with the symbol MIMERNULLHANDLE.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not a BINARY LARGE OBJECT, a CHARACTER LARGE OBJECT or a NATIONAL CHARACTER LARGE OBJECT.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

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)

clobhandle

in

A reference to a character large object handle created by MimerSetLob.

data

in

A pointer to the character data.

length

in

Length of the chunk supplied in this call, in characters.

The size of each chunk is limited to slightly less than 10 MB. This translates to, in the worst case, about 2.5 million characters. If larger character objects than this is to be set, multiple calls to this routine must be used, each supplying the character large object in chunks.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The clobhandle parameter was not recognized as a handle.

MIMER_ILLEGAL_CHARACTER

The input string contained illegal characters.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

clobhandle

in

A reference to a character large object handle created by MimerSetLob.

data

in

A pointer to the character data.

size

in

Length of the chunk supplied in this call, in bytes.

The size of each chunk is limited to slightly less than 10 MB. This translates to, in the worst case, about 2.5 million characters. If larger character objects than this is to be set, multiple calls to this routine must be used, each supplying the character large object in chunks.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

clobhandle

in

A reference to a character large object handle created by MimerSetLob.

data

in

A pointer to the character data.

size

in

Length of the chunk supplied in this call, in bytes.

The size of each chunk is limited to slightly less than 10 MB. This translates to, in the worst case, about 2.5 million characters. If larger character objects than this is to be set, multiple calls to this routine must be used, each supplying the character large object in chunks.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

Other value < 0

Any of the server error codes listed in Return Codes.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

paramno

in

The number of the parameter to set to null. First column/parameter is 1.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A pointer to a buffer holding a null terminated character string. If this pointer is a null pointer, the parameter is set to the SQL null value.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred SQL data type was not a CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL or a NUMERIC.

MIMER_ILLEGAL_CHARACTER

If the input string contained illegal Unicode characters.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_TRUNCATION_ERROR

The input string was longer than could be held in the parameter.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A pointer to a buffer holding a null terminated character string. If this pointer is a null pointer, the parameter is set to the SQL null value.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred SQL data type was not a CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL or a NUMERIC.

MIMER_ILLEGAL_CHARACTER

If the input string contained illegal characters.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_TRUNCATION_ERROR

The input string was longer than could be held in the parameter.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A pointer to a buffer holding a null terminated character string. If this pointer is a null pointer, the parameter is set to the SQL null value.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred SQL data type was not a CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL or a NUMERIC.

MIMER_ILLEGAL_CHARACTER

If the input string contained illegal characters.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_TRUNCATION_ERROR

The input string was longer than could be held in the parameter.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A pointer to a buffer holding a null terminated wide character string. If this pointer is a null pointer, the parameter is set to the SQL null value.

length

in

Length of value in characters.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred SQL data type was not a CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL or a NUMERIC.

MIMER_ILLEGAL_CHARACTER

If the input string contained illegal characters.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_TRUNCATION_ERROR

The input string was longer than could be held in the parameter.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A pointer to a buffer holding a null terminated character string. If this pointer is a null pointer, the parameter is set to the SQL null value.

length

in

Size of value in bytes.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred SQL data type was not a CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL or a NUMERIC.

MIMER_ILLEGAL_CHARACTER

If the input string contained illegal Unicode characters.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_TRUNCATION_ERROR

The input string was longer than could be held in the parameter.

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)

statementhandle

in

A handle returned by MimerBeginStatement[C|8] identifying a prepared statement.

param_no

in

A number identifying the parameter. First parameter is 1.

value

in

A pointer to a buffer holding a null terminated character string. If this pointer is a null pointer, the parameter is set to the SQL null value.

length

in

Size of value in bytes.

Returns

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

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred SQL data type was not a CHARACTER, CHARACTER VARYING, NATIONAL CHARACTER, NATIONAL CHARACTER VARYING, DATE, TIME, TIMESTAMP, DECIMAL or a NUMERIC.

MIMER_ILLEGAL_CHARACTER

If the input string contained illegal Unicode characters.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

MIMER_TRUNCATION_ERROR

The input string was longer than could be held in the parameter.

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])

statementhandle

in

A handle returned by MimerBeginStatement[C|8], identifying a statement that have been executed.

param_no

in

A number identifying the parameter. First parameter is 1.

uuid

in

A pointer to a 16 byte buffer where the identifier to set is located. If this pointer is NULL, the SQL NULL value may be set.

Returns

A negative value indicating an error or zero indicating success.

Return value

Description

MIMER_SUCCESS

Success.

MIMER_CAST_VIOLATION

If the referred database type was not of the BUILTIN.UUID type.

MIMER_HANDLE_INVALID

The statementhandle parameter was not recognized as a handle.

MIMER_NONEXISTENT_COLUMN_PARAMETER

The referenced parameter does not exist.

MIMER_NULL_VIOLATION

Cannot assign the null value to a non-nullable parameter.

MIMER_OUTOFMEMORY

If not enough memory could be allocated.

MIMER_PARAMETER_NOT_INPUT

The referenced parameter is not an input or input/output parameter, which is required when calling a data input routine.

Notes

Micro API compatible.