Release 5.0.1
Part No. A95911-01
 Contents |
 Index |
|
Oracle9i Lite Developers Guide for Palm
Release 5.0.1 Part No. A95911-01 |
|
This document describes the Open Database Connectivity (ODBC) support for Oracle Lite for the Palm Computing Platform. Topics include:
Oracle Lite for the Palm Computing Platform supports a subset of the ODBC 3.0 application programming interface standard. Using the ODBC API, applications can access data stored in the Oracle Lite database in your handheld device.
The Oracle Lite ODBC library supports the Dynamic SQL model, in which applications can construct SQL statements at runtime and execute them directly on the handheld device.
The following lists and describes all the supported ODBC API functions.
Table C-1 ODBC API Functions
| Function | Description |
|---|---|
| SQLAllocConnect | Allocates memory for a connection handle using the specified environment. |
| SQLAllocEnv | Allocates memory for an environment handle. |
| SQLAllocHandle | A generic function for allocating environment, connection, and statement handles. |
| SQLAllocStmt | Allocates memory for a statement handle using the specified connection. |
| SQLFreeConnect | Disconnects from the connected database using the specified handle, and frees the handle. |
| SQLFreeEnv | Frees the specified handle. Uncommitted transactions associated with the handle are rolled back. |
| SQLFreeHandle | A generic handle to free environment, connection, and statement handles. |
| SQLFreeStmt | Frees the specified statement handle and its associated temporary memory. |
| SQLConnect | Connects to a database and saves information about the connection in the provided connection handle. |
| SQLDisconnect | Disconnects and closes a previously connected database. |
| SQLBindParameter | Binds a data buffer to a parameter marker in a SQL statement. |
| SQLPrepare | Compiles a SQL statement and stores the information in the provided statement handle. |
| SQLExecDirect | Compiles and executes the specified SQL statement. |
| SQLExecute | Executes the prepared SQL using SQLPrepare. |
| SQLFetch | Reads in a row of data from the result set. After calling the function, the cursor is positioned to the next row to be read. |
| SQLBindCol | Binds a buffer to a column in the result set. |
| SQLDescribeCol | Retrieves information about a column of the result set. |
| SQLError | Extracts details about the last error associated to the provided handles. |
| SQLGetData | Reads in a single column from the current row into the specified buffer. |
| SQLNumResultCols | Returns the number of columns in the result set. |
| SQLRowCount | Returns the number of rows affected by a SQL SELECT, UPDATE, or DELETE statement. |
| SQLTransact | Requests a commit or rollback for all active operations on all statements associated with an environment. |
Allocates memory for a connection handle using the specified environment, hEnv.
RETCODE SQLAllocConnect( hEnv,hDbc)
Table C-2 SQLAllocConnect ARguments
| Type | Name | Description |
|---|---|---|
| SQLHENV | hEnv
|
Environment handle. If set to NULL, creates a new environment. |
| SQLHDBC* | hDbc
|
Pointer to a connection handle where the routine stores the address of the newly allocated memory. |
This function is supported for backward compatibility with ODBC 2.0. New applications should be coded using the function SQLAllocHandle and the handle type SQL_HANDLE_DBC. Internally, SQLAllocConnect calls SQLAllocHandle.
SQLAllocConnect returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified environment handle.
SQLAllocEnv allocates memory for an environment handle.
To share a single transaction for different connections and statement handles, pass in the same environment handle to SQLAllocConnection, SQLAllocStmt, or SQLAllocHandle. This way, the new handles inherit, and share, the same environment handle. When these handles are freed, the actual connections and transaction are not freed. The resources are not released until the original environment handle is freed.
RETCODE SQLAllocEnv( hEnv )
Table C-3 SQLAllocEnv Arguments
| Type | Name | Description |
|---|---|---|
| SQLHENV* | hEnv
|
Pointer to an environment handle. |
This function is supported for backward compatibility with ODBC 2.0. New applications should be coded using the function SQLAllocHandle and the handle type SQL_HANDLE_ENV. Internally, SQLAllocEnv calls SQLAllocHandle.
SQLAllocEnv returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError and pass in NULL as the handle parameter.
SQLAllocHandle is a generic function for allocating environment, connection, and statement handles.
This function replaces the old allocation functions for each individual handle types (SQLAllocEnv, SQLAllocConnection, and SQLAllocStmt).
A transaction table (new OKAPI environment) is created for each new environment handle. To share a single transaction for different connections and statement handles, pass in the same environment handle to SQLAllocHandle as the inputHandle argument. This way, the new handles inherit and share the same environment handle. When these handles are freed, the actual connections and transaction are not freed. The resources are not released until the original environment handle is freed. You can also share a connection using the same method.
RETCODE SQLAllocHandle( handleType, inputHandle, outputHandle )
Table C-4 SQLAllocHandle Arguments
| Type | Description | Name |
|---|---|---|
| SQLSMALLINT | The type of handle to allocate. See the following "Usage Note" for more information. | handleType
|
| SQLHANDLE | The handle to base on the new handle. This is either an environment or connection handle.
To create a new handle from scratch, pass in NULL. |
inputHandle
|
| SQLHANDLE* | Pointer to the storage for the newly create handle. | outputHandle
|
An application allocates different handles to use with different API functions. The handle provides a context for each function. The following handles are supported:
Table C-5 Handle Parameters
| Handle | Type | Description |
|---|---|---|
| Environment | SQL_TYPE_ENV | Environment handles are used to create an environment. Each environment contains generic information that allows you to access the database. A new transaction is associated with a newly-created environment handle. |
| Connection | SQL_TYPE_DBC | A connection handle is used to open a connection to a specific Oracle Lite database. Connections can be based on the same environment handle, hence sharing the same transaction across multiple database connections. However, a maximum of eight connections can share a single environment. |
| Statement | SQL_TYPE_STMT | The statement handle contains information about the compiled SQL statement and its result sets. |
SQLAllocHandle returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the inputHandle argument.
SQLAllocStmt allocates memory for a statement handle using the specified connection, hDbc.
RETCODE SQLAllocStmt( hDbc, hStmt )
Table C-6 SQLAllocStm Arguments
| Type | Name | Description |
|---|---|---|
| SQLHDBC | hDbc
|
The connection handle to creating the new handle. |
| SQLHSTMT* | hStmt
|
Pointer to a statement handle. |
This function is supported for backward compatibility with ODBC 2.0. New applications should be coded using the function SQLAllocHandle, and the handle type SQL_HANDLE_STMT. Internally, SQLAllocStmt calls SQLAllocHandle.
SQLAllocStmt returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified connection handle.
SQLFreeConnect disconnects from the connected database using the specified handle, and frees the handle.
RETCODE SQLFreeConnect(hDbc )
Table C-7 SQLFreeConnect Arguments
| Type | Name | Description |
|---|---|---|
| SQLHDBC | hDbc
|
The connection handle to free. |
This function is deprecated and is replaced by the new generic function SQLFreeHandle.
SQLFreeConnect returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified environment handle.
SQLFreeEnv frees the specified handle. Uncommitted transactions associated with the handle are rolled back.
RETCODE SQLFreeEnv(hEnv)
Table C-8 SQLFreeEnv Arguments
| Type | Name | Description |
|---|---|---|
| SQLHENV | hEnv
|
Environment handle to free. |
This function is deprecated and is replaced by the new generic function SQLFreeHandle.
SQLFreeEnv returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified environment handle.
SQLFreeHandle is a generic function to free environment, connection, and statement handles.
The argument handleType is not used, because the handle internally contains information about how it is last used and therefore how it should be freed.
RETCODE SQLFreeHandle(handleType, handle)
Table C-9 SQLFreeHandle Arguments
| Type | Name | Description |
|---|---|---|
| SQLSMALLINT | handleType
|
The type of handle to free. |
| SQLHANDLE | handle
|
The handle to free. |
SQLFreeHandle returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified handle.
SQLFreeStmt frees the specified statement handle and its associated temporary memory.
RETCODE SQLFreeStmt(hStmt, Option)
Table C-10 SQLFreeStmt Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle to free. |
| SQLUSMALLINT | Option
|
This argument is not currently supported and is ignored. |
This function is deprecated and is replaced by the new generic function SQLFreeHandle.
SQLFreeStmt returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified environment handle.
SQLConnect connects to a database and saves information about the connection in the provided connection handle. The handle must be previously allocated using the SQLAllocateHandle function.
RETCODE SQLConnect(hConn, dbName, dbNameLen, userName, userNameLen, auth, authLen)
Table C-11 SQLConnect Arguments
| Type | Name | Description |
|---|---|---|
| SQLHDBC | hConn
|
Newly allocated connection handle. If passed a connection handle that is in use, the function closes the existing connection. |
| SQLCHAR* | dbName
|
Name of the database to connect to. |
| SQLSMALLINT | dbNameLen
|
Length of the database name. |
| SQLCHAR* | userName
|
This argument is not currently supported and is ignored. |
| SQLSMALLINT | userNameLen
|
This argument is not currently supported and is ignored. |
| SQLCHAR* | auth
|
This argument is not currently supported and is ignored. |
| SQLSMALLINT | authLen
|
This argument is not currently supported and is ignored. |
SQLConnect returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified connection handle.
SQLDisconnect disconnects and closes a previously connected database.
If the environment used to make the connection is not committed before the connection is closed, committing afterwards fails.
RETCODE SQLDisconnect(hDbc)
Table C-12 SQLDisconnect Arguments
| Type | Name | Description |
|---|---|---|
| SQLHDBC | hDbc
|
Handle of connection to be disconnected. |
SQLDisconnect returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified connection handle.
SQLBindParameter binds a data buffer to a parameter marker in a SQL statement. Parameter markers are denoted by "?" in the SQL statement.
RETCODE SQLBindParameter( hStmt, paramNo, paramType, cType, sqlType, colDef, scale, value, valueMaxSize, valueSize )
Table C-13 SQLBlindParameter Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLUSMALLINT | paramNo
|
The number of the parameter marker to bind to. Starts from 1, counted from left to right. |
| SQLSMALLINT | paramType
|
The parameter type. Currently, only SQL_PARAM_INPUT is supported. |
| SQLSMALLINT | cType
|
The C datatype of the parameter. |
| SQLSMALLINT | sqlType
|
The SQL datatype of the parameter. |
| SQLUINTEGER | colDef
|
The precision of the parameter. |
| SQLSMALLINT | scale
|
The scale of the parameter. |
| SQLPOINTER | value
|
Pointer to the buffer where the parameter value is stored. |
| SQLINTEGER | valueMaxSize
|
The size of the parameter buffer. |
| SQLINTEGER* | valueSize
|
Actual size of the parameter value. |
SQLBindParameter returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR.
SQLPrepare compiles a SQL statement and stores the information in the provided statement handle.
RETCODE SQLPrepare(hStmt, statement, statementLen)
Table C-14 SQLPrepare Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLCHAR* | statement
|
SQL statement string. |
| SQLINTEGER | statementLen
|
Length of the SQL statement string. |
SQLPrepare returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLExecDirect compiles and executes the specified SQL statement.
RETCODE SQLExecDirect(hStmt, statement, statementLen)
Table C-15 SQLExecDirect Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLCHAR* | statement
|
SQL statement string. |
| SQLINTEGER | statementLen
|
Length of the SQL statement string. |
SQLExecDirect returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLExecute executes the prepared SQL using SQLPrepare.
RETCODE SQLExecute(hStmt)
Table C-16 SQLExecute Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle |
SQLExecute returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLFetch reads in a row of data from the result set. After calling the function, the cursor is positioned to the next row to be read.
Application can call SQLGetData to read in the columns of the read-in row.
If the application called SQLBindCol to bind columns, SQLFetch stores data from the row in the specified buffers.
RETCODE SQLFetch(hStmt)
Table C-17 SQLRetch Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle |
SQLFetch returns SQL_SUCCESS if a new row of data is read successfully.
If there are no more rows to be read, SQLFetch returns SQL_NO_DATA_FOUND.
If an error occurs, the function returns SQL_ERROR. To find out specifics about an error, the application can call SQLError with the specified statement handle.
SQLBindCol binds a buffer to a column in the result set. The buffer is updated when SQLFetch is called. New columns from the result set are then read in.
SQLBindCol can be called after or before the statement is prepared and executed, as long as it is called before SQLFetch is called.
RETCODE SQLBindCol( hStmt, columnNo, targetType, targetValue, targetSize, actualSize )
Table C-18 SQLBindCol Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLUSMALLINT | columnNo
|
The number of the column of the result set to bind to. |
| SQLSMALLINT | targetType
|
The C datatype of the buffer. |
| SQLPOINTER | targetValue
|
Pointer to buffer to hold the column data. |
| SQLINTEGER | targetSize
|
Size of the buffer in bytes. |
| SQLINTEGER* | actualSize
|
Pointer buffer to hold the size of the data read. Can pass in NULL if you do not want the information. |
SQLBindCol returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLDescribeCol retrieves information about a column of the result set.
RETCODE SQLDescribeCol(hStmt, columnNo, columnName, columnNameMaxLen,datatype, columnNameLen, columnSize, decimalDigits, nullable)
Table C-19 SQLDescribeCol Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLUSMALLINT | columnNo
|
The number of the column in the result. |
| SQLCHAR* | columnName
|
Pointer to string buffer to store the returned name of the column. |
| SQLSMALLINT | columnNameMaxLen
|
Size of the string buffer. |
| SQLSMALLINT | *columnNameLen
|
Returned size of the column name in bytes. |
| SQLSMALLINT* | dataType
|
Returned SQL datatype. |
| SQLUINTEGER* | columnSize
|
Returned size of the column. |
| SQLSMALLINT* | decimalDigits
|
Returned precision of the column. |
| SQLSMALLINT* | nullable
|
Set to 1 if column is nullable, or 0 if it is not. |
SQLDescribeCol returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLError extracts details about the last error associated with the provided handles.
RETCODE SQLError( hEnv, hConn, hStmt, sqlState, nativeError, messageText, messageMaxSize, messageLength)
Table C-20 SQLError Arguments
| Type | Name | Description |
|---|---|---|
| SQLHENV | hEnv
|
Environment handle. |
| SQLHDBC | hConn
|
Database handle. |
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLCHAR* | sqlState
|
Pointer to string buffer to store the returned SQLSTATE. |
| SQLINTEGER* | nativeError
|
Native error code. |
| SQLCHAR* | messageText
|
Error message text. |
| SQLSMALLINT | messageMaxSize
|
Size of buffer passed in. |
| SQLSMALLINT* | messageLen
|
Length of returned message text. |
SQLError returns SQL_SUCCESS if it can retrieve information related to the last error. If there were no errors associated with the specified handle, the function returns SQL_NO_DATA_FOUND .
SQLGetData reads in a single column from the current row into the specified buffer. The routine attempts to convert the data to the target buffer's type.
RETCODE SQLGetData(hStmt, columnNo, targetType, targetValue, targetSize, actualSize)
Table C-21 SQLGetData Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLUSMALLINT | columnNo
|
The number of the column. |
| SQLSMALLINT | targetType
|
The type of the buffer target Value. |
| SQLPOINTER | targetValue
|
Pointer to the buffer to store the result column data. |
| SQLINTEGER | targetSize
|
Size of the buffer. |
| SQLINTEGER* | actualSize
|
Actual number of bytes read into the specified buffer. |
SQLGetData returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLNumResultCols returns the number of columns in the result set.
RETCODE SQLNumResultCols(hStmt, columnCount)
Table C-22 SQLNumResultCols Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLSMALLINT* | columnCount
|
Pointer to buffer to store the returned number of columns in the result set. |
SQLNumResultCols returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLRowCount returns the number of rows affected by a SQL SELECT, UPDATE, or DELETE statement.
RETCODE SQLRowCount(hStmt, rowCount)
Table C-23 SQLRowCount Arguments
| Type | Name | Description |
|---|---|---|
| SQLHSTMT | hStmt
|
Statement handle. |
| SQLINTEGER* | rowCount
|
Number of rows in the result set. |
SQLRowCount returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified statement handle.
SQLTransact requests a commit or rollback for all active operations on all statements associated with an environment.
RETCODE SQLTransact(hEnv, hDbc, completionType)
Table C-24 SQLTransact Arguments
| Type | Name | Description |
|---|---|---|
| SQLHENV | hEnv
|
Environment handle. |
| SQLHDBC | hDbc
|
Connection handle. Not used. |
| SQLUSMALLINT | completionType
|
The transaction action, which could be either SQL_COMMIT or SQL_ROLLBACK. |
SQLTransact returns SQL_SUCCESS if it is successful. Otherwise, it returns SQL_ERROR. To find out the specifics about an error, the application can call SQLError with the specified environment handle.
|
 Copyright © 2002 Oracle Corporation All rights reserved |
|