SOLID Light Client Function Reference

This document is the function reference to SOLID Light Client API. The available functions, their parameter lists and allowed parameter values are introduced here.

SOLID Light Client API does not provide any ODBC Extension Level functionality, such as the parameter or data binding. For example, functions SQLBindParameter and SQLBindCol are not supported. Instead, SOLID Light Client provides SAG CLI compliant functions SQLSetParamValue for setting values to parameters and SQLGetCol for reading data from result sets. The latter is identical to the ODBC compliant function SQLGetData also provided by SOLID Light Client.

All the SOLID Light Client functions except SQLSetParamValue and SQLGetCol resemble their SOLID SQL API and ODBC 2.0 counterparts. For a full description of the other functions, please see the SOLID Server Programmer's Guide and Reference.

For an introduction on how to use SOLID Light Client API and to view some code examples, please refer to SOLID Light Client Programmer's Guide. For a complete example program on how to use SOLID Light Client API, please see SOLID Light Client Samples.

Other SOLID Light Client Documentation

• SOLID Light Client Programmer's Guide
• SOLID Light Client Samples
• SOLID Light Client v.2.3. Release Notes
• SOLID Light Client FAQ

Full SOLID SQL API (= ODBC) Function Reference

• SOLID Server Programmer's Guide and Reference

Summary of all functions

Connecting to a Data Source
SQLAllocEnv
SQLAllocConnect
SQLConnect

Preparing SQL Statements
SQLAllocStmt
SQLPrepare
SQLSetParamValue
SQLSetCursorName
SQLGetCursorName

Submitting Requests
SQLExecute
SQLExecDirect

Retrieving Results and Information about Results
SQLRowCount
SQLNumResultCols
SQLDescribeCol
SQLGetCol
SQLFetch
SQLGetData
SQLError

Terminating a Statement
SQLFreeStmt
SQLTransact

Terminating a Connection
SQLDisconnect
SQLFreeConnect
SQLFreeEnv

SQLAllocConnect

SQLAllocConnect allocates memory for a connection handle within the environment identified by henv.

Syntax

RETCODE SQLAllocConnect(
        HENV henv,
        HDBC* phdbc);

The SQLAllocConnect function accepts the following arguments:  

See also SQLAllocConnect in SOLID Server Programmer's Guide and Reference.

SQLAllocEnv

SQLAllocEnv allocates memory for an environment handle and initializes the ODBC call level interface for use by an application. An application must call SQLAllocEnv prior to calling any other ODBC function.

Syntax

RETCODE SQLAllocEnv(
        HENV* phenv);

The SQLAllocEnv function accepts the following argument:  

See also SQLAllocEnv in SOLID Server Programmer's Guide and Reference.

SQLAllocStmt

SQLAllocStmt allocates memory for a statement handle and associates the statement handle with the connection specified by hdbc. An application must call SQLAllocStmt prior to submitting SQL statements.

Syntax

RETCODE SQLAllocStmt(
        HDBC hdbc,
        HSTMT* phstmt);

The SQLAllocStmt function accepts the following arguments:  

See also SQLAllocStmt in SOLID Server Programmer's Guide and Reference.

SQLConnect

SQLConnect establishes a connection to a SOLID Server listening in the network for TCP/IP. The connection handle references storage of all information about the connection, including status, transaction state, and error information.

Syntax

RETCODE SQLConnect(
        HDBC hdbc,
        UCHAR* szDSN,
        SWORD cbDSN,
        UCHAR* szUID,
        SWORD cbUID,
        UCHAR* szAuthStr,
        SWORD cbAuthStr);

The SQLConnect function accepts the following arguments:  

A valid connect string consists of a host computer name or its ip-address and a port number. For example the following strings are valid: '192.168.1.111 1313' and 'calvin 1313'.Note that valid connnect strings for ODBC and SOLID SQL API applications cannot be used.

See also SQLConnect in SOLID Server Programmer's Guide and Reference.

SQLDescribeCol

SQLDescribeCol returns the result descriptor — column name, type, precision, scale, and nullability — for one column in the result set.

Syntax

RETCODE SQLDescribeCol(
        HSTMT hstmt,
        UWORD icol,
        UCHAR* szColName,
        SWORD cbColNameMax,
        SWORD* pcbColName,
        SWORD* pfSqlType,
        UDWORD* pcbColDef,
        SWORD* pibScale,
        SWORD* pfNullable);

The SQLDescribeCol function accepts the following arguments:  

See also SQLDescribeCol in SOLID Server Programmer's Guide and Reference.

SQLDisconnect

SQLDisconnect closes the connection associated with a specific connection handle.

Syntax

RETCODE SQLDisconnect(
        HDBC hdbc);

The SQLDisconnect function accepts the following argument:  

See also SQLDisconnect in SOLID Server Programmer's Guide and Reference.

SQLError

SQLError returns error or status information. This function should be called when a call to a Light Client API function returns either value SQL_ERROR or value SQL_SUCCESS_WITH_INFO

Syntax

RETCODE SQLError(
        HENV henv,
        HDBC hdbc,
        HSTMT hstmt,
        UCHAR* szSqlState,
        SDWORD* pfNativeError,
        UCHAR* szErrorMsg,
        SWORD cbErrorMsgMax,
        SWORD* pcbErrorMsg);

The SQLError function accepts the following arguments:  

  See also SQLError in SOLID Server Programmer's Guide and Reference.

SQLExecDirect

SQLExecDirect executes a preparable statement, using the current values of the parameter marker variables if any parameters exist in the statement. SQLExecDirect is the fastest way to submit an SQL statement for one-time execution.

Syntax

RETCODE SQLExecDirect(
        HSTMT hstmt,
        UCHAR* szSqlStr,
        SDWORD cbSqlStr);

The SQLExecDirect function accepts the following arguments:  

See also SQLExecDirect in SOLID Server Programmer's Guide and Reference.

SQLExecute

SQLExecute executes a prepared statement, using the current values of the parameter marker variables if any parameter markers exist in the statement.

Syntax

RETCODE SQLExecute(
        HSTMT hstmt);

The SQLExecute function accepts the following argument:  

See also SQLExecute in SOLID Server Programmer's Guide and Reference.

SQLFetch

SQLFetch fetches a row of data from a result set. Normal operation may return SQL_SUCCESS or SQL_NO_DATA_FOUND.

Syntax

RETCODE SQLFetch(
        HSTMT hstmt);

The SQLFetch function accepts the following argument:  

See also SQLFetch in SOLID Server Programmer's Guide and Reference.

SQLFreeConnect

SQLFreeConnect releases a connection handle and frees all memory associated with the handle.

Syntax

RETCODE SQLFreeConnect(
        HDBC hdbc);

The SQLFreeConnect function accepts the following argument:  

See also SQLFreeConnect in SOLID Server Programmer's Guide and Reference.

SQLFreeEnv

SQLFreeEnv frees the environment handle and releases all memory associated with the environment handle.

Syntax

RETCODE SQLFreeEnv(
        HENV henv);

The SQLFreeEnv function accepts the following argument:  

See also SQLFreeEnv in SOLID Server Programmer's Guide and Reference.

SQLFreeStmt

SQLFreeStmt stops processing associated with a specific hstmt, closes any open cursors associated with the hstmt, discards pending results, and, optionally, frees all resources associated with the statement handle.

Syntax

RETCODE SQLFreeStmt(
        HSTMT hstmt,
        UWORD fOption);

The SQLFreeStmt function accepts the following arguments:  

See also SQLFreeStmt in SOLID Server Programmer's Guide and Reference.

SQLGetCol

SQLGetCol gets result data for a single column in the current row. This function allows the application to retrieve the data one column at the time. It may also be used to retrieve large data values in easily manageable blocks.

SQLGetCol is functionally identical to its ODBC API counterpart SQLGetData. For detailed SQLGetData reference page, please browse SOLID Server Programmer's Guide and Reference .

Syntax

RETCODE SQLGetCol(
        HSTMT hstmt,
        UWORD icol,
        SWORD fCType,
        PTR rgbValue,
        SDWORD cbValueMax,
        SDWORD* pcbValue);

The SQLGetCol function accepts the following arguments:  

Returned values

SQL_SUCCESS, SQL_ERROR, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE or SQL_NO_DATA_FOUND

Diagnostics

If more data is available to be retrieved, SQL_SUCCESS_WITH_INFO is returned ('01004' -- Data truncated).
If the data cannot be converted to the type specified fcType, SQL_ERROR is returned ('07006' -- Restricted data type attribute violation).
If the communication link failed before the function completed processing, SQL_ERROR is returned ('08S01' -- Communication link failure).
If the previous SQL statement executed on the hstmt was not a SELECT, SQL_ERROR is returned ('24000' --Invalid cursor state).

Comments

SQLFetch must be called before calling SQLGetCol. SQLGetCol can then be used to retrieve data for specific columns, in order. SQLGetCol cannot be used to retrieve a column that resides at or before the last column retrieved with SQLGetCol.

If a call to SQLGetCol does not retrieve all data for the given column, pcbValue is set to the total number of bytes in the result and SQL_SUCCESS_WITH_INFO is returned with the SQLSTATE value '01004' -- Data truncated. SQLGetCol may then be called repeatedly with the same column number until SQLGetCol returns SQL_SUCCESS, or with a different column number to ignore the remainder of the data for the original column.

Code example

The following code excerpt prepares an SQL Statement "SELECT I,C FROM TESTTABLE", executes it and fetches all the rows the database returns.
The example code below expects valid definitions for rc, hdbc, hstmt and henv.

  rc = SQLPrepare(hstmt,(UCHAR*)
  "SELECT I,C FROM TESTTABLE",SQL_NTS);
  ...
  rc = SQLExecute(hstmt);
  ...
  rc = SQLFetch(hstmt);
  if ((SQL_SUCCESS != rc) && (SQL_NO_DATA_FOUND != rc)) {
    printf("SQLFetch returned an unexpected error code . \n");
  }

  while (SQL_NO_DATA_FOUND != rc)
  {
     rc = SQLGetCol(hstmt,1,SQL_C_LONG,&lbuf,sizeof(lbuf),NULL);
    if (SQL_SUCCESS == rc)
    {
      printf("LC_SQLGetCol(1) returns %d \n",lbuf);
     }
    else printf("Error in SQLGetCol(1) \n");

    rc = SQLGetCol(hstmt,2,SQL_C_CHAR,buf,sizeof(buf),NULL);
 
    if (SQL_SUCCESS == rc)
    {
      printf("SQLGetCol(2) returns %s \n",buf);
    }
    else printf("Error in SQL_GetCol(2) \n");
 
    rc = SQLFetch(hstmt);
  }
  rc = m_lc->LC_SQLFreeStmt(hstmt,SQL_DROP);
  ... 

Related functions

SQLGetCursorName

SQLGetCursorName returns the cursor name associated with a specified hstmt.

Syntax

RETCODE SQLGetCursorName(
        HSTMT hstmt,
        UCHAR* szCursor,
        SWORD cbCursorMax,
        SWORD* pcbCursor);

The SQLGetCursorName function accepts the following arguments:  

See also SQLGetCursorName in SOLID Server Programmer's Guide and Reference.

SQLGetData

SQLGetData returns result data for a single unbound column in the current row. The application must call SQLFetch to position the cursor on a row of data before it calls SQLGetData. This function can be used to retrieve character or binary data values in parts from a column with a character, binary, or data source–specific data type (for example, data from SQL_LONGVARBINARY or SQL_LONGVARCHAR columns).

SQLGetData is functionally identical to its SAG CLI counterpart SQLGetCol.

Syntax

RETCODE SQLGetData(
        HSTMT hstmt,
        UWORD icol,
        SWORD fCType,
        PTR rgbValue,
        SDWORD cbValueMax,
        SDWORD* pcbValue);

The SQLGetData function accepts the following arguments:  

See also SQLGetData in SOLID Server Programmer's Guide and Reference.

Related functions

SQLNumResultCols

SQLNumResultCols returns the number of columns in a result set.

Syntax

RETCODE SQLNumResultCols(
        HSTMT hstmt,
        SWORD* pccol);

The SQLNumResultCols function accepts the following arguments:  

See also SQLNumResultCols in SOLID Server Programmer's Guide and Reference.

SQLPrepare

SQLPrepare prepares an SQL string for execution.

Syntax

RETCODE SQLPrepare(
        HSTMT hstmt,
        UCHAR* szSqlStr,
        SDWORD cbSqlStr);

The SQLPrepare function accepts the following arguments:  

 See also SQLPrepare in SOLID Server Programmer's Guide and Reference.

SQLRowCount

SQLRowCount returns the number of rows affected by an UPDATE, INSERT, or DELETE statement.

Syntax

RETCODE SQLRowCount(
        HSTMT hstmt,
        SDWORD* pcrow);

The SQLRowCount function accepts the following arguments:  

See also SQLRowCount in SOLID Server Programmer's Guide and Reference.

SQLSetCursorName

SQLSetCursorName associates a cursor name with an active hstmt. If an application does not call SQLSetCursorName, the driver generates cursor names as needed for SQL statement processing.

Syntax

RETCODE SQLSetCursorName(
        HSTMT hstmt,
        UCHAR* szCursor,
        SWORD cbCursor);

The SQLSetCursorName function accepts the following arguments:  

See also SQLSetCursorName in SOLID Server Programmer's Guide and Reference.

SQLSetParamValue

Sets the value of a parameter marker in the SQL statement specified in SQLPrepare. Parameter markers are numbered sequentially from left-to-right, starting with one, and may be set in any order. The value of argument rgbValue will be used for the parameter marker when SQLExecute is called.

Syntax

RETCODE SQLSetParamValue(
        HSTMT hstmt,
        UWORD ipar,
        SWORD fCType,
        SWORD fSqlType,
        UDWORD cbColDef,
        SWORD ibScale,
        PTR rgbValue,
        SDWORD* pcbValue);

The SQLSetParamValue function accepts the following arguments:  

fCType describes the contents of rgbValue. fCType must either be SQL_C_CHAR ot the C equivalent of argument fSqlType. If fCType is SQL_C_CHAR and fSqlType is a numeric type, rgbValue will be converted from a character string to the type specified by fSqlType.

fSqlType is the data type of the column or expression referenced by the parameter marker. At execute time, the value in rgbValue will be read and converted from fCType to fSqlType, and then sent to SOLID Server. Note that the value of rgbValue remains unchanged.

cbColDef is the length or precision of the column definition for the column or expression referenced. cbColDef differs depending on the class of data as follows:  

ibScale is the total number of digits to the right of the decimal point for the column referenced. ibScale is defined only for the SQL_DECIMAL and SQL_NUMERIC data types.

rgbValue is a character string that must contain the actual data for the parameter marker. The data must be of the form specified by the fCType argument.

pcbValue is an integer that is the length of the parameter marker value in rgbValue. It is only used when fCType is SQL_C_CHAR or when specifying a null database value. The variable must be set to SQL_NULL_DATA if a null value is to be specified for the parameter marker. If the variable is set to SQL_NTS then rgbValue will be treated as a null terminated string.

Returned values

SQL_SUCCESS, SQL_ERROR or SQL_INVALID_HANDLE

Diagnostics

If the data identified by the fcType argument cannot be converted to the data value identified by the fSqlType argument, SQL_ERROR is returned ('07006' -- Restricted data type attribute violation).
If the fcType argument is not valid, SQL_ERROR is returned ('S1003' -- Program type out of range).
If the fSqlType argument is not valid, SQL_ERROR is returned ('S1004' -- SQL data type out of range).
If the ipar argument is less than 1, SQL_ERROR is returned ('S1009' -- Invalid argument value).

Comments

All parameters set by this function remain in effect until either SQLFreeStmt is called with the SQL_UNBIND_PARAMS or SQL_DROP option or SQLSetParamValue is called again for the same parameter number. When an SQL statement containing parameters is executed, the set values of the parameters are sent to SOLID Server. Note that the number of parameters must match exactly the number of parameter markers present in the statement that was prepared. If less parameter values are set than there were parameter markers in the SQL statement, NULL values will be used instead.

Code example

The code example below prepares a simple statement INSERT INTO TESTTABLE (I,C) VALUES (?,?) to be executed several times with different parameter values.

...
  char buf[255];
  SDWORD dwPar;
...
  rc = SQLPrepare(hstmt,(UCHAR*)"INSERT INTO TESTTABLE(I,C) VALUES (?,?)",SQL_NTS);
 
  if (SQL_SUCCESS != rc) {
    printf("Prepare failed. \n");
  }

  for (i=1;i<100;i++)
  {
    dwPar = i;
    sprintf(buf,"line%i",i);
 
    rc = m_lc->LC_SQLSetParamValue(
hstmt,1,SQL_C_LONG,SQL_INTEGER,0,0,&dwPar,NULL );
    if (SQL_SUCCESS != rc) {
      printf("(SetParamValue 1 failed) \n");
      return 0;
    }

    rc = m_lc->LC_SQLSetParamValue(
hstmt,2,SQL_C_CHAR,SQL_CHAR,0,0,buf,NULL );
    if (SQL_SUCCESS != rc) {
      printf("(SetParamValue 1 failed) \n");
      return 0;
    }

Related functions  

SQLTransact

SQLTransact requests a commit or rollback operation for all active operations on all hstmts associated with a connection. SQLTransact can also request that a commit or rollback operation be performed for all connections associated with the henv.

Syntax

RETCODE SQLTransact(
        HENV henv,
        HDBC hdbc,
        UWORD fType);

The SQLTransact function accepts the following arguments:  

See also SQLTransact in SOLID Server Programmer's Guide and Reference.

Company | Products | Support | Search | Free Eval Packs
Copyright © 1992-1997 Solid Information Technology Ltd. All rights reserved.