Previous Topic

Next Topic

OpenAPI Functions

This section describes each OpenAPI function and provides its syntax.

Previous Topic

Next Topic

IIapi_abort() Function—Abort a Connection

The IIapi_abort() function closes a connection opened with IIapi_connect() and frees all the resources associated with the connection handle.

Any transaction associated with the connection is aborted, and the transaction handle freed, as are all associated statements and database event handles.

While this function can be used to clean up quickly when a problem is detected on a connection, applications are encouraged to continue calling IIapi_close(), IIapi_commit() or IIapi_rollback(), and IIapi_disconnect() to cleanly shut down server connections.

This function has the following syntax:

II_VOID IIapi_abort ( IIAPI_ABORTPARM *abortParm );

typedef struct _IIAPI_ABORTPARM
{
      IIAPI_GENPARM   ab_genParm;
      II_PTR          ab_connHandle;
} IIAPI_ABORTPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_autocommit() Function—Enable or Disable Autocommit Transactions

The IIapi_autocommit() function provides an interface for the front-end application to manage the autocommit state in a server. It controls the autocommit state of the server through an autocommit transaction handle. An autocommit transaction handle is required to access the Name Server through OpenAPI.

This function is called with a NULL transaction handle to enable the autocommit state in a server. For a DBMS connection, this is equivalent to the SQL statement 'SET AUTOCOMMIT ON'. An autocommit transaction handle is returned to be used in place of a regular transaction handle in IIapi_query(). Query statements executed in the context of an autocommit transaction are automatically committed when they complete execution.

When called with an existing autocommit transaction handle, this function disables the autocommit state in the server. This is equivalent to the SQL statement 'SET AUTOCOMMIT OFF'. The autocommit transaction handle is freed and can not be referenced further by the application.

When you set autocommit on, a commit occurs automatically after every statement except prepare and describe. If autocommit is on and you open a cursor, the DBMS does not issue a commit until the close cursor statement is executed because cursors are logically a single statement.

This function has the following syntax:

II_VOID IIapi_autocommit( IIAPI_AUTOPARM *autoParm);

typedef struct _IIAPI_AUTOPARM
{
      IIAPI_GENPARM  ac_genParm;
      II_PTR         ac_connHandle;
      II_PTR         ac_tranHandle;
} IIAPI_AUTOPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_cancel() Function—Cancel an Outstanding Query Statement

The IIapi_cancel() function causes a query statement started with IIapi_query() or an event retrieval started with IIapi_catchEvent() to complete its operations.

When IIapi_cancel() completes successfully, the query may not yet be canceled; it simply means that the server has received the cancellation request. Each canceled query receives a callback.

This function is different from IIapi_close(), which is used to end a query. The IIapi_close() function waits for the completion of the query, whereas IIapi_cancel() attempts to end it before it is completed.

Statement handle output from IIapi_query() and event handle output from IIapi_catchEvent() is available when the function returns, so queries can be canceled at anytime thereafter.

The following are possible results of the IIapi_cancel() function and their corresponding actions:

This function has the following syntax:

II_VOID IIapi_cancel (IIAPI_CANCELPARM *cancelParm);

typedef struct _IIAPI_CANCELPARM
{
      IIAPI_GENPARM   cn_genParm;
      II_PTR          cn_stmtHandle;
} IIAPI_CANCELPARM;

This function has the following parameters:

Previous Topic

Next Topic

Function Summary

The following is a summary of the OpenAPI functions, grouped by tasks.

Previous Topic

Next Topic

OpenAPI Management

Previous Topic

Next Topic

Session Management

Previous Topic

Next Topic

Query Processing

Previous Topic

Next Topic

Transaction Operations

Previous Topic

Next Topic

Miscellaneous

Previous Topic

Next Topic

IIapi_catchEvent() Function—Retrieve a Database Event

The IIapi_catchEvent() function retrieves a database event previously registered by an application. The application first registers for a database event using IIapi_query() to invoke the register dbevent statement. It then captures each occurrence of the event and retrieves its data by calling IIapi_catchEvent().

IIapi_catchEvent() allows the application to specify the database event by the event parameters. If ce_selectEventName and ce_selectEventOwner are specified, one specific event is captured when the function completes. If only ce_selectEventOwner is specified, any events owned by the specific owner are captured. If only ce_selectEventName is specified, any events with the event name are captured. If neither ce_selectEventName nor ce_selectEventOwner are specified, all events are captured.

When IIapi_catchEvent() returns, it provides an event handle as immediate output. This handle is used to retrieve additional event information, to cancel the event retrieval, or to clean up after the event is retrieved.

Calling IIapi_catchEvent() captures one occurrence of a database event. After it has captured the event, the application can immediately issue another IIapi_catchEvent() with the same event handle to capture the next occurrence.

IIapi_catchEvent() operates in a manner similar to the embedded SQL statement set_sql(dbeventhandler=<dbevent_handler>). IIapi_catchEvent() does not result in any communication with the server. Since database event notification is passed along with other SQL result information, the application must continue with other database operations after calling IIapi_catchEvent() to enable retrieval of database events.

IIapi_getEvent() can be used to receive database event notifications when the application has no other database operations to perform. IIapi_getEvent() operates in a manner similar to the embedded SQL statement GET DBEVENT. See IIapi_getEvent() for further details.

If IIapi_catchEvent() completes with ce_eventInfoAvail set to TRUE, the application should call IIapi_getDescriptor() and IIapi_getColumns() to access additional event information.

If the application no longer wants to retrieve a pending database event, it calls IIapi_cancel() to cancel the event retrieval. A canceled event retrieval completes with a failure status. After an event is canceled, or an event retrieval has completed, the application calls IIapi_close() to free the event handle and associated internal resources.

If an event notification occurs for which there is no active matching event handle, the database event is ignored. IIapi_setEnvParam() permits a callback function to be registered, which will be called for each database event that fails to match to an active event handle and would otherwise be ignored. See IIAPI_EP_EVENT_FUNC and related documentation in the description for IIapi_setEnvParam().

This function has the following syntax:

II_VOID IIapi_catchEvent (IIAPI_CATCHEVENTPARM *catchEventParm);

typedef struct _IIAPI_CATCHEVENTPARM
{
      IIAPI_GENPARM  ce_genParm;
      II_PTR         ce_connHandle;
      II_CHAR        *ce_selectEventName;
      II_CHAR        *ce_selectEventOwner;
      II_PTR         ce_eventHandle;
      II_CHAR        *ce_eventName
      II_CHAR        *ce_eventOwner
      II_CHAR        *ce_eventDB;
      IIAPI_DATAVALUE ce_eventTime;
      II_BOOL         ce_eventInfoAvail;
} IIAPI_CATCHEVENTPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_close() Function—End a Query Statement or Database Event Retrieval

The IIapi_close() function ends a query or database event retrieval started with IIapi_query() or IIapi_catchEvent(). This function frees the event or statement handle and closes any cursor associated with the statement handle.

An application calls IIapi_close() to end a query that has finished all OpenAPI function calls required by the query type. The application must call IIapi_cancel() to interrupt a query with outstanding requests prior to calling IIapi_close().

IIapi_close() invalidates any data returned by the IIapi_catchEvent(), IIapi_getCopyMap(), IIapi_getDescriptor(), or IIapi_getErrorInfo() functions for the statement handle.

Note: For more information, see How Memory is Managed for Data Input and Output.

For each IIapi_query() or IIapi_catchEvent(with NULL ce_eventHandle), there should be a corresponding IIapi_close().

The following are possible results of the IIapi_close() function and their corresponding actions:

This function has the following syntax:

II_VOID IIapi_close (IIAPI_CLOSEPARM *closeParm);

typedef struct _IIAPI_CLOSEPARM
{
      IIAPI_GENPARM cl_genParm;
      II_PTR        cl_stmtHandle;
} IIAPI_CLOSEPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_commit() Function—Commit a Transaction

The IIapi_commit() function commits a transaction that was started with IIapi_query() or restarted by IIapi_connect(), and then frees the transaction handle.

Before the transaction is committed, the application must call IIapi_close() to free the statement handles within the transaction.

This function has the following syntax:

II_VOID IIapi_commit (IIAPI_COMMITPARM *commitParm);

typedef struct _IIAPI_COMMITPARM
{
      IIAPI_GENPARM  cm_genParm;
      II_PTR         cm_tranHandle;
} IIAPI_COMMITPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_connect() Function—Connect to a DBMS Server or Name Server

The IIapi_connect() function establishes a connection to a DBMS Server or the Name Server, based on the connection type, and allocates a connection handle. When connecting to the Name Server an environment handle must be provided as input.

This function returns the co_apiLevel output parameter, which specifies the level of functionality provided by OpenAPI for the current connection. If the output connection handle is not NULL after this function returns, even if an error occurs, IIapi_disconnect() or IIapi_abort() must be called to release the connection handle.

This function has the following syntax:

II_VOID IIapi_connect (IIAPI_CONNPARM *connParm);

typedef struct _IIAPI_CONNPARM
{
      IIAPI_GENPARM      co_genParm;
      II_CHAR            *co_target;
      II_CHAR            *co_username;
      II_CHAR            *co_password;
      II_LONG            co_timeout;
      II_PTR             co_connHandle;
      II_PTR             co_tranHandle
      II_LONG            co_sizeAdvise;
      II_LONG            co_apiLevel;
      II_LONG            co_type;
} IIAPI_CONNPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_convertData() Function—Convert Ingres Data Values to Compatible Types Using Default Settings

The IIapi_convertData() function converts data values between Ingres data types. The data values are translated and formatted using default settings selected by the user and specified at the operating system level prior to running the application. IIapi_formatData() can be used to convert data using settings selected by the application.

This function is intended to support Ingres data types that do not have a corresponding C language data type.

Conversions to and from IIAPI_CHA_TYPE are supported for the data types IIAPI_DEC_TYPE, IIAPI_MNY_TYPE, IIAPI_DTE_TYPE, IIAPI_DATE_TYPE, IIAPI_TIME_TYPE, IIAPI_TMWO_TYPE, IIAPI_TMTZ_TYPE, IIAPI_TS_TYPE, IIAPI_TSWO_TYPE, IIAPI_TSTZ_TYPE, IIAPI_INTYM_TYPE, IIAPI_INTDS_TYPE.

In addition, the following conversions are supported:

Data Type

Converted To

IIAPI_DEC_TYPE

IIAPI_FLT_TYPE

IIAPI_FLT_TYPE

IIAPI_DEC_TYPE

IIAPI_MNY_TYPE

IIAPI_FLT_TYPE

IIAPI_FLT_TYPE

IIAPI_MNY_TYPE

The source data value must not be NULL (that is, dv_null set to TRUE).

This function has the following syntax:

II_VOID IIapi_convertData(IIAPI_CONVERTPARM *convertParm);

typedef struct _IIAPI_CONVERTPARM
{
      IIAPI_DESCRIPTOR      cv_srcDesc;
      IIAPI_DATAVALUE       cv_srcValue;
      IIAPI_DESCRIPTOR      cv_dstDesc;
      IIAPI_DATAVALUE       cv_dstValue;
      IIAPI_STATUS          cv_status;
} IIAPI_CONVERTPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_disconnect() Function—Close a Server Connection

The IIapi_disconnect() function closes the connection to the server opened with IIapi_connect() and frees all resources associated with the connection handle.

An application must close all outstanding statements and event retrievals, and it must commit or roll back all outstanding transactions before calling IIapi_disconnect().

This function has the following syntax:

II_VOID IIapi_disconnect (IIAPI_DISCONNPARM *disconnParm);

typedef struct _IIAPI_DISCONNPARM
{
      IIAPI_GENPARM     dc_genParm;
      II_PTR            dc_connHandle;
} IIAPI_DISCONNPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_formatData() Function—Convert Ingres Data Values to Compatible Types

The IIapi_formatData() function converts data values between Ingres data types. The data values are translated and formatted using settings selected by the application and specified on an environment handle using IIapi_setEnvParam(). IIapi_convertData() can be used to convert data using default settings selected by the user running the application.

For further details, see the description of IIapi_convertData().

This function has the following syntax:

II_VOID IIapi_formatData( IIAPI_FORMATPARM *formatParm );

typedef struct _IIAPI_FORMATPARM
{
      II_PTR                     fd_envHandle;
      IIAPI_DESCRIPTOR           fd_srcDesc;
      IIAPI_DATAVALUE            fd_srcValue;
      IIAPI_DESCRIPTOR           fd_dstDesc;
      IIAPI_DATAVALUE            fd_dstValue;
      IIAPI_STATUS               fd_status;
} IIAPI_FORMATPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_getColumns() Function—Return Columns from a Previously Invoked Query Statement or Database Event Retrieval

The IIapi_getColumns() function returns the results of a query statement or database event retrieval created by IIapi_query() or IIapi_catchEvent() to the application. It retrieves into the application's buffers the requested number of columns of data.

This function is always preceded with the IIapi_getDescriptor() or IIapi_getCopyMap() function, which describes the format and number of columns to be returned to the application from the server.

IIapi_getColumns() can return multiple rows. If there are long varchar or long byte data columns, IIapi_getColumns() returns only one row at a time.

If one of the columns is a long varchar or long byte that requires more than one segment to be returned, the application requests the segments individually with single calls to IIapi_getColumns(). For example, a row of ten columns with a long varchar or long byte spanning multiple segments as the fifth column is handled as follows. The application:

  1. Requests four columns with a call to IIapi_getColumns().
  2. Requests one segment of the long varchar or long byte column with a call to IIapi_getColumns().
  3. Continues making requests until all segments are retrieved.
  4. Requests five columns with a call to IIapi_getColumns() to retrieve the rest of the columns in the current row.

IIapi_getColumns() returns columns sequentially in the order that they appear in the row, as described in IIapi_getCopyMap() and IIapi_getDescriptor(). When IIAPI_ST_NO_DATA is returned, the application should free the statement handle with the IIapi_close() function.

IIapi_getColumns() assumes the application has allocated sufficient storage for each column. The buffer size of each column should be equal to the ds_length parameter of its corresponding descriptor from IIapi_getCopyMap() or IIapi_getDescriptor().

This function has the following syntax:

II_VOID IIapi_getColumns (IIAPI_GETCOLPARM *getColParm);

typedef struct _IIAPI_GETCOLPARM
{
      IIAPI_GENPARM gc_genParm;
      II_PTR               gc_stmtHandle;
      II_INT               gc_rowCount;
      II_INT               gc_columnCount;
      IIAPI_DATAVALUE      *gc_columnData;
      II_INT               gc_rowsReturned
      II_BOOL              gc_moreSegments;
} IIAPI_GETCOLPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_getCopyMap() Function—Return the Data Format of Copy File and Database Table Involved in a Copy Statement

The IIapi_getCopyMap() function returns a pointer to a copy map for data being copied from a file to a database table or from a database table to a file. The copy map describes the data in the file and in the database table.

IIapi_getCopyMap() output remains valid until the copy statement is closed with IIapi_close().

This function has the following syntax:

II_VOID IIapi_getCopyMap (IIAPI_GETCOPYMAPPARM *getCopyMapParm);

typedef struct _IIAPI_GETCOPYMAPPARM
{
      IIAPI_GENPARM    gm_genParm;
      II_PTR           gm_stmtHandle;
      IIAPI_COPYMAP    gm_copyMap;
} IIAPI_GETCOPYMAPPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_getDescriptor() Function—Communicate Format of Return Data with IIapi_getColumns()

The IIapi_getDescriptor() function retrieves information from the server about the format of the data being returned to the application. This information includes the number of columns in a row and the type, length, precision, and scale of each column. The actual values are returned with a subsequent call to IIapi_getColumns().

IIapi_getDescriptor() output remains valid until the query is ended with the IIapi_close() function.

This function has the following syntax:

II_VOID IIapi_getDescriptor (IIAPI_GETDESCRPARM *getDescrParm);

typedef struct _IIAPI_GETDESCRPARM
{
      IIAPI_GENPARM       gd_genParm;
      II_PTR              gd_stmtHandle;
      II_LONG             gd_descriptorCount;
      IIAPI_DESCRIPTOR   *gd_descriptor;
} IIAPI_GETDESCRPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_getErrorInfo() Function—Return Additional Error or User-defined Information

The IIapi_getErrorInfo() function returns a set of error parameters or user-defined information specified by an error handle. User-defined information consists of messages declared in a database procedure. These messages are returned during the execution of the database procedure.

Because the error handle can contain more than one set of error parameters, the application should repeat IIapi_getErrorInfo() until the status IIAPI_ST_NO_DATA is returned by the ge_status parameter.

The output of IIapi_getErrorInfo() is valid until another operation is invoked with the same handle.

This function has the following syntax:

II_VOID IIapi_getErrorInfo (IIAPI_GETEINFOPARM *getEInfoParm);

typedef struct _IIAPI_GETEINFOPARM
{
      II_PTR             ge_errorHandle;
      II_LONG            ge_type;
      II_CHAR            ge_SQLSTATE[6];
      II_LONG            ge_errorCode;
      II_CHAR            *ge_message;
      II_BOOL            ge_serverInfoAvail;
      IIAPI_SVR_ERRINFO  *ge_serverInfo;
      IIAPI_STATUS       ge_status;
} IIAPI_GETEINFOPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_getEvent() Function—Wait for Database Events

The IIapi_getEvent() function provides an interface for applications to wait for database events to occur. The IIapi_getEvent() function checks for database events that are received, independent of other query results being returned by the server. Database event information is retrieved using IIapi_catchEvent(), which should be called prior to calling IIapi_getEvent().

An application prepares to process database events by registering with the server (IIapi_query()) and OpenAPI (IIapi_catchEvent()) for specific events. The application can then receive event notification while processing other queries on the connection.

IIapi_getEvent() can be called to receive database events when the application does not have any query processing to be performed on the desired connection. No queries can be issued on the specified connection handle until IIapi_getEvent() completes.

This function has the following syntax:

II_VOID IIapi_getEvent ( IIAPI_GETEVENTPARM *getEventParm );

typedef struct _IIAPI_GETEVENTPARM
{
      IIAPI_GENPARM   gv_genParm;
      II_PTR          gv_connHandle;
      II_LONG         gv_timeout;
} IIAPI_GETEVENTPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_getQueryInfo() Function—Return Information about a Query

The IIapi_getQueryInfo() function returns data associated with a query statement. It is useful for applications that are updating the database to know if the update was successful. The information includes the following:

As a common practice, applications should call IIapi_getQueryInfo() after each query is completed to check if there are any additional errors or response data reported by the server.

The output of IIapi_getQueryInfo() is valid until the query statement is ended with the IIapi_close() function.

This function has the following syntax:

II_VOID IIapi_getQueryInfo (IIAPI_GETQINFOPARM *getQInfoParm);

typedef struct _IIAPI_GETQINFOPARM
{
      IIAPI_GENPARM  gq_genParm;
      II_PTR         gq_stmtHandle;
      II_ULONG       gq_flags;
      II_ULONG       gq_mask;
      II_LONG        gq_rowCount;
      II_BOOL        gq_readonly
      II_LONG        gq_procedureReturn;
      II_PTR         gq_procedureHandle;
      II_PTR         gq_repeatQueryHandle;
      II_CHAR        gq_tableKey [TBL_KEY_SZ];
      II_CHAR        gq_objectKey [OBJ_KEY_SZ];
} IIAPI_GETQINFOPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_initialize() Function—Initialize OpenAPI to a Specified Input Version

The IIapi_initialize() function prepares OpenAPI for operation. This function allocates an environment handle and returns it to the application. IIapi_initialize() must be called before the application performs any memory allocation and OpenAPI functions. When IIapi_initialize() completes, the application can begin issuing other OpenAPI functions. This function can be called more than once, but each call requires a corresponding call to IIapi_terminate().

The application specifies the OpenAPI interface version used by the application when calling this function. For version IIAPI_VERSION_1, a single default environment is used as the context for server connections (the returned environment handle is set to NULL). For version IIAPI_VERSION_2 (and higher), a new environment handle is allocated and returned to the application. The application can select environment settings by providing the environment handle as input to IIapi_setEnvParam(). The application can also make connections utilizing the environment settings by providing the environment handle as input to IIapi_setConnectParam() or IIapi_connect(). The environment handle must be released by calling IIapi_releaseEnv().

This function has the following syntax:

II_VOID IIapi_initialize (IIAPI_INITPARM *initParm);

typedef struct _IIAPI_INITPARM
{
      II_LONG      in_timeout;
      II_LONG      in_version;
      IIAPI_STATUS in_status;
      II_PTR       in_envHandle;
} IIAPI_INITPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_modifyConnect Function—Send Connection Parameters to Server

The IIapi_modifyConnect() function sends the connection parameters, assigned in prior calls to IIapi_setConnectParam(), to the server. Once sent, parameters are cleared so as to not affect subsequent calls to IIapi_modifyConnect(). This function can be called only when no transaction is active on the specified connection.

Note: An Ingres DBMS Server accepts only IIAPI_CP_SHARED_SYS_UPDATE once a connection is established.

This function has the following syntax:

II_VOID IIapi_modifyConnect (IIAPI_MODCONNPARM *modifyConnParm);

typdef struct _IIAPI_MODCONNPARM
{
      IIAPI_GENPARM  mc_genParm;
      II_PTR         mc_connHandle;
} IIAPI_MODCONNPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_prepareCommit() Function—Begin Two-phase Commit of Transaction

The IIapi_prepareCommit() function prepares to commit a distributed transaction started with IIapi_query() or restarted by IIapi_connect().

IIapi_prepareCommit() secures resources for a transaction in a two-phase commit situation. When IIapi_prepareCommit() completes successfully, the server has allocated and secured all resources to commit the transaction. The application can then call IIapi_commit() to commit the transaction or IIapi_rollback() to abort the transaction.

Normally two-phase commits are desirable when multiple transactions are being committed as a unit. Each transaction is secured for the commit with IIapi_prepareCommit(). When all transactions have been secured, the application calls IIapi_commit() to finish the two-phase commit process. If some of the transactions cannot be secured, resulting in an unsuccessful completion of IIapi_prepareCommit(), the application can call IIapi_rollback() on each transaction to abort it.

In order to create or restart a distributed transaction, the application calls IIapi_registerXID() to register a unique global transaction ID. This global transaction ID can be used for multiple transactions. The transaction ID handle returned by IIapi_registerXID() can then be provided as input to IIapi_query() or IIapi_connect() to create or restart a distributed transaction. The application used the transaction handle returned by IIapi_query() or IIapi_connect() as input to IIapi_prepareCommit() to specify the distributed transaction for which resources are to be secured.

IIapi_prepareCommit() rejects any transaction handle representing a non-distributed or autocommit transaction.

This function has the following syntax:

II_VOID IIapi_prepareCommit (IIAPI_PREPCMTPARM *prepCommitParm);

typedef struct _IIAPI_PREPCMTPARM
{
      IIAPI_GENPARM    pr_genParm;
      II_PTR           pr_tranHandle;
} IIAPI_PREPCMTPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_putColumns() Function—Send Data to Server to Copy Data from File to Database Table

The IIapi_putColumns() function takes the requested number of columns of data from the application's buffers and copies it to a database table.

This function is preceded with the IIapi_getCopyMap() function, which describes the format and number of columns to be copied.

IIapi_putColumns() processes columns sequentially in the order that they appear in the row, as described in the IIapi_getCopyMap() functions. The application requests that a whole row be sent with one call to IIapi_putColumns(), provided it does not contain any long varchar or long byte columns. However, IIapi_putColumns() cannot span rows, so the application cannot request a number greater than the number of columns in a row.

If one of the columns is a long varchar or long byte that requires more than one segment to be sent, the application sends the columns individually with single calls to IIapi_putColumns(). For example, a row of ten columns with a long varchar or long byte spanning multiple segments as the fifth column is handled as follows. The application:

  1. Sends four columns with a call to IIapi_putColumns().
  2. Sends one segment of the long varchar or long byte column with a call to IIapi_putColumns().
  3. Continues sending individual segments until all are sent.
  4. Sends five columns with a call to IIapi_putColumns() to send the rest of the columns of the current row.

This function has the following syntax:

II_VOID IIapi_putColumns (IIAPI_PUTCOLPARM *putColParm);

typedef struct _IIAPI_PUTCOLPARM
{
       IIAPI_GENPARM       pc_genParm;
       II_PTR              pc_stmtHandle;
       II_LONG             pc_columnCount;
       IIAPI_DATAVALUE     *pc_columnData;
       II_BOOL             pc_moreSegments;
} IIAPI_PUTCOLPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_putParms() Function—Send Query Statement Parameter Values to a Server

The IIapi_putParms() function allows the application to send parameter data to a server at statement execution time.

This function is preceded with the IIapi_setDescriptor() function, which describes the format and number of parameters to be sent to the server.

IIapi_putParms() processes parameters sequentially in the order they appear in the query. The application sends all parameters with a single call to IIapi_putParms(), provided the parameters do not contain any long varchar or long byte data types. The total number of parameters provided for a query must not be less than the number of parameters the query expects.

If one of the parameters is a long varchar or long byte that requires more than one segment to be sent, the application sends the parameters individually with single calls to IIapi_putColumns(). For example, a row of ten parameters with a long varchar or long byte spanning multiple segments as the fifth parameter is handled as follows. The application:

  1. Sends four parameters with a call to IIapi_putParms().
  2. Sends one segment of the long varchar or long byte parameter with a call to IIapi_putParms().
  3. Continues sending individual segments until all are sent.
  4. Sends five parameters with a call to IIapi_putParms() to send the rest of the parameters in the current row.

This function has the following syntax:

II_VOID IIapi_putParms (IIAPI_PUTPARMPARM *putParmParm);

typedef struct _IIAPI_PUTPARMPARM
{
       IIAPI_GENPARM       pp_genParm;
       II_PTR              pp_stmtHandle;
       II_LONG             pp_parmCount;
       IIAPI_DATAVALUE     *pp_parmData;
       II_BOOL             pp_moreSegments;
} IIAPI_PUTPARMPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_query() Function—Begin Query Statement and Allocate Statement Handle

The IIapi_query() function begins a query statement. IIapi_query() allocates a statement handle. The statement handle must eventually be freed with the IIapi_close() function.

An application enters parameters for the query statement with subsequent calls to the IIapi_setDescriptor() and IIapi_putParms() functions. It can also use the qy_queryText parameter of IIapi_query() to enter the syntax of the query statement. The qy_queryText parameter should contain NULL if query text is not required.

Note: For a list of SQL statements that can be invoked by IIapi_query(), see Accessing a DBMS Using SQL.

When entering the syntax of SQL statements in the qy_queryText parameter, see SQL Syntax, and the SQL Reference Guide.

An application specifies the beginning of a transaction with the qy_tranHandle input parameter. If this parameter is NULL or is a transaction ID handle created by IIapi_registerXID(), a new transaction is begun and a transaction handle is allocated. Otherwise, this parameter must be an existing transaction handle and the statement is executed as part of the current transaction.

A transaction handle allocated by this function must be released using IIapi_commit() or IIapi_rollback(). If a transaction handle is allocated for a request which eventually fails, the transaction handle should be released using IIapi_rollback().

Currently, the GCA protocol does not support multiple, concurrent non-cursor statements in the same transaction, or multiple concurrent transactions on the same connection.

This function has the following syntax:

II_VOID IIapi_query (IIAPI_QUERYPARM *queryParm);

typedef struct _IIAPI_QUERYPARM
{
       IIAPI_GENPARM       qy_genParm;
       II_PTR              qy_connHandle;
       IIAPI_QUERY_TYPE    qy_queryType;
       II_BOOL             qy_queryText;
       II_CHAR             *qy_parameters;
       II_PTR              qy_tranHandle;
       II_PTR              qy_stmtHandle;
} IIAPI_QUERYPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_registerXID() Function—Reserve Unique ID for Two-phase Commit Transaction

The IIapi_registerXID() function reserves a unique ID to begin a two-phase commit transaction with IIapi_query() or to restart a previously-aborted two-phase commit transaction with IIapi_connect(). An application must use IIapi_registerXID() if a two-phase commit transaction is being used.

After this function is successfully completed, the output parameter rg_tranIdHandle can be used as input for IIapi_connect() and IIapi_query() to specify a transaction. The transaction ID handle can be used on multiple transactions; it does not uniquely identify one transaction.

The transaction ID handle returned by this function must be release using IIapi_releaseXID().

This function has the following syntax:

VOID IIapi_registerXID (IIAPI_REGXIDPARM *regXIDParm);

typedef struct _IIAPI_REGXIDPARM
{
       IIAPI_TRAN_ID  rg_tranID;
       PTR            rg_tranIdHandle;
       IIAPI_STATUS   rg_status;
} IIAPI_REGXIDPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_releaseEnv() Function—Release Resources Associated with Environment Handle

The IIapi_releaseEnv() function frees an environment handle and any resources associated with the environment handle.

An application calls IIapi_releaseEnv() to free an environment handle allocated by IIapi_initialize(). Any active server connections associated with the environment handle are aborted and the respective connection handle is freed, as are all associated transaction, statement, and database event handles. While this function can be used to clean up quickly after a connection failure, applications are encouraged to continue calling IIapi_close(), IIapi_commit() or IIapi_rollback() and IIapi_disconnect() to cleanly shut down server connections. A warning status is returned if a connection is aborted.

The application can continue to make OpenAPI function calls after calling this function, but does so in the context of the default environment handle shared by all IIAPI_VERSION_1 applications. The application must still call IIapi_terminate() to release global resources used by OpenAPI.

This function has the following syntax:

II_VOID IIapi_releaseEnv (IIAPI_RELENVPARM *relEnvParm);

typedef struct _IIAPI_RELENVPARM
{
       II_PTR             re_envHandle:
       IIAPI_STATUS       re_status;
} IIAPI_RELENVPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_releaseXID() Function—Release Unique ID for Two-phase Commit Transaction

The IIapi_releaseXID() function releases the transaction ID reserved by IIapi_registerXID(). It also frees the resources associated with the transaction ID handle.

This function has the following syntax:

II_VOID IIapi_releaseXID (IIAPI_RELXIDPARM *relXIDParm);

typedef struct _IIAPI_RELXIDPARM
{
       II_PTR             rl_tranIdHandle;
       IIAPI_STATUS       rl_status;
} IIAPI_RELXIDPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_rollback() Function—Roll back a transaction

The IIapi_rollback() function rolls back a transaction started with IIapi_query() or restarted by IIapi_connect(). It also frees the transaction handle if the rb_savePointHandle parameter is NULL. If the rb_savePointHandle parameter is the savepoint handle returned by the IIapi_savePoint() function, the transaction is rolled back to the savepoint and the transaction handle remains valid.

Before rolling back a transaction, the application must call IIapi_close() to release all statement handles associated with the transaction.

This function has the following syntax:

II_VOID IIapi_rollback (IIAPI_ROLLBACKPARM *rollbackParm);

typedef struct _IIAPI_ROLLBACKPARM
{
       IIAPI_GENPARM   rb_genParm;
       II_PTR          rb_tranHandle;
       II_PTR          rb_savePointHandle;
} IIAPI_ROLLBACKPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_savePoint() Function—Mark Savepoint in a Transaction for Partial Rollback

The IIapi_savePoint() function marks a savepoint in a transaction for a partial rollback with the IIapi_rollback() function.

The sp_savePointHandle parameter that is output from this function is unique to the transaction and remains valid until the transaction is committed or completely rolled back.

This function has the following syntax:

II_VOID IIapi_savePoint (IIAPI_SAVEPTPARM *savePtParm);

typedef struct _IIAPI_SAVEPTPARM
{
       IIAPI_GENPARM  sp_genParm;
       II_PTR         sp_tranHandle;
       II_CHAR        *sp_savePoint;
       II_PTR         sp_savePointHandle;
} IIAPI_SAVEPTPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_setConnectParam() Function—Assign Connection Parameter and Value to a Connection

The IIapi_setConnectParam() function allows the application to assign connection parameters to a connection. These parameters are sent to the server when IIapi_connect() or IIapi_modifyConnect() are called. One parameter and associated value are assigned for each call to IIapi_setConnectParam().

This function creates a new connection handle if called with sc_connHandle set to NULL or an environment handle returned by IIapi_initialize(). The returned connection handle can be used in subsequent calls to assign additional connection parameters to the connection. The connection handle can then be used to call IIapi_connect() to establish the connection to the server with the desired connection parameters. The connection handle is released using IIapi_disconnect() or IIapi_abort().

Once a connection has been established with IIapi_connect(), IIapi_setConnectParam() can be called with the connection handle to assign new connection parameters or to modify the parameters established with IIapi_connect(). Parameters assigned after calling IIapi_connect() are sent to the server by calling IIapi_modifyConnect().

This function has the following syntax:

II_VOID IIapi_setConnectParam (IIAPI_SETCONPRMPARM *setConPrmParm);

typedef struct _IIAPI_SETCONPRMPARM
{
       IIAPI_GENPARM  sc_genParm;
       II_PTR         sc_connHandle;
       II_LONG        sc_paramID;
       II_PTR         sc_paramValue;
} IIAPI_SETCONPRMPARM;

Note: Only IIAPI_CP_SHARED_SYS_UPDATE is accepted by an Ingres DBMS Server once a connection is established.

This function has the following parameters:

Previous Topic

Next Topic

IIapi_setDescriptor() Function—Send Information About Data Format

The IIapi_setDescriptor() function sends information about the format of data that will be provided with the IIapi_putParms() or IIapi_putColumns() function. Parameters to IIapi_setDescriptor() contain the number of columns being inserted or copied to the database, as well as their data type, length, precision, and scale.

Sends information to the server about the format of data to be provided in subsequent calls to IIapi_putParms() and IIapi_putColumns().

This function has the following syntax:

II_VOID IIapi_setDescriptor
       (IIAPI_SETDESCRPARM *setDescrParm);

typedef struct _IIAPI_SETDESCRPARM
{
       IIAPI_GENPARM       sd_genParm;
       II_PTR              sd_stmtHandle;
       II_LONG             sd_descriptorCount;
       IIAPI_DESCRIPTOR    *sd_descriptor;
} IIAPI_SETDESCRPARM;

This function has the following parameters:

Previous Topic

Next Topic

IIapi_setEnvParam() Function—Assign an Environment Parameter and Value in Environment Handle

The IIapi_setEnvParam() function allows the application to override the default environment logical settings established by the IIapi_initialize() for a specific environment handle.

Settings for environment parameters, which correspond to connection parameters, are used as the default connection parameter values unless specifically overridden by IIapi_setConnectParam().

Environment parameters also affect the conversions performed by IIapi_formatData() and control interactions between OpenAPI and the application.

This function has the following syntax:

II_VOID IIapi_setEnvParam (IIAPI_SETENVPRMPARM *setEnvPrmParm);

typedef struct _IIAPI_SETENVPRMPARAM
{
       II_PTR        se_envHandle;
       II_LONG       se_paramID
       II_PTR        se_paramValue
       IIAPI_STATUS  se_status
} IIAPI_SETENVPRMPARM;

This function has the following parameters:

The following table lists valid parameter ID macros for the se_paramID parameter:

More information:

Environment Parameter IIAPI_EP_CAN_PROMPT

Environment Parameter IIAPI_EP_TRACE_FUNC

Environment Parameter IIAPI_EP_EVENT_FUNC

Previous Topic

Next Topic

Environment Parameter IIAPI_EP_CAN_PROMPT

An application can set IIAPI_EP_CAN_PROMPT in the IIapi_setEnvParam() function by providing the address of an application function to call back. OpenAPI invokes this application function to receive a reply from the application for the prompt message from the server using the following C structure:

typedef struct _IIAPI_PROMPTPARM
{
       II_PTR       pd_envHandle;
       II_PTR       pd_connHandle;
       II_LONG      pd_flags;
       II_LONG      pd_timeout;
       II_UINT2     pd_msg_len;
       II_CHAR      *pd_message;
       II_UINT2     pd_max_reply;
       II_LONG      pd_rep_flags;
       II_UINT2     pd_rep_len;
       II_CHAR      *pd_reply;
} IIAPI_PROMPTPARM;

The syntax of the application function is as follows:

II_VOID promptFunc(IIAPI_PROMPTPARM *parm);

The application must invoke IIapi_setEnvParam() by setting se_paramID to IIAPI_EP_CAN_PROMPT and se_paramValue to the address of an application-supplied function that matches the calling sequence of the promptFunc() template function shown.

The IIAPI_PROMPTPARM parameters are described in the following table:

Previous Topic

Next Topic

Environment Parameter IIAPI_EP_TRACE_FUNC

An application can set IIAPI_EP_TRACE_FUNC in the IIapi_setEnvParam() function by providing an address of an application function to call back. OpenAPI invokes this application function to send trace information from the server to the application using the following C structure:

typedef struct _IIAPI_TRACEPARM
{
       II_PTR       tr_envHandle;
       II_PTR       tr_connHandle;
       II_INT4      tr_length;
       II_CHAR      *tr_message;
} IIAPI_TRACEPARM;

The syntax of the application function is as follows:

II_VOID traceFunc(IIAPI_PROMPTPARM *parm);

The application must invoke IIapi_setEnvParam() by providing se_paramID to be IIAPI_EP_TRACE_FUNC and se_paramValue to the address of an application-supplied function that matches the calling sequence of the traceFunc() function template shown in this section.

The IIAPI_TRACEPARM parameters are described in the following table:

Previous Topic

Next Topic

Environment Parameter IIAPI_EP_EVENT_FUNC

An application can set IIAPI_EP_EVENT_FUNC in the IIapi_setEnvParam() function by providing an address of an application function to callback. OpenAPI invokes this application function to send information on database events which failed to match an existing OpenAPI event handle (and would otherwise be ignored) to the application using the following C structure:

typedef struct _IIAPI_EVENTPARM
{
       II_PTR           ev_envHandle;
       II_PTR           ev_connHandle;
       II_CHAR          *ev_eventName;
       II_CHAR          *ev_eventOwner;
       II_CHAR          *ev_eventDB;
       IIAPI_DATAVALUE  ev_eventTime;
} IIAPI_EVENTPARM;

The syntax of the application function is as follows:

II_VOID eventFunc(IIAPI_EVENTPARM *parm);

The application must invoke IIapi_setEnvParam() by providing sc_paramID to be IIAPI_EP_EVENT_FUNC and sc_paramValue to the address of an application-supplied function that matches the calling sequence of the eventFunc() function template shown in this section.

The IIAPI_EVENTPARM parameters are described in the following table:

Previous Topic

Next Topic

IIapi_terminate() Function—Terminate OpenAPI

The IIapi_terminate() function cleans up all OpenAPI resources. This function should be called when OpenAPI functions are no longer used in the application. If multiple calls to IIapi_initialize() have been made, the OpenAPI is shut down only when the last corresponding call to this function is made; a warning status is returned otherwise.

This function has the following syntax:

II_VOID IIapi_terminate (IIAPI_TERMPARM *termParm);

typedef struct _IIAPI_TERMPARM
{
       IIAPI_STATUS   tm_status;
} IIAPI_TERMPARM;

This statement has the following parameter:

Previous Topic

Next Topic

IIapi_wait() Function—Block Application Control Until Outstanding Operation Completes or User-defined Timeout Expires

The IIapi_wait() function enables an application to give control to OpenAPI until an outstanding task completes. Because OpenAPI is asynchronous and many operating systems do not provide an interrupt mechanism for receiving incoming messages, IIapi_wait() provides a way to yield the flow of control to OpenAPI. By occasionally calling IIapi_wait(), an application ensures that it will receive incoming messages from the server.

IIapi_wait() can be used in two programming styles: synchronous and asynchronous. To support the synchronous style of programming, the application can invoke an OpenAPI function and call IIapi_wait() until the application notes the completion of the function (by checking gp_completed) before calling the next function.

In an asynchronous application, the application code itself is event-driven (the events being OpenAPI function completions). Once the first function is invoked, the application calls IIapi_wait() in a continuous top-level loop to drive all subsequent functions asynchronously.

This function has the following syntax:

II_VOID IIapi_wait (IIAPI_WAITPARM *waitParm);

typedef struct _IIAPI_WAITPARM
{
       II_LONG        wt_timeout;
       II_API_STATUS  wt_status;
} IIAPI_WAITPARM;

This function has the following parameters:

© 2007 Ingres Corporation. All rights reserved.