Home

Informix CLI Programmer`s Manual, Version 2.8

Contents

1. Read through the result set until the cursor is positioned on the row for the 25 year old John Smith do retcode SQLFetch hstmtSelect while retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO 88 stremp szName Smith John 0 sAge 25 Perform a positioned update of John Smith s name if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO SQLExecDirect hstmtUpdate UPDATE EMPLOYEE SET NAME Smith John D WHERE CURRENT OF C1 SQL_NTS INFORMIX CLI Function Reference 12 293 SQL SetCursorName 12 294 Related Functions For Information About Executing an SQL statement Executing a prepared SQL statement Returning a cursor name Setting cursor scrolling options See SQLExecDirect SQLExecute SOLGetCursorName SQLSetScrollOptions INFORMIX CLI Programmer s Manual SQL SetScrol Options SQLSetScrollOptions In ODBC 2 0 the SQL_CURSOR_TYPE SQL_CONCURRENCY SQL_KEYSET_SIZE and SQL_ROWSET_SIZE options for SOLSetStmtOption superseded SQLSetScrollOptions Applications should not call SQLSetScrollOptions INFORMIX CLI Function Reference 12 295 SQL SetStmtOption SQLSetStmt Option SQLSetStmtOption sets options that are related to an hstmt To set an option for all the statements associated with a specific hdbc an application can call SOLSetConnectOption Syntax RETCODE SQLSetStmtOption hstmt fOption vPara
2. denotes those tables that do not have owners Length of szPkTableOwner 1 of 2 SQLForeignKeys Type Argument Use Description UCHAR FAR szPkTableName Input Primary key table name SWORD cbPkTableName Input Length of szPkTableName UCHAR FAR szFkTableQualifier Input Foreign key table qualifier If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have qualifiers SWORD cbFkTableQualifier Input Length of szFkTableQualifier UCHAR FAR szFkTableOwner Input Foreign key owner name If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have owners SWORD cbFkTableOwner Input Length of szFkTableOwner UCHAR FAR szFkTableName Input Foreign key table name SWORD cbFkTableName Input Length of szFkTableName 2 of 2 Returns SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 145 SQL ForeignKeys Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indi
3. For Information About See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SOLCancel Returning the columns in a table or tables SOLColumns Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SOLFetch Returning the columns of a primary key SOLPrimaryKeys INFORMIX CLI Programmer s Manual SQL Statistics SQLStatistics SQLStatistics retrieves a list of statistics about a single table and the indexes associated with the table The driver returns this information as a result set Syntax RETCODE SQLStatistics hstmt szTableQualifier cbTableQualifier szTableOwner cbTableQwner szTableName cbTableName fUnique fAccuracy The SQLStatistics function accepts the following arguments Typedef Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szTableQualifier Input Qualifier name If a driver supports quali fiers for some tables but not for others as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have qualifiers SWORD cbTableQualifier Input Length of szTableQualifier UCHAR FAR szTableOwner Input Owner name If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have owners SWORD cbTableOwner Input Length of szTableOwner
4. Function Description SOLDataSources Retrieves a list of available data sources INFORMIX CLI retrieves this information from the initialization files An application can present this information to a user or automatically select a data source SOLDrivers Retrieves a list of installed drivers and their attributes INFORMIX CLI retrieves this information from the odbcinst ini file An application can present this infor mation to a user or automatically select a driver SOLGetFunctions Retrieves functions supported by a driver This function allows an application to determine at runtime whether a particular function is supported by a driver SOLGetInfo Retrieves general information about a driver and data source including filenames versions conformance levels and capabilities SOLGetTypelnfo Retrieves the SQL data types supported by a driver and data source SQLSetConnectOption Sets or retrieves connection options such as the data SOLGetConnectOption source access mode automatic transaction commitment time out values function tracing data translation options and transaction isolation Connecting to a Data Source 4 15 Executing SQL Statements SQL Statements and INFORMIX CLI Allocating a Statement Handle Executing an SQL Statement Prepared Execution Direct Execution Setting Parameter Values Performing Transactions Retrieving Information About the Data Source Catalog Sending Parameter Data at E
5. m SQL_CONCUR_LOCK Cursor uses the lowest level of locking sufficient to ensure that the row can be updated m SQL_CONCUR_ROWVER Cursor uses optimistic concurrency control comparing row versions m SQL_CONCUR_VALUES Cursor uses optimistic concurrency control comparing values The default value is SQL_CONCUR_READ_ONLY This option can also be set through the fConcurrency argument in SQLSetScrollOptions This option cannot be specified for an open cursor If the SQL_CURSOR_TYPE fOption is changed to a cursor type that does not support the current value of SQL_CONCURRENCY the value of SQL_CONCURRENCY is not automatically changed to a supported value and no error will be reported until SQLExecDirect or SQLPrepare is called If the driver supports the SELECT_FOR_UPDATE statement and such a statement is executed while the value of SQL_CONCURRENCY is set to SQL_CONCUR_READ_ONLY an error will be returned If the value of SQL_CONCURRENCY is changed to a value that the driver supports for some value of SQL_CURSOR_TYPE but not for the current value of SQL_CURSOR_TYPE the value of SQL_CURSOR_TYPE is not automatically changed to a supported value and no error will be reported until SQLExecDirect or SQLPrepare is called If the data source does not support the specified concurrency the driver substitutes a different concurrency and returns SQLSTATE 01502 Option value changed For SQL_CONCUR_VALUES the driver substitutes SQL_CONCUR_RO
6. AND address AND city AND state AND zip 2 SQL_NTS fairly complex query Applications should call SQLSpecialColumns SQL_BEST_ROWID to retrieve the optimal set of columns possibly a pseudocolumn that identifies any given record Many databases support special columns that are not explicitly user defined in the table definition but are hidden columns of every table for example ROWID TID and so on These pseudocolumns almost always provide the fastest access to the data because they typically are pointers to the exact location of the record Because pseudocolumns are not part of the explicit table definition they are not returned from SQLColumns The only way to determine whether pseudocolumns exist is to call SQLSpecialColumns Consider the previous example this time using SOLSpecialColumns rc SQLSpecialColumns hstmt emp rc SQLExecDirect hstmt SELECT first_name last_name ssn address city state zip ROWID FROM emp SQL_NTS fetch data and probably hide ROWID from the user rc SQLExecDirect hstmt UPDATE emp SET address WHERE ROWID SQL_NTS fastest access to the data If your data source does not contain special pseudocolumns the result set of SQLSpecialColumns consists of the columns of the optimal unique index on the specified table if a unique index exists Therefore your application need not additionally call SQLStatistics to find
7. An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support executing or completing the function DM The value specified for the argument icol was 0 and the argument fDescType was not SQL_COLUMN_COUNT The value specified for the argument icol was greater than the number of columns in the result set and the argument fDescType was not SQL_COLUMN_COUNT 1 of 2 SQLSTATE Error S1008 S1010 S1090 S1091 S1C00 S1T00 Operation canceled Function sequence error Invalid string or buffer length Descriptor type out of range Driver not capable Time out expired SQLColAttributes Description The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application DM The function was called prior to calling SQLPrepare or SOLExecDirect for the hstmt DM SOLExecute or SOLExecDirect was called for the hstmt and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value specified for the argument cbDescMax was less than 0 DM The value specified for the argument fDescType was in the block of numbers reserved for ODBC descrip
8. INFORMIX CLI Function Reference 12 313 SQL Statistics 12 314 SQLSTATE Error 1101 Accuracy option type out of range S1C00 Driver not capable S1T00 Time out expired Usage the result set INFORMIX CLI Programmers Manual Description DM An invalid fAccuracy value was specified A table qualifier was specified but the driver or data source does not support qualifiers A table owner was specified but the driver or data source does not support owners The driver or data source did not support the combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options The time out period expired before the data source returned the requested result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLStatistics returns information about a single table as a standard result set ordered by NON_UNIQUE TYPE INDEX_QUALIFIER INDEX_NAME and SEO_IN_INDEX The result set combines statistics information for the table with information about each index The following table lists the columns in Important SQLStatistics might not return all indexes Applications can use any valid index regardless of whether SQLStatistics returns it SQL Statistics The lengths of VARCHAR columns shown in the table are maximums the actual lengths depend on the data source To determine the actual lengths of the TABLE_QUALIFIER TABLE_OWNER TABLE_NAME and COLUM
9. S1008 S1010 S1090 S1100 General warning Communication link failure Invalid cursor state General error Memory allocation failure Operation canceled Function sequence error Invalid string or buffer length Uniqueness option type out of range Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The communication link between the driver and the data source failed before the function completed A cursor was already opened on the statement handle An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multithreaded application DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value of one of the name length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corresponding qualifier or name DM An invalid fUnique value was specified 1 of 2
10. The driver did not allocate memory required to support execution or completion of the function The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application DM The argument szSq Str was a null pointer DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The argument cbSqlStr was less than or equal to 0 but not equal to SOL_NTS A parameter value set with SOLBindParameter was a null pointer and the parameter length value was not 0 SOL_NULL_DATA SQL_DATA_AT_EXEC or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET A parameter value set with SQLBindParameter was not a null pointer and the parameter length value was less than 0 but was not SQL_NTS SQL_NULL_DATA SQL_DATA_AT_EXEC or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET 4 of 5 INFORMIX CLI Programmers Manual SQLExecDirect SQLSTATE Error 1109 S1C00 S1T00 Description Invalid cursor The argument szSq Str contained a positioned UPDATE or DELETE position statement but the cursor was positioned by SQLExtendedFetch on a row for which the value in the rgfRowStatus array in SQLExtendedFetch was SQL_ROW_DELETED or SQL_ROW_ERROR Driver not capable The combination of the current settings of the SQL_CONCURRENCY and SQ
11. The following table describes the actions that the driver manager performs for each function Functions Action SOLDataSources The driver manager processes the call It does not pass SQLDrivers the call to the driver SOLGetFunctions The driver manager passes the call to the driver associated with the connection SOLAllocEnv The driver manager calls SOLAllocEnv SOLAllocConnect SOLAllocConnect and SOLSetConnectOption in SOLSetConnectOption the driver when the application calls a function to SOLFreeConnect connect to the data source SOLConnect SQLFreeEnv SQLDriverConnect or SQLBrowseConnect The driver manager calls SQLFreeConnect and SQLFreeEnv in the driver when the application calls SOLDisconnect SOLConnect The driver manager performs initial processing and SQLDriverConnect then passes the call to the driver that is associated with SQLBrowseConnect the connection SQLError All other functions The driver manager passes the call to the driver Guidelines for Calling INFORMIX CLI Functions 3 7 Calling Functions If requested the driver manager records each called function in a trace file It records the name of the function the values of the input arguments and the names of the output arguments as listed in the function definitions Tip For improved performance your application can bypass the driver manager and link directly to the driver This solution reduces computational overhead If your application t
12. UWORD TablesExists ColumnsExists StatisticsExists SQLGetFunctions hdbc SQL_API_SQLTABLES amp TablesExists SQLGetFunctions hdbc SQL_API_SQLCOLUMNS amp ColumnsExists SQLGetFunctions hdbc SQL_API_SQLSTATISTICS amp StatisticsExists if TablesExists amp amp ColumnsExists amp amp StatisticsExists Continue with application SQLDisconnect hdbc The second example calls SQLGetFunctions once and passes it an array in which SQLGetFunctions returns information about all INFORMIX CLI functions UWORD fExists 100 SQLGetFunctions hdbc SQL_API_ALL_FUNCTIONS fExists if fExists SOL_API_SOLTABLES amp amp fExists SQL_API_SQLCOLUMNS amp amp fExists SQL_API_SQLSTATISTICS I Continue with application SQLDisconnect hdbc 12 182 INFORMIX CLI Programmer s Manual SQLGetFunctions Related Functions For Information About See Returning the setting of a connection option SQLGetConnectOption Returning information about a driver or data source SOLGetInfo Returning the setting of a statement option SOLGetStmtOption INFORMIX CLI Function Reference 12 183 SQL Getinto SQLGetInfo SQLGetInfo returns general information about the driver and data source associated with an hdbc Syntax RETCODE SQLGetInfo hdbc flnfoType rgbInfoValue cbInfoValueMax pcbInfoValue The SQLGetInfo function accepts the following arguments Type Argument Use De
13. for descending NULL is returned if column sort sequence is not supported by the data source or if TYPE is SQL_TABLE_STAT CARDINALITY INTEGER Cardinality of table or index number of rows in table if TYPE is SQL_TABLE_STAT number of unique values in the index if TYPE is not SQL_TABLE_STAT NULL is returned if the value is not available from the data source PAGES INTEGER Number of pages used to store the index or table number of pages for the table if TYPE is SQL_TABLE_STAT number of pages for the index if TYPE is not SQL_TABLE_STAT NULL is returned if the value is not available from the data source or if not applicable to the data source FILTER_CONDITION VARHAR 128 If the index is a filtered index this is the filter condition such as SALARY gt 30000 if the filter condition cannot be determined this is an empty string NULL if the index is not a filtered index it cannot be determined whether the index is a filtered index or TYPE is SQL_TABLE_STAT 3 of 3 If the row in the result set corresponds to a table the driver sets TYPE to SQL_TABLE_STAT and sets NON_UNIQUE INDEX_QUALIFIER INDEX_NAME SEQ_IN_INDEX COLUMN_NAME and COLLATION to NULL If CARDINALITY or PAGES are not available from the data source the driver sets them to NULL Code Example For a code example of a similar function see SQLColumns INFORMIX CLI Function Reference 12 317 SQL Statistics 12 318 Related Func
14. include sql h dinclude lt string h gt include lt stdlib h gt itdefine MAXCOLS 100 define max a b a gt b a b int print_err HDBC hdbc HSTMT hstmt UDWORD display_size SWORD coltype UDWORD collen UCHAR colname example2 server uid pwd sqlstr UCHAR server UCHAR uid UCHAR pwd UCHAR sqlstr int ay HENV henv HDBC hdbc HSTMT hstmt UCHAR errmsg 256 UCHAR colname 32 SWORD coltype SWORD colnamelen SWORD nullable UDWORD collen MAXCOLS SWORD scale SDWORD outlen MAXCOLS UCHAR data MAXCOLS SWORD nresultcols SDWORD rowcount RETCODE rc Allocate environment and connection handles Connect to the data source Xi Allocate a statement handle RA SQLAIlocEnv amp henv SQLA re ocConnect henv amp hdbc SQLConnect hdbc server SQL_NTS uid SQL_NTS pwd SQL_NTS if rc SQL_SUCCESS amp amp rc SQL_SUCCESS_WITH_INFO s eturn print_err hdbc SQL_NULL_HSTMT SQLAllocStmt hdbc amp hstmt Execute the SQL statement if SQLExecDirect hstmt sqlstr SQL_NTS return print_err hdbc hstmt See what kind of statement it was If there are no result t SQL_SUCCESS Constructing an INFORMIX CLI Application 9 7 Interactive Ad Hoc Query Example if 9 8 columns the statementis not a SELECT number of affected rows is g
15. BES 420 LES EN 1 rget irow szName rget irow sAge EN 1 rgetLirow szBirthday For Information About See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SOLCancel Returning information about a column in a result set SOLDescribeCol Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute Returning the number of result set columns SOLNumResultCols Setting a statement option SOLSetStmtOption INFORMIX CLI Function Reference 12 137 SQL Fetch SOLFetch SOLFetch fetches a row of data from a result set The driver returns data for all columns that were bound to storage locations with SOLBindCol Syntax RETCODE SQLFetch hstmt The SQLFetch function accepts the following argument Type Argument Use Description HSTMT hstmt Input Statement handle Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NO_DATA_ FOUND SOL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE 12 138 INFORMIX CLI Programmer s Manual Diagnostics SQLFetch When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SQLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the not
16. INFORMIX CLI Programmer s Manual INFORMIX OnLine Dynamic Server Version 7 2x INFORMIX OnLine Workgroup Server Version 7 2x INFORMIX OnLine XPS Version 8 1x INFORMIX SE Version 7 2x INFORMIX Universal Server Version 9 1x Version 2 8 October 1997 Part No 000 4165 Published by INFORMIX Press Informix Software Inc 4100 Bohannon Drive Menlo Park CA 94025 Copyright 1981 1997 by Informix Software Inc or their subsidiaries provided that portions may be copyrighted by third parties as set forth in documentation All rights reserved This book incorporates text that is copyright 1994 Microsoft Corporation This text was taken by permission from Microsoft s Programmer s Reference Microsoft Open Database Connectivity Software Development Kit Version 2 0 The following are worldwide trademarks of Informix Software Inc or its subsidiaries registered in the United States of America as indicated by and in numerous other countries worldwide INFORMIX INFORMIX OnLine Dynamic Server DataBlade The following are worldwide trademarks of the indicated owners or their subsidiaries registered in the United States of America as indicated by and in numerous other countries worldwide Microsoft Corporation Microsoft Windows Windows NT Windows 95 Windows for Workgroups ODBC X Open Company Ltd UNIX X Open All other marks or symbols are registered trademarks or trad
17. SQL to C Time Stamp The time stamp INFORMIX CLI SQL data type is SOL_TIMESTAMP The following table shows the INFORMIX CLI C data types to which time stamp SQL data can be converted fCType Test rgbValue pcbValue SQLSTATE SQL_C_CHAR cbValueMax gt Display size Data Length of data N A 20 lt cbValueMax lt Display size Truncated data Length of data 01004 cbValueMax lt 20 Untouched Untouched 22003 SQL_C_BINARY Length of data lt cbValueMax Data Length of data N A Length of data gt cbValueMax Untouched Untouched 22003 SQL_C_DATE Time portion of time stamp is zero Data 6f N A Time portion of time stamp is Truncated data 6f 01004 nonzero SQL_C_TIMESTAMP Fractional seconds portion of time Data 16 f N A stamp is not truncated Fractional seconds portion of time Truncated data 16f 01004 stamp is truncated The value of cbValueMax is ignored for this conversion The driver assumes that the size of rgbValue is the size of the C data type P The fractional seconds of the time stamp are truncated The time portion of the time stamp is truncated d The date portion of the time stamp is ignored e The fractional seconds portion of the time stamp is truncated f This is the size of the corresponding C data type When time stamp SQL data is converted to character C data the resulting string is in the yyyy mm dd hh mm ss f format where up to nine digits can be used for fractional seco
18. SWORD UWORD UWORD SDWORD UWORD SWORD FAR SDWORD FAR UDWORD FAR SWORD FAR SWORD FAR SDWORD FAR UDWORD FAR SWORD SDWORD UWORD HDBC FAR Count of bytes Count of rows Flag Connection handle Environment handle Statement handle Widget Byte index Column index Parameter index Row index Pointer to byte count Pointer to column count Pointer to parameter count Pointer to row count Pointer to flag Pointer to connection handle 1 of 2 INFORMIX CLI Function Reference 12 5 Arguments Typedefs for Standard C Combined Prefix Tag Data Types Description phenv ph env HENV FAR Pointer to environment handle phstmt ph stmt HSTMT FAR Pointer to statement handle pib pi b SWORD FAR Pointer to byte index pirow pi row UDWORD FAR Pointer to row index prgb pre b PTR FAR Pointer to range array of bytes pv p v PTR Pointer to value of unspecified type rgb rg b PTR Range array of bytes rgf rg f UWORD FAR Range array of flags SZ SZ UCHAR FAR String zero terminated v v UDWORD Value of unspecified type 2 of 2 Qualifiers are used to distinguish specific variables of the same typedef Qualifiers consist of the concatenation of one or more capitalized English words or abbreviations INFORMIX CLI defines one value for the suffix Max which denotes that the variable represents the largest value of its type for a given situation For example
19. Server Host Service Protocol UID PWD 5 Inthe Data Source Name text box enter the name of the data source to access You define the Data Source Name that is it can be any name that you choose The Data Source Name is like an envelope that contains all relevant connection information about the data source 6 Inthe Database text box enter the name of the database to which you want to connect by default You now have entered enough information to connect to the data source 7 Enter any additional information that you want to specify about this data source For a description of optional data see Adding a Data Source on page 2 4 2 6 INFORMIX CLI Programmer s Manual Modifying a Data Source 8 Click OK The Data Sources dialog box appears again 9 To add another data source click Add To exit the Data Sources dialog box click Close When you click OK in the INFORMIX CLI DSN Setup dialog box the ODBC Administrator updates the data source information in the appropriate files When you use a dialog box or connection string to connect to this data source the values that you entered are the default entries for the data source connection Modifying a Data Source Data sources that you configured with earlier versions of INFORMIX CLI are not valid because they specify an earlier version of the INFORMIX CLI library To use the features in INFORM
20. The SQL_FN_CVT_CONVERT bitmask is used to determine which conversion functions are supported of 24 INFORMIX CLI Function Reference 12 195 SQL Getinto InfoType SOL_CORRELATION_NAME Returns A 16 bit integer that indicates if table correlation names are supported m SQL_CN_NONE Correlation names are not supported m SQL_CN_DIFFERENT Correlation names are supported but they must differ from the names of the tables that they represent m SQL_CN_ANY Correlation names are supported and can be any valid user defined name SQL_CURSOR_COMMIT_BEHAVIOR A 16 bit integer value that indicates how a COMMIT operation affects cursors and prepared statements in the data source m SQL_CB_DELETE Close cursors and delete prepared state ments To use the cursor again the application must re prepare and re execute the hstmt m SQL_CB_CLOSE Close cursors For prepared statements the application can call SQLExecute on the hstmt without calling SOLPrepare again m SQL_CB_PRESERVE Preserve cursors in the same position as before the COMMIT operation The application can continue to fetch data or it can close the cursor and re execute the hstmt without re preparing it SQL_CURSOR_ROLLBACK_BEHAVIOR 12 196 INFORMIX CLI Programmers Manual A 16 bit integer value that indicates how a ROLLBACK operation affects cursors and prepared statements in the data source m SQL_CB_DELETE Close cursors and delete prepar
21. The identifier that is used to qualify the index name doing a DROP INDEX NULL is returned if an index qualifier is not supported by the data source or if TYPE is SQL_TABLE_STAT If a non null value is returned in this column it must be used to qualify the index name on a DROP INDEX statement otherwise the TABLE_LOWNER name should be used to qualify the index name INDEX_NAME VARCHAR 128 Index identifier NULL is returned if TYPE is SQL_TABLE_STAT TYPE SMALLINT not NULL Type of information being returned m SQL_TABLE_STAT indicates a statistic for the table m SQL_INDEX_CLUSTERED indicates a clustered index m SQL_INDEX_HASHED indicates a hashed index SQL_INDEX_OTHER indicates another type of index SEQ_IN_INDEX SMALLINT Column sequence number in index starting with 1 NULL is returned if TYPE is SQL_TABLE_STAT COLUMN_NAME INFORMIX CLI Programmer s Manual VARCHAR 128 Column identifier If the column is based on an expression such as SALARY BENEFITS the expression is returned if the expression cannot be determined an empty string is returned If the index is a filtered index each column in the filter condition is returned this might require more than one row NULL is returned if TYPE is SQL_TABLE_STAT 2 of 3 Informix SQL Column Name Data Type COLLATION CHAR 1 SQL Statistics Comments Sort sequence for the column A for ascending D
22. ad chars truncated outlen i colnum printf s printf n s errmsg else break INFORMIX CLI Programmers Manual collen il col d n collen i 1 collen i datali Finally fetch and print each row printing SWORD sizeof colname amp colnamelen amp coltype 4collen i amp scale Sl ET ay Af 7 Interactive Ad Hoc Query Example Free the data buffers for i 0 i lt nresultcols i free data i SQLFreeStmt hstmt SQL_DROP Free the statement handle a SQLDisconnect hdbc Disconnect from the data source SQLFreeConnect hdbc Free the connection handle y SQLFreeEnv henv Free the environment handle f return 0 xkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkxk The following function is included for completeness but is not relevant for understanding the function of ODBC xkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkxk itdefine MAX_NUM_PRECISION 15 Define max length of char string representation of number as E max precision leading sign E exp sign max exp length pe I5 1 ae ae a 2 ad fe a Tb 4 5 el iidefine MAX_NUM_STRING_SIZE MAX_NUM_PRECISION 5 UDWORD display_size coltype collen colname SWORD coltype UDWORD collen UCHAR colname switch coltype case SQL_CHAR case SQL_VARCHAR return max collen strlen coln
23. Parameters for a data type definition For example CREATE_PARAMS for DECIMAL would be precision scale CREATE_PARAMS for VARCHAR would equal max length null is returned if no parameters for the data type definition exist for example INTEGER The driver supplies the CREATE_PARAMS text in the language of the country where it is used Whether the data type accepts a null value m SQL_NO_NULLS if the data type does not accept null values m SQL_NULLABLE if the data type accepts null values m SOL_NULLABLE_UNKNOWN if it is not known if the column accepts null values Whether a character data type is case sensitive in collations and comparisons m TRUE if the data type is a character data type and is case sensitive m FALSE if the data type is not a character data type or is not case sensitive 2 of 4 Column Name SEARCHABLE UNSIGNED_ ATTRIBUTE MONEY Data Type SMALLINT not NULL SMALLINT SMALLINT not NULL SQL Get Typelnfo Comments How the data type is used in a WHERE clause m SQL_UNSEARCHABLE if the data type cannot be used in a WHERE clause m SOL_LIKE_ONLY if the data type can be used in a WHERE clause only with the LIKE predicate m SQL_ALL_EXCEPT_LIKE if the data type can be used in a WHERE clause with all comparison operators except LIKE m SQL_SEARCHABLE if the data type can be used in a WHERE clause with any comparison operator Whether the data type is uns
24. SQL Statement GET DESCRIPTOR Dynamic SQL OPEN PREPARE SET DESCRIPTOR SQL Statement COMMIT WORK INFORMIX CLI Function SOLNumkResultCols SQLDescribeCol SOLColAttributes SQLExecute SOLPrepare SOLBindParameter Transaction Control Statements INFORMIX CLI Function SQLTransact Comments COUNT FORM VALUE form with field name in NAME TYPE LENGTH PRECISION SCALE NULLABLE None None SQLBindParameter is associated with only one hstmt where a descriptor is applied to any number of statements with USING SQL DESCRIPTOR 2 of 2 The following table lists transaction control statements Comments None SQL_COMMIT option ROLLBACK WORK SQLTransact SQL_ROLLBACK option None Association Management Statements Association Management Statements The following table lists association management statements INFORMIX CLI Section SQL Statement Function Comments 5 5 1 CONNECT SOLConnect None 5 5 2 DISCONNECT SQLDisconnect INFORMIX CLI does not support DISCONNECT ALL 5 5 3 SET CONNECTION None The SOL Access Group SAG Call Level Interface allows multiple simultaneous connections to be established but only one connection can be active at one time SAG compliant drivers track which connection is active and automatically switch to a different connection if a different connection handle is specified However the active connection must be in a state that allows the
25. SQL_NEED_DATA An attribute keyword was specified in the browse request connection string szConnStrIn that does not apply to the current connection level function returns SQL_NEED_DATA The driver could not establish a connection with the data source DM The specified hdbc already established a connection with a data source and the connection is open 1 of 3 SQLSTATE Error 08004 08S01 28000 IM002 IM003 IM004 IM005 IM006 IM009 Data source rejected establishment of connection Communication link failure Invalid authorization specification Data source not found and no default driver specified Specified driver could not be loaded Driver SOLAllocEnv failed Driver SOLAllocConnect failed Driver SQLSetConnectOption failed Unable to load trans lation shared library SQLBrowseConnect Description The data source rejected the establishment of the connection for implementation defined reasons The communication link between the driver and the data source failed before the function completed Either the user identifier or the authorization string or both as specified in the browse request connection string szConnStrIn violated restrictions defined by the data source DM INFORMIX CLI cannot find the data source name specified in the browse request connection string szConnStrIn in the odbc ini file and a default driver specification does not exist
26. See SQL data types Data at execution canceling 12 51 macro 12 29 12 31 12 32 12 33 parameters 5 10 SQLBindParameter 12 29 12 31 12 32 12 33 Database locale 1 12 Databases current 12 285 information types 12 190 Date data CLI data types B 11 converting to C B 28 converting to SQL B 39 intervals 12 214 DATE data type B 2 DATETIME data type B 2 DATE_STRUCT typedef B 11 DBMS product information 12 190 DB_LOCALE 1 12 2 12 DDL See Data Definition Language DEC data type B 2 DECIMAL data type B 2 Declarative statements C 5 Delete rules 12 149 Index 3 DELETE statements affected rows 12 278 cascade delete 12 149 qualifier usage in 12 210 restrictive delete 12 149 Deletes positioned See Positioned delete statements Deleting cursors 12 196 Delimiter character SQL identifiers 12 209 Descriptors columns 12 56 12 89 Diagnostic statements C 10 Diagnostics 12 7 diagnostics 12 7 Dialog boxes disabling 12 287 SQLDriverConnect 12 99 12 101 Dirty reads 12 198 Display size 12 57 B 5 DML See Data Manipulation Language Documentation on line manuals Intro 9 printed manuals Intro 9 Documentation conventions icon Intro 6 typographical Intro 5 Documentation notes Intro 11 Documentation types of documentation notes Intro 11 error message files Intro 10 release notes Intro 11 DOUBLE PRECISION data type B 2 Driver keyword version compatibility 12 44 Driver manager 4 des
27. When you connect to this data source using either a dialog box or connection string the values that you entered appear as the new default entries for the UNIX Configuring Data Sources on UNIX Configuring Data Sources on UNIX Configuring a data source on UNIX involves the following files odbc ini The odbc ini initialization file provides configuration information about data sources Every data source to which your application connects must have an entry in this file The information in odbc ini describes the following items a The database to access o The server associated with the database Q The host on which the DBMS resides a The network protocol used to access that platform odbcinst ini The odbcinst ini file provides configuration information about ODBC drivers You need to modify this file only if you are using an ODBC driver manager from a third party vendor sqlhosts The sqlhosts file describes the following items The database server name The type of connection The name of the host computer O oO oO O The service name For more information about sqlhosts see the Administrator s Guide for your database server Configuring Data Sources 2 9 File Format for odbc ini 2 10 Section You can use a text editor to modify these files The following table explains where the files are located File Description odbc ini When you install INFORMIX CLI the installation script installs a s
28. and a binary 11111111 is converted to FE The driver always converts individual bytes to pairs of hexadecimal digits and terminates the character string with a null byte Because of this conversion if cb ValueMax is even and is less than the length of the converted data the last byte of the rgbValue buffer is not used The converted data requires an even number of bytes the next to last byte is a null byte and the last byte cannot be used Data Types B 27 Converting Data from SQL to C B 28 SQL to C Date The date INFORMIX CLI SQL data type is SOL_DATE The following table shows the INFORMIX CLI C data types to which date SQL data can be in the yyyy mm dd format INFORMIX CLI Programmers Manual converted fCType Test rgbValue pcbValue SQLSTATE SQL_C_CHAR cbValueMax gt 11 Data 10 N A cbValueMax lt 11 Untouched Untouched 22003 SQL_C_BINARY Length of data lt Data Length of N A cbValueMax data Length of data gt Untouched Untouched 22003 cbValueMax SQL_C_DATE None Data 6 N A SQL_C_TIMESTAMP None Data gt 16 N A The value of cbValueMax is ignored for this conversion The driver assumes that the size of rgbValue is the size of the C data type b The time fields of the time stamp structure are set to zero This is the size of the corresponding C data type When date SQL data is converted to character C data the resulting string is Converting Data from SQL to C
29. else int main long char UCHAR RETCODE HENV HDBC HSTMT char UCHAR 4 12 INFORMIX CLI Programmers Manual SQL_INVALID_ fprintf pfNativeError fprintf stdout amp pfNativeError break case 3 rc 4pfNativeError break if rc SQL_SUCCESS argc argv db 20 res 03 henv hdbc hstmt SQLError 1 i lt 3 amp amp rc SQL_NO_DATA_FOUND rc HANDLE i switch i case 1 re SQLError NULL NULL hstmt UCHAR amp pfNativeError UCHAR ErrMsg ErrMsgLen amp pcbErrorMsgLen break case 2 re SQLError NULL hdbc NULL UCHAR UCHAR ErrMsg ErrMsgLen amp pcbErrorMsgLen henv NULL NULL UCHAR ErrMsg ErrMsgLen amp pcbErrorMsgLen UCHAR NULL NULL NULL SqlState 6 ConnStrIin 250 J rc SQL_SUCCESS_WITH_INFO stdout ERROR 4d oS s r n SqlState ErrMsg ERROR Severe Error in ODBC Driver succeds defDbName UCHA UCHAR UCHAR UCHAR UCHAR short int R fprintf Alloca rc SQLA 150 Pe Le note fprintf goto Exi Alloca rc SQLA TFC re te lo note printErr goto Exi sprintf Co Establis rc SQLDriv if rc SQ printErr goto Exi Allocate rc SQLAI1o if rc SQ printErr goto Exi stdout locE Connection Strings ConnStrinp amp ConnStrIn 0 ConnStrO0ut 250 ConnStrOutp am
30. handle S1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SOL Error in the argument szErrorMsg describes the error and its cause 1001 Memory allocation The driver did not allocate memory required to failure support executing or completing the function S1008 Operation canceled The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multithreaded application 1 of 2 INFORMIX CLI Function Reference 12 69 SQLColumns 12 70 SQLSTATE Error S1010 Function sequence error S1090 Invalid string or buffer length S1C00 Driver not capable S1T00 Time out expired INFORMIX CLI Programmers Manual Description DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value of one of the name length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corresponding qualifier or name The maximum length of each qualifier or name can be obtained by calling SQLGetInfo with the fInfoType values For more information see Usage on page 12 187 A table qualifier was specified but the driver or data source does no
31. information or only prompt the user for information it needs Finally if a data source is specified the driver can read connection information from the appropriate section of the registry After the driver connects to the data source it returns the connection infor mation to the application The application can store this information for future use If the application specifies a data source name that was not configured INFORMIX CLI searches for the default data source specification If it finds the default data source it loads the default driver shared library and passes the application specified data source name to it If no default data source exists INFORMIX CLI returns an error When the application calls SQLDriverConnect and requests that the user be prompted for information INFORMIX CLI displays the INFORMIX CLI DSN Setup dialog box as Figure 4 1 illustrates INFORMIX CLI DSN Setup Figure 4 1 INFORMIX CLI DSN Change data source name description or options Setup Dialog Box Then Choose OK Note UID and PWD are Optional If specified PWD will be encrypted Database stores7 Server Service Protocol OK Cancel INFORMIX CLI Programmer s Manual Using SQLBrowseConnect Using SQLBrowseConnect SQLBrowseConnect supports an iterative method of listing and specifying the attributes and attribute values that are required to connect to a data source For each lev
32. is an expression or if the column is part of a view If the data source does not support qualifiers or the qualifier name cannot be determined an empty string is returned SQL_COLUMN_SCALE pfDesc The scale of the column on the data source For more information on scale see Precision Scale Length and Display Size on page B 5 SQL_COLUMN_SEARCHABLE pfDesc SQL_UNSEARCHABLE if the column cannot be used in a WHERE clause SQL_LIKE_ONLY if the column can be used in a WHERE clause only with the LIKE predicate SOL_ALL_EXCEPT_LIKE if the column can be used in a WHERE clause with all comparison operators except LIKE SOL_SEARCHABLE if the column can be used in a WHERE clause with any comparison operator Columns of type SQL_LONGVARCHAR and SQL_LONGVARBINARY usually return SQL_LIKE_ONLY SQL_COLUMN_TABLE_NAME rgbDesc The name of the table that contains the column The returned value is implementation defined if the column is an expression or if the column is part of a view If the table name cannot be determined an empty string is returned SQL_COLUMN_TYPE pfDesc The column s Informix SQL data type The possible values are any of the Informix SQL data types listed in Appendix B Data Types For more information about data types and conversions see Appendix B SQL_COLUMN_TYPE_NAME rgbDesc Data source dependent data type name for example CHAR VARCHAR MONEY LONG VARBINARY or CHAR FOR BIT DATA If the type i
33. object is a function that is it has a return value INFORMIX CLI Programmers Manual 2 of 2 The szProcOwner and szProcName arguments accept search patterns For more information about valid search patterns see Search Pattern Arguments on page 12 8 SQLProcedures Code Example In this example an application uses the procedure AddEmployee to insert data into the EMPLOYEE table The procedure contains input parameters for NAME AGE and BIRTHDAY columns It also contains one output parameter that returns a remark about the new employee The example also shows the use of a return value from a stored procedure For the return value and each parameter in the procedure the application calls SOLBindParameter to specify the ODBC C data type and the SOL data type of the parameter and to specify the storage location and length of the parameter The application assigns data values to the storage locations for each parameter and calls SQLExecDirect to execute the procedure If SQLExecDirect returns SQL_SUCCESS or SOL_SUCCESS_WITH_INFO the return value and the value of each output or input output parameter is automatically put into the storage location defined for the parameter in SOLBindParameter dtdefine NAME_LEN 30 itdefine REM_LEN 128 UCHAR szName NAME_LEN szRemark REM_LEN SWORD sAge sEmpld SDWORD cbEmpId cbName cbAge 0 cbBirthday 0 cbRemark DATE_STRUCT dsBirthday Define parameter for return value
34. or platform specific information Introduction 7 Screen Illustration Conventions Compliance Icons Compliance icons indicate paragraphs that provide guidelines for complying with a standard Icon Description Identifies that a function supports the Core ODBC API Core conformance level Identifies that a function supports the Level 1 ODBC API Level 1 conformance level Identifies that a function supports the Level 2 ODBC API conformance level Level 2 These icons can apply to a row in a table one or more paragraphs or an entire section A symbol indicates the end of the compliance information Screen llustration Conventions The illustrations in this manual represent a generic rendition of various windowing environments The details of dialog boxes controls and windows were deleted or redesigned to provide this generic look Therefore the illustrations in this manual depict the ODBC Administrator graphical interface a little differently than the way it appears on your screen 8 INFORMIX CLI Programmers Manual Additional Documentation Additional Documentation For additional information you might want to refer to the following types of documentation On line manuals Printed manuals On line help Error message files Documentation notes and release notes Related reading On Line Manuals An Answers OnLine CD that contains Informix manuals in electronic format is provided wit
35. rgb Value might point to a storage location that contains the data when the statement executes or to a file that contains the data The driver returns the value to the application when the statement executes When the driver processes a call to SOLExecute or SOLExecDirect and the executing statement includes a data at execution parameter the driver returns SQL_NEED_DATA INFORMIX CLI Programmers Manual Specifying Arrays of Parameter Values To send the parameter data an application performs the following operations 1 Calls SQLParamData which returns rgbValue as set with SQLBindParameter for the first data at execution parameter 2 Calls SOLPutData one or more times to send data for the parameter More than one call is needed if the data value is larger than the buffer multiple calls are allowed only if the C data type is character or binary and the SQL data type is character binary or data source specific 3 Calls SQLParamData again to indicate that all the data has been sent for the parameter If another data at execution parameter remains the driver returns rgbValue for that parameter and SQL_NEED_DATA for the function return code Otherwise it returns SOL_SUCCESS for the function return code 4 Repeats steps 2 and 3 for the remaining data at execution parameters For additional information see SOLBindParameter on page 12 25 Specifying Arrays of Parameter Values To specify multiple sets of parameter
36. value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning 01004 Data truncated 24000 Invalid cursor state S1000 General error S1001 Memory allocation failure S1002 Invalid column number INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer szColName was not large enough to return the entire column name so the column name was truncated The argument pcbColName contains the length of the untruncated column name function returns SQL_SUCCESS_WITH_INFO The statement associated with the hstmt did not return a result set There were no columns to describe An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support executing or completing the function DM The value specified for the argument icol was 0 The value specified for the argument icol was greater than the number of columns in the result
37. 00 0 1992 12 31 23 45 55 12 1992 12 31 23 45 55 1 SQLSTATE N A 01004 N A 01004 22003 N A 01004 22003 01004 22003 a 0 represents a null termination byte The null termination byte is required only if the length of the data is SQL_NTS P In addition to bytes for numbers one byte is required for a sign and another for the decimal point The numbers in this list are the numbers stored in the fields of the DATE_STRUCT structure 4 The numbers in this list the numbers stored in the fields of the TIMESTAMP_STRUCT structure E Data Types B 41 Comparison of INFORMIX CLI and Embedded SQL This appendix compares INFORMIX CLI and embedded SQL INFORMIX CLI to Embedded SQL The following table compares INFORMIX CLI functions core ODBC with embedded SQL statements This comparison is based on the X Open and SQL Access Group SQL CAE specifi cation 1992 INFORMIX CLI uses a parameter marker in place of a host variable where a host variable occurs in embedded SQL INFORMIX CLI to Embedded SQL The SQL language is based on the X Open and SQL Access Group SQL CAE specification 1992 Embedded SQL INFORMIX CLI Function Statement Comments SOLAllocEnv none Driver manager and driver memory allocation SOLAllocConnect none Driver manager and driver memory allocation SOLConnect CONNECT Association management SOLAllocStmt none Driver manager and driver memory allocation SQLPrepa
38. 12 33 Index 5 Length maximum connection options 12 166 12 284 data 12 301 error messages 12 108 indexes 12 204 qualifiers 12 204 rows 12 204 statement options 12 220 12 299 Length names columns 12 203 cursors 12 204 12 292 owners 12 204 procedures 12 204 users 12 205 Length unknown in length B 5 in precision B 5 SQLBindParameter 12 33 SQLExtendedFetch 12 128 SQLFetch 12 142 SQLGetData 12 174 Level 1 API 3 4 Level 2 API 3 4 Levels conformance See Conformance levels Library INFORMIX CLI 1 3 translation 1 12 Library handles driver 12 199 LIKE predicates 12 203 Limitations SQL statements 12 192 Literals character 12 203 prefix string 12 225 suffix string 12 225 Loading drivers 12 79 LOCAL TEMPORARY table type 12 329 Locale client 1 11 database 1 12 Lock levels 1 8 Login authorization 6 connection strings description 4 7 SQLBrowseConnect 4 8 12 43 12 101 INFORMIX CLI Programmer s Manual example 12 80 interval period 12 286 SQLSetConnectOption 12 286 See also Connections Long data values length required 12 205 retrieving 6 7 sending in parameters 5 10 SQLBindParameter 12 33 SQLGetData 12 175 LVARCHAR data type B 4 M Machine notes Intro 11 Macros data at execution 12 29 to 12 35 Manual commit mode beginning transactions 12 333 described 5 9 specifying 12 285 SQLTransact 12 333 See also Transactions Memory buffers 3 8 result sets 6 4 r
39. 308 INFORMIX CLI Programmer s Manual Column Name PRECISION LENGTH SCALE PSEUDO_COLUMN SQL SpecialColumns Informix SQL Data Type Comments INTEGER The precision of the column on the data source NULL is returned for data types where precision is not applicable For more information concerning precision see Precision Scale Length and Display Size on page B 5 INTEGER The length in bytes of data transferred on an SQLGetData or SQLFetch operation if SQL_C_DEFAULT is specified For numeric data this size might be different than the size of the data stored on the data source This value is the same as the PRECISION column for character or binary data For more information see Precision Scale Length and Display Size on page B 5 SMALLINT The scale of the column on the data source NULL is returned for data types where scale is not applicable For more information concerning scale see Precision Scale Length and Display Size on page B 5 SMALLINT Returns one of the following values to indicate whether the column is a pseudo column SOL_PC_UNKNOWN SOL_PC_PSEUDO SOL_PC_NOT_PSEUDO Important For maximum interoperability pseudo columns should not be quoted with the identifier quote character that SQLGetInfo returns 2 of 2 Once the application retrieves values for SQL_BEST_ROWID the application can use these values to reselect that row within the defined scope The SELECT statement is g
40. 4 SQLExecute SQLSTATE Error Description 1109 Invalid cursor The prepared statement was a positioned position UPDATE or DELETE statement and the cursor was positioned by SOLExtendedFetch on a row for which the value in the refRowStatus array in SOLExtendedFetch was SOL_ROW_DELETED or SOL_ROW_ERROR S1C00 Driver not capable The combination of the current settings of the SOL_CONCURRENCY and SOL_CURSOR_TYPE statement options was not supported by the driver or data source S1T00 Time out expired The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 40f4 SQLExecute can return any SOLSTATE that SOLPrepare can return based on when the data source evaluates the SOL statement associated with the hstmt Usage SQLExecute executes a statement prepared by SQLPrepare Once the application processes or discards the results from a call to SQLExecute the application can call SQLExecute again with new parameter values To execute a SELECT statement more than once the application must call SQLFreeStmt with the SOL_CLOSE parameter before it reissues the SELECT statement If the data source is in manual commit mode requiring explicit transaction initiation and a transaction has not already been initiated the driver initiates a transaction before it sends the SOL statement If an application uses SOLPrepare to prepare and SQLExecute to
41. 5 1 8 5 1 9 SQL Statement ALTER TABLE CREATE INDEX CREATE TABLE CREATE VIEW DROP INDEX DROP TABLE DROP VIEW GRANT REVOKE INFORMIX CLI Function Comments SQLPrepare None SQLExecute or SQLExecDirect Comparison of INFORMIX CLI and Embedded SQL C 5 Data Manipulation Statements C 6 Data Manipulation Statements The following table lists data manipulation statements Section SQL Statement 5 2 1 CLOSE 5 2 2 Positioned DELETE 5 2 3 Searched DELETE 5 2 4 FETCH 5 2 5 INSERT 5 2 6 OPEN 5 2 7 SELECT INTO 5 2 8 Positioned UPDATE 5 2 9 Searched UPDATE INFORMIX CLI Programmers Manual INFORMIX CLI Function SQLFreeStmt SQL_CLOSE option SQLExecDirect DELETE FROM table name WHERE CURRENT OF cursor name SQLExecDirect DELETE FROM table name WHERE search condition SQLFetch SQLExecDirect INSERT INTO table name none none SQLExecDirect UPDATE table name SET column identifier expression WHERE CURRENT OF cursor name SQLExecDirect UPDATE table name SET column identifier expression WHERE search condition Comments None Driver generated cursor name can be obtained by calling SQLGetCursorName None None Can also be invoked by SQLPrepare and SQLExecute When a SELECT statement is specified a cursor is opened implicitly by SQLExecute or SQLExecDirect Not supported Driv
42. CLI Function Reference 12 15 SQLAllocStmt SQLSTATE Diagnostics Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SQLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 08003 S1000 S1001 S1009 General warning Connection not open General error Memory allocation failure Invalid argument value 12 16 INFORMIX CLI Programmers Manual Informational message Function returns SQL_SUCCESS_WITH_INFO DM The connection that the hdbc argument specifies was not open The connection process must be completed successfully and the connection must be open for the driver to allocate an hstmt An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SOLError returns in the argument szErrorMsg describes the error and its cause DM The driver manager could not allocate memory for the statement handle The driver could not allocate me
43. CLI Programmer s Manual Description An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support executing or completing the function The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application DM SOLExecute or SOLExecDirect was called for the hstmt and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The hstmt was not prepared Either the hstmt was not in an executed state or a cursor was open on the hstmt and SQLFetch or SQLExtendedFetch had been called The hstmt was not prepared It was in an executed state and either no result set was associated with the hstmt or SOLFetch or SOLExtendedFetch had not been called A parameter value set with SOLBindParameter was a null pointer and the parameter length value was not 0 SOL_NULL_DATA SQL_DATA_AT_EXEC or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET A parameter value set with SOLBindParameter was not a null pointer and the parameter length value was less than 0 but was not SQL_NTS SQL_NULL_DATA or SQL_DATA_AT_EXEC or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET 3 of
44. Connection Server Only Connection Example Related Functions 4 3 4 4 4 11 4 15 4 2 INFORMIX CLI Programmer s Manual his chapter describes the different ways that an application can establish a connection to a data source Initializing the Environment Before an application can use any other function it must initialize the INFORMIX CLI API and associate an environment handle with the environment To initialize the API and allocate an environment handle 1 Declare a variable of type HENV For example you could use the following declaration HENV henvl 2 Call SOLAllocEnv and pass it the address of the variable The driver initializes the environment allocates memory to store information about the environment and returns the environment handle in the variable SQLAIlocEnv supports one or more connections to data sources however your application should perform these steps only once Connecting to a Data Source 4 3 Allocating a Connection Handle 4 4 Allocating a Connection Handle Before your INFORMIX CLI application can connect to the driver it must allocate a connection handle for the connection To allocate a connection handle 1 Declare a variable of type HDBC For example you could use the following declaration HDBC hdbcl 2 Call SQLAIlocConnect and pass it the address of the variable The driver allocates memory to store information about the connection and returns the
45. Cursors Retrieving data Rowsets Rowsets allocating 6 8 binding 6 7 binding type 12 299 errors in 12 131 retrieving 6 9 size 12 302 SQLExtendedFetch 12 126 status 12 134 S SAG CLI compliance 12 207 Scalar functions data conversion 12 195 information types 12 193 TIMESTAMPADD intervals 12 214 TIMESTAMPDIFF intervals 12 214 Scale columns procedures 12 261 result sets 12 87 tables 12 72 12 309 defined B 5 SCHAR typedef B 11 Scope row ID 12 310 Scrollable cursors 6 10 SDOUBLE typedef B 10 SDWORD typedef B 10 Searching columns 12 58 data types 12 227 patterns 12 8 Segment boundaries 3 8 SELECT FOR UPDATE statements 12 209 Select list maximum columns in 12 204 ORDER BY columns in 12 207 SELECT statements affected rows 12 278 cursor name 12 166 12 292 maximum tables in 12 205 multiple result sets 6 12 12 232 privileges 12 66 qualifier usage in 12 210 re executing 12 121 UNION clauses 12 216 See also Result sets Sensitivity cursor 12 213 Separator qualifier 12 209 SERIAL data type B 3 SERIAL8 data type B 4 Serializing isolation levels 12 198 transactions 6 11 Server name 12 212 Server only connection 4 10 setup odbc 1 10 SFLOAT typedef B 10 Signed columns 12 59 Signed data types 12 227 Simulated cursors 12 307 Size display 12 57 B 5 SMALLFLOAT data type B 3 SMALLINT data type B 3 Software dependencies Intro 4 Sorting 12 206 12 317 Special characters in search patterns 12 8 in SQL identifie
46. DM INFORMIX CLI cannot find the odbc ini file DM The driver listed in the data source speci fication in the odbc ini file specified by the DRIVER keyword was not found or could not be loaded for some other reason DM During SOLBrowseConnect the driver manager called the driver SOLAllocEnv function and the driver returned an error DM During SOLBrowseConnect the driver manager called the driver SOLAllocConnect function and the driver returned an error DM During SOLBrowseConnect the driver manager called the driver SQLSetConnectOption function and the driver returned an error The driver did not load the translation shared library that was specified for the data source or for the connection 2 of 3 INFORMIX CLI Function Reference 12 41 SQL BrowseConnect SQLSTATE Error IM010 Data source name too long IM011 Driver name too long IM012 DRIVER keyword syntax error S1000 General error S1001 Memory allocation failure S1090 Invalid string or buffer length S1T00 Time out expired INFORMIX CLI Programmers Manual Description DM The attribute value for the DSN keyword was longer than SOL_MAX_DSN_LENGTH Characters DM The attribute value for the DRIVER keyword was longer than 255 characters DM The keyword value pair for the DRIVER keyword contained a syntax error An error occurred for which no specific SOLSTATE existed and for which no implementation specific SOLSTATE was defi
47. Data 16 N A value fractional seconds portion not truncated gt Data value is a valid timestamp Truncated data 16 N A value fractional seconds portion truncated gt Data value is a valid date value Data 8 16 lt N A Data value is a valid time value Data 16 N A Data value is not a valid date Untouched Untouched 22008 value time value or timestamp value P The value of cb ValueMax is ignored for this conversion The driver assumes that the size of rgbValue is the size of the C data type This is the size of the corresponding C data type The date portion of timestamp value is ignored f The fractional seconds portion of the time stamp is truncated e The time fields of the time stamp structure are set to zero The date fields of the time stamp structure are set to the current date leading and trailing spaces are ignored B 22 INFORMIX CLI Programmer s Manual 2 of 2 When character SQL data is converted to numeric date or time stamp C data Converting Data from SQL to C Additional SQL to C Character Data Conversion for Universal Server The following table shows the additional INFORMIX CLI C data type for Universal Server to which character SQL data can be converted fCType Test rgbValue pcbValue SQLSTATE SOL_C_BIT Datais 0 or 1 Data 1 N A Data is greater than 0 less Truncated data 1 01004 than 2 and not equal to 1 Data is less than 0 or greater Untouched Untouched 22003 tha
48. Diagnostics SQLRowCount When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning 1000 General error S1001 Memory allocation failure S1010 Function sequence error Usage INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM The function was called prior to calling SQLExecute or SQLExecDirect for the hstmt DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns If the last executed statement as
49. Employee ID from procedure SQLBindParameter hstmt 1 SQL_PARAM_OUTPUT SQL_C_SLONG SQL_INTEGER 0 0 amp sEmpId 0 amp cbEmpId Define data types and storage locations for Name Age Birthday input parameter data AY SQLBindParameter hstmt 2 SQL_PARAM_INPUT SQL_C_CHAR SQL_CHAR NAME_LEN 0 szName 0 amp cbName SQLBindParameter hstmt 3 SQL_PARAM_INPUT SQL _C_SSHORT SQL _SMALLINT 0 0 amp sAge 0 amp cbAge SQLBindParameter hstmt 4 SQL_PARAM_INPUT SQL_C_DATE SQL_DATE 0 0 amp dsBirthday 0 amp cbBirthday Define data types and storage location for Remark output parameter SQLBindParameter hstmt 5 SQL_PARAM_OUTPUT SQL_C_CHAR SQL_CHAR REM_LEN 0 szRemark REM_LEN amp cbRemark strcpy szName Smith John D Specify first row of sAge 40 parameter data dsBirthday year 1952 dsBirthday month 2 dsBirthday day 29 cbName SQL_NTS Execute procedure with first row of data After the procedure INFORMIX CLI Function Reference 12 269 SQL Procedures is executed sEmpId and szRemark will have the values yf returned by AddEmployee retcode SQLExecDirect hstmt call AddEmployee SQL_NTS strcpy szName Jones Bob K Specify second row of sAge 52 parameter data EJ dsBirthday year 1940 dsBirthday month 3 dsBirthday day 31 Execute procedure with second row of d
50. INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause DM The driver manager could not allocate memory for the connection handle The driver could not allocate memory for the connection handle DM The argument phdbc was a null pointer SQLAI locConnect Usage A connection handle references information such as the valid statement handles on the connection and whether a transaction is currently open To request a connection handle an application passes the address of an hdbc to SOLAllocComnect The driver allocates memory for the connection infor mation and stores the value of the associated handle in the hdbc On operating systems that support multiple threads applications can use the same hdbc on different threads The application passes the hdbc value in all subsequent calls that require an hdbc If your INFORMIX CLI architecture includes a driver manager the driver manager processes the SOLAllocConnect function and calls the driver SQLAIlocConnect function when the application calls SQLConnect SOLBrowseConnect or SQLDriverConnect For more information see Usage on page 12 79 If the application calls SOLAllocConnect with a pointer to a v
51. N A AS Number of whole as opposed to fractional 01004 digits lt Column length Number of whole as opposed to fractional 22003 digits gt Column length SQL_DECIMAL Data converted without truncation N A SOL_INTEGER AN ALLINT Data converted with truncation of fractional 01004 E digits Conversion of data would result in loss of 22003 whole as opposed to fractional digits SOL_DOUBLE Data is within the range of the data type to N A SQL_REAL which the number is being converted Data is outside the range of the datatype to 22003 which the number is being converted Data Types B 35 Converting Data from C to SQL B 36 rgbValue is the size of the numeric C data type Universal Server to which numeric C data can be converted Additional C to SQL Numeric Data Conversion for Universal Server The value pointed to by the pcbValue argument of SQLBindParameter and the value of the cbValue argument of SQLPutData are ignored when data is converted from the numeric C data types The driver assumes that the size of The following table shows the additional INFORMIX CLI SQL data types for Data is less than 0 or greater than or equal to 2 INFORMIX CLI Programmers Manual fSqlType Test SQLSTATE SQL_BIGINT Data converted without truncation N A Data converted with truncation of fractional digits 01004 Conversion of data would result in loss of whole as 22003 opposed to fractional digits SQL_BIT
52. Output cbValueMax Input SDWORD SDWORD FAR pcbValue Input Output Return Codes SOL_INVALID_HANDLE INFORMIX CLI Programmer s Manual Description The scale of the column or expression of the corresponding parameter marker For further information concerning scale see Precision Scale Length and Display Size on page B 5 A pointer to a buffer for the data of the parameter For more information see rgbValue Argument on page 12 31 Maximum length of the rgb Value buffer For more information see cbValueMax Argument on page 12 31 A pointer to a buffer for the length of the parameter For more information see pcbValue Argument on page 12 32 2 of 2 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_ERROR or Diagnostics SQLBindParameter When SOLBindParameter returns SOL_SUCCESS_WITH_INFO or SOL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SOLSTATE values commonly returned by SQLBindParameter and explains each value in the context of this function the notation DM precedes the description of each SQLSTATE returned by the driver manager The return code associated with each SOLSTATE value is SOL_ERROR unless noted otherwise SQLSTATE Error 01000 07006 S1000 1001 1003 1004 S1009 S1010 General warning Restricted data type attribute violation General error Memory allocation failure Program ty
53. SOLMoreResults eee 12 232 SOLNAativeSql c oe ose os os bar o tubae e e 127233 SQLNumParams a a aaa eee 12 238 SQLNumResultCols a aa eee 12 24 SQLParamData a 0 12 244 SQLPrepare 2 e 2 ww ee eee eee 12 248 SQLPrimaryKeys 2 ee ee ee 12 255 SQLProcedureColumns 12 259 SQLProcedures ee ee eee ee 12 266 SOLPutData c e se moroene a we oe ee a 12 273 SQLRowCount eee ee eee 12 280 SQLSetConnectOption 2 2 2 2 we 12 283 SOLSetCursorName ee 12 292 SQLSetScrollOptions 2 2 ee 12 297 SQLSetStmtOption 2 2 2 ee ew ee 12 298 SQLSpecialColumns 2 2 1 ee 12 306 SQLStatistics 2 2 ee 12 313 SQLTablePrivileges 2 2 we 0 ee ee 12 321 SQLTabless se eo cur a a ay e a ee k aa a e 12327 SQLTransact E a ae e a o e a a eee 12 333 12 2 INFORMIX CLI Programmers Manual his chapter describes each INFORMIX CLI function The functions are listed alphabetically Each function is defined as a programming language function The function descriptions include the following aspects Conformance level Purpose Syntax Return codes Diagnostics Usage Code example optional Related functions Error handling is described under the SQLError function description The text associated with SQLSTATE values is included to provid
54. SOL_SUCCESS_WITH_INFO SOL_NO_DATA_ FOUND SOL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 83 SQLDataSources 12 84 Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning 01004 Data truncated 1000 General error S1001 Memory allocation failure INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO DM The buffer szDSN was not large enough to return the entire data source name so the name was truncated The argument pcbDSN contains the length of the entire data source name function returns SQL_SUCCESS_WITH_INFO DM The buffer szDescription was not large enough to return the entire driver description so the description was truncated The argument pcbDescription contains the length of the untruncated data source description function returns SQL_SUCCESS_WITH_INF
55. SQL GetStmtOption Related Functions For Information About See Returning the setting of a connection option SQLGetConnectOption Setting a connection option SQLSetConnectOption Setting a statement option SOLSetStmtOption INFORMIX CLI Function Reference 12 221 SQL GetTypelnfo SQLGetTypelnfo SQLGetTypelnfo returns information about data types that the data source supports The driver returns the information in the form of an SQL result set Important Applications must use the type names returned in the TYPE_NAME column in ALTER TABLE and CREATE TABLE statements they must not use the sample type names listed in Appendix C Comparison of INFORMIX CLI and Embedded SQL SQLGetTypelnfo might return more than one row with the same value in the DATA_TYPE column Syntax RETCODE SQLGetTypelnfo hstmt fSqlType The SOLGetTypelnfo function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle for the result set SWORD fSqlType Input The parameters INFORMIX CLISOL data type The possible values are any of the fSqlType values listed in Appendix B Data Types as well as SOL_ALL_TYPES which specifies that information about all data types should be returned For more information about data types and conversions see Appendix B Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE 12 222 INFORMIX CLI Programme
56. SQLProcedureColumns SQLProcedures SQLPutData SQLSetConnectOption SOLSetStmtOption SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLPutData SQLExtendedFetch SOLFetch SQLGetData 3 of 13 SQL STATE Error 22003 22005 22008 22012 22026 23000 Numeric value out of range Error in assignment DATETIME field overflow Division by zero String data length mismatch Integrity constraint violation SQLSTATE Values Can be returned from SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SOLGetData SOLGetInfo SQLPutData SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SOLGetData SQLPrepare SQLPutData SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SOLGetData SQLPutData SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SOLGetData SQLParamData SQLExecDirect SQLExecute 4 of 13 INFORMIX CLI Error Codes A 5 SQLSTATE Values 24000 25000 28000 34000 37000 3C000 A 6 INFORMIX CLI Programmers Manual SQL STATE Error Invalid cursor state Invalid transaction state Invalid authorization specification Invalid cursor name Syntax error or access violation Duplicate cursor name Can be returned from SQLColAttributes SQLColumnPrivileges SOLColumns SQLDescribeCol SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SQLForeignKeys SOLGetData SOLGetStmtOption SOLGetTy
57. SQL_CONVERT_DOUBLE SQL_CONVERT_FLOAT SQL_CONVERT_INTEGER SQL_CONVERT_LONGVARBINARY SQL_CONVERT_LONGVARCHAR SQL_CONVERT_NUMERIC SQL_CONVERT_REAL SQL_CONVERT_SMALLINT SQL_CONVERT_TIME SQL_CONVERT_TIMESTAMP SQL_CONVERT_TINYINT SQL_CONVERT_VARBINARY SQL_CONVERT_VARCHAR SQLGetInfo Returns A 32 bit bitmask The bitmask indicates the conversions supported by the data source with the CONVERT scalar function for data of the type named in the fInfoType If the bitmask equals 0 the data source does not support any conversions for data of the named type including conversion to the same data type For example to find out if a data source supports the conversion of SQL_INTEGER data to the SQL_BIGINT data type an appli cation calls SQLGetInfo with the fInfoType of SQL_CONVERT_INTEGER The application ANDs the returned bitmask with SQL_CVT_BIGINT If the resulting value is not 0 the conversion is supported The following bitmasks are used to determine which conver sions are supported SQL_CVT_BIGINT SQL_CVT_BINARY SQL_CVT_BIT SQL_CVT_CHAR SQL_CVT_DATE SQL_CVT_DECIMAL SQL_CVT_DOUBLE SQL_CVT_FLOAT SQL_CVT_INTEGER SQL_CVT_LONGVARBINARY SQL_CVT_LONGVARCHAR SQL_CVT_NUMERIC SQL_CVT_REAL SQL_CVT_SMALLINT SQL_CVT_TIME SQL_CVT_TIMESTAMP SQL_CVT_TINYINT SQL_CVT_VARBINARY SQL_CVT_VARCHAR SQL_CONVERT_FUNCTIONS A 32 bit bitmask that enumerates the scalar conversion functions that the driver and associated data source support
58. The driver returns the row set row rows from the start of the current row set If irow equals 0 the driver refreshes the current row set If the cursor is positioned before the start of the result set and irow is greater than 0 or if the cursor is positioned after the end of the result set and row is less than 0 this is equivalent to SQL_FETCH_ABSOLUTE It supports the following values of the fFetchType argument to move the cursor to an absolute position in the result set fFetchType Argument SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_ABSOLUTE Action The driver returns the first row set in the result set The driver returns the last complete row set in the result set If irow is greater than 0 the driver returns the row set starting at row irow If irow equals 0 the driver returns SQL_NO_DATA_FOUND and the cursor is positioned before the start of the result set If irow is less than 0 the driver returns the row set starting at row n irow 1 where n is the number of rows in the result set For example if irow is 1 the driver returns the row set that starts at the last row in the result set If the result set size is 10 and irow is 10 the driver returns the row set that starts at the first row in the result set INFORMIX CLI Function Reference 12 133 SQLExtendedFetch 12 134 row Argument For the SOL_FETCH_ABSOLUTE fetch type SQLExtendedFetch returns the row set that starts at the row number specif
59. Unfortunately the application might not call SQLGetData again thus the first and only retrieval of CaseHistory is slowed because 64 kilobytes of data has to be sent across the network In this example only one row is returned The performance impact is signif icant when for example 100 rows are returned in the result set This example further illustrates how you can limit the size of the data retrieved with the SQL_MAX_LENGTH option of SOLSetStmtOption to improve performance 10 8 INFORMIX CLI Programmers Manual Using SQLBindCol to Reduce the Call Load Using SQLBindCol to Reduce the Call Load Another way to improve performance is to retrieve data through bound columns To reduce the ODBC call load use SOLBindCol instead of SQLGetData The following pseudocode fragments and analysis illustrate the performance difference that can result from using SOLBindCol Case 1 SQLGetData Method This example uses SQLGetData rc SQLExecDirect hstmt SELECT lt 20 columns gt FROM Employees WHERE HireDate gt SQL_NTS do rc SQLFetch hstmt call SQLGetData 20 times while rc SQL_SUCCESS rc SQL_SUCCESS_WITH_INFO Case 2 SQLBindCol Method This example uses SQLBindCol rc SQLExecDirect hstmt SELECT lt 20 columns gt FROM Employees WHERE HireDate gt SQL_NTS call SQLBindCol 20 times do rc SQLFetch hstmt while re SQL_SUCCESS rc SQL_S
60. a 32 bit integer value The format is noted in the option description This format applies to the infor mation returned for each option in SOLGetStmtOption Character strings pointed to by the vParam argument of SOLSetStmtOption have a maximum length of SOL_MAX_OPTION_STRING_LENGTH bytes excluding the null termination byte vParam Contents A 32 bit integer value that sets the binding orientation to be used when SQLExtendedFetch is called on the associated hstmt Column wise binding is selected by supplying the defined constant SQL_BIND_BY_COLUMN for the argument vParam Row wise binding is selected by supplying a value for vParam specifying the length of a structure or an instance of a buffer into which result columns will be bound The length specified in vParam must include space for all of the bound columns and any padding of the structure or buffer to ensure that when the address of a bound column is incremented with the specified length the result will point to the beginning of the same column in the next row When using the sizeof operator with structures or unions in ANSI C this behavior is guaranteed Column wise binding is the default binding orientation for SOLExtendedFetch 1 of 4 INFORMIX CLI Function Reference 12 299 SQL SetStmtOption fOption SQL_CONCURRENCY vParam Contents A 32 bit integer value that specifies the cursor concurrency m SQL_CONCUR_READ_ONLY Cursor is read only No updates are allowed
61. a binary 00000001 and FF is converted to a binary 11111111 The driver always converts pairs of hexadecimal digits to individual bytes and ignores the null termination byte Because of this conversion if the length of the character string is odd the last byte of the string excluding the null termination byte if any is not converted Additional C to SQL Character Data Conversion for Universal Server The following table shows the additional INFORMIX CLI SQL data types for Universal Server to which character C data can be converted fSqlType Test SQLSTATE SQL_BIGINT Data converted without truncation N A Data converted with truncation of fractional digits 01004 Conversion of data would result in loss of whole as 22003 opposed to fractional digits Data value is not a numeric literal 22005 SQL_BIT Data is 0 or 1 N A Data is greater than 0 less than 2 and not equal to 1 01004 Data is less than 0 or greater than or equal to 2 22003 Data is not a numeric literal 22005 INFORMIX CLI Programmers Manual Converting Data from C to SQL C to SQL Numeric The numeric INFORMIX CLI C data types are SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_SHORT SQL_C_SLONG SQL_C_SSHORT SQL_C_STINYINT SQL_C_TINYINT SQL_C_ULONG SQL_C_USHORT SQL_C_UTINYINT The following table shows the INFORMIX CLI SQL data types to which numeric C data can be converted fSqlType Test SQLSTATE SQL_CHAR Number of digits lt Column length
62. a data at execution parameter it returns SQL_NEED_DATA The application sends the data using SQLParamData and SOLPutData For more information see SOLBindParameter SOLParamData and SOLPutData Code Example See SOLBindCol SOLExtendedFetch SOLProcedures and SOLGetData Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Executing a prepared SQL statement Fetching a block of data or scrolling through a result set Fetching a row of data Returning a cursor name Fetching part or all of a column of data Returning the next parameter to send data for Preparing a statement for execution Sending parameter data at execution time Setting a cursor name Setting a statement option Executing a commit or rollback operation INFORMIX CLI Programmer s Manual See SQLBindCol SQLCancel SQLExecute SQLExtendedFetch SOLFetch SOLGetCursorName SQLGetData SQLParamData SQOLPrepare SQLPutData SOLSetCursorName SOLSetStmtOption SQLTransact SQLExecute 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 The SQLExecute statement accepts the following argument Type Argument Use Description HSTMT hstmt Input Statement handle Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NEED_DATA SOL_STILL_EXE
63. an SQLSTATE description indicates that the driver manager returns the SQLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 01004 01S01 07006 08S01 22002 12 124 General warning Data truncated Error in row Restricted data type attribute violation Communication link failure Indicator value required but not supplied INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The data returned for one or more columns was truncated String values are right truncated For numeric values the fractional part of number was truncated function returns SQL_SUCCESS_WITH_INFO An error occurred while fetching one or more rows function returns SQL_SUCCESS_WITH_INFO A data value could not be converted to the C data type specified by fCType in SQLBindCol The communication link between the driver and the data source failed before the function completed If the column value for any bound column is null the INDICATOR_PTR field of the corresponding descriptor record must not be a null pointer 1 of 3 INFORMIX CLI Programmer s Manual SQLSTATE Error 22003 22005 22008 22012 24000 40001 S1000 S1001 S1002 S1008 Numeric value out of range Error in assignment Datetime field overflow Division by zero Invalid cursor state Serialization failure General error Memory allocation failure Invalid column numbe
64. and error handling protocol The return codes indicate whether a function succeeded succeeded but returned a warning or failed The error handling protocol defines how the components in an INFORMIX CLI connection construct and return error messages through SOLError The protocol describes the following points m Use of the error text to identify the source of an error m Rules to ensure consistent and useful error information m Responsibility for setting the SQLSTATE based on the native error Function Return Codes When an INFORMIX CLI application calls a function the driver executes the function and returns a predefined code These return codes indicate success warning or failure status The following table defines the return codes Return Code Description SQL_SUCCESS Function completed successfully no additional infor mation is available SQL_SUCCESS_WITH_INFO Function completed successfully possibly with a nonfatal error The application can call SQLError to retrieve additional information SQL_NO_DATA_FOUND All rows from the result set have been fetched but no data was found SQL_ERROR Function failed The application can call SQLError to retrieve error information 1 of 2 Retrieving Status and Error Information 7 3 Error Messages 7 4 Return Code SQL_INVALID_HANDLE SQL_STILL _EXECUTING SQL_NEED_DATA return code Error Messages INFORMIX CLI Programmers Manual Description Fun
65. another Executing SQL Statements 5 7 Setting Parameter Values 5 8 To set a parameter value an application performs the following operations 1 Calls SOLBindParameter to bind a storage location to a parameter marker It also uses SQLBindParameter to specify a the data types of the storage location and the column associated with the parameter Q precision and scale for the parameter 2 Places the value of the parameter in the storage location The application can perform these steps before or after a statement is prepared but it must perform them before a statement executes Parameter values must be placed in storage locations in the C data types specified in SOLBindParameter as the following table shows Parameter Value SQL Data Type C Data Type Stored Value ABC SQL_CHAR SQL_C_CHAR ABONO 10 SQL_INTEGER SQL_C_SLONG 10 10 SQL_INTEGER SQL_C_CHAR 10 0 1PM SQL_TIME SQL_C_TIME 13 0 0 gt 1PM SQL_TIME SQL_C_CHAR t 13 00 00 0 2 The MO value represents a null termination byte the null termination byte is required only if the parameter length is SQL_NTS b The numbers in this list are the numbers stored in the fields of the TIME_STRUCT structure The string uses the ODBC date escape clause Storage locations remain bound to parameter markers until the application calls SQLFreeStmt with the SOL_RESET_PARAMS option or the SOL_DROP option An application can bind a different storage area to a param
66. are batched or are submitted with arrays of parameters they can return multiple result sets or counts To process a batch of statements a statement with arrays of parameters or a procedure that returns multiple result sets or row counts an application performs the following operations 1 Calls SOLExecute or SQLExecDirect to execute the statement or procedure 2 Calls SQLRowCount to determine the number of rows affected by an UPDATE INSERT or DELETE statement For statements or procedures that return result sets the application calls functions to determine the characteristics of the result set and retrieve data from the result set 3 Calls SOLMoreResults to determine whether another result set or row count is available 4 Repeats steps 2 and 3 until SQLMoreResults returns SOL_NO_DATA_FOUND Retrieving Results 6 13 Retrieving Status and Error Information Function Return Codes a 2 ee een 7 3 Error Messages o ald a fo ce Ge al oe ae a eS Gh 7 4 Error Text Format o 7 5 Sample Error Messages 2 1 1 we ee ee es 7 6 Sample Error Returned from the Driver 0 7 6 Sample Error Returned from the Driver Manager 7 6 Sample Error Returned from the DataSource 7 7 Processing Error Messages 7 1 we eee es 7 7 Retrieving Error Messages 1 1 eee ee e 7 8 7 2 INFORMIX CLI Programmer s Manual his chapter defines INFORMIX CLI return codes
67. buffer can be a null pointer In such cases the driver does not return anything in the buffer and in the absence of other errors returns SOL_SUCCESS If necessary the driver converts data before returning it The driver always null terminates character data before returning it The length of the buffer The driver ignores this value if the returned data has a fixed length in C as with an integer real number or date structure The address of a variable in which the driver returns the length of the data the length buffer The returned length of the data is SOL_NULL_DATA if the data is a NULL value in a result set Otherwise the returned length of the data is the number of bytes of data that are available to return If the driver converts the data the returned length of the data is the number of bytes that remain after the conversion for character data it does not include the null termination byte that the driver added If the output buffer is too small the driver attempts to truncate the data If the truncation does not cause a loss of significant data the driver returns the truncated data in the output buffer returns the length of the available data as opposed to the length of the truncated data in the length buffer and returns SQL_SUCCESS_WITH_INFO If the truncation causes a loss of signif icant data the driver leaves the output and length buffers untouched and returns SQL_ERROR The application calls SOLError to retrieve
68. cbCursorMax 1 bytes Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_ HANDLE INFORMIX CLI Function Reference 12 167 SQL GetCursorName Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 01004 S1000 S1001 S1010 S1015 S1090 12 168 General warning Data truncated General error Memory allocation failure Function sequence error No cursor name available Invalid string or buffer length INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer szCursor was not large enough to return the entire cursor name so the cursor name was truncated The argument pcbCursor contains the length of the untruncated cursor name function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implemen
69. connection context to be switched in other words a transaction must not be in progress on the current connection Drivers that are not SAG compliant are not required to support this behavior That is drivers that are not SAG compliant are not required to return an error if the driver and its associated data source can simultaneously support multiple active connections Comparison of INFORMIX CLI and Embedded SAL C 9 Diagnostic Statement Diagnostic Statement The following table lists the GET DIAGNOSTIC statement INFORM 1X CLI Section SQL Statement Function Comments 5 6 1 GET DIAGNOSTICS SQLError For SQLError the following fields SQLRowCount from the diagnostics area are available RETURNED_SQLSTATE MESSAGE_TEXT and MESSAGE_LENGTH For SQLRowCount the ROW_COUNT field is available C 10 INFORMIX CLI Programmers Manual Index A Access mode 12 102 Access plans 5 6 ALIAS table type 12 329 Aliases column 12 194 Allocating handles See Connection handles See Environment handles See Statement handles ALTER TABLE statements interoperability 5 4 modifying syntax 5 3 qualifier usage in 12 210 supported clauses 12 194 Architecture 1 3 Arguments naming conventions 12 4 null pointers 3 9 pointers 3 8 search patterns 12 8 See also Parameters Arrays See Binding columns column wise See Parameters arrays Association management C 9 Attributes columns 12 56 12 89 Auto c
70. connection handle in the variable Connecting to a Data Source After the application allocates a connection handle it must specify a data source name or the appropriate connection information INFORMIX CLI provides functions that let you use different methods for connecting to a data source Using SQLConnect Your INFORMIX CLI application passes the following information to the driver in a call to SOLConnect m The data source name is the name of the data source that the appli cation is requesting m The user ID is the login ID or account name for access to the data source This value is optional if it was specified in the configuration information Otherwise this value is required m The password is a character string associated with the user ID that lets the user access the data source This value is optional if it was specified in the configuration information Otherwise this value is required INFORMIX CLI Programmers Manual Using SQLDriverConnect If the application specifies a data source name that was not configured or if the application does not specify a data source name INFORMIX CLI searches for the default data source specification If it finds the default data source INFORMIX CLI loads the default driver shared library and passes the appli cation specified data source name to that library If INFORMIX CLI cannot find a default data source it returns an error Using SQLDriverConnect Your application can
71. data SQL data length 22003 a The SQL data length is the number of bytes needed to store the data on the data source This may be different than the column length as defined in Precision Scale Length and Display Size on page B 5 us Additional C to SQL Binary Data Conversion for Universal Server B 38 The following table shows the additional INFORMIX CLI SQL data types for Universal Server to which binary C data can be converted fSqlType Test SQLSTATE SQL_BIGINT Length of data SQL data length N A Length of data SQL data length 22003 SQL_BIT Length of data SQL data length N A Length of data SOL data length 22003 4 INFORMIX CLI Programmers Manual Converting Data from C to SQL C to SQL Date The date INFORMIX CLI C data type is SQL_C_DATE The following table shows the INFORMIX CLI SQL data types to which date C data can be converted fSqlType Test SQLSTATE SQL_CHAR Column length gt 10 N A L_L VARCHAR AREA ey Column length lt 10 22003 Data value is not a valid date 22008 SQL_DATE Data value is a valid date N A Data value is not a valid date 22008 SQL_TIMESTAMP Data value is a valid date N A Data value is not a valid date 22008 a The time portion of the time stamp is set to zero For information about what values are valid in a SOL_C_DATE structure see Date and Time Stamp C Data Types on page B 11 When date C data is converted
72. defined did not exist The argument szSqlStr contained a CREATE INDEX statement but the specified table name did not exist The argument szSqlStr contained a GRANT or REVOKE statement but the specified table name or view name did not exist The argument szSqlStr contained a SELECT statement but a specified table name or view name did not exist The argument szSq Str contained a DELETE INSERT or UPDATE statement but the specified table name did not exist The argument szSq Str contained a CREATE TABLE statement and a table specified in a constraint referencing a table other than the one being created did not exist 2 of 4 SQLSTATE S0011 S0012 S0021 S0022 S1000 S1001 S1008 S1009 Error Index already exists Index not found Column already exists Column not found General error Memory allocation failure Operation canceled Invalid argument value SQLPrepare Description The argument szSqlStr contained a CREATE INDEX statement but the specified index name already existed The argument szSq Str contained a DROP INDEX statement but the specified index name did not exist The argument szSq Str contained an ALTER TABLE statement and the column specified in the ADD clause is not unique or identifies an existing column in the base table The argument szSqlStr contained a CREATE INDEX statement and one or more of the column names specified in the column list di
73. dialog box It constructs a connection string from the data source name returned by the dialog box and any other keywords passed to it by the appli cation If the data source name returned by the dialog box is empty the driver manager specifies the keyword value pair DSN Default m SQL_DRIVER_COMPLETE or SQL_DRIVER_COMPLETE_REQUIRED If the connection string specified by the application includes the DSN keyword the driver manager copies the connection string specified by the application Otherwise it takes the same actions as it does when fDriverCompletion is SQL_DRIVER_PROMPT m SQL_DRIVER_NOPROMPT The driver manager copies the connection string specified by the application INFORMIX CLI Function Reference 12 99 SQL DriverConnect 12 100 If the connection string specified by the application contains the DRIVER keyword the driver manager copies the connection string specified by the application Using the connection string that it constructed the driver manager deter mines which driver to use loads that driver and passes the connection string that it has constructed to the driver For more information about the inter action of the driver manager and the driver see Usage on page 12 79 If the connection string contains the DSN keyword or does not contain either the DSN or the DRIVER keyword the driver manager determines which driver to use as the following steps show 1 If the connection string contains the DS
74. different function the error messages from the previous function are deleted Additional error or status information can come from one of the following sources m Error or status information from an ODBC function indicating that a programming error was detected m Error or status information from the data source indicating that an error occurred during SQL statement processing The information that SQLError returns is in the same format as that provided by SQLSTATE in the X Open and SQL Access Group SQL CAE specification 1992 SOLError never returns error information about itself INFORMIX CLI Programmers Manual Terminating Transactions and Connections Terminating Statement Processing 8 3 Terminating Transactions 2 2 ee ee ee e 8 4 Terminating Connections 2 2 2 ee ee 8 4 8 2 INFORMIX CLI Programmer s Manual he INFORMIX CLI interface provides functions to terminate state ments transactions and connections as well as to free statement hstmt connection hdbc and environment henv handles Terminating Statement Processing To free the resources associated with a statement handle an application calls SQLFreeStmt The SQLFreeStmt function has the following options m SQL_CLOSE This option closes the cursor if one exists and discards pending results The application can use the statement handle again later m SQL_DROP This option closes the cursor if one exist
75. does not include the null termination byte m Column length and display size are defined for each SQL data type in Precision Scale Length and Display Size on page B 5 m Number of digits is the number of characters that represent a number including the minus sign decimal point and exponent if needed m Words in italics represent elements of the INFORMIX CLI SOL syntax INFORMIX CLI Programmers Manual converted fSqlType Test SQLSTATE SQL_CHAR Length of data lt Column length N A L_L VARCHAR a a Length of data gt Column length 01004 SQL_DECIMAL Data converted without truncation N A L_INTEGER ATEN Data converted with truncation of fractional 01004 7 digits Conversion of data would result in loss of 22003 whole as opposed to fractional digits Data value is not a numeric literal 22005 SQL_DOUBLE Data is within the range of the data type to N A SQL_REAL which the number is being converted Data is outside the range of the data type to 22003 which the number is being converted Data value is not a numeric literal 22005 1 of 2 Converting Data from C to SQL fSqlType Test SOLSTATE SQL_LONGVARBINARY Length of data 2 lt Column length N A Length of data 2 gt Column length 01004 Data value is not a hexadecimal value 22005 SQL_DATE Data value is a valid INFORMIX CLI date N A literal N A Data value is a valid INFORMIX CLI timestamp literal time portion is zero 01004 Data valu
76. driver supports owners for some procedures but not for others as when the driver retrieves data from different DBMSs an empty string denotes those procedures that do not have owners SWORD cbProcOwner Input Length of szProcOwner UCHAR FAR szProcName Input String search pattern for procedure names SWORD cbProcName Input Length of szProcName 12 264 INFORMIX CLI Programmers Manual SQLProcedures Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source failed before the function completed 24000 Invalid cursor state A cursor was already opened on the statement handle S10
77. error occurs in the driver level SOLAllocEnv function the driver manager level SOLConnect SOLBrowseConnect or SOLDriverConnect function returns SOL_ERROR A subsequent call to SOLError with henv SOL_NULL_HDBC and SQL_NULL_HSTMT returns SOLSTATE IM004 the driver SOLAllocEnv function failed followed by one of the following errors from the driver SQLSTATE S1000 General error An INFORMIX CLI SQLSTATE value which ranges from S1000 to S19ZZ For example SOLSTATE S1001 Memory allocation failure indicates that the call from the driver manager to the driver level SOLAllocEnv returned SOL_ERROR and the henv from the driver manager was set to SQL_NULL_HENV For additional information about the flow of function calls between the driver manager and a driver see Usage on page 12 79 Usage An environment handle references global information such as valid connection handles and active connection handles To request an environment handle an application passes the address of an henv to SOLAllocEnv The driver allocates memory for the environment information and stores the value of the associated handle in the henv On operating systems that support multiple threads applications can use the same hdbc on different threads The application passes the henv value in all subsequent calls that require an henv INFORMIX CLI Function Reference 12 13 SQLAllocEnv 12 14 for all applications Code Example Related Functions More
78. following list identifies valid values for fFunction for ODBC extension Level 1 functions that the INFORMIX CLI driver supports SOL_API_ SOLBINDPARAMETER SOL_API_ SOLCOLUMNS SOL_API SOLDRIVERCONNECT 12 180 INFORMIX CLI Programmer s Manual SQLGetFunctions SOL_API_SOLGETCONNECTOPTION SOL_API_ SOLGETDATA SOL_API_ SOLGETFUNCTIONS SOL_API_SOLGETINFO SQL_API_SQLGETSTMTOPTION SOL_API_SOLGETTYPEINFO SOL_API_SOLPARAMDATA SOL_API SOLPUTDATA SOL_API_SOLSETCONNECTOPTION SOL_API_SOLSETSTMTOPTION SOL_API_SOLSPECIALCOLUMNS SOL_API_SOLSTATISTICS SQL_API_SOLTABLES The following list identifies valid values for fFunction for ODBC extension Level 2 functions that the INFORMIX CLI driver supports m SQL_API_SOQLBROWSECONNECT SQL_API_SQLCOLUMNPRIVILEGES SOL_API_SOLDATASOURCES SOL_API SOLDESCRIBEPARAM SOL_API_SOLDRIVERS SOL_API_SOLEXTENDEDFETCH SOL_API_SOLFOREIGNKEYS SOL_API_ SOLMORERESULTS SOL_API_SOLNATIVESQL SOL_API SOLNUMPARAMS SOL_API SOLPRIMARYKEYS SQL_API_SQLPROCEDURECOLUMNS SQL_API_SQLPROCEDURES SOL_API_SOLSETSCROLLOPTIONS SOL_API_SOLTABLEPRIVILEGES INFORMIX CLI Function Reference 12 181 SQL GetFunctions Code Example The following examples show how an application uses SQLGetFunctions to determine whether a driver supports SQLTables SQLColumns and SQL Statistics If the driver does not support these functions the application disconnects from the driver The first example calls SOLGetFunctions once for each function
79. for bytes available to return NULL 0 All qualifiers NULL 0 All owners EMPLOYEE SQL_NTS EMPLOYEE table NULL 0 All columns ey if retcode SQL_SUCCESS Bind columns in result set to storage locations BindCol hstmt 1 SQL_C_CHAR szQualifier STR_LEN amp cbQualifier BindCol hstmt 2 SQL_C_CHAR szOwner STR_LEN amp cbOwner BindCol hstmt 3 SQL_C_CHAR szTableName STR_LEN amp cbTableName BindCol hstmt 4 SQL_C_CHAR szColName STR_LEN amp cbColName BindCol hstmt 5 SQL_C_SSHORT amp DataType 0 amp cbDataType BindCol hstmt 6 SQL_C_CHAR szTypeName STR_LEN amp cbTypeName BindCol hstmt 7 SQL_C_SLONG amp Precision 0 amp cbPrecision BindCol hstmt 8 SQL_C_SLONG amp Length 0 amp cbLength BindCol hstmt 9 SQL_C_SSHORT amp Scale 0 amp cbScale BindCol hstmt 10 SQL_C_SSHORT amp Radix 0 amp cbRadix BindCol hstmt 11 SQL_C_SSHORT amp Nullable 0 amp cbNullable SQ INFORMIX CLI Programmers Manual SQLColumns SQLBindCol hstmt 12 SQL_C_CHAR szRemarks REM_LEN amp cbRemarks while TRUE retcode SQLFetch hstmt if retcode SQL_ERROR retcode SQL_SUCCESS_WITH_INFO show_error if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO Process fetched data else break Related Functions For Information About See Assigning storage fo
80. handle of the application The driver uses this handle to display dialog boxes This is the default If the application has not specified a parent window handle for this option the driver uses a null parent window handle to display dialog boxes or return in SQLGetConnectOption The SQL_QUIET_MODE connection option does not apply to dialog boxes that SQLDriverConnect displays A 32 bit flag value that is passed to the translation shared library This option can only be specified if the driver has connected to the data source 3 of 4 INFORMIX CLI Function Reference 12 287 SQL SetConnectOption fOption SQL_TXN_ISOLATION vParam Contents A 32 bit mask that sets the transaction isolation level for the current hdbc An application must call SQLTransact to commit or roll back all open transac tions on an hdbc before calling SQLSetConnectOption with this option The valid values for vParam can be determined by calling SOLGetInfo with finfotype equal to SQL_TXN_ISOLATION_OPTIONS The following terms are used to define transaction isolation levels m Dirty Read Transaction 1 changes a row Transaction 2 reads the changed row before transaction 1 commits this change Transaction 1 rolls back the change and transaction 2 reads a row that is considered to have never existed m Nonrepeatable Read Transaction 1 reads a row Transaction 2 updates or deletes that row and commits this change Transaction 1 attempts to reread the row and
81. henv is ignored and the driver manager calls SOLTransact in the driver for the hdbc If hdbc is SOL_NULL_HDBC and henv is SOL_NULL_HENV SOLTransact returns SOL_INVALID_HANDLE If fType is SOL_COMMIT SOLTransact issues a COMMIT request for all active operations on any hstmt associated with an affected hdbc If fType is SOL_ROLLBACK SQLTransact issues a ROLLBACK request for all active operations on any hstmt associated with an affected hdbc If no transac tions are active SOLTransact returns SOL_SUCCESS with no effect on any data sources If the driver is in manual commit mode by calling SQLSetConnectOption with the SOL_AUTOCOMMIT option set to zero a new transaction is started implicitly when an SQL statement that can be contained within a transaction is executed against the current data source To determine how transaction operations affect cursors an application calls SQLGetInfo with the SQL_CURSOR_ROLLBACK_BEHAVIOR and SQL_CURSOR_COMMIT_BEHAVIOR options INFORMIX CLI Function Reference 12 333 SQL Transact If the value of SOL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR equals SOL_CB_DELETE SOLTransact closes and deletes all open cursors on all statement handles that are associated with the hdbc and discards all pending results SQLTransact leaves any hstmt present in an allocated unprepared state the application can reuse them for subsequent SQL requests or can call SOLFreeStmt to deallocate them If th
82. in SOLBindCol and the SQL data type of the corresponding column This error applies only when the SQL data type of the column was mapped to a driver specific SQL data type The argument fFetchType was SQL_FETCH_RESUME and the driver supports ODBC 2 0 Time out expired The time out period expired before the data source returned the result set The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT 3 of 3 Usage SQLExtendedFetch returns one row set of data to the application An appli cation cannot mix calls to SQLExtendedFetch and SQLFetch for the same cursor An application specifies the number of rows in the row set by calling SQLSetStmtOption with the SOL_ROWSET_SIZE statement option INFORMIX CLI Programmers Manual SQLExtendedFetch Binding If any columns in the result set are bound with SOLBindCol the driver converts the data for the bound columns as necessary and stores it in the locations bound to those columns The result set can be bound in a column wise the default or row wise fashion Column Wise Binding To bind a result set in column wise fashion an application specifies SQL_BIND_BY_COLUMN for the SQL_BIND_TYPE statement option To bind each column 1 The application allocates an array of data storage buffers The array has as many elements as the row set has rows plus an additional element if the application searches for key values or appends new rows of data The size of e
83. information about the truncation or the error For more information about output buffers see Converting Data from SQL to C on page B 19 3 10 INFORMIX CLI Programmers Manual Environment Connection and Statement Handles Environment Connection and Statement Handles When an application requests them to the driver and the driver manager allocate storage for information about the environment each connection and each SQL statement The handles to these storage areas are returned to the application which uses one or more handles in each call to a function The INFORMIX CLI API uses the following types of handles Environment handles identify memory storage for global information including the valid connection handles and the current active connection handle The environment handle is an HENV variable type An application uses one environment handle It must request this handle before it connects to a data source Connection handles identify memory storage for information about particular connections A connection handle is an HDBC variable type An application must request a connection handle before it connects to a data source Each connection handle is associated with the environment handle However the environment handle can be associated with multiple connection handles Statement handles identify memory storage for information about SQL statements A statement handle is an HSTMT variable type An appli cation mus
84. internal binary format B 16 INFORMIX CLI Programmers Manual Converting Data The following table shows the supported conversions between the Informix SQL data types and the additional INFORMIX CLI C data type for Universal Server A solid circle e indicates a supported conversion INFORMIX CLI C Data Type fCType E im Q e Informix SQL Data Type F BYTE CHAR CHARACTER o CHARACTER VARYING o DATE DATETIME DEC DECIMAL o DOUBLE PRECISION 0 FLOAT 0 INT INTEGERS MONEY 0 NUMERIC O REAL 0 SERIAL 0 SMALLFLOAT SMALLINT o TEXT o VARCHAR 0 4 Data Types B 17 Default C Data Types GLS Additional Conversions for GLS and Universal Server The following table shows the supported conversions between the additional Informix SQL data types for GLS and the additional INFORMIX CLI C data type for Universal Server A solid circle e indicates a supported conversion INFORMIX CLI C Data Type fCType E A i Informix SQL Data Type eS NCHAR e NVARCHAR O 4 Default C Data Types If an application specifies SQL_C_DEFAULT for the fCType argument in SOLBindCol SOLGetData or SOLBindParameter the driver assumes that the C data type of the output or input buffer corresponds to the SQL data type of the column or parameter to which the buffer is bound For each INFORMIX CLI SQL data type the following table shows the default C data type INFORMIX CLI SOL Data Type fSqlType Default INFORMIX C
85. it converts the data from the specified C data type For more information about data types see Appendix B The C data types are defined in the sql h and sqlext h header files Function Return Codes When an INFORMIX CLI application calls a function the driver executes the function and returns a predefined code The following return codes indicate success warning or failure status SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_ERROR SQL_INVALID_HANDLE SQL_STILL_EXECUTING SQL_NEED_DATA When the function returns SOL_SUCCESS_WITH_INFO or SOL_ERROR the application can call SQLError to retrieve additional information about the error For a complete description of return codes and error handling see Chapter 7 Retrieving Status and Error Information 3 12 INFORMIX CLI Programmers Manual How an Application Uses the INFORMIX CLI API How an Application Uses the INFORMIX CLI API An application uses the INFORMIX CLI API to make a connection to a data source issue SQL statements to a data source process result data dynami cally and terminate a connection 1 Connect to the data source While connecting specify the data source name and any additional information needed to complete the connection Process one or more SQL statements a Place the SQL text string in a buffer If the statement includes parameter markers set the parameter values If the statement returns a result set either
86. list of supplementary manuals Introduction 3 Software Deoendencies 4 Software Dependencies This manual assumes that you are using INFORMIX CLLI Version 2 8 on either a Windows NT Windows 95 or UNIX platform In addition you must use one of the following Informix database servers INFORMIX OnLine Dynamic Server Version 7 2x INFORMIX OnLine Workgroup Server Version 7 2x INFORMIX OnLine XPS Version 8 1x INFORMIX SE Version 7 2x INFORMIX Universal Server Version 9 1x Demonstration Database The DB Access utility which is provided with your Informix database server products includes a script to build a demonstration database called stores7 that contains information about a fictitious wholesale sporting goods distributor Sample command files are also included Some database server software allows you to build other demonstration databases as well Many examples in Informix manuals are based on the stores7 demonstration database For more information about installing stores7 see the DB Access User Manual for your database server INFORMIX CLI Programmers Manual Documentation Conventions Documentation Conventions This section describes the following conventions m Typographical conventions m Icon conventions m Screen illustration conventions Typographical Conventions This manual uses the following standard set of conventions to introduce new terms illustrate screen displays describe command sy
87. name INFORMIX CLI Function Reference 12 89 SQL DescribeCol 12 90 Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Returning information about a column in a result set Fetching a row of data Returning the number of result set columns Preparing a statement for execution INFORMIX CLI Programmers Manual See SOLBindCol SOLCancel SQLColAttributes SQLFetch SQLNumResultCols SQLPrepare SQLDisconnect SQLDisconnect SQLDisconnect closes the connection associated with a specific connection handle Syntax RETCODE SQLDisconnect hdbc The SQLDisconnect function accepts the following argument Type Argument Use Description HDBC hdbc Input Connection handle Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 91 SQL Disconnect Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE va
88. not be null Adding a Data Source If a data source name is passed to ConfigDSN in lpszAttributes ConfigDSN checks that the name is valid If the data source name matches an existing data source name and hwndParent is null ConfigDSN overwrites the existing name If it matches an existing name and hwndParent is not null ConfigDSN prompts the user to overwrite the existing name If IpszAttributes contains enough information to connect to a data source ConfigDSN can add the data source or display a dialog box with which the user can change the connection information If pszAttributes does not contain enough information to connect to a data source ConfigDSN must determine the necessary information if hwndParent is not null it displays a dialog box to retrieve the information from the user If ConfigDSN displays a dialog box it must display any connection infor mation passed to it in lpszAttributes In particular if a data source name was passed to it ConfigDSN displays that name but does not allow the user to change it ConfigDSN can supply default values for connection information not passed to it in IpszAttributes If ConfigDSN cannot get complete connection information for a data source it returns FALSE If ConfigDSN can get complete connection information for a data source it calls SQLWriteDSNToIni in the installer shared library to add the new data source specification SQLWriteDSNToIni adds the data source name to the ODBC D
89. now dayofmonth month year m String functions concat LTRIM length RTRIM System function sysusername Procedure calls m Data types See Appendix B see the Informix Guide to SQL Syntax flags INFORMIX CLI Programmer s Manual INFORMIX CLI supports the following extended SQL grammar atan exp power tan For more information about the numeric date string and system functions Verifying INFORMIX CLI Conformance Levels To verify the API conformance level call SOLGetInfo with the SQL_ODBC_SAG_CLI_CONFORMANCE and SQOL_ODBC_API CONFORMANCE To verify the SQL conformance level call SOLGetInfo with the SOL_ODBC_SQL_CONFORMANCE flag To verify SOL conformance for a specific SQL extension call SOLGetInfo with a flag for that extension To verify SOL conformance for a specific SOL data type call SOLGetTypeInfo Using the Driver Manager Using the Driver Manager A driver manager is a shared library that provides an interface between an INFORMIX CLI application and the INFORMIX CLI driver It also checks parameters and transitions The following table describes the driver manager requirements and options for each platform Environment Driver Manager UNIX On UNIX a driver manager is optional You may purchase a UNIX driver manager from a third party vendor Windows In Windows environments INFORMIX CLI provides the driver manager which is mandatory The driver manager file is odbc32 dll
90. number of bytes that are available to return in the pcbValue buffer that is bound to the column This is the number of bytes available before calling SQLExtendedFetch If the number of bytes available to return cannot be determined in advance the driver sets pcbValue to SOL_NO_TOTAL If the data for the column is NULL the driver sets pcb Value to SOL_NULL_DATA It stores the number of bytes available to return for the first row at the start of the buffer and the number of bytes available to return for each subsequent row at an offset of sizeof SDWORD from the value for the previous row Row Wise Binding To bind a result set in row wise fashion an application must specify the SQL_BIND_TYPE statement option for SQLSetStmtOption To bind a result set in row wise fashion 1 The application declares a structure that can hold a single row of retrieved data and the associated data lengths For each bound column the structure contains one field for the data and one SDWORD field for the number of bytes that are available to return The size of the data field is the maximum size of the C data that can be returned for the column 2 The application calls SQLSetStmtOption with fOption set to SOL_BIND_TYPE and vParam set to the size of the structure 3 The application allocates an array of these structures The array has as many elements as the row set has rows plus an additional element if the application searches for key values or appends n
91. of an array for each bound column m It scrolls through the result set according to the setting of a scroll type argument SQLExtendedFetch works with SQLSetStmtOption To fetch one row of data at a time in a forward direction an application should call SQLFetch For more information about scrolling through result sets see Using Block and Scrollable Cursors on page 6 9 Syntax RETCODE SQLExtendedFetch hstmt fFetchType irow pcrow rgfRowStatus The SQLExtendedFetch function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UWORD fFetchType Input Type of fetch SDWORD irow Input Number of the row to fetch UDWORDFAR pcrow Output Number of rows actually fetched UWORD FAR refRowStatus Output An array of status values INFORMIX CLI Function Reference 12 123 SQL ExtendedFetch SQLSTATE Error Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NO_DATA_ FOUND SOL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of
92. of data N A Length of data gt cbValueMax Untouched Untouched 22003 gt The value of cbValueMax is ignored for this conversion The driver assumes that the size of rgbValue is the size of the C data type This is the size of the corresponding C data type B 24 INFORMIX CLI Programmers Manual Converting Data from SQL to C Additional SQL to C Numeric Data Conversion for Universal Server The additional numeric INFORMIX CLI SQL data type is SOL_BIGINT The previous table shows the INFORMIX CLI C data types to which SQL_BIGINT data can be converted The following table shows the additional INFORMIX CLI C data type for Universal Server to which character SQL data can be converted fCType Test rgbValue pcbValue SQLSTATE SQL_C BIT Datais0 or 1 Data 1 N A Data is greater than 0 less Truncated data 1 01004 than 2 and not equal to 1 Data is less than 0 or greater Untouched Untouched 22003 than or equal to 2 Data is not a numeric literal Untouched Untouched 22005 This is the size of the corresponding C data type Data Types B 25 Converting Data from SQL to C ws SQL to C Bit The bit INFORMIX CLI SQL data type is SQL_BIT Only Universal Server supports SQL_BIT The following table shows the INFORMIX CLI C data types to which bit SQL data can be converted fCType Test rgbValue pcbValue SQLSTATE5 SQL_C_CHAR cbValueMax gt 1 Data 1 N A cbValueMax lt 1 Untouched Untouched 22003 S
93. of the driver determined by the driver manager statement handle which must be passed on input in rgbInfoValue from the application In this case rgbInfoValue is both an input and an output argument The input hstmt passed in rgbInfoValue was probably an hstmt allocated on the argument hdbc SOL_DRIVER_NAME A character string with the filename of the driver used to access the data source SOL_DRIVER_ODBC_VER A character string with the version of ODBC that the driver supports The version has the form where the first two digits are the major version and the next two digits are the minor version SOL_SPEC_MAJOR and SOL_SPEC_MINOR define the major and minor version numbers For the version of ODBC described in this manual these are 2 and 0 and the driver should return 02 00 If a driver supports SOLGetInfo but does not support this value of the fInfoType argument the driver manager if you are using one returns 01 00 SOL_DRIVER_VER A character string with the version of the driver and optionally a description of the driver At a minimum the version has the form H H where the first two digits are the major version the next two digits are the minor version and the last four digits are the release version SOL_EXPRESSIONS_IN_ORDERBY A character string m Y if the data source supports expressions in the ORDER BY list m N if it does not 7 of 24 INFORMIX CLI Function Re
94. on page 5 7 3 Retrieves information about the result set if necessary For more information see Determining the Characteristics of a Result Set on page 6 5 4 Calls SOLExecute to execute the statement 5 Repeats steps 2 through 4 as necessary INFORMIX CLI Programmers Manual Direct Execution Direct Execution Execute a statement directly if both of the following conditions are true m The application executes the statement only once m The application does not need information about the result set prior to execution To execute an SQL statement directly an application performs the following operations 1 Sets the values of any statement parameters For more information see Setting Parameter Values 2 Calls SQLExecDirect to execute the statement Setting Parameter Values An SQL statement can use parameter markers to contain values that the driver retrieves from the application at execution time For example an application might use the following statement to insert a row of data into the EMPLOYEE table INSERT INTO EMPLOYEE NAME AGE HIREDATE VALUES An application uses parameter markers instead of literal values when one of the following conditions occurs m t needs to execute the same prepared statement several times with different parameter values m The parameter values are unknown when the statement is prepared m The parameter values need to be converted from one data type to
95. options S1T00 Time out expired The time out period expired before the data source returned the requested result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 Usage SQLProcedures lists all procedures in the requested range A user might or might not have permission to execute any of these procedures To check accessibility an application can call SOLGetInfo and check the SQL_ACCESSIBLE_PROCEDURES information value Otherwise the appli cation must be able to handle a situation in which the user selects a procedure that it cannot execute Important SQLProcedures might not return all procedures Applications can use any valid procedure regardless of whether SQLProcedures returns it SQLProcedures returns the results as a standard result set ordered by PROCEDURE_QUALIFIER PROCEDURE_OWNER and PROCEDURE_NAME The following table lists the columns in the result set 12 266 INFORMIX CLI Programmer s Manual SQLProcedures The lengths of VARCHAR columns shown in the table are maximums the actual lengths depend on the data source To determine the actual lengths of the PROCEDURE_QUALIFIER PROCEDURE_OWNER and PROCEDURE_NAME columns an application can call SOLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME LEN and SQL_MAX_PROCEDURE_NAME_LEN options Column Name PROCEDURE_QUALIFIER PROCEDURE_OWNER PROCEDURE_NAME NUM_INPUT_PARAMS NUM_OUTPUT_PARAMS Data Typ
96. or until the hstmt is used in a call to SOLPrepare SOLExecDirect or one of the catalog functions SQLColumns SOLTables and so on Once the application prepares a statement it can request information about the format of the result set Some drivers cannot return syntax errors or access violations when the appli cation calls SOLPrepare A driver might handle syntax errors and access violations only syntax errors or neither syntax errors nor access violations Therefore an application must be able to handle these conditions when it calls subsequent related functions such as SQLNumResultCols SOLDescribeCol SOLColAttributes and SOLExecute Depending on the capabilities of the driver and data source and on whether the application has called SOLBindParameter parameter information such as data types might be checked when the statement is prepared or when it is executed For maximum interoperability an application should unbind all parameters that applied to an old SOL statement before it prepares a new SOL statement on the same hstmt This action prevents errors that are caused by old parameter information being applied to the new statement Warning Committing or rolling back a transaction either by calling SQLTransact or by using the SQL_AUTOCOMMIT connection option can cause the data source to delete the access plans for all statement handles on a connection handle For more information see SQL CURSOR_COMMIT_BEHAVIOR and SQ
97. predicate escape character m N otherwise SQL_MAX_BINARY_LITERAL_LEN A 32 bit integer value that specifies the maximum length number of hexadecimal characters excluding the literal prefix and suffix returned by SQLGetTypeInfo of a binary literal in an SQL statement For example the binary literal OXFFAA has a length of 4 If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_CHAR_LITERAL_LEN A 32 bit integer value that specifies the maximum length number of characters excluding the literal prefix and suffix returned by SQLGetTypelInfo of a character literal in an SQL statement If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_COLUMN_NAME_LEN A 16 bit integer value that specifies the maximum length of a column name in the data source If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_COLUMNS_IN_GROUP_BY A 16 bit integer value that specifies the maximum number of columns allowed in a GROUP BY clause If no limit is specified or the limit is unknown this value is set to 0 SQL_MAX_COLUMNS_IN_INDEX A 16 bit integer value that specifies the maximum number of columns allowed in an index If no limit is specified or the limit is unknown this value is set to 0 SQL_MAX_COLUMNS_IN_ORDER_BY A 16 bit integer value that specifies the maximum number of columns allowed in an ORDER BY clause I
98. procedure is to use the default value of a parameter rather than a value retrieved from the application This value is valid only in a procedure call and then only if the fParamType argument is SQL_PARAM_INPUT or SQL_PARAM_INPUT_OUTPUT When pcb Value is SOL_DEFAULT_PARAM the corre sponding parameter can only be a parameter for an ODBC canonical procedure invocation When pcb Value is SOL_DEFAULT_PARAM the fCType fSqlType cbColDef ibScale coValueMax and rgbValue arguments are ignored for input parameters and are used only to define the output parameter value for input output parameters This value was introduced in ODBC 2 0 The data for the parameter is sent with SOLPutData If the fSq Type argument is SOL_LONGVARBINARY SQL_LONGVARCHAR or some other long Informix SQL data type and the driver returns Y for the SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo length is the number of bytes of data to be sent for the parameter Otherwise length must be a nonnegative value and is ignored For more infor mation see Passing Parameter Values on page 12 33 For example to send 10 000 bytes of data with SQLPutData for an SQL_LONGVARCHAR parameter an application sets pcbValue to SQL_LEN_DATA_AT_EXEC 10000 This macro was introduced in ODBC 2 0 SQLBindParameter If pcbValue is a null pointer the driver assumes that all input parameter values are non null and that character and binary data are null terminate
99. see Precision Scale Length and Display Size on page B 5 The maximum scale of the data type on the data source Null is returned where scale is not applicable If the maximum scale is not defined separately on the data source but is instead defined to be the same as the maximum precision this column contains the same value as the PRECISION column For more information see Precision Scale Length and Display Size on page B 5 4 0f 4 SQL Get Typelnfo Attribute information can apply to data types or to specific columns in a result set SOLGetTypeInfo returns information about attributes associated with data types SOLColAttributes returns information about attributes associated with columns in a result set Related Functions For Information About See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SOLCancel Returning information about a column in a result set SOLColAttributes Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SOLFetch Returning information about a driver or data source SOLGetInfo INFORMIX CLI Function Reference 12 229 SQL MoreResults SQLM oreResults SOLMoreResults determines whether more results are available on an hstmt that contains SELECT UPDATE INSERT or DELETE statements and if so initializes processing for those results Syntax RETCODE SQLMoreResults hstmt The SQL
100. solid circle e indicates a supported conversion INFORMIX CLI C Data Type fCType jan E E 5 ELE EVE 6 unm BREUESSES26Zz s gt A 20 06T4ESs0m5 m s On CLA KR EB BAB E R 9 A A E A 9 a D a z H gt a gt i Q 9 9 Q 9 9 Q 9 9 Q Q 9 9 A A A oA Be de oe AAAA AAAA Informix SQL Data Type ot en ee P R RIR ARAP oe BYTE o 0 CHAR CHARACTER CHARACTER VARYING 060 0 0 0 0 0 DATE o e DATETIME o O DEC DECIMAL o e DOUBLE PRECISION o e 4 0 e FLOAT e 0 04 INT INTEGER o e 0 0 MONEY e NUMERIC o e 0 REAL e 0 1 of 2 B 14 INFORMIX CLI Programmer s Manual GLS Converting Data INFORMIX CLI C Data Type fCType S E E lt E E Z gt 5 5 48 9 S Ez E EUR E Z m 2ep8B 38 249285622 2n02 lt O0O3602 SRE ZAZA RE A 9 A A E ma Se 9 9 n E A gt gt gt 9 i 9 9 9 9 9 9 9 9 S Sl 9 S Q Soe A oA eB de HB oe HB oe eB on Hn on ot Informix SQL Data Type Ro Oe ee eh aR Oe ae F P ee g SERIAL ee o o o o o o e o o o SMALLFLOAT o o o o o o o o e o o o SMALLINT o o o o o o o o o e o o o TEXT o o o o o o o o o VARCHAR o o o o o o o o o o o 2 of 2 Additional Conversions for GLS The following table shows the su
101. statement that read the rows it receives a different set of rows If the data source supports transactions the driver returns one of the following bitmasks m SQL_TXN_READ_UNCOMMITTED Dirty Reads Non repeatable Reads and Phantoms are possible m SQL_TXN_READ_COMMITTED Dirty Reads are not possible Non repeatable Reads and Phantoms are possible m SQL_TXN_REPEATABLE_READ Dirty Reads and Non repeatable Reads are not possible Phantoms are possible m SQL_TXN_SERIALIZABLE Transactions can be serialized Dirty Reads Non repeatable Reads and Phantoms are not possible m SQL_TXN_VERSIONING Transactions can be serialized but higher concurrency is possible than with SQL_TXN_SERIALIZABLE Dirty Reads are not possible Typically SQL_TXN_SERIALIZABLE is implemented by using locking protocols that reduce concurrency and SQL_TXN_VERSIONING is implemented by using a non locking protocol such as record versioning SQL_DRIVER_HDBC A 32 bit value the environment handle or connection handle of SQL_DRIVER_HENV the driver determined by the argument hdbc 6 of 24 12 198 INFORMIX CLI Programmer s Manual InfoType SQL_DRIVER_HLIB SQLGetInfo Returns A 32 bit value the library handle returned to INFORMIX CLI when it loaded the driver shared library The handle is only valid for the connection handle HDBC specified in the call to SOLGetInfo SOL_DRIVER_HSTMT A 32 bit value the statement handle
102. string for those tables that do not have qualifiers Table owner identifier NULL if not appli cable to the data source If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have owners Table identifier Identifier of the user who granted the privilege NULL if not applicable to the data source Identifier of the user to whom the privilege was granted 1 of 2 Column Name PRIVILEGE IS_GRANTABLE Informix SQL Data Type VARCHAR 128 not NULL VARCHAR 3 SQLTablePrivileges Comments Identifies the table privilege Can be one of the following or a data source specific privilege m SELECT The grantee is permitted to retrieve data for one or more columns of the table m INSERT The grantee is permitted to insert new rows containing data for one or more columns into to the table m UPDATE The grantee is permitted to update the data in one or more columns of the table m DELETE The grantee is permitted to delete rows of data from the table m REFERENCES The grantee is permitted to refer to one or more columns of the table within a constraint for example a unique referential or table check constraint The scope of action permitted the grantee by a given table privilege is data source dependent For example the UPDATE privilege might permit the
103. string or SOLDriverConnect dialog box Returning driver descriptions and attributes SOLDrivers INFORMIX CLI Function Reference 12 85 SQL DescribeCol SQLDescribeCol SQLDescribeCol returns the result descriptor column name type precision scale and whether or not it can have a NULL value for one column in the result set it cannot be used to return information about the bookmark column column 0 Syntax RETCODE SQLDescribeCol hstmt icol szColName cbColNameMax pcbColName pfSqlType pcbColDef pibScale pfNullable The SOLDescribeCol function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UWORD icol Input Column number of result data ordered sequentially left to right starting at 1 UCHAR FAR szColName Output Pointer to storage for the column name If the column is unnamed or the column name cannot be determined the driver returns an empty string SWORD cbColNameMax Input Maximum length of the szColName buffer SWORD FAR pcbColName Output Total number of bytes excluding the null termination byte available to return in szColName If the number of bytes available to return is greater than or equal to cbColNameMax the column name in szColName is truncated to cbColNameMax 1 bytes 1 of 2 12 86 INFORMIX CLI Programmer s Manual SQLDescribeCol Type Argument Use Description SWORD FAR pfSqlType Output The column s INFORMI
104. tables to which they refer If both szPkTableName and szFkTableName contain table names SQLForeignKeys returns the foreign keys in the table specified in szFkTa bleName that refer to the primary key of the table specified in szPkTableName These foreign keys returned by SQLForeignKeys should be one key at most INFORMIX CLI Function Reference 12 147 SQL ForeignKeys Column Name PKTABLE_QUALIFIER PKTABLE_OWNER PKTABLE_NAME PKCOLUMN_NAME FKTABLE_QUALIFIER SQLForeignKeys returns results as a standard result set If the foreign keys associated with a primary key are requested the result set is ordered by FKTABLE_QUALIFIER FKTABLE_OWNER FKTABLE_NAME and KEY_SEO If the primary keys associated with a foreign key are requested the result set is ordered by PKTABLE_QUALIFIER PKTABLE_OWNER PKTABLE_NAME and KEY_SEQ The following table lists the columns in the result set The lengths of VARCHAR columns that the table shows are maximums the actual lengths depend on the data source To determine the actual lengths of the TABLE_QUALIFIER TABLE_OWNER TABLE_NAME and COLUMN_NAME columns an application can call SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SOL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SOL_MAX_COLUMN_NAME_LEN options Data Type Comments Varchar 128 Primary key table qualifier identifier NULL if not applicable to the data source If a driver supports qualifiers for some tables but not for othe
105. than one henv should never be allocated at one time and the appli cation should not call SOLAllocEnv when a current valid henv exists If the application calls SOLAllocEnv with a pointer to a valid henv the driver overwrites the henv without regard to its previous contents When INFORMIX CLI processes the SOLAllocEnv function it checks the Trace value in the initialization files If the value is 1 INFORMIX CLI enables tracing See SOLBrowseConnect and SOLConnect INFORMIX CLI Programmers Manual For Information About See Allocating a connection handle SOLAllocConnect Connecting to a data source SOLConnect Freeing an environment handle SQLFreeEnv SQLAllocStmt SQLAIlocStmt SQLAIlocStmt allocates memory for a statement handle and associates the statement handle with the connection that hdbc specifies An application must call SOLAllocStmt before it submits SQL statements Syntax RETCODE SQLAllocStmt hdbc phstmt The SOLAllocStmt function accepts the following arguments Typedef Argument Use Description HDBC hdbc Input Connection handle HSTMT FAR phstmt Output Pointer to storage for the statement handle Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_INVALID_HANDLE or SQL_ERROR If SOLAllocStmt returns SOL_ERROR it sets the hstmt that phstmt references to SOL_NULL_HSTMT The application can then obtain additional infor mation by calling SOLError with the hdbc and SOL_NULL_HSTMT INFORMIX
106. the argument cbErrorMsgMax contains the largest possible byte count for an error message in this case the argument corresponds to the size in bytes of the argument szErrorMsg a character string buffer The argument pcbErrorMsg is a pointer to the count of bytes available to return in the argument szErrorMsg not including the null termination character Important Because characters are signed in many UNIX implementations and string arguments are unsigned in INFORMIX CLI functions applications that pass string objects to INFORMIX CLI functions without casting them receive compiler warnings 12 6 INFORMIX CLI Programmers Manual INFORMIX CLI Include Files INFORMIX CLI Include Files The files sql h and sqlext h contain function prototypes for all the INFORMIX CLI functions They also contain all type definitions and define constants Diagnostics The diagnostics provided with each function list SQLSTATE values that the function might return INFORMIX CLI can return additional SOLSTATE values that arise from implementation specific situations The character string value returned for an SQLSTATE consists of a two character class value followed by a three character subclass value A class value of 01 indicates a warning and is accompanied by a return code of SOL_SUCCESS_WITH_INFO Class values other than 01 except for the class IM indicate an error and are accompanied by a return code of SOL_ERROR The class IM signifies warnin
107. the characteristics of the result set are known To retrieve a row of data from the result set an application performs the following operations 1 Calls SOLBindCol to bind the columns of the result set to storage locations if it has not already done so 2 Calls SOLFetch to move to the next row in the result set and retrieve data for all bound columns Retrieving Results 6 5 Using Cursors Figure 6 1 shows the operations that an application uses to retrieve data from the result set Figure 6 1 Operations That an Application Uses to Retrieve Data from the Result Set SQLNumResultCols SQLDescribeCol SQLBindCol SQLFetch More rows Using Cursors The INFORMIX CLI driver maintains a cursor to indicate the current position in the result set much as the cursor on a computer screen indicates the current position You can use SQLFetch or SOLExtendedFetch to retrieve data from a result set Each time that an application calls SQLFetch the driver moves the cursor to the next row and returns that row To retrieve a row of data that has already been retrieved from the result set the application must close the cursor by calling SOLFreeStmt with the SOL_CLOSE option re execute the SELECT statement and fetch rows with SQLFetch until the target row is retrieved Important Committing or rolling back a transaction either by calling SQLTransact or by using the SQL_LAUTOCOMMIT connection option can cause the data source to
108. the initialization files to augment the information passed to it in the connection string If the infor mation in the initialization files duplicates information in the connection string the driver uses the information in the connection string Based on the value of fDriverCompletion the driver prompts the user for connection information such as the user ID and password and connects to the data source as follows m SQL_DRIVER_PROMPT The driver displays a dialog box using the values from the connection string and the initialization files as initial values When the user exits the dialog box the driver connects to the data source It also constructs a connection string from the value of the DSN or DRIVER keyword in szConnStrIn and the information returned from the dialog box It places this connection string in the buffer refer enced by szConnStrOut m SOL _DRIVER_COMPLETE or SQL_DRIVER_COMPLETE_REQUIRED If the connection string contains enough correct information the driver connects to the data source and copies szConnStrIn to szConnStrOut If any information is missing or incorrect the driver takes the same actions as it does when fDriverCompletion is SOL_DRIVER_PROMPT except that if fDriverCompletion is SQL_DRIVER_COMPLETE_REQUIRED the driver disables the controls for any information that is not required to connect to the data source m SQL_DRIVER_NOPROMPT If the connection string contains enough information the driver co
109. to reflect the specified values Warning To be compatible with other Informix connectivity products INFORMIX CLI no longer stores the data source configuration information in the odbc ini file Instead Informix products store data source configuration information in a set of files Therefore modifying odbc ini has unpredictable system results Use the ODBC Administrator to add or modify data sources This warning applies only to Windows environments Configuring DataSources 2 3 Adding a Data Source 2 4 Keyword Attribute Adding a Data Source When you add a data source you must provide the name of the data source and the name of the database to which you want to connect to by default All other connection information is optional The following table lists the required information that you must set when you add a data source Description Data Source Name Database a data source Attribute Host Protocol PWD Server Service UID INFORMIX CLI Programmer s Manual Name of a data source as returned by SOLDataSources or the data sources dialog box of SOLDriverConnect Name of the database to which you want to connect by default The following table lists optional information that you can set when you add Description The name of the computer on which the Informix database server resides The protocol used to communicate with the database server In Windows environments values can be xxSOCTC
110. to the C data type specified by the argument fCType The communication link between the driver and the data source failed before the function completed If the column value is null then StrLen_or_Ind must not be a null pointer Returning the numeric value as numeric or string for the column would cause the whole as opposed to fractional number to truncate Returning the binary value for the column would have caused a loss of binary significance The data for the column was incompatible with the data type in which it was to be converted For more information see Appendix B Data Types The data for the column was not a valid date time or time stamp value For more information see Appendix B A value from an arithmetic expression was returned that resulted in a division by zero 1 of 3 INFORMIX CLI Programmers Manual SQL GetData SQLSTATE Error Description 24000 Invalid cursor state DM The hstmt was in an executed state but no result set was associated with the hstmt DM A cursor was open on the hstmt but SQLFetch or SQLExtendedFetch was not called A cursor was open on the hstmt and SQLFetch or SQLExtendedFetch had been called but the cursor was positioned before the start of the result set or after the end of the result set S1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError re
111. typically result in improved performance Because the database server is already positioned on the row for the SELECT statement currently in process expensive operations to locate the row to be changed are unnecessary If the row must be located the database server typically has an internal pointer to the row available for example ROWID Determining the Optimal Set of Columns Use SOLSpecialColumns to determine the optimal set of columns to use in the WHERE clause for updating data Many times pseudocolumns provide the fastest access to the data you can determine these columns only by using SQLSpecialColumns Many applications cannot be designed to take advantage of positioned updates and deletes These applications typically update data by forming a WHERE clause that consists of some subset of the column values that are returned in the result set Some applications might formulate the WHERE clause by using all searchable result columns or by calling SQLStatistics to find columns that might be part of a unique index These methods typically work but can result in fairly complex queries 10 12 INFORMIX CLI Programmer s Manual Determining the Optimal Set of Columns Consider the following example rc SQLExecDirect hstmt SELECT first_name last_name ssn address city state zip FROM emp SQL_NTS fetchdata rc SQLExecDirect hstmt UPDATE EMP SET ADDRESS WHERE first_name AND last_name AND ssn
112. with the desired CREATE DATABASE or DROP DATABASE SQL statements For more information on these SQL statements see the Informix Guide to SQL Syntax 4 Disconnect from the database server only connection 5 Reconnect to the desired database as a normal connection that is with the default setting of the ConnectDatabase option Either the configuration information or the connection string must specify the database to which you are connecting INFORMIX CLI Programmers Manual Example Connection Strings The following code shows how to use the server only connection kK k k kK k k kK kK kK kK kK kK kK kK kK k k kK xf de de de de de de de UCHAR C e reatedb c INFORMIX CLI CREATE Database Example OBD S NANNNNNNNMN C Functions LAllocEnv LAllocConnect LAllocStmt LConnect LFreeEnv LFreeect LFreeStmt LDisconnect LExecDirect IO OOO ODO lt stdio h gt lt stdlib h gt lt string h gt lt io h gt lt windows h gt lt conio h gt infxcli h defDbNameL imydsn define ErrMsgLen 200 UCHAR ErrMsgLErrMsgLen void printError HENV henv HDBC hdbc HSTMT hstmt char SqlState RETCODE rc SQL_NO_DATA_FOUND SWORD pcbErrorMsgLen 0 SDWORD pfNativeError short 13 Connecting toaDataSource 4 11 Connection Strings for i SqlState SqlState SqlState
113. work with the Estimate option When you use a multibyte code set in which characters vary in length ranging from 1 to 4 bytes as either the database or client locale the length of a character string or simple large object TEXT in the database locale does not indicate the length of the string after it is converted to the client locale 0 Estimate 1 Exact Estimate Exact VMBCHARLENEXACT Estimate Overview of INFORMIX CLI 1 13 Configuring Data Sources Configuring Data Sources on Windows Adding a Data Source Modifying a Data Source Configuring Data Sources on UNIX File Format for odbc ini ODBC Data Sources Data Source Specification File Format for odbcinst ini Adding a Data Source Modifying a Data Source 2 3 2 4 2 7 2 10 2 11 2 12 2 14 2 14 2 15 2 2 INFORMIX CLI Programmer s Manual rN his chapter explains how to configure data sources Before you can connect to a data source you must configure it For information about data sources see What Is a Data Source on page 1 7 Configuring Data Sources on Windows In Windows environments INFORMIX CLI provides the ODBC Adminis trator which lets you configure data sources The ODBC Administrator provides a graphical user interface GUI that simplifies the process of adding and modifying data sources After you add or change data source configu ration information the ODBC Administrator updates the appropriate files
114. 0 Execute the SQL statement Ef Istrcpy create CREATE TABLE NAMEID ID INTEGER NAME VARCHAR 50 rc SQLExecDirect hstmt create SQL_NTS 9 4 INFORMIX CLI Programmer s Manual Static SQL Example if re SQL_SUCCESS amp amp rc SQL_SUCCESS WITH_INFO return print_err hdbc hstmt EXEC Comm SQL COMMIT WORK it the table creation Sf Ry Note that the default transaction mode for drivers that support SQLSetConnectOption is auto commit and SQLTransact has no effect SQLTransact hdbc SQL_COMMIT Is if SQ 0 SQ EXEC Show Prep Assi Exec repy SQL SQL INSERT INTO NAMET the use of the SQLPre are the insertion and gn parameter values ute the insertion insert INSERT INTO Prepare hstmt insert return print_err hdbc hs LBind 0 amp LBind MAX_NAM 1d 500 Is if rcpy SQL Parameter hstmt 1 SQ id 0 NULL Parameter hstmt 2 SQ E LEN 0 name 0 NUL name Babbage D VALUES bind parame AMEID VALU mt L_PARAM_INP L_PARAM_INP L Execute hstmt SQL SUCCESS return print_err hdbc hstmt EXEC SQL COMMIT WORK Commit the insertion SQLTransact hdbc SQL_COMMIT id name pare SQLExecute method ers El ES 7 SQL_NTS SQL_SUCCESS UT SQL_C_SLONG SQL_INTEGE
115. 00 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause S1001 Memory allocation The driver was unable to allocate memory failure required to support execution or completion of the function S1010 Function sequence DM SOLExecute or SQLExecDirect was called for error the hstmt and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns 1 of 2 INFORMIX CLI Function Reference 12 265 SQL Procedures SQLSTATE Error Description S1090 Invalid string or DM The value of one of the name length buffer length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corre sponding qualifier or name S1C00 Driver not capable A procedure qualifier was specified but the driver or data source does not support qualifiers A procedure owner was specified but the driver or data source does not support owners A string search pattern was specified for the procedure owner or procedure name but the data source does not support search patterns for one or more of those arguments The driver or data source did not support the combination of the current settings of the SOL_CONCURRENCY and SOL_CURSOR_TYPE statement
116. 002 S0011 S0012 S0021 Syntax error or access violation Base table or view already exists Table or view not found Index already exists Index not found Column already exists SQLExecDirect Description The user did not have permission to execute the SQL statement contained in the argument szSqlStr The argument szSq Str contained a CREATE TABLE or CREATE VIEW statement but the table name or view name specified already exists The argument szSq Str contained a DROP TABLE or a DROP VIEW statement but the specified table name or view name did not exist The argument szSq Str contained an ALTER TABLE statement but the specified table name did not exist The argument szSq Str contained a CREATE VIEW statement but a table name or view name defined by the query specification did not exist The argument szSq Str contained a CREATE INDEX statement but the specified table name did not exist The argument szSq Str contained a GRANT or REVOKE statement but the specified table name or view name did not exist The argument szSq Str contained a SELECT statement but a specified table name or view name did not exist The argument szSq Str contained a DELETE INSERT or UPDATE statement but the specified table name did not exist The argument szSq Str contained a CREATE TABLE statement but a table specified in a constraint referencing a table other than the one being created did not exist The argument
117. 08 22012 24000 40001 S1000 1001 1002 S1008 12 140 SQLSTATE Error Error in assignment Datetime field overflow Division by zero Invalid cursor state Serialization failure General error Memory allocation failure Invalid column number Operation canceled INFORMIX CLI Programmers Manual Description A zero length string was inserted into a string field and the string was bound to a numeric data type so the string was converted to a zero An SOL _C TIME SQL_C_DATE or SOL_C_TIMESTAMP value was converted to an SQL_CHAR data type and the value was an invalid date time or time stamp respectively A value from an arithmetic expression was returned that resulted in division by zero The hstmt was in an executed state but no result set was associated with the hstmt The transaction in which the fetch was executed was terminated to prevent deadlock An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SOLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support executing or completing the function A column number specified in the binding for one or more columns was greater than the number of columns in the result set A column number specified in the binding for a column was 0 The function was called but
118. 09 Invalid cursor position S1C00 Driver not capable Usage the null termination byte INFORMIX CLI Programmers Manual Description DM The value specified for the argument fOption was in the block of numbers reserved for ODBC connection and statement options but was not valid for the version of ODBC supported by the driver The fOption argument was SOL_ROW_NUMBER but the value in the refRowStatus array in SOLExtendedFetch for the current row was SOL_ROW_DELETED or SQL_ROW_ERROR The driver or data source does not support the value specified for the argument fOption 2 of 2 The following table lists statement options for which corresponding values can be returned but not set For a list of options that can be set and retrieved see Usage on page 12 298 If fOption specifies an option that returns a string puParam must be a pointer to storage for the string The maximum length of the string is SOL_MAX_OPTION_STRING_LENGTH bytes excluding fOption pvParam contents SQL_GET_ROWID Returns the row ID of the last row inserted returns 0 if the last SQL operation was not Insert SQL GET_SERIAL_VALUE Returns the serial ID of the last row inserted returns 0 if the last SQL operation was not Insert SQL_ROW_NUMBER A 32 bit integer value that specifies the number of the current row in the entire result set If the number of the current row cannot be determined or there is no current row the driver returns 0
119. 12 246 with SQLExecute 12 121 SQLPrimaryKeys 12 253 SQLProcedureColumns 12 257 12 260 SQLProcedures 12 264 SQLPutData data at execution parameters 5 10 function description 12 271 with SQLBindParameter 12 33 with SQLParamData 12 242 SQLRemoveDSNFromIni 13 6 SQLRowCount function description 12 278 interoperability 6 5 SQLSetConnectOption commit mode 5 9 function description 12 281 with SQLConnect 12 79 with SQLTransact 12 285 See also Connection options SQLSetCursorName 12 290 SQLSetScrollOptions 12 295 SQLSetStmtOption function description 12 296 with SQLExtendedFetch 12 126 See also Statement options SQLSpecialColumns 12 304 SOLSTATE guidelines 7 3 naming conventions 12 7 values listed A 1 See also specific function descriptions SQLStatistics 12 311 SQLTablePrivileges 12 319 SQLTables 12 325 SQLTransact commit mode 12 285 committing 5 9 function description 12 331 rolling back 5 9 two phase commit 12 333 with SQLSetConnectOption 12 285 SQLWriteDSNTolIni 13 5 SOLWritePrivateProfileString 13 5 SQL_BIGINT data type B 4 SQL_BIT data type B 4 SQL_CHAR data type B 2 SQL_C_BINARY data type B 12 SQL_C_BIT data type B 12 SQL_C_CHAR data type B 10 SQL_C_DATE data type B 11 SQL_C_DOUBLE data type B 10 SQL_C_FLOAT data type B 10 SQL_C_LONG data type B 10 SQL_C_SHORT data type B 10 SQL_C_SLONG data type B 10 SQL_C_SSHORT data type B 11 SQL_C_STINYINT data type B 11 SQL_C_TIMESTAMP data type B 11 SQL_C_TINYINT dat
120. 12 62 SQLColumnPrivileges SQLColumnPrivileges returns a list of columns and associated privileges for the specified table The driver returns the information as a result set on the specified hstmt Syntax RETCODE SQLColumnPrivileges hstmt cbTableQualifier cbTableName szTableOwner szColumnName szTableQualifier cbTableOwner szTableName cbColumnName The SOLColumnPrivileges function accepts the following arguments Type HSTMT UCHAR FAR SWORD UCHAR FAR SWORD UCHAR FAR SWORD UCHAR FAR SWORD Argument hstmt szTableQualifier cbTableQualifier szTableOwner cbTableOwner szlableName cbTableName szColumnName cbColumnName INFORMIX CLI Programmer s Manual Use Input Input Input Input Input Input Input Input Input Description Statement handle Table qualifier If a driver supports quali fiers for some tables but not for others such as when the driver retrieves data from different data sources an empty string denotes those tables that do not have qualifiers Length of szTableQualifier Owner name If a driver supports owners for some tables but not for others such as when the driver retrieves data from different data sources an empty string denotes those tables that do not have owners Length of szTableOwner Table name Length of szTableName String search pattern for column names Length of szColumnName SQL ColumnP
121. 2 8 Driver Configuring DataSources 2 11 File Format for odbc ini fication section Format Driver Description Database UID user_id PWD Server CLIENT_LOCALE DB_LOCALE TRANSLATIONDLL VMBCHARLENEXACT Field data_source_name driver_path data_source_description database_name user_id user_password database_server GLS application_locale 2 12 INFORMIX CLI Programmers Manual data_source_name driver_path data_source_description database_name Data Source Specification user_password database_server application_locale database_locale translation_path output_option Description Data source specified in the ODBC Data Sources section Path for the INFORMIX CLI driver Description of the INFORMIX CLI driver Name of the database that is associated with the data source User ID for connecting to the data source Password for connecting to the data source Name of the database server that is associated with the data source Locale and code set in which the application runs Default value en_us 8859 1 Each data source in the ODBC Data Sources section has a Data Source Speci Status Required Required Optional Required Optional Optional Required Optional 1 of 2 File Format for odbc ini Field Description Status database_locale Local and code set in which the database Optional was created Default value en_us 8859 1 translation_path
122. 35 currency data type 12 227 money data type 12 227 radix 12 73 12 262 scalar functions 12 206 See also Floating point data Integer data NUMERIC data type B 2 NVARCHAR data type B 3 O ODBC Administrator adding a data source 2 3 modifying a data source 2 7 odbcinst ini 2 9 odbc ini Data Source Specification section 2 12 introduction 2 9 ODBC Data Sources section 2 11 On line manuals Intro 9 OPAQUE data type B 4 Optimistic concurrency control See Concurrency ORDER BY clauses columns in select list 12 207 expressions in 12 199 maximum columns in 12 203 Outer joins 12 208 Output buffers 3 10 Output parameters 12 30 Owner names procedure 12 260 12 267 table 12 322 SQLColAttributes 12 57 SQLColumnPrivileges 12 65 SQLColumns 12 71 term vendor specific 12 208 P Packet size 12 287 Pages index or table 12 317 Parameters binding 5 8 12 29 data at execution 5 10 12 29 12 31 12 32 12 33 input 12 29 input output 12 29 long data values 5 10 number of 12 236 output 12 30 procedure 12 29 12 260 unbinding 5 8 values 5 7 See also Arguments PATH 1 9 Patterns for searching 12 8 Phantoms 12 198 Plans access 5 6 Platform icons Intro 7 Pointers maintaining 3 8 Pointers null See Null pointers Positioned DELETE statements cursor name 12 169 12 292 executing 6 12 support of 12 209 Positioned UPDATE statements cursor name 12 169 12 292 executing 6 12 support of 12 209 Position cursor See Cursor p
123. ARCHAR 128 Table type one of the following TABLE VIEW SYSTEM TABLE GLOBAL TEMPORARY LOCAL TEMPORARY ALIAS SYNONYM or a data source specific table type REMARKS VARCHAR 254 A description of the table INFORMIX CLI Function Reference 12 329 SQL Tables 12 330 Code Example Related Functions For a code example of a similar function see SQLColumns INFORMIX CLI Programmer s Manual For Information About See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SOLCancel Returning privileges for a column or columns SQLColumnPrivileges Returning the columns in a table or tables SQLColumns Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SQLFetch Returning table statistics and indexes SOLStatistics Returning privileges for a table or tables SQLTablePrivileges SQLTransact 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 SOQLTransact henv hdbc fType The SOLTransact function accepts the following arguments Typedef Argument Use Description HENV henv Input Environment handle HDBC hdbc Input Connection handle UWORD fType Input One of the following t
124. An application typically calls SOLError when a previous call to an INFORMIX CLI function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR However any INFORMIX CLI function can post zero or more errors each time that it is called so an application can call SQLError after any INFORMIX CLI function call SQLError retrieves an error from the data structure associated with the right most non null handle argument An application requests error information in the following ways m To retrieve errors associated with an environment the application passes the corresponding henv and includes SOL_NULL_HDBC and SQL_NULL_HSTMT in hdbc and hstmt respectively The driver returns the error status of the INFORMIX CLI function most recently called with the same henv m To retrieve errors associated with a connection the application passes the corresponding hdbc plus an hstmt equal to SOL_NULL_HSTMT In such a case the driver ignores the henv argument The driver returns the error status of the INFORMIX CLI function most recently called with the hdbc 12 108 INFORMIX CLI Programmer s Manual SQLError m To retrieve errors associated with a statement an application passes the corresponding hstmt If the call to SOLError contains a valid hstmt the driver ignores the hdbc and henv arguments The driver returns the error status of the INFORMIX CLI function most recently called with the hstmt m To retrieve multiple errors for a function call an app
125. CCESS_WITH_INFO 1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause S1001 Memory allocation The driver did not allocate memory required to failure support execution or completion of the function S1010 Function sequence DM SQLGetFunctions was called before error SQLConnect SQLBrowseConnect or SQLDriverConnect DM SQLBrowseConnect was called for the hdbc and returned SQL_NEED_DATA This function was called before SOLBrowseConnect returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS S1095 Function type out DM An invalid fFunction value was specified of range INFORMIX CLI Function Reference 12 179 SQL GetFunctions Usage The following list identifies valid values for fFunction for ODBC core functions that the INFORMIX CLI driver supports SQL_API_SQLALLOCCONNECT SQL_API_SQLALLOCENV SQL_API_SQLALLOCSTMT SQL_API_SOLBINDCOL SQL_API_SOQLCANCEL SOL_API_SOLCOLATTRIBUTES SQL_API_SQLCONNECT SOL_API_SOLDESCRIBECOL SOL_API_ SOLDISCONNECT SQL_API_SQLERROR SQL_API_SQLEXECDIRECT SQL_API_SQLEXECUTE SOL_API_SOLFETCH SOL_API_ SOLFREECONNECT SOL_API_ SOLFREEENV SOL_API_SOLFREESTMT SOL_API_SOLGETCURSORNAME SOL_API SOLNUMRESULTCOLS SOL_API_SOLPREPARE SOL_API SOLROWCOUNT SOL_API_SOLSETCURSORNAME SOL_API_SOLSETPARAM SOL_API SOLTRANSACT The
126. CESS is returned If the fSqlType argument in SOLBindParameter contains a value for an INFORMIX CLI SQL data type that is not shown in the table for a given C data type then SOLBindParameter returns SOLSTATE 07006 Restricted data type attribute violation If the fSqlType argument contains a driver specific value and the driver does not support the conversion from the specific INFORMIX CLI C data type to the driver specific SOL data type then SQLBindParameter returns SOLSTATE S1C00 Driver not capable If the rgbValue and pcbValue arguments specified in SOLBindParameter are both null pointers then that function returns SOLSTATE S1009 Invalid argument value Although it is not shown in the tables an application sets the value pointed to by the pcbValue argument of SOLBindParameter or the value of the cbValue argument to SOL_NULL_DATA to specify a NULL SOL data value The application sets these values to SQL_NTS to specify that the value in rgbValue is a null terminated string Data Types B 31 Converting Data from C to SQL B 32 C to SQL Character The character INFORMIX CLI C data type is SQL_C_CHAR The following table shows the INFORMIX CLI SQL data types to which C character data can be The following terms are used in the tables m Length of data is the number of bytes of SQL data that are available to send to the data source regardless of whether the data is truncated before it goes to the data source For string data this
127. CHAR szName NAME_LEN amp cbName SQLGetData hstmt 2 SQL_C_SSHORT amp sAge 0 amp cbAge SQLGetData hstmt 3 SQL_C_CHAR szBirthday BDAY_LEN amp cbBirthday fprintf out s 2d s NAME_LEN 1 szName sAge BDAY_LEN 1 szBirthday else break 12 176 INFORMIX CLI Programmer s Manual Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Executing an SQL statement Executing a prepared SQL statement Fetching a block of data or scrolling through a result set Fetching a row of data Sending parameter data at execution time SQL GetData See SOLBindCol SQLCancel SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SQLPutData INFORMIX CLI Function Reference 12 177 SQL GetFunctions 12 178 Syntax Type Argument HDBC hdbc UWORD fFunction UWORD FAR pfExists INFORMIX CLI Programmers Manual SQLGetFunctions SOLGetFunctions returns information about whether the INFORMIX CLI driver supports a specific function Use Input Input Output RETCODE SQLGetFunctions hdbc fFunction pfExists The SQLGetFunctions function accepts the following arguments Description Connection handle SQL_API_ALL_FUNCTIONS or a define value that identifies the ODBC function of interest For a list of define values that identify ODBC functions see Usage on page 12 180 If fFunction is SOL_API_ALL_FUN
128. CTIONS pfExists points to a UWORD array with 100 elements The array is indexed by define values used by fFunction to identify each ODBC function some elements of the array are unused and are reserved for future use An element is TRUE if it identifies an ODBC function supported by the driver It is FALSE if it identifies an ODBC function not supported by the driver or does not identify an ODBC function The fFunction value SOL_API_ALL_FUNCTIONS was added in ODBC 2 0 If fFunction identifies a single ODBC function pfExists points to a single UWORD pfExists is TRUE if the specified function is supported by the driver otherwise it is FALSE SQLGetFunctions Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_ HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SQLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SU
129. CUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise INFORMIX CLI Function Reference 12 117 SQL Execute 01000 01004 01006 01503 01504 07001 08501 SQLSTATE Error General warning Data truncated Privilege not revoked No rows updated or deleted More than one row updated or deleted Wrong number of parameters Communication link failure 12 118 INFORMIX CLI Programmer s Manual If you are not using a driver manager the driver returns the SOLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The prepared statement associated with the hstmt contained a character or binary parameter or literal but the value exceeded the maximum length of the associated table column The prepared statement associated with the hstmt contained a numeric parameter or literal but the fractional part of the value was truncated The prepared statement associated with the hstmt c
130. C_ULONG B 11 SQL_C_USHORT B 11 SQL_C_UTINYINT B 11 standard B 1 timestamp B 11 INFORMIX CLI Programmer s Manual typedefs for B 1 See also Converting data SQL data types Call level interface CLI support of 12 207 Canceling connection browsing 12 93 data at execution 12 51 Cardinality 12 317 Cascading deletes 12 149 Cascading updates 12 149 Case sensitivity columns 12 56 data types 12 226 quoted SQL identifiers 12 210 Catalog functions list of 5 10 search patterns 12 8 summary 11 8 CHAR data type B 2 Character data B 10 case sensitivity 12 226 converting to C B 21 converting to SQL B 32 empty string 3 9 literal length 12 203 prefix string 12 225 suffix string 12 225 CHARACTER data type B 2 CHARACTER VARYING data type B 2 Characters special See Special characters Client locale 1 11 CLIENT_LOCALE 1 11 2 12 Closing cursors 12 196 SQLCancel 12 50 SQLFreeStmt 8 3 Clustered indexes 12 316 Code examples ad hoc query 9 7 parameter values 5 8 static SQL 9 4 See also specific function descriptions Codes return 7 3 Collating 12 206 12 316 Columns aliases 12 194 attributes 12 56 12 89 binding See Binding columns foreign keys 12 149 in GROUP BY clauses 12 203 in indexes 12 203 in select lists 12 204 in tables 12 204 listing 12 71 maximum name length 12 203 nullable 12 205 number of 12 56 12 239 precision See Precision primary keys 12 148 12 255 procedure See Procedure columns pseudo 12 309 sign
131. Converting data Types of Data Types The following table describes the types of data types that INFORMIX CLI supports Type of Data Type Description Example Informix SQL data Data types that your Informix CHAR n type database server uses INFORMIX CLISQL Datatypes that correspond to SQL_CHAR data type the Informix SQL data types Standard C data type Data types that your C unsigned char compiler defines Typedef for a Typedefs that correspond to UCHAR standard C data type the standard C data types INFORMIX CLI C Data types that correspond to SQL_C_CHAR data type the standard C data types SQL Data Types SQL Data Types Guide to SQL Reference Informix SQL INFORMIX CLI SQL Data Type Data Type fSqlType BYTE SQL_LONGVARBINARY CHAR n CHARACTER n SQL_CHAR CHARACTER VARYING m r SOL_VARCHAR DATE SQL_DATE DATETIME SQL_TIMESTAMP DEC p s DECIMAL p s SQL_DECIMAL DOUBLE PRECISION SQL_DOUBLE FLOAT SQL_DOUBLE INT INTEGER SQL_INTEGER MONEY p s SQL_DECIMAL NUMERIC SQL_DECIMAL For detailed information about the Informix SQL data types see the Informix Standard SQL Data Types The following table lists the standard Informix SQL data types and their corresponding INFORMIX CLI data types Description Binary data of variable length Character string of fixed length n 1 lt n lt 32 767 Character string of variable length with maximum length m 1 lt m lt 255 and minimum amount of res
132. Data is 0 or 1 N A Data is greater than 0 less than 2 and not equal to 1 01004 22003 C to SQL Bit Converting Data from C to SQL The bit INFORMIX CLI C data type is SQL_C_BIT Only Universal Server supports SOL_C_BIT The following table shows the INFORMIX CLI SQL data types to which bit C data can be converted fSqlType Test SQLSTATE SQL_CHAR None SQL_LONGVARCHAR SQL_VARCHAR SQL_BIGINT None SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_REAL SQL_SMALLINT SQL_BIT None N A N A N A The value pointed to by the pcbValue argument of SQLBindParameter and the value of the cbValue argument of SQLPutData are ignored when data is converted from the bit C data type The driver assumes that the size of rebValue is the size of the bit C data type Data Types B 37 Converting Data from C to SQL C to SQL Binary The binary INFORMIX CLI C data type is SQL_C_BINARY The following table shows the INFORMIX CLI SQL data types to which binary C data can be converted fSqlType Test SQLSTATE SQL_CHAR Length of data lt Column length N A L_L N Length of data gt Column length 01004 SQL_DECIMAL Length of data SQL data length N A SQL_DOUBLE SQL_INTEGER Length of data SQL data length 22003 SQL_REAL SQL_SMALLINT SQL_LONGVARBINARY Length of data lt Column length N A Length of data gt Column length 01004 SQL_DATE Length of data SQL data length N A SQL_TIMESTAMP on i Length of
133. DriverConnect dialog box Freeing an environment handle SQLFreeEnv Freeing a statement handle SOLFreeStmt INFORMIX CLI Function Reference 12 157 SQL FreeEnv SQLFreeEnv SQLFreeEnv frees the environment handle and releases all memory associated with the environment handle Syntax RETCODE SQLFreeEnv henv The SOLFreeEnv function accepts the following argument Type Argument Use Description HENV henv Input Environment handle Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise 12 158 INFORMIX CLI Programmer s Manual SQLFreeEnv If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error mess
134. E SOL_DRIVER_COMPLETE_REQUIRED or SOL_DRIVER_NOPROMPT The time out period expired before the connection to the data source completed The time out period is set through SQLSetConnectOption SQL_LOGIN_TIMEOUT 3 of 3 SQL DriverConnect Usage SQLDriverConnect uses a connection string to specify the information needed to connect to a driver and data source The connection string is a more flexible interface than the data source name user ID and password used by SQLConnect The application can use the connection string for multiple levels of login authorization or to convey other data source specific connection information Driver Manager Guidelines Tip On Windows a driver manager is mandatory and INFORMIX CLI provides the driver manager On UNIX a driver manager is optional If you want to use a driver manager on UNIX you need to purchase one from a third party vendor The driver manager constructs a connection string to pass to the driver in the szConnStrIn argument of the driver SQLDriverConnect function The driver manager does not modify the szConnStrIn argument passed to it by the application If the connection string specified by the application contains the DSN keyword or does not contain either the DSN or DRIVER keywords the action of the driver manager is based on the value of the fDriverCompletion argument as the following list explains m SQL_DRIVER_PROMPT The driver manager displays the Data Sources
135. E table name SET column identifier expression NULL column identifier expression NULL WHERE CURRENT OF cursor name DELETE FROM table name WHERE CURRENT OF cursor name Positioned update and delete statements require cursor names An appli cation can name a cursor with SQLSetCursorName If the application has not named the cursor by the time that the driver executes a SELECT statement the driver generates a cursor name To retrieve the cursor name for an hstmt an application calls SOLGetCursorName To execute a positioned update or delete statement an application must follow these guidelines m The SELECT statement that creates the result set must use a FOR UPDATE clause m The cursor name used in the UPDATE or DELETE statement must be the same as the cursor name associated with the SELECT statement m The application must use different hstmts for the SELECT statement and the UPDATE or DELETE statement m The hstmts for the SELECT statement and the UPDATE or DELETE statement must be on the same connection To determine whether a data source supports positioned update and delete statements an application calls SOLGetInfo with the SQL_POSITIONED_STATEMENTS option INFORMIX CLI Programmers Manual Processing Multiple Results Processing Multiple Results SELECT statements return result sets UPDATE INSERT and DELETE state ments return a count of affected rows If any of these statements are in procedures
136. E was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM The fInfoType was SOL_DRIVER_HSTMT and the value pointed to by rgbInfoValue was not a valid statement handle 1 of 2 SQLSTATE S1090 S1096 S1C00 S1T00 Usage Error Invalid string or buffer length Information type out of range Driver not capable Time out expired SOL Getinto Description DM The value specified for argument cbInfoValueMax was less than 0 DM The value specified for the argument fOption was in the block of numbers reserved for ODBC information types but was not valid for the version of ODBC that the driver supports The driver does not support the value specified for the argument fOption The time out period expired before the data source returned the requested information The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 The format of the information returned in rgbInfoValue depends on the finfoType requested SQLGetInfo returns information in one of the following five formats A 16 bit integer value A 32 bit bitmask A 32 bit integer value A 32 bit binary value A null terminated character string The format for each of the following information types is noted in the description The application must cast the value retu
137. E_NAME DATA_TYPE PRECISION LITERAL_PREFIX LITERAL_SUFFIX Data Type VARCHAR 128 not NULL SMALLINT not NULL INTEGER VARCHAR 128 VARCHAR 128 Comments Data source dependent data type name for example CHAR VARCHAR MONEY LONG VARBINARY or CHAR 0 FOR BIT DATA Applications must use this name in CREATE TABLE and ALTER TABLE statements Informix SOL data type The possible values are any of the Informix SOL data types listed in Appendix B Data Types For more information about data types and conversions see Appendix B The maximum precision of the data type on the data source Null is returned for data types where precision is not applicable For more information on precision see Precision Scale Length and Display Size on page B 5 Character or characters used to prefix a literal for example a single quote for character data types or 0x for binary data types null is returned for data types where a literal prefix is not applicable Character or characters used to terminate a literal for example a single quote for Character data types null is returned for data types where a literal suffix is not applicable 1 of 4 INFORMIX CLI Function Reference 12 225 SQL Get Typelnfo 12 226 Column Name CREATE_PARAMS NULLABLE CASE_SENSITIVE INFORMIX CLI Programmers Manual Data Type VARCHAR 128 SMALLINT not NULL SMALLINT not NULL Comments
138. FAR SWORD UCHAR FAR SWORD Argument hstmt szTableQualifier cbTableQualifier szTableOwner cbTableOwner szTableName cbTableName szTableType cbTableType Use Input Input Input Input Input Input Input Input Input Description Statement handle for retrieved results Qualifier name If a driver supports quali fiers for some tables but not for others such as when a driver retrieves data from different DBMSs an empty string denotes those tables that do not have qualifiers Length of szTableQualifier String search pattern for owner names Length of szTableOwner String search pattern for table names If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have owners Length of szTableName List of table types to match Length of szTableType INFORMIX CLI Function Reference 12 325 SQL Tables Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLS
139. FN_TD_CURTIME SQL_FN_TD_DAYNAME SQL_FN_TD_DAYOFMONTH SQL_FN_TD_DAYOFWEEK SQL_FN_TD_DAYOFYEAR SQL_FN_TD_HOUR SQL_FN_TD_MINUTE SQL_FN_TD_MONTH SQL_FN_TD_MONTHNAME SQL_FN_TD_NOW SQL_FN_TD_QUARTER SQL_FN_TD_SECOND SQL_FN_TD_TIMESTAMPADD SQL_FN_TD_TIMESTAMPDIFF SQL_FN_TD_WEEK SQL_FN_TD_YEAR SQL_TXN_CAPABLE A 16 bit integer value that describes the transaction support in the driver or data source m SQL_TC_NONE Transactions not supported m SQL_TC_DML Transactions can contain only Data Manipu lation Language DML statements SELECT INSERT UPDATE DELETE Data Definition Language DDL statements encoun tered in a transaction cause an error m SQL_TC_DDL_COMMIT Transactions can contain only DML statements DDL statements CREATE TABLE DROP INDEX an so on encountered in a transaction cause the transaction to be committed m SQL_TC_DDL_IGNORE Transactions can contain only DML statements DDL statements encountered in a transaction are ignored m SQL_TC_ALL Transactions can contain DDL statements and DML statements in any order 23 of 24 INFORMIX CLI Function Reference 12 215 SQL Getinto InfoType SOL_TXN_ISOLATION_OPTION Returns A 32 bit bitmask that enumerates the transaction isolation levels available from the driver or data source The following bitmasks are used in conjunction with the flag to determine which options are supported SOL_TXN_READ_UNCOMMITTED SOL_TXN_READ_COMMITTED SO
140. Fetch To determine whether a driver can return data with SOLGetData from a block of data an application calls SOLGetInfo with the SOL_GETDATA_EXTENSIONS option Using Block and Scrollable Cursors Cursors in SQL scroll forward through a result set returning one row ata time However interactive applications often require forward and backward scrolling absolute or relative positioning within the result set and the ability to retrieve and update blocks of data or row sets A block cursor attribute allows an application to retrieve and update row set data A scrollable cursor attribute allows an application to scroll forward or backward through the result set or move to an absolute or relative position in the result set Cursors can have one or both attributes Block Cursors An application calls SOLSetStmtOption with the SOL_ROWSET_SIZE option to specify the row set size The application can call SOLSetStmtOption to change the row set size at any time Each time that the application calls SOLExtendedFetch the driver returns the next row set size rows of data After the data is returned the cursor points to the first row in the row set By default the row set size is one Retrieving Results 6 9 Using Block and Scrollable Cursors 6 10 Scrollable Cursors Applications have different needs to sense changes in the tables underlying a result set For example when balancing financial data an accountant needs data that appears st
141. Function returns SQL_SUCCESS_WITH_INFO The statement corresponding to hstmt was already in an executed or cursor positioned state The cursor name that the argument szCursor specified was invalid For example the cursor name exceeded the maximum length that the driver defines The cursor name that the argument szCursor specifies already exists An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function 1 of 2 INFORMIX CLI Function Reference 12 291 SQL SetCursorName 12 292 SQLSTATE Error S1009 Invalid argument value S1010 Function sequence error S1090 Invalid string or buffer length Description DM The argument szCursor was a null pointer DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The argument cbCursor was less than 0 but not equal to SQL_NTS Usage INFORMIX CLI Programmer s Manual 2 of 2 The only ODBC SQL statements that use a cursor name are a positioned UPDATE and DELETE for example UPDATE table name WHERE CURRENT OF cursor name If the application does not call SQLSetCursorNa
142. H_INFO fprintf out s s gt s s n szFkTable szFkCol szPkTable szPkCol Free the hstmt SQLFreeStmt hstmt SQL DROP INFORMIX CLI Function Reference 12 153 SQL ForeignKeys 12 154 Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Fetching a block of data or scrolling through a result set Fetching a row of data Returning the columns of a primary key Returning table statistics and indexes INFORMIX CLI Programmers Manual See SOLBindCol SOLCancel SOLExtendedFetch extension SOLFetch SQLPrimaryKeys extension SOL Statistics extension SQLFreeConnect SQLFreeConnect SQLFreeConnect releases a connection handle and frees all memory associated with the handle Syntax RETCODE SQLFreeConnect hdbc The SQLFreeConnect function accepts the following argument Type Argument Use Description HDBC hdbc Input Connection handle Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 155 SQLFreeConnect Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver
143. I Programmers Manual his chapter provides guidelines for designing and coding perfor mance oriented INFORMIX CLI applications These guidelines are based on four general performance rules Reduce network traffic as much as possible Simplify queries as much as possible Optimize the application to driver interaction Limit disk I O to improve performance Connecting to a Data Source Connection management is extremely important to application performance because the process of connecting to a data source is expensive To optimize your application design it to connect only once Rather than perform multiple connections use multiple statement handles Making One Connection Some ODBC applications are designed to call information gathering routines that have no record of connection handles hdbc pointers that already exist For example an application might establish a connection and then call a routine in a separate DLL or shared library that reattaches and gathers up front information about the driver to be used later in the application To optimize performance applications that are designed as separate entities should pass the already connected hdbc pointer to the data collection routine instead of establishing a second connection Designing Performance Oriented Applications 10 3 Using Statement Handles 10 4 Using Statement Handles You can associate multiple statement handles with one connection handle Statement
144. INARY or CHAR for BIT DATA The precision of the column on the data source For precision information see Precision Scale Length and Display Size on page B 5 The length in bytes of data transferred on an SQLGetData or SOLFetch operation if SQL_C_DEFAULT is specified For numeric data this size might be different than the size of the data stored on the data source This value is the same as the PRECISION column for character or binary data For more infor mation about length see Precision Scale Length and Display Size on page B 5 The scale of the column on the data source For more scale information see Precision Scale Length and Display Size on page B 5 NULL is returned for data types where scale is not applicable 2 of 3 SQLColumns Column Name Data Type Comments RADIX SMALLINT For numeric data types either 10 or 2 If it is 10 the values in PRECISION and SCALE give the number of decimal digits allowed for the column For example a DECIMAL 12 5 column would return a RADIX of 10 a PRECISION of 12 and a SCALE of 5 a FLOAT column could return a RADIX of 10 a PRECISION of 15 and a SCALE of NULL If itis 2 the values in PRECISION and SCALE give the number of bits allowed in the column For example a FLOAT column could return a RADIX of 2 a PRECISION of 53 and a SCALE of NULL NULL is returned for data types where RADIX is not applicable NULLABLE SMALLINT SQL_NO_NULLS
145. IVE_CONNECTIONS SQL_ACTIVE_STATEMENTS SQL_DATA_SOURCE_NAME SQL_DRIVER_HDBC SQL_DRIVER_HENV SQL_DRIVER_HLIB SQL_DRIVER_HSTMT SQL_DRIVER_NAME SQL_DRIVER_ODBC_VER SQL_DRIVER_VER SQL_FETCH_DIRECTION SQL_FILE_USAGE SOL_GETDATA_EXTENSIONS SOL_LOCK_TYPES SOL_ODBC_API CONFORMANCE SOL_ODBC_SAG_CLI CONFORMANCE SOL_ODBC_VER SOL_POS_OPERATIONS SOL_ROW_UPDATES SOL_SEARCH_PATTERN_ESCAPE SOL_SERVER_NAME INFORMIX CLI Function Reference 12 189 SQL Getinfo DBMS Product Information The following values of fInfoType return information about the Informix DBMS product such as the DBMS name and version m SQL_DATABASE_ NAME m SQL_DBMS_NAME m SQL_DBMS_VER Data Source Information The following values of fInfoType return information about the data source such as cursor characteristics and transaction capabilities SQL_ACCESSIBLE_PROCEDURES SQL_ACCESSIBLE_TABLES SQL_CONCAT_NULL_BEHAVIOR SQL_CURSOR_COMMIT_BEHAVIOR SQL_CURSOR_ROLLBACK_ BEHAVIOR SQL_DATA_SOURCE_READ_ONLY SQL_DEFAULT_TXN_ISOLATION SQL_MULT_RESULT_SETS SQL_MULTIPLE_ACTIVE_TXN SQL_NEED_LONG_DATA_LEN SQL_NULL_COLLATION SQL_OWNER_TERM SQL_PROCEDURE_TERM SQL_QUALIFIER_TERM SQL_SCROLL_CONCURRENCY SQL_SCROLL_OPTIONS SQL_STATIC_SENSITIVITY SQL_TABLE_TERM SQL_TXN_CAPABLE SQL_TXN_ISOLATION_OPTION SQL_USER_NAME 12 190 INFORMIX CLI Programmer s Manual SQLGetInfo Supported SQL The following values of fInfoType return information about the SQL statemen
146. IX CLI Version 2 8 delete the old data sources and configure new data sources with the INFORMIX CLI 2 8 driver To modify a data source 1 Invoke the ODBC Administrator The Data Sources dialog box appears as Figure 2 4 illustrates Figure 2 4 Data S Pees Dialog Box User Data Sources Driver Close Publications Informix 2 80 Accounts Informix 2 80 Help Setup Delete Add System DSN Drivers Configuring Data Sources 2 7 Modifying a Data Source 2 8 2 Inthe Data Sources dialog box select the Informix data source that you want to modify and click Setup The INFORMIX CLI DSN Setup dialog box appears as Figure 2 5 illustrates The values that appear are the default entries specified for this data source connection INFORMIX CLI DSN Setup Change data source name description or options Then Choose OK Note UID and PWD are Optional If specified PWD will be encrypted Host bear Service turbo uD engt2 PWD rr page 2 4 4 When you finish click OK appropriate files data source connection INFORMIX CLI Programmer s Manual Figure 2 5 A Completed INFORMIX CLI DSN Setup Dialog Box 3 Modify the applicable data source text boxes For more information regarding available options see Adding a Data Source on The ODBC Administrator updates the data source information in the
147. LGetData from bound columns from columns before the last bound column or from columns in any order To determine whether a driver supports these extensions an application calls SOLGetInfo with the SOL_GETDATA_EXTENSIONS option INFORMIX CLI Function Reference 12 175 SQL GetData Furthermore applications that use SOLExtendedFetch to retrieve data can call SQLGetData only when the row set size is 1 Code Example In the following example an application executes a SELECT statement to return a result set of the employee names ages and birthdays sorted by birthday age and name For each row of data it calls SOLFetch to position the cursor to the next row It calls SOLGetData to retrieve the fetched data the storage locations for the data and the returned number of bytes are specified in the call to SOLGetData Finally it prints each employee s name age and birthday define NAME_LEN 30 iHdefine BDAY_LEN 11 UCHAR szName NAME_LEN szBirthday BDAY_LEN SWORD sAge SDWORD cbName cbAge cbBirthday retcode SQLExecDirect hstmt SELECT NAME AGE BIRTHDAY FROM EMPLOYEE ORDER BY 3 2 1 SQL_NTS if retcode SQL_SUCCESS while TRUE retcode SQLFetch hstmt if retcode SQL_ERROR retcode SQL_SUCCESS WITH_INFO show_error if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO Get data for columns 1 2 and 3 Print the row of data E SQLGetData hstmt 1 SQL_C_
148. LI C Data Type fCType SOL_CHAR SOL_C_CHAR SOL_DATE SOL_C_DATE SOL_DECIMAL SOL_C_CHAR SOL_DOUBLE SOL_C_DOUBLE SOL_INTEGER SOL_C_SLONG SOL_LONGVARBINARY SOL_C_BINARY SOL_LONGVARCHAR SOL_C_CHAR 1 of 2 B 18 INFORMIX CLI Programmer s Manual Converting Data from SQL to C INFORMIX CLI SQL Data Type fSqlType Default INFORMIX CLI C Data Type fCType SQL_REAL SQL_C_FLOAT SQL_SMALLINT SQL_C_SSHORT SQL_TIMESTAMP SQL_C_TIMESTAMP SQL_VARCHAR SQL_C_CHARS 2 of 2 Additional Default C Data Types for Universal Server For each additional INFORMIX CLI SQL data type for Universal Server the following table shows the default C data type INFORMIX CLI SQL Data Type fSqlType Default INFORMIX CLI C Data Type fCType SQL_BIGINT SQL_C_CHAR SQL_BIT SQL_C_BITS SQL_INFX_UDT_FIXED None SOL_INFX_UDT_VARYING None a This INFORMIX CLI SQL data type does not have a default INFORMIX CLI C data type Since this INFORMIX CLISQL data type can contain binary data or character data you must bind a variable for this INFORMIX CLI SQL data type before you fetch a corresponding value The data type of the bound variable specifies the C data type for the value Converting Data from SQL to C When an application calls SOLExtendedFetch SQLFetch or SQLGetData the driver retrieves the data from the data source If necessary it converts the data from the data type in which the driver retrieved it to the data type specified by the fCTy
149. LSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning 01004 Data truncated 08003 Connection not open 22003 Numeric value out of range S1000 General error S1001 Memory allocation failure S1009 Invalid argument value INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer rgbInfo Value was not large enough to return all of the requested information so the information was truncated The argument pebInfo Value contains the length of the requested information in its untruncated form function returns SQL_SUCCESS_WITH_INFO DM The type of information requested in fInfoType requires an open connection Of the infor mation types reserved by ODBC only SQL_ODBC_VER can be returned without an open connection Returning the requested information would cause a loss of numeric or binary significance An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTAT
150. LSetCursorName associates a cursor name with an active hstmt If an application does not call SOLSetCursorName the driver generates cursor names as needed for SQL statement processing Syntax RETCODE SOLSetCursorName hstmt szCursor cbCursor The SQLSetCursorName function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szCursor Input Cursor name SWORD cbCursor Input Length of szCursor Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE 12 290 INFORMIX CLI Programmer s Manual Diagnostics SQL SetCursorName When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 24000 34000 3C000 S1000 S1001 General warning Invalid cursor state Invalid cursor name Duplicate cursor name General error Memory allocation failure INFORMIX CLI informational message
151. L_CURSOR_ROLLBACK_BEHAVIOR on page 12 196 Code Example See SOLBindParameter and SOLPutData INFORMIX CLI Function Reference 12 251 SQL Prepare 12 252 Related Functions For Information About Allocating a statement handle Assigning storage for a column in a result set Canceling statement processing Executing an SQL statement Executing a prepared SQL statement Returning the number of rows that a statement affects Setting a cursor name Assigning storage for a parameter Executing a commit or rollback operation INFORMIX CLI Programmer s Manual See SOLAllocStmt SOLBindCol SQLCancel SQLExecDirect SQLExecute SOLRowCount SOLSetCursorName SOLBindParameter SQLTransact SQLPrimaryKeys SQLPrimaryKeys SQLPrimaryKeys returns the column names that comprise the primary key for a table The driver returns the information as a result set This function does not support returning primary keys from multiple tables ina single call Syntax RETCODE SOQLPrimaryKeys hstmt szTableQualifier cbTableQualifier szTableQwner cbTableOwner szTableName cbTableName The SOLPrimaryKeys function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szTableQualifier Input Qualifier name If a driver supports quali fiers for some tables but not for others as when the driver retrieves data from different DBMSs an empty string denotes those tabl
152. L_CURSOR_TYPE statement options was not supported by the driver or data source Time out expired The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 5 of 5 Usage The application calls SQLExecDirect to send an SQL statement to the data source The driver modifies the statement to use the form of SQL that the data source uses and then submits it to the data source In particular the driver modifies the escape clauses used to define ODBC specific SQL The application can include one or more parameter markers in the SQL statement To include a parameter marker the application embeds a question mark into the SOL statement at the appropriate position If the SQL statement is a SELECT statement and if the application called SOLSetCursorName to associate a cursor with an hstmt the driver uses the specified cursor Otherwise the driver generates a cursor name If the data source is in manual commit mode requiring explicit transaction initiation and a transaction has not been initiated the driver initiates a transaction before it sends the SOL statement If an application uses SQLExecDirect to submit a COMMIT or ROLLBACK statement it is not interoperable between DBMS products To commit or roll back a transaction call SOLTransact INFORMIX CLI Function Reference 12 115 SQL ExecDirect 12 116 If SOLExecDirect encounters
153. L_TXN_REPEATABLE_READ SOL_TXN_SERIALIZABLE SOL_TXN_VERSIONING For descriptions of these isolation levels see SOL_DEFAULT_TXN_ISOLATION on page 12 198 SOL_UNION A 32 bit bitmask that enumerates the support for the UNION clause m SQL_U_UNION The data source supports the UNION clause m SQL_U_UNION_ALL The data source supports the ALL keyword in the UNION clause SQLGetInfo returns both SQL_U_UNION and SQL_U_UNION_ALL in this case SOL_USER_NAME 12 216 INFORMIX CLI Programmers Manual Code Example A character string with the name used in a particular database which can be different than login name 24 of 24 SQLGetInfo returns lists of supported options as a 32 bit bitmask in rgbInfoValue The bitmask for each option is used with the flag to determine whether the option is supported SQLGetInfo For example an application could use the following code to determine whether the driver associated with the hdbc supports the SUBSTRING scalar function UDWORD fFuncs SQLGetInfo hdbc SQL_STRING_FUNCTIONS PTR amp fFuncs sizeof fFuncs NULL if fFuncs amp SQL_FN_STR_SUBSTRING SUBSTRING supported else SUBSTRING not supported Related Functions For Information About Returning the setting of a connection option Determining if a driver supports a function Returning the setting of a statement option Returning information about the data types of a data source
154. MAX_COLUMNS_IN_SELECT SQL_MAX_COLUMNS_IN_TABLE SQL_MAX_CURSOR_NAME_LEN SQL_MAX_INDEX_SIZE SQL_MAX_OWNER_NAME_LEN SQL_MAX_PROCEDURE_NAME_LEN SOL_MAX_QUALIFIER_NAME_LEN SOL_MAX_ROW_SIZE SQL_MAX_ROW_SIZE_INCLUDES_LONG SQL_MAX_STATEMENT_LEN SQL_MAX_TABLE_NAME_LEN SQL_MAX_TABLES_IN_SELECT SQL_MAX_USER_NAME_LEN INFORMIX CLI Programmer s Manual InfoType SQL_ACCESSIBLE_PROCEDURES SQLGetInfo Scalar Function Information The following values of fInfoType return information about the scalar functions that the data source and the driver support For more information on scalar functions refer to the Informix Guide to SQL Syntax SQL_NUMERIC_FUNCTIONS SQL_STRING_FUNCTIONS SQL_SYSTEM_FUNCTIONS SQL_TIMEDATE_ADD_INTERVALS SQL_TIMEDATE_DIFF_INTERVALS SQL_TIMEDATE_FUNCTIONS Information Type Descriptions The following table lists each information type alphabetically with its description Returns A character string m Y if the user can execute all procedures that SOLProcedures returns m N if procedures might be returned that the user cannot execute SQL_ACCESSIBLE_TABLES A character string a Y if the user is guaranteed SELECT privileges to all tables returned by SOLTables m N if tables might be returned that the user cannot access SOL_ACTIVE_CONNECTIONS A 16 bit integer value that specifies the maximum number of active connection handles that th
155. MoreResults function accepts the following argument Type Argument Use Description HSTMT hstmt Input Statement handle Return Codes SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_NO_DATA_FOUND SQL_ERROR or SQL_INVALID_HANDLE 12 230 INFORMIX CLI Programmer s Manual Diagnostics SQLMoreResults When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 S1000 S1001 S1008 S1010 S1T00 General warning General error Memory allocation failure Operation canceled Function sequence error Time out expired INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver was unable to allocate memory re
156. N keyword the driver manager retrieves the driver associated with the data source 2 Ifthe connection string does not contain the DSN keyword or the data source is not found the driver manager retrieves the driver associated with the default data source However the driver manager does not change the value of the DSN keyword in the connection string 3 Ifthe data source is not found and the Default data source is not found the driver manager returns SQL_ERROR with SQLSTATE IM002 Data source not found and no default driver specified Driver Guidelines The driver checks to see whether the connection string passed to it by the driver manager or the application contains the DSN or DRIVER keyword If the connection string contains the DRIVER keyword the driver cannot retrieve information about the data source If the connection string contains the DSN keyword or does not contain either the DSN or the DRIVER keyword the driver can retrieve information about the data source from the initial ization files as the following steps show 1 If the connection string contains the DSN keyword the driver retrieves the information for the specified data source 2 If the connection string does not contain the DSN keyword or the specified data source is not found the driver retrieves the infor mation for the default data source INFORMIX CLI Programmers Manual SQL DriverConnect The driver uses any information that it retrieves from
157. NFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The communication link between the driver and the data source failed before the function completed The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo was Y and less data was sent for a long parameter the data type was SQL_LONGVARCHAR SQL_LONGVARBINARY or a long data source specific data type than was specified with the pcbValue argument in SQLBindParameter An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function 1 of 2 INFORMIX CLI Function Reference 12 243 SQL ParamData 12 244 SQLSTATE Error S1008 Operation canceled S1010 Function sequence error S1T00 Time out expired Usage Code Example See SOLPutData INFORMIX CLI Programmers Manual Description The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application SOLExecute or SOLExecDirect was called for the hstmt and returned SQL_NEED_DATA SOLCancel was called before data was sent for all data at execution parameters or columns DM The previous function call was not a call to SOLExecDirect or SQLExecute
158. N_NAME columns an application can call SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SOL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SOL_MAX_COLUMN_NAME_LEN options Column Name TABLE_QUALIFIER Informix SQL Data Type VARCHAR 128 Comments Table qualifier identifier of the table to which the statistic or index applies NULL if not applicable to the data source If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have qualifiers TABLE_OWNER VARCHAR 128 Table owner identifier of the table to which the statistic or index applies NULL if not applicable to the data source If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have owners TABLE_NAME VARCHAR 128 not NULL Table identifier of the table to which the statistic or index applies NON_UNIQUE SMALLINT Indicates whether the index prohibits duplicate values m TRUE if the index values can be non unique m FALSE if the index values must be unique m NULL is returned if TYPE is SQL_TABLE_STAT 1 of 3 INFORMIX CLI Function Reference 12 315 SQL Statistics 12 316 Column Name INDEX_QUALIFIER Informix SQL Data Type VARCHAR 128 Comments
159. O An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause DM The driver manager did not allocate memory required to support execution or completion of the function 1 of 2 SQLDataSources SQLSTATE Error Description S1090 Invalid stringor DM The value specified for argument cbDSNMax buffer length was less than 0 DM The value specified for argument cbDescriptionMax was less than 0 1103 Direction option DM The value specified for the argument fDirection out of range was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT 2 of 2 Usage An application can call SQLDataSources multiple times to retrieve all data source names When no more data source names remain the function returns SQL_NO_DATA_FOUND If SOLDataSources is called with SOL_FETCH_NEXT immediately after it returns SOL_NO_DATA_FOUND it returns the first data source name If SQL_FETCH_NEXT is passed to SQLDataSources the first time that it is called it returns the first data source name INFORMIX CLI determines how data source names are mapped to actual data sources Related Functions For Information About See Discovering and listing values required to connect toa data SOLBrowseConnect source Connecting to a data source SOLConnect Connecting to a data source using a connection
160. O or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise INFORMIX CLI Function Reference 12 171 SQL GetData If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 01004 07006 08501 22002 22003 22005 22008 22012 12 172 General warning Data truncated Restricted data type attribute violation Communication link failure Indicator value required but not supplied Numeric value out of range Error in assignment Datetime field overflow Division by zero INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO All the data for the specified column icol could not be retrieved in a single call to the function The argument pcbValue contains the length of the data that remains in the specified column prior to the current call to SOLGetData function returns SOL_SUCCESS_WITH_INFO For more information on using multiple calls to SOLGetData for a single column see Usage on page 12 174 The data value cannot be converted
161. OM EMPLOYEE GROUP BY DEPT AGE SQL_IDENTIFIER_CASE A 16 bit integer value as follows m SQL_IC_UPPER Identifiers in SOL are case insensitive and are stored in uppercase in system catalog m SQL_IC_LOWER Identifiers in SOL are case insensitive and are stored in lowercase in system catalog m SQL_IC_SENSITIVE Identifiers in SOL are case sensitive and are stored in mixed case in system catalog m SQL_IC_MIXED Identifiers in SQL are case insensitive and are stored in mixed case in system catalog SQL_IDENTIFIER_QUOTE_CHAR The character string used as the starting and ending delimiter of a quoted delimited identifiers in SQL statements Identifiers passed as arguments to ODBC functions do not need to be quoted If the data source does not support quoted identifiers a blank is returned 10 of 24 12 202 INFORMIX CLI Programmer s Manual InfoType SQL_KEYWORDS SQLGetInfo Returns A character string that contains a comma separated list of all data source specific keywords This list does not contain keywords specific to ODBC or keywords used by both the data source and ODBC The define value SQL_ODBC_KEYWORDS contains a comma separated list of ODBC keywords SQL_LIKE_ESCAPE_CLAUSE A character string m Y if the data source supports an escape character for the percent character and underscore character _ in a LIKE predicate and the driver supports the ODBC syntax for defining a LIKE
162. Oh eB we a Ce ew wt OR ew BS 13 3 ConfigTranslator 6 ee o 13 7 13 2 INFORMIX CLI Programmers Manual his chapter describes the syntax of the driver setup shared library API which consists of the function ConfigDSN which can be in the driver shared library or in a separate setup shared library This chapter also describes the syntax of the translator setup shared library API which consists of the function ConfigTranslator which can be in the translator setup shared library or in a separate setup shared library For information on argument naming conventions see Arguments on page 12 4 ConfigDSN ConfigDSN adds modifies or deletes data sources It might prompt the user for connection information It can be in the driver shared library or a separate setup shared library Syntax BOOL ConfigDSN hwndParent fRequest IpszDriver lpszAttributes Setup Shared Library Function Reference 13 3 ConfigDSN The ConfigDSN function accepts the following arguments Type Argument Use Description HWND hwndParent Input Parent window handle The function will not display any dialog boxes if the handle is null UINT fRequest Input Type of request fRequest must contain one of the following values m ODBC_ADD_DSN Add a new data source m ODBC_CONFIG_DSN Configure modify an existing data source m ODBC_REMOVE_DSN Remove an existing data source LPCSTR IpszDriver Input Driver description usually the
163. P or xxSOCSPX where xx represents OL ON or SE The user s password for the database server The name of the Informix database server on which the database that you want to access resides The name assigned to the Informix database server process that runs on your UNIX computer Confirm the service name with your system administrator The user ID or account name for access to the data source Adding a Data Source To add a data source 1 Start the ODBC Administrator The Data Sources dialog box appears as Figure 2 1 illustrates Figura 2 1 Data Sources User Data Sources Driver M Gees Dialog Box Help Setup Delete Add Options System DSN Drivers 2 Click Add The Add Data Source dialog box appears as Figure 2 2 illustrates Eig ee Add Data Source Select which ODBC Driver you want to use OK Dialog Box from the list then choose OK Cancel Installed ODBC Drivers INFORMIX 2 80 Help 3 Select Informix 2 80 from the Installed ODBC Drivers list Configuring DataSources 2 5 Adding a Data Source 4 Click OK The INFORMIX CLI DSN Setup dialog box appears as Figure 2 3 illustrates INFORMIX CLI DSN Setup Figure 2 3 INFORMIX CLI DSN Change data source name description or options Setup Dialog Box Then Choose OK Note UID and PWD are Optional If specified PWD will be encrypted Data Source Name Database
164. Parameter Call InitUserData El Call GetUserData and SQLPutData repeatedly to get and put all data for the parameter Call SQLParamData to finish processing this parameter and start processing the next parameter ef while retcode SQL_NEED_DATA retcode SQLParamData hstmt amp pToken if retcode SQL_NEED_DATA InitUserData SWORD pToken InitValue while GetUserData InitValue SWORD pToken Data amp cbData INFORMIX CLI Function Reference 12 275 SQL PutData 12 276 SQLPutData hstmt Data cbData VOID InitUserData sParam InitValue SWORD sParam PTR InitValue UCHAR szPhotoFile MAX_FILE_NAME_LEN switch sParam case 3 Prompt user for bitmap file containing employee photo OpenPhotoFile opens the file and returns the file handle PromptPhotoFileName szPhotoFile OpenPhotoFile szPhotoFile FILE InitValue break BOOL GetUserData InitValue sParam Data cbData PTR InitValue SWORD sParam UCHAR Data SDWORD cbData switch sParam case l Prompt user for employee name PromptEmployeeName Data cbData SQL_NTS return TRUE case 3 GetNextPhotoData returns the next piece of photo data and the number of bytes of data returned up to MAX_DATA_LEN Done GetNextPhotoData FILE InitValue Data MAX_DATA_LEN amp cbData if Done ClosePhotoFile FILE InitValue return TRUE ret
165. Parameter SQLPrepare SQLExecDirect LBindParameter SQLExecute Kind of statement SELECT UPDATE DELETE statement or INSERT statement SQLNumResultCols SQLDescribeCol SQLBindCol SQLFetch L__ More rows SQLRowCount Yes No SQL FreeSimt SQL Transact If repeat If more processing Terminate 5 4 INFORMIX CLI Programmer s Manual Allocating a Statement Handle Allocating a Statement Handle Before your application can submit an SQL statement it must allocate a statement handle for the statement To allocate a statement handle an appli cation performs the following operations 1 Declares a variable of type HSTMT For example the application could use the following declaration HSTMT hstmtl 2 Calls SOLAllocStmt and passes it the address of the variable and the connection handle hdbc with which to associate the statement The driver allocates memory to store information about the statement associates the statement handle with the connection handle hdbc and returns the statement handle in the variable Executing an SQL Statement Your application can submit an SQL statement for execution in the following ways m Prepared statements call SOLPrepare and then call SOLExecute m Direct statements call SOLExecDirect These options are similar but not identical to the prepared and immediate options in embedded SQL For a comparison of the ODBC functions and embedded SQL see A
166. Performs the code set conversion Optional Default value INFORMIXDIR lib esql ig04a304 xx where xx represents a platform specific file extension output_option Varying multibyte character length Optional reporting option that specifies how to set pcbValue when rgbValue the output area is not large enough for the code set converted data Possible values m 0 Estimate m 1 Exact Default value 04 2 of 2 For more information about the GLS fields see GLS on page 1 11 Example The following example shows the configuration for a data source called Emplnfo LEmpInfo Driver informix lib cli iclis09a so Description Demo data source Database stores 7 UID admin PWD tiger Server ifmx_91 CLIENT_LOCALE en_us 8859 1 DB_LOCALE de_de 646de TRANSLATIONDLL opt informix lib esql igo4a304 so VMBCHARLENEXACT 0 Configuring DataSources 2 13 File Format for odbcinst ini File Format for odbcinst ini The following table describes the sections in the odbcinst ini file Section Description Status ODBC Drivers Lists the INFORMIX CLI driver Required Driver Specification Describes the INFORMIX CLI driver Required Default Driver Specifies the driver to use when none is Required Specification specified The default driver is the INFORMIX CLI driver ODBC Translators Lists each available translator Required Translator Specification Each translator listed in the ODBC Trans Required lators
167. QL statement In the case of a cursor specification the call corresponds to static SQL DECLARE CURSOR and OPEN statements SQLNumResultCols GET DESCRIPTOR COUNT form of dynamic SQL GET DESCRIPTOR SOLColAttributes GET DESCRIPTOR COUNT form of dynamic SQL GET DESCRIPTOR or VALUE form of dynamic SQL GET DESCRIPTOR with field name in NAME TYPE LENGTH PRECISION SCALE NULLABLE SOLDescribeCol GET DESCRIPTOR VALUE form of dynamic SQL GET DESCRIPTOR with field name in NAME TYPE LENGTH PRECISION SCALE NULLABLE SOLBindCol none This function establishes output buffers that correspond in usage to host variables for static SOL FETCH and to an SOL DESCRIPTOR for dynamic SOL FETCH cursor USING SQL DESCRIPTOR descriptor 2 of 3 Comparison of INFORMIX CLI and Embedded SAL C 3 INFORMIX CLI to Embedded SQL INFORMIX CLI Function SQLFetch SQLRowCount SQLFreeStmt SQL_CLOSE option SQLFreeStmt SQL_DROP option SQLTransact SQLDisconnect SQLFreeConnect SQLFreeEnv SQLCancel SQLError INFORMIX CLI Programmers Manual Embedded SQL Statement FETCH GET DIAGNOSTICS CLOSE none COMMIT WORK or COMMIT ROLLBACK DISCONNECT none none none GET DIAGNOSTICS Comments Static or dynamic SQL FETCH If the call is a dynamic SQL FETCH then the VALUE form of GET DESCRIPTOR is used with field name in DATA INDICATOR DATA and INDICATOR values are placed in output buffers specifi
168. QLDataSources SQLDescribeCol SQLDriverConnect SQLDrivers SQLExecDirect SQLExecute SQLForeignKeys SOLGetCursorName SOLGetData SOLGetInfo SOLNativeSql SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SOLPutData SQLSetCursorName SQLSpecialColumns SQOLStatistics SQLTablePrivileges SQLTables SQLColAttributes 10 of 13 INFORMIX CLI Error Codes A 11 SQLSTATE Values 1092 1093 1094 1095 S1096 S1097 S1098 S1099 S1100 S1101 S1103 S1104 S1105 S1106 S1107 S1108 S1109 S1110 SQL STATE Error Option type out of range Invalid parameter number Invalid scale value Function type out of range Information type out of range Column type out of range Scope type out of range Nullable type out of range Uniqueness option type out of range Accuracy option type out of range Direction option out of range Invalid precision value Invalid parameter type Fetch type out of range Row value out of range Concurrency option out of range Invalid cursor position Invalid driver completion A 12 INFORMIX CLI Programmers Manual Can be returned from SQLFreeStmt SQLGetConnectOption SQLGetStmtOption SQLSetConnectOption SQLSetStmtOption SQLBindParameter SQLBindParameter SQLGetFunctions SQLGetInfo SQLSpecialColumns SQLSpecialColumns SQLSpecialColumns SQLStatistics SQLStatistics SQLDataSources SQLDrivers SQLBindParameter SQLBindParameter SQLExtendedFetch SQLExtendedFetch SQLP
169. QL_C_DOUBLE None Data Size of the C N A SQL_C_FLOAT data type SQL_C_LONG SQL_C_SHORT SQL_C_SLONG SQL_C_SSHORT SQL_C_STINYINT SQL_C_TINYINT SQL_C_ULONG SQL_C_USHORT SQL_C_UTINYINT SQL_C_BIT None gt Data 1 N A SQL_C_BINARY cbValueMax gt 1 Data 1 N A cbValueMax lt 1 Untouched Untouched 22003 b The value of cbValueMax is ignored for this conversion The driver assumes that the size of rgbValue is the size of the C data type This is the size of the corresponding C data type When bit SQL data is converted to character C data the possible values are Oand1 B 26 INFORMIX CLI Programmers Manual Converting Data from SQL to C SQL to C Binary The binary INFORMIX CLI SQL data type is SOL_LONGVARBINARY The following table shows the INFORMIX CLI C data types to which binary SQL data can be converted fCType Test rgbValue pcbValue SQLSTATE SQL_C_CHAR Length of data 2 lt Data Length of N A cbValueMax data Length of data 2 gt Truncated data Length of 01004 cbValueMax data SQL_C_BINARY Length of data lt Data Length of N A cbValueMax data Length of data gt Truncated data Length of 01004 cbValueMax data When binary SQL data is converted to character C data each byte 8 bits of source data is represented as two ASCII characters These characters are the ASCII character representation of the number in its hexadecimal form For example a binary 00000001 is converted to 01
170. R UT SQL_C_CHAR SQL_VARCHAR EXEC SQL DECLARE cl CURSOR FOR SELECT ID NAME FROM NAMEID EXEC Show Exec SQL OPEN cl E the use of the SQLExecDirect method Ef ute the selection Note that the application does not declare a cursor Istrcpy select SELECT ID NAME FROM NAMEID if SQLExecDirect hstmt sele EXEC SQL FETCH cl INTO id Bind the columns of the result set with SQLBindCol Fetc h the first row SQLBindCol hstmt 1 SQL_C_SL SQLBindCol hstmt 2 SQL_C_CH SQLFetc h hstmt EXEC SQL COMMIT WORK at A Commit the transaction ct SQL_NTS return print_err hdbc hstmt Name ONG amp id O SQL_SUCCESS El xi NULL AR name SDWORD sizeof name amp namelen Constructing an INFORMIX CLI Application 9 5 Static SQL Example 9 6 SQLTransact hdbc SQL_COMMIT FF EXEC SOL CLOSE els Ef Free the statement handle SQLFreeStmt hstmt SQL DROP EXEC SQL DISCONNECT Disconnect from the data source Free the connection handle Free the environment handle SQLDisconnect hdbc SQLFreeConnect hdbc SQLFreeEnv henv return 0 INFORMIX CLI Programmers Manual EI Kf d Interactive Ad Hoc Query Example Interactive Ad Hoc Query Example The following example illustrates how an application can determine the nature of the result set before it retrieves results
171. RMIX CLI uses driver INFORMIX CLI Informix data source DBMS including N database server Database Operating system and network software a y 1 6 INFORMIX CLI Programmers Manual Advantages of Using INFORMIX CL What Is a Data Source A data source consists of the following parts A database management system DBMS including a database server A database The operating system and network software necessary for accessing the database Advantages of Using INFORMIX CLI INFORMIX CLI has the following advantages It lets you develop applications that connect to and disconnect from data sources retrieve information about data sources retrieve information about INFORMIX CLI set and retrieve INFORMIX CLI options prepare and send SQL statements retrieve SQL results and process the results dynamically O oO O O DO UO O retrieve information about SQL results and process the infor mation dynamically It is straightforward for application developers who are familiar with function libraries It does not use a preprocessor It lets you allocate storage for results before or after the results are available This feature lets you determine the results and the action to take without the limitations that predefined data structures impose Overview of INFORMIX CLI 1 7 Isolation and Lock Levels UNIX Isolation and Lock Levels If an INFORMIX CLI application is c
172. ResultCols SQLPrepare INFORMIX CLI Function Reference 12 143 SQL ForeignKeys 12 144 SQLForeignKeys the specified table Syntax cbPkTableQualifier szPkTableName cbFkTableQualifier szFkTableName Type Argument Use RETCODE SOLForeignKeys hstmt szPkTableOwner cbPkTableName szFkTableOwner cbFkTableName SQLForeignKeys can return either of the following items m A list of foreign keys in the specified table columns in the specified table that refer to primary keys in other tables m A list of foreign keys in other tables that refer to the primary key in The driver returns each list as a result set on the specified hstmt szPkTableQualifier cbPkTableOwner szFkTableQualifier cbFkTableOwner The SQLForeignKeys function accepts the following arguments Description HSTMT hstmt Input UCHARFAR szPkTableQualifier Input SWORD cbPkTableQualifier Input UCHARFAR szPkTableOwner Input SWORD cbPkTableOwner Input INFORMIX CLI Programmers Manual Statement handle Primary key table qualifier If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have qualifiers Length of szPkTableQualifier Primary key owner name If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string
173. SOLExtendedFetch SQLSetConnectOption SOLSetStmtOption SOLExecDirect SQLExecute SQLExecDirect SQLExecute SQLExecDirect SQLExecute 1 of 13 SQL STATE Error 07006 08001 08002 08003 08004 08007 Restricted data type attribute violation Unable to connect to data source Connection in use Connection not open Data source rejected establishment of connection Connection failure during transaction SQLSTATE Values Can be returned from SQLBindParameter SQLExtendedFetch SQLFetch SQLGetData SQLBrowseConnect SQLConnect SOLDriverConnect SQLBrowseConnect SQLConnect SOLDriverConnect SQLSetConnectOption SOLAllocStmt SQLDisconnect SQLGetConnectOption SOLGetInfo SOLNativeSql SQLSetConnectOption SQLTransact SQLBrowseConnect SQLConnect SOLDriverConnect SQLTransact 2 of 13 INFORMIX CLI Error Codes A 3 SQLSTATE Values A 4 SQL STATE 08501 21501 21502 22001 22002 INFORMIX CLI Programmers Manual Error Communication link failure Insert value list does not match column list Degree of derived table does not match column list String data right truncation Indicator variable required but not supplied Can be returned from SQLBrowseConnect SQLColumnPrivileges SOLColumns SQLConnect SQLDriverConnect SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SQLForeignKeys SQLFreeConnect SOLGetData SOLGetTypelnfo SOLParamData SQLPrepare SQLPrimaryKeys
174. SQLDescribeCol SQLExtendedFetch SOLFetch SQLFreeStmt SQLGetData SOLNumResultCols SQLBindParameter SQLBindParameter SQLBindParameter binds a buffer to a parameter marker in an SQL statement Syntax RETCODE SQLBIND hstmt ipar fParamType fCType fSqiType cbColDef ibScale rgbValue cbValueMax pcbValue The SOLBindParameter function accepts the following arguments Typedef Argument Use Description HSTMT hstmt Input Statement handle UWORD ipar Input Parameter number ordered sequentially left to right starting at 1 SWORD fParamType Input The type of the parameter For more infor mation see fParamType Argument on page 12 29 SWORD fCType Input The INFORMIX CLI C data type of the result data The possible values are any of the fCType values listed in Appendix B Data Types as well as SQL_C_DEFAULT For more information about data types and conversions see Appendix B SWORD fSqlType Input The INFORMIX CLI SQL data type of the parameter The possible values are any of the fSqlType values listed in Appendix B For more information about data types and conversions see Appendix B UDWORD cbColDef Input The precision of the column or expression of the corresponding parameter marker For more information see cbColDef Argument on page 12 30 1 of 2 INFORMIX CLI Function Reference 12 25 SQL BindParameter 12 26 Typedef Argument Use SWORD ibScale Input PTR rebValue Input
175. SQLExecDirect 12 115 SQLExecute 12 121 SQLTransact 12 333 support of 12 215 two phase commit 12 333 Transferring binary data B 13 Transitions state See State transitions Translation libraries described 1 12 12 289 function summary 11 11 options default 13 7 described 1 12 12 289 setup ConfigTranslator 13 3 TRANSLATIONDLL 1 12 2 12 TRANSLATION_OPTION 1 12 Truncating data maximum data length 12 301 output buffers 3 10 SQLBindCol 12 21 SQLBindParameter 12 31 SQLFetch 12 142 SQLGetData 12 175 See also Binary data Character data 12 INFORMIX CLI Programmer s Manual Two phase commit 12 333 Typedefs DATE_STRUCT B 11 SCHAR B 11 SDOUBLE B 10 SDWORD B 10 SFLOAT B 10 SWORD B 10 TIMESTAMP_STRUCT B 11 UCHAR B 11 UDWORD B 11 UWORD B 11 U UCHAR typedef B 11 UDWORD typedef B 11 UID 2 4 2 12 Unbinding columns 12 22 UNION clauses 12 216 Unloading drivers 12 79 Update rules 12 149 UPDATE statements affected rows 12 278 cascade update 12 149 privileges 12 66 qualifier usage in 12 210 restrictive update 12 149 Updates positioned See Positioned UPDATE statements User names maximum length 12 205 retrieving 12 216 UWORD typedef B 11 V VARCHAR data type B 3 Version DBMS 12 197 driver 12 199 ODEC supported 12 199 Version compatibility information types 12 188 number of input parameters 12 267 number of output parameters 12 267 number of result sets 12 267 SQLBindParameter 12 180 SQLSetParam 12 180
176. SQLGetData 12 170 SQL to C B 19 SQLExtendedFetch 12 127 SQLFetch 12 21 SQLGetData 12 175 Core API 3 4 Correlation names 12 195 CREATE statements 4 10 CREATE TABLE statements interoperability 5 4 modifying syntax 5 3 NOT NULL clauses 12 205 Currency columns 12 57 data types 12 227 Current qualifier 12 285 Cursor position errors 12 132 required 6 12 12 176 SQLExtendedFetch 6 11 12 133 SQLFetch 12 141 Cursor stability 12 285 Cursors block 6 9 closing cursors SQLCancel 12 50 SQLFreeStmt 8 3 described 6 6 dynamic 6 10 getting names 12 169 holes in 12 213 key set driven 6 10 maximum name length 12 204 positioned statements 6 12 position See Cursor position scrollable 6 10 sensitivity 12 213 setting names 12 292 simulated 12 307 specifying type 6 11 static 6 10 supported types 12 211 transaction behavior 12 333 See also Concurrency Cursor library D Data converting See Converting data long See Long data values retrieving See Retrieving data transferring in binary form B 13 truncating See Truncating data Data Definition Language DDL in embedded SQL C 5 Data Manipulation Language DML in embedded SQL C 6 qualifier usage in 12 210 data source specification 2 12 Data sources adding 13 5 configuring 13 6 configuring on UNIX 2 9 configuring on Windows 2 3 default 4 5 definition 1 7 deleting 13 6 information types 12 190 listing 12 85 names 12 197 read only 12 197 Data types See C data types
177. SQL_NTS Primary NULL 0 Foreign NULL 0 Foreign NULL 0 Foreign while retcode SQL_SUCCESS retcode INFORMIX CLI Programmers Manual SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO Key Seq hd n szPkCol ikKeySeq primary key qualifier owner table qualifier owner table EI kpi el sl KI A sl eL SQL_SUCCESS_WITH_INFO SQLForeignKeys Fetch and display the result set This will be all of the foreign keys in other tables that refer to the SALES ORDER primary key f retcode SQLFetch hstmt if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO fprintf out s s lt s s Jin szPkTable szPkCol szFkTable szFkCol Close the cursor the hstmt is still allocated Ef SQLFreeStmt hstmt SOL CLOSE Get all the foreign keys in the SALES ORDER table Xp retcode SQLForeignKeys hstmt NULL 0 Primary qualifier ay NULL 0 Primary owner aa NULL 0 Primary table ef NULL 0 Foreign qualifier g NULL 0 Foreign owner ay szTable SQL_NTS Foreign table while retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO Fetch and display the result set This will be all of the ay primary keys in other tables that are referred to by foreign keys in the SALES ORDER table ef retcode SQLFetch hstmt if retcode SQL_SUCCESS retcode SQL_SUCCESS_WIT
178. See SQLGetConnectOption SOLGetFunctions SOLGetStmtOption SOLGetTypelnfo INFORMIX CLI Function Reference 12 217 SQL GetStmtOption 12 218 Syntax Type Argument HSTMT hstmt UWORD fOption PTR poParam SQL_GET_ROWID SQL GET_SERIAL _VALUE Return Codes SOL_INVALID_ HANDLE INFORMIX CLI Programmers Manual SQLGetStmtOption SOLGetStmtOption returns the current setting of a statement option RETCODE SQLGetStmtOption hstmt Use Input Input Output Output Output fOption pvParam The SQLGetStmtOption function accepts the following arguments Description Statement handle Option to retrieve Value associated with fOption Depending on the value of fOption a 32 bit integer value or a pointer to a null terminated character string will be returned in poParam Returns the row ID of the last row inserted returns 0 if the last SQL operation was not Insert Returns the serial ID of the last row inserted returns 0 if the last SQL operation was not Insert SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or Diagnostics SQL GetStmtOption When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE
179. StmtOption to Reduce the Size of Data Retrieved When you retrieve long data your result set can be huge To reduce the size of the result set data to a manageable level call SOLSetStmtOption with the SQL_MAX_LENGTH option The SOL_MAX_LENGTH option reduces network traffic and improves perfor mance by allowing the driver to communicate to the database server that only n bytes of data are pertinent to the client The database server responds by sending only the first n bytes of data for all result columns A common assumption among application developers is that if an appli cation calls SOLGetData with a container of size x then the driver retrieves only x bytes of information from the server On the contrary because an application can call SQLGetData multiple times for any one column the INFORMIX CLI driver retrieves long data in large chunks to optimize network use it then returns the long data to the user upon request The following code example illustrates the impact on performance char CaseContainer 1000 rc SQLExecDirect hstmt SELECT CaseHistory FROM Cases WHERE CaseNo 71164 SQL_NTS rc SQLFetch hstmt re SQLGetData hstmt 1 CaseContainer SWORD sizeof CaseContainer At this point the driver is more likely to retrieve 64 kilobytes of information from the server instead of 1000 bytes In terms of network access one 64 kilobytes retrieval is less expensive than sixty four 1000 byte retrievals
180. Str violated restrictions defined by the data source DM The data source name specified in the argument szDSN was not found nor was there a default driver specification DM The odbc ini file was not found DM The driver listed in the data source specification in the odbc ini file was not found or could not be loaded for some other reason DM During SQLConnect the driver manager called the driver SOLAllocEnv function and the driver returned an error 1 of 2 INFORMIX CLI Function Reference 12 77 SQLConnect SQLSTATE Error IM005 IM006 IM009 S1000 1001 S1090 S1T00 12 78 Driver SQLAllocConnect failed Driver SQLSetConnectOption failed Unable to load trans lation shared library General error Memory allocation failure Invalid string or buffer length Time out expired Description DM During SOLConnect the driver manager called the driver SQLAllocConnect function and the driver returned an error DM During SOLConnect the driver manager called the driver SQLSetConnectOption function and the driver returned an error function returns SQL_SUCCESS_WITH_INFO The driver did not load the translation shared library that was specified for the data source An error occurred for which no specific SOLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its c
181. TA SOL_DATA_AT_EXEC or the result of the SOL LEN_DATA_AT EXEC macro After the statement executes the driver returns data for the parameter to the application if the data source does not return a value for an input output parameter the driver sets the pcb Value buffer to SOL_NULL_DATA If an application calls SQLSetParam the driver manager converts this to a call to SOLBindParameter in which the fParamType argument is set to SQL_PARAM_INPUT_OUTPUT m SQL _PARAM_OUTPUT The parameter marks the return value of a procedure or an output parameter in a procedure these are collectively known as output parameters For example the parameter in call GetNextEmpID is an output parameter that returns the next employee ID After the statement executes the driver returns data for the parameter to the application unless the rgbValue and pcbValue arguments are both null pointers in which case the driver discards the output value If the data source does not return a value for an output parameter the driver sets the pcbValue buffer to SOL_NULL_DATA cbColDef Argument The cbColDef argument specifies the precision of the column or expression that corresponds to the parameter marker unless all of the following condi tions are true m An application calls SOLSetParam The driver manager converts these calls to SOLBindParameter m The fSqlType argument is SOL_LONGVARBINARY or SOL_LONGVARCHAR m The data for the parameter is sent
182. TATE Values IM009 IM010 IM011 IM012 IM013 S0001 S0002 S0011 S0012 S0021 S0022 S1000 S1001 A 8 INFORMIX CLI Programmers Manual SQL STATE Error Unable to load translation shared library Data source name too long Driver name too long DRIVER keyword syntax error Trace file error Base table or view already exists Base table not found Index already exists Index not found Column already exists Column not found General error Memory allocation failure Can be returned from SQLBrowseConnect SQLConnect SQLDriverConnect SQLSetConnectOption SQLBrowseConnect SQLDriverConnect SQLBrowseConnect SQLDriverConnect SQLBrowseConnect SQLDriverConnect All functions SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare All functions except SOLAllocEnv SQLError All functions except SQLError SQLFreeConnect SQLFreeEnv 7 of 13 SQL STATE 1002 1003 1004 S1009 Error Invalid column number Program type out of range SQL data type out of range Invalid argument value SQLSTATE Values Can be returned from SQLBindCol SQLColAttributes SQLDescribeCol SQLExtendedFetch SOLFetch SOLGetData SOLBindCol SOLBindParameter SQLGetData SQLBindParameter SQLGetTypelInfo SOLAllocConnect SOLAllocStmt SOLBindCol SOLBindPar
183. TATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source failed before the function completed 24000 Invalid cursor state A cursor was already opened on the statement handle S1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause 1001 Memory allocation The driver did not allocate memory required to failure support execution or completion of the function S1008 Operation canceled The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multithreaded application 1 of 2 12 326 INFORMIX CLI Programmer s Manual SQLSTATE Error S1010 Function sequence error S1090 Invalid string or buffer length S1C00 Driver not capable S1T00 Time out expired Usage SQL Tables Description DM SOLExecute or SOLExecDirect was called for the hstmt and returned SOL_NEED_DATA This function was calle
184. Ta bleName were both null pointers 1 of 2 SQLForeignKeys SQLSTATE Error Description S1010 Function sequence DM SQLExecute or SQLExecDirect was called error for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns S1090 Invalid string or DM The value of one of the name length buffer length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corre sponding qualifier or name see Comments S1C00 Driver not capable A table qualifier was specified and the driver or data source does not support qualifiers A table owner was specified and the driver or data source does not support owners The drive or data source did not support the combination of the current settings of the SOL_CONCURRENCY and SOL_CURSOR_TYPE statement options S1T00 Timeout expired The timeout period expired before the data source returned the result set The timeout period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 Comments If szPkTableName contains a table name SQLForeignKeys returns a result set containing the primary key of the specified table and all of the foreign keys that refer to it If szFkTableName contains a table name SOLForeignKeys returns a result set containing all of the foreign keys in the specified table and the primary keys in other
185. The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 01004 Data truncated The argument szSq Str contained an SQL statement that contained a character or binary parameter or literal and the value exceeded the maximum length of the associated table column The argument szSq Str contained an SQL statement that contained a numeric parameter or literal and the fractional part of the value was truncated The argument szSqlStr contained an SQL statement that contained a date or time parameter or literal and a time stamp value was truncated 01006 Privilege not The argument szSq Str contained a REVOKE statement and the user did revoked not have the specified privilege function returns SQL_SUCCESS_WITH_INFO 01S03 No rows updated The argument szSq Str contained a positioned UPDATE or DELETE or deleted statement and no rows were updated or deleted function returns SQL_SUCCESS_WITH_INFO 01S04 More than one row The argument szSq Str contained a positioned UPDATE or DELETE updated or de
186. Type SQL_STATIC_SENSITIVITY SQLGetInfo Returns A 32 bit bitmask that enumerates whether changes made by an application to a static or key set driven cursor through positioned update or delete statements can be detected by that application m SQL_SS_ADDITIONS Added rows are visible to the cursor the cursor can scroll to these rows Where these rows are added to the cursor is driver dependent m SQL_SS_DELETIONS Deleted rows are no longer available to the cursor and do not leave a hole in the result set after the cursor scrolls from a deleted row it cannot return to that row m SQL_SS_UPDATES Updates to rows are visible to the cursor if the cursor scrolls from and returns to an updated row the data returned by the cursor is the updated data not the original data Because updating key values ina key set driven cursor is considered to be deleting the existing row and adding a new row this value is always returned for key set driven cursors Whether an application can detect changes made to the result set by other users including other cursors in the same application depends on the cursor type For more information see Scrol lable Cursors on page 6 10 SQL_SYSTEM_FUNCTIONS A 32 bit bitmask that enumerates the scalar system functions supported by the driver and associated data source The following bitmasks are used to determine which system functions are supported SQL_FN_SYS_DBNAME SQL_FN_S
187. UCCESS_WITH_INFO Consider a situation in which the query returns 90 result rows In Case 1 the number of ODBC calls made is greater than 1 890 20 calls to SOLGetData x 90 result rows 91 calls to SQLFetch In Case 2 the number of ODBC calls made is reduced to about 110 20 calls to SOLBindCol 91 calls to SQLFetch Clearly the use of SQLBindCol can improve performance Another reason to use SOLBindCol is that many drivers optimize use of SQLBindCol by binding result information directly from the data source into the user s buffer That is instead of the driver retrieving information into a container and then copying that information to the user s buffer the driver simply requests that the information from the database server be placed directly into the user s buffer Designing Performance Oriented Applications 10 9 Using SQLExtendedFetch Versus SQLFetch 10 10 Using SQLExtendedFetch Versus SQLFetch Use SOLExtendedFetch instead of SOLFetch to retrieve data The ODBC call load decreases resulting in better performance and the code is less complex resulting in more maintainable code Consider the preceding SQLBindCol example The following code example uses SQLExtendedFetch instead of SQLFetch rc SQLSetStmtOption hstmt SQL_ROWSET_SIZE 100 use arrays of 100 elements re SQLExecDirect hstmt SELECT lt 20 columns gt FROM Employees WHERE HireDate gt SQL_NTS call SQLBindCol 1 time
188. UCHAR FAR szTableName Input Table name SWORD cbTableName Input Length of szTableName 1 of 2 INFORMIX CLI Function Reference 12 311 SQL Statistics 12 312 Typedef Argument UWORD fUnique UWORD fAccuracy Return Codes Diagnostics INFORMIX CLI Programmer s Manual Use Input Input Description Type of index SQL_INDEX_UNIQUE or SQL_INDEX_ALL The importance of the CARDINALITY and PAGES columns in the result set m SQL_ENSURE requests that the driver unconditionally retrieve the statistics m SQL_QUICK requests that the driver retrieve results only if they are readily available from the server In this case the driver does not ensure that the values are current 2 of 2 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise SQL Statistics If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error 01000 08S01 24000 S1000 S1001
189. UMN_NAME GRANTOR and GRANTEE The following table lists the columns in the result Important SQLColumnPrivileges might not return all columns For example the driver might not return information about pseudocolumns such as Informix ROWID Applications can use any valid column regardless of whether it is returned SQL ColumnPrivileges The lengths of VARCHAR columns shown in the table are maximums the actual lengths depend on the data source To determine the actual lengths of the TABLE_QUALIFIER TABLE_OWNER TABLE_NAME and COLUMN_NAME columns an application can call SOLGetInfo with the SOL_MAX_QUALIFIER_NAME_LEN SOL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SOL_MAX_COLUMN_NAME_LEN options Column Name Data Type TABLE_QUALIFIER VARCHAR 128 TABLE_OWNER VARCHAR 128 TABLE_NAME VARCHAR 128 not NULL COLUMN_NAME VARCHAR 128 not NULL GRANTOR VARCHAR 128 Comments Table qualifier identifier NULL if not appli cable to the data source If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different data sources it returns an empty string for those tables that do not have qualifiers Table owner identifier NULL if not applicable to the data source If a driver supports owners for some tables but not for others such as when the driver retrieves data from different data sources it returns an empty string for those tables that do n
190. Versioning isolation level 12 198 VIEW table type 12 329 Views 12 7 VMB character 1 13 VMBCHARLENEXACT 1 13 2 12 W Window handles quiet mode 12 287 See also SQLDriverConnect Windows NT registry data sources adding 13 5 configuring 13 6 removing 13 6
191. WVER and vice versa For SQL_CONCUR_LOCK the driver substitutes in order SQL_CONCUR_ROWVER or SQL_CONCUR_VALUES 2 of 4 12 300 INFORMIX CLI Programmer s Manual fOption SQL_CURSOR_TYPE SQL SetStmtOption vParam Contents A 32 bit integer value that specifies the cursor type m SQL_CURSOR_FORWARD_ONLY The cursor only scrolls forward m SQL_CURSOR_STATIC The data in the result set is static m SQL_CURSOR_KEYSET_DRIVEN The driver saves and uses the keys for the number of rows specified in the SQL_KEYSET_SIZE statement option m SQL_CURSOR_DYNAMIC The driver only saves and uses the keys for the rows in the row set The default value is SQL_CURSOR_FORWARD_ONLY This option cannot be specified for an open cursor and can also be set through the crowKeyset argument in SOLSetScrollOptions If the data source does not support the specified cursor type the driver substitutes a different cursor type and returns SOLSTATE 01502 Option value changed For a mixed or dynamic cursor the driver substitutes a key set driven cursor A key set driven cursor is always set to zero SOL_KEYSET_SIZE UNSUPPORTED A 32 bit integer value that specifies the number of rows in the key set for a key set driven cursor The key set size is 0 and cannot be changed If the specified size exceeds the maximum key set size the driver substitutes that size and returns SQLSTATE 01502 Option value changed SQLExtendedFetch returns an e
192. X CLI Programmers Manual A description of the procedure column 3 of 3 SQLProcedureColumns Related Functions For Information About See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SOLCancel Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SOLFetch Returning a list of procedures in a data source SOLProcedures INFORMIX CLI Function Reference 12 263 SQL Procedures SQLProcedures SQLProcedures returns the list of procedure names stored in a specific data source Procedure is a generic term used to describe an executable object or a named entity that can be invoked using input and output parameters and which can return result sets similar to the results that SELECT statements return Syntax RETCODE SQLProcedures hstmt szProcQualifier cbProcQualifier szProcOwner cbProcOwner szProcName cbProcName The SOLProcedures function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szProcQualifier Input Procedure qualifier If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have qualifiers SWORD cbProcQualifier Input Length of szProcQualifier UCHAR FAR szProcOwner Input String search pattern for procedure owner names If a
193. X CLI SQL data type The possible values are any of the fSqlType values listed in Appendix B Data Types If the data type cannot be determined the driver returns 0 For more information about data types and conversions see Appendix B UDWORDFAR pcbColDef Output The precision of the column on the data source If the precision cannot be determined the driver returns 0 For more information on precision see Precision Scale Length and Display Size on page B 5 SWORD FAR pibScale Output The scale of the column on the data source If the scale cannot be deter mined or is not applicable the driver returns 0 For more information on scale see Precision Scale Length and Display Size on page B 5 SWORD FAR pfNullable Output Indicates whether the column allows one of the following values m SOL_NO_NULLS The column does not allow null values m SOL_NULLABLE The column allows null values m SQL_NULLABLE_UNKNOWN The driver cannot determine whether the column allows null values 2 of 2 Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 12 87 SQL DescribeCol 12 88 Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE
194. YPE_ pfDesc Extended type alignment ALIGNMENT GNMEN If the column is of a built in data type the function returns 0 SQL_INFX_ATTR_EXTENDED_TYPE_CODE pfDesc Extended type ID The database server assigns a unique extended ID to each UDT If the column is of a built in data type the function returns 0 SQL_INFX_ATTR_EXTENDED_TYPE_NAME rgbDesc Extended type name For example if a column is of type circle where circle is a UDT then circle is returned If the column is of a built in data type the function returns an empty string SQL_INFX_ATTR_EXTENDED_TYPE_OWNER rgbDesc Extended type owner name For example if the column is a UDT of type circle and the owner of the circle type is cliuser then the function returns cliuser If the column is of a built in data type the function returns an empty string SQL_INFX_ATTR_SOURCE_TYPE_CODE pfDesc Source type of DISTINCT type columns If the column is of a built in data type or an OPAQUE data type the function returns 0 12 60 INFORMIX CLI Programmer s Manual Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Returning information about a column in a result set Fetching a block of data or scrolling through a result set Fetching a row of data SQLColAttributes See SOLBindCol SOLCancel SQLDescribeCol SQLExtendedFetch SQLFetch INFORMIX CLI Function Reference 12 61 SQL ColumnPrivileges
195. YS_IFNULL SQL_FN_SYS_USERNAME SQL_TABLE_TERM A character string with the data source vendor name for a table for example table or file 21 of 24 INFORMIX CLI Function Reference 12 213 SQL Getinfo InfoType SQL_TIMEDATE_ADD_INTERVALS Returns A 32 bit bitmask that enumerates the time stamp intervals supported by the driver and associated data source for the TIMESTAMPADD scalar function The following bitmasks are used to determine which intervals are supported SOL_FN_TSI_FRAC_SECOND SOL_FN_TSI_SECOND SOL_FN_TSI_MINUTE SOL_FN_TSI_HOUR SOL_FN_TSI_DAY SOL_FN_TSI_WEEK SQL_FN_TSI_LMONTH SOL_FN_TSI_QUARTER SOL_FN_TSI_YEAR SQL_TIMEDATE_DIFF_INTERVALS 12 214 INFORMIX CLI Programmers Manual A 32 bit bitmask that enumerates the time stamp intervals supported by the driver and associated data source for the TIMESTAMPDIFF scalar function The following bitmasks are used to determine which intervals are supported SOL_FN_TSI_FRAC_SECOND SOL_FN_TSI_SECOND SOL_FN_TSI_MINUTE SOL_FN_TSI_HOUR SOL_FN_TSI_DAY SOL_FN_TSI_WEEK SQL_FN_TSI_LMONTH SOL_FN_TSI_QUARTER SOL_FN_TSI_YEAR 22 of 24 SQLGetInfo InfoType Returns SQL_TIMEDATE_FUNCTIONS A 32 bit bitmask that enumerates the scalar date and time functions supported by the driver and associated data source The following bitmasks are used to determine which date and time functions are supported SQL_FN_TD_CURDATE SQL_
196. _INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise INFORMIX CLI Function Reference 12 239 SQLNumResultCols 12 240 SQLSTATE Error 01000 General warning 1000 General error S1001 Memory allocation failure S1008 Operation canceled S1010 Function sequence error S1T00 Time out expired INFORMIX CLI Programmers Manual If you are not using a driver manager the driver returns the SOLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver was unable to allocate memory required to support execution or completion of the function The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application DM The function was called prior to calling SQLPrepare or SOLExecDire
197. _SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE 12 246 INFORMIX CLI Programmers Manual Diagnostics SQLPrepare When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 08S01 21501 21502 22005 24000 34000 General warning Communication link failure Insert value list does not match column list Degree of derived table does not match column list Error in assignment Invalid cursor state Invalid cursor name INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The communication link between the driver and the data source failed before the function completed The argument szSq Str contained an INSERT statement and the number of values to be inserted did not match the degree of the derived table The argument szSqlStr contained a CREATE VIEW statement and the number of names spe
198. a type B 11 SQL_C_ULONG data type B 11 SQL_C_USHORT data type B 11 SQL_C_UTINYINT data type B 11 SQL_DATE data type B 2 SQL_DECIMAL data type B 2 SQL_DOUBLE data type B 2 SQL_ERROR 7 3 SQL_INFX_UDT_FIXED data type B 4 SQL_INFX_UDT_VARYING data type B 4 SQL_INTEGER data type B 2 SOL_INVALID_HANDLE 7 3 SQL_LONGVARBINARY data type B 2 SQL_LONGVARCHAR data type B 3 B 4 SQL_NEED_DATA 7 3 SQL_NO_DATA_FOUND 7 3 SQL_REAL data type B 3 SQL_SMALLINT data type B 3 SQL_STILL_EXECUTING 7 3 SQL_SUCCESS 7 3 SQL_SUCCESS_WITH_INFO 7 3 SQL_TIMESTAMP data type B 2 SOL_VARCHAR data type B 2 Statement handles active 12 194 allocating 5 5 defined 3 11 freeing 8 3 SQLAIlocStmt 12 15 SQLFreeStmt 12 161 Statement options binding type 12 299 concurrency 6 11 cursor type 12 301 driver specific 12 299 maximum data length 12 301 maximum length 12 220 12 299 maximum rows 12 302 releasing 12 298 reserved 12 299 retrieving 12 220 retrieving data 12 302 setting 12 298 substituting values 12 298 Static cursors described 6 10 sensitivity 12 213 Static SQL 9 4 Statistics listing 12 314 Status array errors 12 131 SQLExtendedFetch 12 134 Status information retrieving 7 8 See also Errors String data See Character data Strings connection See Connection strings SWORD typedef B 10 SYNONYM table type 12 329 Syntax connection strings 4 8 SYSTEM TABLE table type 12 329 T Table definition statements 12 210 TABLE table type 12 329 Tabl
199. ach buffer is the maximum size of the C data that can be returned for the column For example when the C data type is SQL_C_DEFAULT the size of each buffer is the column length When the C data type is SQL_C_CHAR the size of each buffer is the display size of the data For more information see Converting Data from SQL to C on page B 19 and Precision Scale Length and Display Size on page B 5 The application allocates an array of SDWORDs to hold the number of bytes available to return for each row in the column The array has as many elements as the row set has rows The application calls SOLBindCol m The rgbValue argument specifies the address of the data storage array m The cbValueMax argument specifies the size of each buffer in the data storage array m The pcbValue argument specifies the address of the number of bytes array INFORMIX CLI Function Reference 12 127 SQLExtendeaFetch 12 128 When the application calls SQLExtendedFetch the driver retrieves the data and the number of bytes that are available to return and stores them in the buffers that the application allocates as the following actions show m For each bound column the driver stores the data in the rgbValue buffer bound to the column It stores the first row of data at the start of the buffer and each subsequent row of data at an offset of cbVal ueMax bytes from the data for the previous row m For each bound column the driver stores the
200. action was open DM The value specified for the argument fOption was in the block of numbers reserved for ODBC connection and statement options but was not valid for the version of ODBC that the driver supports The driver or data source does not support the value specified for the argument fOption 2 of 2 When fOption is a statement option SOLSetConnectOption can return any SQLSTATE that SQLSetStmtOption returns INFORMIX CLI Function Reference 12 283 SQL SetConnectOption 12 284 Usage The following table shows the currently defined options ODBC reserves options from 0 to 999 An application can call SQLSetConnectOption and include a statement option The driver sets the statement option for any statement handles associated with the specified connection handle and establishes the statement option as a default for any statement handles later allocated for that connection handle For a list of statement options see Usage on page 12 298 All connection and statement options that the application successfully sets for the connection handle persist until SQLFreeConnect is called for the connection handle For example if an application calls SQLSetConnectOption before it connects to a data source the option persists even if SQLSetConnectOption fails in the driver when the application connects to the data source if an application sets a driver specific option the option persists even if the application connect
201. age returned by SQLError in the argument szErrorMsg describes the error and its cause S1010 Function DM There was at least one hdbc in an allocated or sequence error connected state Call SQLDisconnect and SQLFreeConnect for each hdbc before calling SQLFreeEnv Usage Before an application calls SOLFreeEnv it must call SQLFreeConnect for any hdbc allocated under the henv Otherwise SOLFreeEnv returns SOL_ERROR and the henv and any active hdbc remains valid When INFORMIX CLI processes the SQLFreeEnv function it checks the TraceAutoStop value in the initialization files If the value is 1 the INFORMIX CLI disables tracing for all applications and sets the TraceAutoStop value in the initialization files to 0 Code Example See SOLBrowseConnect and SOLConnect INFORMIX CLI Function Reference 12 159 SQL FreeEnv Related Functions For Information About See Allocating an environment handle SOLAllocEnv Freeing a connection handle SOLFreeConnect 12 160 INFORMIX CLI Programmer s Manual SOL FreeStmt SOLFreeStmt SQLFreeStmt stops the processing that is associated with a specific hstmt closes any open cursors that are associated with the hstmt discards pending results and optionally frees all resources associated with the statement handle Syntax RETCODE SOLFreeStmt hstmt fOption The SOLFreeStmt function accepts the following arguments Type Argument Use HSTMT hstmt Input UWORD fOption Inp
202. akes advantage of this solution however it cannot use multiple drivers Calling Functions Every INFORMIX CLI function name starts with the prefix SQL Each function accepts one or more arguments Arguments are defined as input to the driver or output from the driver An INFORMIX CLI application must include the sql h and sqlext h header files These files define INFORMIX CLI constants and types and provide function prototypes for the INFORMIX CLI functions Buffers An application passes data to the driver in an input buffer The driver returns data to the application in an output buffer The application must allocate memory for both input and output buffers If the application uses the buffer to retrieve string data the buffer must contain space for the null termination byte Some functions accept pointers to buffers that are used later by other functions The application must ensure that these pointers remain valid until all applicable functions have used them For example the argument rgb Value in SOLBindCol points to an output buffer where SQLFetch returns the data for a column 3 8 INFORMIX CLI Programmer s Manual Buffers Input Buffers An application passes the address and length of an input buffer to the driver The length of the buffer must be one of the following values A length greater than or equal to zero This value is the actual length of the data in the input buffer For character data a length of
203. alid hdbc the driver overwrites the hdbc without regard to its previous contents Code Example See SOLBrowseConnect and SQLConnect Related Functions For Information About See Connecting to a data source SOLConnect Freeing a connection handle SOLFreeConnect 4 INFORMIX CLI Function Reference 12 11 SQLAllocEnv SQLAIlocEnv SOLAllocEnv allocates memory for an environment handle and initializes the INFORMIX CLI call level interface for application use An application must call SOLAllocEnv before it calls any other INFORMIX CLI function Syntax RETCODE SQLA1locEnv phenv The SOLAllocEnv function accepts the following argument Typedef Argument Use Description HENV FAR phenv Output Pointer to storage for the environment handle Return Codes SOL_SUCCESS or SOL_ERROR If SOLAllocEnv returns SOL_ERROR it sets the henv that phenv references to SQL_NULL_HENV In this case the application can assume that the error was a memory allocation error 12 12 INFORMIX CLI Programmers Manual SQLAllocEnv Diagnostics A driver cannot return SQLSTATE values directly after the call to SOLAllocEnv because no valid handle exists with which to call SOLError Two levels of SOLAllocEnv functions exist one within the driver manager if you are using one and one within the driver The driver manager does not call the driver level function until the application calls SQLConnect SOLBrowseConnect or SOLDriverConnect If an
204. ame case SQL _SMALLINT return max 6 strlen colname case SQL_INTEGER return max 11 strlen colname case SQL DECIMAL case SQL_NUMERIC case SQL_REAL case SQL_FLOAT case SQL_DOUBLE return max MAX_NUM_STRING SIZE strlen colname Note that this function only supports the core data types default printf Unknown datatype d n coltype return 0 Constructing an INFORMIX CLI Application 9 9 Designing Performance Oriented Applications Connecting to a Data Source Making One Connection Using Statement Handles Retrieving Information About a Data Source Minimizing the Use of Catalog Functions i Supplying Non Null Arguments to Catalog Functions Determining Table Characteristics ie oe Ge Case 1 SOLColumns Method Case 2 SOLDescribeCol Method Retrieving Data Retrieving Long Data te feos Using SQLSetStmtOption to Reduce the Size of Data Retrieved oo S Using SQLBindCol to Reduce the Call Load Case 1 SOLGetData Method Case 2 SOLBindCol Method Using SQLExtendedFetch Versus SQLFetch Executing Calls Using SQLPrepare and SQLExecute Versus SQLExecDirect Updating Data j Using Positioned Updates and Deletes Determining the Optimal Set of Columns Committing Data 10 3 10 3 10 4 10 4 10 4 10 5 10 6 10 6 10 6 10 7 10 7 10 8 10 9 10 9 10 9 10 10 10 11 10 11 10 12 10 12 10 12 10 14 10 2 INFORMIX CL
205. ameter SOLExecDirect SQLForeignKeys SOLGetData SOLGetInfo SOLNativeSql SQLPrepare SQLPutData SQLSetConnectOption SOLSetCursorName SOLSetStmtOption 8 of 13 INFORMIX CLI Error Codes A 9 SQLSTATE Values SQL STATE Error S1010 Function sequence error A 10 INFORMIX CLI Programmers Manual Can be returned from SOLBindCol SOLBindParameter SOLColAttributes SQLColumnPrivileges SOLColumns SQLDescribeCol SQLDisconnect SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SQLForeignKeys SQLFreeConnect SQLFreeEnv SQLFreeStmt SQLGetConnectOption SOLGetCursorName SOLGetData SQLGetFunctions SOLGetStmtOption SOLGetTypelnfo SQLMoreResults SOLNumParams SOLNumResultCols SOLParamData SOLParamOptions SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SQLPutData SOLRowCount SQLSetConnectOption SOLSetCursorName SQLSetScrollOptions SOLSetStmtOption SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables SQLTransact 9 of 13 SQL STATE 1011 1012 1015 1090 1091 Error Operation invalid at this time Invalid transaction operation code specified No cursor name available Invalid string or buffer length Descriptor type out of range SQLSTATE Values Can be returned from SOLGetStmtOption SQLSetConnectOption SOLSetStmtOption SQLTransact SQLGetCursorName SOLBindCol SOLBindParameter SQLBrowseConnect SQLColAttributes SQLColumnPrivileges SOLColumns SQLConnect S
206. ameters for the NAME ID and PHOTO columns For each parameter the application calls SQLBindParameter to specify the C and SQL data types of the parameter It also specifies that the data for the first and third parameters passes at execution time and that the values 1 and 3 pass for later retrieval by SQLParamData These values identify which parameter is being processed The application calls GetNextID to get the next available employee ID number It then calls SOLExecute to execute the statement SQLExecute returns SQL_NEED_DATA when it needs data for the first and third param eters The application calls SOLParamData to retrieve the value that it stored with SQLBindParameter it uses this value to determine for which parameter to send data For each parameter the application calls InitUserData to initialize the data routine It repeatedly calls GetUserData and SQLPutData to get and send the parameter data Finally it calls SQLParamData to indicate that it sent all the data for the parameter and to retrieve the value for the next parameter After data is sent for both parameters SOLParamData returns SQL_SUCCESS 12 274 INFORMIX CLI Programmers Manual SQL PutData For the first parameter InitUserData does nothing and GetUserData calls a routine to prompt the user for the employee name For the third parameter InitUserData calls a routine to prompt the user for the name of a file containing a bitmap photo of the employee and opens th
207. ample odbc ini file in INFORMIXDIR etc Copy the sample odbc ini file to your HOME directory odbcinst ini Use the odbcinst ini file that the installation script placed in INFORMIXDIR etc sqlhosts Use the sqlhosts file that the installation script placed in INFORMIXDIR etc File Format for odbc ini The following table describes the sections in the odbc ini file Description Status ODBC Data Sources Data Source Specification INFORMIX CLI Programmers Manual This section lists the data sources and Optional associates them with the INFORMIX CLI driver You need to provide this section only if you use an ODBC driver manager from a third party vendor Each data source listed in the ODBC Data Required Sources section has a Data Source Specifi cation section that describes the data source File Format for odbc ini ODBC Data Sources Each entry in the ODBC Data Sources section lists a data source and the INFORMIX CLI driver name You need to provide this section only if you use an ODBC driver manager from a third party vendor Format ODBC Data Sources data_source_name INFORMIX CLI 2 8 Driver data_source_name INFORMIX CLI 2 8 Driver Field Description Status data_source_name Data source that an INFORMIX CLI appli Required cation can access Use any data source name that you choose Example The following example defines a data source called EmpInfo ODBC Data Sources EmpInfo INFORMIX CLI
208. anslation shared library that was specified for the connection This error can only be returned when fOption is SOL_TRANSLATE DLL An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function 1 of 2 SQLSTATE Error S1009 Invalid argument value S1010 Function sequence error S1011 Operation invalid at this time S1092 Option type out of range S1C00 Driver not capable SQLSetConnectOption Description Given the specified fOption value an invalid value was specified for the argument vParam INFORMIX CLI returns this SOLSTATE only for connection and statement options that accept a discrete set of values such as SOL_ACCESS_MODE For all other connection and statement options the driver must verify the value of the argument vParam DM SOLExecute or SOLExecDirect was called for an hstmt associated with the hdbc and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM SQLBrowseConnect was called for the hdbc and returned SOL_NEED_DATA This function was called before SOLBrowseConnect returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS The argument fOption was SQL_TXN_ISOLATION and a trans
209. aramOptions SQLSetScrollOptions SQLSetScrollOptions SQLExecute SQLExecDirect SOLGetData SOLGetStmtOption SQLDriverConnect 11 of 13 SQL STATE Error 1111 S1C00 Invalid bookmark value Driver not capable SQLSTATE Values Can be returned from SOLExtendedFetch SOLBindCol SOLBindParameter SQLColAttributes SQLColumnPrivileges SOLColumns SOLExecDirect SQLExecute SQLExtendedFetch SOLFetch SQLForeignKeys SQLGetConnectOption SQLGetData SOLGetInfo SOLGetStmtOption SOLGetTypelnfo SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SQLSetConnectOption SQLSetScrollOptions SOLSetStmtOption SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables SQLTransact 12 of 13 INFORMIX CLI Error Codes A 13 SQLSTATE Values A 14 SQL STATE Error S1T00 Time out expired INFORMIX CLI Programmers Manual Can be returned from SQLBrowseConnect SOLColAttributes SOLColumnPrivileges SOLColumns SQLConnect SQLDescribeCol SQLDriverConnect SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SQLForeignKeys SOLGetData SOLGetInfo SOLGetTypelnfo SOLMoreResults SOLNumParams SOLNumResultCols SQLParamData SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SOLPutData SQLSpecialColumns SOLStatistics SQLTablePrivileges SQLTables 13 of 13 Data Types This appendix discusses the following topics Types of data types SQL data types C data types Transferring data
210. assign a cursor name for the statement or let the driver assign one Submit the statement for prepared or immediate execution If the statement creates a result set you can inquire about the attributes of the result set such as the number of columns and the name and type of a specific column For each column in the result set assign storage and fetch the results If the statement causes an error retrieve error information from the driver and take the appropriate action End each transaction by committing it or rolling it back Terminate the connection when it finishes interacting with the data source Guidelines for Calling INFORMIX CLI Functions 3 13 How an Application Uses the INFORMIX CLI API Figure 3 1 shows the function calls that a basic application makes Depending on your needs your application can call other functions Figure 3 1 Sample Listing of Function Calls That SQLAllocEnv an INFORMIX CLI Application Makes SQLAllocConnect SQL Connect SQLAllocSimt e Process SQL statements Receive results Y SQLFreeStmt CLOSE option DROP option SQLDisconnect SQL FreeConnect SOL FreeEnv 3 14 INFORMIX CLI Programmers Manual Connecting to a Data Source Initializing the Environment Allocating a Connection Handle Connecting to a Data Source Using SQLConnect Using SQLDriverConnect Using SQLBrowseConnect Connection Strings Exclusive Database Use
211. at do not have owners Foreign key table identifier Foreign key column identifier Column sequence number in key starting with 1 Action to be applied to the foreign key when the SQL operation is UPDATE SQL_CASCADE SQL_RESTRICT SQL_SET_NULL NULL if not applicable to the data source Action to be applied to the foreign key when the SQL operation is DELETE SQL_CASCADE SQL_RESTRICT SQL_SET_NULL NULL if not applicable to the data source Foreign key identifier NULL if not applicable to the data source Primary key identifier NULL if not applicable to the data source 2 of 2 INFORMIX CLI Function Reference 12 149 SQL ForeignKeys Code Example The code example in this section uses four database tables The following table lists the database tables and the columns in each database table Database Table Columns SALES_ORDER SALES_ID CUSTOMER_ID EMPLOYEE_ID TOTAL_PRICE SALES_LINE SALES_ID LINE_NUMBER PART _ID QUANTITY PRICE CUSTOMER CUSTOMER_ID CUST_NAME ADDRESS PHONE EMPLOYEE EMPLOYEE_ID NAME AGE BIRTHDAY In the SALES_ORDER table CUSTOMER _ID identifies the customer to whom the sale was made It is a foreign key that refers to CUSTOMER_ID in the CUSTOMER table In the SALES_ORDER table EMPLOYEE_ID identifies the employee who made the sale It is a foreign key that refers to EMPLOYEE_ID in the EMPLOYEE table In the SALES LINE table SALES_ID identifies the sales order with which the line
212. at it appears as though no other transactions operate on the same data at the same time Suppose one transaction doubles data values and another adds 1 to data values If the transactions are serializable and both attempt to operate on the values 0 and 10 at the same time the final values are 1 and 21 or 2 and 22 depending on which transaction occurs first If the transactions are not serial izable the final values are 1 and 21 2 and 22 1 and 22 or 2 and 21 the sets of values 1 and 22 and 2 and 21 are the result of the transactions acting on each value in a different order To maintain database integrity you must to be able to serialize a transaction However a serialized transaction locks the result set which prohibits cursor concurrency Retrieving Results 6 11 Positioned Update and Delete Statements 6 12 Positioned Update and Delete Statements To modify data in the result set an application can update or delete the row to which the cursor currently points Such an operation is known as a positioned update or delete statement INFORMIX CLI positioned update and delete statements are similar to such statements in embedded SQL After an application executes a SELECT statement to create a result set it calls SOLFetch one or more times to position the cursor on the row to be updated or deleted To update or delete the row the application then executes an SQL statement with the following syntax on a different hstmt UPDAT
213. ata After the procedure is executed sEmpId and szRemark will have the new values EJ returned by AddEmployee EP retcode SQLExecDirect hstmt call AddEmployee SQL_NTS Related Functions For Information About See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SOLCancel Fetching a block of data or scrolling through a SOLExtendedFetch result set Fetching a row of data SOLFetch Returning information about a driver or data SOLGetInfo source Returning the parameters and result set columns of a procedure Syntax for invoking stored procedures SOLProcedureColumns extension Chapter 5 Executing SQL Statements 12 270 INFORMIX CLI Programmer s Manual SQL PutData SQLPutData SQLPutData allows an application to send data for a parameter or column to the driver at statement execution time This function can send character or binary data values in parts to a column with a character binary or data source specific data type for example parameters of SOL_LONGVARBINARY or SOL_LONGVARCHAR Syntax RETCODE SQLPutData hstmt rgbValue cbValue The SOLPutData function accepts the following arguments Type HSTMT PTR SDWORD Argument hstmt rebValue cbValue Use Input Input Input Description Statement handle Pointer to storage for the actual data for the parameter or column The data must use the C data type sp
214. ata Sources section creates the data source specification section and adds the Driver keyword with the driver description as its value ConfigDSN calls SOLWritePrivateProfileString in the installer shared library to add more keywords and values that the driver needs Setup Shared Library Function Reference 13 5 ConfigDSN Modifying a Data Source To modify a data source a data source name must be passed to ConfigDSN in lpszAttributes If hwndParent is null ConfigDSN uses the information in pszAttributes If hwndParent is not null ConfigDSN displays a dialog box that uses the infor mation in pszAttributes The user can modify the information before ConfigDSN stores it If the data source name was changed ConfigDSN first calls SOLRemoveDSNFromini in the installer shared library to remove the existing data source specification It then follows the steps in the previous section to add the new data source specification Ifthe data source name was not changed ConfigDSN calls SQLWritePrivateProfileString in the installer shared library to make any other changes ConfigDSN cannot delete or change the value of the Driver keyword Deleting a Data Source To delete a data source a data source name must be passed to ConfigDSN in IpszAttributes ConfigDSN then calls SOLRemoveDSNFromini in the installer shared library to remove the data source 13 6 INFORMIX CLI Programmers Manual Config Translator ConfigTranslator ConfigT
215. ata is used with SOLPutData to supply parameter data when a statement executes Syntax RETCODE SQLParamData hstmt prgbValue The SOLParamData function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle PTR FAR prgbValue Output Pointer to storage for the value specified for the rebValue argument in SQLBindParameter for parameter data or the address of the rgbValue buffer specified in SOLBindCol for column data Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NEED_DATA SOL_STILL_EXECUTING SQL_ERROR or SOL_INVALID_HANDLEINFORMIX CLI 12 242 INFORMIX CLI Programmers Manual Diagnostics SQLParamData When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 08S01 22026 S1000 S1001 General warning Communication link failure String data length mismatch General error Memory allocation failure I
216. atement that contained a date overflow time or time stamp parameter or literal and the value was respectively an invalid date time or time stamp 22012 Division by zero The argument szSq Str contained an SQL statement that contained an arithmetic expression that caused division by zero 23000 Integrity constraint The argument sz5q Str contained an SQL statement that contained a violation parameter or literal The parameter value was NULL for a column defined as NOT NULL in the associated table column a duplicate value was supplied for a column constrained to contain only unique values or some other integrity constraint was violated 24000 Invalid cursor state A cursor was already opened on the statement handle The argument szSq Str contained a positioned UPDATE or DELETE statement but the cursor was positioned before the start of the result set or after the end of the result set 34000 Invalid cursor The argument szSq Str contained a positioned UPDATE or DELETE name statement but the cursor referenced by the statement being executed was not open 37000 Syntax error or The argument szSq Str contained an SQL statement that was not prepa access violation rable or contained a syntax error 40001 Serialization failure The transaction to which the SQL statement contained in the argument szSqlStr belonged was terminated to prevent deadlock 2 of 5 12 112 INFORMIX CLI Programmer s Manual SQLSTATE Error 42000 S0001 S0
217. atic because it is impossible to balance books when the data changes continually When selling concert tickets a clerk needs up to the minute or dynamic data on which tickets are still available Various cursor models are designed to meet these needs Each requires different sensitivities to changes in the tables that underlie the result set Static Cursors In static cursors the data in the underlying tables appears to be static The membership order and values in the result set used by a static cursor are generally fixed when the cursor is opened Rows updated deleted or inserted by other users including other cursors in the same application are not detected by the cursor until it closes and then reopens The SQL_STATIC_SENSITIVITY information type returns whether the cursor can detect rows that it has updated deleted or inserted Static cursors are commonly implemented by taking a snapshot of the data or locking the result set In the former case the cursor diverges from the under lying tables as other users make changes in the latter case other applications and cursors in the same application cannot change the data Dynamic Cursors In dynamic cursors the data appears to be dynamic The membership order and values in the result set that a dynamic cursor uses are always changing When data is fetched the cursor detects rows updated deleted or inserted by all users the cursor other cursors in the same application and ot
218. ation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SQLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 01004 07006 08501 22002 22003 General warning Data truncated Restricted data type attribute violation Communication link failure Indicator value required but not supplied Numeric value out of range INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The data returned for one or more columns was truncated String values are right truncated For numeric values the fractional part of number was truncated function returns SQL_SUCCESS_WITH_INFO The data value could not be converted to the data type specified by fCType in SOLBindCol The communication link between the driver and the data source failed before the function completed If the column value for any bound column is null the INDICATOR_PTR field of the corresponding descriptor record must not be a null pointer Returning the numeric value as numeric or string for one or more columns would have caused the whole as opposed to fractional number to truncate Returning the binary value for one or more columns would cause a loss of binary significance For more information see Converting Data from SQL to C on page B 19 1 of 3 INFORMIX CLI Function Reference 12 139 SQL Fetch 22005 220
219. ation About See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SOLCancel Returning the columns in a table or tables SOLColumns Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SOLFetch Returning privileges for a table or tables SQLTablePrivileges Returning a list of tables in a data source SQLTables INFORMIX CLI Function Reference 12 67 SQLColumns 12 68 SQLColumns SQLColumns returns the list of column names in specified tables The driver returns this information as a result set on the specified hstmt Syntax RETCODE SQLColumns hstmt cbTableQualifier cbTableName szTableQualifier szTableOwner szColumnName cbTableOwner szTableName cbColumnName The SOLColumns function accepts the following arguments Type HSTMT UCHAR FAR SWORD UCHAR FAR SWORD UCHAR FAR SWORD UCHAR FAR SWORD Argument hstmt szTableQualifier cbTableQualifier szTableOwner cbTableOwner szlableName cbTableName szColumnName cbColumnName INFORMIX CLI Programmers Manual Use Input Input Input Input Input Input Input Input Input Description Statement handle Qualifier name If a driver supports quali fiers for some tables but not for others such as when the driver retrieves data from different data sources an empty string denotes those tables that do not have qualifiers Len
220. ation is returned as a character string a 32 bit descriptor dependent value or an integer value Syntax RETCODE SQLColAttributes hstmt icol fDescType rgbDesc cbDescMax pcbDesc pfDesc The SOLColAttributes function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UWORD icol Input Column number of result data ordered sequentially from left to right starting at 1 Columns can be described in any order UWORD fDescType Input A valid descriptor type See Usage on page 12 56 PTR rgbDesc Output Pointer to storage for the descriptor infor mation The format of the descriptor information returned depends on the fDescType SWORD cbDescMax Input Maximum length of the rgbDesc buffer 1 of 2 12 52 INFORMIX CLI Programmer s Manual SQLColAttributes Type Argument Use Description SWORD FAR pcbDesc Output Total number of bytes excluding the null termination byte for character data available to return in rgbDesc For character data if the number of bytes available to return is greater than or equal to cbDescMax the descriptor information in rgbDesc is truncated to cbDescMax 1 bytes and is null terminated by the driver For all other types of data the value of cbValueMax is ignored and the driver assumes the size of rgbValue is 32 bits SDWORD FAR pfDesc Output Pointer to an integer value to contain descriptor information for numeric descr
221. ause DM The driver manager did not allocate memory required to support execution or completion of the function The driver did not allocate memory required to support execution or completion of the function DM The value specified for argument cbDSN was less than 0 but not equal to SOL_NTS DM The value specified for argument cbDSN exceeded the maximum length for a data source name DM The value specified for argument cbUID was less than 0 but not equal to SOL_NTS DM The value specified for argument cbAuthStr was less than 0 but not equal to SOL_NTS The time out period expired before the connection to the data source completed The time out period is set through SOLSetConnectOption SQL_LOGIN_TIMEOUT 2 of 2 INFORMIX CLI Programmers Manual SQLConnect Usage INFORMIX CLI does not load its driver until the application calls a function SQLConnect SQLDriverConnect or SQLBrowseConnect to connect to the driver Until that point INFORMIX CLI works with its own handles and manages connection information When the application calls a connection function INFORMIX CLI checks to see if its driver is currently loaded m If the driver is not loaded INFORMIX CLI loads the driver and calls SOLAllocEnv SOLAllocConnect SOLSetConnectOption if the application specified any connection options and the connection function in the driver INFORMIX CLI returns SOLSTATE IM006 Driver SQLSetConnectOption function fail
222. aximum interoperability however your application should call SOLGetData only for columns to the right of the right most bound column and then only in left to right order Assigning Storage for Row Sets Binding In addition to binding individual rows of data an application can call SQLBindCol to assign storage for a row set one or more rows of data To specify how many rows of data are in a row set an application calls SQLSetStmtOption with the SOL_ROWSET_SIZE option By default row sets are bound in column wise fashion They can also be bound in row wise fashion Retrieving Results 6 7 Assigning Storage for Row Sets Binding 6 8 1 1 To assign storage for column wise binding Allocate an array of data storage buffers The array has as many elements as there are rows in the row set Allocate an array of storage buffers to hold the number of bytes that are available to return for each data value The array has as many elements as there are rows in the row set Call SOLBindCol and specify the address of the data array the size of one element of the data array the address of the number of bytes array and the type to which the data will be converted When data is retrieved the driver uses the array element size to determine where to store successive rows of data in the array To assign storage for row wise binding Declare a structure that can hold a single row of retrieved data and the associated data leng
223. be called only for columns after the last bound column unless SQL_GD_ANY_COLUMN is also returned SQL_GD_BOUND SQLGetData can be called for bound columns as well as unbound columns A driver cannot return this value unless it also returns SOL_GD_ANY_COLUMN SQLGetData is required to return data only from unbound columns that occur after the last bound column are called in order of increasing column number and are not in a row ina block of rows 9 of 24 INFORMIX CLI Function Reference 12 201 SQL Getinfo InfoType Returns SQL_GROUP_BY A 16 bit integer value that specifies the relationship between the columns in the GROUP BY clause and the non aggregated columns in the SELECT list m SQL_GB_NOT_SUPPORTED GROUP BY clauses are not supported m SQL_GB_GROUP_BY_EQUALS_SELECT The GROUP BY clause must contain all non aggregated columns in the SELECT list It cannot contain any other columns For example SELECT DEPT MAX SALARY FROM EMPLOYEE GROUP BY DEPT m SQL_GB_GROUP_BY_CONTAINS_SELECT The GROUP BY clause must contain all non aggregated columns in the SELECT list It can contain columns that are not in the SELECT list For example SELECT DEPT MAX SALARY FROM EMPLOYEE GROUP BY DEPT AGE m SQL_GB_NO_RELATION The columns in the GROUP BY clause and the select list are not related The meaning of non grouped non aggregated columns in the SELECT list is data source dependent For example SELECT DEPT SALARY FR
224. before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application 2 of 3 SQLFetch SQLSTATE Error Description S1010 Function DM The specified hstmt was not in an executed sequence error state The function was called without first calling SQLExecDirect SQLExecute or a catalog function DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM SQLExtendedFetch was called for an hstmt after SOLFetch was called and before SOLFreeStmt was called with the SOL_CLOSE option S1C00 Driver not capable The driver or data source does not support the conversion specified by the combination of the fCType in SOLBindCol and the SQL data type of the corresponding column This error applies only when the SQL data type of the column was mapped to a driver specific SOL data type S1T00 Time out expired The time out period expired before the data source returned the result set The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT 3 of 3 Usage SQLFetch positions the cursor on the next row of the result set Before SQLFetch is called the first time the cursor is positioned before the start of the result set When the cursor is positioned on the last row of the result set SQLFetch returns SOL_NO_DATA_FOUND and the cursor is positioned af
225. call SOLGetInfo with the SOL_MAX_QUALIFIER_NAME_LEN SOL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SOL_MAX_COLUMN_NAME_LEN options Column Name Data Type Comments TABLE_QUALIFIER VARCHAR 128 Table qualifier identifier null if not appli cable to the data source If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different data sources it returns an empty string for those tables that do not have qualifiers TABLE_OWNER VARCHAR 128 Table owner identifier null if not applicable to the data source If a driver supports owners for some tables but not for others such as when the driver retrieves data from different data sources it returns an empty string for those tables that do not have owners TABLE_NAME VARCHAR 128 Table identifier not NULL 1 of 3 INFORMIX CLI Function Reference 12 71 SQLColumns 12 72 Column Name COLUMN_NAME DATA_TYPE TYPE_NAME PRECISION LENGTH SCALE INFORMIX CLI Programmers Manual Data Type VARCHAR 128 not NULL SMALLINT not NULL VARCHAR 128 not NULL INTEGER INTEGER Comments Column identifier Informix SQL data type The possible values are any of the Informix SOL data types listed in Appendix B Data Types For more information about data types and conver sions see Appendix B Data source dependent data type name for example CHAR VARCHAR MONEY LONG VARB
226. can be supplied For information on attribute keywords that are available with INFORMIX CLI see Connection Strings on page 4 7 m The attribute value list is an enumeration of actual values valid for the corresponding attribute keyword The braces do not indicate a list of choices the driver returns them For example the list might include server names or a list of database names m If the attribute value is a single question mark a single value corresponds to the attribute keyword For example UID JohnS PWD Sesame m Each call to SQLBrowseConnect returns only the information required to satisfy the next level of the connection process The driver associates state information with the connection handle so that the context can be determined on each call Using SQLBrowseConnect SQLBrowseConnect requires an allocated hdbc The driver manager loads the driver that is specified in or that corresponds to the data source name specified in the initial browse request connection string For additional infor mation see Usage on page 12 79 It might establish a connection with the data source during the browsing process If SOLBrowseConnect returns SOL_ERROR outstanding connections terminate and the hdbc returns to an unconnected state When SOLBrowseConnect is called for the first time on an hdbc the browse request connection string must contain the DSN keyword or the DRIVER keyword If the browse request connection
227. cates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SQLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 08S01 24000 IM001 S1000 1001 S1009 General warning Communication link failure Invalid cursor state Driver does not support this function General error Memory allocation failure Invalid argument value 12 146 INFORMIX CLI Programmers Manual Driver specific informational message Function returns SQL_SUCCESS_WITH_INFO The communication link between the driver and the data source to which the driver was connected failed before the function completed processing DM A cursor was open on the hstmt and SOLFetch or SOLExtendedFetch had been called A cursor was open on the hstmt but SQLFetch or SQLExtendedFetch had not been called DM The driver associated with the hstmt does not support the function An error occurred for which there was no specific SQLSTATE and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver was unable to allocate memory required to support execution or completion of the function DM The arguments szPkTableName and szFk
228. cess plans for all of the statement handles that belong to a connection handle For more information see SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR on page 12 196 Executing SQL Statements 5 9 Retrieving Information About the Data Source Catalog 5 10 Retrieving Information About the Data Source Catalog The functions listed in Retrieving Information About Data Source System Tables on page 11 8 are catalog functions that return information about a data source catalog Each function returns the information as a result set Use SOLBindCol and SQLFetch to retrieve these results Sending Parameter Data at Execution Time Use the following functions to send parameter data for instance for param eters of the SOL_LONGVARCHAR or SQL_LONGVARBINARY types when a statement executes SQLBindParameter m SQLParamData m SQLPutData To indicate that your application plans to send parameter data when the statement executes call SOLBindParameter and set the pcbValue buffer for the parameter to the result of the SOL_LEN_DATA_AT_EXEC length macro If the fSq Type argument is SOL_LONGVARBINARY or SOL_LONGVARCHAR and the driver returns Y for the SOL_NEED_LONG_DATA_LEN information type in SQLGetInfo then length is the total number of bytes of data to be sent for the parameter otherwise it is ignored Set the rgbValue argument to a value that can be used to retrieve the data at runtime For example
229. ch hstmt SQL_FETCH_NEXT 1 amp crow rgfRowStatus if retcode SQL_ERROR retcode SQL_SUCCESS WITH_INFO sh if retcode SQL_SUCCESS fo ow_error retcode SQL_SUCCESS WITH_INFO r irow 0 irow lt crow jrowt if rgfRowStatus lirow SQL_ROW_DELETED amp amp rgfRowStatus irow SQL_ROW_ERROR fprintf out s 2d s NAME_LEN 1 szName irow sAgeLirow BDAY_LEN 1 szBirthdayLirow INFORMIX CLI Function Reference 12 135 SQLExtendeaFetch 12 136 else break Row Wise Binding In the following example an application declares an array of structures to hold row wise bound data and the returned numbers of bytes Using SQLSetStmtOption the application requests row wise binding and passes the size of the structure to the driver The driver uses this size to find successive storage locations in the array of structures and specifies the size of the row set with SOLSetStmtOption The application then executes a SELECT statement to return a result set of the employee names and birthdays which is sorted by birthday It calls SQLBindCol to bind the columns of data passing the addresses of storage locations for both the data and the returned numbers of bytes Finally the application fetches the row set data with SOLExtendedFetch and prints each employee s name and birthday Hefine ROWS 100 idefine NAME_LEN 30 idefine BDAY_LEN 11 typedef struct UCHAR s
230. cific table Returns the list of column name or names that make up the primary key for a table Returns the list of input and output parameters as well as the columns that make up the result set for the specified procedures 1 of 2 Function Name SQLProcedures SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables ODBC Conformance Level 2 Level 1 Level 1 Level 2 Level 1 Terminating a Statement Terminating a Statement Purpose Returns a list of procedure names stored in a specific data source Returns information about the optimal set of columns that uniquely identifies a row ina specified table or the columns that are automatically updated when a transaction updates any value in the row Returns statistics about a single table and the list of indexes associated with the table Returns a list of tables and the privileges associated with each table Returns the list of table names stored in a specific data source 2 of 2 The following table describes functions that terminate a statement ODBC Function Name Conformance Purpose SQLFreeStmt Core Ends statement processing and closes the associated cursor discards pending results and optionally frees all resources associated with the statement handle SOLCancel Core Cancels an SOL statement SQLTransact Core Commits or rolls back a transaction Function Summary 11 9 Terminating a Connection Terminati
231. cified is not the same degree as the derived table that the query specification defines The argument szSq Str contained an SQL statement that contained a literal or parameter and the value was incompatible with the data type of the associated table column A cursor was already opened on the statement handle The argument szSq Str contained a positioned DELETE or a positioned UPDATE and the cursor referenced by the statement being prepared was not open 1 of 4 INFORMIX CLI Function Reference 12 247 SQL Prepare 12 248 SQLSTATE Error 37000 Syntax error or access violation 42000 Syntax error or access violation S0001 Base table or view already exists S0002 Base table not found INFORMIX CLI Programmers Manual Description The argument szSq Str contained an SQL statement that was not preparable or contained a syntax error The argument szSq Str contained a statement for which the user did not have the required privileges The argument szSq Str contained a CREATE TABLE or CREATE VIEW statement but the table name or view name specified already exists The argument szSq Str contained a DROP TABLE or a DROP VIEW statement but the specified table name or view name did not exist The argument szSq Str contained an ALTER TABLE statement but the specified table name did not exist The argument szSqlStr contained a CREATE VIEW statement but a table name or view name that the query specification
232. connect to a data source by calling SOLDriverConnect SQLDriverConnect supports the following features Data sources that require more connection information than the three arguments in SOLConnect Dialog boxes to prompt the user for all connection information Data sources that have not been configured An application calls SOLDriverConnect in one of the following ways Specifies a connection string that contains a data source name INFORMIX CLI retrieves the full path of the driver shared library associated with the data source To retrieve a list of data source names an application calls SQLDataSources Specifies a connection string that contains a driver description INFORMIX CLI retrieves the full path of the driver shared library To retrieve a list of driver descriptions an application calls SOLDrivers Specifies a connection string that does not contain a data source name or a driver description INFORMIX CLI displays a dialog box from which the user selects a data source name INFORMIX CLI then retrieves the full path of the driver shared library associated with the data source INFORMIX CLI then loads the driver shared library and passes the SQLDriverConnect arguments to it Connecting to a Data Source 4 5 Using SQLDriverConnect Data Source Name demo_database The application can pass all the connection information that the driver needs It can also request that the driver always prompt the user for connection
233. cribed 1 3 3 7 errors 7 6 ODBC version supported 12 207 SQLDriverConnect 12 99 SQLError 12 109 tracing 12 286 transactions 12 333 unloading drivers 12 79 INFORMIX CLI Programmer s Manual Drivers allocating handles 12 13 errors 7 3 file usage 12 200 information types 12 189 keywords 12 106 listing installed 12 106 loading 12 79 SQLError 12 109 Driver INFORMIX CLI 1 4 DROP INDEX statements 12 316 DROP statements 4 10 DSN keyword 4 8 Dynamic cursors 6 10 Dynamic SQL C 7 E Embedded SQL executing statements 5 5 ODBC function equivalents C 5 C 6 Embedded SQL function equivalents C 1 to C 10 Empty strings 3 9 12 8 Environment handles allocating 4 3 defined 3 11 freeing 8 4 SQLAIlocEnv 12 12 SQLFreeEnv 12 158 Environment variables INFORMIXDIR 1 9 INFORMIXSQLHOSTS 1 10 PATH 1 9 Error message files Intro 10 Errors application processing 7 7 clearing 12 109 format 7 5 handling 7 4 messages 7 4 7 8 queues 12 109 return codes 7 3 rowsets 12 131 source 7 8 SQLError 12 108 SQLSTATE values A 1 See also specific function descriptions Escape clauses 12 203 Examples ad hoc query 9 7 data conversion B 30 B 41 parameter values 5 8 static SQL 9 4 Expressions in ORDER BY clauses 12 199 F Fat cursors 6 9 fCType B 10 Feature icons Intro 7 Fetching data See Retrieving data Files odbcinst ini 2 9 odbc ini 2 9 sqlhosts 2 9 trace 12 286 usage 12 200 h 3 8 Filtered indexes 12 317 finderr utili
234. cs of a Result Set Fetching Result Data Using Cursors Retrieving Data from Unbound Columns Assigning Storage for Row Sets one Retrieving Row Set Data E Using Block and Scrollable Cursors Block Cursors ee Scrollable Cursors Specifying the Cursor Type Specifying Cursor Concurrency Positioned Update and Delete Statements Processing Multiple Results 6 3 6 4 6 5 6 5 6 6 6 7 6 9 6 9 6 10 6 11 6 11 6 12 6 13 6 2 INFORMIX CLI Programmer s Manual his chapter describes the different ways that an application can retrieve results Result Sets and INFORMIX CLI A SELECT statement is used to retrieve data that meets a given set of specifi cations In the following example a SELECT statement retrieves all columns for employees named Jones from all the rows in the EMPLOYEE table SELECT FROM EMPLOYEE WHERE EMPNAME Jones INFORMIX CLI functions can also retrieve data For example SOLColumns retrieves data about columns in the data source These sets of data called result sets can contain zero or more rows Other SQL statements such as GRANT or REVOKE do not return result sets For these statements the return code from SQLExecute or SOLExecDirect is usually the only source of information about whether the statement is successful For INSERT UPDATE and DELETE statements an application can call SQLRowCount to return the number of affected rows Retrieving Results 6 3 Assigning Storage fo
235. ct for the hstmt DM SOLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT SQLNumResultCols can return any SOLSTATE that SOLPrepare or SQLExecute can return when SOLNumResultCols is called after SOLPrepare and before SQLExecute is called depending on when the data source evaluates the SOL statement associated with the hstmt Usage SQLNumResultCols SQLNumResultCols can be called successfully only when the hstmt is in the prepared executed or positioned state If the statement associated with hstmt does not return columns SQLNumResultCols sets pccol to 0 Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Returning information about a column in a result set Returning information about a column in a result set Fetching a block of data or scrolling through a result set Fetching a row of data Fetching part or all of a column of data Setting cursor scrolling options See SQLBindCol SQLCancel SQLColAttributes SQLDescribeCol SQLExtendedFetch SQLFetch SQLGetData SQLSetScrollOptions INFORMIX CLI Function Reference 12 241 SQL ParamData SQLParamData SQLParamD
236. ction failed due to an invalid environment handle connection handle or statement handle This situation indicates a programming error No additional information is available from SOLError Function is still busy processing an asynchronous request While the driver was processing a statement it deter mined that the application needs to send parameter data values 2 of 2 The application is responsible for taking the appropriate action based on the INFORMIX CLI defines a layered architecture to connect an application to a data source SOLError returns error messages that follow the standard INFORMIX CLI format An error message not only explains the error but also provides the identity of the component in which it occurred Because SQLError does not return the identity of the component in which the error occurred this information is embedded in the error text Error Text Format Error Text Format Error messages that SQLError returns come from two sources data sources and INFORMIX CLI Consequently the error text that SQLError returns has two formats one for errors that occur in a data source and one for errors that occur in INFORMIX CLI If INFORMIX CLI receives an error message from a data source it identifies the data source as the source of the error It also identifies itself as the component that received the error For errors that occur in a data source the error text uses the following format vendor_identif
237. d The driver did not load the translation shared library that was specified for the data source or for the connection DM The attribute value for the DSN keyword was longer than SOL_MAX_DSN_LENGTH characters 2 of 3 INFORMIX CLI Function Reference 12 97 SQL DriverConnect 12 98 SQLSTATE Error IMO11 Driver name too long IM012 DRIVER keyword syntax error S1000 General error S1001 Memory allocation failure S1090 Invalid string or buffer length S1110 Invalid driver completion S1T00 Time out expired INFORMIX CLI Programmers Manual Description DM The attribute value for the DRIVER keyword was longer than 255 characters DM The keyword value pair for the DRIVER keyword contained a syntax error An error occurred for which no specific SOLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver manager did not allocate memory required to support execution or completion of the function The driver did not allocate memory required to support execution or completion of the function DM The value specified for argument cbConnStrIn was less than 0 and was not equal to SQL_NTS DM The value specified for argument cbConnStrOutMax was less than 0 DM The value specified for the argument fDriverCompletion was not equal to SOL_DRIVER_PROMPT SOL_DRIVER_COMPLET
238. d If fParamType is SOL_PARAM_OUTPUT and rgbValue and pcbValue are both null pointers the driver discards the output value Important Application developers are strongly discouraged from specifying a null pointer for pcbValue when the parameter s INFORMIX CLI C data type is SQL_C_BINARY For SQL_C_BINARY data the driver sends only the data preceding an occurrence of the null termination character 0x00 To ensure that the driver does not unexpectedly truncate SQL_C_BINARY data pcbValue should contain a pointer to a valid length value If the fParamType argument is SOL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT pcbValue points to a buffer in which the driver returns SOL_NULL_DATA the number of bytes available to return in rgbValue excluding the null termination byte of character data or SOL_NO_TOTAL if the number of bytes available to return cannot be determined If the procedure returns one or more result sets the pcbValue buffer is not guaranteed to be set until all the results are fetched Passing Parameter Values An application can pass the value for a parameter either in the rgb Value buffer or with one or more calls to SOLPutData Parameters whose data is passed with SOLPutData are known as data at execution parameters These are commonly used to send data for SOL_LONGVARBINARY and SOL_LONGVARCHAR parameters and can be mixed with other parameters INFORMIX CLI Function Reference 12 33 SQL BindParameter 12 34 To pass
239. d Display Size Standard SQL Data Types The following table describes the precision scale length and display size for the standard INFORMIX CLI SQL data types INFORMIX CLI SQL Data Type fSqlType Description SQL_CHAR Precision Same as the length Scale Not applicable SOLBindParameter ignores the value of ibScale for this data type Length The specified length For example the length of CHAR 10 is 10 bytes Display size Same as the length SQL_DATE Precision 10 SOLBindParameter ignores the value of cbColDef for this data type Scale Not applicable SOLBindParameter ignores the value of ibScale for this data type Length 6 bytes Display size 10 digits in the format yyyy mm dd SQL_DECIMAL Precision The specified precision For example the precision of DECIMAL 12 3 is 12 Scale The specified scale For example the scale of DECIMAL 12 3 is 3 Length The specified precision plus 2 For example the length of DECIMAL 12 3 is 14 bytes The two additional bytes are used for the sign and the decimal points because functions return this data type as a character string Display size Same as the length SQL_DOUBLE Precision 15 SOLBindParameter ignores the value of cbColDef for this data type Scale Not applicable SOLBindParameter ignores the value of ibScale for this data type Length 8 bytes Display size 22 digits The digits are for a sign 15 numeric characters a deci
240. d Level 1 functions INFORMIX CLI supports the Level 2 functions except those marked with an asterisk Level 2 Functions SOLBrowseConnect SQLColumnPrivileges SQLDataSources SOLDescribeParam SQLDrivers SQLExtendedFetch SQLForeignKeys SQLMoreResults SQLNativeSql SOLNumParams SQLParamOptions SQLPrimaryKeys SQLProcedureColumns SQLProcedures SQLSetPos SQLSetScrollOptions SQLTablePrivileges SQL Conformance Levels SQL Conformance Levels SQL conformance refers to the SQL grammar that an ODBC driver supports The SQL conformance standard consists of three levels Minimum Core and Extended INFORMIX CLI supports all Minimum and Core SQL grammar which includes the following statements expressions and data types m Data Definition Language DDL statements CREATE TABLE DROP TABLE ALTER TABLE CREATE INDEX DROP INDEX CREATE VIEW DROP VIEW GRANT REVOKE m Data Manipulation Language DML statements Full SELECT INSERT UPDATE SEARCHED DELETE SEARCHED Positioned UPDATE Positioned DELETE 0D o oO oO O UO O O O Outer joins 0 oO O O O O O O O Unions m Expressions a Simple such as A gt B C a Subquery a Set functions such as SUM and MIN m Data types See Appendix B Guidelines for Calling INFORMIX CLI Functions 3 5 Verifying INFORMIX CLI Conformance Levels 3 6 Numeric functions abs acos asin atan2 cos cot log log10 mod round sin sqrt truncate m Date functions curdate dayofweek
241. d before data was sent for all data at execution parameters or columns DM The value of one of the name length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corre sponding qualifier or name A table qualifier was specified but the driver or data source does not support qualifiers A table owner was specified but the driver or data source does not support owners A string search pattern was specified for the table owner or table name but the data source does not support search patterns for one or more of those arguments The driver of data source does not support the combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options The time out period expired before the data source returned the requested result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLTables lists all the tables in the requested range A user might or might not have SELECT privileges to any of these tables To check accessibility an application can call SOLGetInfo and check the SQL_ACCESSIBLE_TABLES info value Otherwise the application must handle situations where the user selects a table for which SELECT privileges are not granted INFORMIX CLI Function Reference 12 327 SQL Tables The szTableOwner and szTableName arguments accept search patterns For more informati
242. d not exist The argument szSq Str contained a GRANT or REVOKE statement and a specified column name did not exist The argument szSq Str contained a SELECT DELETE INSERT or UPDATE statement and a specified column name did not exist The argument szSq Str contained a CREATE TABLE statement and a column specified in a constraint referencing a table other than the one being created did not exist An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application DM The argument szSq Str was a null pointer of 4 INFORMIX CLI Function Reference 12 249 SQL Prepare SQLSTATE Error Description S1010 Function DM SQLExecute or SQLExecDirect was called for sequence error the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns S1090 Invalid string or DM The argument cbSqlStr was less than or equal buffer length to 0 but not equal to SQL_NTS S1C00 Driver not capable The cursor concurrency combination is invalid S1T00 Time out expired Th
243. define additional columns beyond column 13 REMARKS The lengths of VARCHAR columns as the table shows are maximums the actual lengths depend on the data source To determine the actual lengths of the PROCEDURE_QUALIFIER PROCEDURE_OWNER PROCEDURE_NAME and COLUMN_NAME columns an application can call SQLGetInfo with the SOL_MAX_QUALIFIER_NAME_LEN SOL_MAX_OWNER_NAME_LEN SQL_MAX_PROCEDURE_NAME_LEN and SQL_MAX_COLUMN_NAME_LEN options Column Name Data Type Comments PROCEDURE_QUALIFIER VARCHAR 128 Procedure qualifier identifier NULL if not applicable to the data source If a driver supports qualifiers for some proce dures but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those procedures that do not have qualifiers PROCEDURE_OWNER VARCHAR 128 Procedure owner identifier NULL if not applicable to the data source If a driver supports owners for some procedures but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those procedures that do not have owners PROCEDURE_NAME VARCHAR 128 Procedure identifier not NULL 1 of 3 12 260 INFORMIX CLI Programmer s Manual Column Name COLUMN_NAME Data Type VARCHAR 128 not NULL SQLProcedureColumns Comments Procedure column identifier COLUMN_TYPE SMALLINT not NULL Defines the procedure column as parameter or a result set col
244. dentifier null if not applicable to the data source TABLE_NAME VARCHAR 128 Primary key table identifier COLUMN_NAME VARCHAR 128 Primary key column identifier not NULL KEY_SEQ SMALLINT Column sequence number in key starting not NULL with 1 PK_NAME VARCHAR 128 Primary key identifier Null if not applicable See SOLBindCol SQLCancel SQLExtendedFetch SOLFetch SQLStatistics SQLProcedureColumns SQLProcedureColumns SQLProcedureColumns returns the list of input and output parameters as well as the columns that make up the result set for the specified procedures The driver returns the information as a result set on the specified hstmt Syntax RETCODE SQLProcedureColumns hstmt szProcQualifier cbProcQualifier szProcOwner cbProcOwner szProcName cbProcName szColumnName cbColumnName The SQLProcedureColumns function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szProcQualifier Input Procedure qualifier name If a driver supports qualifiers for some procedures but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those procedures that do not have qualifiers SWORD cbProcQualifier Input Length of szProcQualifier UCHAR FAR szProcOwner Input String search pattern for procedure owner names If a driver supports owners for some procedures but not for others such as when the dri
245. dure calls whose type cannot be determined are assumed to be input parameters The fParamType argument is one of the following values m SQL_PARAM_INPUT This parameter marks a parameter in an SQL statement that does not call a procedure such as an INSERT statement or it marks an input parameter in a procedure these are collectively known as input parameters For example the parameters in INSERT INTO Employee VALUES and call AddEmp are input parameters When the statement executes the driver sends data for the parameter to the data source the rgb Value buffer must contain a valid input value or the pcbValue buffer must contain SOL_NULL_DATA SQL_DATA_AT_EXEC or the result of the SQL_LEN_DATA_AT_EXEC macro If an application cannot determine the type of a parameter in a procedure call it sets fParamType to SOL_PARAM_INPUT if the data source returns a value for the parameter the driver discards it m SQL_PARAM_INPUT_OUTPUT The parameter marks an input output parameter ina procedure For example the parameter in call GetEmpDept is an input output parameter that accepts the name of an employee and returns the department name of the employee INFORMIX CLI Function Reference 12 29 SQL BindParameter 12 30 When the statement executes the driver sends data for the parameter to the data source the rgb Value buffer must contain a valid input value or the pcbValue buffer must contain SOL_NULL_DA
246. e VARCHAR 128 VARCHAR 128 VARCHAR 128 not NULL N A N A Comments Procedure qualifier identifier NULL if not applicable to the data source If a driver supports qualifiers for some procedures but not for others as when the driver retrieves data from different DBMSs it returns an empty string for those procedures that do not have qualifiers Procedure owner identifier NULL if not applicable to the data source If a driver supports owners for some procedures but not for others as when the driver retrieves data from different DBMSs it returns an empty string for those procedures that do not have owners Procedure identifier Reserved for future use Applications should not rely on the data returned in these result columns Reserved for future use Applications should not rely on the data returned in these result columns 1 of 2 INFORMIX CLI Function Reference 12 267 SQL Procedures 12 268 Column Name NUM_RESULT_SETS REMARKS PROCEDURE_TYPE Data Type N A VARCHAR 254 SMALLINT Comments Reserved for future use Applications should not rely on the data returned in these result columns A description of the procedure Defines the procedure type m SOL_PT_UNKNOWN It cannot be determined whether the procedure returns a value m SQL_PT_PROCEDURZ2E The returned object is a procedure that is it does not have a return value m SQL_PT_FUNCTION The returned
247. e a description of the condition but it is not intended to prescribe specific text INFORMIX CLI Function Reference 12 3 Arguments 12 4 Lprefix All INFORMIX following form Arguments CLI function arguments use a naming convention of the Jtaglqualifierllsuffix Optional elements appear in brackets and use the following prefixes Tag b col dbc env par row stmt SZ INFORMIX CLI Programmers Manual Prefix Description c Count of h Handle of i Index of p Pointer to rg Range array of The following tags are used Description Byte Column of a result set Database connection Environment Flag enumerated type Parameter of an SQL statement Row of a result set Statement Character string array of characters terminated by zero Value of unspecified type Arguments Prefixes and tags combine to correspond roughly to the typedefs for the standard C data types listed below Flags f and byte counts cb do not distinguish among SWORD UWORD SDWORD and UDWORD Combined Prefix cb Tag b Typedefs for Standard C Data Types Description SWORD SDWORD crow hdbc henv hstmt hwnd ib icol ipar irow pcb pccol pcpar pcrow phdbc c rT tT TN a pe pe pe pe row dbc env stmt wnd col par row col par row dbc UDWORD SDWORD UDWORD UWORD SWORD UWORD HDBC HENV HSTMT HWND
248. e driver can support This value can reflect a limitation that either the driver or the data source imposes If no limit is specified or the limit is unknown this value is set to 0 1 of 24 INFORMIX CLI Function Reference 12 193 SQL Getinto InfoType SOL_ACTIVE_STATEMENTS Returns A 16 bit integer value that specifies the maximum number of active hstmts that the driver can support for an hdbc This value can reflect a limitation that either the driver or the data source imposes If no limit is specified or the limit is unknown this value is set to 0 SOL_ALTER_TABLE A 32 bit bitmask that enumerates the clauses in the ALTER TABLE statement supported by the data source The following bitmask is used to determine which clauses are supported SOL_AT_ADD_COLUMN SOL_AT_DROP_COLUMN SOL_COLUMN_ALIAS A character string a Y if the data source supports column aliases otherwise m N is returned SOL_CONCAT_NULL_BEHAVIOR 12 194 INFORMIX CLI Programmers Manual A 16 bit integer value that indicates how the data source handles the concatenation of null valued character data type columns with non null valued character data type columns m SOL_CB_NULL Result is null valued m SOL_CB_NON_NULL Result is concatenation of non null valued column or columns 2 of 24 InfoType SQL_CONVERT_BIGINT SQL_CONVERT_BINARY SQL_CONVERT_BIT SQL_CONVERT_CHAR SQL_CONVERT_DATE SQL_CONVERT_DECIMAL
249. e file GetUserData retrieves the next MAX_DATA_LEN bytes of photo data from the file After it retrieves all the photo data it closes the photo file Some application routines are omitted for clarity iHdefine MAX_DATA_LEN 1024 SDWORD cbNameParam cbID 0 cbPhotoParam cbData SWORD sID PTR pToken InitValue UCHAR Data MAX_DATA_LEN retcode SQLPrepare hstmt INSERT INTO EMPLOYEE NAME ID PHOTO VALUES SQL_NTS if retcode SQL_SUCCESS Bind the parameters For parameters 1 and 3 pass the EJ parameter number in rgbValue instead of a buffer address E SQLBindParameter hstmt 1 SQL_PARAM_INPUT SQL_C_CHAR SQL_CHAR NAME_LEN 0 1 0 amp cbNameParam SQLBindParameter hstmt 2 SQL_PARAM_INPUT SQL_C_SSHORT SQL_SMALLINT 0 0 8sID 0 amp cbID SQLBindParameter hstmt 3 SQL_PARAM_INPUT SQL_C_BINARY SQL_LONGVARBINARY 0 0 3 0 amp cbPhotoParam Set values so data for parameters and 3 will be passed at execution Note that the length parameter in the macro SQL_LEN_DATA_AT_EXEC is 0 This assumes that the driver returns N for the SQL_NEED_LONG_DATA_LEN information xf type in SQLGetInfo cbNameParam cbPhotoParam SQL_LEN_DATA_AT_EXEC 0 sID GetNextID Get next available employee ID number retcode SQLExecute hstmt For data at execution parameters call SQLParamData to get the parameter number set by SQLBind
250. e is a valid INFORMIX CLI timestamp literal time portion is non zero 22008 Data value is not a valid INFORMIX CLI date literal or INFORMIX CLI timestamp literal SQL_TIMESTAMP Data value is a valid INFORMIX CLI N A timestamp literal fractional seconds portion not truncated 01004 Data value is a valid INFORMIX CLI timestamp literal fractional seconds portion N A truncated Data value is a valid INFORMIX CLI date N A literal 4 oe is a valid INFORMIX CLLEtime 22008 iteral Data value is not a valid INFORMIX CLI date literal INFORMIX CLI time literal or INFORMIX CLI timestamp literal 4 The time portion of the time stamp is truncated P The date portion of the time stamp is ignored The fractional seconds portion of the time stamp is truncated 4 The time portion of the time stamp is set to zero The date portion of the time stamp is set to the current date 2 of 2 When character C data is converted to date or time stamp SQL data leading and trailing blanks are ignored When character C data is converted to numeric date or time stamp SQL data leading and trailing blanks are ignored Data Types B 33 Converting Data from C to SQL B 34 When character C data is converted to binary SQL data each 2 bytes of character data are converted to a single byte 8 bits of binary data Each 2 bytes of character data represent a number in hexadecimal form For example 01 is converted to
251. e of the vParam argument and substituted a similar value function returns SQL_SUCCESS_WITH_INFO The communication link between the driver and the data source failed before the function completed The fOption was SOL_CONCURRENCY SQL_SIMULATE_CURSOR or SQL_CURSOR_TYPE and the cursor was open An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function 1 of 2 INFORMIX CLI Function Reference 12 297 SQL SetStmtOption 12 298 SQLSTATE Error Description S1009 Invalid argument Given the specified fOption value an invalid value value was specified for the argument vParam The driver manager returns this SQLSTATE only for statement options that accept a discrete set of values such as SQL_ASYNC_ENABLE For all other statement options the driver must verify the value of the argument vParam S1010 Function sequence DM SQLExecute or SQLExecDirect was called for error the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns 1011 Operation invalid The fOption was SOL_CONCURRENCY at this time SQL_SIMULATE_CURSOR or SOL_CURSOR_TYPE and the statement was prepared 1092 Option value ou
252. e time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 4 of 4 Usage The application calls SQLPrepare to send an SQL statement to the data source for preparation The application can include one or more parameter markers in the SQL statement To include a parameter marker the application embeds a question mark into the SQL string at the appropriate position Tip If an application uses SQLPrepare to prepare and SQLExecute to submit a COMMIT or ROLLBACK statement it is not interoperable among DBMS products To commit or roll back a transaction call SQLTransact The driver modifies the statement to use the form of SQL that the data source uses and then submits it to the data source for preparation In particular the driver modifies the escape clauses used to define ODBC specific SQL For the driver an hstmt is similar to a statement identifier in embedded SOL code If the data source supports statement identifiers the driver can send a statement identifier and parameter values to the data source 12 250 INFORMIX CLI Programmer s Manual SQLPrepare Once a statement is prepared the application uses hstmt to refer to the statement in later function calls The prepared statement associated with the hstmt might be re executed by calling SOLExecute until the application frees the hstmt with a call to SOLFreeStmt with the SOL_DROP option
253. e value of SOL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR equals SQL_CB_CLOSE SOLTransact closes all open cursors on all hstmts associated with the hdbc SQLTransact leaves any hstmt present in a prepared state the application can call SQLExecute for an hstmt associated with the hdbc without first calling SQLPrepare If the value of SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR equals SOL_CB_PRESERVE SQLTransact does not affect open cursors associated with the hdbc Cursors remain at the row to which they pointed before the call to SQLTransact For drivers and data sources that support transactions calling SOLTransact with either SQL_COMMIT or SQL_ROLLBACK when no transaction is active returns SQL_SUCCESS indicating that there is no work to be committed or rolled back and has no effect on the data source Drivers or data sources that do not support transactions SQLGetInfo fOption SQL_TXN_CAPABLE is 0 are effectively always in autocommit mode Therefore calling SOLTransact with SQL_COMMIT returns SOL_SUCCESS However calling SQLTransact with SOL_ROLLBACK results in SQLSTATE S1C00 Driver not capable indicating that a rollback can never be performed Related Functions For Information About See Returning information about a driver or data source SOLGetInfo Freeing a statement handle SOLFreeStmt 4 12 334 INFORMIX CLI Programmers Manual Setup Shared Library Function Reference Confio DSN i li hb
254. eates Although it might be obvious that the intent of the application is to use the one that the user owns it might not be obvious to the user which table to choose If the application specifies the OwnerName argument for the SOLTables call reliability and performance improve and only one table is returned Less network traffic is required to return only one result row and the data source filters unwanted rows To extend this example if the application can provide a value for the TableType argument the driver can optimize the SQL statement as in the following command SELECT FROM SysTables WHERE TableName Customers AND Owner Beth Designing Performance Oriented Applications 10 5 Determining Table Characteristics 10 6 Determining Table Characteristics When an application calls SQLColumns the database server must evaluate the query and form a result set to return to the client When the application makes a dummy query with SQLDescribeCol the database server does not execute the query it only prepares it Thus no results are sent back to the client Consider an application that allows the user to choose which columns to select The following pseudocode fragments and analysis illustrate the performance advantage of SQLDescribeCol Case 1 SQLColumns Method The following example uses SQLColumns rc SQLColumns UnknownTable This call to SQLColumns will generate a query to the sy
255. ecified in the fCType argument of SQLBindParameter for parameter data or SQLBindCol for column data Length of rgbValue Specifies the amount of data sent in a call to SQLPutData The amount of data can vary with each call for a given parameter or column cbValue is ignored unless it is SQL_NTS SOL_NULL_DATA or SOL_DEFAULT_PARAM the C data type specified in SOLBindParameter or SOLBindCol is SOL_C_CHAR or SQL_C_BINARY or the C data type is SQL_C_DEFAULT and the default C data type for the specified SQL data type is SQL_C_CHAR or SQL_C_BINARY For all other types of C data if cbValue is not SQL_NULL_DATA or SOL_DEFAULT_PARAM the driver assumes that the size of rgbValue is the size of the C data type specified with fCType and sends the entire data value For more information see Converting Data from C to SQL on page B 31 INFORMIX CLI Function Reference 12 271 SQL PutData SQLSTATE Error Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at t
256. ecifies the length of the rgbValue buffer if itis a single element If the application specifies multiple values cb ValueMax determines the location of values in the rebValue array both on input and on output For input output and output parameters it determines whether to truncate character and binary C data on output For character C data if the number of bytes available to return is greater than or equal to cbValueMax the data in rgbValue is truncated to cbValueMax 1 bytes and is null terminated by the driver For binary C data if the number of bytes available to return is greater than cbValueMax the data in rgbValue is truncated to cbValueMax bytes For all other types of C data the cbValueMax argument is ignored The length of the rgbValue buffer if it is a single element is assumed to be the length of the INFORMIX CLI C data type INFORMIX CLI Function Reference 12 31 SQL BindParameter 12 32 pcbValue Argument Value The length of the parameter value stored in rebValue SOL_NTS SOL_NULL_DATA SOL_DEFAULT_PARAM The result of the SQL_LEN_DATA_AT_EXEC length macro INFORMIX CLI Programmers Manual The pcbValue argument points to a buffer that when SQLExecute or SQLExecDirect is called contains one of the values in the following table Description This value is ignored except for character or binary C data The parameter value is a null terminated string The parameter value is NULL The
257. ecision 19 SOLBindParameter ignores the value of cbColDef for this data type Scale 0 SOLBindParameter ignores the value of ibScale for this data type Length 8 bytes Display size 20 digits One digit is for the sign SQL_BIT Precision 1 SOLBindParameter ignores the value of cbColDef for this data type Scale 0 SOLBindParameter ignores the value of ibScale for this data type Length 1 byte Display size 1 digit SOL_INFX_UDT_FIXED Precision Variable value To determine this value call a function that returns the precision for a column Scale Not applicable A function that returns the scale for a column returns 1 for this data type Length Variable value To determine this value call a function that returns the length for a column Display Size Variable value To determine this value call a function that returns the display size for a column SOL_INFX_UDT_VARYING Precision Variable value To determine this value call a function that returns the precision for a column Scale Not applicable A function that returns the scale for a column returns 1 for this data type Length Variable value To determine this value call a function that returns the length for a column Display Size Variable value To determine this value call a function that returns the display size for a column SOL_LONGVARCHAR See the description in the table for the standard SQL data types a Sees Da
258. ed and SQL_SUCCESS_WITH_INFO for the connection function if the driver returns an error for SOLSetConnectOption m If the driver is already loaded on the hdbc INFORMIX CLI calls only the connection function in the driver In this case the driver must ensure that all connection options for the hdbc maintain their current settings The driver then allocates handles and initializes itself When the application calls SOLDisconnect INFORMIX CLI calls SOLDisconmnect in the INFORMIX CLI driver However INFORMIX CLI does not unload the driver By keeping the driver in memory INFORMIX CLI makes the driver available for applications that repeatedly connect to and disconnect from a data source When the application calls SQLFreeConnect INFORMIX CLI calls SQLFreeConnect and SQLFreeEnv in the driver and then unloads the driver An INFORMIX CLI application can establish more than one connection After being loaded the INFORMIX CLI driver can locate its corresponding data source specification and use driver specific information from the speci fication to complete its set of required connection information INFORMIX CLI Function Reference 12 79 SQLConnect Code Example In the following example an application allocates environment and connection handles It then connects to the EmpData data source with the user ID JohnS and the password Sesame and processes data When it finishes processing data it disconnects from the data source and fr
259. ed 12 59 unbinding 12 22 uniquely identifying row 12 308 See also Results sets Retrieving data SQL data types Tables Comment icons Intro 6 COMMIT statements interoperability 5 9 12 115 SQLExecDirect 12 115 SQLExecute 12 121 Committing transactions 12 333 Compliance icons Intro 8 with industry standards Intro 12 Concurrency defined 6 11 serializing 6 11 specifying 12 295 supported types 12 211 ConfigDSN 13 3 ConfigTranslator 13 7 function description 13 7 Configuring data sources See Data sources configuring Conformance API 3 3 by function 12 180 determining 12 207 SQL 3 5 Connection handles active 12 193 allocating 4 4 defined 3 11 freeing 8 4 SQLAIlocConnect 12 9 SQLFreeConnect 12 155 Connection options access mode 12 102 commit mode 12 285 current qualifier 12 285 dialog boxes 12 287 login interval 12 286 maximum length 12 166 12 284 packet size 12 287 releasing 12 284 reserved 12 284 setting 12 284 tracing 12 286 Connection strings browse request 4 8 browse result 12 43 special characters 12 43 SQLDriverConnect 4 8 4 9 Connections dialog boxes 12 99 12 101 disconnecting 8 4 function summary 11 4 11 10 in embedded SQL C 9 SQLBrowseConnect 12 44 SQLConnect 12 79 SQLDisconnect 12 93 SQLDriverConnect 4 8 terminating browsing 12 45 Converting data C to SQL B 31 default conversions B 18 examples B 30 B 41 hexadecimal characters B 34 B 38 parameters 5 7 specifying conversions SQLBindCol 12 18
260. ed in SOLBindCol Requested field ROW_COUNT Dynamic SQL CLOSE Driver manager and driver memory deallocation None Association management Driver manager and driver memory deallocation Driver manager and driver memory deallocation None GET DIAGNOSTICS retrieves infor mation from the SQL diagnostics area that pertains to the most recently executed SQL statement This information can be retrieved following execution and preceding the deallocation of the statement 3 of 3 Embedded SQL to INFORMIX CLI Embedded SQL to INFORMIX CLI The following tables list the relationship between the X Open embedded SQL language and corresponding INFORMIX CLI functions The section number that appears in the first column of each table refers to the section of the X Open and SQL Access Group SQL CAE specification 1992 Declarative Statements The following table lists declarative statements Section 4 3 1 4 3 2 SQL Statement Static SQL DECLARE CURSOR Dynamic SQL DECLARE CURSOR INFORMIX CLI Function Comments none Issued implicitly by the driver if a cursor specification is passed to SOLExecDirect none The driver automatically generates the cursor To set a name for the cursor use SQLSetCursorName To retrieve a cursor name use SQLGetCursorName Data Definition Statements The following table lists data definition statements Section 5 1 2 5 1 3 5 1 4 5 1 5 5 1 6 5 1 7
261. ed state ments To use the cursor again the application must re prepare and re execute the hstmt m SQL_CB_CLOSE Close cursors For prepared statements the application can call SQLExecute on the hstmt without calling SQLPrepare again m SQL_CB_PRESERVE Preserve cursors in the same position as before the ROLLBACK operation The application can continue to fetch data or it can close the cursor and re execute the hstmt without re preparing it 4 of 24 InfoType SQL_DATA_SOURCE_NAME SQLGetInfo Returns A character string with the data source name used during connection If the application called SOLConnect this is the value of the szDSN argument If the application called SQLDriverConnect or SOLBrowseConnect this is the value of the DSN keyword in the connection string passed to the driver If the connection string did not contain the DSN keyword as when it contains the DRIVER keyword this is an empty string SQL_DATA_SOURCE_READ_ONLY A character string m Y if the data source is set to READ ONLY mode m N if it is otherwise This characteristic pertains only to the data source it is not a characteristic of the driver that enables access to the data source SQL_DATABASE_NAME A character string with the name of the current database in use if the data source defines a named object called database SQL_DBMS_NAME A character string with the name of the DBMS product accessed by
262. ed the maximum length value for the corresponding qualifier or name The maximum length of each qualifier or name can be obtained by calling SOLGetInfo with the fInfoType values SOL_MAX_QUALIFIER_NAME_LEN SOL_MAX_OWNER_NAME_LEN or SOL_MAX_TABLE_NAME_LEN DM An invalid fCol Type value was specified DM An invalid fScope value was specified DM An invalid fNullable value was specified A table qualifier was specified but the driver or data source does not support qualifiers A table owner was specified but the driver or data source does not support owners The driver or data source did not support the combination of the current settings of the SOL_CONCURRENCY and SOL_CURSOR_TYPE statement options The time out period expired before the data source returned the requested result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLSpecialColumns is provided so that applications can provide their own custom scrollable cursor functionality similar to the functionality that SQLExtendedFetch and SOLSetStmtOption provide INFORMIX CLI Function Reference 12 307 SQL SpecialColumns When the fColType argument is SOL_BEST_ROWID SOLSpecialColumns returns the column or columns that uniquely identify each row in the table These columns can always be used in a SELECT list or WHERE clause However SOLColumns does not necessarily return these columns If no columns uniquely identify each row
263. eed Data After SOLExecute or SQLExecDirect returns SQL_NEED_DATA and before data is sent for all data at execution parameters an application can call SOLCancel to cancel the statement execution After the statement is canceled the application can call SQLExecute or SQLExecDirect again For more infor mation see Passing Parameter Values on page 12 33 Canceling Functions in Multithreaded Applications Ina multithreaded application the application can cancel a function that runs synchronously on an hstmt To cancel the function the application calls SQLCancel with the same hstmt that the target function uses but on a different thread The return code of SQLCancel indicates whether or not the driver processed the request successfully The return code of the original function indicates whether the function completed normally or was canceled Related Functions For Information About See Assigning storage for a parameter SQLBindParameter Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute Freeing a statement handle SOLFreeStmt Returning the next parameter for which to send data SOLParamData Sending parameter data at execution time SOLPutData 4 INFORMIX CLI Function Reference 12 51 SQL ColAttributes SQLCol Attributes SQLColAttributes returns descriptor information for a column ina result set it cannot be used to return information about the bookmark column column 0 Descriptor inform
264. ees the handles HENV henv HDBC hdbc HSTMT hstmt RETCODE retcode retcode SQLA locEnv amp henv Environment handle if retcode SQL_SUCCESS retcode SQLAllocConnect henv amp hdbc Connection handle if retcode SQL_SUCCESS Connect to data source retcode SQLConnect hdbc EmpData SQL_NTS JohnS SQL_NTS Sesame SQL_NTS if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO Process data after successful connection retcode SQLAllocStmt hdbc amp hstmt Statement handle if retcode SQL_SUCCESS SOlFreeStmt hstmt SQL_DROP rl iO ee 12 80 INFORMIX CLI Programmers Manual Related Functions For Information About Allocating a connection handle Allocating a statement handle Discovering and enumerating values required to connect to a data source Disconnecting from a data source Connecting to a data source using a connection string or dialog box Returning the setting of a connection option Setting a connection option SQLConnect See SOLAllocConnect SOLAllocStmt SOLBrowseConnect SQLDisconnect SQLDriverConnect SQLGetConnectOption SQLSetConnectOption INFORMIX CLI Function Reference 12 81 SQLDataSources SQLDataSources SOLDataSources lists data source names Syntax RETCODE SQLDataSources henv fDirection szDSN cbDSNMax pcbDSN szDescription cbDescriptionMax pcbDescription The SQLDataSources f
265. efore it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application 2 of 3 INFORMIX CLI Function Reference 12 125 SQL ExtendedFetch SQLSTATE Error Description S1010 Function sequence DM The specified hstmt was not in an executed state The function was error called without first calling SQLExecDirect SQLExecute or a catalog function S1106 S1107 S1C00 S1T00 12 126 DM SOLExecute or SOLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM SOLExtendedFetch was called for an hstmt after SOLFetch was called and before SOLFreeStmt was called with the SOL_CLOSE option Fetch type out of DM The value specified for the argument fFetchType was invalid range The value of the SOL_CURSOR_TYPE statement option was SQL_CURSOR_FORWARD_ONLY and the value of argument fFetchType was not SQL_FETCH_NEXT Row value out of The value specified with the statement option SQL_CURSOR_TYPE was range SQL_CURSOR_KEYSET_DRIVEN but the value specified with the SQL_KEYSET_SIZE statement option was greater than 0 and less than the value specified with the SQL_ROWSET_SIZE statement option Driver not capable The driver or data source does not support the specified fetch type The driver or data source does not support the conversion specified by the combination of the fCType
266. el 2 Submitting SQL Requests The following table describes functions that submit SQL requests The following table describes functions that prepare SQL requests Purpose Allocates a statement handle Prepares an SQL statement for later execution Assigns storage for a parameter in an SQL statement Returns the cursor name associated with a statement handle Specifies a cursor name Sets options that control cursor behavior 11 6 INFORMIX CLI Programmers Manual ODBC Function Name Conformance Purpose SQLExecute Core Executes a prepared statement SOLExecDirect Core Executes a statement SOLNativeSql Level 2 Returns the text of an SOL statement as translated by the driver 1 of 2 Function Name SOLNumParams SQLParamData SQLPutData Retrieving Results and Information About Results ODBC Conformance Level 2 Level 1 Level 1 Purpose Returns the number of parameters in a statement Used with SQLPutData to supply parameter data at execution time Useful for long data values Sends part or all of a data value for a parameter Useful for long data values 2 of 2 Retrieving Results and Information About Results The following table describes functions that retrieve results and information about results ODBC Function Name Conformance Purpose SOLRowCount Core Returns the number of rows affected by an insert update or delete request SQLNumResultCols Core Retur
267. el of a connection an application calls SQLBrowseConnect and specifies the connection attributes and attribute values for that level First level connection attributes always include the data source name or driver description the connection attributes for later levels are data source dependent but might include the host user name and database Whenever an application calls SOLBrowseConnect it validates the current attributes returns the next level of attributes and returns a user friendly name for each attribute It can also return a list of valid values for those attributes After an application has specified each level of attributes and values SOLBrowseConnect connects to the data source and returns a complete connection string which SQLDriverConnect can use to connect to the data source at a later time Connection Strings Connection strings are used with both the SOLDriverConnect and the SOLBrowseConnect functions With these functions a connection string contains the following information Data source name or driver description Zero or one user ID Zero or one password Zero or more data source specific parameter values The connection string is a more flexible API than the data source name user ID and password that SOLConnect uses The application can use the connection string for multiple levels of login authorization or to convey other data source specific connection information Connecting to a Data Source 4 7 Con
268. emarks of their respective owners Documentation Team Twila Booth Lynne Casey Jennifer Leland To the extent that this software allows the user to store display and otherwise manipulate various forms of data including without limitation multimedia content such as photographs movies music and other binary large objects blobs use of any single blob may potentially infringe upon numerous different third party intellectual and or proprietary rights It is the user s responsibility to avoid infringements of any such third party rights RESTRICTED RIGHTS SPECIAL LICENSE RIGHTS Software and documentation acquired with US Government funds are provided with rights as follows 1 if for civilian agency use with Restricted Rights as defined in FAR 52 227 19 2 if for Dept of Defense use with rights as restricted by vendor s standard license unless superseded by negotiated vendor license as prescribed in DFAR 227 7202 Any whole or partial reproduction of software or documentation marked with this legend must reproduce the legend INFORMIX CLI Programmers Manual Chapter 1 Table of Contents Introduction About This Manual Types of Users 7 Software Dependencies Demonstration Database Documentation Conventions Typographical Conventions Icon Conventions Screen Illustration Conventions A Additional Documentation On Line Manuals Printed Manuals On Line Help Error Message Files Documentation Notes and Release No
269. ement that was not preparable or contained a syntax error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause 1 of 2 SQL NativeSq SQLSTATE Error Description S1001 Memory allocation The driver did not allocate memory required to failure support execution or completion of the function S1009 Invalid argument DM The argument szSqlStrIn was a null pointer value S1090 Invalid string or DM The argument cbSqlStrIn was less than 0 but buffer length not equal to SQL_NTS DM The argument cbSqlStrMax was less than 0 and the argument szSq Str was not a null pointer 2 of 2 Usage The following example shows what SOLNativeSql might return for an input SQL string that contains the scalar function LENGTH SELECT fn LENGTH NAME FROM EMPLOYEE An INFORMIX CLI driver might return the following translated SQL string SELECT length NAME FROM EMPLOYEE Related Functions None INFORMIX CLI Function Reference 12 235 SQLNumParams SQLNumParams SQLNumParams returns the number of parameters in an SQL statement Syntax RETCODE SQLNumParams hstmt pcpar The SOLNumParams function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle SWORD FAR pcpar Output Number of parameters in the sta
270. en cursor and can also be set through the crowRowset argument in SQLSetScrollOptions 40f 4 12 302 INFORMIX CLI Programmer s Manual SQLSetStmtOption Code Example See SOLExtendedFetch Related Functions For Information About See Canceling statement processing SOLCancel Returning the setting of a connection option SOLGetConnectOption Returning the setting of a statement option SOLGetStmtOption Setting a connection option SOLSetConnectOption INFORMIX CLI Function Reference 12 303 SQL SpecialColumns Syntax Use SQLSpecialColumns SQLSpecialColumns retrieves the following information about columns within a specified table The optimal set of columns that uniquely identifies a row in the table Columns that are automatically updated when any value in the row is updated by a transaction RETCODE SQLSpecialColumns hstmt fColType szTableQualifier cbTableQualifier szTableOwner cbTable0wner szTableName cbTableName fScope fNullable The SQLSpecialColumns function accepts the following arguments Argument Deputed Description HSTMT UWORD hstmt fColType UCHAR FAR szTableQualifier SWORD 12 304 INFORMIX CLI Programmers Manual cbTableQualifier Input Input Input Input Statement handle Type of column to return Must be one of the following values m SQL_BEST_ROWID Returns the optimal column or set of columns that by retrieving values from the colum
271. er 1 3 1 4 1 7 1 7 1 8 1 9 1 9 1 10 1 11 1 11 1 12 1 12 1 12 1 13 1 2 INFORMIX CLI Programmer s Manual his chapter introduces INFORMIX CLI describes the conformance isolation and lock levels and discusses the UNIX environment variables What Is INFORMIX CLI INFORMIX CLI is the Informix implementation of the Microsoft Open Database Connectivity ODBC standard INFORMIX CLI is a Call Level Interface that supports SOL statements with a library of C functions An application calls these functions to implement ODBC functionality Architecture INFORMIX CLI consists of the following parts m The INFORMIX CLI libraries These libraries provides the functions and values for the INFORMIX CLI application programming interface API m A driver manager A driver manager provides an interface between an INFORMIX CLI application and the INFORMIX CLI driver It also checks parameters and transitions The following table describes the driver manager requirements and options for each platform Environment Driver Manager UNIX On UNIX a driver manager is optional You may purchase a UNIX driver manager from a third party vendor Windows In Windows environments INFORMIX CLI provides the driver manager which is mandatory Overview of INFORMIX CLI 1 3 Architecture m The INFORMIX CLI driver The driver provides an interface between a data source and either a driver manager or an application de
272. er function with the hstmt or the hdbc associated with the hstmt the function returns SOL_ERROR and SOLSTATE S1010 Function sequence error If the application calls SOLCancel while the driver still needs data for data at execution parameters the driver stops executing the statement the appli cation can then call SQLExecute or SQLExecDirect again If the application calls SOLParamData or SOLPutData after it cancels the statement the function returns SOL_ERROR and SQLSTATE S1008 Operation canceled INFORMIX CLI Function Reference 12 35 SQL BindParameter Code Example In the following example an application prepares an SQL statement to insert data into the EMPLOYEE table The SQL statement contains parameters for the NAME AGE and BIRTHDAY columns For each parameter in the statement the application calls SOLBindParameter to specify the parameter s INFORMIX CLI C data type and INFORMIX CLI SQL data type and to bind a buffer to each parameter For each row of data the application assigns data values to each parameter and calls SOLExecute to execute the statement itdefine NAME_LEN 30 UCHAR szName NAME_LEN SWORD sAge SDWORD cbName SQL_NTS cbAge 0 cbBirthday 0 DATE_STRUCT dsBirthday retcode SQLPrepare hstmt INSERT INTO EMPLOYEE NAME AGE BIRTHDAY VALUES 2 SQL_NTS if retcode SQL_SUCCESS Specify data types and buffers zy for Name Age Birthday parameter data SQLBi
273. er generated cursor name can be obtained by calling SQLGetCursorName None Dynamic SQL Statements Dynamic SQL Statements The following table lists dynamic SQL statements Section 5 3 see 5 2 1 5 3 see 5 2 2 5 3 see 5 2 8 5 3 3 5 3 4 5 3 5 5 3 6 5 3 7 5 3 8 SQL Statement Dynamic SQL CLOSE Dynamic SQL Positioned DELETE Dynamic SQL Positioned UPDATE ALLOCATE DESCRIPTOR DEALLOCATE DESCRIPTOR DESCRIBE EXECUTE EXECUTE IMMEDIATE Dynamic SQL FETCH INFORMIX CLI Function Comments SQLFreeStmt SQL_CLOSE option SQLExecDirect DELETE FROM table name WHERE CURRENT OF cursor name SQLExecDirect UPDATE table name SET column identifier expression WHERE CURRENT OF cursor name None SQLFreeStmt SQL_DROP option none SQLExecute SQLExecDirect SQLFetch None Can also be invoked by SQLPrepare and SOLExecute Can also be invoked by SQLPrepare and SOLExecute Descriptor information is implicitly allocated and attached to the hstmt by the driver Allocation occurs at either the first call to SOLBindParameter or at SOLExecute or SOLExecDirect time None None None None None 1 of 2 Comparison of INFORMIX CLI and Embedded SQL C 7 Transaction Control Statements C 8 Section 5 3 9 5 3 10 5 3 11 5 3 12 Section 5 4 1 5 4 2 INFORMIX CLI Programmers Manual
274. ern include it twice m All other characters represent themselves For example if the search pattern for a table name is A the function returns all tables with names that contain the character A If the search pattern for a table name is B__ B followed by two underscores the function returns all tables with names that are three characters long and start with the character B If the search pattern for a table name is the function returns all tables If the search pattern for a table name is ABC the function returns the table named ABC If the search pattern for a table name is the function returns all tables with names that start with a backslash Failing to precede a metacharacter used as a literal with the escape character might return more results than expected For example if SOLTables returns a table identifier MY_TABLE and if an application wants to retrieve a list of columns for MY_TABLE using SOLColumns SQLColumns returns all the tables that match MY TABLE such as MY_TABLE MY1TABLE MY2TABLE and so on unless the escape character precedes the underscore Important A zero length search pattern matches the empty string A search pattern argument that is a null pointer means the search is not constrained for the argument A null pointer and a search string of should return the same values 12 8 INFORMIX CLI Programmers Manual SQLAl locConnect SOLAllocConnect SQLAIlocConnect allocates memory fo
275. ers SWORD cbTableOwner Input Length of szTableOwner UCHAR FAR szTableName Input String search pattern for table names SWORD cbTableName Input Length of szTableName INFORMIX CLI Function Reference 12 319 SQL TablePrivileges Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_ HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source failed before the function completed 24000 Invalid cursor state A cursor was already opened on the statement handle S1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the arg
276. erved space r 0 lt r lt m Calendar date Calendar date and time of day Signed numeric value with precision p and scale s 1 lt p lt 32 0 lt s lt p Signed numeric value with the same characteristics as the double data type in C Signed numeric value with the same characteristics as the double data type in C Signed numeric value with precision 10 scale 0 and range n 2 147 483 647 lt n lt 2 147 483 647 Signed numeric value with precision p and scale s 1 lt p lt 32 0 lt s lt p Signed numeric value with precision p and scale s 1 lt p lt 32 0 lt s lt p 1 of 2 B 2 INFORMIX CLI Programmers Manual Additional SQL Data Types for GLS Informix SQL INFORMIX CLI SQL Data Type Data Type fSqlType Description REAL SQL_REAL Signed numeric value with the same characteristics as the float data type in C SERIAL SQL_INTEGER Sequential INTEGER SMALLFLOAT SQL_REAL Signed numeric value with the same characteristics as the float data type in C SMALLINT SQL_SMALLINT Signed numeric value with precision 5 scale 0 and range n 32 767 lt n lt 32 767 TEXT SQL_LONGVARCHAR Character string of variable length VARCHAR m r GLS SQL_VARCHAR Character string of variable length with maximum length m 1 lt m lt 255 and minimum amount of reserved space r 0 lt r lt m 2 of 2 Additional SQL Data Types for GLS The following table lists the additional Informix SQL data types for GLS and their c
277. es accessibility 12 193 cardinality 12 317 columns See Columns correlation names 12 195 defined 12 7 foreign keys 12 148 in SELECT statement 12 205 indexes See Indexes maximum columns in 12 204 names maximum length 12 205 retrieving 12 315 12 322 special characters 12 212 SQLColumnPrivileges 12 65 SQLColumns 12 71 SQLTables 12 328 12 329 owner names See Owner names pages 12 317 primary keys 12 148 12 256 qualifiers See Qualifiers rows See Rows statistics 12 314 term vendor specific 12 213 types 12 329 versus views 12 7 Termination byte null See Null termination byte Terms vendor specific owner 12 208 procedure 12 209 qualifier 12 209 table 12 213 TEXT data type B 3 Threads multiple with connection handles 12 11 with environment handles 12 13 with statement handles 12 17 Time out login 12 286 query 12 302 Time stamp data B 11 converting to C B 29 converting to SQL B 40 TIMESTAMPADD intervals 12 214 TIMESTAMPDIFF intervals 12 214 TIMESTAMP_STRUCT typedef B 11 Trace file 12 286 Tracing SQLFreeEnv 12 159 Traffic network maximum data length 12 301 packet size 12 287 prepared statements 5 6 Index 11 Transactions beginning 5 9 12 333 commit mode 5 9 12 285 committing 5 9 12 333 concurrency See Concurrency cursor behavior 12 333 function equivalents C 8 incomplete 12 93 interoperability 5 9 isolation levels 12 198 multiple active 12 205 rolling back 5 9 12 333 serializing 6 11
278. es that do not have qualifiers SWORD cbTableQualifier Input Length of szTableQualifier UCHAR FAR szTableOwner Input Table owner If a driver supports owners for some tables but not for others as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have owners SWORD cbTableOwner Input Length of szTableOwner UCHAR FAR szTableName Input Table name SWORD cbTableName Input Length of szTableName INFORMIX CLI Function Reference 12 253 SQLPrimaryKeys Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source failed before the fu
279. es that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value INFORMIX CLI Function Reference 12 281 SQL SetConnectOption 12 282 action 01000 01502 08002 08003 08501 IM009 S1000 1001 SQLSTATE Error General warning Option value changed Connection in use Connection not open Communication link failure Unable to load translation shared library General error Memory allocation failure INFORMIX CLI Programmers Manual The driver can return SOL_SUCCESS_WITH_INFO to provide information about the result of setting an option For example setting SOL_ACCESS_MODE to read only during a transaction might cause the trans action to be committed The driver could use SOL_SUCCESS_WITH_INFO and information returned with SQLError to inform the application of the commit Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The driver did not support the specified value of the vParam argument and substituted a similar value function returns SQL_SUCCESS_WITH_INFO The argument fOption was SQL_ODBC_CURSORS and the driver was already connected to the data source An fOption value was specified that required an open connection but the hdbc was not in a connected state The communication link between the driver and the data source failed before the function completed The driver was unable to load the tr
280. escription DSN Name of a data source as returned by SOLDataSources or the data sources dialog box of SOLDriverConnect DRIVER Description of the driver as returned by the SQLDrivers function UID The user ID or account name for access to the data source PWD The password that corresponds to the user ID or an empty string if no password exists for the user ID PWD 1 of 2 INFORMIX CLI Programmer s Manual Windows Attribute Keyword ConnectDatabase Database Exclusive Host Protocol Server Service Connection Strings Attribute Value Description A character string This option is available inside a connection string only Yes Connect to the database that is specified in the DSN setup or in the configuration string This is the default setting No Connect to the database server only Name of the database to which you want to connect by default A character string This option is available inside a connection string only Yes Specify that the application has exclusive use of the database No Share database access This is the default setting The name of the computer on which the Informix database server resides The protocol used to communicate with the database server In Windows environments values can be xxSOCTCP or xxSOCSPX where xx represents OL ON or SE 4 The name of the database server on which the database that you want to access resides The name assigned to the database serve
281. etInfo Returns A 32 bit bitmask that enumerates the supported positioned SQL statements The following bitmasks are used to determine which statements are supported SQL_PS_POSITIONED_DELETE SQL_PS_POSITIONED_UPDATE SQL_PS_SELECT_FOR_UPDATE SQL_PROCEDURE_TERM A character string with the data source vendor name for a procedure for example database procedure stored procedure or procedure SQL_PROCEDURES A character string m Y if the data source supports procedures and the driver supports the ODBC procedure invocation syntax m N otherwise SQL_QUALIFIER_LOCATION A 16 bit integer value that indicates the position of the qualifier in a qualified table name SQL_OL_START SQL_OL_END For example a Text driver returns SQL_QL_START because the directory qualifier name is at the start of the table name as in empdata emp dbf SQL_QUALIFIER_NAME_SEPARATOR A character string the character or characters that the data source defines as the separator between a qualifier name and the qualified name element that follows it SQL_QUALIFIER_TERM A character string with the data source vendor name for a qualifier for example database or directory 17 of 24 INFORMIX CLI Function Reference 12 209 SQL Getinfo InfoType SQL_QUALIFIER_USAGE Returns A 32 bit bitmask that enumerates the statements in which quali fiers can be used The fol
282. eter marker at any time by calling SOLBindParameter An application can also change the value in a storage location at any time When a statement is executed the driver uses the current values in the most recently defined storage locations INFORMIX CLI Programmers Manual Performing Transactions Performing Transactions In auto commit mode every SQL statement is a complete transaction that is committed automatically In manual commit mode a transaction consists of one or more statements In manual commit mode when an application submits an SQL statement and no transaction is open the driver implicitly begins a transaction The transaction remains open until the application commits or rolls the transaction back with SOLTransact For INFORMIX CLI the default transaction mode is auto commit An appli cation calls SOLSetConnectOption to switch between manual commit and auto commit mode If an application switches from manual commit to auto commit mode the driver commits any open transactions on the connection Applications should call SQLTransact to commit or roll back a transaction rather than submitting a COMMIT or ROLLBACK statement The result of a COMMIT or ROLLBACK statement depends on the driver and its associated data source Important Committing or rolling back a transaction either by calling SQLTransact or by using the SQL_AUTOCOMMIT connection option can cause the data source to close the cursors and delete the ac
283. eturns the hdbc to an uncon nected state If an application calls SOLDisconnect while an incomplete transaction is associated with the connection handle the driver returns SOLSTATE 25000 Invalid transaction state indicating that the transaction is unchanged and the connection is open An incomplete transaction is one that was not committed or rolled back with SOLTransact If an application calls SOLDisconnect before it frees every hstmt associated with the connection the driver frees each remaining hstmt after it success fully disconnects from the data source Code Example See SOLBrowseConnect and SOLConnect Related Functions For Information About See Allocating a connection handle SOLAllocConnect Connecting to a data source SOLConnect Connecting to a data source using a connection string or SOLDriverConnect dialog box Freeing a connection handle SOLFreeConnect Executing a commit or rollback operation SOLTransact 4 INFORMIX CLI Function Reference 12 93 SQL DriverConnect SQLDriverConnect SQLDriverConnect is an alternative to SQLConnect It supports data sources that require more connection information than the three arguments in SQLConnect dialog boxes to prompt the user for all connection information and data sources that are not defined data source names SQLDriverConnect provides the following connection options m You can establish a connection using a connection string that contains the data source name o
284. ever columns on the left side of the comparison operator in the ON clause must come from the left hand table in the outer join and columns on the right side of the comparison operator must come from the right hand table Also the right hand table of an outer join cannot be included in an inner join m F Full The data source fully supports nested outer joins and the driver supports the ODBC outer join syntax SQL_OWNER_TERM A character string with the data source vendor name for an owner for example owner Authorization ID or Schema SQL_OWNER_USAGE A 32 bit bitmask that enumerates the statements in which owners can be used m SQL_OU_DML_STATEMENTS Owners are supported in all Data Manipulation Language statements SELECT INSERT UPDATE DELETE and if supported SELECT FOR UPDATE and positioned UPDATE and DELETE statements m SQL_OU_PROCEDURE_INVOCATION Owners are supported in the ODBC procedure invocation statement m SQL_OU_TABLE_DEFINITION Owners are supported in all table definition statements CREATE TABLE CREATE VIEW ALTER TABLE DROP TABLE and DROP VIEW m SQL_OU_INDEX_DEFINITION Owners are supported in all index definition statements CREATE INDEX and DROP INDEX m SQL_OU_PRIVILEGE_DEFINITION Owners are supported in all privilege definition statements GRANT and REVOKE 16 of 24 12 208 INFORMIX CLI Programmer s Manual InfoType SQL_POSITIONED_STATEMENTS SQLG
285. ew rows of data INFORMIX CLI Programmers Manual SQLExtendedFetch 4 The application calls SQLBindCol for each column to be bound m The rgbValue argument specifies the address of the data field of the column in the first array element m The cbValueMax argument specifies the size of the data field of the column m The pcbValue argument specifies the address of the number of bytes field of the column in the first array element When the application calls SQLExtendedFetch the driver retrieves the data and the number of bytes that are available to return and stores them in the buffers that are allocated by the application m For each bound column the driver stores the first row of data at the address specified by rgbValue for the column and each subsequent row of data at an offset of vParam bytes from the data for the previous row m For each bound column the driver stores the number of bytes that are available to return for the first row at the address that pcbValue specifies and the number of bytes that are available to return for each subsequent row at an offset of vParam bytes from the value for the previous row This is the number of bytes that are available prior to calling SQLExtendedFetch If the number of bytes that are available to return cannot be determined in advance the driver sets pcbValue to SOL_NO_TOTAL If the data for the column is NULL the driver sets pcbValue to SQL_NULL_DATA Positioning the Cur
286. f no limit is specified or the limit is unknown this value is set to 0 11 of 24 INFORMIX CLI Function Reference 12 203 SQL Getinfo InfoType Returns SQL_MAX_COLUMNS_IN_SELECT A 16 bit integer value that specifies the maximum number of columns allowed in a SELECT list If no limit is specified or the limit is unknown this value is set to 0 SQL_MAX_COLUMNS_IN_TABLE A 16 bit integer value that specifies the maximum number of columns allowed in a table If no limit is specified or the limit is unknown this value is set to 0 SQL_MAX_CURSOR_NAME_LEN A 16 bit integer value that specifies the maximum length of a cursor name in the data source If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_INDEX_SIZE A 32 bit integer value that specifies the maximum number of bytes allowed in the combined fields of an index If no limit is specified or the limit is unknown this value is set to 0 SQL_MAX_OWNER_NAME_LEN A 16 bit integer value that specifies the maximum length of an owner name in the data source If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_PROCEDURE_NAME_LEN A 16 bit integer value that specifies the maximum length of a procedure name in the data source If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_QUALIFIER_NAME_LEN A 16 bit integer value that specifies the maximum length of a quali
287. ference GLS For information about the Global Language Support GLS environment variables see the Informix Guide to GLS Functionality 1 10 INFORMIX CLI Programmers Manual GLS GLS GLS Informix products can support many languages cultures and code sets GLS provides support for all language and culture specific information The following table describes how to set the GLS options depending on your platform Environment How to Set GLS Options UNIX Specify the GLS options in the odbc ini file For more information see Configuring Data Sources on UNIX on page 2 9 Windows Specify the GLS options in the INFORMIX CLI DSN Setup dialog box For more information see Configuring Data Sources on Windows on page 2 3 The rest of this section describes the GLS options for INFORMIX CLI For more information about GLS and locales see the Informix Guide to GLS Functionality Client Locale Description Locale and codeset that the application runs in Format locale codeset modifier odbc ini field for UNIX CLIENT_LOCALE Default value for Windows en_us 1252 Overview of INFORMIX CLI 1 11 Database Locale Database Locale Description Format odbc ini field for UNIX Default value for Windows Translation Library Description Format odbc ini field for UNIX Default value for Windows Translation Option Description Format odbc ini field for UNIX Default value for Wi
288. ference 12 199 SQL Getinfo InfoType SQL_FETCH_DIRECTION Returns A 32 bit bitmask that enumerates the supported fetch direction options The following bitmasks are used in conjunction with the flag to determine which options are supported SQL_FD_FETCH_NEXT SQL_FD_FETCH_FIRST SOL_FD_FETCH_LAST SOL_FD_FETCH_PRIOR SOL_FD_FETCH_ABSOLUTE SOL_FD_FETCH_RELATIVE SOL_FD_FETCH_RESUME SOL_FILE_USAGE 12 200 INFORMIX CLI Programmer s Manual A 16 bit integer value that indicates how a single tier driver directly treats files in a data source m SQL_FILE_NOT_SUPPORTED The driver is not a single tier driver m SQL_FILE_TABLE A single tier driver treats files in a data source as tables For example a text driver treats each text file as a table m SQL_FILE_QUALIFIER A single tier driver treats files in a data source as a qualifier 8 of 24 InfoType SQL_GETDATA_EXTENSIONS SQLGetInfo Returns A 32 bit bitmask that enumerates extensions to SOLGetData The following bitmasks are used in conjunction with the flag to determine what common extensions the driver supports for SQLGetData SQL_GD_ANY_COLUMN SOLGetData can be called for any unbound column including those before the last bound column The columns must be called in order of ascending column number unless SOL _GD_ANY_ORDER is also returned SOL_GD_ANY_ORDER SOLGetData can be called for unbound columns in any order SOLGetData can
289. fier name in the data source If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_ROW_SIZE A 32 bit integer value that specifies the maximum length of a single row in a table If no limit is specified or the limit is unknown this value is set to 0 SQL_MAX_ROW_SIZE_INCLUDES_LONG A character string a Y if the maximum row size returned for the SQL_MAX_ROW_SIZE information type includes the length of all SOL_ LONGVARCHAR and SQL_LONGVARBINARY columns in the row m N otherwise SQL_MAX_STATEMENT_LEN A 32 bit integer value that specifies the maximum length number of characters including white space of an SQL statement If there is no maximum length or the length is unknown this value is set to 0 12 of 24 12 204 INFORMIX CLI Programmers Manual InfoType SQL_MAX_TABLE_NAME_LEN SQLGetInfo Returns A 16 bit integer value that specifies the maximum length of a table name in the data source If there is no maximum length or the length is unknown this value is set to 0 SQL_MAX_TABLES_IN_SELECT A 16 bit integer value that specifies the maximum number of tables allowed in the FROM clause of a SELECT statement If there is no specified limit or the limit is unknown this value is set to 0 SQL_MAX_USER_NAME_LEN A 16 bit integer value that specifies the maximum length of a user name in the data source If there is no maximum length or the length is
290. g attribute value The browse result connection string has the following syntax connection string attribute attribute connection string attribute Jattribute keyword attribute value attribute keyword ODBC attribute keyword driver defined attribute keyword ODBC attribute keyword UID PWD localized identifier driver defined attribute keyword identifer localized identifier attribute value attribute value list The braces are literal they are returned by the driver attribute value list character string character string attribute value list In this example character string has zero or more characters identifier and localized identifier have one or more characters attribute keyword is not case sensitive and attribute value might be case sensitive Because of connection string and initialization file grammar avoid keywords localized identifiers and attribute values that contain the characters Because of the registry grammar keywords and data source names cannot contain a backslash INFORMIX CLI Function Reference 12 43 SQLBrowseConnect 12 44 The browse result connection string syntax is used according to the following semantic rules m Ifan asterisk precedes an attribute keyword the attribute is optional and can be omitted in the next call to SOLBrowseConnect m Anattribute keyword names the kind of attribute for which an attribute value
291. g arguments for SQLError szSQLState S0002 pfNativeError 206 szErrorMsg Informix ODBC Informix Driver LInformix The specified table EMPLOYEE is not in the database pcbErrorMsg 96 Because the error occurred in the data source the driver added a prefix for the data source identifier Informix to the error text Because the driver component interfaced with the data source it adds prefixes for its vendor Informix and identifier ODBC Informix Driver to the error text For a description of an error that the data source returns look up the error message number in the Informix Error Messages manual Processing Error Messages You can provide your users with the error information that SQLError returns the SQLSTATE the error message number the error message and the corrective action You must parse the text to separate the error message from the corrective action You need to take the appropriate action based on the error or provide the user with a choice of actions Retrieving Status and Error Information 7 7 Retrieving Error Messages 7 8 Retrieving Error Messages If a function other than SQLError returns SQL_ERROR or SOL_SUCCESS_WITH_INFO an application can call SQLError to obtain additional information The application might need to call SOLError more than once to retrieve all the error messages from a function because a function might return more than one error message When the application calls a
292. g containing the name of the qualifier to be used by the data source For a single tier driver the qualifier might be a directory in which case the driver changes its current directory to the directory specified in vParam 1 of 4 INFORMIX CLI Function Reference 12 285 SQL SetConnectOption fOption SQL_LOGIN_TIMEOUT SOL_ODBC_CURSORS SOL_OPT_TRACE SOL_OPT_TRACEFILE vParam Contents A 32 bit integer value corresponding to the number of seconds to wait for a login request to complete before returning to the application The default is driver dependent and must be nonzero If vParam is 0 the time out is disabled and a connection attempt will wait indefinitely If the specified time out exceeds the maximum login time out in the data source the driver substitutes that value and returns SQLSTATE 01502 Option value changed A 32 bit option specifying how the driver manager uses the ODBC cursor library m SQL_CUR_USE_IF_NEEDED INFORMIX CLI uses the ODBC cursor library only if it is needed If INFORMIX CLI supports the SQL_FETCH_PRIOR option in SOLExtendedFetch it uses its scrolling capabilities Otherwise it uses the cursor library m SQL_CUR_USE_ODBC INFORMIX CLI uses the cursor library m SQL_CUR_USE_DRIVER INFORMIX CLI uses its scrolling capabilities This is the default setting Informix recommends that you use SQL_CUR_USE_DRIVER For more infor mation about the ODBC cursor library see the Microsoft ODBC Pro
293. grammer s Reference and SDK Guide Version 2 0 A 32 bit integer value telling INFORMIX CLI whether to perform tracing m SQL_OPT_TRACE_OFF Tracing off the default m SQL_OPT_TRACE_ON Tracing on When tracing is on INFORMIX CLI writes each INFORMIX CLI function call to the trace file When tracing is on INFORMIX CLI can return SQLSTATE IM013 Trace file error from any function An application specifies a trace file with the SQL_OPT_TRACEFILE option If the file already exists INFORMIX CLI appends to the file Otherwise it creates the file If tracing is on but no trace file is specified INFORMIX CLI writes to the file sql log in the current directory A null terminated character string containing the name of the trace file 2 of 4 12 286 INFORMIX CLI Programmer s Manual fOption SQL_PACKET_SIZE SQL_QUIET_MODE SQL_TRANSLATE_OPTION SQL SetConnectOption vParam Contents A 32 bit integer value specifying the network packet size in bytes Many data sources either do not support this option or can only return the network packet size If the specified size exceeds the maximum packet size or is smaller than the minimum packet size the driver substitutes that value and returns SQLSTATE 01502 Option value changed A 32 bit window handle hwnd If the window handle is a null pointer the driver does not display any dialog boxes If the window handle is not a null pointer it should be the parent window
294. grantee to update all columns in a table on one data source and only those columns for which the grantor has the UPDATE privilege on another data source Indicates whether the grantee is permitted to grant the privilege to other users YES NO or NULL if unknown or not applicable to the data source 2 of 2 INFORMIX CLI Function Reference 12 323 SQL TablePrivileges 12 324 Code Example Related Functions For a code example of a similar function see SQLColumns INFORMIX CLI Programmer s Manual For Information About See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SOLCancel Returning privileges for a column or columns SOLColumnPrivileges Returning the columns in a table or tables SOLColumns Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SOLFetch Returning table statistics and indexes SOLStatistics Returning a list of tables in a data source SOLTables SQL Tables SQLTables SQLTables returns the list of table names that are stored in a specific data source The driver returns this information as a result set Syntax RETCODE SQLTables hstmt szTableOwner szTableType cbTable0wner cbTableType szTableQualifier cbTableQualifier szTableName cbTableName The SOLTables function accepts the following arguments Typedef HSTMT UCHAR FAR SWORD UCHAR FAR SWORD UCHAR
295. gs and errors that derive from the implemen tation of INFORMIX CLI The subclass value 000 in any class is for implementation defined conditions within the given class ANSI SQL 92 defines the assignment of class and subclass values Tables and Views In INFORMIX CLI functions tables and views are interchangeable The term table is used for tables and views except where view is used explicitly Catalog Functions The functions listed in Retrieving Information About Data Source System Tables on page 11 8 are catalog functions that return information about a data source catalog INFORMIX CLI Function Reference 12 7 Search Pattern Arguments Search Pattern Arguments Each catalog function returns information in the form of a result set The information that a function returns can be constrained by a search pattern passed as an argument to that function These search patterns can contain the underscore _ the percent symbol and a driver defined escape character as follows m The underscore represents any single character m The percent symbol represents any sequence of zero or more characters m The escape character backslash permits the underscore and percent metacharacters to be used as literal characters in search patterns To use a metacharacter as a literal character in the search pattern precede it with the escape character To use the escape character as a literal character in the search patt
296. gth of szTableQualifier String search pattern for owner names Ifa driver supports owners for some tables but not for others such as when the driver retrieves data from different data sources an empty string denotes those tables that do not have owners Length of szTableOwner String search pattern for table names Length of szTableName String search pattern for column names Length of szColumnName SQLColumns Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source failed before the function completed 24000 Invalid cursor state A cursor was already opened on the statement
297. h function description 12 123 retrieving rowsets 6 9 with SQLGetData 6 9 with SQLSetStmtOption 12 126 SQLFetch fetching data 6 5 function description 12 138 positioning cursor 6 6 with SQLBindCol 12 141 with SQLGetData 12 141 SQLFreeConnect function description 12 155 with SQLDisconnect 12 156 with SQLFreeEnv 12 159 See also Connection handles SQLFreeEnv function description 12 158 with SQLFreeConnect 12 159 See also Environment handles 10 INFORMIX CLI Programmer s Manual SQLFreeStmt function description 12 161 unbinding columns 12 22 unbinding parameters 12 29 See also Statement handles SQLGetConnectOption 12 164 SQLGetCursorName 12 167 SQLGetData function description 12 170 interoperability 6 7 6 9 long data values 6 7 12 21 unbound columns 6 7 with SQLExtendedFetch 6 9 with SQLFetch 12 141 SQLGetFunctions 12 178 SQLGetInfo data sources 12 190 DBMSs 12 190 drivers 12 189 function description 12 184 scalar functions 12 193 SQL statements 12 191 SQLGetStmtOption function description 12 218 SQLGetTypelnfo function description 12 222 supported data types 3 12 sqlhosts 2 9 SQLMoreResults 12 230 SQLNativeSql 12 233 SQLNumParams 12 236 SQLNumkResultCols 6 5 12 239 SQLParamData data at execution parameters 5 10 function description 12 242 with SQLBindParameter 12 31 12 33 with SQLPutData 12 242 SQLParamOptions with SQLBindParameter 12 31 SQLPrepare function description
298. h SQLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 The szTableOwner and szIableName arguments accept search patterns For more information about valid search patterns see Search Pattern Arguments on page 12 8 SQLTablePrivileges returns the results as a standard result set ordered by TABLE_QUALIFIER TABLE_OWNER TABLE_NAME and PRIVILEGE The following table lists the columns in the result set Important SQLTablePrivileges might not return privileges for all tables Applica tions can use any valid table regardless of whether SQLTablePrivileges returns it INFORMIX CLI Function Reference 12 321 SQL TablePrivileges 12 322 Column Name TABLE_QUALIFIER TABLE_OWNER TABLE_NAME GRANTOR GRANTEE INFORMIX CLI Programmer s Manual Informix SQL Data Type VARCHAR 128 VARCHAR 128 VARCHAR 128 not NULL VARCHAR 128 VARCHAR 128 not NULL The lengths of VARCHAR columns shown in the table are maximums the actual lengths depend on the data source To determine the actual lengths of the TABLE_QUALIFIER TABLE_OWNER and TABLE_NAME columns an application can call SOLGetInfo with the SOL_MAX_QUALIFIER_NAME_LEN SOL_MAX_OWNER_NAME_LEN and SQL_MAX_TABLE_NAME_LEN options Comments Table qualifier identifier NULL if not appli cable to the data source If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty
299. h to return the entire list of attribute value pairs so the list was truncated The argument pcbDrvrAttr contains the length of the untruncated list of attribute value pairs function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause DM The driver manager did not allocate memory required to support execution or completion of the function DM The value specified for argument cbDriverDescMax was less than 0 DM The value specified for argument cbDrorAttrMax was less than 0 or equal to 1 DM The value specified for the argument fDirection was not equal to SOL_FETCH_FIRST or SQL_FETCH_NEXT INFORMIX CLI Function Reference 12 105 SQL Drivers Usage SQLDrivers returns the driver description in the szDriverDesc argument It returns additional information about the driver in the szDriverAttributes argument as a list of keyword value pairs Each pair is terminated with a null byte and the entire list is terminated with a null byte that is 2 null bytes mark the end of the list Tf szDriverAttributes cannot hold the entire list the list is truncated SQLDrivers returns SOLSTATE 01004 Data truncated and the length of the list excluding the final null termination byte is returned in pebDrorAttr Driver attribute keyword
300. h your Informix products You can install the documentation or access it directly from the CD For information about how to install read and print on line manuals see the installation insert that accompanies Answers OnLine Printed Manuals To order printed manuals call 1 800 331 1763 or send email to moreinfo informix com When you place an order please provide the following information m The documentation that you need m The quantity that you need m Your name address and telephone number Introduction 9 On Line Help On Line Help The ODBC Administrator graphical interface contains Help screens that provides information on how to configure a data source Error Message Files Informix software products provide ASCII files that contain all of the Informix error messages and their corrective actions The finderr utility displays these error messages on the screen See the Introduction to the Informix Error Messages manual for a detailed description of these error messages To read the error messages in the ASCII file Informix provides scripts that let you display error messages on the screen finderr or print formatted error messages rofferr For a detailed description of these scripts see the Introduction to the Informix Error Messages manual Informix Find Error is a graphical tool This utility has been created with Microsoft help facilities For more information see the Introduction to the Informix Error Mes
301. handles provide memory storage for information about SQL state ments You should use statement handles to manage multiple SOL statements instead of connecting and disconnecting several times to execute the SQL statements Retrieving Information About a Data Source Catalog functions are slow compared to all other INFORMIX CLI functions The functions listed in Retrieving Information About Data Source System Tables on page 11 8 are catalog functions that return information about a data source catalog SOLGetTypelnto is also a potentially expensive function and is included in this discussion of catalog functions Minimizing the Use of Catalog Functions Although you probably need to use catalog functions to write an ODBC compliant application use them sparingly To return the necessary result set for a single call to a catalog function a driver might have to perform multiple queries joins subqueries and unions For this reason frequent use of catalog functions in an application will likely result in poor performance If possible your application should eliminate the need for multiple execu tions by caching information that is returned from catalog functions For example the application might call SOLGetTypelnfo once and cache the elements of the result set on which the application depends Few applications use all elements of the result set that a catalog function generates so the cache of information should not be difficult to
302. hat indicates SQL grammar supported by the driver m SQL_OSC_MINIMUM Minimum grammar supported m SQL_OSC_CORE Core grammar supported m SQL_OSC_EXTENDED Extended grammar supported SQL_ODBC_SQL_OPT_IEF A character string a Y if the data source supports the optional Integrity Enhancement Facility m N if it does not SQL_ODBC_VER A character string with the version of ODBC to which the driver manager conforms if you are using a driver manager The version is of the form where the first two digits are the major version and the next two digits are the minor version SQL_ORDER_BY_COLUMNS_IN_SELECT A character string m Y if the columns in the ORDER BY clause must be in the SELECT list m N otherwise 15 of 24 INFORMIX CLI Function Reference 12 207 SQL Getinfo InfoType Returns SQL_OUTER_JOINS A character string m N No The data source does not support outer joins m Y Yes The data source supports two table outer joins and the driver supports the ODBC outer join syntax except for nested outer joins However columns on the left side of the comparison operator in the ON clause must come from the left hand table in the outer join and columns on the right side of the comparison operator must come from the right hand table m P Partial The data source partially supports nested outer joins and the driver supports the ODBC outer join syntax How
303. he beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 01004 Data truncated The data sent for a character or binary parameter or column in one or more calls to SOLPutData exceeded the maximum length of the associated character or binary column The fractional part of the data sent for a numeric or bit parameter or column was truncated Time stamp data sent for a date or time parameter or column was truncated 08S01 Communication The communication link between the driver and the data source failed link failure before the function completed 22001 String data right The SOL_NEED_LONG_DATA_LEN information type in SOLGetInfo was truncation Y and more data was sent for a long parameter the data type was SQL_LONGVARCHAR SQL_LONGVARBINARY or a long data source specific data type than was specified with the pcbValue argument in SQLBindParameter 1 of 2 12 272 INFORMIX CLI Programmer s Manual SQLSTATE Error 22003 22005 22008 S1000 S1001 S1008 S1009 S1010 S1090 S1T00 Numeric value out of range Error in assignment Datetime field overflow General error Memory allocation failure Operation canceled Invalid argument value Function sequence error Invalid string
304. he hstmt from a different thread in a multithreaded application DM The function was called prior to calling SQLPrepare or SQLExecDirect for the hstmt DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns The time out period expired before the data source returned the result set The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT INFORMIX CLI Function Reference 12 237 SQL NumParams Usage SQLNumParams can be called only after SQLPrepare is called If the statement associated with hstmt does not contain parameters SOLNumParams sets pcpar to 0 Related Functions For Information About See Returning information about a parameter in a SQLDescribeParam extension statement Assigning storage for a parameter SOLBindParameter 4 12 238 INFORMIX CLI Programmer s Manual SQLNumResultCols SQLNumResultCols SOLNumResultCols returns the number of columns in a result set Syntax RETCODE SQLNumResultCols hstmt pccol The SQLNumResultCols function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle SWORD FAR pccol Output Number of columns in the result set Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_STILL_EXECUTING SQL_ERROR or SOL_INVALID_ HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH
305. he table owner SQLBindCol hstmt SQLBindCol hstmt SQLBindCol hstmt SQLBindCol hstmt SQLBindCol hstmt 8 strcpy szTable SALES_ORDE Get the names of the col NX 0 WwW retcode SQLPrimaryKeys hs NU NU SZ while retcode SQL_SUCC SQL_C_ SQL_C_ SQL_C_ SQL_C_ SQL_C_ Table to display th Xj Primary key table name Foreign key table name Primary key column Foreign key column name and qualifier CHAR CHAR szPkTable TAB_LEN szPkCol COL_LEN amp cb SSHORT amp iKeySeq TAB_LEN amp cbKeySeq amp cbFkTable CHAR CHAR RE umns in the primary szFkTable TAB_LEN szFkCol COL_LEN amp cb ey mt hs 0 LL 0 Table Table q Table o SQL_NTS Table n ESS retcode SDWORD cbPkTable cbPkCol cbFkTable cbFkCol cbKeySeq that describe the primary and foreign keys for this example amp cbPkTable PkCol FkCol ualifier wner ame bd SE 5 x 5 a SQL SUCCESS_WITH_INFO Fetch and display the result set This will be a list of the columns in the primary key of the SALES ORDER table retcode SQLFetch hstmt if retcode fprintf out Column s Close the cursor the hstmt is still allocated SQLFreeStmt hstmt SQL CLOSE Get all the foreign keys that refer to SALES ORDER retcode SQLForeignKeys hstmt NULL 0 Primary NULL 0 Primary szTable
306. her applications Although dynamic cursors are ideal for many situations they are difficult to implement Key Set Driven Cursors Key set driven cursors possess some attributes of static and dynamic cursors Like static cursors the membership and ordering of the result set of a key set driven cursor is generally fixed when the cursor opens As with dynamic cursors most changes to the values in the underlying result set are visible to the cursor when data is fetched INFORMIX CLI Programmers Manual Using Block and Scrollable Cursors Specifying the Cursor Type To specify the cursor type an application calls SOLSetStmtOption with the SOL_CURSOR_TYPE option The application can specify a cursor that scrolls forward a static cursor or a dynamic cursor If the application specifies a mixed cursor it also specifies the size of the key set that the cursor uses To use the ODBC cursor library an application calls SOLSetConnectOption with the SOL_ODBC_CURSORS option before it connects to the data source For more information on the ODBC cursor library see the Microsoft ODBC Programmer s Reference and SDK Guide Version 2 0 An application calls SOLExtendedFetch to scroll the cursor backward forward or to an absolute or relative position in the result set Specifying Cursor Concurrency Concurrency is the ability of more than one user to access the same data at the same time A transaction is serializable if it is performed so th
307. hich no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM SOLExecute or SOLExecDirect was called for an hstmt associated with the hdbc and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value specified for the argument fType was neither SOL_COMMIT nor SOL_ROLLBACK The driver or data source does not support the ROLLBACK operation SQLTransact Usage If hdbc is SOL_ NULL_HDBC and henv is a valid environment handle the driver manager attempts to commit or roll back transactions on all connection handles that are in a connected state The driver manager calls SOLTransact in the driver associated with each hdbc The driver manager returns SQL_SUCCESS only if it receives SQL_SUCCESS for each hdbc If the driver manager receives SQL_ERROR on one or more connection handles it returns SQL_ERROR to the application To determine which connection s failed during the COMMIT or ROLLBACK operation the application can call SOLError for each hdbc Important The driver manager does not simulate a global transaction across all hdbcs and therefore does not use two phase commit protocols If hdbc is a valid connection handle
308. hstmt that SOLExecDirect returns are removed when SOLExecDirect or SOLTables is called with that hstmt The errors stored on a specific handle are not removed as the result of a call to a function that uses an associated handle of a different type For example errors on an hdbc that SOLNativeSq l returns are not removed when SQLError or SOLExecDirect is called with an hstmt associated with that hdbc For more information about error codes see Appendix A Related Functions None INFORMIX CLI Function Reference 12 109 SQL ExecDirect 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 szSqlStr cbSqlStr The SOLExecDirect function uses the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szSqlStr Input SQL statement to be executed SDWORD cbSqlStr Input Length of szSqlStr Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NEED_DATA SOL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE 12 110 INFORMIX CLI Programmer s Manual SQLExecDirect Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function
309. ied by the irow argument For the SQL_FETCH_RELATIVE fetch type SOLExtendedFetch returns the row set that starts irow rows from the first row in the current row set The irow argument is ignored for the SQL_FETCH_NEXT SQL_FETCH_PRIOR SOL_FETCH_FIRST and SOL_FETCH_LAST fetch types rgfRowStatus Argument In the rgfRowStatus array SQLExtendedFetch returns any changes in status to each row since it was last retrieved from the data source Rows might be unchanged SQL_ROW_SUCCESS updated SQL_ROW_UPDATED deleted SQL_ROW_DELETED added SQL_ROW_ADDED or unretrievable due to an error SQL_ROW_ERROR Important The Informix driver cannot detect changes to data The number of elements must equal the number of rows in the row set as the SQL_ROWSET_SIZE statement option defines If the number of rows fetched is less than the number of elements in the status array the driver sets remaining status elements to SQL_ROW_NOROW Code Example The following two examples show how an application could use column wise or row wise binding to bind storage locations to the same result set Column Wise Binding In the following example an application declares storage locations for column wise bound data and the returned numbers of bytes Because column wise binding is the default it is unnecessary to request column wise binding with SQLSetStmtOption as in the row wise binding example However the application does call SOLSetStmtOption to s
310. ier INFORMIX CLI_component_identifier data_source_identifierldata_source_supplied_text If the source of an error is INFORMIX CLI the error message explains which INFORMIX CLI component caused the error For errors that do not occur in a data source the error text uses the following format vendor_dentifier INFORMIX CLI _component_identifier component_supplied_text The following table shows the meaning of each element Element Meaning vendor_identifier Identifies the vendor of the component in which the error occurred or the vendor of the component that received the error directly from the data source INFORMIX CLI_component Identifies the component in which the error occurred _identifier or that received the error directly from the data source data_source_identifier Identifies the data source For multiple tier drivers this value is the DBMS product component_supplied_text Error text that INFORMIX CLI generates data_source_supplied_text Error text that the data source generates The brackets are included in the error text They do not indicate optional items Retrieving Status and Error Information 7 5 Sample Error Messages 7 6 Sample Error Messages The following examples show how various components in a connection might generate the text of error messages and how INFORMIX CLI might return the error messages to the application with SQLError Sample Error Returned from the Driver INFORMIX CLI se
311. iers A procedure owner was specified and the driver or data source does not support owners A string search pattern was specified for the procedure owner procedure name or column name and the data source does not support search patterns for one or more of those arguments The driver or data source did not support the combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 INFORMIX CLI Function Reference 12 259 SQLProcedureColumns Comments This function is typically used before statement execution to retrieve infor mation about procedure parameters and columns from the data source s catalog Important SQLProcedureColumns might not return all columns that a procedure uses For example a driver might only return information about the parameters that a procedure uses and not the columns in a result set that it generates The szProcOwner szProcName and szColumnName arguments accept search patterns For more information about valid search patterns see Search Pattern Arguments earlier in this chapter SOLProcedureColumns returns the results as a standard result set ordered by PROCEDURE_QUALIFIER PROCEDURE_OWNER PROCEDURE_NAME and COLUMN_TYPE The following table lists the columns in the result set The driver can
312. if the column does not not NULL accept null values SQL_NULLABLE if the column accepts null values SQL_NULLABLE_UNKNOWN if it is not known if the column accepts null values REMARKS VARCHAR 254 A description of the column 3 of 3 The szTableOwner szTableName and szColumnName arguments accept search patterns For more information about valid search patterns see Search Pattern Arguments on page 12 8 INFORMIX CLI Function Reference 12 73 SQLColumns 12 74 Code Example In the following example an application calls SQLColumns to return a result set that describes each column in the EMPLOYEE table It then calls SQLBindCol to bind the columns in the result set to the storage locations Finally the application fetches each row of data with SQLFetch and processes it define STR_LEN 128 dtdefine REM_LEN 254 Declare storage UCHAR UCHAR UCHAR SDWORD SWORD szQualifier S szTableNameLST szTypeNamel S Precision DataType Sca Declare storage SDWORD cbQualifier SDWORD cbTypeName cbRemarks cbDataType cbPrecision SDWORD cbLength cbScale cbRadix cbNullable ocations R_LEN R_LEN rR_LENI Length e Radi oca cbOwner retcode SQLColumns hstmt SQ SQL SQ SQL SQ SQL SQ SQL SQ SQL for result set data szOwner STR_LEN szColName STR_LEN szRemarks REM_LEN x Nullable cbTableName cbColName tions
313. if the row was updated or deleted by another transaction m SQL_SCOPE_TRANSACTION The row ID is guaranteed to be valid for the duration of the current transaction m SQL_SCOPE_SESSION The row ID is guaranteed to be valid for the duration of the session across transaction boundaries Determines whether to return special columns that can have a NULL value It must be one of the following m SQL_NO_NULLS Exclude special columns that can have NULL values m SQL_NULLABLE Return special columns even if they can have NULL values 2 of 2 SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 305 SQL SpecialColumns 12 306 Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 08S01 24000 S1000 S1001 S1008 S1010 General warning Communication link failure Invalid cur
314. ific SQL data type The argument icol was 0 and the driver does not support bookmarks The time out period expired before the data source returned the result set The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT 3 of 3 With each call the driver sets pcbValue to the number of bytes that are available in the result column before the current call to SOLGetData If SQLSetStmtOption sets SOL_MAX_LENGTH and the total number of bytes that are available on the first call is greater than SOL_MAX_LENGTH the available number of bytes is set to SQL_MAX_LENGTH INFORMIX CLI Programmers Manual SQL GetData The SQL_MAX_LENGTH statement option is intended to reduce network traffic and might not be supported by all drivers To guarantee that data is truncated an application should allocate a buffer of the desired size and specify this size in the cb ValueMax argument If the total number of bytes that are in the result column cannot be determined in advance the driver sets pcbValue to SQL_NO_TOTAL If the data value for the column is null the driver stores SOL_NULL_DATA in pcbValue SQLGetData can convert data to a different data type The result and success of the conversion is determined by the rules for assignment specified in Converting Data from SQL to C Data Types in Appendix D Data Types If the application requires more than one call to SOLGetData to retrieve data from a single column with a charac
315. ifier usage in 12 210 query timeout 12 302 SQLCancel 12 50 SQLExecDirect 12 115 SQLExecute 12 121 SQLAIlocConnect function description 12 9 See also Connection handles SQLAllocEnv function description 12 12 with SQLConnect 12 79 See also Environment handles SQLAIlocStmt function description 12 15 See also Statement handles SQLBindCol binding columns 6 4 function description 12 18 unbinding columns 8 3 with SQLFetch 12 141 SQLBindParameter function description 12 25 sending long data values 5 10 unbinding parameters 8 3 with SQLParamData 12 31 12 33 with SQLParamOptions 12 31 with SOLPutData 12 33 SQLBrowseConnect function description 12 44 with SQLDisconnect 12 45 SQLCancel 12 49 SQLColAttributes column attributes 6 5 function description 12 52 SQLColumnPrivileges 12 62 SQLColumns 12 68 Index 9 SQLConnect function description 12 76 with SOLAllocEnv 12 79 with SQLSetConnectOption 12 79 SQLDataSources 4 5 12 82 SQLDescribeCol 6 5 12 86 SQLDisconnect function description 12 91 with SQLBrowseConnect 12 45 with SQLFreeConnect 12 156 SQLDriverConnect connecting with 4 5 CREATE and DROP parameters 4 9 dialog boxes 4 5 4 6 function description 12 94 SQLDrivers function description 12 103 listing drivers 4 5 SQLError function description 12 107 See also Errors SOLSTATE SQLExecDirect 12 110 SQLExecute function description 12 117 with SQLPrepare 12 121 SQLExtendedFetc
316. igned m TRUE if the data type is unsigned m FALSE if the data type is signed m null is returned if the attribute is not applicable to the data type or the data type is not numeric Whether the data type is a money data type m TRUE if it is a money data type m FALSE if it is not 3 of 4 INFORMIX CLI Function Reference 12 227 SQL GetTypelnfo 12 228 Column Name AUTO_INCREMENT MINIMUM_SCALE MAXIMUM_SCALE INFORMIX CLI Programmers Manual Data Type SMALLINT LOCAL_TYPE_NAME VARCHAR 128 SMALLINT SMALLINT Comments Whether the data type is auto incrementing m TRUE if the data type is auto incrementing m FALSE if the data type is not auto incrementing m null is returned if the attribute is not applicable to the data type or the data type is not numeric An application can insert values into a column having this attribute but cannot update the values in the column Localized version of the data source dependent name of the data type Null is returned if a localized name is not supported by the data source This name is intended for display only as in dialog boxes The minimum scale of the data type on the data source If a data type has a fixed scale the MINIMUM_SCALE and MAXIMUM_SCALE columns both contain this value For example an SQL_TIMESTAMP column might have a fixed scale for fractional seconds Null is returned where scale is not applicable For more information
317. in the table SOLSpecialColumns returns a row set with no rows a subsequent call to SOLFetch or SOLExtendedFetch on the hstmt returns SOL_NO_DATA_FOUND If the fColType fScope or fNullable arguments specify characteristics that the data source does not support SOLSpecialColumns returns a result set with no rows as opposed to the function returning SOL_ERROR with SQLSTATE S1C00 Driver not capable A subsequent call to SOLFetch or SOLExtendedFetch on the stmt returns SOL_NO_DATA_FOUND SQLSpecialColumns returns the results as a standard result set ordered by SCOPE The following table lists the columns in the result set The lengths of VARCHAR columns shown in the table are maximums the actual lengths depend on the data source To determine the actual length of the COLUMN_NAME column an application can call SQLGetInfo with the SQL_MAX_COLUMN_NAME_LEN option Informix SQL Column Name Data Type Comments SCOPE SMALLINT Actual scope of the row ID Contains one of the following values SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION NULL is returned when fCol Type is SOL_ROWVER For a description of each value see the description of fScope on page 12 305 COLUMN_NAME VARCHAR 128 Column identifier not NULL DATA_TYPE SMALLINT INFORMIX CLI SQL data type See SQL Data Types on page B 2 not NULL TYPE_NAME VARCHAR 128 Informix SQL data type See SQL Data Types on page B 2 not NULL 1 of 2 12
318. ing Multiple Results Retrieving Status and Error Information Function Return Codes Error Messages Error Text Format Sample Error Messages Processing Error Messages Retrieving Error Messages Terminating Transactions and Connections Terminating Statement Processing Terminating Transactions Terminating Connections 5 3 5 5 5 6 5 7 5 7 5 10 5 10 5 11 5 12 6 3 6 4 6 5 6 6 6 7 6 7 6 9 6 12 6 13 7 3 7 4 7 5 7 6 7 7 7 8 8 3 8 4 8 4 Table of Contents v Chapter 9 Constructing an INFORMIX CLI ee Static SOL Example age Be a ok oa aa 4 9 4 Interactive Ad Hoc Query Bampi Z tee A elu oh te A 9 7 Chapter 10 Designing Performance Oriented Applications Connecting to a Data Source 1 ee 103 Making One Connection 2 2 1 ew ee 108 Using Statement Handles 104 Retrieving Information About a DataSource 10 4 Minimizing the Use of Catalog Functions o 10 4 Supplying Non Null Arguments to Catalog Functions 10 5 Determining Table Characteristics 106 Retrieving Data 2 1 ee ee ee 10 7 Retrieving Long Data 10 7 Using SQLSetStmtOption to Reduce the Size of Data Retrieved 10 8 Using SOLBindCol to Reduce the Call Load 109 Using SQLExtendedFetch Versus SQLFetch 10 10 Executing Calls 10 11 Using SQLPrepare and SQLExecute Versu
319. iptor types such as SOL_COLUMN_LENGTH 2 of 2 Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 12 53 SQL ColAttributes 12 54 Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning 01004 Data truncated 24000 Invalid cursor state S1000 General error S1001 Memory allocation failure S1002 Invalid column number INFORMIX CLI Programmer s Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer rgbDesc was not large enough to return the entire string value so the string value was truncated The argument pcbDesc contains the length of the untruncated string value function returns SQL_SUCCESS_WITH_INFO The statement associated with the hstmt does not return a result set There are no columns to describe
320. it receives different row values or discovers that the row has been deleted m Phantom Transaction 1 reads a set of rows that satisfy some search criteria Transaction 2 inserts a row that matches the search criteria Transaction 1 re executes the statement that read the rows and it receives a different set of rows vParam must be one of the following values m SOL_TXN_READ_UNCOMMITTED Dirty Reads Nonrepeatable Reads and Phantoms are possible m SQL_TXN_READ_COMMITTED Dirty Reads are not possible Nonre peatable Reads and Phantoms are possible m SQL_TXN_REPEATABLE_READ Dirty Reads and Nonrepeatable Reads are not possible Phantoms are possible m SQL_TXN_SERIALIZABLE Transactions are serializable Dirty Reads Nonrepeatable Reads and Phantoms are not possible m SQL_TXN_VERSIONING Transactions can be serialized but higher concurrency is possible than with SQL_TXN_SERIALIZABLE Dirty Reads are not possible Typically SQL_TXN_SERIALIZABLE is implemented by using locking protocols that reduce concurrency and SQL_TXN_VERSIONING is implemented by using non locking protocol such as record versioning 4 of 4 12 288 INFORMIX CLI Programmer s Manual SQL SetConnectOption Data Translation Data translation is performed for all data moving between the driver and the data source The translation option set with the SQL_TRANSLATE_OPTION option can be any 32 bit value Its meaning depends on the transla
321. item is associated It is a foreign key that refers to SALES_ID in the SALES_ORDER table The code example calls SQLPrimaryKeys to get the primary key of the SALES_ORDER table The result set has one row and the significant columns are as follows TABLE_NAME COLUMN_NAME KEY_SEQ SALES_ORDER SALES_ID 1 12 150 INFORMIX CLI Programmer s Manual SQLForeignKeys Next the code example calls SQLForeignKeys to get the foreign keys in other tables that reference the primary key of the SALES_ORDER table The result set has one row and the significant columns are as follows PKTABLE_NAME PKCOLUMN_NAME FKTABLE_NAME FKCOLUMN_NAME KEY_SEQ SALES_ORDER SALES_ID SALES_LINE SALES_ID 1 Finally the code example calls SOLForeignKeys to get the foreign keys in the SALES_ORDER table that refer to the primary keys of other tables The result set has two rows and the significant columns are as follows PKTABLE_NAME PKCOLUMN_NAME FKTABLE NAME FKCOLUMN_NAME KEY_SEQ CUSTOMER CUSTOMER_ID SALES ORDER CUSTOMER ID 1 EMPLOYEE EMPLOYEE_ID SALES_ORDER EMPLOYEE_ID 1 INFORMIX CLI Function Reference 12 151 SQL ForeignKeys 12 152 itdefine TAB_LEN SQL_MAX_TAB LE_NAME_LEN 1 itdefine COL_LEN SQL_MAX_COL UMN_NAME_LEN 1 LPSTRszTable UCHARszPkTable TAB_LEN UCHARszFkTable TAB_LEN UCHARszPkCol COL_LEN UCHARszFKCo1 COL_LEN HSTMT hstmt SWORD KeySeq RETCODE retcode Bind the columns Ignore t
322. iver specific SQL data type to an INFORMIX CLI C data type and this conversion is not supported by the driver SOLExtendedFetch SQLFetch or SOLGetData returns SQLSTATE S1C00 Driver not capable Although the tables in this appendix do not show it the pcbValue argument contains SOL_NULL_DATA when the SOL data value is null When SOL data is converted to character C data the character count returned in pcbValue does not include the null termination byte If rgbValue is a null pointer SQLBindCol or SOLGetData returns SOLSTATE S1009 Invalid argument value The following terms and conventions are used in the tables m Length of data is the number of bytes of C data that are available to return in rgbValue regardless of whether the data is truncated before it returns to the application For string data this does not include the null termination byte m Display size is the total number of bytes that are needed to display the data in character format m Words in italics represent function arguments or elements of the INFORMIX CLI SQL grammar INFORMIX CLI Programmers Manual SQL to C Character The character INFORMIX CLI SQL data types are m SQL_CHAR m SQL_LONGVARCHAR m SQL_VARCHAR Converting Data from SQL to C The following table shows the INFORMIX CLI C data types to which character SQL data can be converted fCType Test rgbValue pcbValue SQLSTATE SQL_C_CHAR Length of data lt cbValueMax Data Length
323. l close the cursors for all hstmts on an hdbc 6 6 INFORMIX CLI Programmer s Manual Retrieving Data from Unbound Columns For more information see SOL_CURSOR_COMMIT_BEHAVIOR and SOL_CURSOR_ROLLBACK_BEHAVIOR on page 12 196 Retrieving Data from Unbound Columns To retrieve data from unbound columns that is columns for which storage has not been assigned with SOLBindCol an application uses SOLGetData The application first calls SQLFetch or SQLExtendedFetch to position the cursor on the next row It then calls SQLGetData to retrieve data from specific unbound columns An application can retrieve data from bound and unbound columns in the same row It calls SQLBindCol to bind as many columns as you specify It calls SQLFetch or SQLExtendedFetch to position the cursor on the next row of the result set and to retrieve all bound columns It then calls SOLGetData to retrieve data from unbound columns If the column data type is character binary or data source specific and the column contains more data than can be retrieved in a single call an appli cation might call SOLGetData more than once for that column as long as the data is being transferred to a buffer of type SOL_C_CHAR or SOL_C_BINARY For example data of the SOL_LONGVARBINARY and SQOL_LONGVARCHAR types might need to be retrieved in several parts The INFORMIX CLI driver can return data with SOLGetData for both bound and unbound columns in any order For m
324. le to return is greater than or equal to cbDrorAttrMax the list of attribute value pairs in szDriverAttributes is truncated to cbDrvrAttrMax 1 bytes 2 of 2 SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SOL_ERROR or SOL_INVALID_HANDLE When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SQLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise SQL Drivers If you are not using a driver manager the driver returns the SOLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error 01000 01004 S1000 S1001 S1090 S1103 General warning Data truncated General error Memory allocation failure Invalid string or buffer length Direction option out of range Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO DM The buffer szDriverDesc was not large enough to return the entire driver description so the description was truncated The argument pcbDriverDesc contains the length of the entire driver description function returns SQL_SUCCESS_WITH_INFO DM The buffer szDriverAttributes was not large enoug
325. less than 0 DM The value specified for the argument ipar was less than 1 The value specified for the argument ipar was greater than the maximum number of parameters supported by the data source ibScale was invalid for fSqlType cbColDef was invalid for fSq Type DM fParamType was invalid For more infor mation see fParamType Argument on page 12 29 fParamType was SOL_PARAM_OUTPUT and the parameter did not mark a return value from a procedure or a procedure parameter fParamType was SQL_PARAM_INPUT and the parameter marked the return value from a procedure The driver or data source does not support the conversion specified by the combination of fCType and fSqlType The driver or data source does not support the value specified for fSq Type 2 of 2 SQLBindParameter Usage An application calls SOLBindParameter to bind each parameter marker in an SQL statement Bindings are effective until the application calls SQLBindParameter again or until the application calls SQLFreeStmt with the SQL_DROP or SOL_RESET_PARAMS option fParamType Argument The fParamType argument specifies the parameter type All parameters in SQL statements that do not call procedures such as INSERT statements are input parameters Parameters in procedure calls can be input input output or output parameters An application calls SOLProcedureColumns to determine the type of a parameter in a procedure call parameters in proce
326. leted statement and more than one row was updated or deleted function returns SQL_SUCCESS_WITH_INFO 07001 Wrong number of The number of parameters specified in SQLBindParameter was less than parameters the number of parameters in the SQL statement contained in the argument szSqIStr 08S01 Communication The communication link between the driver and the data source failed link failure before the function completed 1 of 5 INFORMIX CLI Function Reference 12 111 SQL ExecDirect SQLSTATE Error Description 21501 Insert value list The argument szSq Str contained an INSERT statement and the number of does not match values to be inserted did not match the degree of the derived table column list 21502 Degree of derived The argument szSq Str contained a CREATE VIEW statement and the table does not number of names specified is not the same degree as the derived table match column list defined by the query specification 22003 Numeric value out The argument sz5q Str contained an SQL statement that contained a of range numeric parameter or literal and the value caused the whole as opposed to fractional part of the number to be truncated when assigned to the associated table column 22005 Error in assignment The argument sz5q Str contained an SQL statement that contained a parameter or literal and the value was incompatible with the data type of the associated table column 22008 Datetime field The argument szSq Str contained an SQL st
327. lication calls SQLError multiple times For each error the driver returns SQL_SUCCESS and removes that error from the list of available errors When no additional information for the right most non null handle remains SQLError returns SQL_NO_DATA_FOUND In this case szSqlState equals 00000 Success pfNativeError is undefined pcbErrorMsg equals 0 and szErrorMsg contains a single null termination byte unless cbErrorMsgMax equals 0 The driver manager if you are using one stores error information in its henv hdbc and hstmt structures Similarly the driver stores error information in its henv hdbc and hstmt structures When the application calls SOLError the driver manager checks if any errors exist in its structure for the specified handle If errors exist for the specified handle it returns the first error if no errors exist it calls SOLError in the driver The driver manager if you are using one can store up to 64 errors with an henv and its associated hdbcs and hstmts When this limit is reached the driver manager discards any subsequent errors posted on the henv hdbcs or hstmts of the driver manager The number of errors that a driver can store is driver dependent An error is removed from the structure associated with a handle when SQLError is called for that handle and returns the error All errors stored for a specific handle are removed when the handle is used in a subsequent function call For example errors on an
328. lid authorization specification Data source not found and no default driver specified Specified driver could not be loaded Driver SOLAllocEnv failed Driver SOLAllocConnect failed Driver SQLSetConnectOption failed No data source or driver specified dialog prohibited Dialog failed Unable to load trans lation shared library Data source name too long SQL DriverConnect Description Either the user identifier or the authorization string or both as specified in the connection string szConnStrIn violated restrictions defined by the data source DM The data source name specified in the connection string szConnStrIn was not found and no default driver specification existed DM The driver listed in the data source speci fication or specified by the DRIVER keyword was not found or was not loaded for some other reason DM During SQLDriverConnect the driver manager called the driver SOLAllocEnv function and the driver returned an error DM During SQLDriverConnect the driver manager called the driver SOLAllocConnect function and the driver returned an error DM During SQLDriverConnect the driver manager called the driver SQLSetConnectOption function and the driver returned an error C fDriverCompletion was SQL_DRIVER_NOPROMPT DM The driver manager attempted to display the SQL Data Sources dialog box but failed The driver attempted to display its login dialog box but faile
329. list of SQLSTATE values see Appendix A INFORMIX CLI Error Codes pfNativeError Output Native error code specific to the data source szErrorMsg Output Pointer to storage for the error message text cbErrorMsgMax Input Maximum length of the szErrorMsg buffer This value must be less than or equal to SOL_MAX_MESSAGE_LENGTH 1 pcbErrorMsg Output Pointer to the total number of bytes excluding the null termi nation byte available to return in szErrorMsg If the number of bytes available to return is greater than or equal to cbErrorMsgMax the error message text in szErrorMsg is truncated to cbErrorMsgMax 1 bytes Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NO_DATA_ FOUND SOL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 107 SQLError Diagnostics SQLError does not post error values for itself SOLError returns SOL_NO_DATA_FOUND when it cannot retrieve any error information in which case szSq State equals 00000 If SQLError cannot access error values for any reason that would normally return SOL_ERROR SQLError returns SQL_ERROR but does not post any error values If the buffer for the error message is too short SQLError returns SQL_SUCCESS_WITH_INFO but still does not return a SOLSTATE value for SOLError To determine that a truncation occurred in the error message an application can compare cbErrorMsgMax to the actual length of the message text written to pcbErrorMsg Usage
330. lowed by a three character subclass value A class value of 01 indicates a warning and is accompanied by a return code of SOL_SUCCESS_WITH_INFO Class values other than 01 except for the class 1M indicate an error and are accompanied by a return code of SOL_ERROR The class IM is specific to warnings and errors that derive from the implementation of INFORMIX CLI The subclass value 000 in any class is for implementation defined conditions within the given class ANSI SQL 92 defines the assignment of class and subclass values SQLSTATE Values 01000 01002 01004 01006 01500 01501 01502 01503 01504 07001 A 2 INFORMIX CLI Programmers Manual SQL STATE Error General warning Disconnect error Data truncated Privilege not revoked Invalid connection string attribute Error in row Option value changed No rows updated or deleted More than one row updated or deleted Wrong number of parameters A return value of SQL_SUCCESS normally indicates a function has executed successfully although the SOLSTATE 00000 also indicates success Can be returned from All functions except SOLAllocEnv SQLError SQLDisconnect SQLBrowseConnect SQLColAttributes SOLDataSources SQLDescribeCol SQLDriverConnect SQLDrivers SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SQLGetCursorName SOLGetData SOLGetInfo SOLNativeSql SQLPutData SQLExecDirect SQLExecute SOLBrowseConnect SQLDriverConnect
331. lowing bitmasks are used to determine where qualifiers can be used m SQL_QU_DML_STATEMENTS Qualifiers are supported in all Data Manipulation Language statements SELECT INSERT UPDATE DELETE and if supported SELECT FOR UPDATE and positioned UPDATE and DELETE statements m SQL_QU_PROCEDURE_INVOCATION Qualifiers are supported in the ODBC procedure invocation statement m SQL_QU_TABLE_DEFINITION Qualifiers are supported in all table definition statements CREATE TABLE CREATE VIEW ALTER TABLE DROP TABLE and DROP VIEW m SQL_QU_INDEX_DEFINITION Qualifiers are supported in all index definition statements CREATE INDEX and DROP INDEX m SQL_QU_PRIVILEGE_DEFINITION Qualifiers are supported in all privilege definition statements GRANT and REVOKE SQL_QUOTED_IDENTIFIER_CASE A 16 bit integer value as follows m SQL_IC_UPPER Quoted identifiers in SQL are case insensitive and are stored in uppercase in system catalog m SQL_IC_LOWER Quoted identifiers in SOL are case insen sitive and are stored in lowercase in system catalog m SQL_IC_SENSITIVE Quoted identifiers in SQL are case sensitive and are stored in mixed case in system catalog m SQL_IC_MIXED Quoted identifiers in SQL are not case sensitive and are stored in mixed case in system catalog SQL_ROW_UPDATES 12 210 INFORMIX CLI Programmers Manual A character string a Y if a key set driven or mixed cursor maintains row versions or va
332. lue otherwise the driver returns the SOLSTATE value Description 01000 01002 08003 25000 S1000 S1001 S1010 12 92 General warning Disconnect error Connection not open Invalid transaction state General error Memory allocation failure Function sequence error INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred during the disconnect However the disconnect succeeded function returns SQL_SUCCESS_WITH_INFO DM The connection specified in the argument hdbc was not open A transaction was in process on the connection specified by the argument hdbc The transaction remains active An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM SOLExecute or SOLExecDirect was called for the hstmt associated with the hdbc and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns SQLDisconnect Usage If an application calls SQLDisconnect after SQLBrowseConnect returns SOL_NEED_DATA and before it returns a different return code the driver cancels the connection browsing process and r
333. lues for all fetched rows and therefore can detect any changes made to a row by any user since the row was last fetched m N otherwise 18 of 24 InfoType SQL_SCROLL_CONCURRENCY SQLGetInfo Returns A 32 bit bitmask that enumerates the concurrency control options supported for scrollable cursors The following bitmasks are used to determine which options are supported m SQL_SCCO_READ_ONLY Cursor is read only No updates are allowed m SQL_SCCO_LOCK Cursor uses the lowest level of locking sufficient to ensure that the row can be updated m SQL_SCCO_OPT_ROWVER Cursor uses optimistic concur rency control comparing row versions m SQL_SCCO_OPT_VALUES Cursor uses optimistic concur rency control comparing values For information about cursor concurrency see Specifying Cursor Concurrency on page 6 11 SQL_SCROLL_OPTIONS A 32 bit bitmask that enumerates the scroll options supported for scrollable cursors The following bitmasks are used to determine which options are supported m SQL_SO_FORWARD_ONLY The cursor only scrolls forward m SQL_SO_STATIC The data in the result set is static m SQL_SO_KEYSET_DRIVEN The driver saves and uses the keys for every row in the result set m SQL_SO_DYNAMIC The driver keeps the keys for every row in the row set the key set size is the same as the row set size m SQL_SO_MIXED The driver keeps the keys for every row in the key set and
334. m The SOLSetStmtOption function accepts the following arguments Argume Typedef nt Use Description HSTMT hstmt Input Statement handle UWORD fOption Input Option to set listed in Usage UDWORD vParam Input Value associated with fOption Depending on the value of fOption vParam will be a 32 bit integer value or point to a null terminated character string Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE 12 296 INFORMIX CLI Programmer s Manual Diagnostics SQLSetStmtOption When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 01502 08501 24000 S1000 1001 General warning Option value changed Communication link failure Invalid cursor state General error Memory allocation failure INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The driver did not support the specified valu
335. maintain INFORMIX CLI Programmers Manual Supplying Non Null Arguments to Catalog Functions Supplying Non Null Arguments to Catalog Functions Because catalog functions are slow your application should invoke them as efficiently as possible Passing null arguments to catalog functions can result in the driver generating time consuming queries and can increase network traffic with unwanted result set information Rather than pass the smallest number of non null arguments necessary for a catalog function to return success always supply as many non null arguments as possible to catalog functions Any information that the appli cation can send the driver when it calls a catalog function can result in improved performance and reliability Consider a call to SQLTables in which an application requests information about a table named Customers This call is often coded similarly to the following example rc SQLTables NULL NULL NULL NULL Customers SQL_NTS NULL A driver might turn this SOLTables call into SQL statements as in the following example SELECT FROM SysTables WHERE TableName Customers UNTON ALL SELECT FROM SysViews WHERE ViewName Customers UNTON ALL SELECT FROM SysSynonyms WHERE SynName Customers ORDER BY Suppose that the result set for this example contains three Customers tables one table that the user owns one table that sales owns and one view that management cr
336. mal point the letter E another sign and 2 more numeric characters 1 of 3 B 6 INFORMIX CLI Programmers Manual INFORMIX CLI SQL Data Type fSqlType Precision Scale Length and Display Size Description SQL_INTEGER Precision 10 SOLBindParameter ignores the value of cbColDef for this data type Scale 0 SOLBindParameter ignores the value of ibScale for this data type Length 4 bytes Display size 11 digits One digit is for the sign SQL_LONGVARBINARY Precision Same as the length Scale Not applicable SOLBindParameter ignores the value of ibScale for this data type Length The maximum length If a function cannot determine the maximum length it returns SQL_NO_TOTAL Display size The maximum length times 2 If a function cannot determine the maximum length it returns SQL_NO_TOTAL SQL_LONGVARCHAR Precision Same as the length Scale Not applicable SOLBindParameter ignores the value of ibScale for this data type Length The maximum length If a function cannot determine the maximum length it returns SQL_NO_TOTAL Display size Same as the length SQL_REAL Precision 7 SOLBindParameter ignores the value of cbColDef for this data type Scale Not applicable SOLBindParameter ignores the value of ibScale for this data type Length 4 bytes Display size 13 digits The digits are for a sign 7 numeric characters a decimal point the letter E another sig
337. man and Statement Handles Yo e 8 Using Data Types noe is a Me Geo So ot R12 Function Return Codes m oe fags S312 How an Application Uses the INFORMIX CLI API ty ose ote ee maa Kola Chapter 4 Connecting to a Data Source Initializing the Environment a ew o 4 3 Allocating a Connection Handle 2 2 2 4 4 Connecting to a Data Source 1 wee es 4 4 Using SQLConnect 2 2 1 ee o 4 4 Using SQLDriverConnect 2 2 2 ee 4 5 Using SQLBrowseConnect 2 2 1 1 ee ee 4 7 Connection Strings we ee 4 7 Related Functions a a a eee ee 415 iv INFORMIX CLI Programmers Manual Chapter 5 Chapter 6 Chapter 7 Chapter 8 Executing SQL Statements SQL Statements and INFORMIX CLI Allocating a Statement Handle Executing an SQL Statement Prepared Execution Direct Execution Setting Parameter Values Performing Transactions Retrieving Information About the Data Source Catalog Sending Parameter Data at Execution Time Specifying Arrays of Parameter Values Related Functions Retrieving Results Result Sets and INFORMIX CLI Assigning Storage for Results Binding Determining the Characteristics of a Result Set Fetching Result Data Using Cursors Retrieving Data fior U b u d Columns Assigning Storage for Row Sets apace Retrieving Row Set Data Using Block and Scrollable Cursors Positioned Update and Delete Statements Process
338. manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SQLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source failed before the function completed 1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause 1010 Function DM The function was called prior to calling sequence error SOLDisconnect for the hdbc Usage Prior to calling SOLFreeConnect an application must call SOLDisconnect for the hdbc Otherwise SOLFreeConnect returns SOL_ERROR and the hdbc remains valid SOLDisconnect automatically drops any hstmts open on the hdbc 12 156 INFORMIX CLI Programmer s Manual Code Example See SOLBrowseConnect and SQLConnect Related Functions SQLFreeConnect For Information About See Allocating a statement handle SOLAllocConnect Connecting to a data source SOLConnect Disconnecting from a data source SOLDisconnect Connecting to a data source using a connection string or SOL
339. me stamp C data is converted to character SQL data the resulting character data is in the yyyy mm dd hh mm ss f format The value pointed to by the pcbValue argument of SQLBindParameter and the value of the cbValue argument of SQLPutData are ignored when data is converted from the time stamp C data type The driver assumes that the size of rgbValue is the size of the time stamp C data type INFORMIX CLI Programmers Manual C to SQL Data Conversion Examples Converting Data from C to SQL The following table illustrates how the driver converts C data to SQL data C Data Type SQL_C_CHAR SQL_C_CHAR SQL_C_CHAR SQL_C_CHAR SQL_C_CHAR SQL_C_FLOAT SQL_C_FLOAT SQL_C_FLOAT SQL_C_DATE SQL_C_DATE SQL_C_DATE SQL_C_TIMESTAMP SQL_C_TIMESTAMP SQL_C_TIMESTAMP C Data Value tigers 0 tigers 0 1234 56 02 1234 56 02 1234 56 02 1234 56 1234 56 1234 56 1992 12 31 lt 1992 12 31 lt 1992 12 31 1992 12 31 23 45 55 120000000 1992 12 31 23 45 55 120000000 1992 12 31 23 45 55 120000000 SQL Data Type SQL_CHAR SQL_CHAR SQL_DECIMAL SQL_DECIMAL SQL_DECIMAL SQL_FLOAT SQL_INTEGER SQL_TINYINT SQL_CHAR SQL_CHAR SQL_TIMESTAMP SQL_CHAR SQL_CHAR SQL_CHAR Column length 6 5 gb 7b 4 not applicable not applicable not applicable 10 9 not applicable 22 21 18 SQL Data Value tigers tiger 1234 56 1234 5 1234 56 1234 1992 12 31 1992 12 31 00 00
340. me to define a cursor name when a SELECT statement executes the driver generates a name that begins with the letters SQL_CUR and does not exceed 18 characters All cursor names within the hdbc must be unique The driver defines the maximum length of a cursor name For maximum interoperability cursor names should not exceed 18 characters A cursor name remains set until the hstmt with which it is associated is dropped using SOLFreeStmt with the SQL_DROP option SQL SetCursorName Code Example In the following example an application uses SQLSetCursorName to set a cursor name for an hstmt It then uses that hstmt to retrieve results from the EMPLOYEE table Finally it performs a positioned update to change the name of 25 year old John Smith to John D Smith The application uses different hstmts for the SELECT and UPDATE statements itdefine NAME_LEN 30 HSTMT hstmtSelect HSTMT hstmtUpdate UCHAR szName NAME_LEN SWORD sAge SDWORD cbName SDWORD cbAge Allocate the statements and set the cursor name SQLAllocStmt hdbc amp hstmtSelect LAllocStmt hdbc amp hstmtUpdate SQLSetCursorName hstmtSelect C1 SQL_NTS Wn ro SELECT the result set and bind its columns to local storage SQLExecDirect hstmtSelect SELECT NAME AGE FROM EMPLOYEE FOR UPDATE SQL_NTS SQLBindCol hstmtSelect 1 SQL_C_CHAR szName NAME_LEN amp cbName SQLBindCol hstmtSelect 2 SQL_C_SSHORT amp sAge 0 amp cbAge
341. mer s Manual his chapter describes the conformance levels the driver manager the general characteristics of INFORMIX CLI functions and the basic procedure for using the API Conformance Levels This section describes the API and SQL conformance levels for the INFORMIX CLI driver API Conformance Levels API conformance refers to the functions that an ODBC driver supports The API conformance standard consists of three levels Core Level 1 and Level 2 The Core level consists of functions that correspond to the functions in the CLI specification Level 1 and Level 2 functions extend the core functionality Guidelines for Calling INFORMIX CLI Functions 3 3 AP Conformance Levels 3 4 INFORMIX CLI Programmer s Manual Core Level Functions SOLAllocConnect SOLAllocEnv SOLAllocStmt SOLBindCol SQLCancel SQLColAttributes SQLConnect SQLDescribeCol SQLDisconnect SQLError SQLExecDirect SQLExecute SQLFetch SQLFreeConnect SQLFreeEnv SQLFreeStmt SOLGetCursorName SQLNumResultCols SQLPrepare SQLRowCount SOLSetCursorName SQLTransact Level 1 Functions SQLBindParameter SQLColumns SQLDriverConnect SQLGetConnectOption SQLGetData SOLGetFunctions SQLGetInfo SOLGetStmtOption SOLGetTypelnfo SQLParamData SQLPutData SQLSetConnectOption SQLSetStmtOption SQLSpecialColumns SQLStatistics SQLTables The following table lists the functions that the ODBC standard defines INFORMIX CLI supports all the Core functions an
342. mory for the statement handle DM The argument phstmt was a null pointer SQLAllocStmt Usage A statement handle references statement information such as network infor mation SOLSTATE values and error messages cursor name several result set columns and status information for SQL statement processing To request a statement handle an application connects to a data source and then passes the address of an stmt to SOLAllocStmt The driver allocates memory for the statement information and stores the value of the associated handle in the stmt On operating systems that support multiple threads applications can use the same hdbc on different threads The application passes the hstmt value in all subsequent calls that require an hstmt If the application calls SOLAllocStmt with a pointer to a valid hstmt the driver overwrites the hstmt without regard to its previous contents Code Example See SOLBrowseConnect SOLComnect and SOLSetCursorName Related Functions For Information About See Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute Freeing a statement handle SOLFreeStmt Preparing a statement for execution SQLPrepare 4 INFORMIX CLI Function Reference 12 17 SQLBindCol SQLBindCol Syntax Typedef HSTMT UWORD SWORD PTR Argument hstmt icol fCType rebValue 12 18 INFORMIX CLI Programmers Manual Use Input Input Input Input SQLBindC
343. n and 2 more numeric characters 2 of 3 DataTypes B 7 Precision Scale Length and Display Size B 8 INFORMIX CLI SQL Data Type fSqlType SQL_SMALLINT Description Precision 5 SOLBindParameter ignores the value of cbColDef for this data type Scale 0 SOLBindParameter ignores the value of ibScale for this data type Length 2 bytes Display size 6 digits One digit is for the sign SQL_TIMESTAMP Precision 8 SOLBindParameter ignores the value of cbColDef for this data type Scale The number of digits in the FRACTION field Length 16 bytes Display size 19 or more digits m If the scale of the time stamp is 0 19 digits in the format yyyy mm dd hh mm ss m If the scale of the time stamp exceeds 0 20 digits plus digits for the FRACTION field in the format yyyy mm dd hh mm ss f SQL_VARCHAR INFORMIX CLI Programmers Manual Precision Same as the length Scale Not applicable SOLBindParameter ignores the value of ibScale for this data type Length The specified length For example the length of VARCHAR 10 is 10 bytes Display size Same as the length 3 of 3 Precision Scale Length and Display Size mus Additional SQL Data Types for Universal Server The following table describes the precision scale length and display size for the INFORMIX CLI SQL data types for Universal Server INFORMIX CLI SQL Data Type fSqlType Description SQL_BIGINT Pr
344. n a multithreaded application 2 of 3 INFORMIX CLI Function Reference 12 173 SQL GetData SQLSTATE Error S1009 S1010 S1090 S1109 S1C00 S1T00 12 174 Invalid argument value Function sequence error Invalid string or buffer length Invalid cursor position Driver not capable Time out expired Usage Description DM The argument rgb Value was a null pointer DM The specified hstmt was not in an executed state The function was called without first calling SQLExecDirect SQLExecute or a catalog function DM SQLExecute or SOLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value specified for argument cbValueMax was less than 0 The cursor was positioned by SQLExtendedFetch on a row for which the value in the refRowStatus array in SQLExtendedFetch was SQL_ROW_DELETED or SQL_ROW_ERROR The driver or data source does not support the use of SQLGetData with multiple rows in SQLExtendedFetch This description does not apply to drivers that return the SQL_GD_BLOCK bitmask for the SQL_GETDATA_EXTENSIONS option in SOLGetInfo The driver or data source does not support the conversion specified by the combination of the fCType argument and the SQL data type of the corre sponding column This error applies only when the SQL data type of the column was mapped to a driver spec
345. n or columns allows any row in the specified table to be uniquely identified A column can be either a pseudo column specifi cally designed for this purpose or the column or columns of any unique index for the table m SQL_ROWVER Returns the column or columns in the specified table if any that are automatically updated by the data source when any value in the row is updated by any transaction Qualifier name for the table If a driver supports qualifiers for some tables but not for others as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have qualifiers Length of szTableQualifier 1 of 2 Deputed Argument UCHAR FAR szTableOwner SWORD cbTableOwner UCHAR FAR szTableName SWORD cbTableName UWORD fScope UWORD fNullable Use Input Input Input Input Input Input Return Codes SQL SpecialColumns Description Owner name for the table If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have owners Length of szTableOwner Table name Length of szTableName Minimum required scope of the row ID The returned row ID might be of greater scope It must be one of the following m SQL_SCOPE_CURROW The row ID is guaranteed to be valid only while positioned on that row A later reselect using row ID might not return a row
346. n or equal to 2 Data is not a numeric literal Untouched Untouched 22005 This is the size of the corresponding C data type SQL to C Numeric The numeric INFORMIX CLI SQL data types are found in the following list SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_REAL SQL_SMALLINT DataTypes B 23 Converting Data from SQL to C The following table shows the INFORMIX CLI C data types to which numeric SQL data can be converted fCType Test rgbValue pcbValue SQLSTATE SQL_C_CHAR Display size lt cbValueMax Data Length of data N A Number of whole as opposed Truncated data Length of data 01004 to fractional digits lt cbValueMax Number of whole as opposed Untouched Untouched 22003 to fractional digits cbValueMax SQL_C_LONG Data converted without Data Size of the C N A SQL_C_SHORT truncation gt data type SQL_C_SLONG SQL_C_SSHORT Data converted with truncation Truncated data Size of the C 01004 SQL_C_STINYINT of fractional digits gt data type SO UL ONG Conversion of data would result Untouched Untouched 22003 SQL_C_USHORT in loss of whole as opposed to SOL_C_UTINYINT fractional digits gt SOL_C_DOUBLE Data is within the range of the Data Size of the C N A SQL_C_FLOAT data type to which the number data type is being converted gt Data is outside the range of the Untouched Untouched 22003 data type to which the number is being converted gt SQL_C_BINARY Length of data lt cbValueMax Data Length
347. name of the associated DBMS presented to users instead of the physical driver name LPCSTR IpszAttributes Input List of attributes in the form of keyword value pairs For information about the list structure see Comments Returns The function returns TRUE if it is successful It returns FALSE if it fails Usage ConfigDSN receives connection information from the installer shared library as a list of attributes in the form of keyword value pairs Each pair is termi nated with a null byte and the entire list is null terminated that is two null bytes mark the end of the list The keywords that ConfigDSN uses are the same as those that SQLBrowseConnect and SQLDriverConnect use except ConfigDSN does not accept the DRIVER keyword As in SQLBrowseConnect and SQLDriverConnect the keywords and their values should not contain the 2 characters and the value of the DSN keyword cannot consist of blanks only Because of the registry grammar keywords and data source names cannot contain the backslash character 13 4 INFORMIX CLI Programmers Manual ContigDSN For example to configure a data source that requires a user ID password and database name a setup application might pass the following keyword value pairs DSN Personnel Data OUID Smith OPWD Sesame ODATABASE Personnel 0 0 For more information about these keywords see SQLDriverConnect on page 12 94 To display a dialog box hwndParent must
348. nction completed 24000 Invalid cursor state A cursor was already opened on the statement handle S1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause 1001 Memory allocation The driver did not allocate memory required to failure support execution or completion of the function 1008 Operation canceled The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application 1 of 2 12 254 INFORMIX CLI Programmers Manual SQLSTATE Error S1010 Function sequence error S1090 Invalid string or buffer length S1C00 Driver not capable S1T00 Time out expired Usage SQLPrimaryKeys Description DM SQLExecute or SOLExecDirect was called for the hstmt and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value of one of the name length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corre sponding qualifier or name A table qualifier was specified but the driver or data source does not support qualifiers A table owner was specified but the driver or data source does not support
349. nction Reference 12 163 SQL GetConnectOption SQLGetConnectOption SQLGetConnectOption returns the current setting of a connection option Syntax RETCODE SQLGetConnectOption hdbc fOption pvParam The SQLGetConnectOption function accepts the following arguments Type Argument Use Description HDBC hdbc Input Connection handle UWORD fOption Input Option to retrieve PTR puParam Output Value associated with fOption Depending on the value of fOption a 32 bit integer value or a pointer to a null terminated character string will be returned in pvParam Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NO_DATA_ FOUND SOL_ERROR or SOL_INVALID_HANDLE 12 164 INFORMIX CLI Programmers Manual Diagnostics SQL GetConnectOption When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 08003 S1000 1001 S1010 S1092 S1C00 General warning Connection n
350. nd reduce the call load Retrieving Long Data Retrieving long data SQL_LONGVARCHAR and SQL_LONGVARBINARY data across the network is resource intensive and slow Unless it is absolutely necessary your application should avoid requesting long data If the user wants to see long data items the application can requery the database and specify only the long columns in the SELECT list In general users do not want to see long data Consequently a default that does not retrieve long data or binary data is acceptable If a user does want to see these result items the application can requery the database specifying only the long columns in the SELECT list This method allows the average user to retrieve the result set without paying a high performance penalty for intense network traffic Although the optimal method is to exclude long data from the SELECT list some applications do not formulate the select list before they send the query to the driver that is some applications use a statement such as the following one SELECT FROM table_name If the SELECT list contains long data some drivers must retrieve that data at fetch time even if the application does not bind the long data in the result set If possible the designer should attempt to implement a method that does not retrieve all columns of the table Designing Performance Oriented Applications 10 7 Using SQL SetStmtOption to Reduce the Size of Data Retrieved Using SQLSet
351. ndParameter hstmt 1 SQL_PARAM_INPUT SQL_C_CHAR SQL_CHAR NAME_LEN 0 szName 0 amp cbName SQLBindParameter hstmt 2 SQL_PARAM_INPUT SQL_C_SSHORT SQL_SMALLINT 0 0 amp sAge 0 amp cbAge SQLBindParameter hstmt 3 SQL_PARAM_INPUT SQL_C_DATE SQL_DATE 0 0 amp dsBirthday 0 amp cbBirthday strcpy szName Smith John D Specify first row of sAge 40 parameter data E dsBirthday year 1952 dsBirthday month 2 dsBirthday day 29 retcode SQLExecute hstmt Execute statement with first row ia strcpy szName Jones Bob K Specify second row of sAge 52 parameter data El dsBirthday year 1940 dsBirthday month 3 dsBirthday day 31 SQLExecute hstmt Execute statement with second row xI For a similar example see SQLPutData 12 36 INFORMIX CLI Programmer s Manual SQLBindParameter Related Functions For Information About See Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute Returning the number of statement parameters SOLNumParams Returning the next parameter to send data for SOLParamData Sending parameter data at execution time SOLPutData 4 INFORMIX CLI Function Reference 12 37 SQL BrowseConnect SQLBrowseConnect SQLBrowseConnect supports an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source Each call to SOLBrow
352. ndows Locale and codeset that the database was created in locale codeset modifier DB_LOCALE en_us 1252 Performs the codeset conversion Path to the file for the library The translation DLL must follow the ODBC standard for trans lation libraries For more information see SOLSetComnectOption on page 12 281 TRANSLATIONDLL INFORMIXDIR bin igo4n304 dll Option for a non Informix translation library Determined by the vendor TRANSLATION_OPTION Determined by the vendor Important Do not set this option for an Informix translation library An Informix translation library determines the translation option based on the client locale and database locale values 1 12 INFORMIX CLI Programmers Manual VMB Character Description Possible values for UNIX Possible values for Windows odbc ini field for UNIX Default value for Windows VMB Character Varying multibyte character length reporting option that specifies how to set pcbValue when rgbValue the output area is not large enough for the code set converted data The possible values are Estimate INFORMIX CLI makes a worst case estimate of the storage space needed to return the data This is the default value Exact INFORMIX CLI writes the code set converted data to disk until all of the data is converted Because this option can degrade performance Informix recommends that you do not use this option unless your application does not
353. nds Except for the decimal point and fractional seconds the entire format must be used regardless of the precision of the time stamp SQL data type DataTypes B 29 Converting Data from SQL to C SQL Data Type SQL_CHAR SQL_CHAR SQL_DECIMAL SQL_DECIMAL SQL_DECIMAL SQL_DECIMAL SQL_DECIMAL SQL_DECIMAL SQL_DOUBLE SQL_DOUBLE SQL_DOUBLE SQL_DATE SQL_DATE SQL_DATE SQL_TIMESTAMP SQL_TIMESTAMP SQL_TIMESTAMP SQL to C Data Conversion Examples The following table illustrates how the driver converts SQL data to C data SQL Data Value tigers tigers 1234 56 1234 56 1234 56 1234 56 1234 56 1234 56 1 2345678 1 2345678 1 2345678 1992 12 31 1992 12 31 1992 12 31 1992 12 31 23 45 55 12 1992 12 31 23 45 55 12 1992 12 31 23 45 55 12 C Data Type SQL_C_CHAR SQL_C_CHAR SQL_C_CHAR SQL_C_CHAR SQL_C_CHAR SQL_C_FLOAT SQL_C_SSHORT SQL_C_STINYINT SQL_C_DOUBLE SQL_C_FLOAT SQL_C_STINYINT SQL_C_CHAR SQL_C_CHAR SQL_C_TIMESTAMP SQL_C_CHAR SQL_C_CHAR SQL_C_CHAR cbValueMax 7 6 ignored ignored ignored ignored ignored ignored 11 10 ignored 23 22 18 rgbValue tigers 0 2 tigerWO 2 1234 56 02 1234 02 1234 56 1234 1 2345678 1 234567 1 1992 12 31 0 2 1992 12 31 0 0 0 0 gt 1992 12 31 23 45 55 12 0 1992 12 31 23 45 55 1 0 4 SQLSTATE N A 01004 N A 01004 22003 N A 01004 22003 01004 22003 a 0 represents a null termination b
354. nds requests to a data source and returns information to the application If the INFORMIX CLI architecture includes a driver manager the INFORMIX CLI driver formats and returns arguments for SOLError because it is the component that interfaces with the driver manager For example if an INFORMIX CLI driver for INFORMIX SE encounters a duplicate cursor name it might return the following arguments for SQLError szSQLState 3C000 pfNativeError NULL szErrorMsg Informix ODBC Informix Driver Duplicate cursor name EMPLOYEE_CURSOR pcbErrorMsg 67 Because the error occurred in the driver it adds prefixes to the error text for the vendor Informix and the driver ODBC Informix Driver Sample Error Returned from the Driver Manager The driver manager can also generate error messages For example if an application passed an invalid argument value to SQLDataSources the driver manager might format and return the following arguments for SQLError szSQLState S1009 pfNativeError NULL szErrorMsg Informix 0DBC DLL Invalid argument value SQLDataSources pcbErrorMsg 60 Because the error occurred in the driver manager it adds prefixes to the error text for its vendor Informix and its identifier ODBC DLL INFORMIX CLI Programmers Manual Processing Error Messages Sample Error Returned from the Data Source If the data source could not find the table EMPLOYEE the driver might format and return the followin
355. ne or more user IDs one or more passwords and other information required by the data source m You can establish a connection using a partial connection string or no additional information in this case INFORMIX CLI can prompt the user for connection information Once a connection is established SOLDriverConnect returns the completed connection string The application can use this string for subsequent connection requests Syntax RETCODE SQLDriverConnect hdbc hwnd szConnStrin cbConnStrin szConnStrOut cbConnStrOutMax pcbConnStrOut fDriverCompletion The SQLDriverConnect function accepts the following arguments Type Argument Use Description HDBC hdbc Input Connection handle HWND hwnd Input Window handle platform dependent For Windows this is the parent window handle For UNIX this is the parent Widget handle If the window handle is not applicable or a null pointer is passed SQLDriverConnect does not present any dialog boxes UCHAR FAR szConnStrin Input A full connection string a partial connection string or an empty string SWORD cbConnStrIn Input Length of szConnStrIn 1 of 2 12 94 INFORMIX CLI Programmers Manual Type UCHAR FAR SWORD SWORD FAR UWORD Argument Use szConnStrOut Output cbConnStrOutMax Input pebConnStrOut Output fDriverCompletion Input Return Codes SQL DriverConnect Description Pointer to storage for the completed connection string Upon successf
356. nect to data source Connection in use Data source rejected establishment of connection Communication link failure Invalid authorization specification Data source not found and no default driver specified Specified driver could not be loaded Driver SOLAllocEnv failed SOLConnect Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The driver could not establish a connection with the data source DM The specified hdbc was already used to establish a connection with a data source and the connection was still open The data source rejected the establishment of the connection for imple mentation defined reasons The communication link between the driver and the data source failed before the function completed The value specified for the argument szUID or the value specified for the argument szAuth
357. nection Strings 4 8 With these functions a connection string has the following syntax connection string empty stringL attributeL attribute connection string empty string attribute attribute keyword attribute value DRIVER attribute value The braces are literal the application must specify them attribute keyword DSN UID PWD CONNECTDATABASE EXCLUSIVE HOST PROTOCOL SERVER SERVICE attribute value character string In this example character string has zero or more characters identifier has one or more characters attribute keyword is case insensitive attribute value might be case sensitive and the value of the DSN keyword does not consist solely of blanks Because of connection string and initialization file grammar avoid keywords and attribute values that contain the characters Because of the registry grammar keywords and data source names cannot contain the backslash If any keywords are repeated in the connection string the driver uses the value associated with the first occurrence of the keyword If the DSN and DRIVER keywords are included in the same connection string INFORMIX CLI uses the keyword that appears first The following table describes the attribute keywords available in INFORMIX CLI These attributes are available with both SOLDriverConnect and SQLBrowseConnect Attribute Keyword Attribute Value D
358. ned The error message returned by SQLError in the argument szErrorMsg describes the error and its cause DM The driver manager did not allocate memory required to support executing or completing the function The driver did not allocate memory required to support executing or completing the function DM The value specified for argument cbConnStrIn was less than 0 and was not equal to SQL_NTS DM The value specified for argument cbConnStrOutMax was less than 0 The time out period expired before the connection to the data source completed The time out period is set through SQLSetConnectOption SQL_LOGIN_TIMEOUT 3 of 3 SQLBrowseConnect Usage Each time an application calls SQLBrowseConnect the function validates the current attributes returns the next level of attributes and returns a user friendly name for each attribute It might also return a list of valid values for those attributes After an application has specified each level of attributes and values SQLBrowseConnect connects to the data source and returns a complete connection string This string can be used with SQLDriverConnect to reconnect to the data source szConnStrIn Argument For information about INFORMIX CLI connection strings see Connection Strings on page 4 7 szConnStrOut Argument The browse result connection string is a list of connection attributes A connection attribute consists of an attribute keyword and a correspondin
359. network traffic Conceptually it is applied when the result set is created and limits the result set to the first vParam rows If the specified number of rows exceeds the number of rows that the data source can return the driver substitutes that value and returns SQLSTATE 01502 Option value changed SQL_NOSCAN A 32 bit integer value that specifies whether the driver does not scan SQL strings for escape clauses m SOL_NOSCAN_OFF The driver scans SQL strings for escape clauses the default m SQL_NOSCAN_ON The driver does not scan SQL strings for escape clauses Instead the driver sends the statement directly to the data source SQL_RETRIEVE_DATA A 32 bit integer value m SQL_RD_ON SQLExtendedFetch retrieves data after it positions the cursor to the specified location This is the default m SQL_RD_OFF SQLExtendedFetch does not retrieve data after it positions the cursor By setting SQL_RETRIEVE_DATA to SQL_RD_OFF an application can verify if a row exists without incurring the overhead of retrieving rows SQL_ROWSET_SIZE A 32 bit integer value that specifies the number of rows in the row set This is the number of rows returned by each call to SOLExtendedFetch The default value is 1 If the specified row set size exceeds the maximum row set size that the data source supports the driver substitutes that value and returns SQLSTATE 01502 Option value changed This option can be specified for an op
360. ng a Connection The following table describes functions that terminate a connection ODBC Function Name Conformance Purpose SQLDisconnect Core Closes the connection SQLFreeConnect Core Releases the connection handle SOLFreeEnv Core Releases the environment handle SQLMoreResults Level 2 Determines whether more results are available on a hstmt Setup Shared Library Function Summary The following table describes setup shared library functions For more infor mation about the syntax and semantics for each function see Chapter 13 Setup Shared Library Function Reference Task Function Name Purpose Setting up datasources ConfigDSN Adds modifies or deletes a data and translators source ConfigTranslator Returns a default translation option 11 10 INFORMIX CLI Programmer s Manual Translation Shared Library Function Summary Translation Shared Library Function Summary The following table describes translation shared library functions Task Function name Purpose Translating SQLDriverToDataSource Translates all data that flows from the data driver to the data source SOLDataSourceToDriver Translates all data that flows from the data source to the driver Function Summary 11 11 INFORMIX CLI Function Reference Arguments i a a ea ce ew a A a a 4 12 6 INFORMIX CLI Include Files 2 2 we we 12 9 Diagnostics o a a ee a 12 9 Tables and Views a a a a e o 12 9 Catalog Func
361. nings important notes or tips This information is always displayed in italics Description The warning icon identifies vital instructions cautions or critical information The important icon identifies significant information about the feature or operation that is being described o The tip icon identifies additional details or shortcuts for the functionality that is being described 6 INFORMIX CLI Programmers Manual Icon Conventions Feature Product and Platform Icons Feature product and platform icons identify paragraphs that contain feature product or platform specific information Icon Description Ss Identifies information that is specific to the Informix Global Language Support GLS feature le e fe 7 Identifies information that is specific to INFORMIX Universal Server Identifies information that is specific to INFORMIX OnLine Dynamic Server Identifies information that is specific to INFORMIX OnLine Ww Workgroup Server Identifies information that is specific to INFORMIX SE Identifies information that is specific to the UNIX operating system Identifies information that is specific to both Windows NT and Windows 95 environments Identifies information that is specific to INFORMIX OnLine XPS These icons can apply to a row in a table one or more paragraphs or an entire section A symbol indicates the end of the feature product
362. nnection attribute the function connects to the data source 11 4 INFORMIX CLI Programmers Manual Retrieving Information About a Driver and Data Source Retrieving Information About a Driver and Data Source The following table describes functions that return information about a driver and data source Function Name SQLDataSources SOLDrivers SOLGetInfo SOLGetFunctions SQLGetTypelInfo ODBC Conformance Level 2 Level 2 Level 1 Level 1 Level 1 Purpose Returns the list of available data sources Returns the list of installed drivers and their attributes Returns information about a specific driver and data source Returns supported driver functions Returns information about supported data types Setting and Retrieving Driver Options The following table describes functions that set and retrieve driver options Function Name SQLSetConnectOption SQLGetConnectOption SOLSetStmtOption SOLGetStmtOption ODBC Conformance Level 1 Level 1 Level 1 Level 1 Purpose Sets a connection option Returns the value of a connection option Sets a statement option Returns the value of a statement option Function Summary 11 5 Preparing SQL Requests Function Name SOLAllocStmt SQLPrepare SQLBindParameter SQLGetCursorName SQLSetCursorName SQLSetScrollOptions Preparing SQL Requests ODBC Conformance Core Core Level 1 Core Core Lev
363. nnects to the data source and copies szConnStrIn to szConnStrOut Otherwise the driver returns SOL_ERROR for SQLDriverConnect After successfully connecting to the data source the driver also sets pcbConnStrOut to the length of szConnStrOut If the user cancels a dialog box presented by INFORMIX CLI SQLDriverConnect returns SOL_NO_DATA_FOUND For information about how the driver manager and the driver interact during the connection process see Usage on page 12 79 INFORMIX CLI Function Reference 12 101 SQL DriverConnect 12 102 Connection Options calling SOLDriverConnect Related Functions For Information About Allocating a connection handle Discovering and enumerating values required to connect to a data source Connecting to a data source Disconnecting from a data source Returning driver descriptions and attributes Freeing a connection handle Setting a connection option INFORMIX CLI Programmer s Manual The driver opens the connection in SOL_MODE_READ_WRITE access mode by default To set the access mode to SOL_MODE_READ_ONLY the application must call SOLSetConnectOption with the SOL_ACCESS_MODE option before See SOLAllocConnect SOLBrowseConnect SQLConnect SQLDisconnect SOLDrivers SQLFreeConnect SQLSetConnectOption SQL Drivers SOLDrivers SQLDrivers lists driver descriptions and driver attribute keywords Syntax RETCODE SQLDrivers henv fDirection szDriverDesc cbDri
364. ns the number of columns in the result set SOLDescribeCol Core Describes a column in the result set SQLColAttributes Core Describes attributes of a column in the result set SQLBindCol Core Assigns storage for a result column and specifies the data type SQLFetch Core Returns a result row SQLExtendedFetch Level 2 Returns multiple result rows 1 of 2 Function Summary 11 7 Retrieving Information About Data Source System Tables 11 8 Function Name SOLGetData SOLMoreResults SQLError Function Name SQLColumnPrivileges SQLColumns SQLForeignKeys SQLPrimaryKeys SOLProcedureColumns INFORMIX CLI Programmers Manual ODBC Conformance Level 1 Level 2 Core ODBC Conformance Level 2 Level 1 Level 2 Level 2 Level 2 Purpose Returns part or all of one column of one row of a result set Useful for long data values Determines whether more result sets are available and if so initializes processing for the next result set Returns additional error or status information 2 of 2 Retrieving Information About Data Source System Tables The following table describes catalog functions that return information about data source system tables Purpose Returns a list of columns and associated privileges for one or more tables Returns the list of column names in specified tables Returns a list of column name or names that make up foreign keys if they exist for a spe
365. ns the results as a standard result set ordered by TABLE_TYPE TABLE_QUALIFIER TABLE_OWNER and TABLE_NAME The following table lists the columns in the result set Important SQLTables might not return all qualifiers owners or tables Applica tions can use any valid qualifier owner or table regardless of whether SQLTables returns it 12 328 INFORMIX CLI Programmer s Manual SQL Tables The lengths of VARCHAR columns as the following table shows are maximums the actual lengths depend on the data source To determine the actual lengths of the TABLE_QUALIFIER TABLE_OWNER and TABLE_NAME columns an application can call SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME LEN and SQL_MAX_TABLE_NAME_LEN options Informix SQL Column Name Data Type Comments TABLE_QUALIFIER VARCHAR 128 Table qualifier identifier NULL if not appli cable to the data source If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have qualifiers TABLE_OWNER VARCHAR 128 Table owner identifier NULL if not appli cable to the data source If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have owners TABLE_NAME VARCHAR 128 Table identifier TABLE_TYPE V
366. ntax and so forth Convention Meaning KEYWORD All keywords appear in uppercase letters in a serif font italics Within text new terms and emphasized words appear in italics Within syntax diagrams values that you are to specify appear in italics boldface Identifiers names of classes objects constants events functions program variables forms labels and reports environment variables database names filenames table names column names icons menu items command names and other similar terms appear in boldface monospace Information that the product displays and information that you enter appear in a monospace typeface KEYSTROKE Keys that you are to press appear in uppercase letters in a sans serif font This symbol indicates the end of feature product platform or compliance specific information gt This symbol indicates a menu item For example Choose Tools gt Options means choose the Options item from the Tools menu Introduction 5 Icon Conventions Tip When you are instructed to enter characters or to execute a command immediately press RETURN after the entry When you are instructed to type the text or to press other keys no RETURN is required Icon Conventions Throughout the documentation you will find text that is identified by several different types of icons This section describes these icons Comment Icons Comment icons identify war
367. null termination byte for character data available to return in rgbValue prior to calling SOLExtendedFetch or SQLFetch or SQL_NO_TOTAL if the function cannot determine the number of available bytes For character data if the number of bytes available to return is SQL_NO_TOTAL or is greater than or equal to cbValueMax the data in rgbValue is truncated to cb ValueMax 1 bytes and is null terminated by the driver For binary data if the number of bytes available to return is SQL_NO_TOTAL or is greater than cbValueMax the data in rgbValue is truncated to cbValueMax bytes For all other types of data the value of cbValueMax is ignored and the driver assumes the size of rgbValue is the size of the INFORMIX CLI C data type specified with fCType For more information about the value returned in pcbValue for each fCType see Converting Data from SQL to C on page B 19 2 of 2 Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_ERROR or SOL_INVALID_ HANDLE INFORMIX CLI Function Reference 12 19 SQLBindCol SQLSTATE Diagnostics Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a d
368. of data N A Length of data gt cbValueMax Truncated data Length of data 01004 SQL_C_LONG Data converted without Data Size of the C N A SQL_C_SHORT truncation data type SQL_C_SLONG E SQL_C_SSHORT Data converted with truncation Truncated data Size of the C 01004 SQL_C_STINYINT of fractional digits gt data type SoC CLONE Conversion of data would result Untouched Untouched 22003 SQL_C_USHORT in loss of whole as opposed to SQL_C_UTINYINT fractional digits Data is not a numeric literal Untouched Untouched 22005 SQL_C_DOUBLE Data is within the range of the Data Size of the C N A SQL_C_FLOAT data type to which the number is data type being converted Data is outside the range of the Untouched Untouched 22003 data type to which the number is being converted Data is not a numeric literal Untouched Untouched 22005 SQL_C_BINARY Length of data lt cbValueMax Data Length of data N A Length of data gt cbValueMax Truncated data Length of data 01004 1 of 2 DataTypes B 21 Converting Data from SQL to C fCType Test rgbValue pcbValue SQLSTATE SQL_C_DATE Data value is a valid date value Data 6 N A Data value is a valid timestamp Data 6 N A value time portion is zero Data value is a valid timestamp Truncated data 6 01004 value time portion is non zero 4 Data value is not a valid date Untouched Untouched 22008 value or timestamp value SQL_C_TIMESTAMP Data value is a valid timestamp
369. ol assigns the storage and INFORMIX CLIC data type for a column in a result set as follows m A storage buffer that receives the contents of a column of data m The length of the storage buffer m A storage location that receives the actual length of the column of data returned by the fetch operation m Data type conversion from the Informix SQL data type to the INFORMIX CLI C data type RETCODE SOQLBindCol hstmt icol fCType rgbValue cbValueMax pcbValue The SOLBindCol function accepts the following arguments Description Statement handle Column number of result data ordered sequen tially left to right starting at 1 The INFORMIX CLI C data type for the result data The possible values are any of the fCType values listed in Appendix B Data Types as well as SOL_C_DEFAULT For more information about data types and conversions see Appendix B Pointer to storage for the data If rgbValue is a null pointer the driver unbinds the column To unbind all columns an application calls SQLFreeStmt with the SQL_UNBIND option 1 of 2 SQLBindCol Typedef Argument Use Description SDWORD cbValueMax Input Maximum length of the rgbValue buffer For character data rgb Value must also include space for the null termination byte For more infor mation about length see Precision Scale Length and Display Size on page B 5 SDWORD _ pcbValue Input SQL_NULL_DATA or the number of bytes FAR excluding the
370. olumn does not have a label the column name is returned If the column is unlabeled and unnamed an empty string is returned The length in bytes of data transferred on an SQLGetData or SOLFetch operation if SQL_C_DEFAULT is specified For numeric data this size can be different than the size of the data stored on the data source For more information see Precision Scale Length and Display Size on page B 5 TRUE if the column is MONEY data type FALSE if the column is not MONEY data type The column name If the column is unnamed an empty string is returned SQL_NO_NULLS if the column does not accept null values SQL_NULLABLE if the column accepts null values SOL_NULLABLE_UNKNOWN if it is not known whether the column accepts null values The owner of the table that contains the column The returned value is implementation defined if the column is an expression or if the column is part of a view If the data source does not support owners or the owner name cannot be determined an empty string is returned The precision of the column on the data source For more information on precision see Precision Scale Length and Display Size on page B 5 2 of 4 INFORMIX CLI Function Reference 12 57 SQL ColAttributes Information fDescType Returnedin Description SQL_COLUMN_QUALIFIER_NAME rgbDesc The qualifier of the table that contains the column The returned value is implementation defined if the column
371. ommit mode described 5 9 specifying 12 285 See also Transactions Batch statements 12 232 Binary data C data type B 12 converting to C B 27 converting to SQL B 38 literal length 12 203 retrieving in parts 12 175 transferring B 13 Binding columns binding type 12 299 code examples 12 134 column attributes 6 5 column wise 6 8 12 127 null pointers 12 22 row wise 6 8 12 128 single row 6 4 SOLBindCol 12 21 unbinding 12 22 See also Converting data Rowsets Binding parameters See Parameters binding Bit data converting to C B 26 converting to SQL B 37 Block cursors 6 9 BOOLEAN data type B 4 Boundaries segment 3 8 Braces 4 8 Browse request connection string 4 8 Browse result connection string 12 43 Buffers allocating 3 8 input 3 9 interoperability 3 8 maintaining pointers 3 8 NULL data 3 10 null pointers 3 9 null termination 3 10 output 3 10 segment boundaries 3 8 truncating data 3 10 See also NULL data Null termination byte BYTE data type B 2 C C data types 2 binary B 12 character B 10 conversion examples B 30 B 41 converting from SQL data types B 19 converting to SQL data types B 31 date B 11 default conversions B 18 numeric B 10 SQL_C_BINARY B 12 SQL_C_BIT B 12 SQL_C_CHAR B 10 SQL_C_DATE B 11 SQL_C_DOUBLE B 10 SQL_C_FLOAT B 10 SQL_C_LONG B 10 SQL_C_SHORT B 10 SQL_C_SLONG B 10 SQL_C_SSHORT B 11 SQL_C_STINYINT B 11 SQL_C_TIMESTAMP B 11 SQL_C_TINYINT B 11 SQL_
372. on about valid search patterns see Search Pattern Arguments on page 12 8 To support enumeration of qualifiers owners and table types SQLTables defines the following special semantics for the szTableQualifier szTableOwner szTableName and szTableType arguments If szTableQualifier is a single percent character and szTableOwner and szTableName are empty strings the result set contains a list of valid qualifiers for the data source All the columns except the TABLE_QUALIFIER column contain nulls If szTableOwner is a single percent character and szTableQualifier and szTableName are empty strings the result set contains a list of valid owners for the data source All the columns except the TABLE_OWNER column contain nulls If szTableType is a single percent character and szTableQualifier szTableOwner and szTableName are empty strings then the result set contains a list of valid table types for the data source All the columns except the TABLE_TYPE column contain nulls If szTableType is not a percent character or an empty string it must contain a list of comma separated values for the table types of interest Each value in the list must be in single quotes or unquoted The following two lists provide an example of these two different formats TABLE VIEW TABLE VIEW If the data source does not support a specified table type SOLTables does not return any results for that type SQLTables retur
373. on occurred The application can compare pcb Value to cbValueMax specified in SOLBindCol to determine which column or columns were truncated If pcbValue is greater than or equal to cbValueMax then truncation occurred If the data value for the column is NULL the driver stores SQL_NULL_DATA in pcb Value Tip The SOL_MAX_LENGTH statement option is intended to reduce network traffic and might not be supported by all drivers To guarantee that data is truncated an application should allocate a buffer of the desired size and specify this size in the cbValueMax argument SQLFetch is valid only after a call that returns a result set For information about conversions allowed by SOLBindCol and SQLGetData see Converting Data from SQL to C on page B 19 Code Example See SOLBindCol SOLColumns SOLProcedures and SOLGetData INFORMIX CLI Programmers Manual Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Returning information about a column in a result set Executing an SQL statement Executing a prepared SQL statement Fetching a block of data or scrolling through a result set Freeing a statement handle Fetching part or all of a column of data Returning the number of result set columns Preparing a statement for execution SQLFetch See SOLBindCol SQLCancel SQLDescribeCol SQLExecDirect SQLExecute SQLExtendedFetch SQLFreeStmt SQLGetData SQLNum
374. onnect hdbc szConnStrIn SQL_NTS szConnStrOut BRWS_LEN amp cbConnStrOut if retcode SQL_NEED_DATA GetUserInput szConnStrOut szConnStrIn while retcode SQL_NEED_DATA if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO Process data after successful connection INFORMIX CLI Function Reference 12 47 SQL BrowseConnect 12 48 retcode SQLAllocStmt hdbc amp hstmt if retcode SQL_SUCCESS SL FreeStmt hstmt SQL_DROP REE E i SQLFreeConnect hdbc Mees Related Functions For Information About Allocating a connection handle Connecting to a data source Disconnecting from a data source Connecting to a data source using a connection string or dialog box Returning driver descriptions and attributes Freeing a connection handle INFORMIX CLI Programmers Manual See SOLAllocConnect SQLConnect SQLDisconnect SQLDriverConnect SQLDrivers SOLFreeConnect SOLCancel SOLCancel SQLCancel cancels the processing on an hstmt or a query Syntax RETCODE SQLCancel hstmt The SOLCancel function accepts the following arguments Typedef Argument Use Description HSTMT hstmt Input Statement handle Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_ERROR or SOL_INVALID_ HANDLE INFORMIX CLI Function Reference 12 49 SQL Cancel Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE val
375. onnected to INFORMIX Universal Server or INFORMIX OnLine Dynamic Server INFORMIX CLI supports the following isolation levels m 0 Read Uncommitted m 1 Read Committed m 3 Serializable The default is 1 INFORMIX CLI also supports an alternative isolation level 1 called cursor stability For information about this option see SQLSetConnectOption on page 12 281 INFORMIX CLI supports transactions only if transaction logging has been enabled for your database The driver is always in auto commit mode which treats each statement as a single transaction INFORMIX CLI Libraries For the locations and filenames of the INFORMIX CLI libraries see the Release Notes INFORMIX CLI provides two versions of its libraries shared and static To link an application with an INFORMIX CLI library specify an additional link library search path for the INFORMIX CLI library and other library names For example CC L INFORMIXDIR 1ib cli libifcli laio Im Insl 1socket This command finds the archive library the shared library and other system dependent libraries 1 8 INFORMIX CLI Programmer s Manual UNIX Environment Variables on UNIX Environment Variables on UNIX Set the INFORMIXDIR environment variable to the full path of the directory where your Informix product is installed The UNIX environment variable PATH indicates the directories that are searched for executable programs Your PATH setting m
376. ontained a date or time parameter or literal and a time stamp value was truncated The prepared statement associated with the hstmt was REVOKE but the user did not have the specified privilege function returns SQL_SUCCESS_WITH_INFO The prepared statement associated with the hstmt was a positioned UPDATE or DELETE statement but no rows were updated or deleted function returns SQL_SUCCESS_WITH_INFO The prepared statement associated with the hstmt was a positioned UPDATE or DELETE statement and more than one row was updated or deleted function returns SQL_SUCCESS_WITH_INFO The number of parameters specified in SOLBindParameter was less than the number of parameters in the prepared statement associated with the hstmt The communication link between the driver and the data source failed before the function completed 1 of 4 SQLSTATE Error 22003 22005 22008 22012 23000 24000 40001 42000 Numeric value out of range Error in assignment Datetime field overflow Division by zero Integrity constraint violation Invalid cursor state Serialization failure Syntax error or access violation SQLExecute Description The prepared statement associated with the hstmt contained a numeric parameter and the parameter value caused the whole as opposed to fractional part of the number to be truncated when assigned to the associated table column The prepared statement associated wi
377. or buffer length Time out expired SQL PutData Description SQLPutData was called more than once for a parameter or column and it was not being used to send character C data to a column with a character binary or data source specific data type or to send binary C data to a column with a character binary or data source specific data type The data sent for a numeric parameter or column caused the whole as opposed to fractional part of the number to be truncated when assigned to the associated table column The data sent for a parameter or column was incompatible with the data type of the associated table column The data sent for a date time or time stamp parameter or column was respectively an invalid date time or time stamp An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver could not allocate memory required to support execution or completion of the function The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application SOLExecute or SOLExecDirect was called for the hstmt and returned SOL_NEED_DATA SOLCancel was called before data was sent for all data at execution parameters or columns DM The argument rgbValue was a null pointer and the arg
378. or name SOLSetCursorName Setting cursor scrolling options SQLSetScrollOptions INFORMIX CLI Function Reference 12 169 SQL GetData SQLGetData SQLGetData returns result data for a single unbound column in the current row The application must call SQLFetch or SQLExtendedFetch to position the cursor on a row of data before it calls SOLGetData It is possible to use SOLBindCol for some columns and use SQLGetData for others within the same row 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 SOL_LONGVARBINARY or SQL_LONGVARCHAR columns Syntax RETCODE SQLGetData hstmt icol fCType rgbValue cbValueMax pcbValue The SOLGetData function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UWORD icol Input Column number of result data ordered sequentially left to right starting at 1 SWORD fCType Input The result data s INFORMIX CLIC data type The possible values are any of the fCType values listed in Appendix B Data Types as well as SOL_C_DEFAULT For more information about data types and conversions see Appendix B PTR rebValue Output Pointer to storage for the data SDWORD cbValueMax Input Maximum length of the rgbValue buffer For character data rgbValue must also include space for the null termination byte For character and binar
379. or the data The application must allocate this buffer which must be large enough to hold the data in its converted form m The length of the output buffer This value is ignored if the returned data has a fixed width in C such as an integer real number or date structure m The address of a storage buffer in which to return the number of bytes of available data 6 4 INFORMIX CLI Programmer s Manual Determining the Characteristics of a Result Set Determining the Characteristics of a Result Set To determine the characteristics of a result set an application can perform the following actions m Call SOLNumResultCols to determine how many columns a request returned m Call SOLColAttributes or SOLDescribeCol to describe a column in the result set If the result set is unknown an application can use the information from these functions to bind the columns in the result set An application can call these functions at any time after a statement is prepared or executed Tip For optimal performance an application should call SOLColAttributes SQLDescribeCol and SQLNumResultCols after a statement executes In data sources that emulate statement preparation these functions sometimes execute more slowly before a statement executes because the information that these functions return is not readily available until after the statement has executed Fetching Result Data You can perform several operations to retrieve data once
380. orresponding INFORMIX CLI data types INFORMIX CLI does not provide full GLS support Informix SQL INFORMIX CLI SQL Data Type Data Type fSqlType Description NCHAR n SQL_CHAR Character string of fixed length n 1 lt n 32 767 Collation depends on locale NVARCHAR m r SQL_VARCHAR Character string of variable length with maximum length m 1 lt m lt 255 and minimum amount of reserved space r 0 lt r lt m Collation depends on locale Data Types B 3 Additional SQL Data Types for Universal Server B 4 Informix SQL INFORMIX CLI SQL Data Type Data Type fSqlType BOOLEAN SQL_BIT DISTINCT DISTINCT can correspond to any INFORMIX CLI SQL data type For more information about DISTINCT see the Informix Guide to SQL Tutorial INT8 SQL_BIGINT LVARCHAR SOL_LONGVARCHAR OPAQUE fixed SOL_INFX_UDT_FIXED OPAQUE varying SOL_INFX_UDT_VARYING SERIAL8 SQL_BIGINT infxcli h INFORMIX CLI Programmer s Manual Additional SQL Data Types for Universal Server The following table lists the additional Informix SQL data types for Universal Server and their corresponding INFORMIX CLI data types Description Y or afr UDT that is stored the same way as its source data type but has different casts and functions Signed numeric value with precision 10 scale 0 and range n 2 1 lt n lt 28 1 Character string of variable length Fixed length UDT with an internal structure that the database ser
381. osition Precision columns procedures 12 261 result sets 12 57 12 87 tables 12 72 12 309 defined B 5 Prepared statements deleting 12 196 Preparing statements 5 6 Preserving cursors 12 196 Primary keys 12 255 Printed manuals Intro 9 Privileges data source 12 197 grantable 12 66 12 323 grantee 12 65 12 322 grantor 12 65 12 322 qualifier usage in 12 210 table user granting 12 65 Procedure columns data type 12 261 listing 12 260 name 12 260 owner name 12 260 parameters 12 29 See also Columns Procedures Procedures defined 12 264 name 12 267 name maximum length 12 204 owner name 12 267 qualifier 12 267 qualifier usage in 12 210 return values 12 30 support of 12 209 term vendor specific 12 209 See also Procedure columns PWD 2 4 2 12 Q Qualifiers current 12 285 foreign key 12 148 index 12 316 maximum length 12 204 primary key 12 255 procedure 12 267 separator 12 209 table 12 58 12 65 12 71 12 315 12 328 term vendor specific 12 209 usage 12 210 Index 7 Queries See SQL statements Question mark parameter markers 12 115 Queues error 12 109 Quoted identifiers case sensitivity 12 210 R Radix 12 73 12 262 Read only access mode 12 102 data sources 12 197 Reads 12 198 Read write access mode 12 102 REAL data type B 3 REFERENCES statements 12 66 Referential integrity 12 207 Refreshing data SQLExtendedFetch 12 133 Release notes Intro 11 Remarks 12 73 12 329 Repeatable read isola
382. ot open General error Memory allocation failure Function sequence error Option type out of range Driver not capable INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO DM An fOption value was specified that required an open connection An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM SQLBrowseConnect was called for the hdbc and returned SOL_NEED_DATA This function was called before SOLBrowseConnect returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS DM The value specified for the argument fOption was in the block of numbers reserved for ODBC connection and statement options but was not valid for the version of ODBC supported by the driver The driver or data source does not support the value specified for the argument fOption INFORMIX CLI Function Reference 12 165 SQL GetConnectOption Usage For a list of options see SQLSetConnectOption Important When fOption specifies an option that returns a string pvParam must be a pointer to storage for the string The maximum length of the string is SQL_MAX_OPTION_STRING_LENGTH bytes excluding the null termination byte Depending on the option an application doe
383. ot have owners Table identifier Column identifier Identifier of the user who granted the privilege NULL if not applicable to the data source 1 of 2 INFORMIX CLI Function Reference 12 65 SQL ColumnPrivileges 12 66 Column Name Data Type GRANTEE VARCHAR 128 not NULL PRIVILEGE VARCHAR 128 not NULL IS_GRANTABLE VARCHAR 3 INFORMIX CLI Programmer s Manual Comments Identifier of the user to whom the privilege was granted Identifies the column privilege Can be one of the following or others supported by the data source when implementation defined SELECT The grantee is permitted to retrieve data for the column INSERT The grantee is permitted to provide data for the column in new rows that are inserted into the associated table UPDATE The grantee is permitted to update data in the column REFERENCES The grantee is permitted to refer to the column within a constraint for example a unique referential or table check constraint Indicates whether the grantee is permitted to grant the privilege to other users YES NO or NULL if unknown or not applicable to the data source 2 of 2 The szColumnName argument accepts a search pattern For more information about valid search patterns see Search Pattern Arguments on page 12 8 Code Example SQL ColumnPrivileges For a code example of a similar function see SOLColumns Related Functions For Inform
384. ource code for INFORMIX CLI enabled applications m An example that uses static SQL functions to create a table add data to it and select the inserted data m An example of interactive ad hoc query processing Constructing an INFORMIX CLI Application 9 3 Static SQL Example Static SQL Example The following example constructs SQL statements within the application The example comments include equivalent embedded SQL calls for illustrative purposes include sql h dinclude lt string h gt ifndef NULL idefine NULL 0 dtendif itdefine MAX_NAME_LEN 50 itdefine MAX_STMT_LEN 100 int print_err HDBC hdbc HSTMT hstmt int examplel server uid pwd UCHAR server UCHAR uid UCHAR pwd HENV henv HDBC hdbce HSTMT hstmt SDWORD id UCHAR name MAX_NAME_LEN 1 UCHAR createLMAX_STMT_LEN UCHAR insert MAX_STMT_LEN CHAR select MAX_STMT_LEN SDWORD namelen RETCODE rc EXEC SQL CONNECT TO server USER uid USING pwd Allocate an environment handle E Allocate a connection handle a Connect to a data source os Allocate a statement handle SQLATlocEnv amp henv SQLATlocConnect henv amp hdbc rc SQLConnect hdbc server SQL_NTS uid SQL_NTS pwd SQL_NTS if rc SQL_SUCCESS 88 rc SQL_SUCCESS_WITH_INFO return print_err hdbc SQL_NULL_HSTMT SQLAllocStmt hdbc amp hstmt EXEC SQL CREATE TABLE NAMEID ID integer NAME varchar 5
385. owners The driver or data source did not support the combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options The time out period expired before the data source returned the requested result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLPrimaryKeys returns the results as a standard result set ordered by TABLE_QUALIFIER TABLE_OWNER TABLE_NAME and KEY_SEQ The following table lists the columns in the result set INFORMIX CLI Function Reference 12 255 SQLPrimaryKeys 12 256 The lengths of VARCHAR columns that the table shows are maximums the actual lengths depend on the data source To determine the actual lengths of the TABLE_QUALIFIER TABLE_OWNER TABLE_NAME and COLUMN_NAME columns call SQLGetInfo with the SOL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SQL_MAX_COLUMN_NAME_LEN options Column Name Data Type Comments not NULL to the data source Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Fetching a block of data or scrolling through a result set Fetching a row of data Returning table statistics and indexes INFORMIX CLI Programmer s Manual TABLE_QUALIFIER VARCHAR 128 Primary key table qualifier identifier null if not applicable to the data source TABLE_OWNER VARCHAR 128 Primary key table owner i
386. owsets 6 8 See also Connection handles Environment handles Statement handles Message file error messages Intro 10 Messages error See Errors Modes access 12 102 auto commit See Auto commit mode manual commit See Manual commit mode Money columns 12 57 MONEY data type B 2 Money data types 12 227 Multiple tier drivers error messages 7 6 identifying data sources 7 5 Multithreading with connection handles 12 11 with environment handles 12 13 with statement handles 12 17 N Names arguments 12 4 correlation 12 195 cursors 12 169 12 292 driver 12 199 index 12 316 localized data types 12 228 procedure 12 267 procedure columns 12 260 server 12 212 tables 12 328 12 329 user 12 216 See also Terms NCHAR data type B 3 Network traffic maximum data length 12 302 packet size 12 287 prepared statements 5 6 Nonrepeatable reads 12 198 NOT NULL clauses 12 205 NULL data collating 12 206 concatenation behavior 12 194 output buffers 3 10 retrieving 12 22 SQLBindParameter 12 32 SQLExtendedFetch 12 128 SQLFetch 12 142 SQLGetData 12 174 SQLPutData 12 271 Null pointers input buffers 3 9 output buffers 3 10 parameter length 12 32 unbinding columns 12 22 Nullable columns 12 57 12 73 12 87 12 262 Null termination byte binary data 12 32 character data 12 32 embedded 3 9 examples B 30 B 41 input buffers 3 9 output buffers 3 10 parameters 5 8 Numeric data C data types B 10 converting to C B 23 converting to SQL B
387. p ConnStrOutl 0 J CmdTextlL create database testl with log CmdTextp amp CmdTextL 0 pcbConnStrOut 1n n Ys the Environment handle v amp henv SQLError cannot be used unless SQLAllocEnv stdout 3 Environment Allocation failed n the Connection handle cConnect henv amp hdbc use SQLError from here on or henv hdbc hstmt SqlState t nStrinp dsn s connectdatabase n0 on L ConnStrInp SQL_NTS tp 250 8pcbConnStrOut R_NOPROMPT the server connecti erConnect hdbc NU ConnStro SQL_DRIVE L_ERROR or henv hdbc hstmt SqlState the statement handle cStmt hdbc amp hstmt L_ERROR or henv hdbc hstmt SqlState Connecting toaDataSource 4 13 Connection Strings fprintf stdout Creating database n Create database stores20 rc SQLExecDirect hstmt CmdTextp SQL_NTS if rc SQL_ERROR printError henv hdbc hstmt SqlState goto Exit fprintf stdout Database successfully created n Exit SQLFreeConnect hdbc SQLFreeEnv henv fprintf stdout n nBye n n in getch return re 4 14 INFORMIX CLI Programmers Manual Related Functions Related Functions The following functions are related to connections drivers and data sources For more information about these functions see Chapter 12 INFORMIX CLI Function Reference
388. parameter values 1 The application calls SQLBindParameter for each parameter to bind buffers for the value rgb Value argument and length pcbValue argument of the parameter For data at execution parameters rgbValue is an application defined 32 bit value such as a parameter number or a pointer to data The value is returned later and can be used to identify the parameter The application places values for input and input output parameters in the rgbValue and pcbValue buffers m For normal parameters the application places the parameter value in the rgbValue buffer and the length of that value in the pcbValue buffer m For data at execution parameters the application places the result of the SOL_LEN_DATA_AT_EXEC length macro in the pcbValue buffer The application calls SOLExecute or SOLExecDirect to execute the SQL statement m If no data at execution parameters exist the process is complete m If any data at execution parameters exist the function returns SQL_NEED_DATA The application calls SQLParamData to retrieve the application defined value specified in the rgbValue argument for the first data at execution parameter to be processed The data at execution parameters are similar to data at execution columns although the value that SOLParamData returns is different for each The application calls SOLPutData one or more times to send data for the parameter More than one call is needed if the data value is la
389. pe argument in SOLBindCol or SOLGetData Finally it stores the data in the location pointed to by the rgbValue argument in SOLBindCol or SOLGetData Data Types B 19 Converting Data from SQL to C B 20 The tables in the following sections describe how the driver or data source converts data that is retrieved from the data source drivers are required to support conversions to all INFORMIX CLI C data types from the INFORMIX CLI SQL data types that they support For a given INFORMIX CLI SQL data type the first column of the table lists the legal input values of the fCType argument in SQLBindCol and SQLGetData The second column lists the outcomes of a test often using the cbValueMax argument specified in SQLBindCol or SQLGetData which the driver performs to determine whether it can convert the data For each outcome the third and fourth columns list the values of the rgbValue and pcbValue arguments specified in SQLBindCol or SOLGetData after the driver attempts to convert the data The last column lists the SOLSTATE returned for each outcome by SOLExtendedFetch SOLFetch or SOLGetData If the fCType argument in SOLBindCol or SOLGetData contains a value for an INFORMIX CLI C data type that is not shown in the table for a given INFORMIX CLI SQL data type SOLExtendedFetch SOLFetch or SOLGetData returns SQLSTATE 07006 Restricted data type attribute violation If the fCType argument contains a value that specifies a conversion from a dr
390. pe out of range SQL data type out of range Invalid argument value Function sequence error Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The data value associated with the fCType argument cannot be converted to the INFORMIX CLI SQL data type identified by the fSqlType argument An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support executing or completing the function DM fCType was invalid DM fSqlType was invalid DM The argument rgbValue was a null pointer the argument pcbValue was a null pointer and the argument fParamType was not SQL_PARAM_OUTPUT DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns 1 of 2 INFORMIX CLI Function Reference 12 27 SQL BindParameter 12 28 S1090 S1093 S1094 S1104 1105 S1C00 SQLSTATE Error Invalid string or buffer length Invalid parameter number Invalid scale value Invalid precision value Invalid parameter type Driver not capable INFORMIX CLI Programmers Manual Description DM The value specified for the argument cbValueMax was
391. pecified for the argument fSqlType was in the block of numbers reserved for ODBC SQL data type indicators but was not a valid ODBC SQL data type indicator The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application 1 of 2 INFORMIX CLI Function Reference 12 223 SQL Get Typelnfo 12 224 SQLSTATE Error S1010 Function sequence error S1C00 Driver not capable S1T00 Time out expired Usage result set INFORMIX CLI Programmer s Manual Description DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns The driver or data source does not support the value specified for the argument fSq Type The combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options was not supported by the driver or data source The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLGetTypelnfo returns the results as a standard result set ordered by DATA_TYPE and TYPE_NAME The following table lists the columns in the SQL Get Typelnfo The lengths of VARCHAR columns shown in the following table are maximums the actual lengths depend on the data source Column Name TYP
392. pecify the number of rows in the row set INFORMIX CLI Programmers Manual The applicatio SQLExtendedFetch n then executes a SELECT statement to return a result set of the employee names and birthdays which is sorted by birthday It calls SQLBindCol to bind the columns of data passing the addresses of storage locations for b oth the data and the returned numbers of bytes Finally the application fetches the row set data with SQLExtendedFetch and prints each employee s name and birthday define ROWS iHdefine NAME_ fdefine BDAY_ UCHAR szN SWORD sAge ROWS SDWORD cbN UDWORD crow irow UWORD rgf SQLSetStmtOpt SQLSetStmtOpt SQLSetStmtOpt retcode SQL n if retcode SQLBindCo SQLBindCo SQLBindCo Fetch 100 LEN 30 LEN 11 ame ROWS NAME_LEN szBirthdayLROWS BDAY_LEN ame ROWS cbAge ROWS cbBirthday ROWS RowStatus ROWS jon hstmt SQL_CONCURRENCY SQL_CONCUR_READ_ONLY jon hstmt SQL_CURSOR_TYPE SQL_CURSOR_KEYSET_DRIVEN jon hstmt SQL_ROWSET_SIZE ROWS ExecDirect hstmt SELECT NAME AGE BIRTHDAY FROM EMPLOYEE ORDER BY 3 2 1 QL_NTS SQL_SUCCESS hstmt 1 SQL_C_CHAR szName NAME_LEN cbName hstmt 2 SQL_C_SSHORT sAge 0 cbAge hstmt 3 SQL_C_CHAR szBirthday BDAY_LEN cbBirthday he rowset data and print each row On an error display a message and exit while TRUE retcod e SQLExtendedFet
393. pelnfo SQLPrepare SQLPrimaryKeys SQLProcedureColumns SQLProcedures SOLSetCursorName SOLSetStmtOption SQLSpecialColumns SOLStatistics SQLTablePrivileges SQLTables SQLDisconnect SOLBrowseConnect SQLConnect SQLDriverConnect SQLExecDirect SQLPrepare SQLSetCursorName SQLExecDirect SQLNativeSql SQLPrepare SQLSetCursorName 5 of 13 SQL STATE Error 40001 42000 70100 IM001 IM002 IM003 IM004 IM005 IM006 IM007 IM008 Serialization failure Syntax error or access violation Operation aborted Driver does not support this function Data source name not found and no default driver specified Specified driver could not be loaded Driver SOLAllocEnv failed Driver SQLAIlocConnect failed Driver SQLSetConnectOption failed No data source or driver specified dialog prohibited Dialog failed SQLSTATE Values Can be returned from SQLExecDirect SQLExecute SQLExtendedFetch SOLFetch SOLExecDirect SQLExecute SQLPrepare SQLCancel All functions except SOLAllocEnv SOLDataSources SQLDrivers SQLError SQLFreeConnect SQLFreeEnv SQLGetFunctions SOLBrowseConnect SQLConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SOLBrowseConnect SQLConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLDriverConnect SQLDriverConnect 6 of 13 INFORMIX CLI Error Codes A 7 SQLS
394. pending on whether or not the system architecture includes a driver manager If a driver manager is not included the INFORMIX CLI driver performs the driver manager functions Architecture with a Driver Manager Figure 1 1 on page 1 5 shows the INFORMIX CLI architecture when a driver manager is included in the system In such a system the driver and driver manager look like a single unit that processes INFORMIX CLI function calls 1 4 INFORMIX CLI Programmers Manual Architecture Figure 1 1 INFORMIX CLI Architecture with a Driver Manager Server a Informix data source N a DBMS including N database server Database Client INFORMIX CLI Operating system and network software Application that i a Oy z INFORMIX CLI C j Informix data source T DBMS including database server Database Operating system and network software 2 Overview of INFORMIX CLI 1 5 Architecture Architecture Without a Driver Manager Figure 1 2 shows the INFORMIX CLI architecture without a driver manager In this type of system the application needs to link to the INFORMIX CLI libraries See INFORMIX CLI Libraries on page 1 8 Figure 1 2 INFORMIX CLI Architecture Without a Driver Manager Server Informix data source A O DBMS including N database server Database Operating system and network software Application that INFO
395. ppendix C Executing SQL Statements 5 5 Preoared Execution 5 6 Prepared Execution Prepare a statement before you execute it if either of the following conditions is true m The application can execute the statement more than once possibly with intermediate changes to parameter values m The application needs information about the result set prior to execution A prepared statement executes faster than an unprepared statement because the data source compiles the statement produces an access plan and returns an access plan identifier to the driver The data source minimizes processing time because it does not have to produce an access plan each time that it executes the statement A prepared statement reduces network traffic because the driver sends the access plan identifier instead of the entire statement to the data source Important Committing or rolling back a transaction either by calling SQLTransact or by using the SQL_AUTOCOMMIT connection option can cause the data source to delete the access plans for all of the statement handles that belong to a connection handle For more information see SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR on page 12 196 To prepare and execute an SQL statement an application performs the following operations 1 Calls SQLPrepare to prepare the statement 2 Sets the values of any statement parameters For more information see Setting Parameter Values
396. pported conversions between the additional Informix SQL data types for GLS and the INFORMIX CLI C data types A solid circle e indicates a supported conversion INFORMIX CLI C Data Type fCType z E E lt E E Z Ez E EUA amp Z 5 Ss ES528862 3856248 452 lt O9096 HR RR 6 B43 BS ES Y A A Fa gt 9 A A 9 E E gt gt gt Q 9 9 Q Q 9 Q 9 9 Q 9 9 Q 9 Q A 947 2724222272 2 2272 2 fi ie ft Informix SQL Data Type AR AA RARA oe A NCHAR o o o o o o o o o NVARCHAR o o o o o o o o o o Data Types B 15 Converting Data ws Additional Conversions for Universal Server The following table shows the supported conversions between the additional Informix SQL data types for Universal Server and the INFORMIX CLI C data types including the additional INFORMIX CLI C data type for Universal Server A solid circle e indicates a supported conversion INFORMIX CLI C Data Type fCType es E H lt E e Z E H Uw E Z e re ee Zen lt 696x793R GB 2458 6 a en eo pee ee loo lo es es oe ee Oy Ms MOD is PO Ha Ms rs Vea be la ls ee S Informix SQL Data 2 2 a a 2221222223292 ann T Oo OOOO O O O O O O O O Ol O Ol ype a A A oooO dad OO OO oOQSN a HR BOOLEAN e DISTINCT oeoeeeeeee eeesee eee eee INT8 o e o J O LVARCHAR J e OPAQUE 4 J SERIAL8 Oo Oo Oo Oo Oo a Use SQL_C_CHAR to access an OPAQUE value in the external format as a string Use SQL_C_BINARY to access an OPAQUE value in the
397. quired to support execution or completion of the function The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multithreaded application DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns The time out period expired before the data source returned the result set The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT INFORMIX CLI Function Reference 12 231 SQL MoreResults Usage SELECT statements return result sets UPDATE INSERT and DELETE state ments return a count of affected rows If any of these statements are batched submitted with arrays of parameters or in procedures they can return multiple result sets or counts If another result set or count is available SOLMoreResults returns SQL_SUCCESS and initializes the result set or count for additional processing After an application calls SQLMoreResults for SELECT statements it can call functions to determine the characteristics of the result set and to retrieve data from the result set After calling SQLMoreResults for UPDATE INSERT or DELETE statements an application can call SQLRowCount If all results have been processed SOLMoreResults returns SQL_NO_DATA_FOUND If a current result set has unfetched rows SOLMoreResults discards that result se
398. r Date and Time Stamp C Data Types 2 of 2 The following table lists the date and time stamp C data types that INFORMIX CLI provides It also lists the corresponding INFORMIX CLI typedefs and standard C data types INFORMIX CLI C Data Type fCType INFORMIX CLI Typedef Standard C Data Type SQL_C_DATE SQL_C_TIMESTAMP DATE_STRUCT TIMESTAMP_STRUCT str S U U str eS ee ee a tagDATE_STRUCT year month day Ore OO DAc e cs tagTIMESTAMP_STRUCT D year D month D day D hour D minute R oo0oo0o00o0oo O ono second D fraction Data Types B 11 Binary C Data Type Binary C Data Type The following table lists the binary C data type that INFORMIX CLI provides It also lists the corresponding INFORMIX CLI typedef and standard C data type INFORMIX CLI C Data Type fCType INFORMIX CLI Typedef Standard C Data Type SQL_C_BINARY UCHAR FAR unsigned char FAR Additional C Data Type for Universal Server The following table lists the additional C data type that INFORMIX CLI provides for Universal Server It also lists the corresponding INFORMIX CLI typedef and standard C data type INFORMIX CLI C Data Type fCType INFORMIX CLI Typedef Standard C Data Type SQL_C_BIT UCHAR unsigned char To use the INFORMIX CLI C data types for Universal Server include infxcli h B 12 INFORMIX CLI Programmer s Manual Transferring Data Tran
399. r Operation canceled SQLExtendedFetch Description Returning the numeric value as numeric or string for one or more columns would cause the whole as opposed to fractional part of the number to be truncated Returning the binary value for one or more columns would cause a loss of binary significance A zero length string was inserted into a string field and the string was bound to a numeric data type so the string was converted to a zero An SQL_C_TIME SQL_C_DATE or SQL_C_TIMESTAMP value was converted to an SQL_CHAR data type and the value was an invalid date time or time stamp respectively A value from an arithmetic expression was returned which resulted in division by zero The hstmt was in an executed state but no result set was associated with the hstmt The transaction in which the fetch was executed was terminated to prevent deadlock An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function A column number specified in the binding for one or more columns was greater than the number of columns in the result set Column 0 was bound with SOLBindCol and the SOL_USE_BOOKMARKS statement option was set to SQL_UB_OFF The function was called but b
400. r Results Binding The steps that an application takes to process a result set depend on what is known about it The following table defines known and unknown result sets Type of Result Set Definition Example Known The application knows the exact For example the following query returns two form of the SQL statement and specific columns therefore the result set when the SELECT EMPNO EMPNAME FROM EMPLOYEE statement compiles Unknown The application does not know the For example the following ad hoc query exact form of the SQL statement or returns all the currently defined columns in the therefore the result set when the EMPLOYEE table statement compiles SELECT FROM EMPLOYEE The application might not predict the format of these results before it executes the command Assigning Storage for Results Binding An application can assign storage for results before or after it executes an SOL statement If an application prepares or executes the SQL statement first it can inquire about the result set before it assigns storage for results For example if the result set is unknown the application must retrieve the number of columns in the result set before it can assign storage for them To associate storage for a column of data an application calls SQLBindCol and passes it the following information m The data type to which the data is to be converted For more information see Appendix B m The address of an output buffer f
401. r a column in a result set SQLBindCol Canceling statement processing SOLCancel Returning privileges for a column or columns SQLColumnPrivileges Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SQLFetch Returning table statistics and indexes SOLStatistics Returning a list of tables in a data source SOLTables Returning privileges for a table or tables SQLTablePrivileges INFORMIX CLI Function Reference 12 75 SQLConnect SQLConnect SQLConnect loads a driver and establishes a connection to a data source The connection handle references where all information about the connection including status transaction state and error information is stored Syntax RETCODE SQLConnect hdbc szDSN cbDSN szUID cbUID szAuthStr cbAuthStr The SOLConnect function accepts the following arguments Type Argument Use Description HDBC hdbc Input Connection handle UCHAR FAR szDSN Input Data source name SWORD cbDSN Input Length of szDSN UCHAR FAR szUID Input User identifier SWORD cbUID Input Length of szUID UCHAR FAR szAuthStr Input Authentication string typically the password SWORD cbAuthStr Input Length of szAuthStr Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE 12 76 INFORMIX CLI Programmers Manual SQLSTATE Error 01000 08001 08002 08004 08S01 28000 IM002 IM003 IM004 General warning Unable to con
402. r a connection handle within the environment that henv identifies Syntax RETCODE SQLAllocConnect henv phdbc The SOLAllocConnect function accepts the following arguments Typedef Argument Use Description HENV henv Input Environment handle HDBC FAR phdbc Output Pointer to storage for the connection handle Return Codes SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_ HANDLE If SOLAllocConnect returns SOL_ERROR it sets the hdbc referenced by phdbc to SQL_NULL_HDBC To obtain additional information the application can call SQLError with the specified henv and with hdbc and hstmt set to SQL_NULL_HDBC and SQL_NULL_HSIMT respectively INFORMIX CLI Function Reference 12 9 SQLAllocConnect Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning 1000 General error S1001 Memory allocation failure S1009 Invalid argument value 12 10
403. r process that runs on your UNIX computer Confirm the service name with your system administrator INFORMIX CLI provides two enhanced connection options with the SQLDriverConnect and SQLBrowseConnect functions These options let your application perform the following special connections m Exclusive database use connection m Server only connection These options are available only inside a connection string 2 of 2 Connecting to a Data Source 4 9 Connection Strings 4 10 Exclusive Database Use Connection An exclusive database use connection allows the application to lock out all other users and applications When this parameter is set to Yes the user or application has exclusive use of the database When it is set to No other users and applications can access the database Server Only Connection A server only connection lets you open a connection between the driver and the database server without connecting to a database This option lets you create new databases or drop existing databases within an application However when you use this option you can execute only the CREATE DATABASE and DROP DATABASE SQL statements To use the server only connection in an application 1 Enter a connection string that specifies the database server where you want to create or drop a database and set CONNECTDATABASE to NO 2 Allocate a statement handle Hstmt 3 Execute SOLExecDirect or SOLPrepare and SQLExecute
404. r s Manual Diagnostics SQL Get Typelnfo When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 08S01 24000 S1000 S1001 S1004 S1008 General warning Communication link failure Invalid cursor state General error Memory allocation failure SQL data type out of range Operation canceled INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The communication link between the driver and the data source failed before the function completed A cursor was already opened on the statement handle An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM The value s
405. ranslator returns a default translation option for a translator It can be in the translator shared library or a separate setup shared library Syntax BOOL ConfigTranslator hwndParent pvOption The ConfigTranslator function accepts the following arguments Type Argument Use Description HWND hwndParent Input Parent window handle The function will not display any dialog boxes if the handle is null DWORD FAR pvOption Output A 32 bit translation option Returns The function returns TRUE if it is successful It returns FALSE if it fails Comments If the translator supports only a single translation option ConfigTranslator returns TRUE and sets pvOption to the 32 bit option Otherwise it determines the default translation option to use ConfigTranslator can display a dialog box with which a user selects a default translation option Related Functions For information about See Getting a translation option SQLGetConnectOption Setting a translation option SQLSetConnectOption Setup Shared Library Function Reference 13 7 INFORMIX CLI Error Codes SOLError returns SOLSTATE values as defined by the X Open and SOL Access Group SOL CAE specification 1992 SOLSTATE values are strings that contain five characters The following table lists SOLSTATE values that the Informix driver can return for SOLError SOLSTATE Values The character string value returned for an SOLSTATE consists of a two character class value fol
406. rds compliance with Intro 12 Information status retrieving 7 8 INFORMIXDIR 1 9 INFORMIXSQLHOSTS 1 10 Initializing data sources 2 3 Input buffers 3 9 Input parameters 12 29 Input output parameters 12 29 INSERT statements affected rows 12 278 privileges 12 66 qualifier usage in 12 210 INT data type B 2 INTS8 data type B 4 Integer data converting to C B 23 converting to SQL B 35 INTEGER data type B 2 Integrity enhancement facility IEF 12 207 Interoperability affected rows 6 5 buffer length 3 8 cursor names 12 292 default C data type B 18 functionality 12 189 functions 12 189 pseudo columns 12 309 SQL statements ALTER TABLE 5 3 12 222 COMMIT 5 9 12 115 12 121 CREATE TABLE 5 3 12 222 ROLLBACK 12 115 12 121 SQLGetData 6 7 6 9 12 175 transactions 5 9 transferring data B 13 Intervals date and time 12 214 Isolation levels cursor stability 12 285 transaction 12 198 J Joins outer 12 208 K Keys foreign 12 147 primary 12 255 Key set driven cursors 6 10 Keywords 4 8 data source specific 12 203 in SQLBrowseConnect 4 8 12 43 in SQLDriverConnect 4 8 L Length available SQLBindParameter 12 33 SQLExtendedFetch 12 128 SQLFetch 12 142 SQLGetData 12 174 Length buffers input 3 9 maximum 3 8 output 3 10 SQLBindCol 12 22 SQLBindParameter 12 31 SQLGetData 12 174 Length columns defined 12 142 12 174 B 5 names 12 203 result sets 12 86 tables 12 72 12 309 Length data at execution 12 32
407. re PREPARE The prepared SQL string can contain any of the valid preparable functions that the X Open specification defines including ALTER CREATE cursor specification searched DELETE dynamic SQL positioned DELETE DROP GRANT INSERT REVOKE searched UPDATE or dynamic SQL positioned UPDATE SQLBindParameter SET DESCRIPTOR Dynamic SQL ALLOCATE DESCRIPTOR and dynamic SQL SET DESCRIPTOR ALLOCATE DESCRIPTOR would normally be issued on the first call to SOLBindParameter for an hstmt Alternatively ALLOCATE DESCRIPTOR can be called during SQOLAllocStmt although this call would not be needed by SQL state ments that do not contain embedded parameters The driver generates the descriptor name SOLSetCursorName none The specified cursor name is used in the DECLARE CURSOR statement that SOLExecute or SOLExecDirect generates 1 of 3 C 2 INFORMIX CLI Programmers Manual INFORMIX CLI to Embedded SQL Embedded SQL INFORMIX CLI Function Statement Comments SQLGetCursorName none Driver cursor name management SOLExecute EXECUTE or Dynamic SQL EXECUTE If the SQL DECLARE CURSOR statement requires a cursor then a and OPEN CURSOR dynamic SQL DECLARE CURSOR statement and a dynamic SOL OPEN are issued at this time SOLExecDirect EXECUTE The INFORMIX CLI function call IMMEDIATE or provides for support for a cursor DECLARE CURSOR specification and statements allowed and OPEN CURSOR in an EXECUTE IMMEDIATE dynamic S
408. reater t probably an UPDATE INSERT or DELET number of affected rows the statement is probably a DDL stat operation was successful and commit SQLNumResultCols hstmt amp nresultcols nresultcols 0 SQLRowCount hstmt amp rowcount if rowcount gt 0 statement If the El han 0 the statement was E statement so print the ement so print that the it printf l1d rows affected n rowcount else printf Operation successful n SQLTransact hdbc SQL_COMMIT If the number of affected rows is 0 El ah Ay Otherwise display the column names of the result set and use the display_size function to compute the length needed by each data type Next bind the columns and sp converted to char truncation messages as necessary else for i 0 i lt nresultcols i SQLDescribeCol hstmt i 1 amp nullable colname ecify all data will be collen i display_size coltype collen i colname printf s collen i collen i colname data i UCHAR malloc collenli 1 SQLBindCol hstmt amp outlenLil while TRUE rc SQLFetch hstmt if rc SQL_SUCCESS rc errmsgl0 0 for i 0 i lt nresultcols i 1 SQL_C_CHAR datali collenli SQL_SUCCESS_WITH_INFO i if Coutlenli SQL_NULL_DATA Istrcpy data li NULL else if outlen i gt collenli sprintf amp errmsgLstrlen errmsg
409. regardless of the sort order SQL_NUMERIC_FUNCTIONS 12 206 INFORMIX CLI Programmer s Manual A 32 bit bitmask that enumerates the scalar numeric functions supported by the driver and associated data source The following bitmasks are used to determine which numeric functions are supported SQL_FN_NUM_ABS SQL_FN_NUM_ACOS SQL_FN_NUM_ASIN SQL_FN_NUM_ATAN SQL_FN_NUM_ATAN2 SQL_FN_NUM_CEILING SQL_FN_NUM_COS SQL_FN_NUM_COS SQL_FN_NUM_DEGREES SQL_FN_NUM_EXP SQL_FN_NUM_FLOOR SQL_FN_NUM_LOG SQL_FN_NUM_LOG10 SQL_FN_NUM_MOD SQL_FN_NUM_PI SQL_FN_NUM_POWER SQL_FN_NUM_RADIANS SQL_FN_NUM_RAND SQL_FN_NUM_ROUND SQL_FN_NUM_SIGN SQL_FN_NUM_SIN SQL_FN_NUM_SORT SQL_FN_NUM_TAN SQL_FN_NUM_TRUNCATE Z Z Zi ZZZ ZZ ZZ Z ZZZ Z A G A A ZZZZZZ CCE acacia e Z Z 14 of 24 InfoType SQL_ODBC_API_CONFORMANCE SQLGetInfo Returns A 16 bit integer value that indicates the level of ODBC conformance m SQL_OAC_NONE None m SOL_OAC_LEVEL1 Level 1 supported m SQL_OAC_LEVEL2 Level 2 supported For a list of functions and conformance levels see Chapter 11 Function Summary SOL_ODBC_SAG_CLI CONFORMANCE A 16 bit integer value that indicates compliance to the functions of the SAG specification m SQL_OSCC_NOT_COMPLIANT Not SAG compliant one or more core functions are not supported m SQL_OSCC_COMPLIANT SAG compliant SQL_ODBC_SQL_CONFORMANCE A 16 bit integer value t
410. rger than the rgb Value buffer specified in SQLPutData multiple calls to SQLPutData for the same parameter are allowed only when sending character C data or binary C data INFORMIX CLI Programmers Manual SQLBindParameter 6 The application calls SQLParamData again to signal that all data was sent for the parameter m If more data at execution parameters exist SOLParamData returns SOL_NEED_DATA and the application defined value for the next data at execution parameter to be processed The appli cation repeats steps 5 and 6 m fno more data at execution parameters exist the process is complete If the statement executes successfully SOLParamData returns SOL_SUCCESS or SOL_SUCCESS_WITH_INFO if the execution fails it returns SOL_ERROR At this point SQLParamData can return any SQLSTATE that can be returned by the function used to execute the statement SOLExecDirect or SOLExecute Output values for any input output or output parameters are available in the rgbValue and pcbValue buffers after the appli cation retrieves any result sets that the statement generates If after SOLExecute or SOLExecDirect returns SOL_NEED_DATA and before data is sent for all data at execution parameters the statement is canceled or an error occurs in SOLParamData or SQLPutData the application can call only SOLCancel SOLGetFunctions SOLParamData or SQLPutData with the hstmt or the hdbc associated with the hstmt If the application calls any oth
411. river manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 S1000 S1001 S1002 S1003 S1010 S1090 S1C00 12 20 General warning General error Memory allocation failure Invalid column number Program type out of range Function sequence error Invalid string or buffer length Driver not capable INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SOLSTATE existed and for which no implementation specific SOLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support executing or completing the function The value specified for the argument icol exceeded the maximum number of columns that the data source supports DM The argument fCType was not a valid INFORMIX CLI C data type or SOL_C_DEFAULT DM SOLExecute or SOLExecDirect was called for the hstmt and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value specified for the argument cbVal ueMax was less than 0 The driver does not support the INFORMIX CLI C data type specified in the argumen
412. rivileges Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source failed before the function completed 24000 Invalid cursor state A cursor was already opened on the statement handle S1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause S1001 Memory allocation The driver was unable to allocate memory failure required to support execution or completion of the function S1010 Function sequence DM SOLExecu
413. rmined in advance the driver sets pcbValue to SOL_NO_TOTAL When an application uses SOLExtendedFetch to retrieve more than one row of data it needs to call SOLBindCol only once for each column of the result set in the same way that it binds a column in order to retrieve a single row of data with SQLFetch The SQLExtendedFetch function coordinates placing each row of data into subsequent locations in the row set buffers For additional information about binding row set buffers see SQLExtendedFetch on page 12 123 An application can call SOLBindCol to bind a column to a new storage location regardless of whether data has already been fetched The new binding replaces the old binding The new binding does not apply to data already fetched it takes effect the next time SQLFetch or SOLExtendedFetch is called To unbind a single bound column an application calls SOLBindCol and specifies a null pointer for rgbValue if rgbValue is a null pointer and the column is not bound SOLBindCol returns SOL_SUCCESS To unbind all bound columns an application calls SOLFreeStmt with the SOL_UNBIND option 12 22 INFORMIX CLI Programmers Manual SQLBindCol Code Example In the following example an application executes a SELECT statement to return a result set of the employees names ages and birthdays which is sorted by birthday It then calls SQLBindCol to bind the columns of data to local storage locations Finally the application fe
414. rn is greater than or equal to cbSqlStrMax the translated SQL string in szSqlStr is truncated to cbSqlStrMax 1 bytes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_ HANDLE INFORMIX CLI Function Reference 12 233 SQLNativeSql Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 01004 08003 37000 S1000 General warning Data truncated Connection not open Syntax error or access violation General error 12 234 INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer szSqlStr was not large enough to return the entire SQL string so the SQL string was truncated The argument pcbSglStr contains the length of the untruncated SQL string function returns SQL_SUCCESS_WITH_INFO The hdbc was not in a connected state The argument szSqlStrIn contained an SQL stat
415. rned in rgbInfoValue accordingly For an example of how an application could retrieve data from a 32 bit bitmask see Code Example on page 12 216 INFORMIX CLI Function Reference 12 187 SQL Getinfo A driver must return a value for each information type defined in the following tables If an information type does not apply to the driver or data source the driver returns one of the following values Format of rgbInfoValue Returned Value Character string Y or N N Character string not Y or N Empty string 16 bit integer 0 32 bit bitmask or 32 bit binary value OL For example if a data source does not support procedures SOLGetInfo returns the following values for the fInfoType values which are related to procedures flnfoType Returned Value SQL_PROCEDURES N SQL_ACCESSIBLE_PROCEDURES N SQL_MAX_PROCEDURE_NAME_LEN 0 SQL_PROCEDURE_TERM Empty string SQLGetInfo returns SOLSTATE S1096 Invalid argument value for a value of finfoType that the INFORMIX CLI driver does not define 12 188 INFORMIX CLI Programmer s Manual SQLGetInfo Information Types This section lists the information types supported by SQLGetInfo Infor mation types are grouped categorically and listed alphabetically Driver Information The following values of fInfoType return information about the INFORMIX CLI driver such as the number of active statements the data source name and the API conformance levels SQL_ACT
416. rocessing 24000 Invalid cursor state DM A cursor was open on the hstmt and SQLFetch or SQLExtendedFetch had been called A cursor was open on the hstmt but SOLFetch or SQLExtendedFetch was not called IM001 Driver does not DM The driver associated with the hstmt does support this not support the function function S1000 General error An error occurred for which there was no specific SQLSTATE and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause 1 of 2 INFORMIX CLI Programmer s Manual SQLSTATE 1001 S1010 S1090 S1C00 S1T00 Error Memory allocation failure Function sequence error Invalid string or buffer length Driver not capable Time out expired SQLProcedureColumns Description The driver was unable to allocate memory required to support execution or completion of the function DM SQLExecute SQLExecDirect or SQLSetPos was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value of one of the name length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corresponding qualifier or name A procedure qualifier was specified and the driver or data source does not support qualif
417. roduction About This Manual Types of Users Software Dependencies Demonstration Database Documentation Conventions Typographical Conventions Icon Conventions Comment Icons Feature Product and Platform Ions y Compliance Icons Screen Illustration Conventions Additional Documentation On Line Manuals Printed Manuals On Line Help Error Message Files Documentation Notes and Release Notes Compliance with Industry Standards Informix Welcomes Your Comments Nooo CONAA TV Be Ha 0 0 2 INFORMIX CLI Programmers Manual ead this introduction for an overview of the information provided in this manual and for an understanding of the documentation conventions used About This Manual This manual is a user guide and reference manual for INFORMIX CLI which is the Informix implementation of the Microsoft Open Database Connectivity ODBC interface Version 2 5 This manual explains how to use the INFORMIX CLI application programming interface API to access an Informix database and interact with an Informix database server Types of Users This manual is for C programmers who are using INFORMIX CLI to access Informix relational databases This manual assumes that you know C programming and are familiar with the structure of relational databases If you have limited experience with relational databases SQL or your operating system see the Getting Started manual for your database server for a
418. rror if the key set size is greater than 0 and less than the row set size SQL_MAX_LENGTH A 32 bit integer value that specifies the maximum amount of data that the driver returns from a character or binary column If vParam is less than the length of the available data SOLFetch or SOLGetData truncates the data and returns SQL_SUCCESS If vParam is 0 the default the driver attempts to return all available data If the specified length is less than the minimum amount of data that the data source can return the minimum is 254 bytes on many data sources or greater than the maximum amount of data that the data source can return the driver substitutes that value and returns SQLSTATE 01502 Option value changed This option is intended to reduce network traffic and should only be supported when the data source as opposed to the driver in a multiple tier driver can implement it To truncate data an application should specify the maximum buffer length in the cbValueMax argument in SQLBindCol or SQLGetData In ODBC 1 0 this statement option only applied to SOL_LONGVARCHAR and SQL_LONGVARBINARY columns of 4 INFORMIX CLI Function Reference 12 301 SQL SetStmtOption fOption SQL_MAX_ROWS vParam Contents A 32 bit integer value corresponding to the maximum number of rows to return to the application for a SELECT statement If vParam equals 0 the default then the driver returns all rows This option is intended to reduce
419. rror in row in the error queue After the driver processes the error or warning it continues the operation for the remaining rows in the row set and returns SOL_SUCCESS_WITH_INFO Thus for each error that pertains to a single row the error queue contains SOLSTATE 01501 Error in row followed by zero or more additional SQLSTATEs After the driver processes the error it fetches the remaining rows in the row set and returns SOL_SUCCESS_WITH_INFO Thus for each row that returns an error the error queue contains SQLSTATE 01501 Error in row followed by zero or more additional SOLSTATE values INFORMIX CLI Function Reference 12 131 SQLExtendedFetch y 12 132 If the row set contains rows that are already fetched the driver is not required to return SOLSTATE values for errors that occurred when the rows were first fetched However it is required to return SOLSTATE 01501 Error in row for each row in which an error originally occurred and to return SOL_SUCCESS_WITH_INFO For example a static cursor that maintains a cache might cache row status information so that it can determine which rows contain errors but might not cache the SOLSTATE associated with those errors Error rows do not affect relative cursor movements For example suppose the result set size is 100 and the row set size is 10 If the current row set is rows 11 through 20 and the element in the rgfRowStatus array for row 11 is SOL_ROW_ERROR calling SOLExtendedFe
420. rs such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have qualifiers Varchar 128 Primary key table owner identifier NULL if not applicable to the data source If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have owners Varchar 128 Primary key table identifier not NULL Varchar 128 Primary key column identifier not NULL Varchar 128 Foreign key table qualifier identifier NULL if not applicable to the data source If a driver supports qualifiers for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables that do not have qualifiers 1 of 2 12 148 INFORMIX CLI Programmers Manual Column Name FKTABLE_OWNER FKTABLE_NAME FKCOLUMN_NAME KEY_SEQ UPDATE_RULE DELETE_RULE FK_NAME PK_NAME Data Type Varchar 128 Varchar 128 not NULL Varchar 128 not NULL Smallint not NULL Smallint Smallint Varchar 128 Varchar 128 SQLForeignKeys Comments Foreign key table owner identifier NULL if not applicable to the data source If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs it returns an empty string for those tables th
421. rs 12 212 in SQLBrowseConnect 12 43 SQL data types See SQL data types dynamic C 7 embedded executing statements 5 5 function equivalents C 1 to C 10 ODBC function equivalents C 5 C 6 information types 12 191 12 192 interoperability 5 4 static 9 4 See also SQL statements SQL Access Group 12 207 SQL data types BOOLEAN B 4 BYTE B 2 CHAR B 2 CHARACTER B 2 CHARACTER VARYING B 2 columns procedures 12 261 result sets 12 56 conversion examples B 30 B 41 converting from C data types B 31 converting to C data types B 19 DATE B 2 DATETIME B 2 DEC B 2 DECIMAL B 2 default C data types B 18 display size B 5 DOUBLE PRECISION B 2 FLOAT B 2 INT B 2 INT8 B 4 INTEGER B 2 length B 5 LVARCHAR B 4 MONEY B 2 NCHAR B 3 NUMERIC B 2 NVARCHAR B 3 OPAQUE B 4 precision B 5 REAL B 3 scale B 5 SERIAL B 3 SERIAL8 B 4 SMALLFLOAT B 3 SMALLINT B 3 SQL_BIGINT B 4 SQL_BIT B 4 SQL_CHAR B 2 SQL_DATE B 2 SQL_DECIMAL B 2 SQL_DOUBLE B 2 SQL_INFX_UDT_FIXED B 4 SQL_INFX_UDT_VARYING B 4 SQL_INTEGER B 2 SQL_LONGVARBINARY B 2 SQL_LONGVARCHAR B 3 B 4 SQL_REAL B 3 SQL_SMALLINT B 3 SQL_TIMESTAMP B 2 SQL_VARCHAR B 2 supported 12 224 TEXT B 3 VARCHAR B 3 See also C data types Converting data SQL identifiers 12 212 SQL quoted identifiers 12 210 SQL statements batch 12 232 direct execution 5 7 embedded C 5 ODEC function equivalents C 6 equivalents C 1 to C 10 information types 12 191 maximum length 12 204 native 12 233 qual
422. s discards pending results and frees all resources associated with the statement handle m SQL_UNBIND This option frees all return buffers bound by SQLBindCol for the statement handle m SQL_RESET_PARAMS This option frees all parameter buffers requested by SOLBindParameter for the statement handle Terminating Transactions and Connections 8 3 Terminating Transactions Terminating Transactions An application calls SQLTransact to commit or roll back the current transaction Terminating Connections To terminate a connection to a driver or to a data source an application closes the connection associated with a connection handle and frees the connection and environment handles To terminate a connection to a driver and data source an application performs the following operations 1 It calls SOLDisconnect to close the connection You can then use the handle to reconnect to the same data source or to a different data source 2 It calls SQLFreeConnect to free the connection handle and free all resources associated with the handle 3 It calls SOLFreeEnv to free the environment handle and free all resources associated with the handle 8 4 INFORMIX CLI Programmer s Manual Constructing an INFORMIX CLI Application Static SQL Example o 9 4 Interactive Ad Hoc Query Example 2 1 ww 9 7 9 2 INFORMIX CLI Programmer s Manual his chapter provides the following examples of C language s
423. s SQLExecDirect 10 11 Updating Data eae ee a ew a o 10 12 Using Positioned Updates ahd Deletes Boe ow 2 ee eee a 1012 Determining the Optimal Set of Columns 10 12 Committing Data 2 ee ee ee 10 14 Chapter 11 Function Summary INFORMIX CLI Function Summary 2113 Connecting to a DataSource o 11 4 Retrieving Information About a Driver and Data ute co 11 5 Setting and Retrieving Driver Options 13 Preparing SQL Requests 1 6 Submitting SQL Requests ios cee oa 1156 Retrieving Results and Information About Results Sage ae ae E U Retrieving Information About Data Source System Tables 11 8 Terminating a Statement 1 9 Terminating a Connection 11 10 Setup Shared Library Function Summary 11 10 Translation Shared Library FunctionSummary H 0 vi INFORMIX CLI Programmer s Manual Chapter 12 Chapter 13 Appendix A Appendix B Appendix C INFORMIX CLI Function Reference Arguments INFORMIX CLI Include Files Diagnostics Tables and Views Catalog Functions Search Pattern Arguments Setup Shared Library Function Reference ConfigDSN ConfigTranslator INFORMIX CLI Error Codes Data Types Comparison of INFORMIX CLI and Embedded SQL Index 12 4 12 7 12 7 12 7 12 7 12 8 133 13 7 Table of Contents vii Int
424. s are added during the installation procedure An application can call SQLDrivers multiple times to retrieve all driver descriptions A driver manager retrieves this information from the odbcinst ini file When no more driver descriptions remain SQLDrivers returns SOL_NO_DATA_FOUND If SQLDrivers is called with SOL_FETCH_NEXT immediately after it returns SOL_NO_DATA_FOUND it returns the first driver description If SQL_FETCH_NEXT passes to SOLDrivers the first time it is called SOLDrivers returns the first data source name Related Functions For Information About See Discovering and listing values required to connect to a SOLBrowseConnect data source Connecting to a data source SOLConnect Returning data source names SQLDataSources Connecting to a data source using a connection string or SQLDriverConnect dialog box 12 106 INFORMIX CLI Programmer s Manual Type HENV HDBC HSTMT UCHAR FAR SDWORD FAR UCHAR FAR SWORD SWORD FAR SQLError SQLError SOLError returns error or status information Syntax RETCODE SQLError henv hdbc hstmt szSqlState pfNativeError szErrorMsg cbErrorMsgMax pcbErrorMsg The SOLError function accepts the following arguments Argument Use Description henv Input Environment handle or SQL_NULL_HENV hdbc Input Connection handle or SQL_NULL_HDBC hstmt Input Statement handle or SQL_NULL_HSTMT szSqlState Output SQLSTATE as null terminated string For a
425. s not need to establish a connection prior to calling SQLGetConnectOption However if SQLGetConnectOption is called and the specified option does not have a default and has not been set by a prior call to SQLSetConnectOption SOLGetConnectOption returns SQL_NO_DATA_FOUND Although an application can set statement options using SQLSetConnectOption an application cannot use SOLGetConnectOption to retrieve statement option values it must call SOLGetStmtOption to retrieve the settings of statement options Related Functions For Information About See Returning the setting of a statement option SQLGetStmtOption Setting a connection option SQLSetConnectOption Setting a statement option SQLSetStmtOption 12 166 INFORMIX CLI Programmer s Manual SQL GetCursorName SQLGetCursorName SQLGetCursorName returns the cursor name associated with a specified hstmt Syntax RETCODE SQLGetCursorName hstmt szCursor cbCursorMax pcbCursor The SQLGetCursorName function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szCursor Output Pointer to storage for the cursor name SWORD cbCursorMax Input Length of szCursor SWORD FAR pcbCursor Output Total number of bytes excluding the null termination byte available to return in szCursor If the number of bytes available to return is greater than or equal to cbCursorMax the cursor name in szCursor is truncated to
426. s the prepared statement Creating a stored procedure has substantial overhead but the driver assumes that the statement will be executed multiple times In this case although stored procedure creation is relatively expensive execution is minimal because the query is parsed and optimization paths are stored when the procedure is created However for such a driver if the statement is executed only once unneeded overhead results In general applications that use SOLPrepare and SQLExecute for large single execution query batches almost certainly cause poor performance Similarly applications that always use SQLExecDirect cannot perform as well as those that logically use a combination of SQLPrepare SOLExecute and SOLExecDirect sequences Designing Performance Oriented Applications 10 11 Updating Data Updating Data Use positioned updates and deletes and SQLSpecialColumns to improve the performance of your application Using Positioned Updates and Deletes Although positioned updates do not apply to all types of applications try to use positioned updates and deletes whenever possible Positioned updates with UPDATE WHERE CURRENT OF CURSOR allow you to update data by positioning the database cursor to the row to be changed and signaling the driver to change the data You are not forced to build a complex SQL statement you simply supply the data to be changed Besides making the code more maintainable positioned updates
427. s to a different driver on the connection handle Some connection and statement options support substituting a similar value if the data source does not support the specified value of vParam In such cases the driver returns SOL_SUCCESS_WITH_INFO and SOLSTATE 01502 Option value changed For example if fOption is SOL_PACKET_SIZE and vParam exceeds the maximum packet size the driver substitutes the maximum size To determine the substituted value an application calls SQLGetConnectOption for connection options or SQLGetStmtOption for statement options The format of information set through vParam depends on the specified fOption SOLSetConnectOption accepts option information in one of two formats a null terminated character string or a 32 bit integer value The format of each fOption is noted in the following table Character strings pointed to by the vParam argument of SOLSetConnectOption have a maximum length of SOL_MAX_OPTION_STRING_LENGTH bytes excluding the null termination byte INFORMIX CLI Programmers Manual SQL SetConnectOption In addition to the options described in the following table INFORMIX CLI supports an alternative isolation level 1 called cursor stability To use this isolation level your INFORMIX CLI application should call SQLSetConnectOption with the fOption value set to 1040 and vParam set to 1 fOption vParam Contents SQL_ACCESS_MODE SQL_AUTOCOMMIT SQL_CURRENT_QUALIFIER A 32 bit in
428. s unknown an empty string is returned 3 of 4 12 58 INFORMIX CLI Programmers Manual fDescType SQL_COLUMN_UNSIGNED SQL_COLUMN_UPDATABLE Information Returned in pfDesc pfDesc SQLColAttributes Description TRUE if the column is unsigned or not numeric FALSE if the column is signed Column is described by the values for the defined constants SQL_ATTR_READONLY SQL_ATTR_WRITE SQL_ATTR_READWRITE_UNKNOWN SQL_COLUMN_UPDATABLE describes the updatability of the column in the result set Whether a column is updatable can be based on the data type user privileges and the definition of the result set itself If it is unclear whether a column is updatable SQL_ATTR_READWRITE_UNKNOWN should be returned 4 0f 4 INFORMIX CLI Function Reference 12 59 SQL ColAttributes ws Additional Descriptor Types for Universal Server The following table shows the additional descriptor types for Universal Server and the arguments in which information is returned for them If a descriptor type does not apply to a driver or data source then unless otherwise stated the driver returns 0 in pcbDesc or an empty string in rgbDesc Information fDescType Returnedin Description SQL_INFX_ATTR_FLAGS pfDesc Type attribute flags These flags indicate whether the column type is NULLABLE and or is a DISTINCT type Two macros ISNULLABLE and ISDISTINCT are provided to test the flag value SQL_INFX_ATTR_EXTENDED_T
429. sages manual 10 INFORMIX CLI Programmers Manual UNIX Documentation Notes and Release Notes Documentation Notes and Release Notes In addition to printed documentation the following on line files supplement the information in this manual For UNIX these files are located in the INFORMIXDIR release en_us 0333 directory For Windows these files are located in the INFORMIXDIR release en_us 04e4 directory On Line File CLIDOC_2 8 CLIENTS_2 0 CLI_2 8 Purpose The documentation notes file describes features that are not covered in this manual or that have been modified since publication For Windows click the INFORMIX CLI Document Notes icon The CLIENTS_2 0 file lists the release notes files for the 2 0 Client SDK These release notes files describe feature differ ences from earlier versions of Informix products and how these differences might affect current products These files also contain information about any known problems and their workarounds For Windows click the INFORMIX CLI Release Notes icon The machine notes file describes any special actions that are required to configure and use Informix products on your computer Please examine these files because they contain vital information about application and performance issues Introduction 11 Compliance with Industry Standards 12 Compliance with Industry Standards INFORMIX CLI is based on Version 2 5 of the Microsoft Open Databa
430. same and returns the following string in szConnStrOut DATABASE Database master model empdata INFORMIX CLI Programmers Manual SQLBrowseConnect The application passes this string to its GetUserInput routine which provides a dialog box that asks the user to select a database The user selects empdata and the application calls SQLBrowseConnect a final time with the following string DATABASE empdata This is the final piece of information that the driver needs to connect to the data source SOLBrowseConnect returns SOL_SUCCESS and szConnStrOut contains the completed connection string DSN My Source HOST red UID Smi th PWD Sesame DATABASE empdata itdefine BRWS_LEN 100 HENV henv HDBC hdbe HSTMT hstmt RETCODE retcode UCHAR szConnStrIn BRWS_LEN szConnStrOut BRWS_LEN SWORD cbConnStrOut retcode SQLAllocEnv amp henv Environment handle if retcode SQL_SUCCESS retcode SQLAllocConnect henv amp hdbc Connection handle if retcode SQL_SUCCESS Call SQLBrowseConnect until it returns a value other than SQL_NEED_DATA pass the data source name the first time If SQL_NEED_DATA is returned call GetUserInput not xf shown to build a dialog from the values in szConnStrOut The user supplied values are returned in szConnStrIn which is passed in the next call to SQLBrowseConnect 7 Istrepy szConnStrIn DSN MyServer do retcode SQLBrowseC
431. scription HDBC hdbc Input Connection handle UWORD finfoType Input Type of information The fInfoType argument must be a value that represents the type of interest For more information see Usage on page 12 187 1 of 2 12 184 INFORMIX CLI Programmers Manual Type Argument Use PTR rebInfoValue Output SWORD cbInfoValueMax Input SWORD FAR pcbInfoValue Output Return Codes SQLGetInfo Description Pointer to storage for the information Depending on the fInfoType requested the information returned will be one of the following a null terminated character string a 16 bit integer value a 32 bit flag or a 32 bit binary value Maximum length of the rgbInfo Value buffer The total number of bytes excluding the null termination byte for character data available to return in rebInfo Value For character data if the number of bytes available to return is greater than or equal to cbInfoValueMax the infor mation in rgbInfoValue is truncated to cbInfo ValueMax 1 bytes and is null terminated by the driver For all other types of data the value of cbValueMax is ignored and the driver assumes the size of rgbValue is 32 bits 2 of 2 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 185 SQL Getinfo 12 186 Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SO
432. se Connectivity specification which in turn is based on the X Open Group SQL Access Call Level Interface CLI specification The ODBC and CLI specifica tions provide a common and open interface through which ANSI compliant SQL is passed Informix Welcomes Your Comments Please tell us what you like or dislike about our manuals To help us with future versions of our manuals we want to know about corrections or clari fications that you would find useful Include the following information m The name and version of the manual that you are using m Any comments that you have about the manual m Your name address and phone number Write to us at the following address Informix Software Inc SCT Technical Publications Department 4100 Bohannon Drive Menlo Park CA 94025 If you prefer to send email our address is doc informix com Or send a facsimile to the Informix Technical Publications Department at 650 926 6571 We appreciate your feedback INFORMIX CLI Programmers Manual Overview of INFORMIX CLI What Is INFORMIX CLI Architecture Architecture with a Driver Manager Architecture Without a Driver erase What Is a Data Source Advantages of Using INFORMIX CLI Isolation and Lock Levels INFORMIX CLI Libraries Environment Variables on UNIX Setting Environment Variables in a File Setup File GLS Client Locale Database Locale Translation Library Translation Option VMB Charact
433. seConnect returns successive levels of attributes and attribute values When all levels are enumerated a connection to the data source is completed and SOLBrowseConnect returns a complete connection string A return code of SQL_SUCCESS_WITH_INFO or SQL_SUCCESS indicates that all connection information was specified and the application is now connected to the data source Syntax RETCODE SQLBrowseConnect hdbc szConnStrin cbConnStrin szConnStr0ut cbConnStr0utMax pcbConnStrOut The SOLBrowseConnect function accepts the following arguments Typedef Argument Use Description HDBC hdbc Input Connection handle UCHAR FAR szConnStrin Input Browse request connection string For more information see szConnStrIn Argument on page 12 43 SWORD cbConnStrIn Input Length of szConnStrIn 1 of 2 12 38 INFORMIX CLI Programmer s Manual Typedef Argument Use UCHAR FAR szConnStrOut Output SWORD cbConnStrOutMax Input SWORD FAR pcbConnStrOut Output Return Codes SQLBrowseConnect Description Pointer to storage for the browse result connection string For more information see szConnStrOut Argument on page 12 43 Maximum length of the szConnStrOut buffer The total number of bytes excluding the null termination byte available to return in szConnStrOut If the number of bytes available to return is greater than or equal to cbConnStrOutMax the connection string in szConnStrOut is truncated to coConnStrO
434. section has a Translator Specification section that describes the translator Adding a Data Source 1 Adda Data Source Specification section for the data source to odbc ini 2 If necessary add an entry for the database server to sqlhosts 3 If you use an ODBC driver manager from a third party vendor a If the ODBC Data Sources section does not already exist in odbc ini create it b Add an entry for the data source to the ODBC Data Sources section in odbc ini c If odbcinst ini does not already have an entry for the INFORMIX CLI driver in the ODBC Drivers section add the entry d If odbcinst ini does not already have a Driver Specification section for the INFORMIX CLI driver add the section 2 14 INFORMIX CLI Programmers Manual Modifying a Data Source Modifying a Data Source To modify a data source modify the Data Source Specification section for the data source in odbc ini Configuring Data Sources 2 15 Guidelines for Calling INFORMIX CLI Functions Conformance Levels l API Conformance Levels SQL Conformance Levels Verifying INFORMIX CLI Conformance Levels Using the Driver Manager Calling Functions Buffers dy Input Buffers Output Buffers Environment Connection and Statement Hariales Using Data Types Function Return Codes How an Application Uses the INFORMIX CLI API 3 3 3 3 3 5 3 6 3 7 3 8 3 8 3 10 3 11 3 12 3 12 3 13 3 2 INFORMIX CLI Program
435. set 1 of 2 SQLDescribeCol SQLSTATE Error Description S1008 Operation canceled The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multithreaded application S1010 Function sequence DM The function was called prior to calling error SQLPrepare or SQLExecDirect for the hstmt DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns S1090 Invalid string or DM The value specified for argument buffer length cbColNameMax was less than 0 S1T00 Time out expired The time out period expired before the data source returned the result set The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLDescribeCol can return any SOLSTATE that SOLPrepare or SOLExecute returns when SOLDescribeCol is called after SOLPrepare and before SQLExecute depending on when the data source evaluates the SQL statement associated with the hstmt Usage An application typically calls SOLDescribeCol after a call to SQLPrepare and before or after the associated call to SOLExecute An application can also call SOLDescribeCol after a call to SOLExecDirect SQLDescribeCol retrieves the column name type and length generated by a SELECT statement If the column is an expression szColName is either an empty string or a driver defined
436. sferring Data Among data sources that use the same DBMS an application can safely transfer data in the internal form used by that DBMS For a particular piece of data the SQL data types must be the same in the source and target data sources The C data type is SQL_C_BINARY When the application calls SOLFetch SOLExtendedFetch or SOLGetData to retrieve the data from the source data source the driver retrieves the data from the data source and transfers it without conversion to a storage location of type SQL_C_BINARY When the application calls SOLExecute SQLExecDirect or SQLPutData to send the data to the target data source the driver retrieves the data from the storage location and transfers it without conversion to the target data source The binary representation of INT8 and SERIAL8 is an array of two unsigned long integers followed by a short integer that indicates the sign field The sign field is 1 for a positive value 1 for a negative value or 0 for a null value Important Applications that transfer any data except binary data in this manner are not interoperable among DBMSs Data Types B 13 Converting Data Converting Data The word convert is used in this section in a broad sense it includes the transfer of data from one storage location to another without a conversion in data type The following table shows the supported conversions between the Informix SQL data types and the INFORMIX CLI C data types A
437. sociated with hstmt was not an UPDATE INSERT or DELETE statement the value of pcrow is driver defined INFORMIX CLI Function Reference 12 279 SQL RowCount Related Functions For Information About See Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute 4 12 280 INFORMIX CLI Programmer s Manual SQL SetConnectOption SQLSetConnectOption SQLSetConnectOption sets options that govern aspects of connections Syntax RETCODE SQLSetConnectOption hdbc fOption vParam The SQLSetConnectOption function accepts the following arguments Type Argument Use Description HDBC hdbc Input Connection handle UWORD fOption Input Option to set listed in Usage UDWORD vParam Input Value associated with fOption Depending on the value of fOption vParam will be a 32 bit integer value or point to a null terminated character string Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicat
438. sor The following operations require a cursor position m Positioned update and delete statements m Calls to SOLGetData Before the application executes a positioned update a delete statement or a call to SOLGetData it must position the cursor by calling SOLExtendedFetch to retrieve a row set the cursor points to the first row in the row set INFORMIX CLI Function Reference 12 129 SQLExtendedFetch The following table shows the row set and code returned when the appli cation requests different row sets Requested Row Set Return Code Cursor Position Returned Row Set Before start of SQOL_NO_DATA_FOUND Before start of None The contents of the row set buffers are result set result set undefined Overlaps start SQL_SUCCESS Row 1 of row set First row set in result set of result set Within result SQL_SUCCESS Row 1 of row set Requested row set set Overlaps end SQL_SUCCESS Row 1 of row set For rows in the row set that overlap the of result set result set data is returned For rows in the row set outside the result set the contents of the rgbValue and pcbValue buffers are undefined and the rgfRowStatus array contains SQL_ROW_NOROW After end of SOL_NO_DATA FOUND After end of None The contents of the row set buffers are result set result set undefined For example suppose a result set has 100 rows and the row set size is 5 The following table shows the row set and code returned by SOLExtendedFetch for differen
439. sor state General error Memory allocation failure Operation canceled Function sequence error INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The communication link between the driver and the data source failed before the function completed A cursor was already opened on the statement handle An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multithreaded application DM SOLExecute or SOLExecDirect was called for the hstmt and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns 1 of 2 SQLSTATE Error S1090 S1097 S1098 S1099 S1C00 S1T00 Usage Invalid string or buffer length Column type out of range Scope type out of range Nullable type out of range Driver not capable Time out expired SQL SpecialColumns Description DM The value of one of the length arguments was less than 0 but not equal to SOL_NTS The value of one of the length arguments exceed
440. specifying row wise binding do rc SQLExtendedFetch hstmt SQL_FETCH_NEXT 0 amp RowsFetched RowStatus while rc SQL_SUCCESS rc SQL_SUCCESS_WITH_INFO N The number of ODBC calls that the application makes is reduced from 110 in Case 2 of the previous example to four calls 1 SQLSetStmtOption 1 SQLExecDirect 1 SQLBindCol 1 SQLExtendedFetch The combined use of SQLBindCol SQLExtendedFetch reduces the initial call load of more than 1 890 ODBC calls in Case 1 SQLGetData Method on page 10 9 to only four calls INFORMIX CLI Programmers Manual Executing Calls Executing Calls Certain functions are more efficient than others at performing specialized tasks Using SQLPrepare and SQLExecute Versus SQLExecDirect The combination of SQLPrepare and SQLExecute is optimized for multiple executions of a statement that most likely uses parameter markers SQLExecDirect is optimized for a single execution of an SQL statement Therefore for better performance use SQLPrepare and SQLExecute for queries that are executed more than once and SQLExecDirect for queries that are executed only once Unfortunately more than 75 percent of all ODBC applications use SQLPrepare and SQLExecute exclusively The following situation illustrates the pitfall of always coding SOLPrepare and SQLExecute Consider a driver that implements SQLPrepare by creating a stored procedure on the database server that contain
441. stem catalogs possibly a join which must be prepared executed and produce a result set rc SQLBindCol rc SQLExtendedFetch user must retrieve N rows from the server N result columns of UnknownTable result column information has now been obtained Case 2 SQLDescribeCol Method The following example uses SQLDescribeCol prepare dummy query rc SQLPrepare SELECT from UnknownTable WHERE D607 23 query is never executed on the server only prepared rc SQLNumResultCols for irow 1 irow lt NumColumns irowt rc SQLDescribeCol optional calls to SQLColAttributes result column information has now been obtained Note we also know the column ordering within the table This information cannot be assumed from the SQLColumns example INFORMIX CLI Programmers Manual Retrieving Data Both cases send a query to the database server but in Case 1 SQLColumns must evaluate the query and form a result set that it must send to the client In Case 2 SOLDescribeCol gets the result column information and the order of the columns within the table without returning the information to the client thus improving performance Avoid using SQLColumns to determine characteristics of a table Instead use a dummy query with SQLDescribeCol Retrieving Data To increase the performance of an application limit the amount of data retrieved a
442. string contains the DSN keyword the driver manager locates a corresponding data source specification If the driver manager cannot find the corresponding data source specification and no default data source specification exists it returns SOL_ERROR with SOLSTATE IM002 Data source not found and no default driver specified INFORMIX CLI Programmers Manual SQLBrowseConnect If the browse request connection string contains the DRIVER keyword the driver manager loads the specified driver it does not attempt to locate a data source Because the DRIVER keyword does not use information from the odbc ini file the driver must define enough keywords so a driver can connect to a data source using only the information in the browse request connection strings On each call to SQLBrowseConnect the application specifies the connection attribute values in the browse request connection string The driver returns successive levels of attributes and attribute values in the browse result connection string it returns SOL_NEED_DATA as long as there are connection attributes that have not yet been enumerated in the browse request connection string The application uses the contents of the browse result connection string to build the browse request connection string for the next call to SQLBrowseConnect The application cannot use the contents of previous browse result connection strings when it builds the current one that is it cannot specify different val
443. submit a COMMIT or ROLLBACK statement it is not interoperable between DBMS products To commit or roll back a transaction call SQLTransact INFORMIX CLI Function Reference 12 121 SQL Execute 12 122 If SOLExecute encounters a data at execution parameter it returns SQL_NEED_DATA The application sends the data using SOLParamData and SOLPutData For more information see SOLBindParameter SOLParamData and SOLPutData Code Example See SOLBindParameter and SOLPutData Related Functions For Information About Assigning storage for a column in a result set Canceling statement processing Executing an SQL statement Fetching a block of data or scrolling through a result set Fetching a row of data Freeing a statement handle Returning a cursor name Fetching part or all of a column of data Returning the next parameter to send data for Preparing a statement for execution Sending parameter data at execution time Setting a cursor name Setting a statement option Executing a commit or rollback operation INFORMIX CLI Programmer s Manual See SOLBindCol SOLCancel SQLExecDirect SQLExtendedFetch SOLFetch SQLFreeStmt SOLGetCursorName SQLGetData SQLParamData SQOLPrepare SQLPutData SOLSetCursorName SOLSetStmtOption SQLTransact SQLExtendedFetch SQLExtendedFetch SQLExtendedFetch extends the functionality of SQLFetch in the following ways m Itreturns row set data one or more rows in the form
444. szSq Str contained a CREATE INDEX statement but the specified index name already existed The argument szSq Str contained a DROP INDEX statement but the specified index name did not exist The argument szSq Str contained an ALTER TABLE statement but the column specified in the ADD clause is not unique or identifies an existing column in the base table 3 of 5 INFORMIX CLI Function Reference 12 113 SQL ExecDirect SQLSTATE Error 0022 S1000 S1001 S1008 S1009 S1010 S1090 12 114 Column not found General error Memory allocation failure Operation canceled Invalid argument value Function sequence error Invalid string or buffer length Description The argument szSqlStr contained a CREATE INDEX statement but one or more of the column names specified in the column list did not exist The argument szSqlStr contained a GRANT or REVOKE statement but a specified column name did not exist The argument szSqlStr contained a SELECT DELETE INSERT or UPDATE statement but a specified column name did not exist The argument szSqlStr contained a CREATE TABLE statement but a column specified in a constraint referencing a table other than the one being created did not exist An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause
445. t and makes the next result set or count available If a batch of statements or a procedure mixes other SOL statements with SELECT UPDATE INSERT and DELETE statements these other statements do not affect SOLMoreResults For additional information about the valid sequencing of result processing functions see Appendix B ODBC State Transition Tables Related Functions For Information About See Canceling statement processing SOLCancel Fetching a block of data or scrolling through a result set SOLExtendedFetch Fetching a row of data SOLFetch Fetching part or all of a column of data SOLGetData 12 232 INFORMIX CLI Programmer s Manual SQL NativeSq SQLNative Sql SQLNativeSql returns the SQL string that the driver translates Syntax RETCODE SQLNativeSql hdbc szSqlStrIn cbSqlStrIin szSqlStr cbSqlStrMax pcbSqlStr The SOLNativeSql function accepts the following arguments Type Argument Use Description HDBC hdbc Input UCHAR FAR szSqlStrIn Input SDWORD cbSqlStrIn Input UCHAR FAR szSqlStr Output SDWORD cbSqlStrMax Input SDWORD FAR pcbSqlStr Output Return Codes Connection handle SQL text string to be translated Length of szSqlStrIn text string Pointer to storage for the translated SQL string Maximum length of the szSq Str buffer The total number of bytes excluding the null termination byte available to return in szSqlStr If the number of bytes available to retu
446. t apply to a driver or data source then unless otherwise stated the driver returns 0 in pcbDesc or an empty string in rgbDesc Information Returned in Description SQL_COLUMN_AUTO_INCREMENT pfDesc TRUE if the column is auto increment FALSE if the column is not auto increment or is not numeric Auto increment is valid for numeric data type columns only An application can insert values into an auto increment column but cannot update values in the column SQL_COLUMN_CASE_SENSITIVE pfDesc TRUE if the column is treated as case sensitive for colla tions and comparisons FALSE if the column is not treated as case sensitive for collations and comparisons or is non character SQL_COLUMN_COUNT pfDesc Number of columns available in the result set The icol argument is ignored 1 of 4 12 56 INFORMIX CLI Programmer s Manual fDescType SQL_COLUMN_DISPLAY_SIZE SQL_COLUMN_LABEL SQL_COLUMN_LENGTH SQL_COLUMN_MONEY SQL_COLUMN_NAME SQL_COLUMN_NULLABLE SQL_COLUMN_OWNER_NAME SQL_COLUMN_PRECISION Information Returned in pfDesc rgbDesc pfDesc pfDesc rgbDesc pfDesc rgbDesc pfDesc SQLColAttributes Description Maximum number of characters required to display data from the column For more information on display size see Precision Scale Length and Display Size on page B 5 The column label or title For example a column named EmpName might be labeled Employee Name If a c
447. t fCType The argument icol was 0 and the driver does not support bookmarks SQLBindCol Usage The INFORMIX CLI interface provides the following ways to retrieve a column of data SQLBindCol assigns the storage location for a column of data before the data is retrieved When SQLFetch or SQLExtendedFetch is called the driver places the data for all bound columns in the assigned locations m SQLGetData an extended function assigns a storage location for a column of data after SOLFetch or SQLExtendedFetch is called It also places the data for the requested column in the assigned location Because it can retrieve data from a column in parts SOLGetData can retrieve long data values An application might choose to bind every column with SOLBindCol to retrieve data only and not bind with SOLGetData or to use a combination However unless the driver provides extended functionality SOLGetData can be used only to retrieve data from columns that occur after the last bound column An application calls SOLBindCol to pass the pointer to the storage buffer for a column of data to the driver and to specify how or if to convert the data The application must allocate enough storage for the data If the buffer contains variable length data the application must allocate as much storage as the maximum length of the bound column or the data might be truncated For information about converting data types see Converting Data from SQL
448. t request a statement handle before it submits SQL requests Each statement handle is associated with exactly one connection handle However each connection handle can be associated with multiple statement handles For more information about requesting a connection handle see Connecting to a Data Source on page 4 4 For more information about requesting a statement handle see Executing an SQL Statement on page 5 5 Guidelines for Calling INFORMIX CLI Functions 3 11 Using Data Types Using Data Types Data stored on a data source has an SQL data type The INFORMIX CLI driver maps Informix specific SQL data types to ODBC SQL data types which are defined in the ODBC SQL grammar The driver returns these mappings through SOLGetTypelnfo It also uses the ODBC SQL data types to describe the data types of columns and parameters in SQLColAttributes and SQLDescribeCol Each SQL data type corresponds to an ODBC C data type By default the driver assumes that the C data type of a storage location corresponds to the SQL data type of the column or parameter to which the location is bound If the C data type of a storage location is not the default C data type the appli cation can specify the correct C data type with the fCType argument in SOLBindCol SOLGetData or SOLBindParameter Before the driver returns data from the data source it converts the data to the specified C data type Before the driver sends data to the data source
449. t support qualifiers A table owner was specified but the driver or data source does not support owners A string search pattern was specified for the table owner table name or column name but the data source does not support search patterns for one or more of those arguments The combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options is not supported by the driver or data source The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLColumns Usage This function is typically used before statement execution to retrieve infor mation about columns for a table or tables from the catalog of the data source In contrast SOLColAttributes and SOLDescribeCol describe the columns in a result set and SQLNumResultCols returns the number of columns in a result set SQLColumns returns the results as a standard result set ordered by TABLE_QUALIFIER TABLE_OWNER TABLE_NAME COLUMN_NAME DATA_TYPE and S TYPE_NAME The following table lists the columns in the result set Additional columns beyond column 12 REMARKS can be defined by the driver The lengths of VARCHAR columns shown in the following table are maximums the actual lengths depend on the data source To determine the actual lengths of the TABLE_QUALIFIER TABLE_OWNER TABLE_NAME and COLUMN_NAME columns an application can
450. t values of irow when the fetch type is SQL_FETCH_RELATIVE Current Row Set irow Return Code New Row Set 1to5 5 SQL_NO_DATA_FOUND None 1to5 3 SQL_SUCCESS 1to5 96 to 100 5 SQL_NO_DATA_FOUND None 96 to 100 3 SQL_SUCCESS 99 and 100 For rows 3 4 and 5 in the row set the rgfRowStatusArray is set to SQL_ROW_NOROW 12 130 INFORMIX CLI Programmer s Manual SQLExtendedFetch Before SQLExtendedFetch is called the first time the cursor is positioned before the start of the result set For the purpose of moving the cursor deleted rows that is rows with an entry in the rgfRowStatus array of SOL_ROW_DELETED are treated no differ ently than other rows For example calling SOLExtendedFetch with fFetchType set to SOL_FETCH_ABSOLUTE and irow set to 15 returns the row set starting at row 15 even if the refRowStatus array for row 15 is SOL_ROW_DELETED Processing Errors If an error occurs that pertains to the entire row set such as SOLSTATE S1T00 Time out expired the driver returns SOL_ERROR and the appropriate SOLSTATE The contents of the row set buffers are undefined and the cursor position is unchanged If an error occurs that pertains to a single row the driver performs the following actions m Sets the element in the rgfRowStatus array for the row to SOL_ROW_ERROR m Posts SOLSTATE 01501 Error in row in the error queue m Posts zero or more additional SOLSTATE values for the error after SOLSTATE 01501 E
451. taTypes B 9 C Data Types C Data Types An INFORMIX CLI application uses C data types to store values that the application processes Character C Data Type The following table lists the character C data type that INFORMIX CLI provides It also lists the corresponding INFORMIX CLI typedef and standard C data type INFORMIX CLI C Data Type fCType INFORMIX CLI Typedef Standard C Data Type SQL_C_CHAR UCHAR FAR unsigned char FAR Important String arguments in INFORMIX CLI functions are unsigned Therefore you need to cast a CString object as an unsigned string before you use it as an argument in an INFORMIX CLI function Numeric C Data Types The following table lists the numeric C data types that INFORMIX CLI provides It also lists the corresponding INFORMIX CLI typedefs and standard C data types INFORMIX CLI C Data Type fCType INFORMIX CLI Typedef Standard C Data Type SQL_C_DOUBLE SDOUBLE signed double SQL_C_FLOAT SFLOAT signed float SQL_C_LONG SDWORD signed long int SQL_C_SHORT SWORD signed short int SQL_C_SLONG SDWORD signed long int 1 of 2 B 10 INFORMIX CLI Programmers Manual Date and Time Stamp C Data Types INFORMIX CLI C Data Type fCType INFORMIX CLI Typedef Standard C Data Type SQL_C_SSHORT SWORD signed short int SQL_C_SS SCHAR signed char SQL_C_TINYINT SCHAR signed char SQL_C_ULONG UDWORD unsigned long int SQL_C_USHORT UWORD unsigned short int SQL_C_UTINYINT UCHAR unsigned cha
452. tation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate sufficient memory to execute or complete the function DM SOLExecute or SOLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM There was no open cursor on the hstmt and no cursor name had been set with SQLSetCursorName DM The value specified in the argument cbCursorMax was less than 0 SQL GetCursorName Usage The only INFORMIX CLI SQL statements that use a cursor name are positioned update and delete for example UPDATE table name WHERE CURRENT OF cursor name If the application does not call SOLSetCursorName to define a cursor name when a SELECT statement executes the driver generates a name that begins with the letters SQL_CUR and does not exceed 18 characters SQLGetCursorName returns the name of a cursor regardless of whether the name was created explicitly or implicitly A cursor name that is set either explicitly or implicitly remains set until the hstmt with which it is associated is dropped using SOLFreeStmt with the SQL_DROP option Related Functions For Information About See Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute Preparing a statement for execution SQLPrepare Setting a curs
453. tch with the SOL_FETCH_NEXT fetch type still returns rows 21 through 30 If the driver returns any warnings such as SOLSTATE 01004 Data truncated it returns warnings that apply to the entire row set or to unknown rows in the row set before it returns error information that applies to specific rows It returns warnings for specific rows along with any other error information about those rows fFetchType Argument The fFetchType argument specifies how to move through the result set It is one of the following values SQL_FETCH_NEXT SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_PRIOR SQL_FETCH_ABSOLUTE SQL_FETCH_RELATIVE If the value of the SQL_CURSOR_TYPE statement option is SQL_CURSOR_FORWARD_ONLY the fFetchType argument must be SQL_FETCH_NEXT Tip SQL_CURSOR_FORWARD_ONLY is the only option unless an application uses the Microsoft ODBC Cursor Library INFORMIX CLI Programmers Manual Moving by Row Position SQLExtendedFetch SQLExtendedFetch supports the following values of the fFetchType argument to move the cursor relative to the current row set fFetchType Argument Action SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_RELATIVE The driver returns the next row set If the cursor is positioned before the start of the result set this is equiv alent to SOL_FETCH_FIRST The driver returns the prior row set If the cursor is positioned after the end of the result set this is equivalent to SOL_FETCH_LAST
454. tches each row of data with SQLFetch and prints the name age and birthday of each employee For more code examples see SOLColumns and SQLExtendedFetch dtdefine NAME_LEN 30 itdefine BDAY_LEN 11 UCHAR szName NAME_LEN szBirthday BDAY_LEN SWORD sAge SDWORD cbName cbAge cbBirthday retcode SQLExecDirect hstmt SELECT NAME AGE BIRTHDAY FROM EMPLOYEE ORDER BY 3 2 1 SQL_NTS if retcode SQL_SUCCESS Bind columns 1 2 and 3 SQLBindCol hstmt 1 SQL_C_CHAR szName NAME_LEN amp cbName SQLBindCol hstmt 2 SQL_C_SSHORT amp sAge 0 amp cbAge SQLBindCol hstmt 3 SQL_C_CHAR szBirthday BDAY_LEN amp cbBirthday Fetch and print each row of data On an error display a message and exit while TRUE retcode SQLFetch hstmt if retcode SQL_ERROR retcode SQL_SUCCESS_WITH_INFO show_error if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO fprintf out s 2d s NAME_LEN 1 szName sAge BDAY_LEN 1 szBirthday else break INFORMIX CLI Function Reference 12 23 SQLBindCol 12 24 Related Functions For Information About Returning information about a column in a result set Fetching a block of data or scrolling through a result set Fetching a row of data Freeing a statement handle Fetching part or all of a column of data Returning the number of result set columns INFORMIX CLI Programmers Manual See
455. te or SQLExecDirect was called for error the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns 1 of 2 INFORMIX CLI Function Reference 12 63 SQL ColumnPrivileges 12 64 SQLSTATE Error S1090 Invalid string or buffer length S1C00 Driver not capable S1T00 Time out expired Usage set by SQLColumnPrivileges INFORMIX CLI Programmers Manual Description DM The value of one of the name length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corre sponding qualifier or name See Usage on page 12 56 A table qualifier was specified but the driver or data source does not support qualifiers A table owner was specified but the driver or data source does not support owners A string search pattern was specified for the column name but the data source does not support search patterns for that argument The combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options was not supported by the driver or data source The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLColumnPrivileges returns the results as a standard result set ordered by TABLE_QUALIFIER TABLE_OWNER TABLE_NAME COL
456. teger value SQL_MODE_READ_ONLY is used by the driver or data source as an indicator that the connection is not required to support SQL statements that cause updates to occur This mode can be used to optimize locking strategies transaction management or other areas as appropriate to the driver or data source The driver is not required to prevent such state ments from being submitted to the data source The behavior of the driver and data source when asked to process SQL statements that are not read only during a read only connection is implementation defined SQL_MODE_READ_WRITE is the default A 32 bit integer value that specifies whether to use auto commit or manual commit mode m SQL_AUTOCOMMIT_OFF The driver uses manual commit mode and the application must explicitly commit or roll back transactions with SQLTransact m SQL_AUTOCOMMIT_ON The driver uses autocommit mode Each statement is committed immediately after it is executed This is the default Changing from manual commit mode to autocommit mode commits any open transactions on the connection Important Some data sources delete the access plans and close the cursors for all statement handles on a connection handle each time a statement is committed auto commit mode can cause this to happen after each statement is executed For more information see SQL_CURSOR_COMMIT_BEHAVIOR and SQL _CURSOR_ROLLBACK_BEHAVIOR on page 12 196 A null terminated character strin
457. tement Return Codes SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise 12 236 INFORMIX CLI Programmer s Manual SQLNumParams If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error 01000 S1000 S1001 S1008 S1010 S1T00 General warning General error Memory allocation failure Operation canceled Function sequence error Time out expired Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function The function was called but before it completed execution SQLCancel was called on t
458. ter binary or data source specific data type the driver returns SQL_SUCCESS_WITH_INFO A subsequent call to SQLError returns SQLSTATE 01004 Data truncated The application can then use the same column number to retrieve subsequent parts of the data until SQLGetData returns SOL_SUCCESS indicating that all the column data was retrieved SOLGetData returns SOL_NO_DATA_FOUND when it calls for a column after all the data is retrieved and before data is retrieved for a subse quent column The application can ignore excess data by proceeding to the next result column Important An application can use SQLGetData to retrieve data from a column in parts only when it retrieves character C data from a column with a character binary or data source specific data type or when it retrieves binary C data from a column with a character binary or data source specific data type If SQLGetData is called more than once in a row for a column under any other conditions it returns SQL_NO_DATA_FOUND for all calls after the first call For maximum interoperability applications should call SOLGetData only for unbound columns with numbers greater than the number of the last bound column Within a single row of data the column number in each call to SOLGetData should be greater than or equal to the column number in the previous call that is data should be retrieved in increasing order of column number As extended functionality drivers can return data through SO
459. ter the end of the result set An application cannot mix calls to SOLExtendedFetch and SOLFetch for the same cursor If the application called SOLBindCol to bind columns SQLFetch stores data in the locations specified by the calls to SQLBindCol If the application does not call SOLBindCol to bind any columns SQLFetch does not return any data it moves the cursor to the next row An application can call SOLGetData to retrieve data that is not bound to a storage location INFORMIX CLI Function Reference 12 141 SQL Fetch 12 142 The driver manages cursors during the fetch operation and places each value of a bound column into the associated storage The driver follows these guidelines when it performs a fetch operation SQLFetch accesses column data in left to right order After each fetch pcbValue specified in SQLBindCol contains the number of bytes that are available to return for the column which is the number of bytes that are available before calling SOLFetch If the number of bytes that are available to return cannot be determined in advance the driver sets pcbValue to SOL_NO_TOTAL If SOL_MAX_LENGTH was specified with SOLSetStmtOption and the number of bytes that are available to return is greater than SQL_MAX_LENGTH pcbValue contains SOL_MAX_LENGTH If rebValue cannot hold the entire result the driver stores part of the value and returns SOL_SUCCESS_WITH_INFO A subsequent call to SQLError indicates that a truncati
460. tes Compliance with Industry Standards Informix Welcomes Your Comments Overview of INFORM IX CLI What Is INFORMIX CLI Architecture Advantages of Using INFORMIX CLI Isolation and Lock Levels INFORMIX CLI Libraries Environment Variables on UNIX Setting Environment Variables in a File Setup File oD 0000 FB wW WwW 1 3 1 3 1 7 1 8 1 8 1 9 1 10 GES 4 flog ae PM oe bid pee ao EA Client Locale ee DD Database Locale eee 1 12 Translation Library 2 1 we ee eee 112 Translation Option 2 1 ee ee ee 112 VMB Character eee eee 1 13 Chapter 2 Configuring Data Sources Configuring Data Sources on Windows 2 3 AddingaDataSource 2 2 ee ee 2 4 ModifyingaDataSource 1 ew eee 2 7 Configuring Data Sources on UNIX 2 we 1 2 9 File Format for odbc ini 2 10 File Format for odbcinst ini 2 14 AddingaDataSource 2 1 a D4 ModifyingaDataSource 1 1 a 215 Chapter 3 Guidelines for Calling INFORMIX CLI Functions Conformance Levels 2 o 3 3 API Conformance Levels a ee es 3 3 SQL Conformance Levels de ety AS east As 3 5 Verifying INFORMIX CLI Gontannanee Teves be PR Mi wh y s 3 6 Using the Driver Manager 2 1 2 a 3 7 Calling Functions s gi deg oat a Be os 3 8 Buffers te of 3 8 Environment Co
461. th the hstmt contained a parameter but the value was incompatible with the data type of the associated table column The prepared statement associated with the hstmt contained a date time or time stamp parameter or literal and the value was an invalid date time or time stamp respectively The prepared statement associated with the hstmt contained an arithmetic expression that caused division by zero The prepared statement associated with the hstmt contained a parameter The parameter value was NULL for a column defined as NOT NULL in the associated table column a duplicate value was supplied for a column constrained to contain only unique values or some other integrity constraint was violated A cursor was already opened on the statement handle The prepared statement associated with the hstmt contained a positioned update or delete statement and the cursor was positioned before the start of the result set or after the end of the result set The transaction to which the prepared statement associated with the hstmt belonged was termi nated to prevent deadlock The user did not have permission to execute the prepared statement associated with the hstmt 2 of 4 INFORMIX CLI Function Reference 12 119 SQL Execute 12 120 SQLSTATE Error S1000 General error S1001 Memory allocation failure S1008 Operation canceled S1010 Function sequence error S1090 Invalid string or buffer length INFORMIX
462. the SQLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning 1000 General error S1001 Memory allocation failure S1010 Function sequence error S1092 Option type out of range INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message that SQLError returns in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM SQLExecute or SOLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns DM The value specified for the argument fOption was not SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS SQL FreeStmt Usage An application can call SOLFreeStmt to terminate processing of a SELECT statement with or without canceling the statement handle The SQL_DROP option frees all resources that the SQLAIlocStmt function allocates Code Example See SOLBrowseConnect and SQLConnect Related Functions For Information About See Allocating a statement handle SOLAllocStmt Canceling statement processing SOLCancel Setting a cursor name SOLSetCursorName INFORMIX CLI Fu
463. the driver SQL_DBMS_VER A character string that indicates the version of the DBMS product accessed by the driver The version has the form HH HEHE where the first two digits are the major version the next two digits are the minor version and the last four digits are the release version The driver must render the DBMS product version in this form but can also append the DBMS product specific version For example 04 01 0000 RDB 4 1 5 of 24 INFORMIX CLI Function Reference 12 197 SQL Getinfo InfoType Returns SQL_DEFAULT_TXN_ISOLATION A 32 bit integer that indicates the default transaction isolation level supported by the driver or data source or zero if the data source does not support transactions The following terms are used to define transaction isolation levels m Dirty Read Transaction 1 changes a row Transaction 2 reads the changed row before transaction 1 commits the change If transaction 1 rolls back the change transaction 2 will have read a row that is considered to have never existed m Non repeatable Read Transaction 1 reads a row Transaction 2 updates or deletes that row and commits this change If trans action 1 attempts to reread the row it will receive different row values or discover that the row has been deleted m Phantom Transaction 1 reads a set of rows that satisfy some search criteria Transaction 2 inserts a row that matches the search criteria If transaction 1 re executes the
464. the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 12 96 01000 01004 01500 08001 08002 08004 08501 General warning Data truncated Invalid connection string attribute Unable to connect to data source Connection in use Data source rejected establishment of connection Communication link failure INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer szConnStrOut was not large enough to return the entire connection string so the connection string was truncated The argument pcbConnStrOut contains the length of the untruncated connection string function returns SQL_SUCCESS_WITH_INFO An invalid attribute keyword was specified in the connection string szConnStrIn but the driver connected to the data source anyway function returns SQL_SUCCESS_WITH_INFO The driver did not establish a connection with the data source DM The specified hdbc was used already to establish a connection with a data source and the connection was still open The data source rejected the establishment of the connection for implementation defined reasons The communication link between the driver and the data source failed before the function completed 1 of 3 SQLSTATE Error 28000 IM002 IM003 IM004 IM005 IM006 IM007 IM008 IM009 IM010 Inva
465. the key set size is greater than the row set size The cursor is key set driven inside the key set and dynamic outside the key set For information about scrollable cursors see Scrollable Cursors on page 6 10 19 of 24 INFORMIX CLI Function Reference 12 211 SQL Getinto InfoType SOL_SEARCH_PATTERN_ESCAPE Returns A character string that specifies what the driver supports as an escape character that permits the use of the pattern match metacharacters underscore _ and percent as valid characters in search patterns This escape character applies only for those catalog function arguments that support search strings If this string is empty the driver does not support a search pattern escape character This fInfoType is limited to catalog functions For a description of the use of the escape character in search pattern strings see Search Pattern Arguments on page 12 8 SQL_SERVER_NAME A character string with the actual data source specific server name useful when a data source name is used during SOLConnect SOLDriverConnect and SOLBrowseConnect SOL_SPECIAL_CHARACTERS 12 212 INFORMIX CLI Programmers Manual A character string that contains all special characters that is all characters except a through Z A through Z 0 through 9 and underscore that can be used in an object name such as a table column or index name on the data source For example 20 of 24 Info
466. the smallest unique index Designing Performance Oriented Applications 10 13 Committing Data Committing Data Committing data is extremely I O intensive and slow By default auto commit is on when a driver connects to a data source To improve perfor mance turn auto commit off During a commit the database server must flush back to disk every data page that contains updated or new data The database server does not use a sequential write to perform this task Instead it uses a searched write to replace existing data that is already in the table Thus auto commit mode is typically detrimental to performance because of the amount of I O needed to commit every operation 10 14 INFORMIX CLI Programmers Manual Function Summary INFORMIX CLI Function Summary Connecting toa DataSource Retrieving Information About a Driver and Data Source Setting and Retrieving Driver aa Preparing SQL Requests a o Submitting SOL Requests Retrieving Results and Information About Results Retrieving Information About Data Source System Tables Terminating a Statement Terminating a Connection Setup Shared Library Function Summary Translation Shared Library Function Summary 11 3 11 4 11 5 11 5 11 6 11 6 11 7 11 8 11 9 11 10 11 10 11 11 11 2 INFORMIX CLI Programmers Manual his chapter summarizes the functions that INFORMIX CLI enabled applications and related software use m INFORMIX CLI func
467. ths To bind each column the structure includes one field to contain data and one field to contain the number of bytes of data that are available to return Allocate an array of these structures This array has as many elements as there are rows in the row set Call SOLBindCol for each column to be bound In each call specify the address of the column data field in the first array element the size of the data field the address of the column number of bytes field in the first array element and the type to which the data will be converted Call SQLSetStmtOption with the SQL_BIND_TYPE option and specify the size of the structure When the data is retrieved the driver uses the structure size to determine where to store successive rows of data in the array INFORMIX CLI Programmers Manual Retrieving Row Set Data Retrieving Row Set Data Before it retrieves row set data an application calls SQLSetStmtOption with the SOL_ROWSET_SIZE option to specify the number of rows in the row set It then binds columns in the row set with SOLBindCol The row set is bound using a column or row wise method For more information see Assigning Storage for Row Sets Binding on page 6 7 To retrieve row set data an application calls SOLExtendedFetch For maximum interoperability an application should not use SOLGetData to retrieve data from unbound columns in a block of data more than one row that has been retrieved with SQLExtended
468. tion level 12 198 Restricted deletes 12 149 Restricted updates 12 149 Result sets arrays See Rowsets binding columns 6 4 column attributes 6 5 described 3 13 6 3 fetching data 6 5 fetching rowsets 6 9 multiple 12 205 number of columns 6 5 number of rows 6 5 retrieving data in parts 6 7 rowset size 6 7 SQLBindCol 12 21 SQLColAttributes 12 56 SQLDescribeCol 12 86 SQLMoreResults 12 232 SQLNumResultCols 12 239 SQLRowCount 12 278 See also Cursors Rows Result states See State transitions 8 INFORMIX CLI Programmer s Manual Retrieving data arrays See Rowsets binding columns See Binding columns cursor position 12 141 disabling 12 302 fetching data 6 5 fetching rowsets 6 9 in parts 6 7 12 175 long data values 6 7 maximum length 12 302 multiple result sets 12 205 NULL data 12 22 12 142 12 174 retrieving 12 302 rows See Rows SQLExtendedFetch 12 127 SQLFetch 12 141 SQLGetData 12 175 truncating data 12 142 12 175 unbound columns 6 7 Return codes 7 3 Return values procedure 12 30 ROLLBACK statements cursor behavior 12 196 interoperability 5 9 12 115 12 121 SQLExecute 12 121 Rolling back transactions 5 9 12 333 Row status array errors 12 131 SQLExtendedFetch 12 134 Row versioning isolation level 12 198 ROWID 12 308 12 309 Rows affected 12 278 after last row 12 133 deleting 6 12 errors in 12 131 interoperability 6 5 maximum 12 302 maximum length 12 204 SQLExtendedFetch 12 134 updating 6 12 See also
469. tion passes szConnStrOut to its routine GetUserInput not shown GetUserInput parses the information builds and displays a dialog box and returns the information entered by the user in szConnStrIn The application passes the user s information to the driver in the next call to SQLBrowseConnect After the application provides all the necessary infor mation for the driver to connect to the data source SOLBrowseConnect returns SQL_SUCCESS and the application proceeds For example to connect to the data source My Source the following actions might occur First the application passes the following string to SQLBrowseConnect as the following example shows DSN My Source The driver manager loads the driver associated with the data source My Source It then calls the driver SOLBrowseConmnect function with the same arguments that it received from the application The driver returns the following string in szConnStrOut HOST Server tred blue green UID ID PWD Password The application passes this string to its GetUserInput routine which provides a dialog box that asks the user to select the red blue or green database server and to enter a user ID and password The routine passes the following user specified information back in szConnStrIn which the appli cation passes to SOLBrowseConnect HOST red UID Smith PWD Sesame SOLBrowseConnect uses this information to connect to the red database server as Smith with the password Se
470. tion shared library that you use A new option can be set at any time and will be applied to the next exchange of data following a call to SQLSetConnectOption A default trans lation shared library can be specified for the data source in its data source specification The driver loads the default translation shared library at connection time A translation option SQL_TRANSLATE_OPTION can also be specified in the data source specification To change the translation shared library for a connection an application calls SQLSetConnectOption with the SOL_TRANSLATE_DLL option after it connects to the data source The driver attempts to load the specified shared library and if the attempt fails the driver returns SQL_ERROR with the SQLSTATE IM009 Unable to load translation shared library If no translation shared library is specified in the ODBC initialization file or by calling SOLSetConnectOption the driver does not attempt to translate data Any value set for the translation option is ignored For more information about translating data see Chapter 13 Setup Shared Library Function Reference Code Example See SOLConnect Related Functions For Information About See Returning the setting of a connection option SQLGetConnectOption Returning the setting of a statement option SOLGetStmtOption Setting a statement option SOLSetStmtOption 4 INFORMIX CLI Function Reference 12 289 SQL SetCursorName SQLSet CursorName SO
471. tions 2 a a a o o 12 9 Search Pattern Arguments a a a a a o 12 10 SQLAllocConnect a a a a a 12 11 SQLAllocEnv a 12 14 SQLANOCESENE s 0 a Boe ee a ei 12 17 SOLBindG ols de live Se Sacau ont hk manh GP hoa k oap AY 12 20 SQLBindParameter a a a a a a 12 27 SQLBrowseConnect a a a a a a 12 40 SOLCancel e ge a khe ewe E uk ae oa o oea 12 51 SQLColAttributes 0 a a a a 12 54 SQLColumnPrivileges a a a a 12 64 SQLColumns a a 12 70 SQOLGonnect a o sT od e e GT e 12 78 SQLDataSources 00 a a a ee 12 84 SQLDescribeCol a a a a a 12 88 SQLDisconnect 2 a a a a a a 12 93 SQLDriverConnect a a a a a 12 96 SOLDIVETS 2 iaar ma ay ce har Ay Rk rea da tar e ray AO 12 105 SOLETO os Behe Bae EA a A ES 12 109 SQLExecDirect 2 12 112 SQLExecute 2 2 d e aE A e AE e Ae G ea 12 119 SQLExtendedFetch a 12 125 SQLFetch s Gou o taw e w o e E 12 140 SQLForeignKeys a a ee eee 12 146 SQLFreeConnect ee ee ee 12 157 SQLFreeEnv ee ee ee a a 12 160 SQLFreeStmt 2 2 eee ee ee ee 12 163 SQLGetConnectOption 2 2 we 12 166 SOLGetCursorName ee ee 12 169 SOlLGetData 0 402 6 lao a a Boe Rk 12172 SQLGetFunctions ee ee 12 180 SQLGetInfo 2 2 wee 12 186 SQLGetStmtOption 2 a 2 12 220 SOLGetTypeldfo a 2 a 12 224
472. tions For Information About Assigning storage for a column in a result set Canceling statement processing Fetching a block of data or scrolling through a result set Fetching a row of data Returning the columns of foreign keys Returning the columns of a primary key INFORMIX CLI Programmer s Manual See SQLBindCol SOLCancel SQLExtendedFetch SOLFetch SOLForeignKeys SOLPrimaryKeys SQLTablePrivileges SQLTablePrivileges SQLTablePrivileges returns a list of tables and the privileges associated with each table The driver returns the information as a result set on the specified hstmt Syntax RETCODE SQLTablePrivileges hstmt szTableQualifier cbTableQualifier szTableOwner cbTableOwner szTableName cbTableName The SOLTablePrivileges function accepts the following arguments Typedef Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szTableQualifier Input Table qualifier If a driver supports quali fiers for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have qualifiers SWORD cbTableQualifier Input Length of szTableQualifier UCHAR FAR szTableOwner Input String search pattern for owner names If a driver supports owners for some tables but not for others such as when the driver retrieves data from different DBMSs an empty string denotes those tables that do not have own
473. tions m Setup shared library functions m Translation shared library functions INFORMIX CLI Function Summary The following tables list INFORMIX CLI functions according to the type of tasks that the functions perform The tables include function name conformance designation and a brief description of each function For more information about conformance designations see API Conformance Levels on page 3 3 For more information about the syntax and semantics for each function see Chapter 12 An application can call the SOLGetInfo function to get conformance infor mation about a driver To get information about support for a specific function in a driver an application can call SOLGetFunctions Function Summary 11 3 Connecting to a Data Source Connecting to a Data Source The following table describes functions that connect to a data source ODBC Function Name Conformance Purpose SOLAllocEnv Core Obtains an environment handle One environment handle is used for one or more connections SOLAllocConnect Core Obtains a connection handle SOLConnect Core Connects to a specific driver by data source name user ID and password SQLDriverConnect Level 1 Connects to a specific driver by connection string or requests that INFORMIX CLI display connection dialog boxes for the user SQLBrowseConnect Level 2 Returns successive levels of connection attributes and valid attribute values Whena value is specified for each co
474. to C on page B 19 At fetch time the driver processes the data for each bound column according to the arguments specified in SOLBindCol First it converts the data according to the argument fCType Next it fills the buffer to which rgbValue points Finally it stores the available number of bytes in pcbValue the value stored in pcbValue is the number of bytes available before the driver calls SOLFetch or SOLExtendedFetch INFORMIX CLI Function Reference 12 21 SQLBindCol Before the driver calls SQLFetch or SQLExtendedFetch it returns a value according to the following conditions m IfSQL_MAX_LENGTH has been specified with SQLSetStmtOption and the available number of bytes is greater than SOL_MAX_LENGTH the driver stores SOL_MAX_LENGTH in pcbValue m If the data is truncated because of SOL_MAX_LENGTH but the user s buffer is large enough for SOL_MAX_LENGTH bytes of data the driver returns SOL_SUCCESS Important The SOL_MAX_LENGTH statement option is intended to reduce network traffic To guarantee that data is truncated an application should allocate a buffer of the desired size and specify this size in the cbValueMax argument m If the user s buffer causes the truncation the driver returns SQL_SUCCESS_WITH_INFO and SQLSTATE 01004 Data truncated for the fetch function m If the data value for a column is NULL the driver sets pcbValue to SOL_NULL_DATA m If the number of bytes available to return cannot be dete
475. to character SOL data the resulting character data is in the yyyy mm dd format The value pointed to by the pcbValue argument of SOLBindParameter and the value of the cbValue argument of SQLPutData are ignored when data is converted from the date C data type The driver assumes that the size of rgbValue is the size of the date C data type Data Types B 39 Converting Data from C to SQL B 40 C to SQL Time Stamp The time stamp INFORMIX CLI C data type is SQL_C_TIMESTAMP The following table shows the INFORMIX CLI SQL data types to which time stamp C data can be converted fSqlType Test SQLSTATE SQL_CHAR Column length gt Display size N A CN 19 lt Column length lt Display size 01004 Column length lt 19 22003 Data value is not a valid date 22008 SQL_DATE Time fields are zero N A Time fields are non zero 01004 Data value does not contain a valid date 22008 SQL_TIMESTAMP Fractional seconds fields are not truncated N A Fractional seconds fields are truncated 01004 Data value is not a valid time stamp 22008 a The fractional seconds of the time stamp are truncated The time fields of the time stamp structure are truncated The date fields of the time stamp structure are ignored d The fractional seconds fields of the time stamp structure are truncated For information about what values are valid in a SQL_C_TIMESTAMP structure see Date and Time Stamp C Data Types on page B 11 When ti
476. tof DM The value specified for the argument fOption range was in the block of numbers reserved for ODBC connection and statement options but was not valid for the version of ODBC that the driver supports S1C00 Driver not capable The driver or data source does not support the value specified for the argument fOption 2 of 2 Usage Statement options for an hstmt remain in effect until they are changed by another call to SOLSetStmtOption or the hstmt is dropped by calling SQLFreeStmt with the SQL_DROP option Calling SQLFreeStmt with the SQL_CLOSE SQL_UNBIND or SQL_RESET_PARAMS options does not reset statement options Some statement options support substituting a similar value if the data source does not support the specified value of vParam In such cases the driver returns SQL_SUCCESS_WITH_INFO and SOLSTATE 01502 Option value changed For example if fOption is SOL_CONCURRENCY vParam is SQL_CONCUR_ROWVER and the data source does not support this the driver substitutes SOL_CONCUR_VALUES To determine the substituted value an application calls SOLGetStmtOption INFORMIX CLI Programmers Manual fOption SQL_BIND_TYPE SQLSetStmtOption The following table shows the currently defined options ODBC reserves options from 0 to 999 The format of information set with vParam depends on the specified fOption SQLSetStmtOption accepts option information in one of two different formats a null terminated character string or
477. tor types but was not valid for the version of ODBC supported by the driver The driver or data source does not support the value specified for the argument fDescType The time out period expired before the data source returned the requested information The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLColAttributes can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when it is called after SOLPrepare and before SQLExecute depending on when the data source evaluates the SQL statement associated with the hstmt INFORMIX CLI Function Reference 12 55 SQL ColAttributes fDescType Usage SQLColAttributes returns information either in pfDesc or in rgbDesc Integer information is returned in pfDesc as a 32 bit signed value all other formats of information are returned in rgbDesc When information is returned in pfDesc the driver ignores rgbDesc coDescMax and pcbDesc When infor mation is returned in rgbDesc the driver ignores pfDesc This function is an extensible alternative to SOLDescribeCol SQLDescribeCol returns a fixed set of descriptor information based on ANSI 89 SQL SOLColAttributes allows access to the more extensive set of descriptor information available in ANSI SQL 92 and Informix extensions fDescType Descriptor Types The following table shows the descriptor types and the arguments in which information is returned for them If a descriptor type does no
478. tored on the data source For more information see Precision Scale Length and Display Size on page B 5 2 of 3 INFORMIX CLI Function Reference 12 261 SQLProcedureColumns Column Name Data Type SCALE SMALLINT Comments The scale of the procedure column on the data source NULL is returned for data types where scale is not applicable For more information concerning scale see Precision Scale Length and Display Size on page B 5 RADIX SMALLINT For numeric data types either 10 or 2 If it is 10 the values in PRECISION and SCALE give the number of decimal digits allowed for the column For example a DECIMAL 12 5 column would return a RADIX of 10 a PRECISION of 12 and a SCALE of 5 a FLOAT column could return a RADIX of 10 a PRECISION of 15 and a SCALE of NULL If it is 2 the values in PRECISION and SCALE give the number of bits allowed in the column For example a FLOAT column could return a RADIX of 2 a PRECISION of 53 and a SCALE of NULL NULL is returned for data types where radix is not applicable NULLABLE SMALLINT not NULL Whether the procedure column accepts a NULL value m SQL_NO_NULLS The procedure column does not accept NULL values m SQL_NULLABLE The procedure column accepts NULL values m SQL_NULLABLE_UNKNOWN It is not known if the procedure column accepts NULL values REMARKS 12 262 VARCHAR 254 Code Example See SQLProcedures INFORMI
479. ts that the data source supports These information types do not exhaustively describe ODBC SQL grammar but they describe those parts of the grammar for which data sources commonly offer different levels of support Applications should determine the general level of supported grammar from the SOL_ODBC_SQL_CONFORMANCE information type and use the other information types to determine variations from the stated conformance level SQL_ALTER_TABLE SQL_COLUMN_ALIAS SQL_CORRELATION_NAME SQL_EXPRESSIONS_IN_ORDERBY SQL_GROUP_BY SQL_IDENTIFIER_CASE SQL_IDENTIFIER_QUOTE_CHAR SQL_KEYWORDS SQL_LIKE_ESCAPE_CLAUSE SQL_NON_NULLABLE_COLUMNS SQL_ODBC_SQL_CONFORMANCE SOL_ODBC_SOL_OPT_IEF SOL_ORDER_BY_COLUMNS_IN_SELECT SOL_OUTER_JOINS SOL_OWNER_USAGE SOL_POSITIONED_STATEMENTS SOL_PROCEDURES SQL_QUALIFIER_LOCATION SQL_QUALIFIER_NAME_SEPARATOR SQL_QUALIFIER_USAGE SQL_QUOTED_IDENTIFIER_CASE SQL_SPECIAL_CHARACTERS SQL_SUBQUERIES SQL_UNION INFORMIX CLI Function Reference 12 191 SQL Getinfo 12 192 SQL Limits The following values of fInfoType return information about the limits applied to identifiers and clauses in SQL statements such as the maximum lengths of identifiers and the maximum number of columns in a SELECT list The driver or the data source might impose limitations SOL_MAX_BINARY_LITERAL_LEN SOL_MAX_CHAR_LITERAL_LEN SQL_MAX_COLUMN_NAME_LEN SQL_MAX_COLUMNS_IN_GROUP_BY SQL_MAX_COLUMNS_IN_ORDER_BY SQL_MAX_COLUMNS_IN_INDEX SQL_
480. turns in the argument szErrorMsg describes the error and its cause S1001 Memory allocation The driver did not allocate memory required to support execution or failure completion of the function S1002 Invalid column The value specified for the argument icol was 0 and SQLFetch was used number to fetch the data The value specified for the argument icol was 0 and the SQL_USE_BOOKMARKS statement option was set to SQL_UB_OFF The specified column was greater than the number of result columns The specified column was bound through a call to SQLBindCol This description does not apply to drivers that return the SOL_GD_BOUND bitmask for the SOL_GETDATA_EXTENSIONS option in SQLGetInfo The specified column was at or before the last bound column specified through SOLBindCol This description does not apply to drivers that return the SQL_GD_ANY_COLUMN bitmask for the SQL_GETDATA_EXTENSIONS option in SOLGetInfo The application already called SOLGetData for the current row The column specified in the current call was before the column specified in the preceding call This description does not apply to drivers that return the SOL_GD_ANY_ORDER bitmask for the SOL_GETDATA_EXTENSIONS option in SQLGetInfo S1003 Program type out DM The argument fCType was not a valid data type or SOL_C_DEFAULT of range S1008 Operation canceled The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread i
481. ty Intro 10 FLOAT data type B 2 Floating point data converting to C B 23 converting to SQL B 35 Foreign keys 12 148 Freeing handles See Connection handles See Environment handles See Statement handles fSqlType B 2 Functionality of driver 12 180 12 189 Functions buffers 3 8 canceling 12 50 list of 11 3 return codes 7 3 SQL statement equivalents C 1 to C 10 See also specific function descriptions Functions ODBC SQL statement equivalents C 5 C 10 G GLOBAL TEMPORARY table type 12 329 Global transactions 12 333 GLS 1 11 Granting privileges 12 65 12 322 GROUP BY clauses 12 202 12 203 H h files 3 8 Handles error queues 12 109 See Connection handles See Environment handles See Statement handles Hashed indexes 12 316 HDBC See Connection handles Header files required 3 8 sqlext h C data types 3 12 contents 12 7 sql h 12 7 HENV See Environment handles Hexadecimal characters B 34 B 38 Holes in cursors 12 213 HSTMT See Statement handles Icons comment Intro 6 compliance Intro 8 feature Intro 7 platform Intro 7 Identifiers quoted 12 210 IEF See Integrity enhancement facility 12 Include files See Header files Indexes cardinality 12 317 clustered 12 316 collating 12 316 filtered 12 317 hashed indexes 12 316 listing 12 314 maximum columns in 12 203 maximum length 12 204 pages 12 317 qualifier usage in 12 210 sorting 12 316 unique 12 316 See also SQLStatistics Industry standa
482. uaranteed to return either no rows or one row If an application reselects a row based on the row ID column or columns and the row is not found the application can assume that the row was deleted or the row ID columns were modified The opposite is not true Even if the row ID has not changed the other columns in the row might have changed Columns returned for column type SQL_BEST_ROWID are useful for applications that need to scroll forward and backward within a result set to retrieve the most recent data from a set of rows The row ID column or columns are guaranteed not to change while positioned on that row INFORMIX CLI Function Reference 12 309 SQL SpecialColumns 12 310 The row ID column or columns might remain valid even when the cursor is not positioned on the row the application can determine this by checking the SCOPE column in the result set Columns returned for column type SOL_ROWVER are useful for applications that need the ability to check if any columns in a given row have been updated while the row was reselected using the row ID For example after re selecting a row using row ID the application can compare the previous values in the SOL_ROWVER columns to the ones last fetched If the value in a SQL_ROWVER column differs from the previous value the application can alert the user that data on the display has changed Code Example For a code example of a similar function see SQLColumns Related Functions
483. ue The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 70100 Operation aborted The data source did not process the cancel request S1000 General error An error occurred for which no specific SQLSTATE existed and for which no implementation specific SQLSTATE was defined The error message returned by SQLError in the argument szErrorMsg describes the error and its cause S1001 Memory allocation The driver did not allocate memory required to failure support execution or completion of the function Usage SQLCancel can cancel function processing on an hstmt that needs data If an application calls SQLCancel when processing does not involve the hstmt SOLCancel has the same effect as SOLFreeStmt with the SOL_CLOSE option this behavior is defined only for completeness and applications should call SOLFreeStmt to close cursors 12 50 INFORMIX CLI Programmers Manual SQLCancel Canceling Functions that N
484. ues for attributes set in previous levels When all levels of connection and their associated attributes are enumerated the driver returns SOL_SUCCESS the connection to the data source is complete and a complete connection string returns to the application The connection string can be used with SOLDriverConnect with the SQL_DRIVER_NOPROMPT option to establish another connection SOLBrowseConnect also returns SOL_NEED_DATA if recoverable nonfatal errors occur during the browse process For example an invalid password supplied by the application or an invalid attribute keyword supplied by the application cause recoverable nonfatal errors When SOL_NEED_DATA returns and the browse result connection string is unchanged an error has occurred and the application must call SQLError to return the SOLSTATE for browse time errors This permits the application to correct the attribute and continue the browse An application can terminate the browse process at any time by calling SQLDisconnect The driver terminates any outstanding connections and returns the hdbc to an unconnected state For more information see Connection Strings on page 4 7 INFORMIX CLI Function Reference 12 45 SQL BrowseConnect 12 46 Code Example In the following example an application calls SQLBrowseConnect repeatedly Each time SOLBrowseConnect returns SOL_NEED_DATA it passes back information about the data that it needs in szConnStrOut The applica
485. ul connection to the target data source this buffer contains the completed connection string Applica tions should allocate at least 255 bytes for this buffer Maximum length of the szConnStrOut buffer Pointer to the total number of bytes excluding the null termination byte available to return in szConnStrOut If the number of bytes available to return is greater than or equal to coConnStrOutMax the completed connection string in szConnStrOut is truncated to chConnStrOutMax 1 bytes Flag that indicates whether INFORMIX CLI must prompt for more connection information SQL_DRIVER_PROMPT SQL_DRIVER_COMPLETE SQL_DRIVER_COMPLETE_REQUIRED or SQL_DRIVER_NOPROMPT For more information see Driver Manager Guidelines on page 12 99 and Driver Guidelines on page 12 100 2 of 2 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 12 95 SQL DriverConnect Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that
486. ument cbValue was not 0 SQL_DEFAULT_PARAM or SQL_NULL_DATA DM The previous function call was not a call to SQLPutData or SQLParamData The previous function call was a call to SQLExecDirect or SQLExecute where the return code was SQL_NEED_DATA The argument rgbValue was not a null pointer and the argument cbValue was less than 0 but not equal to SQL_NTS or SOL_NULL_DATA The time out period expired before the data source completed processing the parameter value The time out period is set through SOLSetStmtOption SOL_QUERY_TIMEOUT 2 of 2 INFORMIX CLI Function Reference 12 273 SQL PutData Usage For an explanation of how data at execution parameter data passes when a statement executes see Passing Parameter Values on page 12 33 For an explanation of how data at execution column data is updated or added see SOLSetScrollOptions on page 12 295 Important An application can use SQLPutData to send parts of data when sending character C data to a column with a character binary or data source specific data type or when SQLPutData sends binary C data to a column witha character binary or data source specific data type If SQLPutData is called more than once under any other conditions it returns SOL_ERROR and SQLSTATE 22003 Numeric value out of range Code Example In the following example an application prepares an SQL statement to insert data into the EMPLOYEE table The statement contains par
487. ument szErrorMsg describes the error and its cause S1001 Memory allocation The driver was unable to allocate memory failure required to support execution or completion of the function S1010 Function sequence DM SQLExecute or SQLExecDirect was called for error the hstmt and returned SOL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns 1 of 2 12 320 INFORMIX CLI Programmer s Manual SQLSTATE S1090 S1C00 S1T00 Usage Error Invalid string or buffer length Driver not capable Time out expired SQLTablePrivileges Description DM The value of one of the name length arguments was less than 0 but not equal to SQL_NTS The value of one of the name length arguments exceeded the maximum length value for the corre sponding qualifier or name A table qualifier was specified but the driver or data source does not support qualifiers A table owner was specified but the driver or data source does not support owners A string search pattern was specified for the table owner table name or column name and the data source does not support search patterns for one or more of those arguments The driver or data source does not support the combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options The time out period expired before the data source returned the result set The time out period is set throug
488. umn m SQL_PARAM_TYPE_UNKNOWN The procedure column is a parameter whose type is unknown ODBC 1 0 m SQL_PARAM_INPUT The procedure column is an input parameter ODBC 1 0 m SQL_PARAM_INPUT_OUTPUT the procedure column is an input output parameter ODBC 1 0 m SQL_PARAM_OUTPUT The procedure column is an output parameter ODBC 1 0 m SQL_RETURN_VALUE The procedure column is the return value of the procedure ODBC 2 0 m SQL_RESULT_COL The procedure column is a result set column ODBC 1 0 DATA_TYPE SMALLINT not NULL SQL data type This can be an ODBC SQL data type or a driver specific SQL data type For a list of valid ODBC SQL data types see SQL Data Types on page B 2 For information about driver specific SQL data types see the driver s documentation TYPE_NAME VARCHAR 128 not NULL Data source dependent data type name for example CHAR VARCHAR MONEY LONG VARBINARY or CHAR FOR BIT DATA PRECISION INTEGER The precision of the procedure column on the data source NULL is returned for data types where precision is not appli cable For more information concerning precision see Precision Scale Length and Display Size on page B 5 LENGTH INTEGER The length in bytes of data transferred on an SOLGetData or SQLFetch operation if SQL_C_DEFAULT is specified For numeric data this size may be different than the size of the data s
489. unction accepts the following arguments Type Argument Use Description HENV henv Input Environment handle UWORD fDirection Input Determines whether the function fetches the next data source name in the list SQL_FETCH_NEXT or whether the search starts from the beginning of the list SQL_FETCH_FIRST UCHAR FAR szDSN Output Pointer to storage for the data source name SWORD cbDSNMax Input Maximum length of the szDSN buffer this buffer need not be longer than SQL_MAX_DSN_LENGTH 1 SWORD FAR pcbDSN Output Total number of bytes excluding the null termination byte available to return in szDSN If the number of bytes available to return is greater than or equal to cbDSNMax the data source name in szDSN is truncated to cbDSNMax 1 bytes 1 of 2 12 82 INFORMIX CLI Programmer s Manual SQL DataSources Type Argument Use Description UCHAR FAR szDescription Output Pointer to storage for the description of the driver associated with the data source SWORD cbDescriptionMax Input Maximum length of the szDescription buffer this buffer should be at least 255 bytes SWORD FAR pcbDescription Output Total number of bytes excluding the null termination byte available to return in szDescription If the number of bytes available to return is greater than or equal to cbDescriptionMax the driver description in szDescription is truncated to cbDescriptionMax 1 bytes 2 of 2 Return Codes SQL_SUCCESS
490. unknown this value is set to 0 SQL_MULT_RESULT_SETS A character string a Y if the data source supports multiple result sets m N if it does not SQL_MULTIPLE_ACTIVE_TXN A character string a Y if active transactions on multiple connections are allowed m N if only one connection at a time can have an active transaction SQL_NEED_LONG_DATA_LEN A character string a Y if the data source needs the length of a long data value the data type is SQL_LONGVARCHAR SQL_LONGVARBINARY or a long data source specific data type before that value is sent to the data source m N if it does not For more information see SQLBindParameter SQL_NON_NULLABLE_COLUMNS A 16 bit integer that specifies whether the data source supports non nullable columns m SOL_NNC_NULL All columns must be nullable m SQL_NNC_NON_NULL Columns may be non nullable the data source supports the NOT NULL column constraint in CREATE TABLE statements 13 of 24 INFORMIX CLI Function Reference 12 205 SQL Getinto InfoType SOL_NULL_COLLATION Returns A 16 bit integer value that specifies where NULLs are sorted in a list m SQL_NC_END NULLs are sorted at the end of the list regardless of the sort order m SQL_NC_HIGH NULLs are sorted at the high end of the list m SQL_NC_LOW NULLs are sorted at the low end of the list m SQL_NC_START NULLs are sorted at the start of the list
491. urn FALSE return FALSE INFORMIX CLI Programmers Manual SQL PutData Related Functions For Information About See Canceling statement processing SOLCancel Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute Returning the next parameter to send data for SOLParamData Assigning storage for a parameter SOLBindParameter 4 INFORMIX CLI Function Reference 12 277 SQL RowCount SQLRowCount 12 278 DELETE statement affects Syntax Type Argument Use HSTMT hstmt Input SDWORD FAR pcrow Output RETCODE SQLRowCount hstmt SOLRowCount returns the number of rows that an UPDATE INSERT or pcrow The SOLRowCount function accepts the following arguments Description Statement handle For UPDATE INSERT and DELETE statements pcrow is the number of rows affected by the request or 1 if the number of affected rows is not available For other statements and functions the driver can define the value of pcrow For example some data sources might be able to return the number of rows that a SELECT statement or a catalog function returns before fetching the rows Many data sources cannot return the number of rows in a result set before fetching them for maximum interoperability applications should not rely on this behavior Return Codes SOL_INVALID_HANDLE INFORMIX CLI Programmers Manual SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or
492. ust include the path to your INFORMIXDIR bin directory Setting Environment Variables in a File If you set these variables at the command line you must reset them whenever you log on to your system If you set these variables in a file they are set automatically when you log on to your system For example if your Informix directory path is usr informix in the C shell you can add the following lines to your cshre file to set the INFORMIXDIR and PATH environment variables setenv INFORMIXDIR usr informix setenv PATH PATH INFORMIXDIR bin In the Bourne or Korn shells you can add the following lines to your login or profile file INFORMIXDIR usr informix export INFORMIXDIR PATH PATH INFORMIXDIR bin export PATH Overview of INFORMIX CLI 1 9 Setup File Setup File INFORMIX CLI provides a sample setup file called setup odbc in INFORMIXDIR etc You can use this file to set up environment variables for the INFORMIX CLI driver This file includes the following environment variables m INFORMIXDIR INFORMIXDIR specifies the directory where the INFORMIX Enter prise Client Software Developer s Kit is installed m INFORMIXSQLHOSTS INFORMIXSQLHOSTS is optional It specifies the directory that contains sqlhosts By default sqlhosts is in INFORMIXDIR etc Set INFORMIXSQLHOSTS if you want sqlhosts to be in a different directory For more information about environment variables see the Informix Guide to SQL Re
493. ut Return Codes Description Statement handle One of the following options SOL_CLOSE Close the cursor associated with hstmt if one is defined and discard all pending results The application can reopen this cursor later by executing a SELECT statement again with the same or different parameter values If no cursor is open this option has no effect for the application SQL_DROP Release the hstmt free all resources associated with it close the cursor if one is open and discard all pending rows This option termi nates all access to the hstmt The hstmt must be reallocated to be reused SQL_UNBIND Release all column buffers bound by SQLBindCol for the given hstmt SQL_RESET_PARAMS Release all parameter buffers set by SOLBindParameter for the given hstmt SOL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_ HANDLE INFORMIX CLI Function Reference 12 161 SQL FreeStmt 12 162 Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns
494. utMax 1 bytes 2 of 2 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NEED_DATA SQL_ERROR or SOL_INVALID_ HANDLE INFORMIX CLI Function Reference 12 39 SQL BrowseConnect 12 40 Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 General warning 01004 Data truncated 01S00 Invalid connection string attribute 08001 Unable to connect to data source 08002 Connection in use INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer szConnStrOut was not large enough to return entire browse result connection string so the string was truncated The argument pcbConnStrOut contains the length of the untruncated browse result connection string function returns SQL_SUCCESS_WITH_INFO An invalid attribute keyword was specified in the browse request connection string szConnStrIn Function returns
495. value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 24000 S1000 S1001 S1010 S1011 General warning Invalid cursor state General error Memory allocation failure Function sequence error Operation invalid at this time INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The argument fOption was SOL_ROW_NUMBER but the cursor was not open or the cursor was positioned before the start of the result set or after the end of the result set An error occurred for which no specific SQLSTATE existed and for which no implementation specific SOLSTATE was defined The error message returned by SOLError in the argument szErrorMsg describes the error and its cause The driver did not allocate memory required to support execution or completion of the function DM SOLExecute or SOLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns The fOption argument was SQL_GET_BOOKMARK and the value of the SOL_USE_BOOKMARKS statement option was SQL_UB_OFF 1 of 2 INFORMIX CLI Function Reference 12 219 SQL GetStmtOption 12 220 SQLSTATE Error S1092 Option type out of range S11
496. values for a single SQL statement an application calls SQLParamOptions For example if there are 10 sets of column values to insert into a table and the same SOL statement can be used for all 10 operations the application can set up an array of values and then submit a single INSERT statement If an application uses SOLParamOptions it must allocate enough memory to handle the array of values To retrieve a list of the procedures stored in a data source an application calls SOLProcedures Executing SQL Statements 5 11 Related Functions 5 12 Function SQLNativeSql SOLNumParams SQLSetStmtOption SQLSetConnectOption SOLGetStmtOption INFORMIX CLI Programmers Manual Related Functions INFORMIX CLI provides the following functions related to SQL statements For more information about these functions see Chapter 12 Description Retrieves the SQL statement as processed by the data source with escape sequences translated to SQL code used by the data source Retrieves the number of parameters in an SQL statement Sets or retrieves statement options such as orientation for binding row sets maximum amount of variable length data to return maximum number of result set rows to return and query time out value SQLSetConnectOption sets options for all the state ments in a connection Retrieving Results Result Sets and INFORMIX CLI Assigning Storage for Results Binding Determining the Characteristi
497. ver cannot access Variable length UDT with an internal structure that the database server cannot access Sequential INT8 To use the INFORMIX CLI SQL data types for Universal Server include Precision Scale Length and Display Size Precision Scale Length and Display Size The functions that get and set precision scale length and display size for SQL values have size limitations for their input arguments Therefore these values are limited to the size of an SDWORD that has a maximum value of 2 147 483 647 The following table describes these values Value Description for a Numeric Data Type Description for a Non Numeric Data Type Precision Scale Length Display size Maximum number of digits Maximum number of digits to the right of the decimal point For floating point values the scale is undefined because the number of digits to the right of the decimal point is not fixed Maximum number of bytes that a function returns when a value is transferred to its default C data type Maximum number of bytes needed to display data in Character form Either the maximum length or the specified length Not applicable Maximum number of bytes that a function returns when a value is transferred to its default C data type The length does not include the NULL termination byte Maximum number of bytes needed to display data in character form Data Types B 5 Precision Scale Length an
498. ver retrieves data from different DBMSs an empty string denotes those procedures that do not have owners SWORD cbProcOwner Input Length of szProcOwner UCHAR FAR szProcName Input String search pattern for procedure names SWORD cbProcName Input Length of szProcName UCHAR FAR szColumnName Input String search pattern for column names SWORD cbColumnName Input Length of szColumnName INFORMIX CLI Function Reference 12 257 SQLProcedureColumns 12 258 Returns SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SOLSTATE values for the function The return code for each SOLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value SQLSTATE Error Description 01000 General warning Driver specific informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver and link failure the data source to which the driver was connected failed before the function completed p
499. verDescMax pcbDriverDesc szDriverAttributes cbDrvrAttrMax pcbDrvrAttr The SOLDrivers function accepts the following arguments Type Argument Use Description HENV henv Input Environment handle UWORD fDirection Input Specifies whether the function fetches the next driver description in the list SQL_FETCH_NEXT or whether the search starts from the beginning of the list SQL_FETCH FIRST UCHAR FAR szDriverDesc Output Pointer to storage for the driver description SWORD cbDriverDescMax Input Maximum length of the szDriverDesc buffer SWORD FAR pcbDriverDesc Output Total number of bytes excluding the null termination byte available to return in szDriverDesc If the number of bytes available to return is greater than or equal to cbDriverDescMax the driver description in szDriverDesc is truncated to cbDriverDescMax 1 bytes 1 of 2 INFORMIX CLI Function Reference 12 103 SQL Drivers 12 104 Type Argument UCHAR FAR SWORD SWORD FAR pcebDrorAttr Return Codes Diagnostics INFORMIX CLI Programmers Manual cbDrorAttrMax Use szDriverAttributes Output Input Output Description Pointer to storage for the list of driver attribute value pairs For more infor mation see Usage on page 12 106 Maximum length of the szDriverAttributes buffer Total number of bytes excluding the null termination byte available to return in szDriverAttributes If the number of bytes availab
500. where the return code was SOL_NEED_DATA or a call to SOLPutData The previous function call was a call to SQLParamData The time out period expired before the data source completed processing the parameter value The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 If SQLParamData is called while sending data for a parameter in an SQL statement it can return any SQLSTATE that can be returned by the function that was called to execute the statement SQLExecute or SQLExecDirect For an explanation of how data at execution parameter data is passed at statement execution time see Passing Parameter Values on page 12 33 SQLParamData Related Functions For Information About See Canceling statement processing SOLCancel Returning information about a parameter in a SQLDescribeParam extension statement Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SOLExecute Sending parameter data at execution time SOLPutData Assigning storage for a parameter SOLBindParameter INFORMIX CLI Function Reference 12 245 SQL Prepare SQLPrepare SQLPrepare prepares an SQL string for execution Syntax RETCODE SQLPrepare hstmt szSqlStr cbSqlStr The SOLPrepare function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szSqlStr Input SQL text string SDWORD cbSqlStr Input Length of szSqlStr Return Codes SQL
501. with SQLPutData In this case the cbColDef argument contains the total number of bytes that are sent for the parameter For more information see Passing Parameter Values on page 12 33 INFORMIX CLI Programmers Manual SQLBindParameter rgbValue Argument The rgbValue argument points to a buffer that when SQLExecute or SQLExecDirect is called contains the actual data for the parameter The data must be in the form specified by fCType If pcbValue is the result of the SOL_LEN_DATA_AT_EXEC length macro or SQL_DATA_AT_EXEC then rgbValue is an application defined 32 bit value that is associated with the parameter It is returned to the application through SQLParamData For example rgbValue might be a token such as a parameter number a pointer to data or a pointer to a structure that the application used to bind input parameters If the parameter is an input output parameter rgbValue must be a pointer to a buffer where the output value is stored If the fParamType argument is SOL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT rgbValue points to a buffer in which the driver returns the output value If the procedure returns one or more result sets the rgbValue buffer is not guaranteed to be set until all results are fetched If fParamType is SOL_PARAM_OUTPUT and rgbValue and pcbValue are both null pointers the driver discards the output value cbValueMax Argument For character and binary C data the cbValueMax argument sp
502. wo values SQL_COMMIT SQL_ROLLBACK Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SOL_INVALID_HANDLE INFORMIX CLI Function Reference 12 331 SQL Transact Diagnostics SQLSTATE Error When the function returns SQL_SUCCESS_WITH_INFO or SQL_ERROR you can call SQLError to get the SOLSTATE value The following table describes the SQLSTATE values for the function The return code for each SQLSTATE value is SOL_ERROR unless an SQLSTATE description indicates otherwise If you are not using a driver manager the driver returns the SQLSTATE value If you are using a driver manager the notation DM at the beginning of an SQLSTATE description indicates that the driver manager returns the SOLSTATE value otherwise the driver returns the SOLSTATE value Description 01000 08003 08007 S1000 S1001 S1010 S1012 S1C00 12 332 General warning Connection not open Connection failure during transaction General error Memory allocation failure Function sequence error Invalid transaction operation code Driver not capable INFORMIX CLI Programmers Manual INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO DM The hdbc was not in a connected state The connection associated with the hdbc failed during the execution of the function it cannot be determined whether the requested COMMIT or ROLLBACK occurred before the failure An error occurred for w
503. xecution Time Specifying Arrays of Parameter Values Related Functions 5 3 5 5 5 5 5 6 5 7 5 7 5 9 5 10 5 10 5 11 5 12 5 2 INFORMIX CLI Programmer s Manual his chapter describes the different ways an application can execute SQL statements SQL Statements and INFORMIX CLI An application can submit any SQL statement that is supported by a data source and ODBC defines a standard syntax for SQL statements For maximum interoperability an application should submit only SQL state ments that use this syntax the driver translates these statements to the syntax that the data source uses If an application submits an SQL statement that does not use the ODBC syntax the driver passes the statement directly to the data source Important For CREATE TABLE and ALTER TABLE statements applications should use the data type name returned by SQLGetTypelnfo in the TYPE_NAME column rather than the data type name defined in the SQL syntax Use SQLExecDirect to execute a statement once Use SQLPrepare to prepare a statement and execute it multiple times with SQLExecute An application calls SOLTransact to commit or roll back a transaction Executing SQL Statements 5 3 SQL Statements and INFORMIX CLI Figure 5 1 illustrates a simple sequence of function calls to execute SQL state ments Figure 5 1 rere A Sequence of nitialize Function Calls to Execute SQL Statements Repeatable execution wy yo SQLBind
504. y C data cbValueMax determines the amount of data that can be received in a single call to SOLGetData For all other types of C data cbValueMax is ignored the driver assumes that the size of rgbValue is the size of the C data type specified with fCType and returns the entire data value For more information about length see Precision Scale Length and Display Size on page B 5 1 of 2 12 170 INFORMIX CLI Programmer s Manual Type Argument SDWORD FAR pcbValue Use Output Diagnostics SQL GetData Description SQL_NULL_DATA the total number of bytes excluding the null termination byte for character data available to return in rgbValue prior to the current call to SOLGetData or SQL_NO_TOTAL if the number of available bytes cannot be determined For character data if pcbValue is SOL_NO_TOTAL or is greater than or equal to cbValueMax the data in rgbValue is truncated to cbVal ueMax 1 bytes and is null terminated by the driver For binary data if pcb Value is SOL_NO_TOTAL or is greater than cbValueMax the data in rgb Value is truncated to cbValueMax bytes For all other data types the value of cbValueMax is ignored and the driver assumes the size of rgbValue is the size of the C data type specified with fCType 2 of 2 Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SOL_NO_DATA_ FOUND SOL_STILL_EXECUTING SOL_ERROR or SOL_INVALID_HANDLE When the function returns SQL_SUCCESS_WITH_INF
505. yte The driver always null terminates SOL_C_CHAR data b The numbers in this list are the numbers stored in the fields of the TIMESTAMP_STRUCT structure a aaeeeaiimaons B 30 INFORMIX CLI Programmers Manual Converting Data from C to SQL Converting Data from C to SQL When an application calls SQLExecute or SQLExecDirect the driver retrieves the data for any parameters that are bound with SOLBindParameter from storage locations in the application For data at execution parameters the application sends the parameter data with SOLPutData If necessary the driver converts the data from the data type specified by the fCType argument in SOLBindParameter to the data type specified by the fSq Type argument in SOLBindParameter Finally the driver sends the data to the data source The tables in the following sections describe how the driver or data source converts data sent to the data source drivers are required to support conver sions from all INFORMIX CLI C data types to the INFORMIX CLI SQL data types that they support For a given INFORMIX CLI C data type the first column of the table lists the legal input values of the fSq Type argument in SOLBindParameter The second column lists the outcomes of a test that the driver performs to determine whether it can convert the data The third column lists the SOLSTATE that is returned for each outcome by SOLExecDirect SOLExecute or SOLPutData Data is sent to the data source only if SQL_SUC
506. zNameLNAME_LEN SDWORD cbName SWORD sAge SDWORD cbAge UCHAR szBirthday BDAY_LEN SDWORD cbBirthday EmpTable EmpTable rget ROWS UDWORD crow irow UWORD rgfRowStatus ROWS SQLSetStmtOption hstmt SQL_BIND_TYPE sizeof EmpTable SQLSetStmtOption hstmt SQL_CONCURRENCY SQL_CONCUR_READ_ONLY SQLSetStmtOption hstmt SQL_CURSOR_TYPE SQL_CURSOR_KEYSET_DRIVEN SQLSetStmtOption hstmt SQL_ROWSET_SIZE ROWS retcode SQLExecDirect hstmt SELECT NAME AGE BIRTHDAY FROM EMPLOYEE ORDER BY 3 2 1 SQL_NTS if retcode SQL_SUCCESS SQLBindCol hstmt 1 SQL_C_CHAR rget 0 szName NAME_LEN amp rget 0 cbName INFORMIX CLI Programmers Manual SQLExtendedFetch SQLBindCol hstmt 2 SQL_C_SSHORT amp rget 0 sAge 0 amp rgetl0 cbAge SQLBindCol hstmt 3 SQL_C_CHAR rget 0 szBirthday BDAY_LEN g8rget 0 cbBirthday Fetch the rowset data and print each row On an error display a message and exit while TRUE retcode SQLExtendedFetch hstmt SQL_FETCH_NEXT 1 amp crow if retcode SQL_ER show_error if retcode SQL_SU rgfRowStatus ROR retcode SQL_SUCCESS WITH_INFO CCESS retcode SQL_SUCCESS_WITH_INFO for jrow 0 irow lt crow irowt if rgfRowStatu sLirow SQL_ROW_DELETED amp amp rgfRowStatus irow SQL_ROW_ERROR fprintf out NAME_L BDAY_L else break Related Functions
507. zero indicates that the data is an empty zero length string A length of zero is different from a null pointer If the application specifies the length of character data the character data does not need to be null terminated SQL_NTS This value specifies that a character data value is null terminated SQL_NULL_DATA This value tells the driver to ignore the value in the input buffer and use a NULL data value instead It is valid only when the input buffer provides the value of a parameter in an SQL statement For character data that contains embedded null characters the operation of INFORMIX CLI functions is undefined for maximum interoperability it is better not to use them Informix database servers treat null characters as end of string markers or as indicators that no more data exists Unless it is specifically prohibited in a function description the address of an input buffer can be a null pointer In such cases the value of the corre sponding buffer length argument is ignored For more information about input buffers see Converting Data from SQL to C on page B 19 Guidelines for Calling INFORMIX CLI Functions 3 9 Buffers Output Buffers An application passes the following arguments to the driver so that the driver can return data in an output buffer The address of the output buffer to which the driver returns the data Unless it is specifically prohibited in a function description the address of an output

Download Pdf Manuals

Related Search

Related Contents

Tellus mobi  EN DE Original-Montage- und Betriebsanleitung Original assembly  User Manual - Energy Conscious  - Goodmans  Linksys DMP100 User's Manual  1. General laboratory consumables  取扱説明書    TC48-1066  avertissement  

Copyright © All rights reserved. Failed to retrieve file