Home

Informix CLI Programmer`s Manual, Version 2.5

1. Sources Dialog Box User Data Sources Driver Close Stores7 Informix Accounting informix Help Documentation Informix l Inventory Informix Setup Delete Add Options System DSN Drivers When an application requests it the driver displays the Logon to INFORMIX dialog box to retrieve login information as Figure 5 2 illustrates Logon to INFORMIX Figure 5 2 The Logon to INFORMIX Dialog Database Name Stores7 z OK Box User Name mjones Options 5 8 INFORMIX CLI Programmer s Manual Connection Browsing with SQLBrowseConnect Connection Browsing with SQLBrowseConnect SQLBrowseConnect supports an iterative method of listing and specifying the attributes and attribute values required to connect to a data source For each level 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 Each time an application calls SQLBrowseConnect it 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 applic
2. 3 Modify the applicable data source text boxes For more information regarding available options see Adding a Data Source on page 2 16 4 When you are finished click OK in the ODBC INFORMIX Driver Setup dialog box The ODBC Administrator updates your ODBC INI file 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 data source connection INFORMIX CLI 2 25 Connecting to a Data Source 2 26 Connecting to a Data Source An INFORMIX CLI application can pass connection information in several ways For example the application might have the driver always prompt the user for connection information or the application might expect a connection string that specifies the data source connection How you connect to a data source depends on the connection method that your INFORMIX CLI application uses Using Dialog Boxes to Connect to a Data Source One common way of connecting to a data source is through the Data Sources dialog box as Figure 2 11 illustrates If your INFORMIX CLI application is set up to use a dialog box the Data Sources dialog box appears and prompts you for the appropriate data source connection information Figure 2 11 The Data Sources Dialog Box User Data Sources Driver Close Stores7 Informix Help Setup Delete Add System DSN Drivers
3. returns N for the SQL_NEED_LONG_DATA_LEN information K 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 SQLBindParameter Call InitUserData 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 Hef 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 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 13 268 INFORMIX CLI Programmer s Manual SQL PutData SWORD sParam UCHAR Data SDWORD cbData switch sParam case 1 Prompt user for employee name PromptEmp
4. SQL SpecialColumns The rowid 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 SQL_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 rowid For example after reselecting a row using rowid the application can compare the previous values in the SOQL_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 For information about See Assigning storage for a column in a result set SOLBindCol Canceling statement processing SQLCancel Returning the columns in a table or tables SOLColumns Fetching a block of data or scrolling througha SOQLExtendedFetch result set Fetching a row of data SQLFetch Returning the columns of a primary key SOLPrimaryKeys INFORMIX CLI Function Reference 13 303 SQL Statistics SQLStatistics SQ1Statistics 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 sz
5. INFORMIX CLI Programmer s Manual Using Dialog Boxes to Connect to a Data Source To connect to a data source using a dialog box In the Data Sources dialog box select a data source Click OK The Logon to Informix dialog box appears as Figure 2 12 illustrates The connection information that appears is the default information listed in your ODBC INI Figure 2 12 The Logon to Host Name User Name Password Database Name INFORMIX Dialog So A E aa mickey Cancel Help To accept the default values and connect to the data source click OK or To modify the default values for this data source continue to step 4 In the Database Name text box type the name of the OnLine or SE database that contains the tables that you want to access You can also click the down arrow to choose a name from a drop down list In the Host Name text box type the name of the computer on which your Informix database server resides In the User Name text box type your user name as specified on the database server In the Password text box type your password for the UNIX server to which you want to connect To display the INFORMIX Server Options dialog box click Options This dialog box lets you specify options that are described in Optional Data Source Configuration Information on page 2 17 INFORMIX CLI 2 27 Using a Connection String to Connect to a Data Source
6. All cursor names within the hdbc must be unique The maximum length of a cursor name is defined by the driver For maximum interoperability cursor names should not exceed 18 characters A cursor name remains set until the stmt with which it is associated is dropped using SOLFreeStmt with the SQL_DROP option INFORMIX CLI Function Reference 13 283 SQL SetCursorName 13 284 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 SQLAllocStmt hdbc amp hstmtUpdate SQLSetCursorName hstmtSelect C1 SQL_NTS 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 Read through the result set until the cursor is ar positioned on the row for the 25 year
7. INFORMIX CLI Function Reference 13 63 SQL ColumnPrivileges options Column Name TABLE_QUALIFIER TABLE_OWNER TABLE_NAME COLUMN_NAME GRANTOR 13 64 INFORMIX CLI Programmer s Manual Data Type VARCHAR 128 VARCHAR 128 VARCHAR 128 not NULL VARCHAR 128 not NULL VARCHAR 128 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 SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SQL_MAX_COLUMN_NAME_LEN Comments 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 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 Table identifier Column identifier Identifier of the user who granted the privilege NULL if not applicable to the data source 1 of 2 Column Name Data Type GRANTEE VARCHAR 128 not NULL PRIVILEGE VAR
8. The driver could not allocate memory for the statement handle S1009 Invalid argument DM The argument phstmt was a null pointer value Usage A statement handle references statement information such as network infor mation SQLSTATE values and error messages cursor name several result set columns and status information for SQL statement processing INFORMIX CLI Function Reference 13 15 SQLBindCol To request a statement handle an application connects to a data source and then passes the address of an hstmt to SQLAIlocStmt The driver allocates memory for the statement information and stores the value of the associated handle in the hstmt 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 SQLAIlocStmt with a pointer to a valid hstmt the driver overwrites the hstmt without regard to its previous contents Code Example See SOLBrowseConnect SOLConnect and SQLSetCursorName Related Functions For information about See Executing an SQL statement SQLExecDirect Executing a prepared SQL statement SQLExecute Freeing a statement handle SQLFreeStmt Preparing a statement for execution SQLPrepare SQLBindCol SQLBindCol assigns the storage and data type for a column in a result set as follows m A storage buffer that receives the contents of a co
9. 01002 08003 25000 S1000 S1001 S1010 Error General warning Disconnect error Connection not open Invalid trans action state General error Memory allocation failure Function sequence error Description 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 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 DM SQLExecute or SQLExecDirect was called for the 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 INFORMIX CLI Function Reference 13 91 SQL Disconnect Usage If an application calls SQLDisconnect after SQLBrowseConnect returns SQL_NEED_DATA and before it returns a different return code the driver cancels the connection browsing process and returns the hdbc to an uncon nected state If an appli
10. 08S01 22002 13 128 Return Codes Diagnostics Error General warning Data truncated Error in row Restricted data type attribute violation Communication link failure Indicator value required but not supplied INFORMIX CLI Programmer s Manual SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE When SQLExtendedFetch returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLExtendedFetch 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 SQLSTATE value is SQL_ERROR unless noted otherwise Description 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
11. 2 of 2 Setting and Retrieving Driver Options The following table describes functions that set and retrieve driver options ODBC Function Name Conformance Purpose SQLSetConnectOption Level1 Sets a connection option SOQLGetConnectOption Level 1 Returns the value of a connection option SQLSetStmtOption Level 1 Sets a statement option SOLGetStmtOption Level 1 Returns the value of a statement option Preparing SQL Requests The following table describes functions that prepare SQL requests ODBC Function Name Conformance Purpose SQLAllocStmt Core Allocates a statement handle SQLPrepare Core Prepares an SQL statement for later execution 1 of 2 Function Summary 12 5 Submitting SQL Requests Function Name SQLBindParameter SQLParamOptions SQLGetCursorName SQLSetCursorName Function Name SQLExecute SQLExecDirect SQLNativeSql SQLNumParams SQLParamData SQLPutData 12 6 INFORMIX CLI Programmer s Manual SQLSetScrollOptions ODBC Conformance Level 1 Level 2 Core Core Level 2 Submitting SQL Requests The following table describes functions that submit SQL requests ODBC Conformance Core Core Level 2 Level 2 Level 1 Level 1 Purpose Assigns storage for a parameter in an SQL statement Specifies the use of multiple values for parameters Returns the cursor name associated with a statement handle Specifies a cursor name Sets options that control cu
12. 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 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 2 of 5 SQLSTATE 1001 1002 1003 Error Memory allocation failure Invalid column number Program type out of range SQ_GetData Description The driver did not allocate memory required to support execution or completion of the function The value specified for the argument icol was 0 and SQLFetch was used 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 SOLBindCol This description does not apply to drivers that return the SQL_GD_BOUND bitmask for the SQL_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 SQLGetInfo The application already called SQLGetData for the current row The column sp
13. Attribute value description Name of a data source as returned by SQLDataSources or the data sources dialog box of SQLDriverConnect Description of the driver as returned by the SOLDrivers function A user ID The password that corresponds to the user ID or an empty string if no password exists for the user ID PWD Driver Manager Guidelines 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 follows m SQL_DRIVER_PROMPT The driver manager displays the Data Sources 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
14. Data converting See Converting data long See Long data values retrieving See Retrieving data transferring in binary form C 8 translating See Translation shared libraries truncating See Truncating data Data Definition Language DDL in embedded SQL D 5 Data Manipulation Language DML in embedded SQL D 6 qualifier usage in 13 207 Data source name attribute for driver UNIX 2 9 Data source specification entry for driver UNIX 2 9 Data sources adding 14 5 configuring 14 6 default 5 6 deleting 14 7 information types 13 189 listing 13 86 names 13 194 Index 3 read only 13 194 UNIX adding and modifying 2 6 connecting to 2 11 Windows adding and modifying 2 16 Data translation See Translation shared libraries Data Types supported by INFORMIX driver 1 15 Data types supported by INFORMIX CLI driver 1 15 See C data types See SQL data types Data at execution canceling 13 53 macro 13 30 13 33 13 35 13 36 parameters 6 10 SQLBindParameter 13 30 13 33 13 35 13 36 DATABASE attribute for Informix driver UNIX 2 14 2 29 Database name attribute for driver UNIX 2 9 Databases current 13 278 information types 13 188 Date data converting to C C 21 converting to SQL C 32 intervals 13 211 literals 6 13 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 Date functions supported by INFORMIX driver 1 15 DBMS product information 13 188 DDL See Data Definition Language
15. Description 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 corre sponding descriptor record must not be a null pointer 1 of 3 INFORMIX CLI Function Reference 13 145 SQ_Fetch 13 146 SQLSTATE Error 22003 Numeric value out of range 22005 Error in assignment 22008 Datetime field overflow 22012 Division by zero 24000 Invalid cursor state 40001 Serialization failure 1000 General error S1001 Memory allocation failure INFORMIX CLI Programmer s Manual Description Returning the numeric value as numeric or string for one or more columns would have caused the whole as opposed to fractional part of the number to be truncated Returning the binary value for one or more columns would have caused a loss of binary significance For more information see Converting Data from SQL to C Data Types on page C 13 A zero length string was inserted into a string field and the string was bound to a nume
16. Determining the Characteristics of a Result Set Fetching Result Data Using Cursors Retrieving Data Rout inbound Calan Assigning Storage for Rowsets poe Retrieving Rowset Data Using Block and Scrollable Cursots Modifying Result Set Data with Positioned Update d Delete Statements Bea amp a er eee Processing Multiple Results 5 10 6 5 6 6 6 7 6 7 6 9 6 10 6 11 6 12 6 19 7 4 7 4 7 5 7 6 7 7 7 7 7 9 7 9 7 13 7 15 Table of Contents v Chapter 8 Chapter 9 Chapter 10 Chapter 11 Chapter 12 Retrieving Status and Error Information Function Return Codes Retrieving Error Messages Error Messages Error Text Format Sample Error Messages Processing Error Messages Terminating Transactions and Connections Terminating Statement Processing Terminating Transactions Terminating Connections Constructing an INFORMIX CLI ere Static SQL Example Interactive Ad Hoc Query Bcmnle Designing Performance Oriented Applications Connecting to a Data Source Executing Calls or a SQLPrepare SOLExecute Versus SQLExecDirect Committing Data Function Summary INFORMIX CLI Function Summary Connecting to a Data Source Obtaining Information About a Driver and Data So ice Setting and Retrieving Driver Options Preparing SQL Requests Submitting SQL Requests Retrieving Results and informato about Results Obtaining Information About Data Source System Tables Terminating a Statement Term
17. HDBC hdbc Input Connection handle Return Codes SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE 13 150 INFORMIX CLI Programmer s Manual SQLFreeConnect Diagnostics When SQLFreeConnect returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SOLSTATE values commonly returned by SQLFree Connect 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver link failure and the data source failed before the function completed 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 S1010 Function DM The function was called prior to calling sequence error SQLDisconnect for the hdbc Usage Prior to calling SQLFreeConnect an application must call SQLDisconnect for the hdbc Otherwise SQLFreeConnect returns SQL_ERROR and the hdbc remains valid SQLDisconnect automatically
18. S1000 S1001 S1002 Diagnostics Error General warning Data truncated Invalid cursor state General error Memory allocation failure Invalid column number 13 88 INFORMIX CLI Programmer s Manual When SQLDescribeCol returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLDescribeCol 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 SQLSTATE value is SQL_ERROR unless noted otherwise Description 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 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 The value specified f
19. SQL_CURSOR_ROLLBACK_BEHAVIOR SQL_DATA_SOURCE_NAME SQL_DATA_SOURCE_READ_ONLY 13 192 INFORMIX CLI Programmer s Manual Returns A 16 bit integer value that indicates how a COMMIT operation affects cursors and prepared statements in the data source SQL_CB_DELETE Close cursors and delete prepared state ments To use the cursor again the application must reprepare and reexecute the hstmt SQL_CB_CLOSE Close cursors For prepared statements the application can call SQLExecute on the hstmt without calling SQLPrepare again 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 reexecute the hstmt without repreparing it A 16 bit integer value that indicates how a ROLLBACK operation affects cursors and prepared statements in the data source SQL_CB_DELETE Close cursors and delete prepared state ments To use the cursor again the application must reprepare and reexecute the hstmt SQL_CB_CLOSE Close cursors For prepared statements the application can call SQLExecute on the hstmt without calling SQLPrepare again 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 reexecute the hstmt without repreparing it A character string with the data source name used during connection If the applicat
20. SQL_MAX_ROW_SIZE_INCLUDES_LONG SQL_MAX_STATEMENT_LEN 13 200 INFORMIX CLI Programmer s Manual Returns 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 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 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 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 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 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 A 16 bit integer value that specifies the maximum length of a qualifier name in the data source If there is no maximum length or the length is unknown this value is set to 0 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 u
21. Syntax RETCODE SOQLFreeStmt hstmt fOption The SQLFreeStmt function accepts the following arguments 13 154 INFORMIX CLI Programmer s Manual Type Argument HSTMT hstmt UWORD fOption Return Codes Use Input Input SQLFreeStmt Description Statement handle One of the following options SQL_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 terminates 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 SQLBindPa rameter for the given hstmt SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 155 SQL FreeStmt SQLSTATE 01000 S1000 S1001 S1010 S1092 Diagnostics Error General warning General error Memory allocation failure Function sequence error Option type out of range 13 156 INFORMIX CLI Programmer s Manual When SQLFreeStmt returns SQL_SUCCESS_WITH_INFO or SQL_ER
22. Translation Shared Library Function Reference 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 12 10 INFORMIX CLI Programmer s Manual INFORMIX CLI Function Reference Arguments INFORMIX CLI Include Files Diagnostics Tables and Views Catalog Functions Search Pattern Arguments SQLAlIlocConnect SQLAIlocEnv SQLAllocStmt SQLBindCol SQLBindParameter SQLBrowseConnect SOLCancel SQOLColAttributes SQLColumnPrivileges SOQLColumns SOQLConnect SQLDataSources SQLDescribeCol Related Functions SQLDisconnect SQLDriverConnect SOQLDrivers SQLError SQLExecDirect SOLExecute 13 6 13 9 13 9 13 9 13 10 13 10 13 11 13 14 13 16 13 18 13 25 13 40 13 51 13 54 13 62 13 68 13 77 13 83 13 87 13 92 13 92 13 95 13 106 13 110 13 113 13 122 SQLExtendedFetch 2 ee ee 13 129 SQLFetch 2 a aa ee ee ew 2 13 146 SQLFreeConnect 2 2 ee eee ee ee 13 152 SQLFreeEnv 1 ee eee eee eee 13 154 SQLFreeStmt 2 2 eee eee ee a 13 156 SQLGetConnectOption a 2 2 a we 13 160 SQLGetCursorName ee ee 13 163 SQLGetData 2 ee ee ee 13 166 SQLGetFunctions ee ee ee 13 176 SQLGetInfo 2 2 eee 13 183 S
23. 2 28 i Figure 2 13 INFORMIX t OBEN Server Options The INFORMIX Server Options Service Name OK Dialog Box Server Name Cancel Protocol Type v Help 9 Click OK to accept any changes you make and return to the Logon to Informix dialog box 10 Click OK to complete the logon and to update these values in ODBC INI Once the connection information is verified your application can use the INFORMIX CLI driver to access the information that the data source contains Using a Connection String to Connect to a Data Source Some applications require that you connect to a data source by typing a connection string The connection string includes several attributes that specify how a driver connects to a data source for a particular session An attribute identifies a specific piece of information that the driver needs to know before it can make the appropriate data source connection A connection string has the following format DSN data_source_name attribute valueL attribute value You must specify data_source_name however all other attributes are optional If you do not specify an attribute it defaults to the one that is specified in the Data Source Specification section for the data source specified in the connection string of your ODBC INI file in Windows 3 1 or your Registry in Windows NT and Windows 95 INFORMIX CLI Programmer s Manual Using a Connection Str
24. Data value is a valid ODBC timestamp literal time portion is zero Data value is a valid ODBC timestamp literal time portion is non zero Data value is not a valid ODBC date literal or ODBC timestamp literal Data value is a valid ODBC timestamp literal fractional seconds portion not truncated Data value is a valid ODBC timestamp literal fractional seconds portion truncated Data value is a valid ODBC date literal 4 Data value is a valid ODBC time literal Data value is not a valid ODBC date literal ODBC time literal or ODBC timestamp literal a 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 e The date portion of the time stamp is set to the current date SQLSTATE Data value is a valid ODBC date literal N A N A 01004 22008 N A 01004 N A N A 22008 2 of 2 When character C data is converted to date or time stamp SQL data leading and trailing blanks are ignored C to SQL Numeric 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 a binary 00000001 and FF is converted to a binary 11111111 The dri
25. INFORMIX CLI Programmer s Manual Version 2 5 August 1996 Part No 000 8984 Published by INFORMIX Press Informix Software Inc 4100 Bohannon Drive Menlo Park CA 94025 Copyright 1981 1996 by Informix Software Inc or their subsidiaries provided that portions may be copyrighted by third parties as set forth in documentation All rights reserved 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 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 FTP Software PC TCP Information Builders Inc API SQL EDA SQL Enterprise Data Access Enterprise Data Access SQL Microsoft Corporation Microsoft MS DOS MS Windows Windows Windows NT Windows 95 Windows for Workgroups ODBC Sun Microsystems Inc Solaris X Open Company Ltd UNIX X Open All other marks or symbols are registered trademarks or trademarks of their respective owners Portions of this software product include or were based on INTERSOLV DataDirect ODBC Drivers a product of INTERSOLY Inc Portions copyright INTERSOLY Inc 1995 DataDirect is a trademark of INTERSOLY Inc 9
26. The SQLPutData function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle PTR rgbValue Input Pointer to storage for the actual data for the parameter or column The data must use the C data type specified in the fCType argument of SQLBindParameter for parameter data or SQLBindCol for column data SDWORD cbValue Input Length of rgb Value 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 SQL_DEFAULT_PARAM the C data type specified in SQLBindParameter or SOLBindCol is SQL_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 SQL_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 infor mation see Converting Data from C to SQL Data Types on page C 24 INFORMIX CLI Function Reference 13 263 SQL PutData Return Codes Diagnostics SQLSTATE Error 01000 General warning SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE When SQLPutData returns SOL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtai
27. To determine the level of outer joins that a data source supports an appli cation calls SQLGetInfo with the SQL_OUTER_JOINS flag Data sources can support two table outer joins partially support multitable outer joins fully support multitable outer joins or not support outer joins Procedures An application can call a procedure in place of an SQL statement The escape clause that ODBC uses for calling a procedure is as follows vendor Microsoft product ODBC call procedure name Lparameter parameter In the example procedure name specifies the name of a procedure stored on the data source and parameter specifies a procedure parameter A procedure can have zero or more parameters and can return a value The shorthand syntax for procedure invocation is as follows call procedure name Lparameter l parameter Executing SQL Statements 6 17 Using ODBC Extensions to SQL 6 18 For output parameters parameter must be a parameter marker For input and input output parameters parameter can be a literal a parameter marker or not specified If parameter is a literal or is not specified for an input output parameter the driver discards the output value If parameter is not specified for an input or input output parameter the procedure uses the default value of the parameter as the input value the procedure also uses the default value if parameter is a parameter marker and the pcbValue argume
28. m Understanding the New SQL A Complete Guide by J Melton and A Simon Morgan Kaufmann Publishers 1993 m Using SQL by J Groff and P Weinberg Osborne McGraw Hill 1990 Compliance with Industry Standards INFORMIX CLI is based on the Microsoft Open Database Connectivity ODBC Specification which in turn is based on the X Open and SQL Access Group 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 let us know what you like or dislike about our manuals To help us with future versions of our manuals please tell us about any corrections or clarifications that you would find useful Please 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 Introduction 15 Informix Welcomes Your Comments If you prefer to send electronic mail our address is doc informix com Or send a facsimile to the Informix Technical Publications Department at 415 926 6571 We appreciate your feedback 16 INFORMIX CLI Programmer s Manual Overview of INFORMIX CLI What Is INFORMIX CLI Advantages of Using INFORMIX CLI Over
29. 3 5 3 5 3 6 3 7 3 8 3 2 INFORMIX CLI Programmer s Manual his chapter describes the general characteristics of INFORMIX CLI functions determining driver conformance levels the role of the driver manager passing function arguments to a driver and the values that functions return Each 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 C programs that call INFORMIX CLI functions must include the sql h and sqlext h header files These files define INFORMIX CLI constants and types and provide function prototypes for all INFORMIX CLI functions Determining INFORMIX CLI Conformance Levels ODBC defines conformance levels for drivers in two areas the ODBC API and the ODBC SQL grammar which includes the ODBC SQL data types These levels establish standard sets of functionality By verifying the conformance levels supported by a driver an application can determine if the driver provides the necessary functionality To determine the function conformance level of a driver an application calls SQLGetInfo with the SQL_ODBC_SAG_CLICONFORMANCE and SQL_ODBC_API_CONFORMANCE flags To determine the SQL conformance level of a driver an application calls SQLGetInfo with the SQL_ODBC_SQL_CONFORMANCE flag To determine whether a driver supports a specific SQL extension an application calls SQLGetInfo wit
30. Add Options System DSN Drivers 2 Click Add The Add Data Source dialog box appears Figure 2 5 illustrates Figure 2 5 The Add Data Source Dialog Box Select which ODBC driver you want to use from the list then click OK P Se a INFORMIX CLI 2 21 Adding a Data Source 3 Select the Informix driver from the Installed ODBC Drivers list 4 Click Add The ODBC INFORMIX Driver Setup dialog box appears as Figure 2 6 illustrates y Figure 2 6 ODBC INFORMIX 7 2 Driver Setup The ODBC INFORMIX Driver Setup Dialog Box In the Data Source Name text box enter the name of the data source you want to access You define the data source name that is it can be any name that you choose 5 Inthe Description text box type a long description of your data source This section is optional 6 Inthe Database Name text box enter the name of the database to which you want to connect by default You now have entered enough information to be able to connect to the data source a To enter the data source click OK The Data Sources dialog box appears as Figure 2 4 illustrates You can then click Add to add another data source or click Close to exit the Data Sources dialog box a To add optional connection information about the data source click Advanced The ODBC INFORMIX 7 2 Advanced Driver Setup Window appears as Figure 2 7 illustrates 2 22 INFORMIX CLI Programmer s Manual ODBC INFORM
31. Declarative statements D 5 Default data source specification 1 10 DELETE statements 4 INFORMIX CLI Programmer s Manual See also SQLSetPos affected rows 13 272 qualifier usage in 13 207 Deletes positioned See Positioned delete statements Deleting cursors 13 194 Delimiter character SQL identifiers 13 207 Deprecated functions 13 287 Descriptors columns 13 57 13 91 Diagnostic statements D 10 Dialog boxes disabling 13 280 SQLDriverConnect 13 102 13 104 Dirty reads 13 196 Display size 13 58 C 12 DML See Data Manipulation Language Documentation notes Intro 14 Driver keyword 13 101 version compatibility 13 47 Driver manager allocating handles 13 14 described 3 4 errors 8 5 8 7 functions supported 13 179 listing drivers 13 109 loading drivers 13 80 ODBC version supported 13 205 SQLBrowseConnect 13 47 SQLConnect 13 80 SQLDriverConnect 13 102 SQLError 13 112 SQLSTATE values 13 9 tracing 13 155 13 279 transactions 13 329 unloading drivers 13 81 Driver path attribute for driver UNIX 2 9 Driver setup shared library function summary 12 10 Drivers allocating handles 13 14 errors 8 3 file usage 13 198 functions supported 13 179 information types 13 188 Informix UNIX to 1 16 INFORMIX CLI UNIX 2 3 INFORMIX CLI Windows 2 15 keywords 13 109 listing installed 13 109 loading 13 80 SQLError 13 112 SQLSTATE values 13 9 DROP INDEX statements 13 312 DSN attribute for Informix driver UNIX 2 14 2 29 DSN
32. Passing Parameter Values on page 13 34 Related Functions For information about Canceling statement processing Executing an SQL statement Executing a prepared SQL statement Sending parameter data at execution time Assigning storage for a parameter SQLParamOptions SQLParamOptions See SQLCancel SQLExecDirect SQLExecute SQLPutData SQLBindParameter SQLParamOptions allows an application to specify multiple values for the set of parameters assigned by SQLBindParameter The ability to specify multiple values for a set of parameters is useful for bulk inserts and other work that requires the data source to process the same SQL statement multiple times with various parameter values For example an application can specify three sets of values for the set of parameters associated with an INSERT statement and then execute the INSERT statement once to perform the three insert operations Syntax RETCODE SQLParamOptions hstmt crow pirow INFORMIX CLI Function Reference 13 239 SQL ParamOptions 13 240 Type Argument Use HSTMT hstmt Input UDWORD crow Input UDWORD pirow Input FAR Return Codes SQL_INVALID_HANDLE INFORMIX CLI Programmer s Manual The SQLParamOptions function accepts the following arguments Description Statement handle Number of values for each parameter If crow is greater than 1 the rgbValue argument in SOLBindParameter points to an array of parameter values and pcbVal
33. 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 SiQL_FN_NUM_ROUND SQL_FN_NUM_SIGN SQL_FN_NUM_SIN SQL_FN_NUM_SORT SQL_FN_NUM_TAN SQL_FN_NUM_TRUNCATE SQL_ODBC_API_CONFORMANCE A 16 bit integer value that indicates the level of ODBC conformance SQL_OAC_NONE None SQL_OAC_LEVEL1 Level 1 supported SQL_OAC_LEVEL2 Level 2 supported For a list of functions and conformance levels see Chapter 12 Function Summary 13 of 22 13 202 INFORMIX CLI Programmer s Manual SQLGetInfo InfoType Returns SQL_ODBC_SAG_CLI_CONFORMANCE A 16 bit integer value that indicates compliance to the functions of the SAG specification SQL_OSCC_NOT_COMPLIANT Not SAG compliant one or more core functions are not supported SQL_OSCC_COMPLIANT SAG compliant SQL_ODBC_SQL_CONFORMANCE A 16 bit integer value that indicates SQL grammar supported by the driver SQL_OSC_MINIMUM Minimum grammar supported SQL_OSC_CORE Core grammar supported SQL_OSC_EXTENDED Extended grammar supported SQL_ODBC_SQL_OPT_IEF A character string Y if the data source supports the optional Integrity Enhancement Facility N if it does not SQL_ODBC_VER A character string with the version of ODBC to which the driver manager conforms The version is of the form where the first two digits are the major version and the next two digits are the minor
34. 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 9 of 22 13 198 INFORMIX CLI Programmer s Manual InfoType SQL_KEYWORDS SQL_LIKE_ESCAPE_CLAUSE SQL_MAX_BINARY_LITERAL_LEN SQL_MAX_CHAR_LITERAL_LEN SQL_MAX_COLUMN_NAME_LEN SQL_MAX_COLUMNS_IN_GROUP_BY SQL_MAX_COLUMNS_IN_INDEX SQL_MAX_COLUMNS_IN_ORDER_BY 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 For a list of ODBC keywords see List of Reserved Keywords on page B 21 The define value SQL_ODBC_KEYWORDS contains a comma separated list of ODBC keywords A character string 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 predicate escape character N otherwise A 32 bit integer value that specifies the maximum length number of hexadecimal characters excluding the literal prefix and
35. System Requirements GLS System Requirements Depending on your Informix database configuration you must have a compatible Informix database server installed on your system or network The following list shows examples of compatible database servers m INFORMIX OnLine Version 5 x m INFORMIX OnLine Dynamic Server Version 7 x m INFORMIX SE Version 5x 7 x For information on these products refer to your Informix documentation set For a complete listing of compatible database servers see the release notes for INFORMIX CLI To take advantage of the GLS feature you must have an Informix database server of Version 7 2 or greater For more information see the Guide to GLS Functionality Setting Environment Variables Set the INFORMIXDIR environment variable to the full path of the directory where your Informix product is installed The INFORMIXSERVER environment variable must specify the default database server for the user This value must correspond to a valid dbservername entry in the sqlhosts file The UNIX environment variable PATH indicates the directories that are searched for executable programs Your PATH setting must include the path to your INFORMIXDIR bin directory In the C shell you can set these variables using the setenv command at the command line or in your login or cshrc files In the Bourne or Korn shells you can set this variable using the export command at the command line or in your login or prof
36. UPDATE EMP SET ADDRESS WHERE first_name and last_name and ssn and address and city and state and zip SQL_NTS fairly complex query INFORMIX CLI Programmer s Manual Use SQLSpecialColumns to Determine the Optimal Set of Columns Applications should call SQLSpecialColumns SQL_BEST_ROWID to retrieve the optimal set of columns possibly a pseudo column that identifies any given record Many databases support special columns that are not explicitly defined by the user in the table definition but are hidden columns of every table for example ROWID TID and so on These pseudo columns almost always provide the fastest access to the data because they typically are pointers to the exact location of the record Because pseudo columns are not part of the explicit table definition they are not returned from SQLColumns The only method of determining if pseudo columns exist is to call SQLSpecialColumns Consider the previous example again 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 pseudo columns the result set of SQLSpecialColumns consists of
37. d Data value is not a valid date value or timestamp value gt Data value is a valid time value Data value is a valid timestamp value fractional seconds portion is zero Data value is a valid timestamp value fractional seconds portion is non zero f Data value is not a valid time value or timestamp value Data value is a valid timestamp value fractional seconds portion not truncated Data value is a valid timestamp value fractional seconds portion truncated Data value is a valid date value Data value is a valid time value Data value is not a valid date value time value or timestamp value P The value of cb ValueMax is ignored for this conversion size of the C data type 2 of 3 rgbValue Data Data Truncated data Untouched Data Data Truncated data Untouched Data Truncated data Data Data Untouched SQL to C Character pebValue 6 Cc 6 6 Untouched 6 6 Untouched 16 16 16 16 Untouched SQLSTATE N A N A 01004 22008 N A N A 01004 22008 N A N A N A N A 22008 The driver assumes that the size of rgbValue is the Data Types C 17 SQL to C Numeric fCType Test rgbValue pebValue SQLSTATE This is the size of the corresponding C data type 4 The time portion of timestamp value is truncated e The date portion of timestamp value is ignored f The
38. executed and produce a result set rc SQLBindCol re 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 prepare dummy query rc SQLPrepare SELECT from UnknownTable WHERE 1 0 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 Designing Performance Oriented Applications 11 7 Retrieving Data In both cases a query is sent to the server but in Case 1 the query must be evaluated and form a result set that must be sent to the client Clearly Case 2 is the better performing model Retrieving Data Limit the amount of data retrieved and reduce the call load to increase the performance of an application Retrieving Long Data Retrieving long data SQL_LONGVARCHAR and SQL_LONGVARBINARY data across the network is resource intensive and thus slow Applications should avoid requesting long data unless it is absolutely necessary If the user does wish to see these result items then the application can requery the database sp
39. list of 12 3 return codes 8 3 SQL statement equivalents D 1 D 5 D 6 D 7 D 8 D 9 D 10 supported 13 179 See also specific function G Global Language Support GLS Intro 7 2 4 2 15 GLOBAL TEMPORARY table type 13 325 Global transactions 13 329 Grammar SQL B 11 Granting privileges 13 66 13 318 GROUP BY clauses 13 200 13 201 H h files 3 3 Handles connection See Connection handles defined 3 7 error queues 13 112 library 13 197 SQLAlIlocConnect 13 13 SQLAIlocEnv 13 15 SQLAIlocStmt 13 17 SQLFreeConnect 13 152 SQLFreeEnv 13 154 SQLFreeStmt 13 159 statement See Statement handles Hashed indexes 13 312 Header files required 3 3 sqlext h C data types 3 8 contents 13 9 sql h contents 13 9 SQL data type C 2 henv See Environment handles Hexadecimal characters C 20 C 29 C 31 Holes in cursors 7 11 13 210 Icons compliance Intro 10 Identifiers quoted case sensitive 13 208 IEF See Integrity enhancement facility Indexes cardinality 13 313 clustered 13 312 collating 13 312 filtered 13 313 hashed indexes 13 312 listing 13 310 maximum columns in 13 201 maximum length 13 202 pages 13 313 qualifier usage in 13 207 sorting 13 312 unique 13 312 See also SQLStatistics Information status retrieving 8 4 INFORMIX 5 driver isolation level 1 16 lock level 1 16 INFORMIX 7 driver isolation level 1 16 lock level 1 16 INFORMIX driver API conformance 1 12 data types 1 15 Isolation and lock le
40. 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 ay ES 7 SQL_NTS SQL_SUCCESS UT SQL_C_SLONG SQL_INTEGER UT SQL_C_CHAR SQL_VARCHAR EXEC SQL DECLARE cl CURSOR FOR SELECT ID NAME FROM NAMEID EXEC Show Exec SQL OPEN cl Ej the use of the SQLExecDirect method 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 imame ONG amp id O SQL_SUCCESS a xi NULL AR name SDWORD sizeof name amp namelen Constructing an INFORMIX CLI Application 10 5 Static SQL Example 10 6 SQLTransact hdbc SQL_COMMIT IE EXEC SQL CLOSE els XI Free the statement handle SQLFreeStmt hstmt SQL_DROP EXEC SQL DISCONNECT Disconnect from the data source Free the connection handle Free
41. or by using the SQL_AUTOCOMMIT connection option can cause the data source to delete the access plans for all hstmts on an hdbc For more information see SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR on page 13 192 Code Example See SOLBindParameter SQLParamOptions and SQLPutData INFORMIX CLI Function Reference 13 249 SQL Prepare 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 affected by a statement Setting a cursor name Assigning storage for a parameter Executing a commit or rollback operation 13 250 INFORMIX CLI Programmer s Manual See SQLAIlocStmt SQLBindCol SQLCancel SQLExecDirect SQLExecute SQLRowCount SQLSetCursorName SQLBindParameter 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 in a 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
42. then truncation occurs The driver must determine whether the truncation is acceptable If truncation does not occur the SOLDriver ToDataSource returned FALSE due to another error In either case a specific error message is returned in szErrorMsg Related Functions For information about See Translating data returned from the data source SQLDataSourceToDriver Returning the setting of a connection option SQLGetConnectOption Setting a connection option SQLSetConnectOption INFORMIX CLI Programmer s Manual INFORMIX CLI Error Codes SQLError returns SQLSTATE values as defined by the X Open and SQL Access Group SQL CAE specification 1992 SOLSTATE values are strings that contain five characters The following table lists SOLSTATE values that the Informix driver can return for SQLError 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 SQL_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 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 The assignment of class and subclass values is defined by ANSI S
43. to return all of the requested information so the information was truncated The argument pebInfoValue 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 information types reserved by ODBC only SQL_ODBC_VER can be returned without an open connection Returning the requested information would have caused a loss of numeric or binary significance 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 1 of 2 INFORMIX CLI Function Reference 13 183 SQL Getinfo 13 184 SQLSTATE Error S1009 Invalid argument value S1090 Invalid string or buffer length S1096 Information type out of range S1C00 Driver not capable S1T00 Time out expired Usage A 16 bit integer value A 32 bit bitmask A 32 bit integer value A 32 bit binary value INFORMIX CLI Programmer s Manual Description DM The fInfoType was SQL_DRIVER_HSTMT and the value pointed to by rgbInfoValue was not a valid statement handle DM The value specified for argument cbInfo ValueMax was less than 0 DM The value specified for the argu
44. which might be specific to that data source The Informix driver maps data source specific SQL data types to ODBC SQL data types The driver returns these mappings through SQLGetTypelInfo It also returns the SQL data types when describing the data types of columns and parameters in SOLColAttributes SQLColumns SQLDescribeCol and SQLSpecialColumns Each ODBC SQL data type corresponds to an ODBC C data type By default the Informix 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 application can specify the correct C data type with the fCType argument in SQLGetData or in SOLBindParameter Before returning data from the data source the Informix driver converts it to the specified C data type before sending data to the data source the Informix driver converts it from the specified C data type This appendix discusses the following topics ODBC SQL data types that INFORMIX CLI supports ODBC C data types Default ODBC C data types Transferring data in its binary form Precision scale length and display size of SQL data types Converting data from SQL to C data types Converting data from C to SQL data types ODBC SQL Data Types That INFORMIX CLI Supports ODBC SQL Data Types That INFORMIX CLI Supports The following table lists valid values of fSqlTyp
45. 13 174 truncating data 13 150 13 174 unbound columns 7 7 Return codes 8 3 Return values procedure 13 31 ROLLBACK SQLExecDirect 13 120 ROLLBACK statements cursor behavior 13 194 interoperability 6 9 13 120 13 127 SQLExecute 13 127 SQLPrepare 13 250 Rolling back transactions 6 9 13 329 Row status array errors 13 138 SQLExtendedFetch 13 141 Row versioning isolation level 13 196 ROWID 13 303 13 305 Rows affected 13 272 after last row 13 140 deleting 7 13 errors in 13 138 interoperability 7 4 maximum 13 294 maximum length 13 202 SQLExtendedFetch 13 141 updating 7 13 See also Cursors See also Retrieving data See also Rowsets Rowsets allocating 7 8 binding 7 7 binding type 13 291 cursor position 13 136 errors in 13 138 retrieving 7 9 size 13 295 SQLExtendedFetch 13 133 status 13 141 S SAG CLI compliance 13 205 Scalar functions information types 13 192 supported by INFORMIX CLI driver 1 14 syntax 6 14 TIMESTAMPADD intervals 13 211 TIMESTAMPDIFEF intervals 13 211 Scale columns result sets 13 89 tables 13 73 13 305 data types 13 225 defined C 10 Scope rowid 13 306 Scrollable cursors 7 10 Search patterns 13 10 Searchability columns 13 60 data types 13 224 Segment boundaries 3 5 SELECT FOR UPDATE statements 7 14 13 206 Select list maximum columns in 13 202 ORDER BY columns in 13 205 SELECT statements affected rows 13 272 bulk 13 241 cursor name 13 162 13 285 maximum tables in 13
46. 13 19 SQLBindParameter 13 31 SQLGetData 13 167 TIMESTAMPADD intervals 13 211 TIMESTAMPDIFF intervals 13 211 Trace file 1 10 13 279 Trace keyword SQLAIlocEnv 13 15 TraceAutoStop definition of 1 11 TraceFile definition of 1 10 Trace definition of 1 10 Tracing SQLAIlocEnv 13 15 SQLFreeEnv 13 155 SQLSetConnectOption 13 279 Traffic network maximum data length 13 293 packet size 13 279 prepared statements 6 6 Transactions beginning 6 9 13 330 commit mode 6 9 13 278 committing 6 9 13 329 concurrency See Concurrency cursor behavior 13 330 incomplete 13 94 interoperability 6 9 isolation levels 13 196 multiple active 13 203 ODBC function equivalents D 8 rolling back 6 9 13 329 serializability 7 12 SQLExecDirect 13 120 SQLExecute 13 127 SQLTransact 13 329 support of 13 212 two phase commit 13 329 Transferring binary data C 8 Transitions state See State transitions Translation options default 14 7 described 13 282 specifying 13 280 SQLDriverConnect 13 105 Translation setup shared library ConfigTranslator 14 3 See also Translation shared libraries Translation shared libraries character sets 5 9 default 13 105 default option 14 7 described 5 9 13 282 function summary 12 10 setup shared library See Translation setup shared library specifying 13 280 SQLDataSourceToDriver 15 6 SQLDriverConnect 13 105 SQLDriverToDataSource 15 10 truncating data 15 6 15 10 See also Converting data See also odbcinst ini Tr
47. 13 213 SQL GetStmtOption SQLSTATE 01000 24000 S1000 S1001 S1010 S1011 Diagnostics Error General warning Invalid cursor state General error Memory allocation failure Function sequence error Operation invalid at this time 13 214 INFORMIX CLI Programmer s Manual When SQLGetStmtOption returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLGetStmtOption 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 SQLSTATE value is SQL_ERROR unless noted otherwise Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The argument fOption was SQL_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 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 DM SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA This function was
48. 13 241 13 246 13 253 13 257 13 265 13 272 13 274 13 283 13 287 13 288 13 297 13 307 13 315 13 321 13 327 listing drivers 5 7 SQLDriverToDataSource 15 7 SQLError driver manager 13 112 function description 13 110 See also Errors See also SQLSTATEs SQLExecDirect function description 13 113 SQLExecute function description 13 122 with SQLPrepare 13 127 SQLExtendedFetch code examples 13 142 function description 13 129 retrieving rowsets 7 9 with SQLGetData 7 9 with SQLSetPos 13 136 with SQLSetStmtOption 13 133 SQLFetch fetching data 7 5 function description 13 146 positioning cursor 7 6 with SQLBindCol 13 150 with SQLGetData 13 150 SQLFreeConnect freeing connection handles 9 4 function description 13 152 with SQLDisconnect 13 153 with SQLFreeEnv 13 155 SQLFreeEnv freeing environment handles 9 4 function description 13 154 with SQLFreeConnect 13 155 SQLFreeStmt closing cursors 7 6 13 156 freeing statement handles 9 3 13 159 function description 13 156 unbinding columns 9 3 13 23 13 156 unbinding parameters 6 8 13 30 13 156 SQLGetConnectOption 13 160 SQLGetCursorName 13 163 SQLGetData code example 13 175 function description 13 166 interoperability 7 7 7 9 long data values 7 7 13 22 unbound columns 7 7 with SQLExtendedFetch 7 9 with SQLFetch 13 150 SQLGetFunctions code example 13 181 function description 13 176 SQLGetInfo code example 13 213 data sources 13 189 DBMSs 13 188 drivers 13 188 fu
49. 13 278 SQLTransact 13 329 See also Transactions Batch statements processing 13 229 syntax B 11 Binary data converting to C C 20 converting to SQL C 31 literal length 13 201 null termination byte 13 35 retrieving in parts 13 167 13 174 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 transferring C 8 Binary large object blob See SQLGetData Binding columns binding type 13 291 code examples 13 142 column attributes 7 4 column wise 7 8 13 134 null pointers 13 23 row wise 7 8 13 135 single row 7 4 SQLBindCol 13 22 unbinding 13 23 13 156 See also Converting data See also Rowsets Binding parameters See Parameters binding Bit data converting to SQL C 31 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 Blob binary large object See SQLGetData Block cursors 7 9 Bookmarks SQLExtendedFetch 13 140 Boundaries segment 3 5 Braces 13 46 13 101 Browse request connection string 13 45 Browse result connection string 13 45 Buffers allocating 3 5 input 3 5 interoperability 3 5 maintaining pointers 3 5 NULL data 3 6 null pointers 3 6 null termination 3 6 output 3 6 segment boundaries 3 5 truncating data 3 7 See also NULL data See also Null termination byte Bulk operations 13 241 C C data types conversion examples C 23 C 36 converting from SQL data types C 13 converting to SQL data types C 24 defaults C 6 defined C 4 2 I
50. 13 287 See also Arguments Patterns search patterns 13 10 Percent sign 13 10 13 324 Phantoms 13 196 Plans access 6 6 Platform icons Intro 10 Pointers maintaining 3 5 Pointers null See Null pointers Positioned DELETE statements cursor name 13 165 13 285 cursor position 13 136 executing 7 13 support of 13 206 version compatibility 7 14 Positioned UPDATE statements cursor name 13 165 13 285 cursor position 13 136 executing 7 13 support of 13 206 version compatibility 7 14 Position cursor See Cursor position Precision columns result sets 13 60 13 89 tables 13 73 13 304 data types 13 222 defined C 9 Prepared statements deleting 13 194 Preparing statements 6 6 13 250 Preserving cursors 13 194 Primary keys 13 255 Privileges data source 13 194 grantable 13 67 13 319 grantee 13 66 13 318 grantor 13 66 13 318 qualifier usage in 13 207 table user granting 13 66 Procedure columns parameters 13 30 Procedures defined 13 257 interoperability 6 17 name 13 261 name maximum length 13 202 ODBC syntax 6 17 owner name 13 261 qualifier 13 261 qualifier usage in 13 207 return values 13 31 See also Procedure columns 13 261 support of 13 206 term vendor specific 13 206 Pseudo columns 13 305 Q Qualifiers current 13 278 index 13 312 maximum length 13 202 primary key 13 255 procedure 13 261 separator 13 207 table 13 60 13 66 13 72 13 311 13 324 term vendor specific 13 207 usag
51. 13 297 SQLSTATE guidelines 8 3 naming conventions 13 9 values A 1 values See also specific function description SQLStatistics 6 10 13 307 SQLTablePrivileges 13 315 SQLTables argument syntax 13 324 catalog 6 9 formatting 13 324 function description 13 321 SQLTransact commit mode 13 278 committing 6 9 function description 13 327 rolling back 6 9 two phase commit 13 329 with SQLSetConnectOption 13 278 SQLWriteDSNToIni 14 6 SQLWritePrivateProfileString 14 6 sql log file 1 11 12 INFORMIX CLI Programmer s Manual SQL_ERROR 8 3 SQL_INVALID_HANDLE 8 3 SQL_NEED_DATA 8 3 SQL_NO_DATA_FOUND 8 3 SQL_STILL_EXECUTING 8 3 SQL_SUCCESS 8 3 SQL_SUCCESS_WITH_INFO 8 3 Statement handles allocating 6 5 defined 3 7 driver 13 197 freeing 9 3 13 290 overwriting 13 18 SQLAIlocStmt 13 17 SQLFreeStmt 13 159 SQLMoreResults 13 229 with threads 13 18 See also Handles Statement options binding type 13 291 concurrency 7 12 7 13 cursor type 13 293 driver specific 13 291 maximum data length 13 293 maximum length 13 217 13 291 maximum rows 13 294 releasing 13 290 reserved 13 291 retrieving 13 217 retrieving data 13 295 setting 13 290 substituting values 13 291 Static cursors described 7 10 sensitivity 13 210 Static SQL 10 4 Statistics listing 13 310 Status array errors 13 138 SQLExtendedFetch 13 141 Status information retrieving 8 4 See also Errors String data See Character data String functions supported by I
52. 15 SQLBrowseConnect 13 47 SQLFreeEnv 13 155 SQLSetConnectOption 13 279 Index 7 Setup shared library functions using ConfigDSN 14 6 structure 1 6 odbc ini UNIX data source specification section 1 9 default data source specification section 1 10 file example 1 12 file format 1 8 for driver 2 10 modifying 2 6 ODBC data sources section 1 8 ODBC options section 1 10 ODBC INI Windows data source specification section 1 9 default data source specification section 1 10 definition of 1 7 1 10 file example 1 11 file format 1 8 ODBC data sources section 1 8 ODBC options section 1 10 Optimistic concurrency control See Concurrency ORDER BY clauses columns in select list 13 205 expressions in 13 197 maximum columns in 13 201 Outer joins described 6 16 support of 13 205 Output buffers 3 6 Output parameters 13 31 Owner names procedure 13 261 table 13 318 13 324 SQLColAttributes 13 59 SQLColumnPrivileges 13 66 SQLColumns 13 72 term vendor specific 13 206 P Packet size 13 279 Pages index or table 13 313 Parameters 8 INFORMIX CLI Programmer s Manual arrays 13 34 13 241 binding 6 8 13 30 data types B 2 data at execution 6 10 13 30 13 33 13 35 13 36 default 13 31 input 13 30 input output 13 31 interoperability 6 17 long data values 6 10 markers 6 18 B 3 number of 13 233 output 13 31 preparing 13 250 procedure 6 18 13 30 return values 6 17 unbinding 6 8 13 156 values 6 7 version compatibility
53. 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 14 4 INFORMIX CLI Programmer s 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 0DATABASE Personnel O 0 For more information about these keywords see SQLDriverConnect on page 13 93 and Adding and Modifying Data Sources on page 2 6 In order to display a dialog box hwndParent must 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 lpszAttributes 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 th
54. 38 INFORMIX CLI Programmer s Manual SQLBrowseConnect The SQLBrowseConnect function accepts the following arguments Type HDBC UCHAR FAR SWORD UCHAR FAR SWORD SWORD FAR Return Codes Argument hdbc szConnStrIn cbConnStrIn szConnStrOut cbConnStrOutMax pebConnStrOut Use Input Input Input Output Input Output Description Connection handle Browse request connection string See szConnStrIn Argument on page 13 43 Length of szConnStrIn Pointer to storage for the browse result connection string See szConnStrOut Argument on page 13 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 cbConnStrOutMax 1 bytes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NEED_DATA SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 39 SQL BrowseConnect 13 40 INFORMIX CLI Programmer s Manual When SQLBrowseConnect returns SQL_ERROR SQL_SUCCESS_WITH_INFO or SQL_NEED_DATA an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLBrowseConnect and explains each value in the context of this function the notation DM preced
55. 7 13 Modifying Result Set Data with Positioned Update and Delete Statements 7 14 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 the driver executes a SELECT statement the driver generates a cursor name To retrieve the cursor name for an hstmt an application calls SQLGetCursorName 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 if a data source supports positioned update and delete statements an application calls SQLGetInfo with the SQL_POSITIONED_STATEMENTS option In ODBC 1 0 positioned update positioned delete and SELECT FOR UPDATE statements were part of the core SQL grammar In ODBC 2 x positioned update positioned delete and SELECT FOR UPDATE statements are part of the extended grammar Applications that use the SQL conformance level to determine whether these statements are supported also need to check the ve
56. Data Source ee to a Data Source Using Dialog Boxes to Connect to a 1 Data Source Using a Connection String to Connect to a Data Source Guidelines for Calling INFORMIX CLI Functions Determining INFORMIX CLI Conformance Levels Using the Driver Manager Calling Functions Buffers P Environment Connection aid Statement Handles Using Data Types Function Return Codes Basic Application Steps How an Application Uses the INFORMIX CLI Interface INFORMIX CLI Programmer s Manual 1 15 1 16 23 23 2 4 2 4 2 6 2 6 2 10 2 11 2 11 2 11 2 13 2 15 2 15 2 15 2 16 2 16 2 16 2 24 2 26 2 26 2 28 3 4 3 5 3 5 3 8 3 8 4 3 Chapter 5 Chapter 6 Chapter 7 Connecting to a Data Source Description of Data Sources Initializing the Environment Allocating a Connection Handle Connecting to a Data Source Connecting with SQLConnect Connecting to a Data Source with SQLDriverConnect Connection Browsing with SQLBrowseConnect Translating Data Related Functions Executing SQL Statements 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 Using ODBC Extensions to SQL Related Functions es Retrieving Results Assigning Storage for Results Binding
57. Environment handle UWORD fDirection Input Determines whether the driver manager 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 ter mination 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 INFORMIX CLI Function Reference 13 81 SQLDataSources Type UCHAR FAR SWORD SWORD FAR 13 82 Return Codes Diagnostics INFORMIX CLI Programmer s Manual Argument szDescription cbDescriptionMax pcebDescription Use Output Input Output Description Pointer to storage for the description of the driver associated with the data source Maximum length of the szDescription buffer this buffer should be at least 255 bytes 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
58. Function Reference 13 299 SQL SpecialColumns 13 300 Usage SQLSpecialColumns is provided so that applications can provide their own custom scrollable cursor functionality similar to the functionality provided by SQLExtendedFetch and SQLSetStmtOption When the fColType argument is SQL_BEST_ROWID SQLSpecialColumns 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 SQLColumns does not necessarily return these columns If no columns uniquely identify each row in the table SOLSpecialColumns returns a rowset with no rows a subsequent call to SQLFetch or SQLExtendedFetch on the stmt returns SQL_NO_DATA_FOUND If the fColType fScope or fNullable arguments specify characteristics that are not supported by the data source SQLSpecialColumns returns a result set with no rows as opposed to the function returning SQL_ERROR with SQLSTATE S1C00 Driver not capable A subsequent call to SQLFetch or SQLExtendedFetch on the stmt returns SQL_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 INFORMIX CLI Programmer s Manual SQL SpecialColumns 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 SOLGetI
59. Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver link failure and 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 The driver was unable to allocate memory allocation failure required to support execution or completion of the function S1008 Operation The function was called but before it canceled completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application 1 of 2 INFORMIX CLI Function Reference 13 313 SQLTablePrivileges SQLSTATE 1010 S1090 S1C00 S1T00 Usage Error Function sequence error Invalid string or buffer length Driver not capable Time out expired 13 314 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 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 maxim
60. Guidelines The driver checks if the connection string passed to it by the driver manager contains the DSN or DRIVER keyword If the connection string contains the DRIVER keyword the driver cannot retrieve information about the data source from the odbc ini file 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 odbc ini file as follows 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 Function Reference 13 101 SQL DriverConnect 13 102 The driver uses any information that it retrieves from the odbc ini file to augment the information passed to it in the connection string If the infor mation in the odbc ini file 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 odbc ini file as initial values When the user exits the dia
61. INFORMIX CLI Programmer s Manual See Assigning storage for a column in a result set SOLBindCol SQLCancel SQLColumns SQLExtendedFetch SQLFetch SQLTablePrivileges SQLTables SQLColumns returns the list of column names in specified tables The driver returns this information as a result set on the specified hstmt RETCODE SQLColumns hstmt szTableQualifier cbTableQualifier szTableOwner cblableOwner szTableName cbTableName szColumnName cbColumnName SQLColumns The SQLColumns function accepts the following arguments Type Argument HSTMT hstmt UCHAR FAR szTableQualifier SWORD cbTableQualifier UCHAR FAR szTableOwner SWORD cbTableOwner UCHAR FAR szTableName SWORD cbTableName UCHAR FAR szColumnName SWORD cbColumnName Return Codes Use Input Input Input Input Input Input Input Input Input Description Statement handle Qualifier name 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 szTableQualifier 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 owners Length of szTableOwner String search pattern for table names Length of
62. If this value is set SELECT lists must not include long columns such as SQLLLONGVARCHAR or SQL_LONGVARBINARY Tip You can also add data sources when you install INFORMIX CLL In either case the steps that you follow are the same To add a data source 1 Edit your odbc ini file using a text editor such as vi If you do not have this file in your home directory copy the default odbc ini file from the INFORMIXDIR odbc directory and change the name to odbc ini 2 Under the ODBC Data Sources section add an entry for your data source Each entry in this section lists the data source and a description of the driver that the data source uses Use the following format for data source entries ODBC Data Sources data_source_name driver_description 2 8 INFORMIX CLI Programmer s Manual Adding a Data Source data_source_name identifies the data source that INFORMIX CLI accesses You choose the data source name driver_description describes the driver that the data source accesses This field is optional Set this field to Informix Driver For example to associate the stores7 data source with an INFORMIX CLI driver you might make the following entry in the Data Sources section of your odbc ini file ODBC Data Sources Stores7 Informix Driver 3 After the ODBC Data Sources section add an entry for each specified data source Each data source listed in the ODBC Data Sources section of your odbc ini file re
63. Option type out of range 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 1C00 13 274 Driver not capable INFORMIX CLI Programmer s Manual The driver or data source does not support the value specified for the argument fOption 2 of 2 SQL SetConnectOption When fOption is a statement option SOLSetConnectOption can return any SQLSTATE that is returned by SQLSetStmtOption Usage The currently defined options are shown in the following table Options from 0 to 999 are reserved by ODBC An application can call SQLSetConnectOption and include a statement option The driver sets the statement option for any hstmts associated with the specified hdbc and establishes the statement option as a default for any hstmts later allocated for that hdbc For a list of statement options see Usage on page 13 288 All connection and statement options that the application successfully sets for the hdbc persist until SQLFreeConnect is called for the hdbc 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 connects to a different
64. Positioned SQL conformance level Core ODBC 1 0 SQL conformance level Extended ODBC 2 0 UPDATE table name SET column identifier expression NULL column identifier expression NULL WHERE CURRENT OF cursor name UPDATE Statement Searched SQL conformance level Minimum UPDATE table name SET column identifier expression NULL column identifier expression NULL WHERE search condition Elements Used in SQL Statements The following elements are used in the SQL statements listed previously SQL Conformance Element Level all function AVG MAX MIN SUM expression Core approximate numeric literal mantissaEexponent Core approximate numeric type approximate numeric types Core For example DOUBLE PRECISION or REAL argument list expression expression argument list Minimum base table identifier user defined name Minimum base table name base table identifier Minimum 1 of 11 SQL Grammar B 11 Hements Used in SQL Statements B 12 INFORMIX CLI Programmer s Manual SQL Conformance Element Level base table name base table identifier Core owner name base table identifier qualifier name qualifier separator base table identifier qualifier name qualifier separator owner name base table identifier The third syntax is valid only if the data source does not support owners between predicate Core expression NOT BETWEEN expr
65. RETCODE SQLMoreResults hstmt The SOLMoreResults 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 INFORMIX CLI Function Reference 13 225 SQL MoreResults SQLSTATE 01000 S1000 S1001 S1008 S1010 S1T00 Diagnostics Error General warning General error Memory allocation failure Operation canceled Function sequence error Time out expired 13 226 INFORMIX CLI Programmer s Manual When SQLMoreResults returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLMoreResults and explains each one 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 SQLSTATE value is SQL_ERROR unless noted otherwise 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 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 compl
66. 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 CARDI NALITY or PAGES are not available from the data source the driver sets them For a code example of a similar function see SQLColumns SQL Statistics Related Functions For information about See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SQLCancel Fetching a block of data or scrolling through a result set SQLExtendedFetch Fetching a row of data SQLFetch Returning the columns of a primary key SQLPrimaryKeys INFORMIX CLI Function Reference 13 311 SQ_TablePrivileges SQLTablePrivileges SOLTablePrivileges 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 SQLTablePrivileges function accepts the following arguments v2 Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szTableQualifi
67. SQLBrowseConnect SQLConnect SQLDriverConnect SQLDrivers SQLDescribeCol SQLDescribeCol SQLDescribeCol returns the result descriptor column name type precision scale and nullability 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 pfSqliType pcbColDef pibScale pfNullable The SQLDescribeCol 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 pebColName 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 chColNameMax 1 bytes 1 of 3 INFORMIX CLI Function Reference 13 85 SQLDescribeCol 13 86 Type SWORD FAR INFORMIX CLI Programmer s Manual Argument pfSqlType Use Output Description The SQL data type of the column The SQL data type must be one
68. SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare All ODBC functions except SQLAllocEnv SQLError All ODBC functions except SQLAllocEnv SQLError SQLFreeConnect SQLFreeEnv 7 of 13 SQLSTATEs 1002 1003 1004 S1009 Error Invalid column number Program type out of range SQL data type out of range Invalid argument value Can be returned from SQLBindCol SQLColAttributes SQLDescribeCol SQLExtendedFetch SQLFetch SQLGetData SQLBindCol SQLBindParameter SQLGetData SQLBindParameter SQLGetTypelnfo SQLAllocConnect SQLAllocStmt SQLBindCol SQLBindParameter SQLExecDirect SOLGetData SQLGetInfo SQLNativeSql SQLPrepare SQLPutData SQLSetConnectOption SQLSetCursorName SQLSetStmtOption 8 of 13 INFORMIX CLI Error Codes A 9 A 10 SQLSTATEs 1010 1011 INFORMIX CLI Programmer s Manual Error Function sequence error Operation invalid at this time Can be returned from SQLBindCol SQLBindParameter SQLColAttributes SQLColumnPrivileges SQLColumns SQLDescribeCol SQLDisconnect SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLFreeConnect SQLFreeEnv SQLFreeStmt SQLGetConnectOption SOQLGetCursorName SOLGetData SQLGetFunctions SQLGetStmtOption SQLGetTypelInfo SQLMoreResults SOLNumParams SQOLNumResultCols SQLParamData SQLParamOptions SQLPrepare SQLPrimaryKeys SQLProcedures SQLPutData SQLRowCount SQLSetConnectOption SOLSetCursorName SQLSetScrollOptions
69. SQLExtendedFetch 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 use the same data at the same time A transaction is serializable if it is performed in a manner in which it appears as if no other transactions operate on the same data at the same time For example assume 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 serializable 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 INFORMIX CLI Programmer s Manual Modifying Result Set Data with Positioned Update and Delete Statements Serializability is necessary to maintain database integrity For cursors it is implemented at the expense of concurrency by locking the result set A compromise between serializability and concurrency is optimistic concurrency control Ina cursor that uses optimistic concurrency control the driver does not lock rows when it retrieves them When the application requests an update or delete operation the driver or data source checks if the row has changed If
70. SQLSetStmtOption SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables SQLTransact SQLGetStmtOption SQLSetConnectOption SQLSetStmtOption 9 of 13 SQLSTATEs 1012 1015 S1090 S1091 S1092 S1093 S1094 Error Invalid transaction operation code specified No cursor name available Invalid string or buffer length Descriptor type out of range Option type out of range Invalid parameter number Invalid scale value Can be returned from SQLTransact SQLGetCursorName SQLBindCol SQLBindParameter SQLBrowseConnect SQLColAttributes SQLColumnPrivileges SQLColumns SQLConnect SQLDataSources SQLDescribeCol SQLDriverConnect SQLDrivers SQLExecDirect SQLExecute SQLGetCursorName SQLGetData SQLGetInfo SQLNativeSql SQLPrepare SQLPrimaryKeys SQLProcedures SQLPutData SQLSetCursorName SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables SQLColAttributes SQLFreeStmt SQLGetConnectOption SQLGetStmtOption SQLSetConnectOption SQLSetStmtOption SQLBindParameter SQLBindParameter 10 of 13 INFORMIX CLI Error Codes A 11 A 12 SQLSTATEs 1095 S1096 S1097 S1098 S1099 S1100 S1101 S1103 S1104 S1105 S1106 S1107 S1108 S1109 S1110 INFORMIX CLI Programmer s Manual Error 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 o
71. SQL_FETCH_NEXT 1 amp crow fRowStatus retcode SQL_SUCCESS_WITH_INFO retcode SQL_SUCCESS_WITH_INFO w irow SQL_ROW_DELETED amp amp SQL_ROW_ERROR 2d s szName irow sAge irow szBirthday irow cation declares an array of structures to returned numbers of bytes Using SQLSet StmtOption it 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 Using SOLSetStmtOption it specifies the size of the rowset INFORMIX CLI Function Reference 13 141 SQLExtendeaFetch 13 142 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 rowset data with SOLExtendedFetch and prints each employee s name and birthday itdefine ROWS 100 dtdefine NAME_LEN 30 itdefine BDAY_LEN 11 typedef struct UCHAR szNameLNAME_LEN SDWORD cbName SWORD sAge SDWORD cbAge UCHAR szBirthday BDAY_LEN SDWORD cbBirthday EmpTable EmpTable rgetLROWS UDWORD crow irow UWORD rgfRowStatus ROWS SQLSetStmtOption hstmt SQL_BIND_TYPE sizeof EmpTable SQLSetStmtOption hstmt SQL_CONCURRENCY SQL_CONCUR_READ_O
72. SQL_NEED_DATA SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLEINFORMIX CLI 13 236 INFORMIX CLI Programmer s Manual Diagnostics SQLParamData When SQLParamData returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLParamData 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 08S01 22026 S1000 S1001 Error General warning Communication link failure String data length mismatch General error Memory allocation failure 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 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 returned by SQLError in the argument szE
73. The following table shows the ODBC C data types to which date SQL data can be converted For an explanation of the columns and terms in the table see Converting Data from SQL to C Data Types on page C 13 Test rgbValue pcbValue SQLSTATE cbValueMax gt 11 Data 10 N A cbValueMax lt 11 Untouched Untouched 22003 Length of data lt cbValueMax Data Length of data N A Length of data gt cbValueMax Untouched Untouched 22003 None Data 6 N A None Data gt 16 N A 4 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 gt 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 in the yyyy mm dd format Data Types C 21 SQL to C Time Stamp fCType SQL_C_CHAR SQL_C_BINARY SQL_C_DATE SQL_C_TIME SQL_C_TIMESTAMP SQL to C Time Stamp The time stamp ODBC SQL data type is SQL_TIMESTAMP The following table shows the ODBC C data types to which time stamp SQL data can be converted For an explanation of the columns and terms in the table see Converting Data from SQL to C Data Types on page C 13 Test cbValueMax gt Display size 20 lt cbValueMax lt Display size cbValueMax lt 20 Length of data lt cbValueMax Length of data gt cb ValueMax Time portion of ti
74. 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_LAUTOCOMMIT connection option can cause the data source to close the cursors and delete the access plans for all hstmts on an hdbc For more infor mation see SQL_CURSOR_COMMIT_BEHAVIOR and SQL _CURSOR_ROLLBACK_BEHAVIOR on page 13 192 Retrieving Information About the Data Source Catalog The following functions known as catalog functions return information about a data source catalog m SQLTables returns the names of tables stored in a data source m SQLTablePrivileges returns the privileges associated with one or more tables SQLColumns returns the names of columns in one or more tables m SQLColumnPrivileges returns the privileges associated with each column in a single table m SQLPrimaryKeys returns the names of columns that comprise the primary key of a single table Executing SQL Statements 6 9 Sending Parameter Data at Execution Time 6 10 m SQLSpecialColumns returns information about the optimal set of columns that uniquely identify a row in a single table or the columns in the table that are automatically updated when any value in the row is updated by a transaction m SQLStatistics returns statistics about a single table and the indexes associated with the table m SQLProcedures returns the na
75. Usage Error Invalid string or buffer length Driver not capable Time out expired SQLColumnPrivileges 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 corresponding qualifier or name See Usage 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 SQLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLColumnPrivileges returns the results as a standard result set ordered by TABLE_QUALIFIER TABLE_LOWNER TABLE_NAME COLUMN_NAME GRANTOR and GRANTEE The following table lists the columns in the result set 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 by SQLColumnPrivileges
76. a dialog from the values in szConnStrOut The user supplied values are returned in szConnStrIn which is passed in the next call to SQLBrowseConnect Istrcpy szConnStriIn DSN MyServer do retcode SQLBrowseConnect hdbc szConnStrIn SQL_NTS szConnStrOut BRWS_LEN amp cbConnStrOut if retcode SQL_NEED_DATA GetUserInput szConnStrOut szConnStrIn SQL_NEED_DATA CCESS retcode SQL_SUCCESS_WITH_INFO er successful connection SQLAllocStmt hdbc amp hstmt SQ L_SUCCESS SQLFreeStmt hstmt SQL DROP SQLDisconnect hdbc SQLCancel Related Functions For information about See Allocating a connection handle SQLAllocConnect Connecting to a data source SOLConnect Disconnecting from a data source SQLDisconnect Connecting to a data source using a connection string or SQLDriverConnect dialog box Returning driver descriptions and attributes SQLDrivers Freeing a connection handle SQLFreeConnect SQLCancel SQLCancel cancels the processing on an hstmt Syntax RETCODE SQLCancel hstmt The SQLCancel function accepts the following argument Type Argument Use Description HSTMT hstmt Input Statement handle Return Codes SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 49 SQL Cancel Diagnostics When SQLCancel returns SOQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained
77. amp outlenLil while TRUE rc SQLFetch hstmt if rc SQL_SUCCESS rc errmsg 0 0 for i 0 i lt nresultcols i 1 SQL_C_CHAR data i collenli SQL_SUCCESS_WITH_INFO i if Coutlenli SQL_NULL_DATA Istrcpy dataLi NULL else if outlen i gt collenli sprintf amp errmsglstrlen errmsg ad chars truncated outlen i colnum printf 2 s printf n s errmsg else break INFORMIX CLI Programmer s Manual collenlil col d n collen i 1 collenli datali Finally fetch and print each row printing SWORD sizeof colname amp colnamelen amp coltype amp collen i amp scale si ET ay Af 7 Interactive Ad Hoc Query Example Free the data buffers for i 0 i lt nresultcols i free dataLli 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 a return 0 xkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkxk The following function is included for completeness but is not relevant for understanding the function of ODBC xkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk itdefine MAX_NUM_PRECISION 15 Define max length of char string representation
78. 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 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 INFORMIX CLI Programmer s Manual Fetching Result Data Important Although SQLRowCount can sometimes return the number of rows in a result set it is not guaranteed to do so Few data sources support this functionality and interoperable applications should not rely on it Tip For optimal performance an application should call SQLColAttributes 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 returned by them is not readily available until after the statement has executed Fetching Result Data You can perform several operations to retrieve data once the characteristics of the result set are known To retrieve
79. and returns SQL_ERROR The application calls SQLError to retrieve information about the truncation or the error For more information about output buffers see Converting Data from SQL to C Data Types on page C 13 Environment Connection and Statement Handles The driver manager and the driver allocate storage for information about the environment each connection and each SQL statement when an application requests 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 interface uses the following types of handles that are defined by the ODBC specification m The environment handle identifies memory storage for global infor mation including the valid connection handles and the current active connection handle The environment handle is an HENV variable type An application uses a single environment handle it must request this handle before it connects to a data source m 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 have multiple connection handles associated with it m Statement handles identify memory storage for information about SQL statements A statement handl
80. any bound column is null the INDICATOR_PTR field of the corre sponding descriptor record must not be a null pointer 1 of 4 SQLSTATE 22003 22005 22008 22012 24000 40001 S1000 S1001 Error Numeric value out of range Error in assignment Datetime field overflow Division by zero Invalid cursor state Serialization failure General error Memory allocation failure SQLExtendedFetch Description Returning the numeric value as numeric or string for one or more columns would have caused the whole as opposed to fractional part of the number to be truncated Returning the binary value for one or more columns would have caused a loss of binary significance For more information see Appendix C 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
81. 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 in the odbc ini file The default translation shared library is loaded by the driver 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 SQL_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 has been specified in the ODBC initialization file or by calling SQLSetConnectOption the driver does not attempt to translate data Any value set for the translation option is ignored For more information about translating data see ODBC Options on page 1 10 and Chapter 15 Translation 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 SQLGetStmtOption Setting a statement option SQLSetStmtOption INFORMIX CLI Programmer s Manual SQL SetCursorName SQLSetCursorName
82. by the application is reduced from 110 in the previous example to 4 calls 1 SOLSetStmtOption 1 SQLExecDirect 1 SQLBindCol 1 SQLExtendedFetch The total savings changes from an initial call load of more than 1890 ODBC calls in the first presentation of the example to 4 calls In addition to reducing the call load many ODBC drivers retrieve data from the server in arrays that further improve the performance by reducing network traffic Executing Calls ODBC drivers are optimized based on the perceived use of the functions that are being executed This section discusses differences that can affect the performance of your application SQLPrepare SQLExecute Versus SQLExecDirect Use SOLExecDirect for queries that will be executed once and SQLPrepare SQLExecute for queries that will be executed more than once SQLPrepare 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 Unfortunately more than 75 percent of all ODBC applications use SQLPrepare SQLExecute exclusively Designing Performance Oriented Applications 11 11 Using SQLPrepare and Multiple SQLExecute Calls 11 12 The pitfall of always coding SQLPrepare SQLExecute can be understood better by considering an ODBC driver that implements SQLPrepare by creating a stored procedure on the server that contains the prepared statement Creating a stored proc
83. 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 SQL_USE_BOOKMARKS statement option was SQL_UB_OFF 1 of 2 SQLSTATE Error 1092 Option type out of range 1109 Invalid cursor position S1C00 Driver not capable Usage SQL GetStmtOption 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 SQL_ROW_NUMBER but the value in the refRowStatus array in SQLExtendedFetch for the current row was SQL_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 13 288 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 SQL_MAX_OPTION_STRING_LENGTH bytes excluding the null termination byte fOption pvParam contents SQL_GET_BOOKMARK INFORMIX CLI does not support this option The UNSUPPORTED default is set to SQL_USE_BOOKMARKS SQL_UB_OFF SQL_ROW_NUMBER A 32 bit integer value that specifies the number of the current row
84. column identifier data type ADD column identifier data type column identifier data type SQL conformance level Extended ALTER TABLE base table name ADD column identifier data type ADD column identifier data type column identifier data type DROP COLUMN column identifier CASCADE RESTRICT CREATE INDEX Statement SQL conformance level Core CREATE UNIQUE INDEX index name ON base table name column identifier ASC DESC column identifier ASC DESC B 4 INFORMIX CLI Programmer s Manual CREATE TABLE Statement CREATE TABLE Statement Important As a data type in a CREATE TABLE statement applications must use a data type from the TYPE_NAME column of the result that SQLGetTypeInfo returns SQL conformance level Minimum CREATE TABLE base table name column element column element column element column definition table constraint definition column definition column identifier data type DEFAULT default value column constraint definition column constraint definition default value literal NULL USER column constraint definition NOT NULL UNIQUE PRIMARY KEY REFERENCES ref table name referenced columns CHECK search condition table constraint definition UNIQUE column identifier column identifier PRIMARY KEY column identifier column jdentifier CHECK search condition FOREIGN KEY referenci
85. 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 The connection string might include several driver defined keywords Because the DRIVER keyword does not use information from the odbc ini file the driver must define enough keywords so that a driver can connect to a data source using only the information in the connection string For more information see Driver Guidelines on page 13 101 The driver defines which keywords are required in order to connect to the data source For more information about keywords that can be used in a connection string for the INFORMIX CLI driver see Using a Connection String to Connect to a Data Source on page 2 13 for UNIX and Using a Connection String to Connect to a Data Source on page 2 28 for Windows 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 the driver manager and the driver use the keyword that appears first The following table describes the attribute values of the DSN DRIVER UID and PWD keywords INFORMIX CLI Function Reference 13 99 SQL DriverConnect 13 100 Keyword DSN DRIVER UID PWD
86. data be converted to its default C data type For information about how data is converted see Converting Data from SQL to C Data Types on page C 13 Pointer to storage for the data Maximum length of the rgb Value buffer For character data rgbValue must also include space for the null termination byte For character and binary C data cbValueMax determines the amount of data that can be received in a single call to SQLGetData 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 C 8 2 of 3 INFORMIX CLI Function Reference 13 165 SQL GetData 13 166 Type Argument Use SDWORD pebValue Output FAR Return Codes INFORMIX CLI Programmer s Manual 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 SQLGetData or SQL_NO_TOTAL if the number of available bytes cannot be deter mined For character data if pcb Value is SQL_NO_TOTAL or 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 data if pcbValue is SQL_NO_TOTAL or is greater than cbValueMax the data in
87. data source that uses the INFORMIX CLI driver the odbc ini entry might look like the following example ODBC Data Sources Agencies Informix Driver File Format for odbe ini Data Source Specification Each data source listed in the ODBC Data Sources section has its own Data Source Specification section This section has the following format data_source_name Driver driver_path Description data_source_description TranslationDLL translation_path TranslationName translator_name TranslationOption translation_option keyword attribute data_source_name driver_path translation_path translation_option attribute is the name of the data source as specified in the ODBC Data Sources section of this file is the full path to the driver shared library UNIX or dynamic link library Windows is the full path of the translation shared library UNIX or dynamic link library Windows This field is optional shows the ASCII representation of the 32 bit integer translation option This field is optional specifies the value for the keyword Each INFORMIX CLI driver has its own set of keywords For UNIX specific keywords and attributes refer to Adding a Data Source on page 2 6 For Windows specific keywords and attributes refer to Adding a Data Source on page 2 16 This field is optional For example the data source called Agencies connects to an INFORMIX CLI driver for Solaris called libifmx07 so 1 Th
88. data transferred on an SQLGetData or SQLFetch 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 length infor mation see Precision Scale Length and Display Size on page C 8 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 SQL_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 2 of 4 INFORMIX CLI Function Reference 13 57 SQL ColAttributes fDescType SQL_COLUMN_PRECISION SQL_COLUMN_QUALIFIER_NAME SQL_COLUMN_SCALE SQL_COLUMN_SEARCHABLE SQL_COLUMN_TABLE_NAME 13 58 INFORMIX CLI Programmer s Manual Information Returned in pfDesc rgbDesc pfDesc pfDesc rgbDesc Description The precision of the column on the data source For more information on precision see Precision Scale Length and Display Size on page C 8 The qualifier of the table that contains the column The r
89. 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 SQLExtendedFetch or SQLGetData 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 SQLExecute 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 Important Applications that transfer any data except binary data in this manner are not interoperable among DBMSs Precision Scale Length and Display Size SQLColAttributes SOQLColumns and SQLDescribeCol return the precision scale length and display size of a column in a table SOLProcedureColumns returns the precision scale and length of a column in a procedure SQLDescribeParam returns the precision or scale of a parameter in an SQL statement SQLBindParameter sets the precision or scale of a parameter in an SQL statement SQLGetTypelInfo returns the maximum precision and the minimum and maximum scales of an SQL data type on a data source SQLColAttributes SOLColumns and SQLDescribeCol return the precision scale length and display size of a column in a table SOQLBindParameter sets the precision or scale of a parameter in an SQL statement SQLGetTyp
90. different languages cultural conventions and code sets GLS functionality supersedes the functionality of Native Language Support NLS and Asian Language Support ALS GLS eliminates the need to distin guish between internationalized versions of Informix software This feature is available only when you connect to an Informix database server of Version 7 2 or later Support for additional ODBC API level 2 funtions SQLMoreResults SQLColumnPrivileges SQLTablePrivileges SQLParamOptions SQLProcedures Introduction 7 Conventions Convention italics Conventions This section describes the conventions that are used in this manual By becoming familiar with these conventions you will find it easier to gather information from this and other volumes in the documentation set The following conventions are covered Typographical conventions Icon conventions Example code conventions Screen illustration conventions Typographical Conventions This manual uses a standard set of conventions to introduce new terms illustrate screen displays describe command syntax and so forth The following typographical conventions are used throughout this manual Meaning Within text new terms and emphasized words are printed in italics Within syntax diagrams values that you are to specify are printed in italics Within examples values that you must supply such as a database file or program name are printed in italics A ta
91. driver did not allocate memory required to support executing or completing the function The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded 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 1 of 2 SQLSTATE S1090 Error SQLColumns Description DM The value of one of the name length S1C00 S1T00 Usage Invalid string or buffer length Driver not capable Time out expired 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 see Usage on page 13 184 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 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
92. driver on the hdbc 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 SQLSTATE 01802 Option value changed For example if fOption is SQL_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 SQLSetConnectOption 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 SQLSetConnectOption have a maximum length of SQL_MAX_OPTION_STRING_LENGTH bytes excluding the null termination byte INFORMIX CLI Function Reference 13 275 SQL SetConnectOption fOption SQL_ACCESS_MODE SQL_AUTOCOMMIT SQL_CURRENT_QUALIFIER UNSUPPORTED SQL_LOGIN_TIMEOUT UNSUPPORTED vParam Contents A 32 bit integer 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 ap
93. equal to zero This value is the actual length of the data in the input buffer For character data a length of 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 m SQL_NTS This value specifies that a character data value is null terminated m 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 Guidelines for Calling INFORMIX CLI Functions 3 5 Buffers The operation of INFORMIX CLI functions on character data that contains embedded null characters is undefined and is not recommended for maximum interoperability Unless it is specifically prohibited in a function description the address of an input buffer can be a null pointer In this case the value of the corresponding buffer length argument is ignored For more information about input buffers see Converting Data from C to SQL Data Types on page C 24 Output Buffers An application passes the following arguments to the driver so that the driver can return data in an output buffer m The address of the buffer in which the driver returns the data the output buffer Unless it is specifically prohibited in a function description the a
94. fColType szTableQualifier cbTableQualifier szTableOwner cbTableQwner szTableName cbTableName fScope fNullable The SQLSpecialColumns function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UWORD fColType Input Type of column to return Must be one of the following values SQL_BEST_ROWID Returns the optimal column or set of columns that by retrieving values from the column or columns allows any row in the specified table to be uniquely identified A column can be either a pseudo column specifically designed for this purpose or the column or columns of any unique index for the table 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 1 of 3 INFORMIX CLI Function Reference 13 295 SQL SpecialColumns 13 296 Type Argument UCHAR FAR szTableQualifier SWORD cbTableQualifier UCHAR FAR szTableOwner SWORD cbTableOwner UCHAR FAR szTableName SWORD cbTableName INFORMIX CLI Programmer s Manual Use Input Input Input Input Input Input Description 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 szTableQualif
95. failed No data source or driver specified dialog prohibited Dialog failed INFORMIX CLI Programmer s Manual Description 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 connection string szConnStrIn violated restrictions defined by the data source DM The data source name specified in the connection string szConnStrIn was not found in the odbc ini file and no default driver specification existed DM The odbc ini file could not be found DM The driver listed in the data source specification in the odbc ini file or specified by the DRIVER keyword was not found or was not loaded for some other reason DM During SOLDriverConnect the driver manager called the driver SQLAIlocEnv function and the driver returned an error DM During SOLDriverConnect the driver manager called the driver SQLAIlocConnect function and the driver returned an error DM During SOLDriverConnect the driver manager called the driver SQLSetConnec tOption 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 failed 2 of 4 SQLSTATE IMO009 IM010 IM011 IM012 S1000 S1001 Error
96. file that is logging the ODBC function calls INFORMIX CLI Programmer s Manual tracefile_path TraceAutoStop File Examples for odbc ini specifies the full path to the trace file If a trace file is not specified and tracing is enabled logging information is written to the sql log file which is located in your current directory indicates whether tracing is enabled or disabled when an application calls the SOLFreeEnv function If the TraceAutoStop keyword is set to 0 tracing is not automat ically disabled If the TraceAutoStop keyword is set to 1 the Trace keyword in the odbc ini file is set to 0 Additionally all other concurrent Windows ODBC appli cations will have tracing disabled The default is 1 File Examples for odbc ini The following example shows a Windows 3 1 ODBC INI file ODBC Da Stores Default river C Kas LogonID tores7 S r Os Sr ODD OTUA ODBC Trace l ta Sources nformix Driver WINDOWS SYSTEM QEINF509 DLL atabase vendors iver C WINDOWS SYSTEM QEINF509 DLL tName odin vice sqlexec tabase stores gonID mary TraceFile C WINDOWS LOG TRACE LOG TraceAutoStop 0 Overview of INFORMIX CLI 1 11 ODBC Conformance Levels The following example shows a UNIX odbc ini file ODBC Data Sources Stores 7 Informix Driver Default Driver usr informix cli dlls qeinf 708 so Database stores 7 LogonID marvin ODBC nstallDir usr
97. following situations occurs m t needs to execute the same prepared statement several times with different parameter values m The parameter values are not known when the statement is prepared m The parameter values need to be converted from one data type to another Executing SQL Statements 6 7 Setting Parameter Values 6 8 To set a parameter value an application performs the following operations 1 Calls SOQLBindParameter to bind a storage location to a parameter marker and to specify the data types of the storage location and the column associated with the parameter as well as the precision and scale of the parameter 2 Places the value of the parameter in the storage location These steps can be performed before or after a statement is prepared but must be performed before a statement executes Parameter values must be placed in storage locations in the C data types specified in SOLBindParameter shown in the following table Parameter Value SQL Data Type C Data Type Stored Value ABC SQL_CHAR SQL_C_CHAR ABC 0 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 a 0 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 c
98. 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 exists 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 9 3 Terminating Transactions Terminating Transactions An application calls SQLTransact to commit or roll back the current transaction Terminating Connections An application terminates a connection to a driver or to a data source by closing the connection associated with a connection handle and freeing the connection and environment handles To terminate a connection to a driver and data source an application performs the following operations 1 Calls SQLDisconnect to close the connection You can then use the handle to reconnect to the same data source or to a different data source 2 Calls SQLFreeConnect to free the connection handle and free all resources associated with the handle 3 Calls SQLFreeEnv to free the environment handle an
99. function description The text associated with SQLSTATE values is included to provide a description of the condition but it is not intended to prescribe specific text INFORMIX CLI Function Reference 13 3 Arguments Arguments All INFORMIX CLI function arguments use a naming convention of the following form Lprefix taglqualifier suffix Optional elements are enclosed in brackets and use the following prefixes Prefix Description c Count of h Handle of i Index of p Pointer to rg Range array of The following tags are used Tag Description b Byte col Column of a result set dbc Database connection env Environment f Flag enumerated type par Parameter of an SQL statement row Row of a result set stmt Statement SZ Character string array of characters terminated by zero v Value of unspecified type 13 4 INFORMIX CLI Programmer s Manual Arguments Prefixes and tags combine to correspond roughly to the ODBC C types listed below Flags f and byte counts cb do not distinguish among SWORD UWORD SDWORD and UDWORD Combined cb crow hdbc henv hstmt hwnd ib icol ipar irow pcb pecol pcpar pcrow pf phdbc phenv Prefix Cc rT TFT TF gt para pe pe pe pe ph Tag b row dbc env stmt wnd col par row col par row dbc env ODBC C Type s SWORD SDWORD UDWORD SDWORD UDWORD UWORD
100. has a section that lists the translator shared library UNIX Windows 3 1 Windows NT Windows 95 D Understanding the odbc ini File Understanding the odbc ini File The INFORMIX CLI driver and driver manager use the odbc ini initialization file Although this file has a slightly different name depending upon whether you use a UNIX or Windows client application the format and structure of the file are the same For UNIX users odbc ini is a text file called odbc ini The file is located in your home directory Initially a template file called odbc ini resides in the INFORMIXDIR cli directory where your INFORMIX CLI software is installed For information on setting up your odbc ini file see Adding and Modifying Data Sources on page 2 6 For Windows 3 1 odbc ini is a text file called ODBC INI The file is located in the WINDOWS directory Before you can connect to a data source you must use the ODBC Administrator to add the connection information for the data source to this file Warning Windows 3 1 users should never modify the ODBC INI file The contents of this file are changed based on the data source setup and modification you make using the ODBC Administrator Modifying the ODBC INI file directly might result in data source configuration errors For Windows NT and Windows 95 ODBC INI is a subkey of the HKEY_CURRENT_USER key within the registry When you access the registry using this subkey the ODBC st
101. in SQLBindCol to determine which column or columns were truncated If pcb Value is greater than or equal to cbValueMax then truncation occurred m Ifthe data value for the column is NULL the driver stores SQL_NULL_DATA in pcbValue 13 148 INFORMIX CLI Programmer s Manual SQLFetch SQLFetch is valid only after a call that returns a result set For information about conversions allowed by SQLBindCol and SQLGetData see Converting Data from SQL to C Data Types on page C 13 Code Example See SOLBindCol SOLColumns SQLGetData and SQLProcedures Related Functions For information about See Assigning storage for a column ina result set SQLBindCol Canceling statement processing SQLCancel Returning information about a column in a SQLDescribeCol result set Executing an SQL statement SQOLExecDirect Executing a prepared SQL statement SQLExecute Fetching a block of data or scrolling througha SQLExtendedFetch result set Freeing a statement handle SOLFreeStmt Fetching part or all of a column of data SOLGetData Returning the number of result set columns SOLNumResultCols Preparing a statement for execution SQLPrepare INFORMIX CLI Function Reference 13 149 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
102. 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 INFORMIX CLI Function Reference 13 215 SQL GetTypelnfo Related Functions For information about See Returning the setting of a connection option SQLGetConnectOption Setting a connection option SQLSetConnectOption Setting a statement option SQLSetStmtOption SQLGetTypel nfo SQLGetTypeInfo returns information about data types supported by the data source The driver returns the information in the form of an SQL result set Important Applications must use the type names returned in the TYPELNAME v gt column in ALTER TABLE and CREATE TABLE statements they must not use the sample type names listed in Appendix C SQL Grammar SQLGetTypeInfo might return more than one row with the same value in the DATA_TYPE column Syntax RETCODE SQLGetTypeInfo hstmt fSqlType 13 216 INFORMIX CLI Programmer s Manual SQL Get Typelnfo The SQLGetTypelInfo function accepts the following arguments Return Codes Description Statement handle for the result set The SQL data type which must be one of the following values SQL_CHAR SQL_DATE SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_REAL SQL_SMALLINT SQL_TIMESTAMP SQL_VARCHAR SQL_ALL_TYPES specifies that infor mation about all data types should be returned For information on ODBC SQL data types see Ap
103. keyword 13 101 Dynamic cursors 7 10 Dynamic SQL D 7 E Elements SQL statements B 11 Embedded SQL executing statements 6 5 ODBC function equivalents D 1 D 5 D 6 Empty strings 3 5 13 11 Environment handles allocating 13 15 defined 3 7 freeing 9 4 initializing 5 4 overwriting 13 15 SQLFreeEnv 13 154 with threads 13 15 See also Handles Errors application processing 8 8 clearing 13 112 format 8 5 messages 8 4 queues 13 112 return codes 8 3 rowsets 13 138 source 8 4 SQLError 13 111 SQLSTATE values A 1 with parameter arrays 13 244 See also specific function description Escape characters 13 10 Escape clauses datetime literals 6 13 outer joins 6 16 procedures 6 17 scalar functions 6 14 support of 13 201 syntax 6 12 Examples ad hoc query 10 7 data conversion C 23 C 36 parameter values 6 8 static SQL 10 4 Expressions data types B 11 in ORDER BY clauses 13 197 Expressions in NewEra statements expression types 6 13 Extensions to SQL 6 12 F Fat cursors 7 9 Fetching data See Retrieving data Files ODBC INI 1 7 1 10 odbc ini file 1 6 sql log 1 11 trace 1 10 13 279 usage 13 198 odbc ini 2 6 Filtered indexes 13 313 Floating point data converting to C C 18 converting to SQL C 29 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 Freeing handles 13 152 13 154 13 159 Functionality driver 13 179 13 188 Functions ODBC buffers 3 5 canceling 13 52 deprecated 13 287
104. kong ok 7 9 Block Cursors 2 2 2 eee en 7 9 Scrollable Cursors Rae is oh ae Pho id oh ae th ALO Specifying the Cursor Type ge Wu eB ae Th 8 hue he aed Specifying Cursor Concurrency amp 7212 Modifying Result Set Data with Positioned d Update ar and Delete Statements onog FB Processing Multiple Results yia Of fa we ua a a oo w rw ZAD 7 2 INFORMIX CLI Programmer s Manual SELECT statement is used to retrieve data that meets a given set of specifications 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 SQLColumns 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 SQLExecDirect 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 The steps an application takes to process a result set depends on what is known about it The following list defines known and unknown result sets Known result set The application knows the exact form of the SQL statement and therefore the resu
105. library does not null terminate this value Length of rgbValueOut 1 of 2 Type SDWORD FAR UCHAR FAR SWORD SWORD FAR Argument pebValueOut szErrorMsg cbErrorMsgMax pebErrorMsg Return Codes Use Output Output Input Output SQLDataSourceToDriver Description The total number of bytes excluding the null termination byte available to return in rgbValueOut For character or binary data if this is greater than or equal to cbValue OutMax the data in rgb ValueOut is truncated to cbValueOutMax bytes For all other data types the value of cbValueOutMax is ignored and the translation shared library assumes the size of rgbValueOut is the size of the default C data type of the SQL data type specified with fSq Type Pointer to storage for an error message This is an empty string unless the translation failed Length of szErrorMsg Pointer to the total number of bytes excluding the null termination byte available to return in szErrorMsg If this is greater than or equal to cbErrorMsg the data in szErrorMsg is truncated to cbErrorMsgMax 1 bytes 2 of 2 The application returns TRUE if the translation succeeds FALSE if it fails Translation Shared Library Function Reference 15 5 SQLDataSourceToDriver 15 6 Usage The driver calls SQLDataSourceToDriver to translate all the data result set data table names row counts error messages and so on that pas
106. loyeeName 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 return FALSE return FALSE Related Functions For information about See Canceling statement processing SQLCancel Executing an SQL statement SQLExecDirect Executing a prepared SQL statement SQLExecute Returning the next parameter to send data for SQOLParamData Assigning storage for a parameter SQLBindParameter INFORMIX CLI Function Reference 13 269 SQL RowCount 13 270 SQLRowCount SQLRowCount returns the number of rows affected by an UPDATE INSERT or DELETE statement Syntax RETCODE SQLRowCount hstmt pcrow The SOLRowCount function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle SDWORD FAR pcrow Output For UPDATE INSERT and DELETE state Return Codes ments 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 returned by a SELECT statement or a catalog function before fetching
107. 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 More than one henv should never be allocated at one time and the appli cation should not call SQLAIlocEnv when a current valid henv exists If the application calls SOLAIlocEnv with a pointer to a valid henv the driver overwrites the henv without regard to its previous contents When the driver manager processes the SQLAIlocEnv function it checks the Trace keyword in the ODBC options section of the odbc ini file If the keyword is set to 1 the driver manager enables tracing for all applications Code Example See SOLBrowseConnect and SQLConnect INFORMIX CLI Function Reference 13 13 SQLAllocStmt Related Functions For information about See Allocating a connection handle SQLAllocConnect Connecting to a data source SQLConnect Freeing an environment handle SQLFreeEnv SQLAIlocStmt SQLAIlocStmt allocates memory for a statement handle and associates the statement handle with the connection that hdbc specifies An application must call SQLAIlocStmt before it submits SQL statements Syntax RETCODE SQLAllocStmt hdbc phstmt The SQLAIlocStmt function accepts the following arguments Type Argument Use Description HDBC hdbc Input Connection handle HSTMT FAR phstmt Output Pointer to storage for the statement handle Return Codes SQL_SUCCESS SOQL_SUCCESS
108. number of result set columns SQLDescribeCol SQLExtendedFetch SQLFetch SQLFreeStmt SQLGetData SOLNumResultCols SQLBindParameter SQLBindParameter binds a buffer to a parameter marker in an SQL statement SQLBindParameter is an ODBC 2 0 function that replaces the ODBC 1 0 function SQLSetParam For more information see Usage on page 13 28 Syntax RETCODE SQLBIND hstmt ipar cbColDef ibScale rgbValue fParamType fCType FSqliType cbValueMax pcbValue INFORMIX CLI Function Reference 13 23 SQL BindParameter 13 24 INFORMIX CLI Programmer s Manual Type Argument HSTMT hstmt UWORD ipar SWORD fParamType SWORD fCType SWORD fSqlType UDWORD cbColDef SWORD ibScale Use Input Input Input Input Input Input Input The SQLBindParameter function accepts the following arguments Description Statement handle Parameter number ordered sequen tially left to right starting at 1 The type of the parameter For more information see fParamType Argument on page 13 28 The C data type of the parameter For more information see fCType Argument on page 13 29 The SQL data type of the parameter For more information see fSqlType Argument on page 13 30 The precision of the column or expression of the corresponding parameter marker For more infor mation see cbColDef Argument on page 13 31 The scale of the column or expression of the corresp
109. of number as Ef max precision leading sign E exp sign max exp length pe I5 1 ae ae a 2 ad fe 2S Tb 4 5 By itdefine 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 colname 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 10 9 Designing Performance Oriented Applications Connecting to a Data Source 2 en 11 4 Executing Calls 4 0s goes Oe ae hoe gle te a We hs Wd 11 11 SOLPrepare SQLExecute Versus SQLExecDirect 2 11 11 Committing Data a a 6 we a 11 16 11 2 INFORMIX CLI Programmer s Manual his chapter provides guidelines for designing and coding perfor mance oriented INFORMIX CLI applications These guidelines are not hard theorems but general advice that apply to ODBC applications The guidelines address areas in which inefficient performance can be improved Areas in Which Performance is Im
110. of the result set or after the end of the result set The argument szSqlStr contained a positioned UPDATE or DELETE statement but the cursor referenced by the statement being executed was not open The argument szSqlStr contained an SQL statement that was not preparable or contained a syntax error The transaction to which the SQL statement contained in the argument szSq Str belonged was terminated to prevent deadlock The user did not have permission to execute the SQL statement contained in the argument szSqlStr The argument szSqlStr contained a CREATE TABLE or CREATE VIEW statement but the table name or view name specified already exists 3 of 6 SQLSTATE S0002 S0011 S0012 Error Table or view not found Index already exists Index not found SQLExecDirect Description 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 szSqlStr 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 defined by the query specification 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 SELE
111. of valid data conversion types see Converting Data from SQL to C Data Types on page C 13 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 rgb Value points Finally it stores the available number of bytes in pcb Value The value stored in pcbValue is the number of bytes available before the driver calls SQLFetch or SQLExtendedFetch 13 20 INFORMIX CLI Programmer s Manual 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 SQOL_MAX_LENGTH the driver stores SOL_MAX_LENGTH in pebValue m If the data is truncated because of SOL_MAX_LENGTH but the user s buffer is large enough for SQLLMAX_LENGTH bytes of data the driver returns SQL_SUCCESS Important The SQL_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 Ifthe 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 pcbVal
112. 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 22005 Error in assignment The data sent for a parameter or column was incompatible with the data type of the associated table column 22008 Datetime field overflow The data sent for a date time or time stamp parameter or column was respectively an invalid date time or time stamp 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 failure The driver could not allocate memory required to 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 multi threaded application SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED_DATA SQLCancel was called before data was sent for all data at execution
113. places the result of the SQL_LEN_DATA_AT_EXEC ength macro in the pebValue buffer The application calls SQLExecute or SQLExecDirect 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 SQLParamData 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 larger than the rgb Value buffer specified in SOLPutData multiple calls to SQLPutData for the same parameter are allowed only when sending character C data to a column with a character binary or data source specific data type or when sending binary C data to a column with a character binary or data source specific data type INFORMIX CLI Function Reference 13 35 SQL BindParameter 13 36 6 The application calls SQLParamData again to signal that all data has been sent for the parameter m If more data at execution parameters exist SQLParamData returns SQL_NEED_DATA and the application defined value for the next data at execution parameter to be processed The appli
114. preceding them with an escape character The escape clause that ODBC uses to define the LIKE predicate escape character is shown in the following example vendor Microsoft product ODBC escape escape character In this example escape character is any character supported by the data source The shorthand syntax for the LIKE predicate escape character is as follows escape escape character Executing SQL Statements 6 15 Using ODBC Extensions to SQL 6 16 For example each of the following statements creates the same result set of department names that start with the characters AAA The first statement uses the escape clause syntax The second statement uses the shorthand syntax The third statement uses the native syntax for Informix for UNIX and is not interoperable among DBMSs The second percent character in each LIKE predicate is a wild card character that matches zero or more of any character SELECT NAME FROM DEPT WHERE NAME LIKE ZAAA vendor Microsoft product ODBC escape SELECT NAME FROM DEPT WHERE NAME LIKE 2AAA escape SELECT NAME FROM DEPT WHERE NAME LIKE ZAAA ESCAPE To determine whether a data source supports LIKE predicate escape characters an application calls SOLGetInfo with the information type SQL_LIKE_ESCAPE_CLAUSE Outer Joins ODBC supports the ANSI SQL 92 LEFT OUTER JOIN syntax The escape clause that ODBC uses for outer joins is shown in
115. 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 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 requested result set The time out period is set through SQOLSetStmtOption 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 13 253 SQLPrimaryKeys 13 254 options Column Name Data Type TABLE_QUALIFIER VARCHAR 128 TABLE_LOWNER VARCHAR 128 TABLE_NAME VARCHAR 128 not NULL COLUMN_NAME VARCHAR 128 not NULL KEY_SEQ SMALLINT not NULL PK_NAME VARCHAR 128 Related Functions Fetching a row of data Returning table statistics and indexes INFORMIX CLI Programmer s Manual 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_LOWNER TABLE_NAME and COLUMN_NAME columns call SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SQL_ MAX_COLUMN_NAME_LEN Comments Primary key t
116. required only if the length of the data is SQL_NTS gt An addition to bytes for numbers one byte is required for a sign and another byte is required 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 are the numbers stored in the fields of the TIMESTAMP_STRUCT structure Sate eee C 36 INFORMIX CLI Programmer s Manual Comparison Between 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 The SQL language is based on the X Open and SQL Access Group SQL CAE specification 1992 D 2 INFORMIX CLI to Embedded SQL INFORMIX CLI Function SQLAllocEnv SQLAllocConnect SQLConnect SQLAllocStmt SQLPrepare SQLBindParameter SQLSetCursorName SQLGetCursorName INFORMIX CLI Programmer s Manual Statement none none CONNECT none PREPARE SET DESCRIPTOR none none Comments Driver manager and driver memory allocation Driver manager and driver memory allocation Association management Driver manager and driver memor
117. result set result set Within result set SQL_SUCCESS Row 1 of rowset Requested rowset Overlaps end of SQL_SUCCESS Row 1 of rowset For rows in the rowset that result set overlap the result set data is returned For rows in the rowset outside the result set the contents of the rgbValue and pcbValue buffers are undefined and the refRowStatus array contains SQL_ROW_NOROW After end of result SQL_NO_DATA_FOUND After end of result None The contents of the rowset set set buffers are undefined For example suppose a result set has 100 rows and the rowset size is 5 The following table shows the rowset and code returned by SQLExtendedFetch for different values of irow when the fetch type is SQL_FETCH_RELATIVE Current Rowset irow Return Code New Rowset 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 rowset the rgfRowStatusArray is set to SQL_ROW_NOROW INFORMIX CLI Function Reference 13 135 SQLExtendeaFetch 13 136 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 SQL_ROW_DELETED are treated no differ ently than other rows For example calling SQLExtendedFetch with fFetchType set to SQL_FETCH_ABSOLUTE and irow set to 15 returns t
118. returns SQL_SUCCESS_WITH_INFO but still does not return a SQLSTATE value for SQLError 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 pebErrorMsg Usage An application typically calls SQLError 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 rightmost non null handle argument An application requests error infor mation as follows m To retrieve errors associated with an environment the application passes the corresponding henv and includes SQL_ 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 SQL_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 INFORMIX CLI Function Reference 13 109 SQLError m To retrieve errors associated with a statement an application passes the corresponding hstmt I
119. 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 The application calls SQLSetStmtOption with fOption set to SQL_BIND_TYPE and vParam set to the size of the structure The application allocates an array of these structures The array has as many elements as the rowset has rows plus an additional element if the application searches for key values or appends new rows of data INFORMIX CLI Function Reference 13 133 SQLExtendeaFetch 13 134 The application calls SOLBindCol 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 pebValue 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 For each bound column the driver stores the first row of data at the address specified by rgbValue for the colum
120. shared library the driver can retrieve information about the default data source from the odbc ini file m If the driver manager cannot find the corresponding data source specification and no default data source specification exists it returns SQL_ERROR with SQLSTATE IM002 Data source not found and no default driver specified 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 in the odbc ini file Because the DRIVER keyword does not use infor mation 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 INFORMIX CLI Function Reference 13 45 SQL BrowseConnect 13 46 On each call to SOLBrowseConnect 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 SQL_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 curre
121. so the irow entry of szDatal is skipped by rebinding at szDatalirow itdefine CITY_LEN 256 n NM SDWORD cbValueL J SQL_NTS SQL_NTS SQL_NTS SQL_NTS SQL_NTS UCHAR szDataL J CITY_LEN Boston New York Keokuk Seattle Eugene UDWORD irow SQLSetConnectOption hdbc SQL_AUTOCOMMIT 0 QLBindParameter hstmt 1 SQL_PARAM_INPUT SQL_C_DEFAULT SQL_CHAR CITY_LEN 0 szData 0 cbValue QLPrepare hstmt INSERT INTO CITIES VALUES SQL_NTS QLParamOptions hstmt 5 amp irow while TRUE retcode SQLExecute hstmt Done if execution was successful if retcode SQL_ERROR break On an error print the error If the error is in row 1 roll back the transaction and quit If the error is in another th row commit the transaction and unless the error is in the last row rebind to the next row and continue processing show_error if irow 1 SQLTransact henv hstmt SQL_ROLLBACK break else SQLTransact henv hstmt SQL_COMMIT if irow 5 break else SQLBindParameter hstmt 1 SQL_PARAM_INPUT SQL_C_DEFAULT SQL_CHAR CITY_LEN 0 szDataLirow 0 cbValuelirow SQLParamOptions hstmt 5 irow amp irow INFORMIX CLI Function Reference 13 243 SQL Prepare Related Functions For information about See Assigning storage for a parameter SQLBindParameter SQLPrepare SQLPrepare prepares an SQL string for executi
122. specified Specified driver could not be loaded INFORMIX CLI Programmer s Manual When SQLConnect returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLConnect 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 SQLSTATE value is SQL_ERROR unless noted otherwise 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 had already been 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 implementation 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 szAuthStr violated restrictions defined by the data source DM The data source name specified in the argument szDSN was not found in the odbc ini file nor was there a default driver specifi cation DM The odbc ini file was not found DM The driver listed in the data source speci fication in the odbc ini file was not found or could not b
123. string 13 222 time 6 13 timestamp 6 13 Loading drivers 13 80 LOCAL TEMPORARY table type 13 325 Lock level INFORMIX 5 driver 1 16 INFORMIX 7 driver 1 16 Login authorization connection strings description 5 6 SQLBrowseConnect 13 45 13 104 example 13 81 interval period 13 105 time out 13 105 See also Connections Long data values length required 13 203 retrieving 7 7 sending in parameters 6 10 SQLBindParameter 13 36 SQLGetData 13 174 M Macros data at execution 13 30 13 33 13 35 13 36 Manual commit mode beginning transactions 13 330 described 6 9 specifying 13 278 SQLTransact 13 330 See also Transactions Memory allocating buffers 3 5 connection handles 3 7 environment handles 3 7 result sets 7 4 rowsets 7 8 SQLAlIlocConnect 13 13 SQLAIlocEnv 13 15 SQLAIlocStmt 13 17 SQLFreeConnect 13 152 SQLFreeEnv 13 154 SQLFreeStmt 13 159 statement handles 3 7 Messages error See Errors Mixed cursors 7 11 Modes access 13 105 auto commit See Auto commit mode manual commit See Manual commit mode Money columns 13 59 Money data types 13 224 Multiple tier drivers error messages 8 6 identifying data sources 8 6 Multithreading with connection handles 13 13 with environment handles 13 15 with statement handles 13 18 N Names arguments 13 6 cursors 13 165 13 285 driver 13 197 index 13 312 localized data types 13 225 procedure 13 261 See also Terms server 13 209 tables 13 324 13 325 user 13 213 Networ
124. table INSERT The grantee is permitted to insert new rows containing data for one or more columns into to the table UPDATE The grantee is permitted to update the data in one or more columns of the table DELETE The grantee is permitted to delete rows of data from the table 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 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 appli cable to the data source 2 of 2 For a code example of a similar function see SQLColumns Related Functions For information about Assigning storage for a column in a result set Canceling statement processing Returning privileges for a column or columns Returning the columns in a table or tables Fetching a block of data or scrolling through a result set Fetching a row of data Returning table statistics and indexes Returning a list of tables in a data source SQLTablePrivileges See SOLBindCol SQOLCancel SQLColumnPrivileges S
125. 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 The argument szSqlStr contained a positioned UPDATE or DELETE 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 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 6 of 6 INFORMIX CLI Function Reference 13 117 SQL ExecDirect 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 used by the data source then submits it to the data source In particular the driver modifies the escape clauses used to define ODBC specific SQL For a description of SQL statement grammar see Appendix B 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 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 stmt the driver uses the specified cursor Otherwi
126. that return and retrieve results m Chapter 8 Retrieving Status and Error Information defines the INFORMIX CLI return codes and error handling protocol m Chapter 9 Terminating Transactions and Connections describes how an application terminates statements and transactions The chapter also discusses how an application terminates the connection when it finishes interacting with a data source m Chapter 10 Constructing an INFORMIX CLI Application provides code examples of basic applications INFORMIX CLI Programmer s Manual Types of Users Chapter 11 Designing Performance Oriented Applications provides guidelines for designing and coding efficient INFORMIX CLI applications Chapter 12 Function Summary summarizes the functions that INFORMIX CLI uses Chapter 13 INFORMIX CLI Function Reference describes each INFORMIX CLI function in detail Each reference contains the function s ODBC conformance level purpose syntax returns diagnostics comments SQLSTATE values and related functions The chapter also includes code examples Chapter 14 Setup Shared Library Function Reference describes the syntax of the driver setup and translator setup shared library APIs Chapter 15 Translation Shared Library Function Reference describes the syntax of the translation shared library API Appendix A provides a listing of the SQLSTATE values that can be returned the error messa
127. the driver manager The return code associated with each SQLSTATE value is SQL_ERROR unless noted otherwise 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 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 The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application 1 of 2 SQLSTATE 1010 S1090 S1C00 S1T00 Usage Error Function sequence error Invalid string or buffer length Driver not capable Time out expired SQLPrimaryKeys 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 A table
128. 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 SQL_NULL_DATA fCType Argument The fCType argumentis the C data type of the parameter The fCType argument must be one of the following values SQL_C_BINARY SQL_C_CHAR SQL_C_DATE SQL_C_DEFAULT SQL_C_DOUBLE INFORMIX CLI Function Reference 13 29 SQL BindParameter SQL_C_FLOAT SQL_C_SLONG SQL_C_SSHORT SQL_C_TIME SQL_C_TIMESTAMP SQL_C_ULONG SQL_C_USHORT SQL_C_DEFAULT specifies that the parameter value be transferred from the default C data type for the SQL data type specified with fSq Type For more information see Default C Data Types on page C 6 Converting Data from C to SQL Data Types on page C 24 and Converting Data from SQL to C Data Types on page C 13 fSqlType Argument The fSqlType argument must be one of the following values SQL_CHAR SQL_DATE SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_REAL SQL_SMALLINT SQL_TIMESTAMP SQL_VARCHAR Values greater than SQL_TYPE_DRIVER_START are reserved by ODBC For information about how data is converted see Converting Data from C to SQL Data Types on page C 24 and Converting Data from SQL to C Data Types on page C 13 13 30 INFORMIX CLI Programmer
129. the rows Many data sources cannot return the number of rows in a result set before fetching them for maximum interopera bility applications should not rely on this behavior SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Programmer s Manual Diagnostics SQLRowCount When SQLRowCount returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLRowCount 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error 01000 General warning Description 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 message returned by SQLError in the argument szErrorMsg describes the error and its cause S1001 Memory allocation failure The driver did not allocate memory required to support execution or completion of the function S1010 Function sequence error Usage DM The function was called prior to calling SQLExecute or SQLExecDirect for the hstmt DM SQLExecute or SQLExecDirect
130. 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 the smallest unique index Designing Performance Oriented Applications 11 15 Committing Data Committing Data Committing data is extremely disk I O intensive and thus slow Always turn auto commit off if the driver can support transactions What is actually involved in a commit At commit time the DBMS server must flush back to disk every data page that contains updated or new data This is not a sequential write but a searched write to replace existing data already in the table By default auto commit is on when connecting to a data source Auto commit mode is typically detrimental to performance because of the amount of disk I O needed to commit every operation Further reducing performance some DBMS servers do not provide an auto commit mode For this type of server the ODBC driver must explicitly issue a COMMIT statement and perhaps a BEGIN TRANSACTION for every operation sent to the server In addition to the large amount of disk I O required to support auto commit mode we must also pay a performance penalty for up to three network requests for every statement issued by an application in this scenario 11 16 INFORMIX CLI Programmer s Manual Function Summary INFORMIX CLI Function Summary Connecting toa DataSource Obtaining Information About a
131. the environment handle SQLDisconnect hdbc SQLFreeConnect hdbc SQLFreeEnv henv return 0 INFORMIX CLI Programmer s Manual xI EI Kf Ri 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 prior to retrieving results 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 errmsgl256 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 F SQLAIlocEnv amp henv SQLA ES 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 hstm
132. the following example vendor Microsoft product ODBC oj outer join Outer join is used as follows table reference LEFT OUTER JOIN table reference outer join ON search condition Also in the previous example table reference specifies a table name and search condition specifies the join condition between the table references The shorthand syntax for outer joins is as follows oj outer join An outer join request must appear after the FROM keyword and before the WHERE clause if one exists For complete syntax information see Appendix B INFORMIX CLI Programmer s Manual Using ODBC Extensions to SQL For example each of the following statements creates the same result set of the names and departments of employees working on project 544 The first statement uses the escape clause syntax The second statement uses the shorthand syntax The third statement uses the native syntax for Informix for UNIX and is not interoperable among DBMSs SELECT EMPLOYEE NAME DEPT DEPTNAME FROM vendor Microsoft product ODBC oj EMPLOYEE LEFT OUTER JOIN DEPT ON EMPLOYEE DEPTID DEPT DEPTID HERE EMPLOYEE PROJID 544 SELECT EMPLOYEE NAME DEPT DEPTNAME FROM oj EMPLOYEE LEFT OUTER JOIN DEPT ON EMPLOYEE DEPTID DEPT DEPTID HERE EMPLOYEE PROJID 544 SELECT EMPLOYEE NAME DEPT DEPTNAME FROM EMPLOYEE OUTER DEPT HERE EMPLOYEE PROJID 544 AND EMPLOYEE DEPTID DEPT DEPTID
133. value of the pirow argument in SQLParamOptions with the rgbValue For example rgbValue might point to an array of values and the application might use pirow to retrieve the correct value from the array For more information see Passing Parameter Values on page 13 34 If the fParamType argument is SQL_LPARAM_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 rgb Value buffer is not guaranteed to be set until all results have been fetched If fParamType is SQL_LPARAM_OUTPUT and rgbValue and pebValue are both null pointers the driver discards the output value INFORMIX CLI Function Reference 13 31 SQL BindParameter 13 32 If the application calls SQLParamOptions to specify multiple values for each parameter rgbValue must point to an array A single SQL statement processes the entire array of input values for an input or input output parameter and returns an array of output values for an input output or output parameter cbValueMax Argument For character and binary C data the cbValueMax argument specifies the length of the rgbValue buffer if it is a single element or the length of an element in the rgbValue array if the application calls SQLParamOptions to specify multiple values for each parameter If the application specifies multiple values cb ValueMax determines the location of values in the rgbValue array bot
134. version This is implemented solely in the driver manager SQL_ORDER_BY_COLUMNS_IN_SELECT A character string Y if the columns in the ORDER BY clause must be in the SELECT list otherwise N SQL_OUTER_JOINS A character string N No The data source does not support outer joins 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 P Partial The data source partially supports nested outer joins and the driver supports the ODBC outer join syntax 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 Also the right hand table of an outer join cannot be included in an inner join F Full The data source fully supports nested outer joins and the driver supports the ODBC outer join syntax 14 of 22 INFORMIX CLI Function Reference 13 203 SQL Getinfo InfoType SQL_OWNER_TERM SQL_OWNER_USAGE SQL_POSITIONED_STATEMENTS SQL_PROCEDURE_TERM SQL_PROCEDURES 13 204 INFORMIX CLI Programmer s Manual Return
135. 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 associated with hstmt was not an UPDATE INSERT or DELETE statement the value of pcrow is driver defined INFORMIX CLI Function Reference 13 271 SQL SetConnectOption Related Functions For information about See Executing an SQL statement SQLExecDirect Executing a prepared SQL statement SQLExecute 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 SQL_INVALID_HANDLE 13 272 _INFORMIX CLI Programmer s Manual SQL SetConnectOption Diagnostics When SQLSetConnectOption returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLSetConnectOption and explains each value in the context of this
136. with it m If you have never used Structured Query Language SQL read the Informix Guide to SQL Tutorial It provides a tutorial on Informix SQL It also describes the fundamental ideas and terminology for planning implementing and using a relational database m A companion volume to the Tutorial the Informix Guide to SQL Reference includes details of the Informix system catalog tables describes Informix environment variables and UNIX environment variables that you should set and describes the column data types that Informix database servers support m An additional companion volume to the Reference the Informix Guide to SQL Syntax provides a detailed description of all the SQL statements supported by Informix products This guide also provides a detailed description of Stored Procedure Language SPL statements m The SQL Quick Syntax Guide contains syntax diagrams for all state ments and segments described in this manual m Depending on the database server you are using you or your system administrator need either the INFORMIX SE Administrator s Guide or the INFORMIX OnLine Dynamic Server Administrator s Guide 12 INFORMIX CLI Programmer s Manual On Line Documentation m The Guide to GLS Functionality describes how to use nondefault locales with Informix products A locale contains language and culture specific information that Informix products use when they format and interpret data m The DB Access Use
137. 0 The maximum length of the column The maximum number of digits plus 2 Because these data types are returned as character strings characters are needed for the digits a sign and a decimal point For example the length of a column defined as NUMERIC 10 3 is 12 2 2 bytes 4 4 bytes 4 4 bytes 1 of 2 Data Types C 11 Display Size C 12 fSqlType SQL_DOUBLE SQL_LONGVARBINARY SQL_DATE SQL_TIMESTAMP SQL_NO_TOTAL Display Size fSqlType SQL_CHAR SQL_VARCHAR SQL_LONGVARCHAR SQL_DECIMAL SQL_SMALLINT SQL_INTEGER SQL_REAL SQL_DOUBLE INFORMIX CLI Programmer s Manual Length 8 8 bytes The maximum length of the column 6 the size of the DATE_STRUCT or TIME_STRUCT structure 16 the size of the TIMESTAMP_STRUCT structure a If the driver cannot determine the column or parameter length it returns 2 of 2 The display size of a column is the maximum number of bytes needed to display data in character form The following table defines the display size for each ODBC SQL data type Display Size The defined length of the column For example the display size of a column defined as CHAR 10 is 10 The maximum length of the column The precision of the column plus 2 a sign precision digits and a decimal point For example the display size of a column defined as NUMERIC 10 3 is 12 6 if signed a sign and 5 digits or 5 if unsigned 5 digits 11 if signed a
138. 00 Error Invalid parameter number Invalid scale value Invalid precision value Invalid parameter type Driver not capable SQLBindParameter Description 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 param eters supported by the data source The value specified for the argument ibScale was outside the range of values supported by the data source for a column of the SQL data type specified by the fSqlType argument The value specified for the argument cbColDef was outside the range of values supported by the data source for a column of the SQL data type specified by the fSq Type argument DM The value specified for the argument fParamType was invalid For more infor mation see fParamType Argument on page 13 28 The value specified for the argument fParamType was SQL_PARAM_OUTPUT and the parameter did not mark a return value from a procedure or a procedure parameter The value specified for the argument 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 the value specified for the argument fCType and the driver specific value specified for the argument fSqlType The driver or data source does not support the value specified for the argument fSq Type 2 of 2 IN
139. 1 ee ee a 8 5 Error Text Format 2 2 2 1 ee een 8 5 Sample Error Messages 2 1 ww eee ee es 8 6 Sample Error Returned fromthe Driver 8 6 Sample Error Returned from the Driver Manager 8 7 Sample Error Returned from the DataSource 8 7 Processing Error Messages n we ee ee e 8 8 8 2 INFORMIX CLI Programmer s Manual his chapter defines INFORMIX CLI return codes 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 SQLError 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 information is available SQL_SUCCESS_WITH_INFO Function completed successfully possibly with a nonfatal error The application can call SQLError to retrieve additional information SQ
140. 11 SQL Grammar B 19 Hements Used in SQL Statements B 20 INFORMIX CLI Programmer s Manual SQL Conformance Element Level table reference table name Minimum table reference table name correlation name Core table reference table name correlation name Extended ODBC outer join extension A SELECT statement can contain only one table reference that is an ODBC outer join extension table reference list table reference table reference Core term factor term factor Minimum timestamp separator Extended The blank character timestamp type timestamp types Extended For example TIMESTAMP To determine the type name used by a data source an application calls SQLGetTypeInfo timestamp value date value timestamp separator Extended time value seconds fraction unsigned integer digit Minimum upper case letter Minimum AIBICIDIEIFIGIHITIJIKILIMI NIOIPIQIRISITIUIVIWIXIYIZ user defined name letter digit letter _ Minimum user name user defined name Core value literal USER dynamic parameter Core 10 of 11 List of Reserved Keywords SQL Conformance Element Level viewed table identifier user defined name Core viewed table name viewed table identifier Core owner name viewed table identifier qualifier name qualifier separator viewed table identifier qualifier name qualifier separator owner name viewed table identifier The t
141. 13 111 SQL ExecDirect SQLSTATE 01000 01004 01006 01803 Diagnostics Error General warning Data truncated Privilege not revoked No rows updated or deleted 13 112 INFORMIX CLI Programmer s Manual When SQLExecDirect returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLExecDirect 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 SQLSTATE value is SQL_ERROR unless noted otherwise Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The argument szSqlStr 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 szSqlStr 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 The argument szSqlStr contained a REVOKE statement and the user did not have the specified privilege function returns SQL_SUCCESS_WITH_INFO The argument szSqlStr contained a positioned UPDATE or DE
142. 13 132 Binding If any columns in the result set have been 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 this is the default value To bind each column 1 The application allocates an array of data storage buffers The array has as many elements as the rowset has rows plus an additional element if the application searches for key values or appends new rows of data The size of each buffer is the maximum size of the C data that can be returned for the column For example when the C data type is SOQL_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 Data Types on page C 13 and Precision Scale Length and Display Size on page C 8 2 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 rowset has rows 3 The application calls SOLBindCol m The rgbValue argument specifies the address of the data storage array m The cbValueMax argument specifi
143. 13 323 SQL Transact SQLTransact SQLTransact requests a commit or rollback operation for all active operations on all hstmts associated with a connection SQLTransact can also request that a commit or rollback operation be performed for all connections associated with the henv Syntax RETCODE SQLTransact henv hdbc flype The SQLTransact function accepts the following arguments Type Argument Use Description HENV henv Input Environment handle HDBC hdbc Input Connection handle UWORD fType Input One of the following two values SQL_COMMIT SQL_ROLLBACK Return Codes SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE 13 324 INFORMIX CLI Programmer s Manual Diagnostics SQLTransact When SOLTransact returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLTransact 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 08003 08007 S1000 S1001 Error General warning Connection not open Connection failure during transaction General error Memory allocation failure Description INFORMIX CLI informational message Function returns SQL_SUCCE
144. 156 uniquely identifying row 13 303 See also Results sets See also Retrieving data See also SQL data types See also Tables Comment Icons Intro 9 COMMIT statements interoperability 6 9 13 120 SQLExecute 13 127 SQLPrepare 13 250 Committing transactions 13 329 COMMIT in SQLExecDirect 13 120 Compliance icons Intro 10 Concurrency defined 7 12 serializability 7 12 specifying 13 287 supported types 13 208 ConfigDSN function description 14 3 with SQLRemoveDSNFromIni 14 6 with SQLWriteDSNTolni 14 6 with SQLWritePrivateProfileString 14 6 ConfigTranslator function description 14 7 See also Translation setup shared library Configuring data sources See Data sources configuring Conformance API levels 1 12 ODBC standards 1 12 SQL grammar 1 14 Conformance levels by function 13 179 determining 13 205 in ODBC 1 0 7 14 SQL B 4 C 2 See also API conformance See also SQL conformance Connection handles active 13 192 allocating 5 5 13 13 defined 3 7 freeing 9 4 overwriting 13 13 SQLFreeConnect 13 152 with threads 13 13 Connection options access mode 13 105 commit mode 13 278 dialog boxes 13 280 login interval 13 105 maximum length 13 162 13 277 packet size 13 279 releasing 13 277 reserved 13 277 retrieving 13 160 setting 13 277 trace file 13 279 tracing 13 279 Connection string for Informix driver UNIX 2 13 2 28 Connection strings browse request 13 45 browse result 13 45 special characters 13 45 13 46 SQ
145. 192 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 on page 6 7 3 Retrieves information about the result set if necessary For more information see Determining the Characteristics of a Result Set on page 7 4 4 Calls SQLExecute to execute the statement 5 Repeats steps 2 through 4 as necessary INFORMIX CLI Programmer s Manual Direct Execution Direct Execution Execute a statement directly if both of the following situations 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 SOLExecDirect to execute the statement Setting Parameter Values An SQL statement can contain parameter markers that indicate 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
146. 2 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_ERROR or SQL_INVALID_HANDLE When SQLDataSources returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLDataSources 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 01004 S1000 S1001 S1090 S1103 Error General warning Data truncated General error Memory allocation failure Invalid string or buffer length Direction option out of range SQLDataSources Description 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 untrun cated data source description function returns SQL_SUCCESS_WITH_INFO An error occurred for which no specific SQLSTATE existed and for which no implement
147. 2 fSqlType Test SQLSTATE SQL_CHAR Length of data lt Column length N A SQL_VARCHAR Length of data gt Column length 01004 SQL_LONGVARCHAR SQL_DECIMAL Length of data SQL data length N A SQL_SMALLINT Length of data SQL data length 22003 SQL_INTEGER SQL_REAL SQL_DOUBLE 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 Length of 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 might be different than the column length as defined Precision Scale Length and Display Size on page C 8 C to SQL Date The date ODBC C data type is SQL_C_DATE The following table shows the ODBC SQL data types to which date C data can be converted For an explanation of the columns and terms in the table see Converting Data from C to SQL Data Types on page C 24 fSqlType Test SQLSTATE SQL_CHAR Column length 10 N A SQL_VARCHAR Column length lt 10 22003 SQL_LONGVARCHAR Data value is not a valid date 22008 1 of 2 INFORMIX CLI Programmer s Manual C to SQL Time fSqlType Test SQLSTATE 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 aData value is not a valid date 22008 a The time portion of the time stamp is set to zero 2 of 2 For inf
148. 203 multiple result sets 7 13 13 229 Index 9 privileges 13 67 qualifier usage in 13 207 reexecuting 13 127 UNION clauses 13 213 See also Result sets Sensitivity cursor 13 210 Separator qualifier 13 207 Serializability 7 12 Serializable isolation level 13 196 Server name 13 209 Shared library See specific shared library Signed columns 13 61 Signed data types 13 224 Simulated cursors by applications 13 303 Size display 13 58 C 12 Sorting 13 203 13 313 Special characters in search patterns 13 10 in SQL identifiers 13 209 in SQLBrowseConnect 13 45 13 46 SQL conformance definition of 1 14 data types See SQL data types dynamic D 7 embedded executing statements 6 5 ODBC function equivalents D 1 D 5 D 6 information types 13 190 13 191 interoperability 6 3 B 1 keywords B 21 ODBC extensions to 6 12 ODBC grammar B 1 referential integrity B 1 static 10 4 See also SQL statements SQL Access Group 13 205 SQL data types columns indexes 13 312 result sets 13 57 tables 13 73 13 222 conformance levels C 2 conversion examples C 23 C 36 10 INFORMIX CLI Programmer s Manual converting from C data types C 24 converting to C data types C 13 default C data types C 6 display size C 12 in translation shared libraries 15 4 15 7 length C 11 parameters B 2 precision C 9 scale C 10 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 supported 13 73 13 221 13 222 See also C data type
149. 3 124 SQLSTATE Error 1090 Invalid string or buffer length 1109 Invalid cursor position S 1C00 Driver not capable S1T00 Time out expired the hstmt INFORMIX CLI Programmer s Manual Description A parameter value set with SQLBindParameter was a null pointer and the parameter length value was not 0 SQL_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 or SQL_DATA_AT_EXEC or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET The prepared statement was a positioned UPDATE or DELETE statement and 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 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 4 of 4 SQLExecute can return any SQLSTATE that can be returned by SQLPrepare based on when the data source evaluates the SOL statement associated with SQLExecute Usage SQLExecute executes a statement prepared by SQLPrepare Once the application processes or discards t
150. 3 211 Isolation level INFORMIX 5 driver 1 16 INFORMIX 7 driver 1 16 Isolation levels transaction 13 196 J Joins outer described 6 16 support of 13 205 K Keys primary 13 255 Keyset driven cursors 7 10 Keywords data source specific 13 201 in SQLBrowseConnect 13 45 in SQLDriverConnect 13 101 ODBC B 21 L Length available SQLBindParameter 13 36 SQLExtendedFetch 13 135 SQLFetch 13 150 SQLGetData 13 173 Length buffer input 3 5 output 3 6 SQLBindCol 13 23 SQLBindParameter 13 34 SQLGetData 13 173 Length column defined C 11 result sets 13 87 tables 13 73 13 305 Length data at execution 13 35 13 36 Length maximum buffers 3 5 column names length 13 201 columns 13 150 13 173 connection options 13 162 13 277 cursor names 13 202 13 285 data 13 294 error messages 13 111 indexes 13 202 owner name 13 202 procedure names 13 202 qualifiers 13 202 rows 13 202 statement options 13 217 13 291 user names 13 203 Length unknown in length C 11 in precision C 9 SQLBindParameter 13 36 SQLExtendedFetch 13 135 SQLFetch 13 150 SQLGetData 13 173 Level 1 API for INFORMIX driver 1 13 list of functions 1 13 Level 2 API for INFORMIX driver 1 13 list of functions 1 13 Levels conformance See Conformance levels Library handles driver 13 197 LIKE predicates support of 13 201 Limitations SQL statements 13 191 Literals character 13 201 date 6 13 prefix string 13 222 procedure parameters 6 17 suffix
151. 324 Asterisk 13 46 Question mark browse result connection string 13 46 parameter markers 13 120 13 250 _ Underscore 13 10 braces 13 46 14 INFORMIX CLI Programmer s Manual
152. 420 Key West Avenue Rockville MD 20850 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 Software Development Kit Version 2 0 Documentation Team Twila Booth Diana Chase Geeta Karmarkar Katherine Schaefer 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 Programmer s Manual Chapter 1 Table of Contents Introduction About This Manual Organization of This Manual Types of Users Software Dependen
153. 7 x for the stores7 database might look like the following example Stores7 Driver usr informix cli dlls qeinf708 so Database stores LogonID Mary In this example the data source and database are both called stores7 and the user ID is Mary You might want the database and data source names to be the same so that when you connect to a data source you know the specific database to which you are connecting Tip Data source names are case insensitive That is stores7 and Stores7 refer to the same data source Sample Data Source Entry for odbc ini A complete odbc ini data source entry for the stores7 data source that is described in the procedure for adding a data source on page 2 8 might look like the following example ODBC Data Sources Stores7 Informix Driver Stores7 Driver usr informix cli dlls qeinf708 so Database stores LogonID Mary 2 10 INFORMIX CLI Programmer s Manual Modifying a Data Source Modifying a Data Source To edit a data source use a text editor such as the vi editor Open your odbc ini file and modify the appropriate lines in that file The sections that make up this file are described in Adding a Data Source on page 2 6 Connecting to a Data Source An INFORMIX CLI application can pass connection information in several ways For example the application might have the driver prompt the user for connection information or the application might expect a connection string tha
154. BindCol 20 times do rc SQLFetch hstmt while rc SQL_SUCCESS rc SQL_SUCCESS_WITH_INFO The number of ODBC calls made is reduced from greater than 1890 to about 110 20 calls to SQLBindCol 91 calls to SOLFetch In addition to reducing the call load many drivers optimize use of SQLBindCol by binding result information directly from the DBMS 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 infor mation from the server be placed directly into the user s buffer INFORMIX CLI Programmer s Manual Use SQLExtendedFetch instead of SQLFetch Use SQLExtendedFetch instead of SQLFetch Use SQLExtendedFetch instead of SQLFetch to retrieve data The ODBC call load decreases resulting in better performance and the code is less complex resulting in more maintainable code Again consider the preceding example using SQLExtendedFetch instead of SQLFetch rc SQLSetStmtOption hstmt SQL_ROWSET_SIZE 100 use arrays of 100 elements rc SQLExecDirect hstmt SELECT lt 20 columns gt FROM Employees WHERE HireDate gt SQL_NTS call SQLBindCol 1 time specifying row wise binding do rc SQLExtendedFetch hstmt SQL_FETCH_NEXT 0 amp RowsFetched RowStatus while re SQL_SUCCESS re SQL_SUCCESS_WITH_INFO The number of ODBC calls made
155. CESS for each hdbc If the driver manager receives SQL_ERROR on one or more hdbcs it returns SQL_ERROR to the application To determine which connection s failed during the COMMIT or ROLLBACK operation the application can call SQLError 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 henv is ignored and the driver manager calls SOLTransact in the driver for the hdbc If hdbc is SQL_NULL_HDBC and henv is SQL_NULL_HENV SOLTransact returns SOQL_INVALID_HANDLE If fType is SQL_COMMIT SQLTransact issues a COMMIT request for all active operations on any hstmt associated with an affected hdbc If fType is SQL_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 13 326 INFORMIX CLI Programmer s Manual SQLTransact If the driver is in manual commit mode by calling SOLSetConnectOption with the SQL_LAUTOCOMMIT option set to zero a new transaction is implicitly started 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_BE
156. CHAR 128 not NULL IS_GRANTABLE VARCHAR 3 SQLColumnPrivileges 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 refer ential 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 13 8 Code Example For a code example of a similar function see SQLColumns INFORMIX CLI Function Reference 13 65 SQLColumns 13 66 Related Functions For information about Canceling statement processing Returning the columns in a table or tables Fetching a block of data or scrolling through a result set Fetching a row of data Returning privileges for a table or tables Returning a list of tables in a data source SQLColumns Syntax
157. CLI options Prepare and submit SQL requests Retrieve results and information about results Obtain information about server system tables 1 4 INFORMIX CLI Programmer s Manual Advantages of Using INFORMIX CLI Advantages of Using INFORMIX CLI Based on the Microsoft Open Database Connectivity ODBC Specification a call level interface such as INFORMIX CLI is typically used for dynamic access INFORMIX CLI is similar to the dynamic embedded version of SQL described in the X Open and SQL Access Group CAE specification 1992 Applications written with INFORMIX CLI do not need embedded Structured Query Language SQL statements Instead they pass SQL statement strings to INFORMIX CLI functions as arguments For a comparison between embedded SQL statements and the ODBC call level interface on which INFORMIX CLI is based see Appendix D INFORMIX CLI is very straightforward to application developers who are familiar with function libraries The function call interface does not require host variables or other embedded SQL concepts INFORMIX CLI does not require a preprocessor To submit an SQL request you place an SQL command into a text buffer and pass the buffer as a parameter in a function call INFORMIX CLI functions provide declarative capabilities and request management You obtain error information as you do for any function call by return code or error function call depending on the application INFORMIX CLI allo
158. CT statement but a specified table name or view name did not exist The argument szSqlStr contained a DELETE INSERT or UPDATE statement but the specified table name did not exist The argument szSqlStr 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 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 4 of 6 INFORMIX CLI Function Reference 13 115 SQL ExecDirect 13 116 SQLSTATE Error S0021 Column already exists S0022 Column not found S1000 General error S1001 Memory allocation failure S1008 Operation canceled S1009 Invalid argument value INFORMIX CLI Programmer s Manual Description The argument szSqlStr 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 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 CREAT
159. CUR_LOCK Cursor uses the lowest level of locking sufficient to ensure that the row can be updated SQL_CONCUR_ROWVER Cursor uses optimistic concurrency control comparing row versions 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 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 specified concurrency is not supported by the data source the driver substitutes a different concurrency and returns SQLSTATE 01502 Option value changed For SQL_CONCUR_VALUES the driver substitutes SQL_CONCUR_ROWVER and vice versa
160. Col to bind any columns SQLFetch does not return any data it moves the cursor to the next row An application can call SQLGetData to retrieve data that is not bound to a storage location 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 m SQLFetch accesses column data in left to right order m After each fetch pcbValue specified in SQLBindCol contains the number of bytes that are available to return for the column This is the number of bytes that are available prior to calling SQLFetch If the number of bytes that are available to return cannot be deter mined in advance the driver sets pcbValue to SQL_NO_TOTAL If SQL_MAX_LENGTH has been specified with SOLSetStmtOption and the number of bytes that are available to return is greater than SQL_MAX_LENGTH pcb Value contains SQL_MAX_LENGTH Tip 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 cbValueMax argument m If rgbValue cannot hold the entire result the driver stores part of the value and returns SQL_SUCCESS_WITH_INFO A subsequent call to SQLError indicates that a truncation occurred The application can compare pcbValue to cbValueMax specified
161. DATE and UNIONS m Date and time stamp data m The following numeric functions abs acos asin atan atan2 cos cot exp log log10 mod power round sin sqrt tan truncate 1 14 INFORMIX CLI Programmer s Manual Mapping Data Types The following date functions curdate dayofweek now dayofmonth month year The following string functions concat LTRIM length RTRIM The user system function Data types LONG VARBINARY DATE and TIMESTAMP Procedure calls For more information on the numeric date string and system functions refer to Informix Guide to SQL Syntax Mapping Data Types INFORMIX CLI maps Informix data types to their appropriate ODBC SQL data types The following table lists the Informix data type and its corresponding ODBC SQL data type Informix Data Type ODBC SQL Data Type BYTE SQL_LONGVARBINARY CHAR CHARACTER SQL_CHAR DATE SQL_DATE DATETIME year to fraction 5 SQL_TIMESTAMP DECIMAL DEC NUMERIC SQL_DECIMAL FLOAT SQL_DOUBLE INTEGER INT SQL_INTEGER INTERVAL SQL_CHAR MONEY SQL_DECIMAL 1 of 2 Overview of INFORMIX CLI 1 15 Supported Isolation and Lock Levels 1 16 Informix Data Type ODBC SQL Data Type SERIAL SQL_INTEGER SMALLFLOAT REAL SQL_REAL SMALLINT SQL_SMALLINT TEXT SQL_LONGVARCHAR VARCHAR CHARACTER VARYING SQL_VARCHAR 2 of 2 Not supported for INFORMIX SE databases For more information on data types see Appendix C Supported Isolation and Lock Levels If co
162. Data SQLParamData SQLPrepare SQLPutData SQLSetCursorName SQLSetStmtOption SQLTransact INFORMIX CLI Function Reference 13 119 SQL Execute 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 SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_NEED_DATA SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLExecute returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SOLSTATE values commonly returned by SQLExecute 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 SQLSTATE value is SQL_ERROR unless noted otherwise 13 120 INFORMIX CLI Programmer s Manual SQLSTATE 01000 01004 01006 01503 01504 07001 08S01 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 SQLExecute Description INFORMIX CLI informational message Func
163. Driver and Data Source Setting and Retrieving Driver ee Preparing SQL Requests Submitting SQL Requests s Retrieving Results and Information about Results Obtaining Information About Data Source System Tables Terminating a Statement Terminating a Connection Setup Shared Library Function Summary Translation Shared Library Function Summary 12 3 12 4 12 4 12 5 12 5 12 6 12 7 12 8 12 9 12 9 12 10 12 10 12 2 INFORMIX CLI Programmer s Manual his chapter summarizes the functions that INFORMIX CLI enabled applications and related software use m INFORMIX CLI functions 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 task 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 Level of INFORMIX CLI on page 1 12 For more information about the syntax and semantics for each function see Chapter 13 INFORMIX CLI Function Reference An application can call the SQLGetInfo function to obtain conformance infor mation about a driver To obtain information about support for a specific function in a driver an application can call SQLGetFunctions Function Summary 12 3 Connecting to a Data Source 12 4 ODBC Fu
164. E DATA_TYPE PRECISION LITERAL_PREFIX LITERAL_SUFFIX INFORMIX CLI Programmer s Manual Data Type VARCHAR 128 not NULL SMALLINT not NULL INTEGER VARCHAR 128 VARCHAR 128 The lengths of VARCHAR columns shown in the following table are maximums the actual lengths depend on the data source Comments Data source dependent data type name for example CHAR VARCHAR MONEY LONG VARBINARY or CHAR FOR BIT DATA Applications must use this name in CREATE TABLE and ALTER TABLE statements SQL data type For a list of valid ODBC SQL data types see Appendix C For information on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 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 C 8 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 Column Name CREATE_PARAMS NULLABLE CASE_SENSITIVE Data Type VARCHAR 128 SMALLINT
165. E 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 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 5 of 6 SQLSTATE 1010 S1090 S1109 S1C00 S1T00 Error Function sequence error Invalid string or buffer length Invalid cursor position Driver not capable Time out expired SQLExecDirect 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 argument cbSqlStr was less than or equal to 0 but not equal to SQL_NTS A parameter value set with SQLBindParameter was a null pointer and the parameter length value was not 0 SQL_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
166. EDURES N SQL_ACCESSIBLE_PROCEDURES N SQL_MAX_PROCEDURE_NAME_LEN 0 SQL_PROCEDURE_TERM Empty string SQLGetInfo returns SQLSTATE S1096 Invalid argument value for a value of finfoType that is not defined by the version of ODBC the driver supports To determine the version of ODBC to which a driver conforms an application calls SQLGetInfo with the SQL_DRIVER_ODBC_VER information type SQLGetInfo returns SQLSTATE S1C00 Driver not capable for values of finfoType that are in the range of information types reserved for driver specific use but that the driver does not support Information Types This section lists the information types supported by SQLGetInfo Infor mation types are grouped categorically and listed alphabetically INFORMIX CLI Function Reference 13 185 SQL Getinfo 13 186 Driver Information The following values of fInfoType return information about the Informix driver such as the number of active statements the data source name and the API conformance levels SQL_ACTIVE_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 SQL_GETDATA_EXTENSIONS SQL_LOCK_TYPES SQL_ODBC_API_CONFORMANCE SQL_ODBC_SAG_CLI_CONFORMANCE SQL_ODBC_VER SQL_POS_OPERATIONS SQL_ROW_UPDATES SQL_SEARCH_PATTERN_ESCAPE SQL_SERVER_NAME DBMS Product Information The following v
167. EOUT connection option set using SQLSetConnectOption defines the number of seconds to wait for a login request to complete before returning to the application If the user is prompted to complete the connection string a waiting period for each login request begins after the user has dismissed each dialog box The driver opens the connection in SQL_LMODE_READ_WRITE access mode by default To set the access mode to SQLLMODE_READ_ONLY the application must call SQLSetConnectOption with the SQL_ACCESS_MODE option before calling SQLDriverConnect If a default translation shared library is specified in the odbc ini file for the data source the driver loads it A different translation shared library can be loaded by calling SQLSetConnectOption with the SQL_TRANSLATE_DLL option A translation option can be specified by calling SQLSetConnec tOption with the SQL_TRANSLATE_OPTION option Related Functions For information about See Allocating a connection handle SQLAllocConnect Discovering and enumerating values SQLBrowseConnect required to connect to a data source Connecting to a data source SOLConnect Disconnecting from a data source SQLDisconnect Returning driver descriptions and SQOLDrivers attributes Freeing a connection handle SQLFreeConnect Setting a connection option SQLSetConnectOption INFORMIX CLI Function Reference 13 103 SQLDrivers SQLDrivers SQLDrivers lists driver descriptions and driver attribute keywords This
168. Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 01004 Data truncated 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 01S00 Invalid connection An invalid attribute keyword was specified in string attribute the connection string szConnStrIn but the driver connected to the data source anyway function returns SQL_SUCCESS_WITH_INFO 08001 Unable to connect The driver did not establish a connection with to data source the data source 08002 Connection in use DM The specified hdbc was used already to establish a connection with a data source and the connection was still open 08004 Datasource rejected The data source rejected the establishment of establishment of the connection for implementation defined connection reasons 1 of 4 INFORMIX CLI Function Reference 13 95 SQL DriverConnect 13 96 SQLSTATE 08S01 28000 IM002 IM003 IM004 IM005 IM006 IM007 IM008 Error Communication link failure Invalid authori zation specification Data source not found and no default driver specified Specified driver could not be loaded Driver SQLAI locEnv failed Driver SQLAIloc Connect failed Driver SQLSetConnect Option
169. FORMIX CLI Function Reference 13 27 SQL BindParameter 13 28 Usage An application calls SOLBindParameter to bind each parameter marker in an SQL statement Bindings are effective until the application calls SQLBindPar ameter again or until the application calls SQLFreeStmt with the SQL_DROP or SQL_RESET_PARAMS option For more information concerning parameter data types and parameter markers see Parameter Data Types on page B 2 and Parameter Markers on page B 3 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 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 pcebValue buffer must contain SQL_ NULL_DATA SQL_DATA_AT_EXEC or the result of the SOL_LEN_DATA_AT_ EXEC macro If an application cannot deter
170. FORMIX CLI Programmer s Manual SQLBindParameter pcebValue Argument The pebValue argument points to a buffer that when SQLExecute or SOLEx ecDirect is called contains one of the following values The length of the parameter value stored in rgbValue This is ignored except for character or binary C data SQL_NTS The parameter value is a null terminated string SQL_NULL_DATA The parameter value is NULL SQL_DEFAULT_PARAM A procedure is to use the default value of a parameter rather than a value retrieved from the application This value is valid only ina procedure call and then only if the fParamType argument is SQL_PARAM_INPUT or SQL_PARAM_INPUT_OUTPUT When pebValue is SQL_DEFAULT_PARAM the corresponding parameter can only be a parameter for an ODBC canonical procedure invocation When pebValue is SQL_LDEFAULT_PARAM the fCType fSqlType cbColDef ibScale cbValueMax 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 result of the SQL_LEN_DATA_AT_EXEC length macro The data for the parameter is sent with SQLPutData If the fSq Type argument is SQL_LONGVARBINARY SQL_LONGVARCHAR or a long data source specific data type and the driver returns Y for the SQL_NEED_LONG_DATA_LEN information type in SOLGetInfo length is the number of bytes of data to be sent for the parameter otherwise lengt
171. For SQL_CONCUR_LOCK the driver substitutes in order SQL_CONCUR_ROWVER or SQL_CONCUR_VALUES 2 of 5 13 290 INFORMIX CLI Programmer s Manual fOption SQL_CURSOR_TYPE SQL_KEYSET_SIZE SQL SetStmtOption vParam Contents A 32 bit integer value that specifies the cursor type SQL_CURSOR_FORWARD_ONLY The cursor only scrolls forward SQL_CURSOR_STATIC The data in the result set is static SQL_CURSOR_KEYSET_DRIVEN The driver saves and uses the keys for the number of rows specified in the SQL_KEYSET_SIZE statement option SQL_CURSOR_DYNAMIC The driver only saves and uses the keys for the rows in the rowset 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 SQLSetScrollOptions If the specified cursor type is not supported by the data source the driver substitutes a different cursor type and returns SQLSTATE 01502 Option value changed For a mixed or dynamic cursor the driver substitutes in order a keyset driven or static cursor For a keyset driven cursor the driver substitutes a static cursor A 32 bit integer value that specifies the number of rows in the keyset for a keyset driven cursor If the keyset size is 0 the default the cursor is fully keyset driven If the keyset size is greater than 0 the cursor is mixed keyset driven within the keyset and dynamic outside of the keyset The default key
172. Function Name SQLFreeStmt SQLCancel SQLTransact ODBC Conformance Core Core Core Terminating a Connection Purpose Ends statement processing and closes the associated cursor discards pending results and optionally frees all resources associated with the statement handle Cancels an SQL statement Commits or rolls back a transaction The following table describes functions that terminate a connection Function Name SQLDisconnect SQLFreeConnect SQLFreeEnv ODBC Conformance Core Core Core Purpose Closes the connection Releases the connection handle Releases the environment handle INFORMIX CLI does not support the following ODBC functions SQLForeignKeys SOLDescribeParam SOLProcedurColumns SQLSetPos Function Summary 12 9 Setup Shared Library Function Summary 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 14 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 Translation Shared Library Function Summary The following table describes translation shared library functions For more information about the syntax and semantics for each function see Chapter 15
173. HAVIOR options If the value of SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR equals SQL_CB_DELETE SQLTransact closes and deletes all open cursors on all hstmts 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 subse quent SQL requests or can call SOLFreeStmt to deallocate them If the value of SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR equals SQL_CB_CLOSE SQLTransact 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 SQLTransact with SQL_COMMIT retu
174. INFORMIX CLI Programmer s Manual SQLBindParameter 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 ODBC C data type and the SQL data type of the parameter and to bind a buffer to each parameter For each row of data the application assigns data values to each parameter and calls SQLExecute to execute the statement itdefine NAME_LEN 30 UCHAR szNameL 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 Li for Name Age Birthday parameter data SQLBindParameter 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 dsBirthday year 1952 dsBirthday month 2 dsBirthday day 29 retcode SQLExecute hstmt Execute statem
175. IX 7 2 Advanced Driver Setup L Enable Insert Cursors Yield Proc Cursor Behavior Enable Scrollable Cursors Get DB List From Informix Database List O Default User Name T 7 Protocol Type fo ciose fe 0 Disable v 1 Yes v lt No Translator gt MS Code Page Translator OEM to ANSI 8 To specify a translator click Translate Adding a Data Source Figure 2 7 The ODBC INFORMIX Advanced Driver Setup Dialog Box 7 Type the information you want to specify about this data source You can also choose options from the drop down lists For a description of the advanced connection options that are available see Optional Data Source Configuration Information on page 2 17 The Translator dialog box appears as Figure 2 8 illustrates Select Translator Select which ODBC translator you want to use from the list then click OK Figure 2 8 The Translator Dialog Box INFORMIX CLI 2 23 Modifying a Data Source 9 Select the translator you want from the list 10 Click OK to return to the ODBC INFORMIX Advanced Driver Setup dialog box 11 To accept your specifications for this data source click OK When you click OK in the ODBC INFORMIX Advanced Driver Setup dialog box the Data Sources dialog box appears as shown in Figure 2 4 12 To add another data source click Add To exit the Data Sources dialog box click Close After you click OK in the ODBC INF
176. Informix database server and describes the special features that the product offers It progresses from general topics to more advanced programming techniques and examples Introduction 3 Organization of This Manual 4 Organization of This Manual The INFORMIX CLI Programmer s Manual includes the following chapters m This Introduction provides an overview of the manual and describes the documentation conventions used m Chapter 1 Overview of INFORMIX CLI introduces INFORMIX CLI describes its relationship to ODBC describes the format of the initialization files and lists the API and SOL grammar conformance levels m Chapter 2 INFORMIX CLI explains how to set up the INFORMIX CLI driver and how to configure and connect to data sources for UNIX and Windows platforms m Chapter 3 Guidelines for Calling INFORMIX CLI Functions describes the role of the driver manager and the general character istics of INFORMIX CLI functions m Chapter 4 Basic Application Steps describes how an application uses the INFORMIX CLI interface to interact with a data source m Chapter 5 Connecting to a Data Source describes data sources and also describes how to establish a connection to a data source m Chapter 6 Executing SQL Statements describes the sequence of function calls INFORMIX CLI applications can use to execute SQL statements m Chapter 7 Retrieving Results describes the SQL statements
177. Initializing the Environment Before an application can use any other function it must initialize the INFORMIX CLI interface and associate an environment handle with the environment To initialize the interface and allocate an environment handle an application performs the following operations 1 Declares a variable of type HENV For example your application could use the following declaration HENV henvl 2 Calls SQLAIlocEnv and passes 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 These steps should be performed only once by your application SQLAllocEnv supports one or more connections to data sources 5 4 INFORMIX CLI Programmer s Manual Allocating a Connection Handle Allocating a Connection Handle Before your INFORMIX CLI application can connect to the driver you must allocate a connection handle for the connection To allocate a connection handle an application performs the following operations 1 Declares a variable of type HDBC For example the application could use the following declaration HDBC hdbcl 2 Calls SOLAIlocConnect and passes it the address of the variable The driver allocates memory to store information about the connection and returns the connection handle in the variable Connecting to a Data Source After allocating a connection handle you m
178. Invalid string or buffer length Driver not capable Time out expired 13 320 INFORMIX CLI Programmer s Manual Description 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 multi threaded 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 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 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 requested result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQL T
179. L Procedures is executed sEmpId and szRemark will have the values returned by AddEmployee ef retcode SQLExecDirect hstmt call AddEmployee SQL_NTS strcpy szName Jones Bob K Specify second row of sAge 52 parameter data dsBirthday year 1940 dsBirthday month 3 dsBirthday day 31 Execute procedure with second row of data After the procedure is executed sEmpId and szRemark will have the new values returned by AddEmployee w retcode SQLExecDirect hstmt call AddEmployee SQL_NTS Related Functions For information about See Assigning storage fora column ina result SQLBindCol set Canceling statement processing SQLCancel Fetching a block of data or scrolling SQLExtendedFetch through a result set Fetching a row of data SQLFetch Returning information about a driver or SQLGetInfo data source Syntax for invoking stored procedures Chapter 6 Executing SQL Statements 13 262 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 SQL_LONGVARBINARY or SQL_LONGVARCHAR Syntax RETCODE SQLPutData hstmt rgbValue cbValue
180. LAIlocEnv functions exist one within the driver manager and one within the driver The driver manager does not call the driver level function until the application calls SQLConnect SQLBrowseConnect or SQLDriverConnect If an error occurs in the driver level SQLAllocEnv function the driver manager level SQLConnect SQLBrowseConnect or SQLDriverConnect function returns SOQL_ERROR A subsequent call 13 12 INFORMIX CLI Programmer s Manual SQLAllocEnv toSQLError with henv SQL_NULL_HDBC and SQL_NULL_HSTMT returns SQLSTATE IM004 the driver SQLAIlocEnv function failed followed by one of the following errors from the driver m SQLSTATE S1000 General error m A INFORMIX CLI SQLSTATE value that ranges from S1000 to S19ZZ For example SQLSTATE S1001 Memory allocation failure indicates that the call from the driver manager to the driver level SQLAIlocEnv returned SQL_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 13 78 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 SQLAIlocEnv The driver allocates memory for the environment information and stores the value of the associated handle in the henv On operating systems that support
181. LDescribeCol result set Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SQLExecute Returning the number of result set columns SQLNumResultCols Setting a statement option SQOLSetStmtOption INFORMIX CLI Function Reference 13 143 SQLFetch SQLFetch SQLFetch fetches a row of data from a result set The driver returns data for all columns that were bound to storage locations with SQLBindCol Syntax RETCODE SQLFetch hstmt The SQLFetch function accepts the following argument Type Argument Use Description HSTMT hstmt Input Statement handle Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE 13 144 INFORMIX CLI Programmer s Manual Diagnostics When SOQLFetch returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLFetch 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 01004 07006 08S01 22002 Error General warning Data truncated Restricted data type attribute violation Communication link failure Indicator value required but not supplied SQLFetch
182. LDriverConnect 5 6 13 101 Connections dialog boxes 13 102 13 104 13 105 disconnecting 9 4 driver manager 13 80 function summary 12 4 12 9 in embedded SQL D 9 login information 5 8 SQLBrowseConnect 13 47 SQLConnect 13 80 SQLDisconnect 13 94 SQLDriverConnect 13 101 terminating browsing 13 48 Converting data C to SQL C 24 default conversions C 6 examples C 23 C 36 hexadecimal characters C 20 C 29 C 31 parameters 6 7 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 SQL to C C 13 SQLExtendedFetch 13 134 SQLFetch 13 22 SQLGetData 13 174 See also Translation shared libraries Core API for INFORMIX driver 1 13 list of functions 1 13 CREATE TABLE statements data type names B 1 interoperability 6 3 modifying syntax 6 3 NOT NULL clauses 13 203 Currency columns 13 59 Currency data types 13 224 Cursor position errors 13 139 required 7 13 13 174 SQLExtendedFetch 7 12 13 136 13 140 SQLFetch 13 150 Cursors block 7 9 closing cursors SQLCancel 13 52 SQLFreeStmt 9 3 described 7 6 dynamic 7 10 getting names 13 165 holes in 7 11 13 210 keyset driven 7 10 maximum name length 13 202 mixed 7 11 positioned statements 7 14 position See Cursor position scrollable 7 10 sensitivity 13 210 setting names 13 285 simulated 13 303 specifying type 7 12 SQLFreeStmt 13 156 static 7 10 supported types 13 208 transaction behavior 13 330 See also Concurrency See also Cursor library D
183. LETE statement and no rows were updated or deleted function returns SQL_SUCCESS_WITH_INFO 1 of 6 SQLSTATE 01504 07001 08S01 21501 21502 22003 22005 22008 Error More than one row updated or deleted Wrong number of parameters Communication link failure Insert value list does not match column list Degree of derived table does not match column list Numeric value out of range Error in assignment Datetime field overflow SQLExecDirect Description The argument szSqlStr contained 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 SQLBindParameter was less than the number of parameters in the SQL statement contained in the argument szSqlStr The communication link between the driver and the data source failed before the function completed The argument szSqlStr 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 specified is not the same degree as the derived table defined by the query specification The argument szSqlStr contained an SQL statement that contained a 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 a
184. LUES Cursor uses optimistic concurrency control comparing values For information about cursor concurrency see Specifying Cursor Concurrency on page 7 12 17 of 22 InfoType SQL_SCROLL_OPTIONS SQL_SEARCH_PATTERN_ESCAPE SQL_SERVER_NAME SQL_SPECIAL_CHARACTERS SQLGetInfo Returns A 32 bit bitmask that enumerates the scroll options supported for scrollable cursors The following bitmasks are used to determine which options are supported SQL_SO_FORWARD_ONLY The cursor only scrolls forward SQL_SO_STATIC The data in the result set is static SQL_SO_KEYSET_DRIVEN The driver saves and uses the keys for every row in the result set SQL_SO_DYNAMIC The driver keeps the keys for every row in the rowset the keyset size is the same as the rowset size SQL_SO_MIXED The driver keeps the keys for every row in the keyset and the keyset size is greater than the rowset size The cursor is keyset driven inside the keyset and dynamic outside the keyset For information about scrollable cursors see Scrollable Cursors on page 7 10 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 p
185. L_FD_FETCH_PRIOR SQL_FD_FETCH_ABSOLUTE SQL_FD_FETCH_RELATIVE SQL_FD_FETCH_RESUME A 16 bit integer value that indicates how a single tier driver directly treats files in a data source SQL_FILE_NOT_SUPPORTED The driver is not a single tier driver 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 SQL_FILE_QUALIFIER A single tier driver treats files in a data source as a qualifier 7 of 22 InfoType SQL_GETDATA_EXTENSIONS SQLGetInfo Returns A 32 bit bitmask that enumerates extensions to SQLGetData The following bitmasks are used in conjunction with the flag to determine what common extensions the driver supports for SQLGetData SQL_GD_ANY_COLUMN SQLGetData 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 SQL_GD_ANY_ORDER is also returned SQL_GD_ANY_ORDER SQLGetData can be called for unbound columns in any order SQLGetData can 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 SQL_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 in
186. L_NO_DATA_FOUND All rows from the result set have been fetched 1 of 2 Retrieving Status and Error Information 8 3 Retrieving Error Messages 8 4 Return Code Description SQL_ERROR Function failed The application can call SQLError to retrieve error information SQL_INVALID_HANDLE Function failed due to an invalid environment handle connection handle or statement handle This situation indicates a programming error No additional information is available from SQLError SQL_NEED_DATA While the driver was processing a statement it determined that the application needs to send parameter data values 2 of 2 The application is responsible for taking the appropriate action based on the return code Retrieving Error Messages If a function other than SQLError returns SQL_ERROR or SQL_SUCCESS_WITH_INFO an application can call SQLError to obtain additional information The application might need to call SQLError 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 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
187. L_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQOLColAttributes returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLColAttributes 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 SQLSTATE value is SQL_ERROR unless noted otherwise INFORMIX CLI Function Reference 13 53 SQL ColAttributes 13 54 SQLSTATE Error 01000 General warning 01004 Data truncated 24000 Invalid cursor state 1000 General error S1001 Memory allocation failure S1002 Invalid column number S1008 Operation canceled INFORMIX CLI Programmer s Manual Description 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 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 de
188. M An invalid fFunction value was specified SQLGetFunctions Usage SQOLGetFunctions always returns that SOLGetFunctions SOQLDataSources and SQLDrivers are supported It does so because these functions are imple mented in the driver manager 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_SQLBINDCOL SQL_API_SQLCANCEL SQL_API_SQLCOLATTRIBUTES SQL_API_SQLCONNECT SQL_API_SQLDESCRIBECOL SQL_API_SQLDISCONNECT SQL_API_SQLERROR SQL_API_SQLEXECDIRECT SQL_API_SQLEXECUTE SQL_API_SQLFETCH SQL_API_SQLFREECONNECT SQL_API_SQLFREEENV SQL_API_SQLFREESTMT SQL_API_SQLGETCURSORNAME SQL_API_SQLNUMRESULTCOLS SQL_API_SQLPREPARE SQL_API_SQLROWCOUNT SQL_API_SQLSETCURSORNAME SQL_API_SQLSETPARAM SQL_API_SQLTRANSACT INFORMIX CLI Function Reference 13 177 SQL GetFunctions 13 178 The following list identifies valid values for fFunction for ODBC extension level 1 functions that the INFORMIX CLI driver supports m SQL_API_SOLBINDPARAMETER SQL_API_SQLCOLUMNS SQL_API_SOQLDRIVERCONNECT SQL_API_SQLGETCONNECTOPTION SQL_API_SQLGETDATA SQL_API_SQLGETFUNCTIONS SQL_API_SOQLGETINFO SQL_API_SOQLGETSTMTOPTION SQL_API_SOQLGETTYPEINFO SQL_API_SOQLPARAMDATA SQL_API_SQLPUTDATA SQL_API_SOQLSETCONNECTOPTION SQL_API_SOQLSETSTMTOPTION SQL_API_SOQLSPECIALCOLUMNS SQL_API_SOLSTATISTICS SQL_API_SOLTABLES The fol
189. NFORMIX driver 1 15 Strings connection See Connection strings SYNONYM table type 13 325 Syntax connection strings 13 45 13 46 13 101 ODBC SQL 6 12 SQL B 11 System functions supported by INFORMIX driver 1 15 System requirements for INFORMIX CLI UNIX 2 4 for INFORMIX CLI Windows 2 15 SYSTEM TABLE table type 13 325 T Table definition statements qualifier usage in 13 207 TABLE table type 13 325 Tables accessibility 13 192 cardinality 13 313 columnsSee Columns 13 62 defined 13 9 in SELECT statement 13 203 indexes See Indexes maximum columns in 13 202 names maximum length 13 203 retrieving 13 311 13 318 special characters 13 209 SQLColumnPrivileges 13 66 SQLColumns 13 72 SQLTables 13 324 13 325 owner nameSee Owner names 13 66 pages 13 313 primary keys 13 256 qualifierSee Qualifiers 13 66 rows See Rows statistics 13 310 term vendor specific 13 210 types 13 325 versus views 13 9 Termination byte null See Null termination byte Terms vendor specific owner 13 206 procedure 13 206 qualifier 13 207 table 13 210 Threads multiple with connection handles 13 13 with environment handles 13 15 with statement handles 13 18 Time data converting to SQL C 33 literals 6 13 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 Time out login 13 105 query 13 294 Timestamp data converting to C C 22 converting to SQL C 34 literals 6 13 specifying conversions SQLBindCol
190. NFORMIX CLI Programmer s Manual When SQLColumnPrivileges returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLColumnPrivileges and explains each one 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 SQOLSTATE value is SOL_ERROR unless noted otherwise 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 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 The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded 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 1 of 2 SQLSTATE S1090 S1C00 S1T00
191. NFORMIX CLI Programmer s Manual specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 using 3 8 See also SQL data types Call Level Interface CLI support of 13 205 Canceling connection browsing 13 94 data at execution 13 53 Cardinality 13 313 Case sensitivity columns 13 58 data types 13 223 quoted SQL identifiers 13 208 Catalog functions list of 6 9 search patterns 13 10 summary 12 8 Character data case sensitivity 13 223 converting to C C 15 converting to SQL C 27 empty string 3 5 literal length 13 201 prefix string 13 222 suffix string 13 222 null termination byte 3 6 13 35 retrieving in parts 13 167 13 174 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 Character sets 5 9 Characters escape 13 10 Characters special See Special characters CLI See Call Level Interface Closing cursors 13 156 13 194 SQLCancel 13 52 SQLFreeStmt 9 3 Clustered indexes 13 312 Code examples ad hoc query 10 7 parameter values 6 8 static SQL 10 4 See also specific function description Codes return 8 3 Collating 13 203 13 312 Columns aliases 13 193 attributes 13 57 13 91 binding See Binding columns in GROUP BY clauses 13 201 in indexes 13 201 in select list 13 202 in tables 13 202 listing 13 71 maximum name length 13 201 nullability 13 203 number of 13 58 13 235 precision See Precision primary keys 13 255 pseudo 13 305 signed 13 61 unbinding 13 23 13
192. NLY 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 rgetL0 cbName SQLBindCol hstmt 2 SQL_C_SSHORT amp rget 0 sAge 0 amp argetL0 cbAge SQLBindCol hstmt 3 SQL_C_CHAR rget 0O szBirthday BDAY_LEN amp rgetL0 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 rgfRowStatus if retcode SQL_ERROR retcode SQL_SUCCESS_WITH_INFO show_error if retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO for jrow 0 irow lt crow irowt if rgfRowStatusLirow SQL_ROW_DELETED amp amp rgfRowStatuslirow SQL_ROW_ERROR INFORMIX CLI Programmer s Manual SQLExtendedFetch fprintf out s 2d s NAME_LEN 1 rgetLirow szName rgetLirow sAge BDAY_LEN 1 rgetLirow szBirthday else break Related Function The following table shows where to find information about related functions For information about See Assigning storage for a column ina result set SQLBindCol Canceling statement processing SQLCancel Returning information about acolumnina SQ
193. NVALID_HANDLE INFORMIX CLI Function Reference 13 175 SQL GetFunctions SQLSTATE 01000 S1000 S1001 S1010 S1095 Diagnostics Error General warning General error Memory allocation failure Function sequence error Function type out of range 13 176 INFORMIX CLI Programmer s Manual When SQLGetFunctions returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLGet Functions 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 SQLSTATE value is SQL_ERROR unless noted otherwise 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 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 SQLGetFunctions was called before SQLConnect SOLBrowseConnect or SQLDriverConnect DM SQLBrowseConnect was called for the hdbc and returned SQL_NEED_DATA This function was called before SQLBrowseConnect returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS D
194. OQLColumns SQLExtendedFetch SQLFetch SQLStatistics SQLTables INFORMIX CLI Function Reference 13 317 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 szTableQualifier cbTableQualifier szTableOwner cbTableOwner szTableName cbTableName szTableType cbTableType The SQLTables function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle for retrieved results UCHAR FAR szTableQualifier Input Qualifier name If a driver supports qualifiers 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 SWORD cbTableQualifier Input Length of szTableQualifier UCHAR FAR szTableOwner Input String search pattern for owner names SWORD cbTableOwner Input Length of szTableOwner UCHAR FAR szTableName Input 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 1 of 2 13 318 INFORMIX CLI Programmer s Manual SQL Tables Type Argument Use Description SWORD cbTableName Input Length of szTableName UCHAR FAR szTableType Input List
195. OR FOREIGN FORTRAN FOUND FROM FULL GET GLOBAL GO GOTO GRANT GROUP HAVING HOUR IDENTITY IGNORE IMMEDIATE Z NCLUDE NDEX NDICATOR NITIALLY NNER NPUT NSENSITIVE I I I I I I I I INFORMIX CLI Programmer s Manual INSERT INTEGER INTERSECT INTERVAL INTO IS ISOLATION JOIN KEY LANGUAGE LAST LEFT LEVEL LIKE LOCAL LOWER MATCH MAX MIN MINUTE MODULE MONTH MUMPS NAMES NATIONAL NCHAR NEXT NONE NOT NULL NULLIF NUMERIC OCTET_LENGTH List of Reserved Keywords SQL Grammar B 25 List of Reserved Keywords OF OFF ON ONLY OPEN OPTION OR ORDER OUTER OUTPUT OVERLAPS PARTIAL PASCAL PLI POSITION PRECISION PREPARE PRESERVE PRIMARY PRIOR PRIVILEGES PROCEDURE PUBLIC RESTRICT REVOKE RIGHT ROLLBACK ROWS SCHEMA SCROLL SECOND SECTION SELECT B 26 INFORMIX CLI Programmer s Manual List of Reserved Keywords SEQUENCE SET SIZE SMALLINT SOME SOL SQLCA SQLCODE SQLERROR SOLSTATE SQLWARNING SUBSTRING SUM SYSTEM TABLE TEMPORARY THEN TIME TIMESTAMP TIMEZONE_HOUR TIMEZONE_MINUTE TO TRANSACTION TRANSLATE TRANSLATION TRUE NION NIQUE NKNOWN PDATE PPER SAGE SER Gee MG eee SQL Grammar B 27 List of Reserved Keywords B 28 USING VALUE VALUES VARCHAR VARYING VIEW WHEN WHENEVER WHERE WITH WORK YEAR INFORMIX CLI Programmer s Manual Data Types Data stored on a data source has an SQL data type
196. ORMIX Driver Setup dialog box the ODBC Administrator updates your ODBC INI file or Registry The information that you entered in any of the setup dialog boxes becomes the new default data source connection information for this data source Modifying a Data Source Use the ODBC Administrator to make all modifications to your data source To make basic modifications to the defaults for a data source see Using Dialog Boxes to Connect to a Data Source on page 25 To make more detailed modifications to a data source complete the following steps To modify a data source 1 Start the ODBC Administrator The Data Sources dialog box appears as Figure 2 9 illustrates Figure 2 9 The Data Sources Dialog Box User Data Sources Driver Close Stores7 Informix Help Setup Delete Add 2 24 INFORMIX CLI Programmer s Manual Data Source Name Description Database Name Modifying a Data Source 2 In the Data Sources dialog box select the Informix data source that you want to modify and then click Setup The ODBC INFORMIX Driver Setup dialog box appears as Figure 2 10 illustrates The values that appears the default entries specified for this data source connection ODBC INFORMIX 7 2 Driver Setup r P a INFORMIX Driver OK Stores7 Setup Dialog Box Cancel Informix demonstration database Help Stores7 Advanced
197. QL 92 A 2 SQLSTATEs 01000 01002 01004 01006 01500 01S01 01502 01503 INFORMIX CLI Programmer s Manual 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 A return value of SQL_SUCCESS normally indicates a function has executed successfully although the SQLSTATE 00000 also indicates success Can be returned from All INFORMIX CLI functions except SQLAllocEnv SQLError SQLDisconnect SQLBrowseConnect SQLColAttributes SQLDataSources SQLDescribeCol SQLDriverConnect SQLDrivers SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLGetCursorName SQLGetData SQLGetInfo SQLNativeSql SQLPutData SQLExecDirect SQLExecute SQLBrowseConnect SQLDriverConnect SQLExtendedFetch SQLSetConnectOption SQLSetStmtOption SQLExecDirect SQLExecute 1 of 13 SQLSTATEs 01504 07001 07006 08001 08002 08003 08004 08007 Error More than one row updated or deleted Wrong number of parameters Restricted data type attribute violation Unable to connect to data source Connection in use Connection not open Data source rejected estab lishment of connection Connection failure during transaction Can be returned from SQLExecDirect SQLExecute SQLExecDirect SQLExecute SQLBindParameter SQLExtendedFetch SQLFetch SQLG
198. QLExtendedFetch Fetching a row of data SQLFetch Returning table statistics and indexes SQLStatistics Returning a list of tables in a data source SQLTables Returning privileges for a table or tables SQLTablePrivileges 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 SQLConnect 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 SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 75 SQLConnect SQLSTATE 01000 08001 08002 08004 08S01 28000 IM002 IMO003 13 76 Diagnostics Error General warning Unable to connect to data source Connection in use Data source rejected establishment of connection Communication link failure Invalid authori zation specification Data source not found and no default driver
199. QLGetStmtOption 2 2 2 we a ee ee 13 215 SQLGetTypeInfo 2 2 ee ee ee we 2 13 218 SQLMoreResults 2 2 2 eee ee ee 13 227 SQLNativeSql 2 2 2 1 ww ee ee ee we 13 230 SQLNumParams ee ee eee 13 233 SQLNumResultCols eee 18 235 SQLParamData 2 ee ee ee 13 238 SQLParamOptions 2 2 eee ee 13 24 SQLPrepare v o so s uos dos ee a wos o 2 13 246 SQLPrimaryKeys a a a aaa a 13 253 SQLProcedures a a ee 13 257 SQLPutData ee 13 265 SQLRowCount ee ee ee 13 272 SQLSetConnectOption 2 2 2 1 ee ew ee 13 274 SQLSetCursorName eee eee 13 283 SQLSetParam ee eee eee 13 287 SQLSetScrollOptions 2 1 2 ee ee ww 13 287 SQLSetStmtOption 2 2 a we ee ew ww 13 288 SQLSpecialColumns 2 2 we ee ee ee 13 297 SQLStatistics 2 2 eee ee 13 307 SQLTablePrivileges 2 2 1 2 we ee eee ee ee 13 315 SQLTables 2 2 2 ee ee ee 13 321 SQLTransact 2 ee ee ee a 13 327 13 2 INFORMIX CLI Programmer s 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
200. RBINARY LONG VARBINARY SQL_DATE DATE SQL_TIMESTAMP TIMESTAMP Description Signed approximate numeric value with a mantissa precision 7 zero or absolute value 10 to 1038 Signed approximate numeric value with a mantissa precision 15 zero or absolute value 10 to 10308 Variable length binary data Maximum length is data source dependent Date data Date time data a An application uses SQLGetTypeInfo or SQLColAttributes to determine if a particular data type or a particular column in a result set is unsigned 2 of 2 Data Types C 3 C Data Types C4 al C Data Types Data is stored in the application in ODBC C data types The core C data types support the minimum and core SQL data types They also support some extended SQL data types The extended C data types support only extended SQL data types The C data type is specified in the SQLBindCol SOLGetData and SQLBindParameter functions with the fCType argument Core C Data Types The following table lists valid values of fcType for the core C data types These values are defined in sql h The table also lists the ODBC C data type that implements each value of fCType and the definition of this data type from sql h fCType ODBC C Typedef C Type SQL_C_CHAR UCHAR FAR unsigned char FAR SQL_C_SSHORT SWORD short int SQL_C_USHORT UWORD unsigned short int SQL_C_SLONG SDWORD long int SQL_C_ULONG UDWORD unsigned long int SQL_C_FLOAT SFLOA
201. RD 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 Setup Shared Library Function Reference 14 7 Config Translator Related Functions For information about See Getting a translation option SQLGetConnectOption Selecting a translator SQLGetTranslator Setting a translation option SQLSetConnectOption 14 8 INFORMIX CLI Programmer s Manual Translation Shared Library Function Reference SQLDataSourceToDriver 2 a a eee a 15 3 SQLDriverToDataSource 2 2 1 we ee a a 15 7 15 2 INFORMIX CLI Programmer s Manual his chapter describes the syntax of the translation shared library API which comprises SQLDriverToDataSource and SQLDataSourceToDriver functions These functions must be included in the shared library that performs translations for the driver For information on argument naming conventions see Chapter 13 INFORMIX CLI Function Reference SQLDataSourceToDriver SQLDataSourceToDriver supports translations for the Informix driver This function is not called by INFORMIX CLI enabled applications applicatio
202. RMIX CLI Programmer s Manual Executing SQL Statements 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 Using ODBC Extensions to SQL Date Time and Time Stamp Data Scalar Functions LIKE Predicate pe tae Characters Outer Joins Procedures Related Functions 6 5 6 5 6 6 6 7 6 9 6 9 6 10 6 11 6 12 6 13 6 14 6 15 6 16 6 17 6 19 6 2 INFORMIX CLI Programmer s Manual napplication can submit any SQL statement that is supported by a data source ODBC defines a standard syntax for SQL statements see Appendix B For maximum interoperability an application should submit only SQL statements that use this syntax the driver translates these state ments to the syntax used by the data source If an application submits an SQL statement that does not use the ODBC syntax the driver passes it 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_LNAME column rather than the data type name defined in the SQL grammar Statements can be executed a single time with SQLExecDirect or prepared with SQLPrepare and executed multiple times with SQLExe
203. ROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLFreeStmt 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 SQLSTATE value is SQL_ERROR unless noted otherwise 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 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 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 specified for the argument fOption was not SQL_CLOSE SQL_DROP SQL_UNBIND SQL_RESET_PARAMS SQLFreeSimt Usage An application can call SQLFreeStmt to terminate processing of a SELECT statement with or without canceling the statement handle The SQL_DROP option frees all resources that are allocated by the SQLAIllocStmt function Code Example See SOLBrowseConnect and SQLConnect Related Functions For information about See Allo
204. S SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLStatistics returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLStatistics 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 SQLSTATE value is SQL_ERROR unless noted otherwise INFORMIX CLI Function Reference 13 305 SQL Statistics SQLSTATE 01000 08S01 24000 S1000 S1001 S1008 S1010 S1090 S1100 13 306 Error 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 INFORMIX CLI Programmer s Manual 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 returned by SQLError in the argument szErrorMsg describes the error and its
205. SOLGetData Returning the next parameter to send data for SQLParamData Preparing a statement for execution SQLPrepare Sending parameter data at execution time SOLPutData Setting a cursor name SQLSetCursorName Setting a statement option SQLSetStmtOption Executing a commit or rollback operation SQLTransact 13 126 INFORMIX CLI Programmer s Manual SQLExtendedFetch SQLExtendedFetch ESQLExtendedFetch extends the functionality of SQLFetch in the following ways m Itreturns rowset data one or more rows in the form 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 in conjunction with SOLSetStmtOption 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 7 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 UDWORD FAR pcrow Output Number of rows actually fetched UWORD FAR refRowStatus Output An array of status values INFORMIX CLI Function Reference 13 127 SQLExtendeaFetch SQLSTATE 01000 01004 01S01 07006
206. SQL statement processing The information returned by SQLError is in the same format as that provided by SQLSTATE in the X Open and SQL Access Group SQL CAE specification 1992 SQLError never returns error information about itself INFORMIX CLI Programmer s Manual Error Messages Error Messages ODBC defines a layered architecture to connect an application to a data source In INFORMIX CLI SQLError returns error messages that follow the standard ODBC format Error messages must not only explain the error but also provide 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 must be embedded in the error text Error Text Format Error messages returned by SQLError come from two sources data sources and ODBC components the driver manager or the driver Consequently the error text returned by SQLError has two formats one for errors that occur in a data source and one for errors that occur in ODBC components If an ODBC component receives an error message from a data source it must identify the data source as the source of the error It must also identify itself as the component that received the error For errors that occur in a data source the error text must use the following format vendor_identifier 0DBC_component_identifier data_source_identifier data_source_supplied_text If the source of an error is an ODBC
207. SQLBrowseConnect and SQLError the driver manager performs initial processing and then passes the call to the driver associated with the connection For any other function the driver manager passes the call to the driver If requested the driver manager records each called function in a trace file The name of each function is recorded along with the values of the input arguments and the names of the output arguments as listed in the function definitions 1 INFORMIX CLI Programmer s Manual Calling Functions Calling Functions The following paragraphs describe general characteristics of 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 SQLBindCol points to an output buffer where SQLFetch returns the data for a column 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 m A length greater than or
208. SQLSetConnec tOption SQL_LOGIN_TIMEOUT 3 of 3 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 SQLBrowseConnect szConnStrIn Argument A browse request connection string has the following syntax connection string attribute attribute connection string attribute attribute keyword attribute value DRIVER attribute value The braces are literal the application must specify them attribute keyword DSN UID PWD driver defined attribute keyword attribute value character string driver defined attribute keyword identifier 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 n
209. SQLSetCursorName associates a cursor name with an active hstmt If an application does not call SQLSetCursorName the driver generates cursor names as needed for SQL statement processing Syntax RETCODE SQLSetCursorName hstmt 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 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 281 SQL SetCursorName SQLSTATE 01000 Diagnostics Error General warning When SQLSetCursorName returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLSetCursorName 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 SQOLSTATE value is SOL_ERROR unless noted otherwise Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 24000 Invalid cursor state The statement corresponding to hstmt was already in an executed or cursor positioned state 34000 Invalid cursor name The cursor name specified by the argument szCursor was invalid For
210. SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR on page 13 192 7 6 INFORMIX CLI Programmer s Manual Retrieving Data from Unbound Columns Retrieving Data from Unbound Columns To retrieve data from unbound columns that is columns for which storage has not been assigned with SQLBindCol an application uses SQLGetData 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 SQLGetData 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 SQLGetData more than once for that column as long as the data is being transferred to a buffer of type SQL_C_CHAR or SQL_C_BINARY For example data of the SQL_LLONGVARBINARY and SQL_LONGVARCHAR types might need to be retrieved in several parts The Informix driver can return data with SQLGetData for both bound and unbound columns in any order For maximum interoperability however your application should call SQLGetData only for co
211. SS_WITH_INFO DM The hdbc was not in a connected state The connection associated with the hdbc failed during the execution of the function and it cannot be determined whether the requested COMMIT or ROLLBACK occurred before the failure 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 1 of 2 INFORMIX CLI Function Reference 13 325 SQL Transact SQLSTATE Error Description 1010 Function DM SQLExecute or SQLExecDirect was called sequence error 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 1012 Invalid trans DM The value specified for the argument action operation fType was neither SQL_COMMIT nor code SQL_ROLLBACK S1C00 Driver not capable The driver or data source does not support the ROLLBACK operation 2 of 2 Usage If hdbc is SQL_NULL_HDBC and henvis a valid environment handle the driver manager attempts to commit or roll back transactions on all hdbcs that are in a connected state The driver manager calls SQLTransact in the driver associated with each hdbc The driver manager returns SQL_SUCCESS only if it receives SQL_SUC
212. SWORD UWORD HDBC HENV HSTMT HWND SWORD UWORD UWORD SDWORD UWORD SWORD FAR SDWORD FAR UDWORD FAR SWORD FAR SWORD FAR SDWORD FAR UDWORD FAR SWORD SDWORD UWORD HDBC FAR HENV FAR Description 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 Pointer to environment handle 1 of 2 INFORMIX CLI Function Reference 13 5 Arguments Combined Prefix Tag ODBC C Type s Description 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 prg b PTR FAR Pointer to range array of bytes pv p v PTR Pointer to value of unspec ified 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 type Quali fiers 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 situati
213. See Translating data being sent to the datasource SQLDriverToDataSource Returning the setting of a connection option SQLGetConnectOption extension Setting a connection option SQLSetConnectOption extension SQLDriverToDataSource SQLDriverToDataSource supports translations for the Informix driver This function is not called by INFORMIX CLI enabled applications applications request translation through SQLSetConnectOption The driver associated with the hdbc specified in SQLSetConnectOption calls the specified shared library to perform translations of all the data that flows from the driver to the data source A default translation shared library can be specified in the odbc ini file Syntax BOOL SQLDriverToDataSource fOption fSqlType rgbValueln cbValueIn rgbValueOut cbValueQutMax pcbValueOut szErrorMsg cbErrorMsg pcbErrorMsg Translation Shared Library Function Reference 15 7 SQL DriverToDataSource 15 8 The SOLDriverToDataSource function accepts the following arguments Type Argument UDWORD fOption SWORD fSqlType PTR rgbValueIn SDWORD cbValuelIn PTR rgbValueOut SDWORD cbValueOutMax INFORMIX CLI Programmer s Manual Use Input Input Input Input Output Input Description Option value The ODBC SQL data type This argument tells the driver how to convert rgbValueln to a form acceptable by the data source This must be one of the following values SQL_CHAR SQL_DATE SQL_DECIMAL SQL
214. SqlStr 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 specified is not the same degree as the derived table defined by the query specification The argument szSqlStr 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 szSqlStr contained a positioned DELETE or a positioned UPDATE and the cursor referenced by the statement being prepared was not open The argument szSqlStr contained an SQL statement that was not preparable or contained a syntax error 1 of 4 INFORMIX CLI Function Reference 13 245 SQL Prepare 13 246 SQLSTATE 42000 S0001 S0002 Error Syntax error or access violation Base table or view already exists Base table not found INFORMIX CLI Programmer s Manual Description The argument szSqlStr contained a statement for which the user did not have the required privileges The argument szSqlStr contained a CREATE TABLE or CREATE VIEW statement but the table name or view name specified already exists The argument szSqlStr contained a DROP TABLE or a DROP VIEW statement but the specified table name or view name did not exist The argument szSqlStr contained an ALTER
215. StrMax the translated SQL string in szSqlStr is truncated to cbSql StrMax 1 bytes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE Diagnostics SQL NativeSq When SQLNativeSq returns either SOQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLNativeSql 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 01004 08003 37000 S1000 Error General warning Data truncated Connection not open Syntax error or access violation General error Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer szSq Str was not large enough to return the entire SQL string so the SQL string was truncated The argument pcbSqlStr 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 statement 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 returned by SQLError in the ar
216. T float SQL_C_DOUBLE SDOUBLE double Important Because string arguments in INFORMIX CLI functions are unsigned applications that pass CString objects to INFORMIX CLI functions without casting them to unsigned strings receive compiler warnings INFORMIX CLI Programmer s Manual Extended C Data Types The following table lists valid values of fCType for the extended C data types These values are defined in sqlext h The table also lists the ODBC C data type that implements each value of fCType and the definition of this data type from sqlext h or sql h fCType SQL_C_BIT SQL_C_STINYINT SQL_C_UTINYINT SQL_C_BINARY SQL_C_DATE SQL_C_TIME SQL_C_TIMESTAMP ODBC C Typedef UCHAR SCHAR UCHAR UCHAR FAR DATE_STRUCT TIME_STRUCT TIMESTAMP_STRUCT Extended C Data Types C Type unsigned char signed char unsigned char unsigned char FAR struct tagDATE_STRUCT SWORD year UWORD month gt UWORD day struct tagTIME_STRUCT UWORD hour 4 UWORD minute UWORD second f struct tagTIMESTAMP_STRUCT SWORD year UWORD month UWORD day UWORD hour UWORD minute UWORD second f UDWORD fraction a The value of the year field must be in the range from 0 to 9 999 Years are measured from 0 A D Some data sources do not support the entire range of years gt The value of the month field must be in the range from 1 to 12 1 of 2 Data Types C 5 Defaul
217. 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 defined by the query specification 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 szSqlStr contained a DELETE INSERT or UPDATE statement but the specified table name did not exist The argument szSqlStr 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 Error Index already exists Index not found Column already exists Column not found General error Memory allocation failure SQLPrepare Description The argument szSqlStr contained a CREATE INDEX statement but the specified index name already existed The argument szSqlStr contained a DROP INDEX statement but the specified index name did not exist The argument szSqlStr 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 szS
218. TCODE SQLColAttributes hstmt icol fDescType rgbDesc cbDescMax pcbDesc pfDesc The SQLColAttributes 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 13 55 PTR rgbDesc Output Pointer to storage for the descriptor information The format of the descriptor information returned depends on the fDescType SWORD cbDescMax Input Maximum length of the rgbDesc buffer 1 of 2 13 52 INFORMIX CLI Programmer s Manual SQLColAttributes Type Argument Use Description SWORD FAR pcebDesc 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 descriptor types such as SQL_COLUMN_LENGTH 2 of 2 Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQ
219. TO table name column identifier column identifier query specification VALUES insert value insert value ODBC Procedure Extension SQL conformance level Extended ODBC std esc initiator call procedure ODBC std esc terminator ODBC ext esc initiator call procedure ODBC ext esc terminator SQL Grammar B 7 REVOKE Statement REVOKE Statement SQL conformance level Core REVOKE ALL revoke privilege revoke privilege ON table name FROM PUBLIC user name user name CASCADE RESTRICT revoke privilege DELETE INSERT SELECT UPDATE REFERENCES SELECT Statement SQL conformance level Minimum SELECT ALL DISTINCT select list FROM table reference list WHERE search condition order by clause SQL conformance level Core SELECT ALL DISTINCT select list FROM table reference list WHERE search condition GROUP BY column name column name HAVING search condition order by clause B 8 INFORMIX CLI Programmer s Manual SELECT FOR UPDATE Statement SQL conformance level Extended SELECT ALL DISTINCT select list FROM table reference list WHERE search condition GROUP BY column name column name HAVING search condition UNION ALL select statement order by clause m m m In ODBC 1 0 the UNION clause is in the SQL core grammar and does not support the ALL keyword SELECT FOR UPDATE State
220. TableOwner cbTableQwner szTableName cbTableName fUnique fAccuracy The SQLStatistics function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UCHAR FAR szTableQualifier Input Qualifier name 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 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 UCHAR FAR szTableName Input Table name SWORD cbTableName Input Length of szTableName 1 of 2 13 304 INFORMIX CLI Programmer s Manual SQL Statistics Type Argument Use Description UWORD fUnique Input Type of index SQL_INDEX_UNIQUE or SQL_INDEX_ALL UWORD fAccuracy Input The importance of the CARDI NALITY and PAGES columns in the result set SQL_ENSURE requests that the driver unconditionally retrieve the statistics 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 Return Codes SQL_SUCCES
221. UALIFIER_LOCATION SQL_QUALIFIER_NAME_SEPARATOR SQL_QUALIFIER_TERM SQL_QUALIFIER_USAGE SQLGetInfo Returns A 16 bit integer value that indicates the position of the qualifier in a qualified table name SOL_OL_START SQL_QL_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 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 A character string with the data source vendor name for a qualifier for example database or directory A 32 bit bitmask that enumerates the statements in which quali fiers can be used The following bitmasks are used to determine where qualifiers can be used 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 SQL_QU_PROCEDURE_INVOCATION Qualifiers are supported in the ODBC procedure invocation statement SQL_QU_TABLE_DEFINITION Qualifiers are supported in all table definition statements CREATE TABLE CREATE VIEW ALTER TABLE DROP TABLE and DROP VIEW SQL_QU_INDEX_DEFINITION Qualifiers are supported in all index definition statements CREATE INDEX and DROP INDEX SQL_QU_PRIVILEGE_DEFINITION Qualifiers
222. UCHAR FAR szTableQualifier Input Qualifier name 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 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 13 251 SQLPrimaryKeys SQLSTATE 01000 08S01 24000 S1000 S1001 S1008 Return Codes Diagnostics Error General warning Communication link failure Invalid cursor state General error Memory allocation failure Operation canceled 13 252 INFORMIX CLI Programmer s Manual SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE When SQLPrimaryKeys returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLPrimaryKeys and explains each value in the context of this function the notation DM precedes the description of each SQLSTATE returned by
223. UMN_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 SQL_ODBC_SQL_OPT_IEF SQL_ORDER_BY_COLUMNS_IN_SELECT SQL_OUTER_JOINS SQL_OWNER_USAGE SQL_POSITIONED_STATEMENTS SQL_PROCEDURES SQL_QUALIFIER_LOCATION SQL_QUALIFIER_NAME_SEPARATOR SQL_QUALIFIER_USAGE SQL_QUOTED_IDENTIFIER_CASE SQL_SPECIAL_CHARACTERS SQL_SUBQUERIES SQL_UNION 13 188 INFORMIX CLI Programmer s Manual SQLGetInfo 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 Limita tions might be imposed by either the driver or the data source SQL_MAX_BINARY_LITERAL_LEN SQL_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_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 SQL_MAX_QUALIFIER_NAME_LEN SQL_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 5 Ss s INFORMIX CLI Function Reference 13 189 SQL Getinfo InfoTy
224. Unable to load translation shared library Data source name too long Driver name too long DRIVER keyword syntax error General error Memory allocation failure SQL DriverConnect Description 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 SQL_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 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 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 3 of 4 INFORMIX CLI Function Reference 13 97 SQL DriverConnect 13 98 SQLSTATE S1090 S1110 S1T00 Usage Error Invalid string or buffer length Invalid driver completion Time out expired INFORMIX CLI Programmer s Manual Description 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 T
225. _DATA This function was called before data was sent for all data at execution parameters or columns DM The value specified for the argument crow was equal to 0 INFORMIX CLI Function Reference 13 241 SQL ParamOptions Usage As a statement executes the driver sets pirow to the number of the current row of parameter values the first row is row number 1 The contents of pirow can be used as follows m When SQLParamData returns SQL_NEED_DATA for data at execution parameters the application can access the value in pirow to determine which row of parameters is being executed m When SQLExecute or SQLExecDirect returns an error the application can access the value in pirow to find out which row of parameters failed m When SQOLExecute SOLExecDirect SOLParamData or SOLPutData succeed the value in pirow is set to crow the total number of rows of parameters processed 13 242 _INFORMIX CLI Programmer s Manual SQLParamOptions Code Example In the following example an application specifies an array of parameter values with SOLBindParameter and SQLParamOptions It then inserts those values into a table with a single INSERT statement and checks for any errors If the first row fails the application rolls back all changes If any other row fails the application commits the transaction skips the failed row rebinds the remaining parameters and continues processing Note that irow is 1 based and szDatal is 0 based
226. _DECIMAL SQL_LONGVARBINARY SQL_CHAR SQL_VARCHAR SQL_DOUBLE SQL_DATE SQL_TIMESTAAMP C Data Type SQL_C_CHAR SQL_C_BIT SQL_C_STINYINT SQL_C_UTINYINT SQL_C_TINYINT SQL_C_SSHORT SQL_C_USHORT SQL_C_SHORT SQL_C_SLONG SQL_C_ULONG SQL_C_LONG SQL_C_FLOAT SQL_C_DOUBLE SQL_C_BINARY SQL_C_DATE SQL_C_TIME SQL_C_TIMESTAMP OO0290009029AO0A9A90000 O O O 0O 0 0 0 0 0 0O 0O 070 0O 0 0 0 0 0 040 0 00 070 70 0 00 0 O0 0 0O 0 0 0 0 0 0O 0 0 0O O O 0 0 0 0 O0 80900000 O0O000 80000000 0 0 50 O 0 0 0 0 0 0 0 0 0 OO 0 0 0 0 0 0 0 OO 0 0 0 0 00 0 0 0 0 0 0 O O 0 e 000 OO O O O O O O O OQO QO O OOQOQ QOQQO O Data Types C 25 Converting Data from C to SQL Data Types C 26 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 ODBC C data types to the ODBC SQL data types that they support For a given ODBC 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 if it can convert the data The third column lists the SQLSTATE that is returned for each outcome by SQLExecDirect SQLExecute or SOLPutData Data is sent to the data source only if SQL_SUCCESS is returned If the fSqlType argument in SOLBindParameter contains a value fo
227. _DOUBLE SQL_INTEGER SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_REAL SQL_SMALLINT SQL_TIMESTAMP SQL_VARCHAR For information on ODBC SQL data types see Appendix C For information on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 Value to translate Length of rgbValueln Result of the translation The translation shared library does not null terminate this value Length of rgbValueOut 1 of 2 Type SDWORD FAR UCHAR FAR SWORD SWORD FAR Return Codes Argument pebValueOut szErrorMsg cbErrorMsgMax pebErrorMsg Use Output Output Input Output SQLDriverToDataSource Description The total number of bytes excluding the null termination byte available to return in rgbValueOut For character or binary data if this is greater than or equal to cbValue OutMax the data in rgb ValueOut is truncated to cbValueOutMax bytes For all other data types the value of cbValueOutMax is ignored and the translation shared library assumes the size of rgbValueOut is the size of the default C data type of the SQL data type specified with fSqlType Pointer to storage for an error message This is an empty string unless the translation failed Length of szErrorMsg Pointer to the total number of bytes excluding the null termi nation byte available to return in szErrorMsg If this is greater than or equal to cbErrorMsg the data in
228. _DRIVER_PROMPT m SQL_DRIVER_NOPROMPT The driver manager copies the connection string specified by the application INFORMIX CLI Programmer s Manual SQL DriverConnect 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 13 78 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 follows 1 If the connection string contains the DSN keyword the driver manager retrieves the driver associated with the data source from the odbc ini file 2 If the 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 from the odbc ini file 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
229. _RESUME the driver manager returns SQLSTATE S1C00 Driver not capable The SQL_FETCH_RESUME fetch type is obsolete in ODBC 2 x drivers INFORMIX CLI Function Reference 13 137 SQLExtendedFetch 13 138 fFetchType Argument Moving by Row Position SQLExtendedFetch supports the following values of the fFetchType argument to move the cursor relative to the current rowset Action SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_RELATIVE fFetchType Argument SQL_FETCH_FIRST SQL_FETCH_LAST SQL_FETCH_ABSOLUTE INFORMIX CLI Programmer s Manual The driver returns the next rowset If the cursor is positioned before the start of the result set this is equiv alent to SQL_FETCH_FIRST The driver returns the prior rowset If the cursor is positioned after the end of the result set this is equivalent to SQL_FETCH_LAST The driver returns the rowset irow rows from the start of the current rowset If irow equals 0 the driver refreshes the current rowset 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 irow 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 Action The driver returns the first rowset in the result set The driver returns the last complete rowset in the result set If
230. _WITH_INFO SQL_INVALID_HANDLE or SQL_ERROR If SQLAIlocStmt returns SQL_ERROR it sets the hstmt that phstmt references to SQL_NULL_HSTMT The application can then obtain additional infor mation by calling SOLError with the hdbc and SQL_NULL_HSTMT 13 14 INFORMIX CLI Programmer s Manual SQLAllocStmt Diagnostics When SQLAIlocStmt returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLAIlocStmt 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error Description 01000 General warning informational message Function returns SQL_SUCCESS_WITH_INFO 08003 Connection not DM The connection specified by the hdbc open argument was not open The connection process must be completed successfully and the connection must be open for the driver to allocate an hstmt 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 DM The driver manager could not allocate allocation failure memory for the statement handle
231. a an application performs the following operations 1 Calls SQLParamData which returns rgbValue as set with SOLBind Parameter for the first data at execution parameter Calls SQLPutData 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 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 Repeats steps 2 and 3 for the remaining data at execution parameters For additional information see SOLBindParameter on page 13 23 Specifying Arrays of Parameter Values To specify multiple sets of parameter values for a single SQL statement an application calls SQLParamOptions For example if there are ten sets of column values to insert into a table and the same SOL statement can be used for all ten operations the application can set up an array of values then submit a single INSERT statement If an application uses SQLParamOptions it must allocate enough memory to handle the arrays of values Executing SQL Statements 6 11 Using ODBC Extensions to SQL 6 12 Usin
232. a for a single column see Usage on page 13 171 The data value cannot be converted 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 1 of 5 INFORMIX CLI Function Reference 13 167 SQL GetData 13 168 SQLSTATE Error 22003 Numeric value out of range 22005 Error in assignment 22008 Datetime field overflow 22012 Division by zero 24000 Invalid cursor state 1000 General error INFORMIX CLI Programmer s Manual Description Returning the numeric value as numeric or string for the column would have caused the whole as opposed to fractional part of the number to be truncated Returning the binary value for the column would have caused a loss of binary signifi cance For more information see Appendix C The data for the column was incompatible with the data type into which it was to be converted For more information see Appendix C The data for the column was not a valid date time or time stamp value For more infor mation see Appendix C A value from an arithmetic expression was returned that resulted in a division by zero 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 had not been called
233. a row of data from the result set an application performs the following operations 1 Calls SQLBindCol to bind the columns of the result set to storage locations if it has not already done so 2 Calls SQLFetch to move to the next row in the result set and retrieve data for all bound columns Figure 7 1 shows the operations an application uses to retrieve data from the result set Retrieving Results 7 5 Using Cursors Figure 7 1 Operations That an Application Uses to Retrieve Data from SELECT Statement SQLNumResultCols the Result Set SQLDescribeCol SQLBindCol SQLFetch More Rows Using Cursors A driver maintains a cursor to indicate the current position in the result set much as the cursor on a CRT screen indicates the current position You can use SQLFetch or SQLExtendedFetch to retrieve data from a result set Each time 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 SQLFreeStmt with the SQL_CLOSE option reexecute the SELECT statement and fetch rows withSQLFetch until the target row is retrieved Important Committing or rolling back a transaction either by calling SQLTransact Vy or by using the SQL_LAUTOCOMMIT connection option can cause the data source to j close the cursors for all hstmts on an hdbc For more information see
234. a source for a particular session An attribute identifies a specific piece of information that the driver needs to know before it can make the appropriate data source connection A connection string has the following format DSN data_source_name attribute valueL attribute value You must specify data_source_name however all other attributes are optional If you do not specify an attribute it defaults to the one that is specified in the Data Source Specification section for the data source specified in the connection string of your odbc ini file INFORMIX CLI 2 13 Using a Connection String to Connect to a Data Source 2 14 The following table lists the long and short names of the attributes that you can include in the INFORMIX driver connection string With the exception of the data source name which must be specified by DSN you can use either the long or short names in the connection string For a description of these attributes see Optional Data Source Configuration Information on page 2 6 Attribute Long Name Short Name DataSourceName DSN Database DB HostName HOST LogonID UID Password PWD Service SERV CursorBehavior CB EnableScrollableCursors ESC The following example shows a valid connection string for connecting to the stores7 data source The string specifically requests a connection to the stores7 database that resides on a computer named rainbow The user ID is mary DSN Stores7 DB sto
235. aSource and SQLDataSourceToDriver that the driver loads and uses to perform tasks such as character set translation This option can be specified only if the driver has connected to the data source For more information about translating data see Chapter 15 Translation Shared Library Function Reference A 32 bit flag value that is passed to the translatation shared library This option can only be specified if the driver has connected to the data source 3 of 4 13 278 INFORMIX CLI Programmer s Manual fOption SQL_TXN_ISOLATION SQL SetConnectOption 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 SQLGetInfo with finfotype equal to SQL_TXN_ISOLATION_OPTIONS The following terms are used to define transaction isolation levels 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 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 it receives different row values or discovers that the row has bee
236. able Dirty Reads Nonrepeatable Reads and Phantoms are not possible SQL_TXN_VERSIONING Transactions are serializable 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 nonlocking 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 These information types are implemented by the driver manager alone 5 of 22 13 194 INFORMIX CLI Programmer s Manual InfoType SQL_DRIVER_HLIB SQL_DRIVER_HSTMT SQL_DRIVER_NAME SQL_DRIVER_ODBC_VER SQL_DRIVER_VER SQL_EXPRESSIONS_IN_ORDERBY SQLGetInfo Returns A 32 bit value the library handle returned to the driver manager when it loaded the driver shared library The handle is only valid for the hdbc specified in the call to SQLGetInfo This information type is implemented by the driver manager alone A 32 bit value the statement handle 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 This information type
237. able qualifier identifier NULL if not applicable to the data source Primary key table owner identifier NULL if not applicable to the data source Primary key table identifier Primary key column identifier Column sequence number in key starting with 1 Primary key identifier NULL if not appli cable to the data source For information about See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SQLCancel Fetching a block of data or scrolling through a result set SQLExtendedFetch SQLFetch SQLStatistics SQLProcedures 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 returned by SQL SELECT expressions 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 cbProcQualifi
238. ables Usage 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 perform one of the following actions m Call SQLGetInfo and check the SQL_ACCESSIBLE_TABLES info value m Call SQLTablePrivileges to check the privileges for each table Otherwise the application must handle situations where the user selects a table for which SELECT privileges are not granted The szTableOwner and szIableName arguments accept search patterns For more information about valid search patterns see Search Pattern Arguments on page 13 8 To support enumeration of qualifiers owners and table types SQLTables defines the following special semantics for the szTableQualifier szTableOwner szTableName and szTableType arguments m If szTableQualifier is a single percent character and szIableOwner 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 m 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 m If szTableType is a single percent character and szTableQualifier szTableOwner and szTableName are empty strings then the
239. ads drivers dynamically and provides argument and transition checking The driver is either a shared library for UNIX drivers or a dynamic link library for Windows drivers that implements function calls and manages exchanges between an application and an Informix database Figure 1 1 shows the relationship of the components in an INFORMIX CLI application and ODBC configuration The driver manager and driver appear to an application as one unit that processes INFORMIX CLI function calls Overview of INFORMIX CLI 1 3 What Is INFORMIX CLI Figure 1 1 INFORMIX CLI I CLI CLI aay Architecture I CLI interface Informix data source may Sm Fel ODBC 2 0 specification The data source consists of the database a user wants to access its associated DBMS the platform on which the DBMS resides and the network used to access that platform When you compile and link an INFORMIX CLI application it is automatically equipped to communicate with an Informix database server that resides either on the same computer local or on a network on other computers remote INFORMIX CLI enables the development of applications that issue SQL state ments to Informix database servers and process resulting data dynamically INFORMIX CLI provides functions that allow your applications to perform the following set of operations Initiate and terminate connections to database servers Obtain information about the server and CLI Set and retrieve
240. alues 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 INFORMIX CLI Programmer s Manual SQLGetInfo 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 INFORMIX CLI Function Reference 13 187 SQL Getinfo Supported SQL The following values of fInfoType return information about the SQL statements that are supported by the data source 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 SQL_ODBC_SQL_CONFORMANCE information type and use the other information types to determine variations from the stated conformance level SQL_ALTER_TABLE SQL_COL
241. ames cannot contain a backslash If any keywords are repeated in the browse request 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 browse request connection string the driver manager and driver use whichever keyword appears first szConnStrOut Argument The browse result connection string is a list of connection attributes A connection attribute consists of an attribute keyword and a corresponding attribute value The browse result connection string has the following syntax connection string attributeL 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 identiferL 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 INFORMIX CLI Function Reference 13 43 SQL BrowseConnect 13 44 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 avo
242. ammer s Manual Description Maximum length of the rgbValue buffer For character data rgbValue must also include space for the null termination byte For more information about length see Precision Scale Length and Display Size on page C 8 7 SQL_NULL_DATA or the number of bytes excluding the null termination byte for character data available to return in rgbValue prior to calling SQLExtendedFetch or SQLFetch or SQL_NO_TOTAL if the number of available bytes cannot be deter mined 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 cbValueMax 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 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 For more information about the value returned in pcbValue for each fCType see Converting Data from SQL to C Data Types on page C 13 2 of 2 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR or Diagnostics SQLBindCol When SQLBindCol returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE value
243. amp fEXxistsLSQL_API_SQLCOLUMNS amp amp fExistsLSQL_API_SQLSTATISTICS Continue with application SQLDisconnect hdbc INFORMIX CLI Function Reference 13 179 SQL GetFunctions Related Functions For information about See Returning the setting of a connection option SQLGetConnectOption Returning information about a driver or data source SQLGetInfo Returning the setting of a statement option SOLGetStmtOption 13 180 INFORMIX CLI Programmer s Manual SQLGetInfo SQLGetInfo SQLGetInfo returns general information about the driver and data source associated with an hdbc Syntax RETCODE SQLGetInfo hdbc finfoType rgbInfoValue cbInfoValueMax pcbInfoValue The SQLGetInfo function accepts the following arguments Type Argument Use Description HDBC hdbc Input Connection handle UWORD finfoType Input Type of information The fInfoType argument must be a value that represents the type of interest see Usage on page 13 184 1 of 2 INFORMIX CLI Function Reference 13 181 SQL Getinfo 13 182 Type Argument Use PTR rgbInfo Value Output SWORD cbInfoValueMax Input SWORD FAR pcbInfoValue Output Return Codes SQL_INVALID_HANDLE INFORMIX CLI Programmer s Manual Description Pointer to storage for the infor mation Depending on the fInfoType requested the information returned will be one of the following a null terminated character string a 16 bit integer
244. an application calls SQLGetInfo with the SQL_ODBC_SQL_CONFORMANCE flag For information about how an appli cation determines whether a specific extension is supported see Supported SQL on page 13 188 and SQL Limits on page 13 189 INFORMIX CLI Programmer s Manual Using ODBC Extensions to SQL Important Informix database servers provide extensions to SQL other than those defined by ODBC To use one of these extensions refer to Informix Guide to SQL Syntax If your application uses the Informix specific syntax it is not interoperable among DBMSs Date Time and Time Stamp Data The escape clauses that ODBC uses for date time and time stamp data are shown in the following example vendor Microsoft product ODBC d value vendor Microsoft product ODBC t value vendor Microsoft product ODBC ts value d indicates value is a date in the yyyy mm dd format t indicates value is a time in the hh mm ss format ts indicates value is a time stamp in the yyyy mm dd hh mm ss f format The shorthand syntax for date time and time stamp data is as follows d value t value ts value For example each of the following statements updates the birthday of Walter Jacobs in the EMPLOYEE table The first statement uses the escape clause syntax The second statement uses the shorthand syntax The third statement uses the native syntax for Informix for a DATE colu
245. an be xxSOCTCP xxSOCSPX or SEIPCPIP where xx represents an abbreviation for the type of database server to which you are connecting For example SESOCSPX indicates that you are using an INFORMIX SE with sockets and IPX A value of 0 1 2 or 3 that determines whether you can work in other Windows applications when the INFORMIX CLI driver is busy m 0 Peek and dispatch This setting causes the Informix driver to check the Windows message queue and send any messages to the appropriate Windows application m 1 No yielding This setting does not let you work in other applications This is the default setting m 2 Informix yield procedure This is the default setting For more information refer to the section on the TABLOCKMODE environment variable in the INFORMIX DCE NET User s Guide m 3 Dispatch via Windows Yield function This setting turns control over to the Windows kernel The Windows kernel checks the message queue and sends any messages to the appropriate application window The recommended value is 1 Tip You can also add data sources when you install INFORMIX CLI In either case the steps that you follow are the same Adding a Data Source To add a data source 1 Invoke the ODBC Administrator The Data Sources dialog box appears as Figure 2 4 illustrates Figure 2 4 The Data Sources Dialog Box User Data Sources Driver Close Help Setup Delete
246. an hold a single row of retrieved data and the associated data lengths To bind each column the structure contains one field to contain data and one field to contain the number of bytes of data that are available to return Allocates an array of these structures This array has as many elements as there are rows in the rowset Calls SQLBindCol for each column to be bound In each call the application specifies 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 Calls SQLSetStmtOption with the SOL_BIND_TYPE option and specifies 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 Programmer s Manual Retrieving Rowset Data Retrieving Rowset Data Before it retrieves rowset data an application calls SQLSetStmtOption with the SQL_ROWSET_SIZE option to specify the number of rows in the rowset It then binds columns in the rowset with SQLBindCol The rowset is bound using a column or row wise method For more information see Assigning Storage for Rowsets Binding on page 7 7 To retrieve rowset data an application calls SQLExtendedFetch For maximum interoperability an application should not use SQLGetData to retrieve data from unbound columns
247. ancing financial data an accountant needs data that appears static it is impossible to balance books when the data is continually changing 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 requiring different sensitiv ities 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 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 used by a dynamic cursor are always changing Rows updated deleted or inserted by all users the cursor other cursors in the same appl
248. are supported in all privilege definition statements GRANT and REVOKE 16 of 22 INFORMIX CLI Function Reference 13 205 SQL GetInfo InfoType SQL_QUOTED_IDENTIFIER_CASE SQL_ROW_UPDATES SQL_SCROLL_CONCURRENCY 13 206 INFORMIX CLI Programmer s Manual Returns A 16 bit integer value as follows SQL_IC_UPPER Quoted identifiers in SQL are case insensitive and are stored in uppercase in system catalog SQL_IC_LOWER Quoted identifiers in SQL are case insensitive and are stored in lowercase in system catalog SQL_IC_SENSITIVE Quoted identifiers in SQL are case sensitive and are stored in mixed case in system catalog SQL_IC_MIXED Quoted identifiers in SQL are not case sensitive and are stored in mixed case in system catalog A character string Y if a keyset driven or mixed cursor maintains row versions or values for all fetched rows and therefore can detect any changes made to a row by any user since the row was last fetched otherwise N 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 SQL_SCCO_READ_ONLY Cursor is read only No updates are allowed SQL_SCCO_LOCK Cursor uses the lowest level of locking suffi cient to ensure that the row can be updated SQL_SCCO_OPT_ROWVER Cursor uses optimistic concurrency control comparing row versions SQL_SCCO_OPT_VA
249. ata converted without truncation Data converted with truncation of fractional digits Conversion of data would result in loss of whole as opposed to fractional digits Data is within the range of the data type to which the number is being converted gt Data is outside the range of the data type to which the number is being converted gt Data is 0 or 1 Data is greater than 0 less than 2 and not equal to 1 Data is less than 0 or greater than or equal to 2 gt rgbValue Data Truncated data Untouched Data Truncated data Untouched Data Untouched Data Truncated data Untouched SQL to C Numeric pcebValue Length of data Length of data Untouched Size of the C data type Size of the C data type Untouched Size of the C data type Untouched Untouched SQLSTATE N A 01004 22003 N A 01004 22003 N A 22003 N A 01004 22003 1 of 2 Data Types C 19 SQL to C Binary fCType Test rgbValue pebValue SQLSTATE SQL_C_BINARY Length of data lt cbValueMax Data Length of data N A Length of data gt cbValueMax Untouched Untouched 22003 P 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 2 of 2 SQL to C Binary The binary ODBC SQL data type that INFORMIX CLI supports is SQL_LONGVARBINARY T
250. atements DDL statements CREATE TABLE DROP INDEX an so on encountered in a transaction cause the transaction to be committed SQL_TC_DDL_IGNORE Transactions can contain only DML statements DDL statements encountered in a transaction are ignored SQL_TC_ALL Transactions can contain DDL statements and DML statements in any order 21 of 22 InfoType SQL_TXN_ISOLATION_OPTION SQL_UNION SQL_USER_NAME Code Example SQLGetInfo 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 SQL_TXN_READ_UNCOMMITTED SQL_TXN_READ_COMMITTED SQL_TXN_REPEATABLE_READ SQL_TXN_SERIALIZABLE SQL_TXN_VERSIONING For descriptions of these isolation levels see SQL_DEFAULT_TXN_ISOLATION on page 13 194 A 32 bit bitmask that enumerates the support for the UNION clause SQL_U_UNION The data source supports the UNION clause 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 A character string with the name used in a particular database which can be different than login name 22 of 22 SQLGetInfo returns lists of supported options as a 32 bit bitmask in rgbIn foValue The bitmask for each option is used with the flag to determine whether the option is s
251. ation can verify if a row exists without incurring the overhead of retrieving rows A 32 bit integer value that specifies the number of rows in the rowset This is the number of rows returned by each call to SOLExtendedFetch The default value is 1 If the specified rowset size exceeds the maximum rowset size supported by the data source the driver substitutes that value and returns SQLSTATE 01S02 Option value changed This option can be specified for an open cursor and can also be set through the crowRowset argument in SQLSetScrollOptions INFORMIX CLI does not support this option INFORMIX CLI does not support this option The default is set to SOL_UB_OFF Off 5 of 5 INFORMIX CLI Function Reference 13 293 SQL SetStmtOption 13 294 Code Example See SOLExtendedFetch Related Functions INFORMIX CLI Programmer s Manual For information about See Canceling statement processing SQLCancel Returning the setting of a connection option SQLGetConnectOption Returning the setting of a statement option SOLGetStmtOption Setting a connection option SQLSetConnectOption SQL SpecialColumns SQLSpecialColumns SQLSpecialColumns retrieves the following information about columns within a specified table m The optimal set of columns that uniquely identifies a row in the table m Columns that are automatically updated when any value in the row is updated by a transaction Syntax RETCODE SQLSpecialColumns hstmt
252. ation has specified each level of attributes and values SOLBrowseConnect connects to the data source and returns a complete connection string This string can be used with SQLDriverConnect to connect to the data source at a later time Translating Data An INFORMIX CLI application and a data source can store data in different formats For example the application might use a different character set than the one the data source uses The driver can translate all data data values SQL statements table names row counts and so on that passes between the driver and the data source The driver translates data by calling functions in a translation shared library A default translation shared library can be specified for the data source in the odbc ini file the application can override this by calling SQLSetConnectOption When the driver connects to the data source it loads the translation shared library if one has been specified After the driver has connected to the data source the application might specify a new translation shared library by calling SOLSetConnectOption For more information about specifying a default translation shared library see ODBC Options on page 1 10 Translation functions might support several types of translation For example a function that translates data from one character set to another might support a variety of character sets To specify a particular type of trans lation an application can pass an optio
253. ation specific SQLSTATE 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 cbDSNMax was less than 0 DM The value specified for argument cbDescriptionMax was less than 0 DM The value specified for the argument fDirection was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT INFORMIX CLI Function Reference 13 83 SQLDataSources Usage returns the first data source name called it returns the first data source name sources Related Functions For information about Discovering and listing values required to connect toa data source Connecting to a data source Connecting to a data source using a connection string or dialog box Returning driver descriptions and attributes 13 84 INFORMIX CLI Programmer s Manual An application can call SQLDataSources multiple times to retrieve all data source names The driver manager retrieves this information from the odbc ini file When no more data source names remain the driver manager returns SOQL_NO_DATA_FOUND If SQLDataSources is called with SQL_FETCH_NEXT immediately after it returns SQL_NO_DATA_FOUND it If SQL_FETCH_NEXT is passed to SQLDataSources the first time that it is The driver determines how data source names are mapped to actual data See
254. attern 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 13 8 A character string with the actual data source specific server name useful when a data source name is used during SOLConnect SQLDriverConnect and SOQLBrowseConnect 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 18 of 22 INFORMIX CLI Function Reference 13 207 SQL GetInfo InfoType SQL_STATIC_SENSITIVITY SQL_SYSTEM_FUNCTIONS SQL_TABLE_TERM 13 208 INFORMIX CLI Programmer s Manual Returns A 32 bit bitmask that enumerates whether changes made by an application to a static or keyset driven cursor through positioned update or delete statements can be detected by that application 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 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 SQL_SS_UPDATES Updates to rows are visible to the cursor if the cursor s
255. ault data source exists the driver manager returns an error Connecting to a Data Source with SQLDriverConnect Your application can connect to a data source by calling SQLDriverConnect SQLDriverConnect supports the following m Data sources that require more connection information than the three arguments in SQLConnect m Dialog boxes to prompt the user for all connection information m Data sources that are not defined in the odbc ini file SQLDriverConnect uses a connection string to specify the information needed to connect to a driver and data source The connection string contains the following information Data source name or driver description Zero or more user IDs Zero or more passwords Zero or more data source specific parameter values 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 INFORMIX CLI Programmer s Manual Connecting to a Data Source with SQL DriverConnect An application calls SQLDriverConnect in one of the following ways Specifies a connection string that contains a data source name The driver manager retrieves the full path of the driver shared library associated with the data source from the odbc ini file To retrieve a list of data source names an application calls SQLDataS
256. birthday itdefine NAME_LEN itdefine BDAY_LEN UCHAR szNameL SWORD sAge SDWORD cbName 30 11 AME_LEN szBirthday BDAY_LEN 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 ay SQLGetData hstmt 1 SQL_C_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 INFORMIX CLI Function Reference 13 173 SQL GetFunctions Related Functions For information about See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SQLCancel Executing an SQL statement SOLExecDirect Executing a prepared SQL statement SQLExecute Fetching a block of data or scrolling through a result set SQLExtendedFetch Fetching a row of data SQLFetch Sending parameter data at execution time SOLPutData SQLGetFunctions SQLGetFunctions returns information about whether a driver supports a specific ODBC function This function is implement
257. ble following the diagram explains the value boldface Identifiers names of classes objects constants events functions program variables forms labels and reports environment variables database names table names column names menu items command names and other similar terms are printed in boldface monospace Information that the product displays and information that you enter are printed in a monospace typeface KEYWORD All keywords appear in uppercase letters 8 INFORMIX CLI Programmer s Manual This symbol indicates the end of product or platform specific information 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 three types of information as described in the following table This information is always displayed in italics Icon Description Identifies paragraphs that contain vital instructions j cautions or critical information Identifies paragraphs that contain significant information about the feature or operation that is being described Identifies paragraphs that off
258. by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLCancel 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 SQLSTATE value is SQL_ERROR unless noted otherwise 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 failure to 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 SQLCancel has the same effect as SOLFreeStmt with the SQL_CLOSE option this behavior is defined only for completeness and applications should call SOLFreeStmt to close cursors 13 50 INFORMIX CLI Programmer s Manual SQLCancel Canceling Functions that Need Data After SQLExecute or SQLExecDirect returns SQL_NEED_DATA and before data has been sent for all data at execution paramet
259. c SQL statements Dynamic SQL Statements INFORM IX CLI Section SQL Statement Function Comments 5 3 Dynamic SQL SOLFreeStmt None see 5 2 1 CLOSE SQL_CLOSE option 5 3 Dynamic SQL SQLExecDirect Can also be invoked by see 5 2 2 Positioned DELETE DELETE FROM table SQLPrepare and name WHERE SQLExecute CURRENT OF cursor name 5 3 Dynamic SQL SQLExecDirect Can also be invoked by see 5 2 8 Positioned UPDATE table name SQLPrepare and UPDATE SET column identifier SQLExecute expression WHERE CURRENT OF cursor name 5 3 3 ALLOCATE None Descriptor information DESCRIPTOR is implicitly allocated and attached to the hstmt by the driver Allocation occurs at either the first call to SQLBindParameter or at SQLExecute or SQLExecDirect time 5 3 4 DEALLOCATE SOLFreeStmt None DESCRIPTOR SQL_DROP option 5 3 5 DESCRIBE none None 5 3 6 EXECUTE SQLExecute None 5 3 7 EXECUTE SQLExecDirect None IMMEDIATE 5 3 8 Dynamic SQL SQLFetch None FETCH 1 of 2 Comparison Between INFORMIX CLI and Embedded SQL D 7 Transaction Control Statements D 8 Section SQL Statement 5 3 9 GET DESCRIPTOR 5 3 10 Dynamic SQL OPEN 5 3 11 PREPARE 5 3 12 SET DESCRIPTOR Section SQL Statement 5 4 1 COMMIT WORK 5 4 2 ROLLBACK WORK INFORMIX CLI Programmer s Manual INFORMIX CLI Function SOLNumResultCols SQLDescribeCol SQLColAttributes SQLExecute SQLPrepare SQLBindParameter Transaction Contro
260. cate expression NOT LIKE pattern value INFORMIX CLI Programmer s Manual Extended Core Core Core Core Minimum Minimum Extended Core Core Core Core Minimum Minimum Minimum Minimum Minimum 4 of 11 Hements Used in SQL Statements SQL Conformance Element Level like predicate Extended expression NOT LIKE pattern value ODBC like escape clause literal character string literal Minimum literal character string literal numeric literal Core literal character string literal Extended numeric literal bit literal binary literal ODBC date time extension lower case letter Minimum albilcildlelflgIhliljlklllmInlolplqlIirl sltlulvlwlxlylz mantissa exact numeric literal Core minutes value digit digit Extended months value digit digit Extended null predicate column name IS NOT NULL Minimum numeric literal exact numeric literal approximate numeric literal Minimum ODBC date literal Extended ODBC std esc initiator d date value ODBC std esc terminator ODBC ext esc initiator d date value ODBC ext esc terminator ODBC date time extension Extended ODBC date literal ODBC time literal ODBC timestamp literal ODBC like escape clause Extended ODBC std esc initiator escape escape character ODBC std esc terminator ODBC ext esc initiator escape escape character ODBC ext esc terminator 5 of 11 SQL Grammar B 15 He
261. cating a statement handle SQLAllocStmt Canceling statement processing SQLCancel Setting a cursor name SQLSetCursorName INFORMIX CLI Function Reference 13 157 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 poParam 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 poParam Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_ERROR or SQL_INVALID_HANDLE 13 158 INFORMIX CLI Programmer s Manual Diagnostics SQL GetConnectOption When SQLGetConnectOption returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLGetConnectOption 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 08003 S1000 S1001 S1010 S1092 S1C00 Error General war
262. cation of fractional digits Conversion of data would result in loss of whole as opposed to fractional digits gt Data is not a numeric literal Data is within the range of the data type to which the number is being converted gt Data is outside the range of the data type to which the number is being converted gt Data is not a numeric literal Data is 0 or 1 Data is greater than 0 less than 2 and not equal to 1 Data is less than 0 or greater than or equal to 2 Data is not a numeric literal Length of data lt cbValueMax Length of data gt cb ValueMax INFORMIX CLI Programmer s Manual rgbValue Data Truncated data Data Truncated data Untouched Untouched Data Untouched Untouched Data Truncated data Untouched Untouched Data Truncated data pebValue Length of data Length of data Size of the C data type Size of the C data type Untouched Untouched Size of the C data type Untouched Untouched 1 c 1 c Untouched Untouched Length of data Length of data SQLSTATE N A 01004 N A 01004 22003 22005 N A 22003 22005 N A 01004 22003 22005 N A 01004 1 of 3 fCType SQL_C_DATE SQL_C_TIME SQL_C_TIMESTAMP Test Data value is a valid date value Data value is a valid timestamp value time portion is zero gt Data value is a valid timestamp value time portion is non zero
263. cation calls SQLDisconnect 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 has not been committed or rolled back with SQLTransact If an application calls SQLDisconnect before it has freed every hstmt associated with the connection the driver frees each remaining hstmt after it successfully disconnects from the data source Code Example See SOLBrowseConnect and SQLConnect Related Functions For information about See Allocating a connection handle SQLAllocConnect Connecting to a data source SOLConnect Connecting to a data source using a connection string or SQLDriverConnect dialog box Freeing a connection handle SQLFreeConnect Executing a commit or rollback operation SQLTransact 13 92 _INFORMIX CLI Programmer s Manual 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 in the odbc ini file SQLDriverConnect provides the following connection options m You can establish a connection using a connection string that contains the data source name one or more user IDs one or more passw
264. cation repeats steps 5 and 6 m fno more data at execution parameters exist the process is complete If the statement executes successfully SQLParamData returns SQL_SUCCESS or SQL_SUCCESS_WITH_INFO if the execution fails it returns SQL_ERROR At this point SQLParamData can return any SQLSTATE that can be returned by the function used to execute the statement SQLExecDirect or SQLExecute 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 SOQLExecute or SOLExecDirect returns SQL_NEED_DATA and before data is sent for all data at execution parameters the statement is canceled or an error occurs in SQLParamData or SQLPutData the application can call only SQLCancel SQLGetFunctions SOLParamData or SQLPutData with the hstmt or the hdbc associated with the hstmt If the application calls any other function with the hstmt or the hdbc associated with the hstmt the function returns SQL_ERROR and SQLSTATE 1010 Function sequence error If the application calls SQLCancel while the driver still needs data for data at execution parameters the driver stops executing the statement the application can then call SQLExecute or SQLExecDirect again If the appli cation calls SOQLParamData or SQLPutData after it cancels the statement the function returns SQL_ERROR and SQLSTATE S1008 Operation canceled
265. 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 multi threaded 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 SQLSTATE 1101 1C00 S1T00 Usage Error Accuracy option type out of range Driver not capable Time out expired SQL Statistics 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 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 requested result set The time out period is set through SQOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 SQLStatistics retur
266. ce 13 193 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 Dirty Read Transaction 1 changes a row Transaction 2 reads the changed row before transaction 1 commits the change If trans action 1 rolls back the change transaction 2 will have read a row that is considered to have never existed Nonrepeatable 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 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 reexecutes the 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 SQL_TXN_READ_UNCOMMITTED Dirty Reads Nonrepeatable Reads and Phantoms are possible SQL_TXN_READ_COMMITTED Dirty Reads are not possible Nonrepeatable Reads and Phantoms are possible SQL_TXN_REPEATABLE_READ Dirty Reads and Nonrepeatable Reads are not possible Phantoms are possible SQL_TXN_SERIALIZABLE Transactions are serializ
267. cies Demonstration Database New Features of This Product Conventions Typographical Conventions Icon Conventions Example Code Conventions Screen Illustration Conventions Additional Documentation Printed Documentation On Line Documentation Related Reading ry Compliance with Industry Bbndards Informix Welcomes Your Comments Overview of INFORMIX CLI What Is INFORMIX CLI Advantages of Using INFORMIX CLI Overview of the Initialization Files Understanding the odbcinst ini File Understanding the odbc ini File File Format for odbc ini File Examples for odbc ini ODBC Conformance Levels API Conformance Level of INFORMIX CLI SQL Conformance Level of INFORMIX CLI OMAN DAGWIHLW 1 3 1 5 1 6 1 6 1 7 1 11 1 12 1 12 1 14 iv Chapter 2 Chapter 3 Chapter 4 Mapping Data Types Supported Isolation and Lock tesil INFORMIX CLI INFORMIX CLI for UNIX Setting Up INFORMIX CLI System Requirements Setting Environment Variables Adding and Modifying Data Sources Adding a Data Source Sample Data Source Entry for odbei ini Modifying a Data Source Connecting to a Data Source Using Dialog Boxes to Connect to a i Data Source Using a Connection String to Connect to a Data Source INFORMIX CLI for Windows Setting Up INFORMIX CLI Systm Requirements Setting the INFORMIXDIR Environment Variable Adding and Modifying Data Sources Adding a Data Source Modifying a
268. component the error message must explain which component For errors that do not occur in a data source the error text must use the following format vendor_dentifier ODBC_component_identifier component_supplied_text Retrieving Status and Error Information 8 5 Sample Error Messages 8 6 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 that received the error directly from the data source ODBC_component_identifier Identifies the component in which the error occurred or that received the error directly from the data source data_source_identifier Identifies the data source For multiple tier drivers this is the DBMS product component_supplied_text Error text generated by the ODBC component the driver manager or the driver data_source_supplied_text Error text generated by the data source The brackets are included in the error text they do not indicate optional items 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 An INFORMIX CLI driver sends requests to a DBMS and returns information to the application through the driver manager Because it is the component that interfaces with the dr
269. creasing column number and are not in a row ina block of rows 8 of 22 INFORMIX CLI Function Reference 13 197 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 SQL_GB_NOT_SUPPORTED GROUP BY clauses are not supported SQL_GB_GROUP_BY_EQUALS_SELECT The GROUP BY clause must contain all nonaggregated columns in the SELECT list It cannot contain any other columns For example SELECT DEPT MAX SALARY FROM EMPLOYEE GROUP BY DEPT SQL_GB_GROUP_BY_CONTAINS_SELECT The GROUP BY clause must contain all nonaggregated 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 SQL_GB_NO_RELATION The columns in the GROUP BY clause and the select list are not related The meaning of nongrouped nonaggregated columns in the SELECT list is data source dependent For example SELECT DEPT SALARY FROM EMPLOYEE GROUP BY DEPT AGE SQL_IDENTIFIER_CASE A 16 bit integer value as follows SQL_IC_UPPER Identifiers in SQL are case insensitive and are stored in uppercase in system catalog SQL_IC_LOWER Identifiers in SQL are case insensitive and are stored in lowercase in system catalog SQL_IC_SENSITIVE Identifiers in SQL are case sensitive and are stored in mixed case in system catalog
270. crolls 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 in a keyset driven cursor is considered to be deleting the existing row and adding a new row this value is always returned for keyset 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 7 10 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_SYS_IFNULL SQL_FN_SYS_USERNAME A character string with the data source vendor name for a table for example table or file 19 of 22 InfoType SQL_TIMEDATE_ADD_INTERVALS SQL_TIMEDATE_DIFF_INTERVALS SQLGetInfo 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 SQL_FN_TSI_FRAC_SECOND SQL_FN_TSI_SECOND SQL_FN_TSI_MINUTE SQL_FN_TSI_LHOUR SQL_FN_TSI_DAY SQL_FN_TSI_LWEEK SQL_FN_TSI_LMONTH SQL_FN_TSI_LQUARTER SQL_FN_TSI_YEAR A 32 bit bitmask that enumerates the time stamp intervals suppo
271. cter C data the character count returned in pcebValue does not include the null termi nation byte If rgbValue is a null pointer SQLBindCol or SQLGetData returns SQLSTATE 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 ODBC SQL grammar For the syntax of grammar elements see Appendix B SQL to C Character The character ODBC SQL data types are found in the following list m SQL_CHAR m SQL_VARCHAR m SQL_LONGVARCHAR The following table shows the ODBC C data types to which character SQL data can be converted For an explanation of the columns and terms in the table see the previous list Data Types C 15 SQL to C Character fCType SQL_C_CHAR SQL_C_STINYINT SQL_C_UTINYINT SQL_C_TINYINT SQL_C_SSHORT SQL_C_USHORT SQL_C_SHORT SQL_C_SLONG SQL_C_ULONG SQL_C_LONG SQL_C_FLOAT SQL_C_DOUBLE SQL_C_BIT SQL_C_BINARY C 16 Test Length of data lt cb ValueMax Length of data gt cbValueMax Data converted without truncation Data converted with trun
272. ction string Upon successful connection to the target data source this buffer contains the completed connection string Applications 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 cbConnStrOutMax the completed connection string in szConnStrOut is truncated to cbConnStrOutMax 1 bytes Flag that indicates whether driver manager or driver 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 Guide lines on page 13 100 and Driver Guidelines on page 13 101 SQL DriverConnect Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLDriverConnect returns either SOQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SOLDriverConnect 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE
273. cute An appli cation calls SOLTransact to commit or roll back a transaction Figure 6 1 illustrates a simple sequence of function calls to execute SQL statements Executing SQL Statements 6 3 6 4 Initialize Repeatable Execution Te SQLBinatParameter SQL Prepare SQLBindtParameter SQLExecDirect q SQLExecute Kind of Statement SELECT UPDATE DELETE statement or INSERT statement SQLNumResultsCol SQLDescribeCol SQLBindCol SISERA K E SQLhetch SQLRowCount More Rows No SQLFreeStmt SQLTransact if repeat y if more processing Terminate INFORMIX CLI Programmer s Manual Figure 6 1 A Sequence of Function Calls to Execute SQL Statements Allocating a Statement Handle Allocating a Statement Handle Before your application can submit an SQL statement you 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 SQLAIlocStmt and passes it the address of the variable and the connected hdbc with which to associate the statement The driver allocates memory to store information about the statement associates the statement handle with the hdbc and returns the statement handle in the variable Executing an SQL Statement Your application can submit an SQL statement f
274. cuting or completing the function 1 of 2 SQL GetCursorName SQLSTATE Error Description S1010 Function DM SQLExecute or SQLExecDirect was called sequence 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 1015 No cursor name DM There was no open cursor on the hstmt available and no cursor name had been set with SQLSetCursorName 1090 Invalid string or DM The value specified in the argument buffer length cbCursorMax was less than 0 2 of 2 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 SQLSetCur sorName 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 SQOLFreeStmt with the SQL_DROP option INFORMIX CLI Function Reference 13 163 SQL GetData Related Functions For information about See Executing an SQL statement SQOLExecDirect Executing a prepared SQL statement SQLExecute Preparing a statement for execution SQLPre
275. d SQL_NEED_DATA This function was called before data was sent for all data at execution parameters or columns 1 of 2 SQLSTATE S1090 S1097 S1098 S1099 S1C00 S1T00 Error 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 SQL_NTS The value of one of the 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 SOLGetInfo with the finfoType values SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME_LEN or SQL_MAX_TABLE_NAME_LEN DM An invalid fColType 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 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 requested result set The time out period is set through SQOLSetStmtOption SQL_QUERY_TIMEOUT 2 of 2 INFORMIX CLI
276. d before SQLExecute is called depending on when the data source evaluates the SOL statement associated with the hstmt Usage 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 See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SQLCancel Returning information about a column in a result set SQOLColAttributes Returning information about a column in a result set SQLDescribeCol Fetching a block of data or scrolling through a result set SQLExtendedFetch Fetching a row of data SQLFetch Fetching part or all of a column of data SOLGetData Setting cursor scrolling options SQLSetScrollOptions INFORMIX CLI Function Reference 13 235 SQL ParamData SQLParamData SQLParamData 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 PTRFAR prgbValue Output Pointer to storage for the value specified for the rgbValue argument in SQLBindParameter for parameter data or the address of the rgb Value buffer specified in SQLBindCol for column data Return Codes SQL_SUCCESS SOQL_SUCCESS_WITH_INFO
277. d free all resources associated with the handle 9 4 INFORMIX CLI Programmer s Manual Constructing an INFORMIX CLI Application StaticSQLExample s 2 2 eoa ee ee en 10 4 Interactive Ad Hoc Query Example 2 2 2 2 ww 10 7 10 2 INFORMIX CLI Programmer s Manual his chapter provides the following examples of C language source code for INFORMIX CLI enabled applications m Anexample that uses static SQL functions to create a table add data to it and select the inserted data m Anexample of interactive ad hoc query processing Constructing an INFORMIX CLI Application 10 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 fendif 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 hdbc HSTMT hstmt SDWORD id UCHAR nameL MAX_NAME_LEN 1 UCHAR createLMAX_STMT_LEN UCHAR insert MAX_STMT_LEN UCHAR selectLMAX_STMT_LEN SDWORD namelen RETCODE rc EXEC SQL CONNECT TO server USER uid USING pwd Allocate an environment handle Ef Allocate a connection handle a Connect to a data source ey A
278. d to return an error if the driver and its associated data source can simultaneously support multiple active connections Comparison Between INFORMIX CLI and Embedded SQL D 9 Diagnostic Statement Diagnostic Statement The following table lists the GET DIAGNOSTIC statement INFORM IX CLI Section SQL Statement Function Comments 5 6 1 GET SQLError For SQLError the following fields DIAGNOSTICS SQLRowCount from the diagnostics area are available RETURNED_SQLSTATE MESSAGE_TEXT and MESSAGE_LENGTH For SQLRowCount the ROW_COUNT field is available D 10 INFORMIX CLI Programmer s Manual Index A Access mode 13 105 Access plans 6 6 ALIAS table type 13 325 Aliases column 13 193 ALTER TABLE statements data type names B 1 interoperability 6 3 modifying syntax 6 3 qualifier usage in 13 207 supported clauses 13 193 API conformance definition of 1 12 Application interactive example 10 7 static example 10 4 Architecture INFORMIX CLI 1 3 ODBC error handling 8 5 Arguments naming conventions 13 6 null pointers 3 6 pointers 3 5 search patterns 13 10 SQLTables 13 324 See also Parameters Arrays 11 See Binding columns column wise See Parameters arrays Association management statements D 9 Asterisk 13 46 Attributes columns 13 57 13 91 connection string for driver UNIX 2 13 2 28 data source specification for driver UNIX 2 9 definition of 1 9 Auto commit mode described 6 9 specifying
279. d 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 hstmt that were returned by SQLExecDirect are removed when SQLExecDirect or SQLTables is called with that hstmt The errors stored on a specific handle are not removed as the result of a call to a function using an associated handle of a different type For example errors on an hdbc that were returned by SOLNativeSq are not removed when SQLError or SQLExecDirect is called with an hstmt associated with that hdbc For more information about error codes see Appendix A 13 110 INFORMIX CLI Programmer s Manual SQLExecDirect Related Functions None 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 SQLExecDirect 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 SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_NEED_DATA SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference
280. data source If no limit is specified or the limit is unknown this value is set to 0 1 of 22 InfoType SQL_ALTER_TABLE SQL_BOOKMARK_ PERSISTENCE UNSUPPORTED SQL_COLUMN_ALIAS SQL_CONCAT_NULL_BEHAVIOR SQL_CONVERT_FUNCTIONS UNSUPPORTED SQL_CORRELATION_NAME SQLGetInfo Returns 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 SQL_AT_ADD_COLUMN SQL_AT_DROP_COLUMN INFORMIX CLI does not support this option A character string Y if the data source supports column aliases otherwise N is returned 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 SQL_CB_NULL Result is NULL valued SQL_CB_NON_NULL Result is concatenation of non NULL valued column or columns INFORMIX CLI does not support this option A 16 bit integer that indicates if table correlation names are supported SQL_CN_NONE Correlation names are not supported SQL_CN_DIFFERENT Correlation names are supported but they must differ from the names of the tables that they represent SQL_CN_ANY Correlation names are supported and can be any valid user defined name 2 of 22 INFORMIX CLI Function Reference 13 191 SQL Getinfo InfoType SQL_CURSOR_COMMIT_BEHAVIOR
281. data and the returned numbers of bytes Finally the application fetches the rowset data with SOLExtendedFetch and prints each employee s name and birthday ifdefine ROWS 100 ifdefine NAME_LEN 30 tdefine BDAY_LEN 11 UCHAR szNameLROWS J NAME_LEN szBirthdayLROWS J BDAY LEN SWORD sAgeLROWS SDWORD cbNameLROWS cbAgeLROWS cbBirthdayLROWS UDWORD crow irow UWORD rgfRowStatus ROWS Q 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 szName NAME_LEN cbName SQLBindCol hstmt 2 SQL_C_SSHORT sAge 0 cbAge SQLBindCol hstmt 3 SQL_C_CHAR szBirthday BDAY_LEN cbBirthday Fetch the rowset data and print each row 13 140 INFORMIX CLI Programmer s Manual On an error display a message SQLExtendedFetch hs rg if retcode SQL_ERROR show_error while TRUE retcode if retcode for irow SQL_SUCCESS 0 irow lt cro if rgfRowStatusLirow rgfRowStatus irow fprintf out s NAME_LEN BDAY_LEN 1 else break Row Wise Binding In the following example an appli hold row wise bound data and the SQLExtendedFetch and exit tmt
282. data source If you do not set a new default the default value that is listed in the table will apply Attribute Description Description A long description that identifies the data source Default User The host user ID Name Host Name The name of the computer on which the INFORMIX OnLine Dynamic Server INFORMIX OnLine or INFORMIX SE database server resides 1 of 2 INFORMIX CLI 2 17 Adding a Data Source 2 18 Attribute Service Name Server Name Get DB List from Informix Database List INFORMIX CLI Programmer s Manual Description The name assigned to the Informix database server process running on your UNIX computer Commonly the service is sqlexec Confirm the service name with your system administrator The name of the OnLine or SE database server on which the database that you want to access resides available only for Windows 95 and Windows NT A value of 0 or 1 that determines from where the driver requests the database list to be returned m 1 Request the database list from the database server This is the default setting m 0 Use the database list that is specified by the user at driver setup The list of databases that will be displayed in the logon dialog box that is the databases to which you will be able to connect if Get DB List From Informix is set to 0 If more than one name is specified the names must be separated by commas 2 of 2 Adding a Data Source Optio
283. data source failed before the function completed 24000 Invalid cursor state A cursor was already opened on the statement 1 of 3 SQLProcedures SQLSTATE Error Description 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 The driver was unable to allocate memory allocation failure required to support execution or completion of the function S1008 Operation The function was called but before it canceled completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application S1010 Function DM SQLExecute or SQLExecDirect was called sequence 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 corresponding qualifier or name 2 of 3 INFORMIX CLI Function Reference 13 257 SQL Procedures SQLSTATE Error Description S 1C00 Driver not capable A procedure qualifier was specified but the driver or data source does not support qualifiers A procedure owner was s
284. ddress of an output buffer can be a null pointer In this case the driver does not return anything in the buffer and in the absence of other errors returns SOQL_SUCCESS If necessary the driver converts data before returning it The driver always null terminates character data before returning it m The length of the buffer This value is ignored by the driver if the returned data has a fixed length in C such as an integer real number or date structure m 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 SQL_NULL_DATA if the data is a NULL value in a result set Otherwise it is the number of bytes of data that are available to return If the driver converts the data it is the number of bytes that remain after the conversion For character data it does not include the null termination byte added by the driver 3 6 INFORMIX CLI Programmer s Manual Environment Connection and Statement Handles 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
285. des for support for a cursor specification and statements allowed in an EXECUTE IMMEDIATE dynamic SQL statement In the case of a cursor specification the call corresponds to static SQL DECLARE CURSOR and OPEN statements COUNT form of dynamic SQL 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 VALUE form of dynamic SQL GET DESCRIPTOR with field name in NAME TYPE LENGTH PRECISION SCALE NULLABLE This function establishes output buffers that correspond in usage to host variables for static SQL FETCH and to an SQL DESCRIPTOR for dynamic SQL FETCH cursor USING SQL DESCRIPTOR descriptor 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 specified in SQLBindCol 2 of 3 D 3 INFORMIX CLI to Embedded SQL D 4 SQLRowCount SQLFreeStmt SQL_CLOSE option SQLFreeStmt SQL_DROP option SQLTransact SQLDisconnect SQLFreeConnect SOQLFreeEnv SQLCancel SQLError INFORMIX CLI Programmer s Manual INFORMIX CLI Function Statement GET DIAGNOSTICS CLOSE none COMMIT WORK or COMMIT ROLLBACK DISCONNECT none none none GET DIAGNOSTICS Comments Requested field ROW_COUNT Dynamic SQL CLOSE Driver
286. drops any hstmts open on the hdbc Code Example See SQLBrowseConnect and SQLConnect INFORMIX CLI Function Reference 13 151 SQL FreeEnv Related Functions For information about See Allocating a statement handle SQLAllocConnect Connecting to a data source SOLConnect Disconnecting from a data source SQOLDisconnect Connecting to a data source using a connection SQLDriverConnect string or dialog box Freeing an environment handle SQLFreeEnv Freeing a statement handle SQLFreeStmt 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 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE 13 152 INFORMIX CLI Programmer s Manual SQLFreeEnv Diagnostics When SQLFreeEnv returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLFreeEnv 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error Description 01000 General warning INFORMIX CLI infor
287. dvantage of the GLS feature you must connect to an Informix database server of Version 7 2 or later For more information see the Guide to GLS Functionality e INFORMIX CLI 2 15 Setting the INFORMIXDIR Environment Variable Windows 3 1 Setting the INFORMIXDIR Environment Variable Before you can use INFORMIX CLI make sure that the INFORMIXDIR environment variable is set to the full path of the directory where your Informix product is installed SET INFORMIXDIR C INFORMIX For Windows 3 1 and Windows 95 set this information in the AUTOEXEC BAT file For Windows NT set this information in the Registry Adding and Modifying Data Sources A data source is a database or file that INFORMIX CLI accesses To add and configure data sources use the ODBC Administrator The ODBC Adminis trator then updates your ODBC INI file in Windows 3 1 or your Registry in Windows 95 and Windows NT to reflect your data source connection information Adding a Data Source In Windows 3 1 the ODBC INI file is an initialization file used by the INFORMIX CLI and is located in the WINDOWS directory This file contains information about each data source Before you can connect to a data source you must use the ODBC Administrator to add the connection information for the data source to the ODBC INI file For complete information on the format and contents of this file refer to Understanding the odbc ini File on page 1 7 Warning Window
288. e specified in the argument fCType The argument icol was 0 and the driver does not support bookmarks INFORMIX CLI Function Reference 13 19 SQLBindCol Usage The INFORMIX CLI interface provides the following ways to retrieve a column of data m SQLBindCol assigns the storage location for a column of data before the data is retrieved When SQLFetch or SOLExtendedFetch 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 SQLFetch 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 SQLBindCol to retrieve data only and not bind with SQLGetData or to use a combination However unless the driver provides extended functionality SQLGetData can be used only to retrieve data from columns that occur after the last bound column An application calls SQLBindCol 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 a list
289. e 13 207 Queries See SQL statements Question mark browse result connection string 13 46 parameter markers 13 120 13 250 Queues error 13 112 Quoted identifiers case sensitivity 13 208 R Radix 13 74 Read committed isolation level 13 196 Read only access mode 13 105 data sources 13 194 Read uncommitted isolation level 13 196 Reads dirty 13 196 Reads nonrepeatable 13 196 Read write access mode 13 105 REFERENCES statements 13 67 Referential integrity 13 205 B 1 Refreshing data SQLExtendedFetch 13 140 Release notes Intro 14 Remarks 13 74 13 325 Repeatable read isolation level 13 196 Result sets arrays See Rowsets binding columns 7 4 column attributes 7 4 described 4 3 7 3 fetching data 7 5 fetching rowsets 7 9 multiple 13 203 number of columns 7 4 number of rows 7 4 retrieving data in parts 7 7 rowset size 7 7 SQLBindCol 13 22 SQLColAttributes 13 57 SQLDescribeCol 13 87 SQLFreeStmt 13 156 SQLMoreResults 13 229 SQLNumResultCols 13 235 SQLRowCount 13 272 See also Cursors See also Rows Result states See State transitions Retrieving data arrays See Rowsets binding columns See Binding columns cursor position 13 136 13 150 disabling 13 295 fetching data 7 5 fetching rowsets 7 9 in parts 7 7 13 174 long data values 7 7 maximum length 13 294 multiple result sets 13 203 NULL data 13 23 13 150 13 173 retrieving 13 295 rows See Rows SQLExtendedFetch 13 134 SQLFetch 13 150 SQLGetData
290. e Data Type Comments TABLE_QUALIFIER VARCHAR 128 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 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 DBMSs it returns an empty string for those tables that do not have owners TABLE_NAME VARCHAR 128 Table identifier not NULL COLUMN_NAME VARCHAR 128 Column identifier not NULL 1 of 3 13 70 INFORMIX CLI Programmer s Manual Column Name DATA_TYPE TYPE_NAME PRECISION LENGTH SCALE Data Type SMALLINT not NULL VARCHAR 128 not NULL INTEGER INTEGER SQLColumns Comments SQL data type For a list of valid ODBC SQL data types see Appendix C For information on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 Data source dependent data type name for example CHAR VARCHAR MONEY LONG VARBINARY or CHAR for BIT DATA The precision of the column on the data source For precision infor mation see Precision Scale Length and Display Size on page C 8 The length in bytes of data trans f
291. e database that Agencies accesses is called agencies and it resides on the database server The Data Source Specification entry for the Agencies data source might look like the following example Agencies Driver usr informix cli dlls qeinf708 so Database agencies LogonID marvin Overview of INFORMIX CLI 1 9 File Format for odbe ini 1 10 Default Data Source Specification This section for both UNIX and Windows is optional The Default Data Source Specification contains information about the default data source This data source is called Default and has the same format as any other Data Source Specification section however the Default data source is not listed in the ODBC Data Sources section The following example shows a Default Data Source Specification entry for an Informix database Default Driver usr informix cli dlls qeinf708 so Database Stores LogonID marvin ODBC Options The ODBC Options section indicates whether tracing is enabled or disabled With tracing all ODBC function calls made from an application can be logged to the specified trace file This section has the following format ODBC Trace 0 1 TraceFile tracefile_path TraceAutoStop 0 1 This section lists the following information Trace indicates whether tracing is enabled If the Trace keyword is set to 0 tracing is disabled If the Trace keyword is set to 1 tracing is enabled TraceFile is the name of the specified trace
292. e dependent data type name for example CHAR VARCHAR MONEY LONG VARBINARY or CHAR FOR BIT DATA If the type is unknown an empty string is returned 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 updat ability 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 40f4 INFORMIX CLI Function Reference 13 59 SQLColumnPrivileges Related Functions For information about See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SQLCancel Returning information about a column in a result set SQLDescribeCol Fetching a block of data or scrolling through a result set SQLExtendedFetch Fetching a row of data SQLFetch 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 szTableQualifier cbTableQualifier szTableOwner cblableOwner szTableName cbTableName szColumnName cbColumnName 13 60 INFORMIX CLI Programm
293. e 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 native error value in the Informix Error Messages manual Retrieving Status and Error Information 8 7 Processing Error Messages Processing Error Messages In your application provide users with all the error information available through SQLError the SOLSTATE the native error code the error text and the source of the error The application might parse the error text to separate the text from the information that identifies the source of the error The appli cation must take appropriate action based on the error or provide the user with a choice of actions 8 8 INFORMIX CLI Programmer s Manual Terminating Transactions and Connections Terminating Statement Processing 9 3 Terminating Transactions 2 2 ee ee ee a 9 4 Terminating Connections 2 2 2 ee en 9 4 9 2 INFORMIX CLI Programmer s Manual he INFORMIX CLI interface provides functions that terminate state ments transactions and connections as well as free statement hstmt connection hdbc and environment henv handles Terminating Statement Processing To
294. e for the SQL data types that INFORMIX CLI supports In the table precision refers to the total number of digits and scale refers to the number of digits to the right of the decimal point To determine which data types are supported by a data source and the characteristics of those data types an application calls SQLGetTypelInfo For information about how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 For information on Informix data types refer to the Informix Guide to SQL Reference fSqlType SQL Data Type Description SQL_CHAR CHAR n Character string of fixed string length n 1 lt n lt 254 SQL_VARCHAR VARCHAR n Variable length character string with a maximum string length n 1 lt n 254 SQL_LONGVARCHAR LONG VARCHAR Variable length character data Maximum length is data source dependent SQL_DECIMAL DECIMAL p s Signed exact numeric value with a precision p and scales 1 lt p lt 15 O lt s lt p SQL_SMALLINT SMALLINT Exact numeric value with precision 5 and scale 0 signed 32 768 lt n lt 32 767 unsigned 0 lt n lt 65 535 SQL_INTEGER INTEGER Exact numeric value with precision 10 and scale 0 signed 231 lt n lt 2 1 unsigned 0 lt n lt 232 a 1 1 of 2 C 2 INFORMIX CLI Programmer s Manual ODBC SQL Data Types That INFORMIX CLI Supports fSqlType SQL Data Type SQL_REAL REAL SQL_DOUBLE DOUBLE PRECISION SQL_LONGVA
295. e is an HSTMT variable type An appli cation must request a statement handle before it submits SQL requests Each statement handle is associated with exactly one connection handle However each connection handle can have multiple statement handles associated with it Guidelines for Calling INFORMIX CLI Functions 3 7 Using Data Types For more information about requesting a connection handle see Connecting to a Data Source on page 5 5 For more information about requesting a statement handle see Executing an SQL Statement on page 6 5 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 SOLGetTypelInfo 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 SOQLGetData or SOLBindParameter Before the driver returns data from the data source it converts the data to the specified C data ty
296. e loaded for some other reason 1 of 3 SQLSTATE IM004 IM005 IM006 IMO009 S1000 S1001 Error Driver SQLAI locEnv failed Driver SQLAlloc Connect failed Driver SQLSetConnect Option failed Unable to load translation shared library General error Memory allocation failure SQLConnect Description DM During SOLConnect the driver manager called the driver SQLAIlocEnv function and the driver returned an error DM During SQLConnect the driver manager called the driver SQLAllocConnect function and the driver returned an error DM During SQLConnect 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 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 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 2 of 3 INFORMIX CLI Function Reference 13 77 SQLConnect 13 78 SQLSTATE Error 1090 Invalid string or buffer length S1T00 Time out expired Usage for the specif
297. e procedures stored in a data source an application calls SQOLProcedures INFORMIX CLI Programmer s Manual Related Functions Related Functions INFORMIX CLI also provides the following functions related to SQL state ments For more information about these functions see Chapter 13 INFORMIX CLI Function Reference Function SQLNativeSql SQLNumParams SQLSetStmtOption SQLSetConnectOption SOQLGetStmtOption 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 rowsets maximum amount of variable length data to return maximum number of result set rows to return and query time out value SOLSet ConnectOption sets options for all the statements in a connection Executing SQL Statements 6 19 Retrieving Results Assigning Storage for Results Binding a 7 4 Determining the Characteristics ofa ResultSet 2 2 7 4 Fetching Result Data 2 2 a a a a a 7 5 Using Cursors b a a Oh ag a ol 7 6 Retrieving Data from Unbound Columns Ay he th oy A SET Assigning Storage for Rowsets Binding 1 7 7 Column Wise and Row Wise ee Ashi be vaca ee Retrieving Rowset Data is Wes theca GaGa gg fan eG 7 9 Using Block and Scrollable Cursors sige eth eee GT
298. e 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 to the odbc ini file SQLWriteDSNToIni adds the data source name to the ODBC Data Sources section creates the data source speci fication section and adds the Driver keyword with the driver description as its value ConfigDSN calls SQLWritePrivateProfileString in the installer shared library to add more keywords and values that the driver needs Setup Shared Library Function Reference 14 5 ConfigDSN Modifying a Data Source To modify a data source a data source name must be passed to ConfigDSN in IpszAttributes ConfigDSN checks that the data source name is in the odbc ini file If hwndParent is null ConfigDSN uses the information in lpszAttributes to modify the information in the odbc ini file If hwndParent is not null ConfigDSN displays a dialog box that uses the information in IpszAttributes for information that is not in p
299. eInfo returns the maximum precision and the minimum and maximum scales of an SQL data type on a data source Because of limitations in the size of the arguments that these functions use precision length and display size are limited to the size of an SDWORD or 2 147 483 647 INFORMIX CLI Programmer s Manual Precision Precision The precision of a numeric column or parameter refers to the maximum number of digits used by the data type of the column or parameter The precision of anonnumeric column or parameter generally refers to either the maximum length or the defined length of the column or parameter To determine the maximum precision allowed for a data type an application calls SQLGetTypelnfo The following table defines the precision for each ODBC SQL data type fSqlType SQL_CHAR SQL_VARCHAR SQL_LONGVARCHAR SQL_DECIMAL SQL_SMALLINT SQL_INTEGER SQL_REAL SQL_DOUBLE SQL_LONGVARBINARY P SQL_DATE SQL_TIMESTAMP Precision The defined length of the column or parameter For example the precision of a column defined as CHAR 10 is 10 The maximum length of the column or parameter The defined number of digits For example the precision of a column defined as NUMERIC 10 3 is 10 5 10 7 15 The maximum length of the column or parameter 10 the number of characters in the yyyy mm dd format The number of characters in the yyyy mm dd hh mmi ss f format
300. ecified in the current call was before the column specified in the preceding call This description does not apply to drivers that return the SQL_GD_ANY_ORDER bitmask for the SQL_GETDATA_EXTENSIONS option in SQLGetInfo DM The argument fCType was nota valid data type or SQL_C_DEFAULT 3 of 5 INFORMIX CLI Function Reference 13 169 SQL GetData 13 170 SQLSTATE S1008 S1009 S1010 S1090 S1109 Error Operation canceled Invalid argument value Function sequence error Invalid string or buffer length Invalid cursor position INFORMIX CLI Programmer s Manual Description The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application DM The argument rgbValue 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 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 specified for argument cbValueMax was less than 0 The cursor was positioned by SQLExtended Fetch on a row for which the value in the rgfRowStatus array in SQLExtendedFetch was SQL_ROW_DELETED or SQL_ROW_ERROR 4 of 5 SQ_GetData SQLSTATE Error Description S1C00 D
301. ecifying only the long columns in the select list How often do users want to see long data By default it is generally acceptable not to retrieve long data or binary data because most users do not want to see such information If the user does wish to see these result items then 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 having to pay 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 ODBC driver that is some applications simply SELECT FROM lt table name gt If the select list contains long data then 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 11 8 INFORMIX CLI Programmer s Manual Use SQLSetStmtOption to Reduce the Size of Data Retrieved Use SQLSetStmt Option to Reduce the Size of Data Retrieved To reduce the size of any data being retrieved to some manageable limit call SQLSetStmtOption with the SQL_MAX_SIZE option This option reduces network traffic and improves performance by allowing the driver to commu nicate to the DBMS backend server that only Z b
302. ed in the driver manager it can also be implemented in drivers If a driver implements SQLGetFunctions the driver manager calls the function in the driver Otherwise it executes the function Syntax RETCODE SQLGetFunctions hdbc fFunction pfExists 13 174 INFORMIX CLI Programmer s Manual SQLGetFunctions The SQLGetFunctions function accepts the following arguments Type Argument Use HDBC hdbc Input UWORD fFunction Input UWORD FAR pfExists Output Return Codes 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 13 177 If fFunction is SQL_API_LALL_FUNCTIONS pfEx ists 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 SQL_API_LALL_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 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_I
303. ed to return only one result row and unwanted rows are filtered by the DBMS In addition if the TableType argument can be supplied then the SQL sent to the server can be optimized from a three query union to a singleton SELECT similar to the following command SELECT FROM SysTables WHERE TableName Customers and Owner Beth 11 6 INFORMIX CLI Programmer s Manual Avoid Using SQLColumns to Determine Table Characteristics Avoid Using SQLColumns to Determine Table Characteristics Avoid using SQLColumns to determine characteristics about a table Instead use a dummy query with SQLDescribeCol In both cases the application sends a query to the server When the application calls SQLColumns the database server must evaluate the query and form a result set that must then must be sent back to the client When the application makes a dummy query with SOLDescribeCol the database server does not execute the query it only prepares it Thus no results are sent back to the client Consider an ad hoc application that allows the user to choose the columns that will be selected Should the application use SQLColumns to return infor mation about the columns to the user or instead prepare a dummy query and call SQLDescribeCol Case 1 SQLColumns Method rc SQLColumns UnknownTable This call to SQLColumns will generate a query to the system catalogs possibly a join which must be prepared
304. edFetch SQLFetch SQLGetData SQLGetInfo SQLGetTypelnfo SQLMoreResults SQLNumParams SQLNumResultCols SQLParamData SQLPrepare SQLPrimaryKeys SQLProcedures SQLPutData SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables 13 of 13 SQL Grammar This chapter describes the recommended syntax for maximum interoperability in calls to SOLPrepare SQLExecute and SQLExecDirect To the right of each construct is an indicator that tells whether the construct is part of the minimum grammar the core grammar or the extended grammar Important Informix database servers provide extensions to SQL other than those defined by ODBC To use one of these extensions refer to Informix Guide to SQL Syntax If your application uses the Informix specific syntax it is not interoperable among DBMSs The Integrity Enhancement Facility IEF is included in the grammar but is optional The grammar for the IEF comes from the X Open and SQL Access Group SQL CAE specification 1992 and is a subset of the ISO SQL 92 standard Elements that are part of the IEF and are optional in the ANSI 1989 standard are presented in the following typeface and font distinct from the rest of the grammar table constraint definition Important In CREATE TABLE and ALTER TABLE statements applica tions must use the data type name returned by SQLGetTypelnfo in the TYPE_NAME column Parameter Data Types Parameter Data Types Although each parame
305. edure has substantial overhead but the ODBC driver assumes that the statement will be executed multiple times 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 Using SOLPrepare SQLExecute for a statement that will be executed only once with such an ODBC driver will result in unneeded overhead Furthermore applications that use SQLPrepare SQLExecute for large single execution query batches will almost certainly exhibit poor performance when they are used with ODBC drivers Similar arguments can be used to show applications that always use SQLExecDirect cannot perform as well as those that logically use a combi nation of SOLPrepare SQLExecute and SQLExecDirect sequences Using SQLPrepare and Multiple SQLExecute Calls Applications that use SQLPrepare and multiple SQLExecute calls should use SQLParamOptions Passing arrays of parameter values reduces the ODBC call load and greatly reduces network traffic Consider the following pseudocode for inserting data in bulk rc SQLPrepare hstmt INSERT INTO DailyLedger VALUES CB Eee SOLANTS 3 bind parameters do read ledger values into bound parameter buffers rc SQLExecute hstmt insert row while eof INFORMIX CLI Programmer s Manual Updating Data If there are 100 rows to insert SQLExecute is called 100 times resulting in 100 n
306. ength generated by a SELECT statement If the column is an expression szColName is either an empty string or a driver defined name INFORMIX CLI Function Reference 13 89 Related Functions 13 90 INFORMIX CLI Related Functions For information about See Assigning storage fora column ina result SQLBindCol set Canceling statement processing SQLCancel Returning information about acolumnina SQLColAttributes result set Fetching a row of data SQLFetch Returning the number of result set columns SQLNumResultCols Preparing a statement for execution SQLPrepare 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 SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE Programmer s Manual Diagnostics SQLDisconnect When SQLDisconnect returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLDis connect 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000
307. ent with first row K strcpy szName Jones Bob K Specify second row of sAge 52 parameter data Xf dsBirthday year 1940 dsBirthday month 3 dsBirthday day 31 SQLExecute hstmt Execute statement with second row 7 For other similar examples see SQLParamOptions SQLProcedures and SQLPutData INFORMIX CLI Function Reference 13 37 SQL BrowseConnect Related Functions For information about See Executing an SQL statement SQOLExecDirect Executing a prepared SQL statement SQLExecute Returning the number of statement SOLNumParams parameters Returning the next parameter to send SQLParamData data for Specifying multiple parameter values SQLParamOptions Sending parameter data at execution SQLPutData time 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 SOQLBrowseConnect 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 has been specified and the application is now connected to the data source Syntax RETCODE SQLBrowseConnect hdbc szConnStriIn cbConnStrIn szConnStr0ut cbConnStr0utMax pcbConnStr0dut 13
308. ented Applications 11 9 Use SQLBindCol to Reduce the Call Load 11 10 Many ODBC drivers allow limiting the amount of data retrieved across the network by supporting the statement option SQL_MAX_SIZE This option allows the driver to communicate to the database server that only Z bytes of data are pertinent to the client The server responds by sending only the first Z bytes of data for all result columns This optimization greatly reduces network traffic and thus improves performance of the client The preceding example returned just one row but consider the case where 100 rows are returned in the result set The performance improvement is substantial Use SQLBindCol to Reduce the Call Load To improve performance retrieve data through bound columns SQLBindCol instead of using SOLGetData to reduce the ODBC call load Consider the following pseudo code fragment 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 Suppose the query returns 90 result rows The number of ODBC calls made is gt 1890 20 calls to SQLGetData x 90 result rows 91 calls to SQLFetch Consider the same scenario that uses SOLBindCol instead of SOQLGetData rc SQLExecDirect hstmt SELECT lt 20 columns gt FROM Employees WHERE HireDate gt SQL_NTS call SQL
309. ept for the decimal point and fractional seconds the entire format must be used regardless of the precision of the time stamp SQL data type SQL to C Data Conversion Examples The following table illustrates how the driver converts SQL data to C data SQL Data Type SQL Data Value C Data Type cbValueMax rgbValue SQLSTATE SQL_CHAR abcdef SQL_C_CHAR 7 abcdef 0 N A SQL_CHAR abcdef SQL_C_CHAR 6 abcde 0 01004 SQL_DECIMAL 1234 56 SQL_C_CHAR 8 1234 56 0 N A SQL_DECIMAL 1234 56 SQL_C_CHAR 5 1234 02 01004 SQL_DECIMAL 1234 56 SQL_C_CHAR 4 me 22003 SQL_DECIMAL 1234 56 SQL_C_FLOAT ignored 1234 56 N A SQL_DECIMAL 1234 56 SQL_C_SSHORT ignored 1234 01004 SQL_DECIMAL 1234 56 SQL_C_STINYINT ignored 22003 SQL_DOUBLE 1 2345678 SQL_C_DOUBLE ignored 1 2345678 N A SQL_DOUBLE 1 2345678 SQL_C_FLOAT ignored 1 234567 N A SQL_DOUBLE 1 2345678 SQL_C_STINYINT ignored 1 N A 1 of 2 Data Types C 23 Converting Data from C to SQL Data Types SQL Data Type SQL_DATE SQL_DATE SQL_DATE SQL_TIMESTAMP SQL_TIMESTAMP SQL_TIMESTAMP SQL Data Value C Data Type cbValueMax rgbValue SQLSTATE 1992 12 31 SQL_C_CHAR 11 1992 12 31 0 N A 1992 12 31 SQL_C_CHAR WO 22003 1992 12 31 SQL_C_TIMESTAMP ignored 1992 12 31 N A 0 0 0 0 gt 1992 12 31 SQL_C_CHAR 23 1992 12 31 N A 23 45 55 12 23 45 55 12 0 1992 12 31 SQL_C_CHAR 22 1992 12 31 01004 23 45 55 12 23 45 55 1 0 1992 12 31 SQL_C_CHAR 18 22003 23 45 55 12 a 0 represents a null t
310. er 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 as when the driver retrieves data from different DBMSs an empty string denotes those proce dures that do not have owners 1 of 2 INFORMIX CLI Function Reference 13 255 SQL Procedures Return Codes Diagnostics SQLSTATE Error Description Type Argument Use Description SWORD cbProcOwner Input Length of szProcOwner UCHAR FAR szProcName Input String search pattern for procedure names SWORD cbProcName Input Length of szProcName 2 of 2 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE When SQLProcedures returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value may be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLProcedures and explains each one 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 SQLSTATE value is SQL_ERROR unless noted otherwise 13 256 INFORMIX CLI Programmer s Manual handle 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver link failure and the
311. er Input 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 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 owners SWORD cbTableOwner Input Length of szTableOwner UCHAR FAR szTableName Input String search pattern for table names SWORD cbTableName Input Length of szTableName 13 312 INFORMIX CLI Programmer s Manual Return Codes SQLTablePrivileges SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLTablePrivileges returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value may be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLTablePrivileges and explains each one 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message
312. er additional details or QO shortcuts for the functionality that is being described Introduction 9 Icon Conventions 10 Icon GLS Compliance Icons Compliance icons indicate paragraphs that provide guidelines for complying with a standard Description Identifies information that is specific to a database or appli cation that uses the Informix Global Language Support GLS feature for support of a nondefault locale Core Identifies that a function supports the Core ODBC API conformance level Level 1 Identifies that a function supports the Level 1 ODBC API conformance level Level 2 Icon Platform Icons Identifies that a function supports the Level 2 ODBC API conformance level Platform icons identify paragraphs that describe product specific or platform specific information The following table describes the product and platform icons that are used in this manual Description Identifies information that is specific to 32 bit support for the UNIX environment Windows 3 1 Identifies information that is specific to 16 bit support for the Windows 3 1x environment Windows NT Identifies information that is specific to the Windows NT environment INFORMIX CLI Programmer s Manual Identifies information that is specific to the Windows 95 environment Example Code Conventions These icons can apply to a row ina table one or more paragraphs or an entire section A
313. er s Manual SQL ColumnPrivileges The SQLColumnPrivileges function accepts the following arguments Type Argument HSTMT hstmt UCHAR FAR szTableQualifier SWORD cbTableQualifier UCHAR FAR szTableOwner SWORD cbTableOwner UCHAR FAR szTableName SWORD cbTableName UCHAR FAR szColumnName SWORD cbColumnName Return Codes Use Input Input Input Input Input Input Input Input Input Description Statement handle 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 szTableQualifier 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 Length of szTableOwner Table name Length of szTableName String search pattern for column names Length of szColumnName SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 61 SQL ColumnPrivileges 13 62 Diagnostics SQLSTATE Error 01000 General warning 08S01 Communication link failure 24000 Invalid cursor state S1000 General error S1001 Memory allocation failure S1008 Operation canceled S1010 Function sequence error I
314. er uses the ODBC cursor library only if it is needed If the driver supports the SQL_FETCH_PRIOR option in SQLExtendedFetch the driver manager uses the scrolling capabil ities of the driver Otherwise it uses the ODBC cursor library SQL_CUR_USE_ODBC The driver manager uses the ODBC cursor library SQL_CUR_USE_DRIVER The driver manager uses the scrolling capabilities of the driver 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 Programmer s Reference and SDK Guide Version 2 0 SQL_OPT_TRACE A 32 bit integer value telling the driver manager whether to perform tracing SQL_OPT_TRACE_OFF Tracing off the default SQL_OPT_TRACE_ON Tracing on When tracing is on the driver manager writes each INFORMIX CLI function call to the trace file When tracing is on the driver manager 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 the driver manager appends to the file Otherwise it creates the file If tracing is on but no trace file has been specified the driver manager writes to the file sql log in the current directory If the Trace keyword in the ODBC section of the odbc ini file is set to 1 when an application calls SOLAIlocEnv tracing is enabled SQL_OPT_TRACEFILE A null terminated character string co
315. erators except LIKE SQL_SEARCHABLE if the data type can be used in a WHERE clause with any comparison operator Whether the data type is unsigned TRUE if the data type is unsigned FALSE if the data type is signed 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 TRUE if it is a money data type FALSE if it is not Whether the data type is autoincrementing TRUE if the data type is autoincrementing FALSE if the data type is not autoincrementing 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 3 of 4 SQL Get Typelnfo Column Name Data Type Comments LOCAL_TYPE_NAME VARCHAR 128 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 MINIMUM_SCALE SMALLINT 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 appli cable For more information see Precision Scale Leng
316. ermination byte The driver always null terminates SQL_C_CHAR data b The numbers in this list are the numbers stored in the fields of the TIMESTAMP_STRUCT structure 2 of 2 Converting Data from C to SQL Data Types When an application calls SQLExecute or SQLExecDirect the driver retrieves the data for any parameters that are bound with SQLBindParameter 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 SQLBindParameter to the data type specified by the fSq Type argument in SQLBindParameter Finally the driver sends the data to the data source The word convert is used in this section in a broad sense and it includes the transfer of data without a conversion in data type from one storage location to another C 24 INFORMIX CLI Programmer s Manual Converting Data from C to SQL Data Types The following table shows the supported conversions from ODBC C data types to ODBC SQL data types A solid circle indicates the default conversion for an SQL data type the C data type from which the data is converted when the value of fCType is SQL_C_DEFAULT A hollow circle 0 indicates a supported conversion SQL Data Type SQL_SMALLINT unsigned SQL_INTEGER signed SQL_INTEGER unsigned SQL_LONGVARCHAR SQL_SMALLINT signed SQL_REAL SQL
317. erred 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 about length see Precision Scale Length and Display Size on page C 8 The scale of the column on the data source For more scale information see Precision Scale Length and Display Size on page C 8 NULL is returned for data types where scale is not applicable 2 of 3 INFORMIX CLI Function Reference 13 71 SQLColumns Column Name Data Type RADIX SMALLINT NULLABLE SMALLINT not NULL REMARKS VARCHAR 254 Comments For numeric data types either 10 or 2 If itis 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 SQL_NO_NULLS if the column does not accept NULL values SQL_NULLABLE if the column accepts NULL values SQL_NULLABLE_UNKNOWN if it is not
318. 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 2 of 4 INFORMIX CLI Function Reference 13 129 SQLExtendeaFetch 13 130 SQLSTATE 1002 S1008 S1010 S1106 Error Invalid column number Operation canceled Function sequence error Fetch type out of range INFORMIX CLI Programmer s Manual Description 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 SQLBindCol and the SQL_USE_BOOKMARKS statement option was Set to SQL_UB_OFF The function was called but before it completed execution SOLCancel was called on the hstmt from a different thread in a multi threaded application DM The specified hstmt was not in an executed state The function was called without first calling SQLExecDirect SQLEx ecute 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 SQLFetch was called and before SQLFreeStmt was called with the SQL_CLOSE option DM The value specified for the argument fFetchType was invalid The value of the SQL_CURSOR_TYPE statement opti
319. ers an application can call SQLCancel to cancel the statement execution After the statement is canceled the application can call SQLExecute or SQLExecDirect again For more information see Passing Parameter Values on page 13 34 Canceling Functions in Multithreaded Applications Ina multithreaded application the application can cancel a function that is running synchronously on an hstmt To cancel the function the application calls SQLCancel with the same hstmt as that used by the target function 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 SQLExecute Freeing a statement handle SOLFreeStmt Returning the next parameter for which SQLParamData to send data Sending parameter data at execution SOLPutData time INFORMIX CLI Function Reference 13 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 information is returned as a character string a 32 bit descriptor dependent value or an integer value Syntax RE
320. es the description of each SQLSTATE returned by the driver manager The return code associated with each Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INEFO 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 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 The data source rejected the establishment of the connection for implementation defined reasons Diagnostics SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error 01000 General warning 01004 Data truncated 01S00 Invalid connection string attribute 08001 Unable to connect to data source 08002 Connection in use 08004 Data source rejected establishment of connection 1 of 3 SQLSTATE 08S01 28000 IM002 IMO003 IM004 IMO005 IM006 IMO009 IM010 Error Comm
321. es the size of each buffer in the data storage array m The pebValue argument specifies the address of the number of bytes array INFORMIX CLI Programmer s Manual SQLExtendedFetch 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 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 For each bound column the driver stores the number of bytes that are available to return in the pcb Value buffer that is bound to the column This is the number of bytes available before calling SQLEx tendedFetch If the number of bytes available to return cannot be determined in advance the driver sets pcbValue to SQL_NO_TOTAL If the data for the column is NULL the driver sets pcbValue to SQL_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
322. ession AND expression binary literal implementation defined Extended binary type binary types Extended For example LONG VARBINARY boolean factor NOT boolean primary Minimum boolean primary predicate search condition Minimum boolean term boolean factor AND boolean term Minimum character any character in the implementor s character set Minimum character string literal character Minimum To include a single literal quote character in a character string literal use two literal quote characters character string type character types Minimum For example CHAR VARCHAR or LONG VARCHAR column alias user defined name Core column identifier user defined name Minimum column name table name column identifier Minimum column name table name correlation name column identifier Core comparison operator lt gt lt gt lt gt Minimum comparison predicate expression comparison operator expression Minimum 2 of 11 Hements Used in SQL Statements SQL Conformance Element Level comparison predicate Core expression comparison operator expression sub query correlation name user defined name Core cursor name user defined name Core data type character string type Minimum data type Core character string type exact numeric type approximate numeric type data type Extended character string t
323. etData SQLBrowseConnect SQLConnect SOLDriverConnect SQLBrowseConnect SQLConnect SOLDriverConnect SQLSetConnectOption SQLAllocStmt SQLDisconnect SQLGetConnectOption SQLGetInfo SQLNativeSql SQLSetConnectOption SQLTransact SQLBrowseConnect SQLConnect SOQLDriverConnect SQLTransact 2 of 13 INFORMIX CLI Error Codes A 3 A 4 SQLSTATEs 08S01 21501 21502 22001 22002 INFORMIX CLI Programmer s 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 SQLColumns SQLConnect SQLDriverConnect SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLFreeConnect SQLGetData SQLGetTypelInfo SQLParamData SQLPrepare SQLPrimaryKeys SQLProcedures SQLPutData SQLSetConnectOption SQLSetStmtOption SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLPutData SQLExtendedFetch SQLFetch SQLGetData 3 of 13 SQLSTATEs 22003 22005 22008 22012 22026 23000 Error Numeric value out of range Error in assignment DATETIME field overflow Division by zero String data length mismatch Integrity constraint violation Can be returned from SQLExecDirect SQLExecute SQLExtendedFetch SQLFe
324. etion of the function The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded 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 SQLMoreResults 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 SQLMoreResults returns SQL_SUCCESS and initializes the result set or count for additional processing After calling SQLMoreResults for SELECT statements an application 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 there is a current result set with unfetched rows SQLMoreResults discards that result set and makes the next result set or count available If a batch
325. eturn 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 szNameLNAME_LEN szRemark REM_LEN SWORD sAge sEmplId SDWORD cbEmpId cbName cbAge 0 cbBirthday 0 cbRemark DATE_STRUCT dsBirthday Define parameter for return value Employee ID from procedure SQLBindParameter hstmt 1 SQL_PARAM_OUTPUT SQL_C_SLONG SQL_INTEGER 0 0 amp sEmpId 0 amp cbEmpld 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 13 261 SQ
326. eturned 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 quali fiers or the qualifier name cannot be determined an empty string is returned The scale of the column on the data source For more information on scale see Precision Scale Length and Display Size on page C 8 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 SQL_ALL_EXCEPT_LIKE if the column can be used in a WHERE clause with all comparison operators except LIKE SQL_SEARCHABLE if the column can be used in a WHERE clause with any comparison operator Columns of type SQL_LLONGVARCHAR and SQL_LONGVARBINARY usually return SQL_LIKE_ONLY 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 3 of 4 fDescType SQL_COLUMN_TYPE SQL_COLUMN_TYPE_NAME SQL_COLUMN_UNSIGNED SQL_COLUMN_UPDATABLE Information Returned in pfDesc rgbDesc pfDesc pfDesc SQLColAttributes Description SQL data type For a list of valid ODBC SQL data types see Appendix C For information on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 Data sourc
327. etwork requests to the server Consider however an algorithm that uses parameter arrays by calling SOLParamOptions rc SQLPrepare hstmt INSERT INTO DailyLedger VALUES CE kins se a SOL NTS rc SQLParamOptions hstmt UDWORD 50 amp CurrentRow pass 50 parameters per execute bind parameters do read up to 50 ledger values into bound parameter buffers rc SQLExecute hstmt insert row The call load has been reduced from 100 executions to just two SQLExecute calls furthermore network traffic is reduced considerably To achieve high performance applications should contain algorithms for using SQLParamOptions SQLParamOptions is ideal for copying data into new tables or loading tables in bulk Updating Data Use positioned updates and deletes and SQLSpecialColumns to increase the performance of your application Use Positioned Updates and Deletes Designing an efficient method for updating data is challenging Although positioned updates do not apply to all types of applications attempt to use positioned updates and deletes whenever possible Positioned updates via UPDATE WHERE CURRENT OF cursor allow you to update data simply by positioning the database cursor to the appropriate row to be changed and signal the driver to change the data here You are not forced to build a complex SQL statement but simply required to supply the data that is to be changed Designing Performance Orie
328. example the cursor name exceeded the maximum length as defined by the driver 3C000 Duplicate cursor name The cursor name specified by the argument szCursor already exists 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 failure 13 282 INFORMIX CLI Programmer s Manual The driver did not allocate memory required to support execution or completion of the function 1 of 2 SQL SetCursorName SQLSTATE Error Description S1009 Invalid argument DM The argument szCursor was a null value pointer S1010 Function DM SQLExecute or SQLExecDirect was called sequence 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 argument cbCursor was less than 0 buffer length but not equal to SQL_NTS 2 of 2 Usage 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 SQLSetCursorName 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
329. f the call to SQLError 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 application 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 rightmost 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 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 SQLError 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 SQLError in the driver The driver manager 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 associate
330. f the columns and terms in the table see Converting Data from C to SQL Data Types on page C 24 SQLSTATE N A 01004 22003 N A 01004 22003 N A 22003 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 rgbValue is the size of the numeric C data type C to SQL Bit C to SQL Bit The bit ODBC C data type is SQL_C_BIT The following table shows the ODBC SQL data types to which bit C data can be converted For an explanation of the columns and terms in the table see Converting Data from C to SQL Data Types on page C 24 fSqlType Test SQLSTATE SQL_CHAR None N A SQL_VARCHAR SQL_LONGVARCHAR SQL_DECIMAL None N A SQL_SMALLINT SQL_INTEGER SQL_REAL SQL_DOUBLE 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 bit C data type The driver assumes that the size of rgbValue is the size of the bit C data type C to SQL Binary The binary ODBC C data type is SQL_C_BINARY The following table shows the ODBC SQL data types to which binary C data can be converted For an explanation of the columns and terms in the table see Converting Data from C to SQL Data Types on page C 24 Data Types C 31 C to SQL Date C 3
331. fier separator owner name procedure identifier The third syntax is valid only if the data source does not support owners procedure parameter list procedure parameter procedure parameter procedure parameter list procedure parameter dynamic parameter literal empty string If a procedure parameter is an empty string the procedure uses the default value for that parameter qualifier name user defined name qualifier separator implementation defined The qualifier separator is returned through SQLGetInfo with the SQL_QUALIFIER_NAME SEPARATOR option quantified predicate expression comparison operator ALL ANY sub query query specification SELECT ALL DISTINCT select list FROM table reference list WHERE search condition GROUP BY column name column name HAVING search condition ref table name base table identifier ref table name base table identifier owner name base table identifier qualifier name qualifier separator base table identifier qualifier name qualifier separator owner name base table identifier The third syntax is valid only if the data source does not support owners referenced columns column identifier column identifier referencing columns column identifier column identifier INFORMIX CLI Programmer s Manual Extended Extended Extended Core Core Core Core Minimum Core Core C
332. fractional seconds portion of the time stamp is truncated 8 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 3 of 3 When character SQL data is converted to numeric date time or time stamp C data leading and trailing spaces are ignored All drivers that support date time and time stamp data can convert character SQL data to date time or time stamp C data as specified in the previous table Drivers might be able to convert character SQL data from other driver specific formats to date time or time stamp C data Such conversions are not interoperable among data sources SQL to C Numeric The numeric ODBC SQL data types are found in the following list SQL_DECIMAL SQL_REAL SQL_SMALLINT SQL_DOUBLE SQL_INTEGER The following table shows the ODBC C data types to which numeric SQL data can be converted For an explanation of the columns and terms in the table see Converting Data from SQL to C Data Types on page C 13 C 18 INFORMIX CLI Programmer s Manual fCType SQL_C_CHAR SQL_C_STINYINT SQL_C_UTINYINT SQL_C_TINYINT SQL_C_SSHORT SQL_C_USHORT SQL_C_SHORT SQL_C_SLONG SQL_C_ULONG SQL_C_LONG SQL_C_FLOAT SQL_C_DOUBLE SQL_C_BIT Test Display size lt cbValueMax Number of whole as opposed to fractional digits lt cbVal ueMax Number of whole as opposed to fractional digits cbValueMax D
333. function the notation DM precedes the description of each SQLSTATE returned by the driver manager The return code associated with each SQLSTATE value is SQL_ERROR unless noted otherwise The driver can return SQL_SUCCESS_WITH_INFO to provide information about the result of setting an option For example setting SQL_ACCESS_MODE to read only during a transaction might cause the trans action to be committed The driver could use SQL_SUCCESS_WITH_INFO and information returned with SQLError to inform the application of the commit action SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 01S02 Option value The driver did not support the specified value changed of the vParam argument and substituted a similar value function returns SQL_SUCCESS_WITH_INFO 08002 Connection in use The argument fOption was SQL_ODBC_CURSORS and the driver was already connected to the data source 08003 Connection not An fOption value was specified that required open an open connection but the hdbc was not in a connected state 08S01 Communication The communication link between the driver link failure and the data source failed before the function completed IM009 Unable to load The driver was unable to load the translation translation shared library shared library that was specified for the connection This error can only be returned when fOp
334. function is implemented solely by the driver manager SQLDrivers is an ODBC 2 0 function Syntax RETCODE SQLDrivers henv fDirection szDriverDesc cbDriverDescMax pcbDriverDesc szDriverAttributes cbDrvrAttrMax pcbDrvrAttr The SQLDrivers function accepts the following arguments Type Argument Use Description HENV henv Input Environment handle UWORD fDirection Input Determines whether the driver manager fetches the next driver description in the list SQL_FETCH_NEXT or whether the search starts from the beginning of the list 6QL_FETCH_FIRST UCHAR FAR szDriverDesc Output Pointer to storage for the driver description SWORD cbDriverDescMax Input Maximum length of the szDriverDesc buffer SWORD FAR pebDriverDesc Output Total number of bytes excluding the null 13 104 INFORMIX CLI Programmer s Manual termnation byte available to return in szDriverDesc If the number of bytes available to return is greater than or equal to cbDriver DescMax the driver description in szDriverDesc is truncated to cbDriverDescMax 1 bytes 1 of 2 Type UCHAR FAR SWORD SWORD FAR Argument Use szDriverAttributes Output cbDrovrAttrMax Input pebDrorAttr Output Return Codes SQLDrivers Description Pointer to storage for the list of driver attribute value pairs see Usage on page 13 107 Maximum length of the szDriverAttributes buffer Total number of bytes excluding the nu
335. fying Data Sources Adding a Data Source Required Data Source Configuration Information Optional Data Source Configuration Information Modifying a Data Source Connecting to a Data Source Using Dialog Boxes to Connect to a Data Source Using a Connection String to Connect to a Data Source 2 3 2 3 2 4 2 4 2 6 2 6 2 10 2 11 2 11 2 11 2 13 2 15 2 15 2 15 2 16 2 16 2 16 2 17 2 17 2 24 2 26 2 26 2 28 2 2 INFORMIX CLI Programmer s Manual his chapter explains how to set up INFORMIX CLI and how to configure and connect to data sources for UNIX and Windows platforms INFORMIX CLI for UNIX INFORMIX CLI for UNIX conforms to the Microsoft ODBC Specification Version 2 5 INFORMIX CLI supports multiple connections to an Informix database The INFORMIX CLI library is named qeinf708 Some libraries might have a platform specific extension for example the library for Solaris is called qeinf708 so The following sections describe how to set up and configure INFORMIX CLI so that you can connect your UNIX client application to a data source Setting Up INFORMIX CLI Perform the following setup activities before you use INFORMIX CLI Confirm that your system has the appropriate software installed Set the INFORMIXDIR and PATH environment variables to reflect the appropriate directory paths m Set the INFORMIXSERVER environment variable to the default database server name INFORMIX CLI 2 3
336. g ODBC Extensions to SQL INFORMIX CLI supports ODBC extensions to SQL as well as Informix specific extensions The following section describes the general format of the exten sions as defined by the ODBC specification ODBC defines the following extensions to SQL which are common to most DBMSs m Date time and time stamp data m Scalar functions such as numeric and string functions m Outer joins The syntax defined by ODBC for these extensions uses the escape clause provided by the X Open and SQL Access Group SQL CAE specification 1992 to cover vendor specific extensions to SQL Its format is as follows vendor vendor name product product name extension For the ODBC extensions to SQL product name is always ODBC because the product that defines them is ODBC Vendor name is always Microsoft because ODBC is a Microsoft product ODBC also defines a shorthand syntax for these extensions as follows extension Most DBMSs provide the same extensions to SQL as ODBC does For this reason an application might be able to submit an SQL statement using one of these extensions in either of the following ways m Use the syntax defined by ODBC An application that uses the ODBC syntax is interoperable among DBMSs m Use the syntax defined by the DBMS An application that uses DBMS specific syntax is not interoperable among DBMSs To determine whether the driver and data source support all the ODBC exten sions to SQL
337. g SQLExecDirect SQLEx ecute 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 SQLFetch was called and before SQLFreeStmt was called with the SQL_CLOSE option The driver or data source does not support the conversion specified by the combination of the fCType in SQLBindCol 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 time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 3 of 3 INFORMIX CLI Function Reference 13 147 SQLFetch 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 SQL_NO_DATA_FOUND and the cursor is positioned after the end of the result set An application cannot mix calls to SQLExtended Fetch and SQLFetch for the same cursor If the application called SQLBindCol to bind columns SQLFetch stores data into the locations specified by the calls to SQLBindCol If the application does not call SOLBind
338. ge that corresponds to each numerical value SQLSTATE and the functions that can return each SQLSTATE value Appendix B describes the recommended syntax for maximum interoperability in calls to SQLPrepare SQLExecute and SQLExecDirect Appendix C provides information on ODBC SQL data types that INFORMIX CLI supports and ODBC C data types This appendix also describes conversion from one data type to the other Appendix D compares INFORMIX CLI functions core ODBC with embedded SQL statements Types of Users This manual is for C programmers who want to use INFORMIX CLI to create custom applications for accessing Informix relational databases The manual assumes that you know C programming and are familiar with your computer operating system and the structure of relational databases Knowledge of SQL is also useful Three other manuals describe the Informix implemen tation of SQL in detail the Informix Guide to SQL Tutorial the Informix Guide to SQL Reference and the Informix Guide to SQL Syntax Introduction 5 Software Deoendencies 6 Software Dependencies Depending on your Informix database configuration you must have a compatible Informix database server installed on your system or network The following list shows examples of compatible database servers m INFORMIX OnLine Version 5 x m INFORMIX OnLine Dynamic Server Version 7 x m INFORMIX SE Version 5x 7 x For information on these products refer t
339. gths depend on the data source To determine the actual lengths of the PROCEDURE_QUALIFIER PROCEDURE_OWNER and PROCEDURE_NAME columns an application can call SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME LEN and SQL_MAX_PROCEDURE_NAME_LEN options Column Name PROCEDURE_QUALIFIER Data Type VARCHAR 128 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 proce dures 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 as when the driver retrieves data from different DBMSs it returns an empty string for those proce dures that do not have owners PROCEDURE_NAME VARCHAR 128 not NULL Procedure identifier NUM_INPUT_PARAMS N A Reserved for future use Applica tions should not rely on the data returned in these result columns NUM_OUTPUT_PARAMS N A Reserved for future use Applica tions should not rely on the data returned in these result columns NUM_RESULT_SETS N A Reserved for future use Applica tions should not rely on the data returned in these result columns 1 of 2 INFORMIX CLI Function Refe
340. gument of SQLBindParameter and the value of the cbValue argument of SQLPutData are ignored when data is converted from the time C data type The driver assumes that the size of rgbValue is the size of the time C data type C to SQL Time Stamp The time stamp ODBC C data type is SQL_C_TIMESTAMP INFORMIX CLI Programmer s Manual C to SQL Time Stamp The following table shows the ODBC SQL data types to which time stamp C data can be converted For an explanation of the columns and terms in the table see Converting Data from C to SQL Data Types on page C 24 fSqlType Test SQLSTATE SQL_CHAR Column length gt Display size N A SQL_VARCHAR SQL_LONGVARCHAR 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 gt 01004 Data value does not contain a valid date 22008 SQL_TIMESTAMP Fractional seconds fields are not N A truncated 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 gt 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 Extended C Data Types on page C 5 Whe
341. gument szErrorMsg describes the error and its cause 1 of 2 INFORMIX CLI Function Reference 13 229 SQL NativeSq 13 230 SQLSTATE 1001 S1009 S1090 Usage None SELECT SELECT length NAME Error Memory allocation failure Invalid argument value Invalid string or buffer length fn LENGTHCNAME Related Functions INFORMIX CLI Programmer s Manual Description The driver did not allocate memory required to support execution or completion of the function DM The argument szSq StrIn was a null pointer DM The argument cbSqlStrIn was less than 0 but not equal to SQL_NTS DM The argument cbSq StrMax was less than 0 and the argument szSq Str was not a null pointer 2 of 2 The following example shows what SQLNativeSqI might return for an input SQL string that contains the scalar function LENGTH FROM EMPLOYEE An INFORMIX CLI driver might return the following translated SQL string FROM EMPLOYEE SQLNumParams SQLNumParams SQLNumParams returns the number of parameters in an SQL statement Syntax RETCODE SQLNumParams hstmt pcpar The SQLNumParams function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle SWORD FAR pepar Output Number of parameters in the statement Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLNumPa
342. h a flag for that extension To determine whether a driver supports a specific SQL data type an application calls SOLGetTypelnfo Guidelines for Calling INFORMIX CLI Functions 3 3 Using the Driver Manager 3 4 Using the Driver Manager The driver manager is a shared library that provides access to the Informix driver An INFORMIX CLI application typically links with the driver manager import library to gain access to the driver manager For UNIX this file is named libodbc with platform specific extensions For Windows 3 1 this file is named ODBC DLL and for Windows 95 and Windows NT this file is named ODBC32 DLL Whenever an INFORMIX CLI application calls a function the driver manager performs one of the following actions m For SQLDataSources and SQLDrivers the driver manager processes the call It does not pass the call to the driver m For SQLGetFunctions the driver manager passes the call to the driver associated with the connection m For SQLAIlocEnv SOLAIlocConnect SOLSetConnectOption SQLFreeConnect and SQLFreeEnv the driver manager processes the call The driver manager calls SQLAIlocEnv SQLAIlocConnect and SQLSetConnectOption in the driver when the application calls a function to connect to the data source SQLConnect SQLDriverConnect or SOLBrowseConnect The driver manager calls SQLFreeConnect and SQLFreeEnv in the driver when the appli cation calls SQLDisconnect m For SQLConnect SQLDriverConnect
343. h must be a nonnegative value and is ignored For more information see Passing Parameter Values on page 13 34 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 INFORMIX CLI Function Reference 13 33 SQL BindParameter If pebValue is a null pointer the driver assumes that all input parameter values are non null and that character and binary data are null terminated If fParamType is SQL_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 data type of the parameter 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 SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT pcbValue points to a buffer in which the driver returns SQL_NULL_DATA the number of bytes available to return in rgb Value excluding the null termination byte of character data or SQL_NO_TOTAL if the number of bytes available to return cannot be determined If the procedure returns one or more result sets the pebVal
344. h on input and on output For input output and output param eters 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 or the length of an element in the rgbValue array if the application calls SQLParamOptions to specify multiple values for each parameter is assumed to be the length of the C data type When an ODBC 1 0 application calls SQLSetParam in an ODBC 2 x driver the driver manager converts this to a call to SQLBindParameter in which the cbValueMax argument is always SQL_SETPARAM_VALUE_MAx Because the driver manager returns an error when an ODBC 2 x application sets cbValueMax to SQL_SETPARAM_VALUE_MAX an ODBC 2 x driver can use this to determine when it is called by an ODBC 1 0 application In SQLSetParam the driver defines how an application specifies the length of the rgbValue buffer so that the driver can return character or binary data and how an application sends an array of character or binary parameter values to the driver IN
345. haracter binary or data source specific data type If SQLPutData is called more than once under any other conditions it returns SQL_ERROR and SQLSTATE 22003 Numeric value out SQL PutData Code Example In the following example an application prepares an SQL statement to insert data into the EMPLOYEE table The statement contains parameters 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 SQLExecute to execute the statement SQLExecute returns SQL_NEED_DATA when it needs data for the first and third param eters The application calls SQLParamData 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 SOLPutData to get and send the parameter data Finally it calls SQLParamData to indicate that it has sent all the data for the parameter and to retrieve the value for the next parameter After data has been sent for both parameters SQLParamData re
346. he SQLSTATE values commonly returned by SOQLNumResultCols 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 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 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 The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded 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 SOLSetStmtOption SQL_QUERY_TIMEOUT SQLNumResultCols SQLNumResultCols can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when SQLNumResultCols is called after SQLPrepare an
347. he database server qualifier LogonID Your user name as specified on the INFORMIX OnLine Dynamic Server or the INFORMIX SE database server Password A password HostName The name of the computer on which the INFORMIX OnLine Dynamic Server or the INFORMIX SE database server resides Service The name assigned to the Informix database server process running on your UNIX computer Commonly the service is sqlexec Confirm the service name with your system administrator ServerName The name of the database server on which the database that you want to access resides INFORMIX CLI 2 7 Adding a Data Source Options That Define Cursor Behavior The following table lists the types of cursor behavior you can set as default connection options for a data source The following table lists the initial default that applies if you do not specify a value in the Data Source Specifi cation section of your odbc ini file Keyword Attribute CursorBehavior A value that determines the type of behavior of the cursors after the transaction ends m 0 Closed This is the default setting m 1 Preserve Choose this setting to hold the cursors at the current position when the transaction ends This setting might affect the performance of your database operations EnableScrollable A value that determines if the driver provides scrollable cursors Cursors m 0 No scrollable cursors This is the default setting m 1 Enable scrollable cursors
348. he first and third operands of a BETWEEN operation As both the expression and the first value of an IN operation As the operand of a unary or operation As the argument of a set function reference For more information see the ANSI SQL 92 specification If an application includes parameter markers in the SQL statement the appli cation must call SOLBindParameter to associate storage locations with parameter markers before it calls SQLExecute or SQLExecDirect If the appli cation calls SQLPrepare the application can call SOLBindParameter before or after it calls SOLPrepare The application can set parameter markers in any order The driver buffers argument descriptors and sends the current values referenced by the SQLBindParameter argument rgbValue for the associated parameter marker when the application calls SOLExecute or SOLExecDirect It is the responsi bility of the application to ensure that all pointer arguments are valid at execution time The keyword USER in the following tables represents a character string containing the user name of the current user SQL Grammar B 3 SQL Statements SQLStatements The following SQL statements define the base ODBC SQL grammar ALTER TABLE Statement Important As a data type in an ALTER TABLE statement applications must use a data type from the TYPE_LNAME column of the result set that SQLGetTypeInfo returns SQL conformance level Core ALTER TABLE base table name ADD
349. he following table shows the ODBC C data types to which binary SQL data can be converted For an explanation of the columns and terms in the table see Converting Data from SQL to C Data Types on page C 13 fCType Test rgbValue pebValue SQLSTATE SQL_C_CHAR Length of data 2 lt cbValueMax Data Length of data N A Length of data 2 gt cbValueMax Truncated data Length of data 01004 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 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 and a binary 11111111 is converted to FF C 20 INFORMIX CLI Programmer s Manual fCType SQL_C_CHAR SQL_C_BINARY SQL_C_DATE SQL_C_TIMESTAMP SQL to C Date 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 SQL to C Date The date ODBC SQL data type is SQL_DATE
350. he following table shows the supported conversions from ODBC SQL data types to ODBC C data types A solid circle e indicates the default conversion for an SQL data type the C data type to which the data is converted when the value of fCType is SQL_C_DEFAULT A hollow circle 0 indicates a supported conversion Data Types C 13 Converting Data from SQL to C Data Types C 14 C Data Type 2 BZ h H al lt S28 ee elouk enw k z3 BER ZERroe6 Sok eee Y a a gt a n 2 wy E gt A A a A i H Yi 9 9 9 9 9 9 Y Y 9 9 9 Y 9 9 9 9 er er re ee a re a a re re ee E E SQL Data Type g SSSSKSSSKFSKSSKEFZB SQL_CHAR J DRD ED D S S S E S S S S S O S E S S SQL_VARCHAR ee OO OO OD O Oo OO OO OF SQL_LONGVARCHAR e O OMOLO O O OTO O OnO O OLOO O SQL_DECIMAL e Q7 Os ODO CO OOTO O7 Os OO LO SQL_SMALLINT signed O 0O0O0O0800000000 SQL_SMALLINT O O O O O O OO0O0 o0 o0o0o o SQL_INTEGER signed OO O O O O O OO O00 0o0o SQL_INTEGER unsigned O 0OO0O0000008000 0 SQL_REAL O O O O O O O O O O O ECO OF SQL_DOUBLE O O O O O O O O O O O O O SQL_LONGVARBINARY O e O O SQL_DATE O O O SQL_TIMESTAMP O O O O 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 ODBC C data types from the ODBC SQL data types that they support For a given ODBC SQL data type the first col
351. he 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 SQL_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 SQL statement If an application uses SQLPrepare to prepare and SQLExecute to submit a COMMIT or ROLLBACK statement it is not interoperable between DBMS products To commit or roll back a transaction call SQLTransact If SQLExecute encounters a data at execution parameter it returns SQL_NEED_DATA The application sends the data using SQLParamData and SQLPutData For more information see SOLBindParameter SOQLParamData SQLParamOptions and SQLPutData Code Example See SOLBindParameter SQLParamOptions and SQLPutData INFORMIX CLI Function Reference 13 125 SQL Execute Related Functions For information about See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SQLCancel Executing an SQL statement SQLExecDirect Fetching a block of data or scrolling through a result set SQLExtendedFetch Fetching a row of data SQLFetch Freeing a statement handle SQLFreeStmt Returning a cursor name SQLGetCursorName Fetching part or all of a column of data
352. he rowset starting at row 15 even if the rgfRowStatus array for row 15 is SQL_ROW_DELETED Processing Errors If an error occurs that pertains to the entire rowset such as SQLSTATE S1T00 Time out expired the driver returns SQL_ERROR and the appropriate SQOLSTATE The contents of the rowset 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 SQL_ROW_ERROR m Posts SQLSTATE 01801 Error in row in the error queue m Posts zero or more additional SOLSTATE values for the error after SQLSTATE 01501 Error in row in the error queue After it processes the error or warning the driver continues the operation for the remaining rows in the rowset and returns SQL_SUCCESS_WITH_INFO Thus for each error that pertains to a single row the error queue contains SQLSTATE 01501 Error in row followed by zero or more additional SQLSTATEs After the driver processes the error it fetches the remaining rows in the rowset and returns SQL_SUCCESS_WITH_INFO Thus for each row that returns an error the error queue contains SOLSTATE 01801 Error in row followed by zero or more additional SQLSTATE values INFORMIX CLI Programmer s Manual SQLExtendedFetch If the rowset contains rows that have already been fetched the driver is not required to return SQLSTATE values for errors that occ
353. he value specified for the argument fDriverCompletion was not equal to SQL_DRIVER_PROMPT SQL_DRIVER_COMPLETE SQL_DRIVER_COMPLETE_REQUIRED or SQL_DRIVER_NOPROMPT The time out period expired before the connection to the data source completed The time out period is set through SQLSetConnec tOption SQL_LOGIN_TIMEOUT 4 0f4 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 SQL DriverConnect Connection Strings A connection string has the following syntax connection string empty string 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 driver defined attribute keyword attribute value character string driver defined attribute keyword identifier 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
354. hird syntax is valid only if the data source does not support owners years value digit digit digit digit Extended 11 of 11 List of Reserved Keywords The following words are reserved for use in ODBC function calls These words do not constrain the minimum SQL grammar however to ensure compatibility with drivers that support the core SQL grammar applications should avoid using any of these keywords The define value SQL_ODBC_KEYWORDS contains a comma separated list of these keywords ABSOLUTE ADA ADD ALL ALLOCATE ALTER AND ANY ARE AS ASC ASSERTION SQL Grammar B 21 List of Reserved Keywords B 22 AT AUTHORIZATION AVG BEGIN BETWEEN BIT BIT_LENGTH BY CASCADE CASCADED CASE CAST CATALOG CHAR CHAR_LENGTH CHARACTER CHARACTER_LENGTH CHECK CLOSE COALESCE COBOL COLLATE COLLATION COLUMN COMMIT CONNECT CONNECTION CONSTRAINT CONSTRAINTS CONTINUE CONVERT CORRESPONDING COUNT INFORMIX CLI Programmer s Manual CREATE CURRENT CURRENT_DATE CURRENT_TIME CURRENT_TIMESTAMP CURSOR DATE DAY DEALLOCATE DEC DECIMAL DECLARE DEFERRABLE DEFERRED DELETE DESC DESCRIBE DESCRIPTOR DIAGNOSTICS DICTIONARY DISCONNECT DISPLACEMENT DISTINCT DOMAIN DOUBLE DROP ELSE END END EXEC ESCAPE EXCEPT EXCEPTION EXEC List of Reserved Keywords SQL Grammar B 23 List of Reserved Keywords B 24 EXECUTE EXISTS EXTERNAL EXTRACT FALSE FETCH FIRST FLOAT F
355. ication and other applications are detected by the cursor when data is fetched Although dynamic cursors are ideal for many situa tions they are difficult to implement Keyset Driven Cursors Keyset driven cursors possess some attributes of static and dynamic cursors Like static cursors the membership and ordering of the result set of a keyset 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 Programmer s Manual Using Block and Scrollable Cursors When a keyset driven cursor opens the driver saves the keys for the entire result set which fixes the membership and order of the result set As the cursor scrolls through the result set the driver uses the keys in this keyset to retrieve the current data values for each row in the rowset Because data values are retrieved only when the cursor scrolls to a given row updates to that row by other users including other cursors in the same application after the cursor was opened are visible to the cursor If the cursor scrolls to a row of data that has been deleted by other users including other cursors in the same application the row appears as a hole in the result set because the key is still in the keyset but the row is no longer in the result set Updating the key values in a row is considered to be deleting the existing row and inserti
356. id keywords localized identifiers and attribute values that contain the characters Because of the registry grammar keywords and data source names cannot contain a backslash The browse result connection string syntax is used according to the following semantic rules If an asterisk precedes an attribute keyword the attribute is optional and can be omitted in the next call to SOLBrowseConnect The attribute keywords UID and PWD have the same meaning as defined in SQLDriverConnect A driver defined attribute keyword names the kind of attribute for which an attribute value can be supplied For example it might be SERVER DATABASE HOST or DBMS ODBC attribute keywords and driver defined attribute keywords include a localized or user friendly version of the keyword This localized version might be used by applications as a label in a dialog box However UID PWD or the identifier alone must be used when the application passes a browse request connection string to the driver 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 If the attribute value is a single question mark a single value corresponds to the attribute keyword For example UID JohnS PWD Sesame Each call to SQLBrowseConnect re
357. ied hdbc INFORMIX CLI Programmer s Manual Description DM The value specified for argument cbDSN was less than 0 but not equal to SQL_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 SQL_NTS DM The value specified for argument cbAuthStr was less than 0 but not equal to SQL_NTS 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 The driver manager does not load a driver until the application calls a function SQLConnect SQLDriverConnect or SQLBrowseConnect to connect to the driver Until that point the driver manager works with its own handles and manages connection information When the application calls a connection function the driver manager checks if a driver is currently loaded m Ifadriver is not loaded the driver manager loads the driver and calls SQLAIlocEnv SQLAIlocConnect SOLSetConnectOption if the application specified any connection options and the connection function in the driver The driver manager returns SOLSTATE IM006 Driver SOLSetConnectOption function failed and SQL_SUCCESS_WITH_INEFO for the connection function if the driver returns an error for SQLSetConnectOption m Ifthe specified driver is already loaded on the hdbc the driver manager ca
358. ier 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 2 of 3 Type Argument Use UWORD fScope Input UWORD fNullable Input Return Codes SQL SpecialColumns Description Minimum required scope of the rowid The returned rowid might be of greater scope It must be one of the following SQL_SCOPE_CURROW The rowid is guaranteed to be valid only while positioned on that row A later reselect using rowid might not return a row if the row was updated or deleted by another transaction SQL_SCOPE_TRANSACTION The rowid is guaranteed to be valid for the duration of the current transaction SQL_SCOPE_SESSION The rowid 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 SQL_NO_NULLS Exclude special columns that can have NULL values SQL_NULLABLE Return special columns even if they can have NULL values 3 of 3 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 297 SQL SpecialColumns 13 298 Diagnostics SQLSTATE Error 01000 General warning 08S01 Communicat
359. ile files 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 automat ically when you log on to your system 2 4 INFORMIX CLI Programmer s Manual GLS Setting Environment Variables For example if your Informix directory path is usr informix and the name of your default database server is online_one in the C shell you could add the following lines to your cshre file to set the INFORMIXDIR INFORMIX SERVER and PATH environment variables setenv INFORMIXDIR usr informix setenv INFORMIXSERVER online_one setenv PATH PATH INFORMIXDIR bin In the Bourne or Korn shells you could add the following lines to your login or profile file INFORMIXDIR usr informix export INFORMIXDIR INFORMIXSERVER online_one export INFORMIXSERVER PATH PATH INFORMIXDIR bin export PATH When you installed INFORMIX CLI the following environment variables got set m IV_GLS_LCDIR m IV_GLS_REGISTRY m GL_PATH Look in your cli sh file Bourne shell or cli csh C Shell to see the settings For information about additional GLS environment variables that you can set see the Guide to GLS Functionality INFORMIX CLI 2 5 Adding and Modifying Data Sources 2 6 Adding and Modifying Data Sources A data source is a database or file that INFORMIX CLI accesses INFORMIX CLI uses the odbc ini file for initialization To connec
360. in a block of data more than one row that has been retrieved with SQLExtendedFetch To determine if a driver can return data with SQLGetData from a block of data an application calls SQLGetInfo with the SQL_GETDATA_EXTENSIONS option Using Block and Scrollable Cursors Cursors in SQL scroll forward through a result set returning one row at a 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 rowsets A block cursor attribute allows an application to retrieve and update rowset 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 SQL_ROWSET_SIZE option to specify the rowset size The application can call SQLSetStmtOption to change the rowset size at any time Each time the application calls SQLExtendedFetch the driver returns the next rowset size rows of data After the data is returned the cursor points to the first row in the rowset by default the rowset size is one Retrieving Results 7 9 Using Block and Scrollable Cursors 7 10 Scrollable Cursors Applications have different needs to sense changes in the tables underlying a result set For example when bal
361. inating a Connection Setup Shared Library Function Summary Translation Shared Library Function Summary vi INFORMIX CLI Programmer s Manual 8 3 8 4 8 5 8 6 8 8 9 4 9 4 10 4 10 7 11 4 11 11 11 11 11 16 12 3 12 4 12 4 12 5 12 5 12 6 12 7 12 8 12 9 12 9 12 10 12 10 Chapter 13 Chapter 14 Chapter 15 Appendix A Appendix B Appendix C Appendix D INFORMIX CLI Function Reference Arguments INFORMIX CLI Include Files Diagnostics Tables and Views Catalog Functions Search Pattern Arguments SOLColAttributes SQLColumnPrivileges Related Functions SQLDriverConnect SQLFreeConnect SQLMoreResults SQLParamOptions SQLProcedures SOLSpecialColumns SQLTablePrivileges Setup Shared Library Function Reference ConfigDSN ConfigTranslator Translation Shared Library Function Reference SQLDataSourceToDriver SQLDriverToDataSource INFORMIX CLI Error Codes SQL Grammar Data Types 13 4 13 7 13 7 13 7 13 8 13 8 13 52 13 60 13 90 13 93 13 150 13 225 13 239 13 255 13 295 13 312 14 3 14 7 15 3 15 7 Comparison Between INFORMIX CLI and Embedded SQL Index Table of Contents vii Introduction About This Manual Organization of This Manual Types of Users Software Dependencies Demonstration Database New Features of This Product Conventions Typographical Conventions Icon Conventions l Co
362. ine GetUserInput not shown GetUserlInput parses the information builds and displays a dialog box and INFORMIX CLI Programmer s Manual SQLBrowseConnect returns the information entered by the user in szConnStrIn The application passes the user s information to the driver in the next call to SQLBrowse Connect After the application provides all the necessary information 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 shown in the following example DSN My Source The driver manager loads the driver associated with the data source My Source It then calls the driver SOLBrowseConnect 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 SQLBrowseConnect uses this information to connect to the red database server a
363. informix cli Trace 1 TraceFile trace log TraceAutoStop 0 ODBC Conformance Levels ODBC defines two conformance standards for drivers the API conformance standard and the SQL conformance standard API conformance refers to the functions that a driver supports SQL conformance refers to the SQL grammar that the driver supports API Conformance Level of INFORMIX CLI The ODBC API conformance standard includes three levels Core Level 1 and Level 2 The Core level includes functions that correspond to the functions in the X Open and SQL Access Group Call Level Interface CLI specification Level 1 and Level 2 functions extend the core functionality 1 12 INFORMIX CLI Programmer s Manual API Conformance Level of INFORMIX CLI The following table lists all Core Level 1 and Level 2 API functions that are defined by the ODBC specification INFORMIX CLI supports all of the Core and Level 1 API functions In addition INFORMIX CLI supports all Level 2 functions except those marked with an asterisk Core Level Functions Level 1 Functions Level 2 Functions SQLAllocConnect SQLBindParameter SQLBrowseConnect SQLAIlocEnv SQLColumns SQLColumnPrivileges SQLAIlocStmt SQLDriverConnect SQLDataSources SQLBindCol SQLGetConnectOption SOLDescribeParam SQLCancel SQLGetData SQLDrivers SQLColAttributes SQLGetInfo SQLExtendedFetch SQLConnect SQLGetFunctions SQLForeignKeys SQLDescribeCol SQLGetStmtOption SQLMoreResults SQLDisc
364. ing on the option an application does 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 SQLGetConnnectOption 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 SQLGetStmtOption 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 13 160 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 pebCursor 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 cu
365. ing to Connect to a Data Source The following table lists the long and short names of the attributes that you can include in the INFORMIX driver connection string With the exception of the data source name which must be specified by DSN you can use either the long or short names in the connection string For a description of these attributes see Required Data Source Configuration Information and Optional Data Source Configuration Information on page 2 17 Attribute Short Name DataSourceName DSN Database DB HostName HOST LogonID UID Password PWD Service SERV Server SERVER GetDBListFrom Informix GDBLFI CursorBehavior CB EnableScrollableCursors ESC Protocol PRO Windows 3 1 and Windows NT only YieldProc YLD Windows 3 1 only The following example shows a valid connection string for connecting to the stores7 data source The string specifically requests a connection to the stores7 database that resides on a computer named rainbow The user ID is mary DSN Stores7 DB stores7 H0ST rainbow SERV sqlexec UID mary PWD secret In this example the service and password are also specified INFORMIX CLI 2 29 Guidelines for Calling INFORMIX CLI Functions Determining INFORMIX CLI Conformance Levels Using the Driver Manager Calling Functions Buffers A Input Buffers ee Output Buffers 2 2 a Environment Connection and Statement Handles Using Data Types Function Return Codes 3 3 3 4
366. ink between the driver and the data source failed before the function completed The fOption was SQL_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 returned by SQLError in the argument szErrorMs describes the error and its cause The driver did not allocate memory required to support execution or completion of the function Given the specified fOption value an invalid 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 1 of 2 INFORMIX CLI Function Reference 13 287 SQL SetStmtOption SQLSTATE Error Description 1010 Function DM SQLExecute or SQLExecDirect was called sequence 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 1011 Operation invalid The fOption was SQL_CONCURRENCY at this time SQL_SIMULATE_CURSOR or SQL_CURSOR_TYPE and the statement was prepared 1092 Option type out of DM The value specified for the argument range fOption was in the block of numbers reserved for ODBC connection and statement options but was not valid for
367. ion link failure 24000 Invalid cursor state S1000 General error S1001 Memory allocation failure S1008 Operation canceled S1010 Function sequence error INFORMIX CLI Programmer s Manual When SQLSpecialColumns returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLSpecialColumns 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 SQOLSTATE value is SOL_ERROR unless noted otherwise 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 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 The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application DM SQLExecute or SQLExecDirect was called for the hstmt and returne
368. ion called SOLConnect this is the value of the szDSN argument If the application called SQLDriv erConnect or SOQLBrowseConnect 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 A character string Y if the data source is set to READ ONLY mode 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 3 of 22 InfoType SQL_DATABASE_NAME SQLGetInfo Returns A character string with the name of the current database in use SQL_DBMS_NAME SQL_DBMS_VER if the data source defines a named object called database In ODBC 2 0 this value of fInfoType has been replaced by the SQL_CURRENT_QUALIFIER connection option A character string with the name of the DBMS product accessed by the driver A character string that indicates the version of the DBMS product accessed by the driver The version has the form HH HHHH 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 4 of 22 INFORMIX CLI Function Referen
369. ire an hdbc The driver manager processes the SQLAIlocConnect function and calls the driver SQLAIlocConnect function when the application calls SQLConnect SQLBrowseConnect or SQLDriverConnect For more information see Usage on page 13 78 If the application calls SQLAllocConnect with a pointer to a valid 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 INFORMIX CLI Function Reference 13 11 SQLAllocEnv SQLAIlocEnv SQLAllocEnv allocates memory for an environment handle and initializes the INFORMIX CLI call level interface for application use An application must call SQLAIlocEnv before it calls any other INFORMIX CLI function Syntax RETCODE SQLA1locEnv phenv The SQLAIlocEnv function accepts the following argument Type Argument Use Description HENV FAR phenv Output Pointer to storage for the environment handle Return Codes SQL_SUCCESS or SQL_ERROR If SQLAIlocEnv returns SQL_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 Diagnostics A driver cannot return SQLSTATE values directly after the call to SQLAIllocEnv because no valid handle exists with which to call SQLError Two levels of SQ
370. irow is greater than 0 the driver returns the rowset 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 rowset 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 rowset 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 rowset that starts at the first row in the result set SQLExtendedFetch irow Argument For the SQL_FETCH_ABSOLUTE fetch type SQLExtendedFetch returns the rowset that starts at the row number specified by the irow argument For the SQL_FETCH_RELATIVE fetch type SOLExtendedFetch returns the rowset that starts irow rows from the first row in the current rowset The irow argument is ignored for the SQL_FETCH_NEXT SQL_FETCH_PRIOR SQL_FETCH_FIRST and SOQL_FETCH_LAST fetch types rgfRowStatus Argument In the refRowStatus 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 For static cursors this information is available for all rows For keyset mixed and dynamic cursors this information is available only fo
371. is implemented by the driver manager alone A character string with the filename of the driver used to access the data source 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 SQL_SPEC_MAJOR and SQL_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 returns 01 00 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 A character string Y if the data source supports expressions in the ORDER BY list N if it does not 6 of 22 INFORMIX CLI Function Reference 13 195 SQL Getinfo InfoType SQL_FETCH_DIRECTION SQL_FILE_USAGE 13 196 INFORMIX CLI Programmer s Manual 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 SQL_FD_FETCH_LAST SQ
372. iver manager it formats and returns arguments for SQLEtrror 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 INFORMIX CLI Programmer s Manual Sample Error Messages 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 InformixJ ODBC 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 Sample Error Returned from the Data Source If the DBMS could not find the table EMPLOYEE the driver might format and return the following arguments for SQLError szSQLState S0002 pfNativeError 206 szErrorMsg Informix ODBC Informix Driver Informix The specified table EMPLOYEE is not in the database pcbErrorMsg 96 Because th
373. k traffic maximum data length 13 294 packet size 13 279 prepared statements 6 6 Nonrepeatable reads 13 196 NOT NULL clauses 13 203 NULL data collating 13 203 concatenation behavior 13 193 output buffers 3 6 retrieving 13 23 SQLBindParameter 13 35 SQLExtendedFetch 13 135 SQLFetch 13 150 SQLGetData 13 173 SQLPutData 13 265 Null pointers input buffers 3 6 output buffers 3 6 parameter length 13 35 unbinding columns 13 23 Nullability columns 13 59 13 74 13 89 Null termination byte binary data 13 35 character data 13 35 embedded 3 6 examples C 23 C 36 input buffers 3 5 output buffers 3 6 parameters 6 8 Numeric data converting to C C 18 converting to SQL C 29 currency datatype 13 224 money data type 13 224 radix 13 74 scalar functions 13 204 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 See also Floating point data See also Integer data Numeric functions supported by INFORMIX driver 1 14 O ODBC conformance standards 1 12 extensions to SQL for INFORMIX driver 1 14 functions See Functions ODBC version compatibility See Version compatibility ODBC Administrator adding data sources for Informix driver 2 16 ODBC administrator modifying data sources for driver Windows 2 24 ODBC architecture error handling 8 5 ODBC options 1 10 ODBC INI Windows 95 1 7 2 17 Windows NT 1 7 2 17 odbc ini keywords trace 13 15 listing drivers 13 109 ODBC functions using SQLAllocEnv 13
374. known if the column accepts NULL values 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 13 8 13 72 _INFORMIX CLI Programmer s Manual SQLColumns 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 define REM_LEN 254 Declare storage locations for result set data UCHAR szQualifier STR_LEN szOwner STR_LEN UCHAR szTableName STR_LEN szColName STR_LEN UCHAR szTypeNameLSTR_LEN szRemarks REM_LEN SDWORD Precision Length SWORD DataType Scale Radix Nullable Declare storage locations for bytes available to return SDWORD cbQualifier cbOwner cbTableName cbColName SDWORD cbTypeName cbRemarks cbDataType cbPrecision SDWORD cbLength cbScale cbRadix cbNullable retcode SQLColumns hstmt NULL O All qualifiers NULL O All owners xf EMPLOYEE SQL_NTS EMPLOYEE table NULL 0 All columns f if retcode SQL_SUCCESS Bind columns in result set to storage location
375. l Statements INFORMIX CLI Function SQLTransact SQL_COMMIT option SQLTransact SQL_ROLLBACK option 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 state ments with USING SQL DESCRIPTOR 2 of 2 The following table lists transaction control statements Comments None 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 SQLConnect None 5 5 2 DISCONNECT SQLDisconnect INFORMIX CLI does not support DISCONNECT ALL 5 5 3 SET CONNECTION None The SQL 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 connection context to be switched in other words there must not be a transaction 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 require
376. lause For more information see Date Time and Time Stamp Data on page 6 13 Storage locations remain bound to parameter markers until the application calls SQLFreeStmt with the SQL_RESET_PARAMS option or the SQL_DROP option An application can bind a different storage area to a parameter 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 Programmer s Manual Performing Transactions Performing Transactions In auto commit mode every SQL statement is a complete transaction that is automatically committed 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 back the transaction with SQLTransact For the Informix driver the default transaction mode is auto commit An application calls SQLSetConnectOption 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 rollback a transaction rather than submitting a COMMIT or ROLLBACK statement
377. lid ODBC SQL data type indicator The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application Diagnostics SQL_ERROR unless noted otherwise SQLSTATE Error 01000 General warning 08S01 Communication link failure 24000 Invalid cursor state S1000 General error S1001 Memory allocation failure S1004 SQL data type out of range S1008 Operation canceled 1 of 2 SQLSTATE 1010 1C00 S1T00 Usage Error Function sequence error Driver not capable Time out expired SQL Get Typelnfo 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 fSqlType 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 SQLSetStmtOption 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 result set INFORMIX CLI Function Reference 13 219 SQL GetTypelnfo 13 220 Column Name TYPE_NAM
378. ll termnation byte available to return in szDriverAttributes If the number of bytes available to return is greater than or equal to cbDrvrAttrMax the list of attribute value pairs in szDriverAttributes is truncated to cbDrovrAttrMax 1 bytes 2 of 2 SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLDrivers returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLDrivers 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 SQLSTATE value is SQL_ERROR unless noted otherwise INFORMIX CLI Function Reference 13 105 SQLDrivers 01000 01004 S1000 S1001 S1090 S1103 SQLSTATE Error General warning Data truncated General error Memory allocation failure Invalid string or buffer length Direction option out of range 13 106 INFORMIX CLI Programmer s Manual 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 retur
379. llocate a statement handle Kj SQLAIlocEnv amp henv SQLAIlocConnect henv amp hdbc rc SQLConnect hdbc server SQL_NTS uid SQL NTS pwd SQL_NTS if rc SQL_SUCCESS amp amp rc SQL_SUCCESS_WITH_INFO return print_err hdbc SQL_NULL_HSTMT SQLAIlocStmt hdbc amp hstmt EXEC SQL CREATE TABLE NAMEID ID integer NAME varchar 50 Execute the SQL statement Ef Istrcpy create CREATE TABLE NAMEID ID INTEGER NAME VARCHAR 50 rc SQLExecDirect hstmt create SQL_NTS 10 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 NAMEI 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 id 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
380. lls 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 SQLConnect The driver then allocates handles and initializes itself When the application calls SQLDisconnect the driver manager calls SQLDisconnect in the driver However it does not unload the driver This keeps the driver in memory for applications that repeatedly connect to and disconnect from a data source When the application calls SQLFreeConnect the driver manager calls SOLFreeConnect and SQLFreeEnv in the driver and then unloads the driver An INFORMIX CLI application can establish more than one connection After being loaded by the driver manager a driver can locate its corre sponding data source specification in the odbc ini file and use driver specific information from the specification to complete its set of required connection information 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 has finished processing data it disconnects from the data source and frees 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
381. log 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 referenced by szConnStrOut m SQL_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 SQL_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 connects to the data source and copies szConnStrIn to szConnStrOut Otherwise the driver returns SQL_ERROR for SOQLDriverConnect After successfully connecting to the data source the driver also sets pcebConnStrOut to the length of szConnStrOut If the user cancels a dialog box presented by the driver manager or the driver SOLDriverConnect returns SQL_NO_DATA_FOUND For information about how the driver manager and the driver interact during the connection process see Usage on page 13 78 INFORMIX CLI Programmer s Manual SQL DriverConnect Connection Options The SQL_LOGIN_TIM
382. lowing list identifies valid values for fFunction for ODBC extension level 2 functions that the INFORMIX CLI driver supports m SQL_API_SOQLBROWSECONNECT SQL_API_COLUMNPRIVILEGES SQL_API_SOQLDATASOURCES SQL_API_SOLDRIVERS SQL_API_SQLEXTENDEDFETCH SQL_API_MORERESULTS SQL_API_SOLNATIVESQL SQL_API_SQLNUMPARAMS SQL_API_PARAMOPTIONS SQL_API_SOLPRIMARYKEYS SQL_API_PROCEDURES SQL_API_SOQLSETSCROLLOPTIONS SQL_API_TABLEPRIVILEGES INFORMIX CLI Programmer s Manual SQLGetFunctions Code Example The following examples show how an application uses SQLGetFunctions to determine if a driver supports SQLTables SOQLColumns and SQLStatistics If the driver does not support these functions the application disconnects from the driver The first example calls SQLGetFunctions once for each function 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 SQL_API_SQLTABLES amp
383. lt set when the statement compiles For example the query SELECT EMPNO EMPNAME FROM EMPLOYEE returns two specific columns Unknown result set The application does not know the exact form of the SQL statement and therefore the result set when the statement compiles For example the ad hoc query SELECT FROM EMPLOYEE returns all the currently defined columns in the EMPLOYEE table The appli cation might not predict the format of these results before it executes the command Retrieving Results 7 3 Assigning Storage for Results Binding 7 4 Assigning Storage for Results Binding An application can assign storage for results before or after it executes an SQL 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 C m The address of an output buffer for the data The application must allocate this buffer which must be sufficient 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
384. lumn 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 13 16 INFORMIX CLI Programmer s Manual SQLBindCol Syntax RETCODE SQLBindCol hstmt icol fCType rgbValue cbValueMax pcbValue The SQLBindCol 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 C data type of the result data which must be one of the following values SQL_C_BINARY SQL_C_BIT SQL_C_CHARSOL_C_DATE SQL_C_DEFAULT SQL_C_DOUBLE SQL_C_FLOAT SQL_C_SLONG SQL_C_SSHORT SQL_C_STINYINT SQL_C_TIME SQL_C_TIMESTAMP SQL_C_ULONG SQL_C_USHORT SQL_C_UTINYINT SQL_C_DEFAULT specifies that data be transferred to its default C data type For information about how data is converted see Converting Data from SQL to C Data Types on page C 13 PTR rgbValue Input Pointer to storage for the data If rgbValue is a null pointer the driver unbinds the column To unbind all columns an appli cation calls SQLFreeStmt with the SQL_UNBIND option 1 of 2 INFORMIX CLI Function Reference 13 17 SQLBindCol 13 18 Type Argument Use SDWORD cbValueMax Input SDWORD pebValue Input FAR Return Codes SQL_INVALID_HANDLE INFORMIX CLI Progr
385. lumns to the right of the rightmost bound column and then only in left to right order Assigning Storage for Rowsets Binding In addition to binding individual rows of data an application can call SQLBindCol to assign storage for a rowset one or more rows of data To specify how many rows of data are in a rowset an application calls SQLSetStmtOption with the SQL_ROWSET_SIZE option Column Wise and Row Wise Binding By default rowsets are bound in column wise fashion They can also be bound in row wise fashion Retrieving Results 7 7 Assigning Storage for Rowsets Binding 7 8 1 1 To assign storage for column Cwise bound results an application performs the following operations Allocates an array of data storage buffers The array has as many elements as there are rows in the rowset Allocates 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 rowset Calls SQLBindCol and specifies 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 will use the array element size to determine where to store successive rows of data in the array To assign storage for row wise bound results an application performs the following operations Declares a structure that c
386. 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 SQL Statement INFORMIX CLI Function Comments 4 3 1 Static SQL none Issued implicitly by the DECLARE CURSOR driver if a cursor specifi cation is passed to SQLExecDirect 4 3 2 Dynamic SQL none Cursor is generated DECLARE CURSOR automatically by the driver To set a name for the cursor use SQLSet CursorName To retrieve a cursor name use SQLGetCursorName Data Definition Statements The following table lists data definition statements Section SQL Statement INFORMIX CLI Function Comments 5 1 2 ALTER TABLE SQLPrepare None 5 1 3 o qee SQLExecute ae CREATE VIEW or SQLExecDirect
387. mational message Function returns SQL_SUCCESS_WITH_INFO 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 S1010 Function DM There was at least one hdbc in an allocated sequence error or 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 SOQL_ERROR and the henv and any active hdbc remains valid When the driver manager processes the SQLFreeEnv function it checks the TraceAutoStop keyword in the ODBC section of the odbc ini file If the keyword is set to 1 the driver manager disables tracing for all applications and sets the Trace keyword in the ODBC section of the odbc ini file to 0 Code Example See SOLBrowseConnect and SQLConnect INFORMIX CLI Function Reference 13 153 SQL FreeStmt Related Functions For information about See Allocating an environment handle SQLAIlocEnv Freeing a connection handle SQLFreeConnect SQLFreeStmt SQLFreeStmt stops processing associated with a specific hstmt closes any open cursors associated with the hstmt discards pending results and optionally frees all resources associated with the statement handle
388. me stamp is zero Time portion of time stamp is nonzero Fractional seconds portion of time stamp is zero Fractional seconds portion of time stamp is nonzero Fractional seconds portion of time stamp is not truncated Fractional seconds portion of time stamp is truncated rgbValue Data Truncated data Untouched Data Untouched Data Truncated data Data 4 Truncated data d e Data Truncated data pcbValue Length of data Length of data Untouched Length of data Untouched 6f 6f 6f 6f 16 16 SQLSTATE N A 01004 22003 N A 22003 N A 01004 N A 01004 N A 01004 4 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 gt The fractional seconds of the time stamp are truncated The time portion of the time stamp is truncated 1 of 2 C 22 INFORMIX CLI Programmer s Manual fCType Test d The date portion of the time stamp is ignored SQL to C Data Conversion Examples rgbValue e The fractional seconds portion of the time stamp is truncated f This is the size of the corresponding C data type pebValue SQLSTATE 2 of 2 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 seconds Exc
389. ment SQL conformance level Core ODBC 1 0 SQL conformance level Extended ODBC 2 0 SELECT ALL DISTINCT select list FROM table reference list WHERE search condition FOR UPDATE OF column name column name Statement List SQL conformance level Minimum statement create table statement delete statement searched drop table statement insert statement select statement update statement searched SQL Grammar B 9 Statement List SQL conformance level Core statement alter table statement create index statement create table statement create view statement delete statement searched drop index statement drop table statement drop view statement grant statement insert statement revoke statement select statement update statement searched SQL conformance level Extended statement alter table statement create index statement create table statement create view statement delete statement positioned delete statement searched drop index statement drop table statement drop view statement ODBC procedure extension grant statement insert statement revoke statement select statement select for update statement statement list update statement positioned update statement searched statement list statement statement statement list B 10 INFORMIX CLI Programmer s Manual UPDATE Statement Positioned UPDATE Statement
390. ment fOption was in the block of numbers reserved for ODBC information types but was not valid for the version of ODBC supported by the driver 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 SQLSetStmtOption 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 five formats 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 returned in rgbInfoValue accordingly For an example of how an application could retrieve data from a 32 bit bitmask see Code Example on page 13 211 SQLGetInfo 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_PROC
391. ments Used in SQL Statements B 16 SQL Conformance Element Level ODBC time literal Extended ODBC std esc initiator t time value ODBC std esc terminator ODBC ext esc initiator t time value ODBC ext esc terminator ODBC timestamp literal Extended ODBC std esc initiator ts timestamp value ODBC std esc terminator ODBC ext esc initiator ts timestamp value ODBC ext esc terminator ODBC ext esc initiator Extended ODBC ext esc terminator Extended ODBC outer join extension Extended ODBC std esc initiator oj outer join ODBC std esc terminator ODBC ext esc initiator oj outer join ODBC ext esc terminator ODBC scalar function extension Extended ODBC std esc initiator fn scalar function ODBC std esc terminator ODBC ext esc initiator fn scalar function ODBC ext esc terminator ODBC std esc initiator ODBC std esc prefix SQL esc vendor clause Extended ODBC std esc prefix Extended ODBC std esc terminator Extended order by clause ORDER BY sort specification sort specification Minimum outer join table name correlation name LEFT OUTER JOIN Extended table name correlation name outer join ON search condition For outer joins search condition must contain only the join condition between the specified table names owner name user defined name Core pattern value character string literal dynamic parameter Minimum In a character string literal the percent charac
392. mes of procedures stored in a data source Each function returns the information as a result set Use SQLBindCol and SQLFetch to retrieves these results Sending Parameter Data at Execution Time To send parameter data such as for parameters of the SQL_LLONGVARCHAR or SQL_LONGVARBINARY types when a statement executes use the following functions 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 SQL_LEN_DATA_AT_EXEC length macro If the fSqlType argument is SQL_LONGVARBINARY or SQL_LONGVARCHAR and the driver returns Y for the SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo 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 at ru time can be used to retrieve the data For example rgbValue 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 SQLExecDirect and the executing statement includes a data at execution parameter the driver returns SQL_NEED_DATA INFORMIX CLI Programmer s Manual Specifying Arrays of Parameter Values To send the parameter dat
393. mine the type of a parameter in a procedure call it sets fParamType to SQL_PARAM_INPUT if the data source returns a value for the parameter the driver discards it INFORMIX CLI Programmer s Manual SQLBindParameter 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 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 pcebValue buffer must contain SQL_NULL_DATA SQL_DATA_AT_EXEC or the result of the SQL_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 SQL_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 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
394. mined in advance the driver sets pcebValue to SQL_NO_TOTAL If the data value for the column is NULL the driver stores SQL_NULL_DATA in pebValue INFORMIX CLI Function Reference 13 171 SQL GetData 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 7 If the application requires more than one call to SQLGetData to retrieve data from a single column with a character 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 SQL_SUCCESS indicating that all the column data has been retrieved SQLGetData returns SQL_NO_DATA_FOUND when it calls for a column after all the data has been retrieved and before data is retrieved for a subsequent 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 mo
395. mment Icons Compliance Icons Platform Icons Example Code Conventions Screen Illustration Conventions Additional Documentation Printed Documentation On Line Documentation Error Message Files Release Notes and Dacumeniaton Noise Related Reading Compliance with Industry Standards Informix Welcomes Your Comments fo O OC NX DDB WwW PRR ePrROO PRR PRR PP WO WON NY e o oo 2 _INFORMIX CLI Programmer s Manual his chapter introduces the INFORMIX CLI Programmer s Manual Read this chapter for an overview of the information provided in this manual and for an understanding of the conventions used throughout this manual The INFORMIX CLI application programming interface API enables the C programmer to create custom applications for relational database access and it uses function calls to pass dynamic SQL statements as function arguments It is an alternative to embedded dynamic SQL Unlike embedded SQL it does not require a preprocessor The libraries and header files that are provided with INFORMIX CLI enable you to access databases manipulate the data in your program interact with the database server and check for errors About This Manual The INFORMIX CLI Programmer s Manual is both a user guide and a reference manual This manual is a complete guide to the features that make up the Informix implementation of the ODBC standards This manual explains how to use INFORMIX CLI to access an
396. mn and is not interop erable among DBMSs UPDATE EMPLOYEE SET BIRTHDAY vendor Microsoft product ODBC d 938 0115 HERE NAME Jacobs Walter UPDATE EMPLOYEE SET BIRTHDAY d 1938 01 15 HERE NAME Jacobs Walter UPDATE EMPLOYEE SET BIRTHDAY 01 15 1938 HERE NAME Jacobs Walter Executing SQL Statements 6 13 Using ODBC Extensions to SQL 6 14 The ODBC escape clauses for date time and timestamp literals can be used in parameters with a C data type of SQL_C_CHAR For example the following statement uses a parameter to update the birthday of Jane Smith in the EMPLOYEE table UPDATE EMPLOYEE SET BIRTHDAY WHERE NAME Smith Jane A storage location of type SQL_C_CHAR bound to the parameter might contain any of the following values The first value uses the escape clause syntax The second value uses the shorthand syntax The third value uses the native syntax for Informix for a DATE column and is not interoperable among DBMSs yvendor Microsoft product ODBC d 1938 01 15 d 1938 01 15 TOTALS 103 o An application can also send date time or time stamp values as parameters using the C structures defined by the C data types SQL_C_DATE SQL_C_TIME and SQL_C_TIMESTAMP To determine if a data source supports date time or time stamp data an application calls SOLGetTypelnfo Scalar Functions Scalar functions such as string length absolute
397. mns of data to local storage locations Finally the application fetches each row of data with SQLFetch and prints the name age and birthday of each employee For more code examples see SOQLColumns 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 13 22 INFORMIX CLI Programmer s Manual Related Functions For information about SQLBindParameter See 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
398. more information see Precision Scale Length and Display Size on page C 8 SCALE SMALLINT The scale of the column on the data source NULL is returned for data types where scale is not applicable For more infor mation concerning scale see Precision Scale Length and Display Size on page C 8 PSEUDO_COLUMN SMALLINT Returns one of the following values to indicate whether the column is a pseudo column SQL_PC_UNKNOWN SQL_PC_PSEUDO SQL_PC_NOT_PSEUDO with the identifier quote character returned by SQLGetInfo Important For maximum interoperability pseudo columns should not be quoted 13 302 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 guaranteed to return either no rows or one row If an application reselects a row based on the rowid column or columns and the row is not found the application can assume that the row was deleted or the rowid columns were modified The opposite is not true Even if the rowid 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 rowid column or columns are guaranteed not to change while positioned on that row INFORMIX CLI Programmer s Manual
399. mount of non null arguments necessary for the function to return success Consider a call to SQLTables in which the application requests information about a table named Customers Many times this call is coded similarly to the following example rc SQLTables NULL NULL NULL NULL Customers SQL_NTS NULL A driver could turn this SQLTables call into SOL similar to the following commands SELECT FROM SysTables WHERE TableName Customers UNION ALL SELECT FROM SysViews WHERE ViewName Customers UNION ALL SELECT FROM SysSynonyms WHERE SynName Customers ORDER BY In some circumstances not much information is known about the object for which you are requesting information but in many cases at least some infor mation is known Any additional information that the application can send the driver when calling catalog functions can result in improved perfor mance and reliability Suppose in the previous example that three Customers tables were returned in the result set one owned by the user one owned by sales and one that was a view created by management Although it might be obvious that the intent of the application is to use the one owned by the user it might not be obvious to the user which table to choose If the application had specified the OwnerName argument for the SQLTables call then reliability is improved only one table returned and performance increases Less network traffic is requir
400. mple 13 24 function description 13 18 truncating data 13 22 unbinding columns 9 3 13 23 with SQLFetch 13 150 SQLBindParameter code example 13 39 function description 13 25 replaces SQLSetParam 13 31 sending long data values 6 10 unbinding parameters 9 3 13 156 version compatibility 13 287 with SQLParamData 13 33 13 36 with SQLParamOptions 13 33 13 34 with SQLPutData 13 36 SQLBrowseConnect code example 13 48 driver manager 13 47 function description 13 40 15 3 15 7 with SQLDisconnect 13 48 SQLCancel function description 13 51 SQLColAttributes column attributes 7 4 function description 13 54 SQLColumnPrivileges 13 62 SQLColumns catalog 6 9 code example 13 75 function description 13 68 intended usage 13 71 SQLConnect code example 13 81 driver manager 13 80 function description 13 77 with SQLAIocConnect 13 80 with SQLAIocEnv 13 80 with SQLSetConnectOption 13 80 SQLDataSources 5 7 13 83 SQLDataSourceToDriver 15 3 SQLDescribeCol 7 4 13 87 SQLDisconnect disconnecting 9 4 function description 13 92 with SQLBrowseConnect 13 48 with SQLFreeConnect 13 153 SQLDriverConnect connecting with 5 6 connection strings 5 6 dialog boxes 5 7 5 8 driver manager 13 102 function description 13 95 login interval 13 105 odbc ini 5 7 SQLDrivers function description 13 106 13 110 13 113 13 122 13 129 13 146 13 152 13 154 13 156 13 160 13 163 13 166 13 176 13 183 13 215 13 218 13 227 13 230 13 233 13 235 13 238
401. n and each subsequent row of data at an offset of vParam bytes from the data for the previous row For each bound column the driver stores the number of bytes that are available to return for the first row at the address specified by pcbValue 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 SOQL_NO_TOTAL If the data for the column is NULL the driver sets pcebValue to SQL_NULL_DATA Positioning the Cursor The following operations require a cursor position Positioned update and delete statements Calls to SQLGetData Before the application executes a positioned update a delete statement or a call to SOLGetData it must position the cursor by calling SQLExtendedFetch to retrieve a rowset the cursor points to the first row in the rowset INFORMIX CLI Programmer s Manual SQLExtendedFetch The following table shows the rowset and code returned when the appli cation requests different rowsets Requested Rowset Return Code Cursor Position Returned Rowset Before start of SQL_NO_DATA_FOUND Before start ofresult None The contents of the rowset result set set buffers are undefined Overlaps start of SQL_SUCCESS Row 1 of rowset First rowset in
402. n at connect time is a good algorithm it should not be minimized by connecting twice to get this information At least one popular ODBC enabled application connects a second time to gather driver information but never disconnects the second connection 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 Another poor algorithm is to connect and disconnect several times throughout your application to perform SQL statements Connection handles can have multiple statement handles associated with them Statement handles are defined to be memory storage for information about SQL statements Applications should use statement handles to manage multiple SQL statements Connection and statement handling should not be delayed until implemen tation Spending time in the design phase on connection management makes your application perform better and makes it more maintainable INFORMIX CLI Programmer s Manual Retrieving Information about a Data Source Retrieving Information about a Data Source Catalog functions are relatively slow compared to all other ODBC functions In addition SOLGetTypelnfo is also a potentially expensive ODBC function and is included in this discussion of catalog functions For a list of the catalog functions that INFORMIX CLI supports see Retrieving Information About the Data Source Catalog o
403. n deleted 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 reexecutes the statement that read the rows and it receives a different set of rows vParam must be one of the following values SQL_TXN_READ_UNCOMMITTED Dirty Reads Nonrepeatable Reads and Phantoms are possible SQL_TXN_READ_COMMITTED Dirty Reads are not possible Nonrepeatable Reads and Phantoms are possible SQL_TXN_REPEATABLE_READ Dirty Reads and Nonrepeatable Reads are not possible Phantoms are possible SQL_TXN_SERIALIZABLE Transactions are serializable Dirty Reads Nonrepeatable Reads and Phantoms are not possible SQL_TXN_VERSIONING Transactions are serializable but higher concur rency 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 nonlocking protocol such as record versioning 40f4 INFORMIX CLI Function Reference 13 279 SQL SetConnectOption 13 280 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 translation shared library that you use A new option can be set at any time and will
404. n error and are accompanied by a return code of SQL_ERROR The class IM is signifies warnings and errors that derive from the imple mentation of INFORMIX CLI The subclass value 000 in any class is for implementation defined conditions within the given class The assignment of class and subclass values is defined by ANSI SQL 92 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 INFORMIX CLI Function Reference 13 7 Catalog Functions Catalog Functions INFORMIX CLI supports a set of functions that return information about the system tables or catalog of the data source These functions are sometimes collectively called the catalog functions For more information about catalog functions see Retrieving Information About the Data Source Catalog on page 6 9 The following list shows the catalog functions SQLColumnPrivileges SOLColumns SQLPrimaryKeys SQLProcedures SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables Search Pattern Arguments Each catalog function returns information in the form of a result set The information a function returns can be constrained by a search pattern passed as an argument to that function These search patterns can contain the under score _ the percent symbol and a driver defined escape character as follows m The underscore represents a
405. n flag to the translation functions with SQLSetConnectOption Connecting to a Data Source 5 9 Related Functions Related Functions The following functions are related to connections drivers and data sources For more information about these functions see Chapter 13 INFORMIX CLI Function Reference Function Description SQLDataSources Retrieves a list of available data sources The driver manager retrieves this information from the odbc ini file An application can present this information to a user or automatically select a data source SQLDrivers Retrieves a list of installed drivers and their attributes The driver manager 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 SQLGetInfo Retrieves general information about a driver and data source including filenames versions conformance levels and capabilities SQLGetTypelInfo Retrieves the SQL data types supported by a driver and data source SQLSetConnectOption Sets or retrieves connection options such as the data SQLGetConnectOption source access mode automatic transaction commitment time out values function tracing data translation options and transaction isolation 5 10 INFO
406. n page 6 9 Minimize the use of Catalog Functions Although almost no ODBC application can be written without catalog functions their use should be minimized To return all result column infor mation mandated by the ODBC specification a driver might have to perform multiple queries joins subqueries and or unions in order to return the necessary result set for a single call to a catalog function Frequent use of catalog functions in an application will likely result in poor performance If possible applications should cache information returned from catalog functions so that multiple executions are not needed For example call SQLGetTypelnfo once in the application and cache the elements of the result set on which your application depends Probably no application uses all elements of the result set generated by a catalog function so the cache of information should not be difficult to maintain Supply Non Null Arguments to Catalog Functions Passing null arguments to catalog functions results in time consuming queries being generated by the driver In addition network traffic potentially increases due to unwanted result set information Always supply as many non null arguments to catalog functions as possible Designing Performance Oriented Applications 11 5 Supply Non Null Arguments to Catalog Functions Because catalog functions are slow applications should invoke them as efficiently as possible Many applications pass the least a
407. n the manuals or that have been modified since publication The file that contains the documentation notes for INFORMIX CLI Version 2 5 for UNIX is called CLIDOC_2 5 The file that contains the documentation notes for INFORMIX CLI Version 2 5 for Windows is called doccli 250 Describes feature differences from earlier versions of Informix products and how these differences might affect current products This file also contains information about any known problems and their workarounds The file that contains the release notes for INFORMIX CLI Version 2 5 for UNIX is called CLI_2 5 The file that contains the release notes for INFORMIX CLI Version 2 5 for Windows is called cli 250 Please examine these files because they contain vital information about application and performance issues Related Reading For additional information on ODBC refer to the Microsoft ODBC Programmer s Reference and SDK Guide Version 2 0 Microsoft Press 1994 For additional technical information on database management consult the following books m An Introduction to Database Systems by C J Date Addison Wesley Publishing 1994 m Transaction Processing Concepts and Techniques by Jim Gray and Andreas Reuter Morgan Kaufmann Publishers Inc 1993 Compliance with Industry Standards To learn more about the SQL language consider the following books m A Guide to the SQL Standard by C J Date with H Darwen Addison Wesley Publishing 1993
408. n time 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 Data Types C 35 C to SQL Data Conversion Examples C to SQL Data Conversion Examples The following table illustrates how the driver converts C data to SQL data C DataType C Data Value SQL Data Type Column length SQL Data Value SQLSTATE SQL_C_CHAR abcdef 0 SQL_CHAR 6 abcdef N A SQL_C_CHAR abcdef 0 SQL_CHAR 5 abcde 01004 SQL_C_CHAR 1234 56 0 SQL_DECIMAL 8 gt 1234 56 N A SQL_C_CHAR 1234 56 04 SQL_DECIMAL Pe 1234 5 01004 SQL_C_CHAR 1234 56 02 SQL_DECIMAL 4 22003 SQL_C_FLOAT 1234 56 SQL_INTEGER not applicable 1234 01004 SQL_C_DATE 1992 12 31 SQL_CHAR 10 1992 12 31 N A SQL_C_DATE 1992 12 31 SQL_CHAR 9 22003 SQL_C_DATE 1992 12 31 SQL_TIMESTAMP not applicable 1992 12 31 N A 00 00 00 0 SQL_C_TIMESTAMP 1992 12 31 SQL_CHAR 22 1992 12 31 N A 23 45 55 23 45 55 12 120000000 4 SQL_C_TIMESTAMP 1992 12 31 SQL_CHAR 21 1992 12 31 01004 23 45 55 23 45 55 1 120000000 4 SQL_C_TIMESTAMP 1992 12 31 SQL_CHAR 18 i 22003 23 45 55 120000000 4 a 0 represents a null termination byte The null termination byte is
409. nce number in index starting with 1 NULL is returned if TYPE is SQL_TABLE_STAT 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 CLI Function Reference 13 309 SQL Statistics 13 310 Column Name Data Type COLLATION CHAR 1 CARDINALITY INTEGERS PAGES INTEGER FILTER_CONDITION VARHAR 128 to NULL Code Example INFORMIX CLI Programmer s Manual Comments Sort sequence for the column A for ascending D for descending NULL is returned if column sort sequence is not supported by the data source or if TYPE is SQL_TABLE_STAT 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 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 If the index is a filtered index this is the filter condition such as
410. nction Name SQLAIlocEnv Core SQLAIlocConnect Core SQLConnect Core SQLDriverConnect Level 1 SQLBrowseConnect Level 2 driver and data source ODBC Function Name SQLDataSources Level 2 SQOLDrivers Level 2 INFORMIX CLI Programmer s Manual Conformance Conformance Connecting to a Data Source The following table describes functions that connect to a data source Purpose Obtains an environment handle One environment handle is used for one or more connections Obtains a connection handle Connects to a specific driver by data source name user ID and password Connects to a specific driver by connection string or requests that the driver manager and driver display connection dialog boxes for the user Returns successive levels of connection attributes and valid attribute values Whena value has been specified for each connection attribute connects to the data source Obtaining Information About a Driver and Data Source The following table describes functions that obtain information about a Purpose Returns the list of available data sources Returns the list of installed drivers and their attributes 1 of 2 Setting and Retrieving Driver Options ODBC Function Name Conformance Purpose SQLGetInfo Level 1 Returns information about a specific driver and data source SQLGetFunctions Level 1 Returns supported driver functions SQLGetTypelInfo Level 1 Returns information about supported data types
411. nction description 13 183 scalar functions 13 192 SQL statements 13 190 SQLGetStmtOption 13 215 SQLGetTypelnfo ALTER TABLE statements B 1 CREATE TABLE statements B 1 function description 13 218 supported data types 3 8 SQLMoreResults 13 227 SQLNativeSql 13 230 SQLNumParams 13 233 SQLNumkResultCols 7 4 13 235 SQLParamData data at execution parameters 6 10 function description 13 238 with SQLBindParameter 13 33 13 36 with SQLPutData 13 238 SQLParamOptions code example 13 245 function description 13 241 multiple parameter values 13 241 with SQLBindParameter 13 33 13 34 SQLPrepare function description 13 246 with SQLExecute 13 127 SQLPrimaryKeys 6 9 13 253 SQLProcedureColumns listing columns 6 18 SQLProcedures code example 13 263 listing procedures 6 18 SQLPutData code example 13 269 data at execution parameters 6 10 Index 11 function description 13 265 with SQLBindParameter 13 36 with SQLParamData 13 238 SQLRemoveDSNFromIni 14 6 SQLRowCount function description 13 272 interoperability 7 4 SQLSetConnectOption commit mode 6 9 function description 13 274 translating data 5 9 with SQLConnect 13 80 with SQLTransact 13 278 See also Connection options SQLSetCursorName 13 283 SQLSetParam 13 287 SQLSetPos locking rows 7 13 with SQLExtendedFetch 13 136 SQLSetScrollOptions 13 287 SQLSetStmtOption function description 13 288 with SQLExtendedFetch 13 133 See also Statement options SQLSpecialColumns 6 10
412. nd TABLE_NAME columns an application can call SQLGetInfo with the SOL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME LEN and SQL_MAX_TABLE_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 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 not NULL GRANTOR VARCHAR 128 Identifier of the user who granted the privilege NULL if not applicable to the data source GRANTEE VARCHAR 128 Identifier of the user to whom the privilege not NULL was granted 1 of 2 INFORMIX CLI Function Reference 13 315 SQ_TablePrivileges 13 316 Column Name Data Type PRIVILEGE VARCHAR 128 not NULL IS_GRANTABLE VARCHAR 3 Code Example INFORMIX CLI Programmer s Manual Comments Identifies the table privilege Can be one of the following or a data source specific privilege SELECT The grantee is permitted to retrieve data for one or more columns of the
413. ned by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLPutData 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 SQLSTATE value is SQL_ERROR unless noted otherwise Description 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 SQLPutData 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 link failure The communication link between the driver and the data source failed before the function completed 22001 String data right truncation 13 264 INFORMIX CLI Programmer s Manual The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo was 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 pcebValue argument in SOLBindParameter 1 of 3 SQLSTATE 22003 Error Numeric value out of range SQL PutData Description SQLPutData was called more than once for a
414. nfo with the SQL_MAX_COLUMN_NAME_LEN option Column Name SCOPE COLUMN_NAME DATA_TYPE TYPE_NAME PRECISION Data Type SMALLINT VARCHAR 128 not NULL SMALLINT not NULL VARCHAR 128 not NULL INTEGER Comments Actual scope of the rowid Contains one of the following values SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_SESSION NULL is returned when fColType is SQL_ROWVER For a description of each value see the description of fScope on page 13 297 Column identifier For a list of valid ODBC SQL data types see Appendix C For information on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 Data source dependent data type name for example CHAR VARCHAR MONEY LONG VARBINARY or CHAR FOR BIT DATA 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 C 8 1 of 2 INFORMIX CLI Function Reference 13 301 SQL SpecialColumns Column Name Data Type Comments LENGTH 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
415. nfor mation returned for each option in SQLGetStmtOption Character strings pointed to by the vParam argument of SOLSetStmtOption have a maximum length of SQL_MAX_OPTION_STRING_LENGTH bytes excluding the null termination byte vParam Contents INFORMIX CLI does not support this option The default is set to SQL_ASYNC_ENABLE_OFF 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 SQLExtendedFetch 1 of 5 INFORMIX CLI Function Reference 13 289 SQL SetStmtOption fOption SQL_CONCURRENCY vParam Contents A 32 bit integer value that specifies the cursor concurrency SQL_CONCUR_READ_ONLY Cursor is read only No updates are allowed SQL_CON
416. ng a new row therefore rows of data for which the key values have been changed also appear as holes When the driver encounters a hole in the result set it returns a status code for the row of SQL_ROW_DELETED Rows of data inserted into the result set by other users including other cursors in the same application after the cursor was opened are not visible to the cursor because the keys for those rows are not in the keyset The SQL_STATIC_SENSITIVITY information type returns whether the cursor can detect rows it has deleted or inserted Because updating key values in a keyset driven cursor is considered to be deleting the existing row and inserting a new row keyset driven cursors can always detect rows that they have updated Mixed Keyset Dynamic Cursors If a result set is large it might be impractical for the driver to save the keys for the entire result set Instead the application can use a mixed cursor Ina mixed cursor the keyset is smaller than the result set but larger than the rowset Within the boundaries of the keyset a mixed cursor is keyset driven that is the driver uses keys to retrieve the current data values for each row in the rowset When a mixed cursor scrolls beyond the boundaries of the keyset it becomes dynamic so the driver simply retrieves the next rowset size rows of data The driver then constructs a new keyset which contains the new rowset Retrieving Results 7 11 Using Block and Scrollable Curs
417. ng columns REFERENCES ref table name referenced columns CREATE VIEW Statement SQL conformance level Core CREATE VIEW viewed table name column identifier column identifier AS query specification SQL Grammar B 5 DELETE Statement Positioned DELETE Statement Positioned SQL conformance level Core ODBC 1 0 SQL conformance level Extended ODBC 2 0 DELETE FROM table name WHERE CURRENT OF cursor name DELETE Statement Searched SQL conformance level Minimum ODBC 2 0 DELETE FROM table name WHERE search condition DROP INDEX Statement SQL conformance level Core DROP INDEX index name DROP TABLE Statement SQL conformance level Minimum DROP TABLE base table name L CASCADE RESTRICT DROP VIEW Statement SQL conformance level Core DROP VIEW viewed table name L CASCADE RESTRICT B 6 INFORMIX CLI Programmer s Manual GRANT Statement GRANT Statement SQL conformance level Core GRANT ALL grant privilege grant privilege ON table name TO PUBLIC user name user name grant privilege DELETE INSERT SELECT UPDATE column identifier column identifier REFERENCES column identifier column identifier INSERT Statement SQL conformance level Minimum INSERT INTO table name column identifier column identifier VALUES insert value insert value SQL conformance level Core INSERT IN
418. ning Connection not open General error Memory allocation failure Function sequence error Option type out of range Driver not capable Description 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 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 DM SQLBrowseConnect was called for the hdbc and returned SQL_NEED_DATA This function was called before SQLBrowseConnect 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 13 159 SQL GetConnectOption Usage For a list of options see SQLSetConnectOption Important When 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 SQL_MAX_OPTION_STRING_LENGTH bytes excluding the null termination byte Depend
419. ning Performance Oriented Applications offers design and coding suggestions that can enhance application perfomance How an Application Uses the INFORMIX CLI Interface An application uses the INFORMIX CLI interface to make a connection to a data source issue SQL statements to a data source process result data dynamically and terminate a connection To interact with a data source 1 Connect to the data source specifying the data source name and any additional information needed to complete the connection Basic Application Steps 4 3 How an Application Uses the INFORMIX CLI Interface 2 Process one or more SQL statements m The application places the SQL text string in a buffer If the statement includes parameter markers it sets the parameter values m Ifthe statement returns a result set the application assigns a cursor name for the statement or allows the driver to assign one m The application submits the statement for prepared or immediate execution m If the statement creates a result set the application can inquire about the attributes of the result set such as the number of columns and the name and type of a specific column It assigns storage for each column in the result set and fetches the results m Ifthe statement causes an error the application retrieves error information from the driver and takes appropriate action 3 End each transaction by committing it or rolling it back 4 Terminate the c
420. nknown this value is set to 0 A character string Y if the maximum row size returned for the SQL_MAX_ROW_SIZE information type includes the length of all SQL_LONGVARCHAR and SQL_LONGVARBINARY columns in the row N otherwise 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 11 of 22 InfoType SQL_MAX_TABLE_NAME_LEN SQL_MAX_TABLES_IN_SELECT SQL_MAX_USER_NAME_LEN SQL_MULT_RESULT_SETS SQL_MULTIPLE_ACTIVE_TXN SQL_NEED_LONG_DATA_LEN SQL_NON_NULLABLE_COLUMNS SQL_NULL_COLLATION 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 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 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 unknown this value is set to 0 A character string Y if the data source supports multiple result sets N if it does not A character string Y if active transactions on multiple connec tions are allowed N if only one co
421. nnected to an OnLine database server the INFORMIX driver supports isolation levels 0 Read Uncommitted 1 Read Committed and 3 Serial izable The default setting is 1 INFORMIX SE supports isolation level 0 Read Uncommitted only The Informix driver also supports an alternative isolation level 1 called cursor stability Your INFORMIX CLI application can use this isolation level by calling SOLSetConnectOption 1040 1 Additionally if transaction logging has not been enabled for your database then transactions are not supported by the driver the driver is always in auto commit mode Each statement is treated as if it is a single transaction The Informix driver also supports page level locking For more information on isolation and lock levels see the Informix Guide to SQL Tutorial INFORMIX CLI Programmer s Manual INFORMIX CLI INFORMIX CLI for UNIX Setting Up INFORMIX CLI System Requirements Setting Environment Variables Adding and Modifying Data Sources Adding a Data Source Required Data Source Configuration Information Optional Data Source Configuration Information Sample Data Source Entry for odbc ini Modifying a Data Source a Connecting to a Data Source Using Dialog Boxes to Connect to a Data Source Using a Connection String to Connect to a Data Source INFORMIX CLI for Windows Setting Up INFORMIX CLI Systm Requirements Setting the INFORMIXDIR Environment Variable Adding and Modi
422. nnection at a time can have an active transaction A character string Y if the data source needs the length of a long data value the data type is SQLLLONGVARCHAR SQL_LONGVARBINARY or a long data source specific data type before that value is sent to the data source N if it does not For more information see SOLBindParameter A 16 bit integer that specifies whether the data source supports non nullable columns SQL_NNC_NULL All columns must be nullable SQL_NNC_NON_NULL Columns may be non nullable the data source supports the NOT NULL column constraint in CREATE TABLE statements A 16 bit integer value that specifies where NULLs are sorted ina list SQL_NC_END NULLs are sorted at the end of the list regardless of the sort order SQL_NC_HIGH NULLs are sorted at the high end of the list SQL_NC_LOW NULLs are sorted at the low end of the list SQL_NC_START NULLs are sorted at the start of the list regardless of the sort order 12 of 22 INFORMIX CLI Function Reference 13 201 SQL GetInfo InfoType Returns SQL_NUMERIC_FUNCTIONS 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
423. not NULL SMALLINT not NULL SQL Get Typelnfo Comments 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 there are no parameters for the data type definition 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 SQL_NO_NULLS if the data type does not accept NULL values SQL_NULLABLE if the data type accepts NULL values SQL_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 TRUE if the data type is a character data type and is case sensitive FALSE if the data type is not a character data type or is not case sensitive 2 of 4 INFORMIX CLI Function Reference 13 221 SQL Get Typelnfo 13 222 Column Name Data Type SEARCHABLE SMALLINT not NULL UNSIGNED_ATTRIBUTE SMALLINT MONEY SMALLINT not NULL AUTO_INCREMENT SMALLINT INFORMIX CLI Programmer s Manual Comments How the data type is used in a WHERE clause SQL_UNSEARCHABLE if the data type cannot be used in a WHERE clause SQL_LIKE_ONLY if the data type can be used in a WHERE clause only with the LIKE predicate SQL_ALL_EXCEPT_LIKE if the data type can be used in a WHERE clause with all comparison op
424. ns SQL_SUCCESS_WITH_INFO DM The buffer szDriverAttributes was not large enough to return the entire list of attribute value pairs so the list was truncated The argument pcbDrovrAttr 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 SQLSTATE 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 cbDrvrAttrMax was less than 0 or equal to 1 DM The value specified for the argument fDirection was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT SQLDrivers 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 If 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 retu
425. ns request translation through SQLSetConnectOption The driver associated with the hdbc specified in SQLSetConnectOption calls the specified shared library to perform translations of all data that flows from the data source to the driver A default translation shared library can be specified in the odbc ini file Syntax BOOL SQLDataSourceToDriver fOption fSqlType rgbValueln cbValueIn rgbValueOut cbValueOutMax pcbValueOut szErrorMsg cbErrorMsgMax pcbErrorMsg Translation Shared Library Function Reference 15 3 SQLDataSourceToDriver Type Argument UDWORD fOption SWORD fSqlType PTR rgbValueIn SDWORD cbValuelIn PTR rgbValueOut SDWORD cbValueOutMax 15 4 INFORMIX CLI Programmer s Manual Use Input Input Input Input Output Input The SQLDataSourceToDriver function accepts the following arguments Description Option value The ODBC SQL data type This argument tells the driver how to convert rgbValueln to a form acceptable by the application This must be one of the following values SQL_CHAR SQL_DATE SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_REAL SQL_SMALLINT SQL_TIMESTAMP SQL_VARCHAR For information on ODBC SQL data types see Appendix C For infor mation on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 Value to translate Length of rgbValueln Result of the translation The translation shared
426. ns That Define Cursor Behavior The following table lists the types of cursor behavior you can set as default connection options for a data source If you do not set a new default the default setting that is listed in the table will apply Attribute Description Cursor Behavior A value that determines the type of behavior of the cursors after the transaction ends m 0 Closed This is the default setting m 1 Preserve Choose this setting to hold the cursors at the current position when the transaction ends This setting might impact the performance of your database operations Enable A value that determines if the driver provides scrollable cursors Scrollable m 0 Noscrollable cursors This is the default setting Cursors m 1 Enable scrollable cursors If this value is set SELECT lists must not include long columns such as SQLLLONGVARCHAR or SQL_LONGVARBINARY INFORMIX CLI 2 19 Adding a Data Source Attribute Options That Define Operation Behavior The following table lists the types of operation behavior you can set as default connection options for a data source If you do not set a new default tlhe default setting that is listed in the table will apply Description Protocol Type Windows 3 1 Yield Proc 2 20 INFORMIX CLI Programmer s Manual The protocol used to communicate with the database server Values can be IPX TCP IP or PIPE for Windows 3 1 For Windows NT and Windows 95 values c
427. ns information about a single table as a standard result set ordered by NON_UNIQUE TYPE INDEX_QUALIFIER INDEX_NAME and SEQ_IN_INDExX The result set combines statistics information for the table with information about each index The following table lists the columns in the result set Important SQLStatistics might not return all indexes Applications can use any valid index regardless of whether it is returned by SQLStatistics INFORMIX CLI Function Reference 13 307 SQL Statistics 13 308 options Column Name TABLE_QUALIFIER TABLE_OWNER TABLE_NAME NON_UNIQUE INFORMIX CLI Programmer s Manual Data Type VARCHAR 128 VARCHAR 128 VARCHAR 128 not NULL SMALLINT 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 SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SQL_ MAX_COLUMN_NAME_LEN 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 identifier of the table t
428. nt in SOLBind Parameter is SQL_DEFAULT_PARAM If a procedure call includes parameter markers including the parameter marker for the return value the application must bind each marker by calling SQLBindParameter prior to calling the procedure Important For some data sources parameter cannot be a literal value For all data sources it can be a parameter marker For maximum interoperability applications should always use a parameter marker for parameter If an application specifies a return value parameter for a procedure that does not return a value the driver sets the pcbValue buffer specified in SOLBind Parameter for the parameter to SQL_NULL_DATA If the application omits the return value parameter for a procedure which returns a value the driver ignores the value returned by the procedure If a procedure returns a result set the application retrieves the data in the result set in the same manner as it retrieves data from any other result set For example each of the following statements uses the procedure EMPS_IN_PROJ to create the same result set of names of employees working on a project The first statement uses the escape clause syntax The second statement uses the shorthand syntax vendor Microsoft product ODBC call EMPS_IN_PROJ call EMPS_IN_PROJ To determine if a data source supports procedures an application calls SOLGetInfo with the SQL_PROCEDURES information type To retrieve a list of th
429. nt one that is it cannot specify different values 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 When SQL_NEED_DATA returns and the browse result connection string is unchanged an error has occurred and the application must call SOLError 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 Browsing with SQLBrowseConnect on page 5 9 Code Example In the following example an application calls SQLBrowseConnect repeatedly Each time SOLBrowseConnect returns SOQL_NEED_DATA it passes back information about the data that it needs in szConnStrOut The application passes szConnStrOut to its rout
430. ntaining the name of the trace file The default value of the SQL_OPT_TRACEFILE option is specified with the TraceFile keyname in the ODBC section of the odbc ini file For more infor mation see ODBC Options on page 1 10 SQL_PACKET SIZE 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 2 of 4 INFORMIX CLI Function Reference 13 277 SQL SetConnectOption fOption SQL_QUIET_MODE SQL_TRANSLATE_DLL SQL_TRANSLATE_OPTION vParam Contents 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 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 displayed by SOLDriverConnect A null terminated character string that contains the name of a shared library that contains the functions SQLDriverToDat
431. nted Applications 11 13 Use SQLSpecialColumns to Determine the Optimal Set of Columns 11 14 Besides making the code more maintainable positioned updates 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 not needed If the row must be located the server typically has an internal pointer to the row available for example ROWID Use SQLSpecialColumns to Determine the Optimal Set of Columns Use SQLSpecialColumns to determine the optimal set of columns to use in the WHERE clause for updating data Many times pseudo columns provide the fastest access to the data and these columns can only be determined 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 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 Consider the following rc SQLExecDirect hstmt SELECT first_name last_name ssn address city state zip FROM emp SQL_NTS fetchdata rc SQLExecDirect hstmt
432. ny 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 pattern include it twice m All other characters represent themselves 13 8 INFORMIX CLI Programmer s Manual SQLAl locConnect 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 a table identifier MY_TABLE returns as the result of a call to SOLTables and an application wants to retrieve a list of c
433. o 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 identifier of the table to which the statistic or index applies Indicates whether the index prohibits duplicate values TRUE if the index values can be nonunique FALSE if the index values must be unique NULL is returned if TYPE is SQL_TABLE_STAT 1 of 3 Column Name INDEX_QUALIFIER INDEX_NAME TYPE SEQ_IN_INDEX COLUMN_NAME Data Type VARCHAR 128 VARCHAR 128 SMALLINT not NULL SMALLINT VARCHAR 128 SQL Statistics Comments 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 identifier NULL is returned if TYPE is SQL_TABLE_STAT Type of information being returned SQL_TABLE_STAT indicates a statistic for the table SQL_INDEX_CLUSTERED indicates a clustered index SQL_INDEX_HASHED indicates a hashed index SQL_INDEX_OTHER indicates another type of index Column seque
434. o your Informix documentation set For a complete listing of compatible database servers see the release notes for INFORMIX CLI INFORMIX CLI enables you to compose queries send them to the database server and view the results that the database server returns You can use DB Access to test and verify all the SQL statements described in this manual Demonstration Database The DB Access utility which is provided with your Informix database server products includes a demonstration database that contains information about a fictitious wholesale sporting goods distributor The sample command files that make up a demonstration application are also included Most examples in this manual are based on the stores7 demonstration database The stores7 database is described in detail and its contents are listed in Appendix A of the Informix Guide to SQL Reference For the script and the instructions that you use to install the demonstration database on your database server refer to your Informix database server documentation INFORMIX CLI Programmer s Manual New Features of This Product New Features of This Product This section highlights the major new features implemented in Version 2 5 of INFORMIX CLI Support for Windows 95 and Windows NT INFORMIX CLI now supports application programming for both Windows NT and Windows 95 environments Global Language Support GLS The GLS feature lets Informix Version 7 2 products handle
435. ocEnv failed Driver SQLAllocConnect failed Driver SQLSetConnectOption failed No data source or driver specified dialog prohibited Dialog failed Unable to load translation shared library Can be returned from SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLExecDirect SQLExecute SQLPrepare SQLCancel SQLBrowseConnect SQLConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLDriverConnect SQLDriverConnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLSetConnectOption 6 of 13 INFORMIX CLI Error Codes A 7 SQLSTATEs IM010 IM011 IM012 IM013 S0001 S0002 S0011 S0012 S0021 S0022 S1000 S1001 A 8 INFORMIX CLI Programmer s Manual Error 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 SQLDriverConnect SQLBrowseConnect SQLDriverConnect SQLBrowseConnect SQLDriverConnect All ODBC functions SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare SQLExecDirect SQLPrepare
436. of the following values SQL_CHAR SQL_DATE SQL_DECIMAL SQL_DOUBLE SQL_INTEGER SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_REAL SQL_SMALLINT SQL_TIMESTAMP SQL_VARCHAR If the data type cannot be deter mined the driver returns 0 For more information see Appendix C For information on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 2 of 3 Type Argument UDWORD FAR pcbColDef SWORD FAR pibScale SWORD FAR pfNullable Return Codes Use Output Output Output SQLDescribeCol Description 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 C 8 The scale of the column on the data source If the scale cannot be determined or is not applicable the driver returns 0 For more information on scale see Precision Scale Length and Display Size on page C 8 Indicates whether the column allows one of the following values SQL_NO_NULLS The column does not allow NULL values SQL_NULLABLE The column allows NULL values SQL_NULLABLE_UNKNOWN The driver cannot determine if the column allows NULL values 3 of 3 SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 87 SQ_DescribeCol SQLSTATE 01000 01004 24000
437. of statements or a procedure mixes other SQL 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 SOQLCancel Fetching a block of data or scrolling through a result set SQLExtendedFetch Fetching a row of data SQLFetch Fetching part or all of a column of data SQLGetData INFORMIX CLI Function Reference 13 227 SQL NativeSq 13 228 Syntax cbSqlStrMax SQLNative Sql SQLNativeSql returns the SQL string translated by the driver RETCODE SQLNativeSql hdbc szSqlStriIn cbSqlStriIn szSqlStr pcbSqlStr The SQLNativeSql function accepts the following arguments Return Codes INFORMIX CLI Programmer s Manual Type Argument Use Description HDBC hdbc Input Connection handle UCHAR FAR szSqlStrIn Input SQL text string to be translated SDWORD cbSqlStrIn Input Length of szSqlStrIn text string UCHAR FAR szSqlStr Output Pointer to storage for the trans lated SQL string SDWORD cbSqlStrMax Input Maximum length of the szSqlStr buffer SDWORD FAR pcbSqlStr Output The total number of bytes excluding the null termination byte available to return in szSqlStr If the number of bytes available to return is greater than or equal to cbSqI
438. of table types to match SWORD cbTableType Input Length of szTableType 2 of 2 Return Codes SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLTables returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SOLError The following table lists the SQLSTATE values commonly returned by SQLTables 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 08S01 Communication The communication link between the driver link failure and 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 1 of 2 INFORMIX CLI Function Reference 13 319 SQL Tables SQLSTATE 1001 S1008 S1010 S1090 S1C00 S1T00 Error Memory allocation failure Operation canceled Function sequence error
439. old John Smith do retcode SQLFetch hstmtSelect while retcode SQL_SUCCESS retcode SQL_SUCCESS_WITH_INFO amp amp 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 Programmer s Manual Related Functions SQLSetParam For information about See Executing an SQL statement SQLExecDirect Executing a prepared SQL statement SQLExecute Returning a cursor name SOQLGetCursorName Setting cursor scrolling options SQLSetScrollOptions SQLSetParam Deprecated SQLBindParameter replaces the ODBC 1 0 function SQLSetParam For more information see SOLBindParameter SQLSetScrollOptions In ODBC 2 0 the SQL_CURSOR_TYPE SQL_CONCURRENCY SQL_KEYSET_SIZE and SQL_ROWSET_SIZE options for SOLSetStmtOption superseded SQLSetScrollOptions INFORMIX CLI 2 5 applications should not call this function INFORMIX CLI Function Reference 13 285 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 SQLSetConnectOption Syntax RETCODE SQLSetStmtOption hstmt fOption vParam The SQLSetStmtOption function accepts
440. olumns 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 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 can be returned by the data source the driver substitutes that value and returns SQLSTATE 01502 Option value changed A 32 bit integer value that specifies whether the driver does not scan SQL strings for escape clauses SQL_NOSCAN_OFF The driver scans SQL strings for escape clauses the default SQL_NOSCAN_ON The driver does not scan SQL strings for escape clauses Instead the driver sends the statement directly to the data source INFORMIX CLI does not support this option The default is set to 0 no time out 4 of 5 13 292 INFORMIX CLI Programmer s Manual fOption SQL_RETRIEVE_DATA SQL_ROWSET_SIZE SQL_SIMULATE_CURSOR UNSUPPORTED SQL_USE_BOOKMARKS UNSUPPORTED SQL SetStmtOption vParam Contents A 32 bit integer value SQL_RD_ON SQLExtendedFetch retrieves data after it positions the cursor to the specified location This is the default SQL_RD_OFF SQLExtendedFetch does not retrieve data after it positions the cursor By setting SQL_RETRIEVE_DATA to SQL_RD_OFF an applic
441. olumns for MY_TABLE using SOLColumns SOLColumns 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 SQLAIlocConnect SQLAIlocConnect allocates memory for a connection handle within the environment identified by henv Syntax RETCODE SQLAIlocConnect henv phdbc The SQLAI locConnect function accepts the following arguments Type Argument Use Description HENV henv Input Environment handle HDBC FAR phdbc Output Pointer to storage for the connection handle INFORMIX CLI Function Reference 13 9 SQLAllocConnect Return Codes SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE If SOLAllocConnect returns SQL_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_HSTMT respectively Diagnostics When SQLAIlocConnect returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLAIloc Connect and explain
442. on For example 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 in INFORMIX CLI functions are unsigned applications that pass string objects to INFORMIX CLI functions without casting them receive compiler warnings 13 6 INFORMIX CLI Programmer s 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 names Diagnostics The diagnostics provided with each function list SQLSTATE values that might be returned for the function by the driver manager or a driver The driver can however return additional SQLSTATE 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 SQL_SUCCESS_WITH_INFO Class values other than 01 except for the class IM indicate a
443. on Syntax RETCODE SQLPrepare hstmt szSqlStr cbSqlStr The SQLPrepare 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_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE 13 244 INFORMIX CLI Programmer s Manual Diagnostics SQLPrepare When SQLPrepare returns SOQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SOLSTATE values commonly returned by SOLPrepare 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 08S01 21501 21502 22005 24000 34000 37000 Error 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 Syntax error or access violation 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 The argument sz
444. on 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 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 SQL_MAX_MESSAGE_LENGTH 1 pebErrorMsg Output Pointer to the total number of bytes excluding the null termination 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 SQL_NO_DATA_FOUND SQL_ERROR or SQL_INVALID_HANDLE 13 108 INFORMIX CLI Programmer s Manual SQLError Diagnostics SQLError does not post error values for itself SQLError returns SQL_NO_DATA_FOUND when it cannot retrieve any error information in which case szSqlState equals 00000 If SQLError cannot access error values for any reason that would normally return SQL_ERROR SQLError returns SQL_ERROR but does not post any error values If the buffer for the error message is too short SQLError
445. on was SQL_CURSOR_FORWARD_ONLY and the value of argument fFetchType was not SQL_FETCH_NEXT 3 of 4 SQLSTATE S1107 S1C00 S1T00 Usage Error Row value out of range Driver not capable Time out expired SQLExtendedFetch Description The value specified with the statement option SQL_CURSOR_TYPE was 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 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 in SQLBindCol 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 The time out period expired before the data source returned the result set The time out period is set through SOLSetStmtOption SQL_QUERY_TIMEOUT 4 0f 4 SQLExtendedFetch returns one rowset 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 rowset by calling SQLSet StmtOption with the SQL_ROWSET_SIZE statement option INFORMIX CLI Function Reference 13 131 SQLExtendedFetch
446. onding parameter marker For further information concerning scale see Precision Scale Length and Display Size on page C 8 1 of 2 Type Argument Use PTR rgbValue Input Output cbValueMax Input SDWORD SDWORD FAR pcbValue Input Output Return Codes SQLBindParameter Description A pointer to a buffer for the data of the parameter For more information see tgbValue Argument on page 13 31 Maximum length of the rgb Value buffer For more information see cbValueMax Argument on page 13 32 A pointer to a buffer for the length of the parameter For more information see pcbValue Argument on page 13 33 2 of 2 SQL_SUCCESS SQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE Diagnostics When SQLBindParameter returns SOL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SOLSTATE values commonly returned by SQLBind Parameter 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 SQLSTATE value is SQL_ERROR unless noted otherwise INFORMIX CLI Function Reference 13 25 SQL BindParameter 13 26 SQLSTATE Error 01000 General warning 07006 Restricted data type attribute violation 1000 General error 1001 Memory allocation failure 1003 Program type
447. onnect SQLGetTypelInfo SQLNativeSql SQLError SQLParamData SQLNumParams SQLExecDirect SQLPutData SQLParamOptions SQLExecute SQLSetConnectOption SQLPrimaryKeys SQLFetch SQLSetStmtOption SOLProcedureColumns SQLFreeConnect SQLSpecialColumns SQLProcedures SOLFreeEnv SQLStatistics SOLSetPos SQLFreeStmt SQLTables SQLSetScrollOptions SOLGetCursorName SQLTablePrivileges SQLNumResultCols SQLPrepare 1 of 2 Overview of INFORMIX CLI 1 13 SQL Conformance Level of INFORMIX CLI Core Level Functions Level 1 Functions Level 2 Functions SQLRowCount SQLSetCursorName SQLTransact 2 of 2 SQL Conformance Level of INFORMIX CLI The ODBC SQL conformance standard includes 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 and REVOKE m Data Manipulation Language DML statements full SELECT INSERT UPDATE SEARCHED and DELETE SEARCHED m Expressions simple such as A gt B C subquery set functions such as SUM and MIN m Data types CHAR VARCHAR LONG VARCHAR DECIMAL NUMERIC SMALLINT INTEGER REAL DOUBLE PRECISION In addition INFORMIX CLI supports the following ODBC extensions to SQL grammar m DML statements outer joins positioned UPDATE positioned DELETE SELECT FOR UP
448. onnection when it finishes interacting with the data source Figure 4 1 shows the function calls that a basic application makes to connect to a data source process SQL statements and disconnect from the data source Depending on your needs your application can call other functions 4 4 NFORMIX CLI Programmer s Manual How an Application Uses the INFORMIX CLI Interface Figure 4 1 A Sample Listing of Function Calls Made SQLAllocEnv by an INFORMIX CLI Application SQLAllocConnect SQL Connect SQLAllocSimt Process SQL Statements Receive Results Y SQLFreeStmt CLOSE option DROP option SQL Disconnect SQLFreeConnect SQLFreeEnv Basic Application Steps 4 5 Connecting to a Data Source Description of Data Sources a 2 1 2 ww ee 53 Initializing the Environment 2 ee ee ee 5 4 Allocating a Connection Handle 2 2 we 8 Connecting toa Data Source As ity Ay tere chy A a ay Aor oe BORO Connecting with SQLConnect a ey A tee EOD Connecting to a Data Source with SQLDriverConnect ee ee D6 Connection Browsing with SQLBrowseConnect 59 Translating Data ew ee 5 9 Related Functions ee B10 5 2 INFORMIX CLI Programmer s Manual his chapter describes how to establish a connection to a data source Description of Data Sources A data source consists of the data that a user wants to access its associated DBMS the platfo
449. ony DROP INDEX 5 1 6 DROP TABLE 5 1 7 DROP VIEW 5 1 8 GRANT 5 1 9 REVOKE Comparison Between INFORMIX CLI and Embedded SQL D 5 Data Manipulation Statements D 6 INFORMIX CLI Programmer s Manual The following table lists data manipulation statements 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 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 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 SOLExecute When a SELECT statement is specified a cursor is opened implicitly by SQOLExecute or SQLExecDirect Not supported Driver generated cursor name can be obtained by calling SQLGetCursorName None Dynamic SQL Statements The following table lists dynami
450. 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 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 Table type identifier one of the following TABLE VIEW SYSTEM TABLE GLOBAL TEMPORARY LOCAL TEMPORARY ALIAS SYNONYM or a data source specific type identifier A description of the table SQL Tables Code Example For a code example of a similar function see SQLColumns Related Functions For information about See Assigning storage fora column ina result SQLBindCol set Canceling statement processing SQLCancel Returning privileges for a column or SQLColumnPrivileges columns Returning the columns ina table or tables SQLColumns Fetching a block of data or scrolling SQLExtendedFetch through a result set Fetching a row of data SQLFetch Returning table statistics and indexes SalStatistics Returning privileges for a table or tables SQLTablePrivileges INFORMIX CLI Function Reference
451. or execution in the following ways m Prepared statements call SQLPrepare and then call SQLExecute m Direct statements call SQLExecDirect 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 Appendix D Executing SQL Statements 6 5 Preoared Execution 6 6 Prepared Execution Prepare a statement before you execute it if either of the following situations 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 it executes the statement Network traffic is minimized 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_LAUTOCOMMIT connection option can cause the data source to delete the access plans for all hstmts on an hdbc For more information see SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR on page 13
452. or the argument icol was 0 The value specified for the argument icol was greater than the number of columns in the result set 1 of 2 SQLDescribeCol SQLSTATE Error Description S1008 Operation The function was called but before it completed canceled execution SQLCancel was called on the hstmt from a different thread in a multithreaded application S1010 Function DM The function was called prior to calling sequence 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 stringor DM The value specified for argument cbCol buffer length NameMax 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 SQLSTATE that SQLPrepare or SOLExecute returns when SQLDescribeCol is called after SQLPrepare and before SQLExecute depending on when the data source evaluates the SQL statement associated with the hstmt Usage An application typically calls SQLDescribeCol after a call to SQLPrepare and before or after the associated call to SQLExecute An application can also call SQLDescribeCol after a call to SQLExecDirect SQLDescribeCol retrieves the column name type and l
453. ords 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 the driver manager and the driver can each prompt the user for connection information Once a connection is established SQLDriverConnect returns the completed connection string The application can use this string for subsequent connection requests Syntax RETCODE SQLDriverConnect hdbc hwnd szConnStrIn cbConnStriIn szConnStrOut cbConnStrOutMax pcbConnStroOut fDriverCompletion The SQLDriverConnect function accepts the following arguments INFORMIX CLI Function Reference 13 93 SQL DriverConnect Type Argument HDBC hdbc HWND hwnd UCHAR FAR szConnStrIn SWORD cbConnStrIn UCHAR FAR szConnStrOut SWORD cbConnStrOutMax SWORD FAR pebConnStrOut UWORD fDriverCompletion 13 94 INFORMIX CLI Programmer s Manual Use Input Input Input Input Output Input Output Input Description Connection handle 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 A full connection string see Connection Strings on page 13 99 a partial connection string or an empty string Length of szConnStrIn Pointer to storage for the completed conne
454. ore 8 of 11 Hements Used in SQL Statements SQL Conformance Element Level scalar function function name argument list Extended The definitions for the non terminals function name and function name argument list are derived from the list of scalar functions in Appendix F Scalar Functions scale unsigned integer Core search condition boolean term OR search condition Minimum seconds fraction unsigned integer Extended seconds value digit digit Extended select list select sublist select sublist Minimum select sublist expression Minimum select sublist expression AS column alias Core table name correlation name set function reference COUNT distinct function all function Core sort specification unsigned integer column name ASC DESC Minimum SQL esc vendor clause VENDOR Microsoft PRODUCT ODBC Extended sub query Core SELECT ALL DISTINCT select list FROM table reference list WHERE search condition GROUP BY column name column name HAVING search condition table identifier user defined name Minimum table name table identifier Minimum table name table identifier Core owner name table identifier qualifier name qualifier separator table identifier qualifier name qualifier separator owner name table identifier The third syntax is valid only if the data source does not support owners 9 of
455. ormation about what values are valid in a SOQL_C_DATE structure see Extended C Data Types on page C 5 When date C data is converted to character SQL 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 C to SQL Time The time ODBC C data type is SQL_C_TIME Data Types C 33 C to SQL Time Stamp C 34 The following table shows the ODBC SQL data types to which time C data can be converted For an explanation of the columns and terms in the table see Converting Data from C to SQL Data Types on page C 24 fSqlType Test SQLSTATE SQL_CHAR Column length 8 N A SQL_VARCHAR SQL_LONGVARCHAR Column length lt 8 22003 Data value is not a valid time 22008 SQL_TIMESTAMP Data value is a valid time N A Data value is not a valid time 22008 a The date portion of the time stamp is set to the current date and the fractional seconds portion of the time stamp is set to zero For information about what values are valid in a SOL_C_TIME structure see Extended C Data Types on page C 5 When time C data is converted to character SQL data the resulting character data is in the hh mm ss format The value pointed to by the pcbValue ar
456. ors 7 12 For example assume a result set has 1000 rows and uses a mixed cursor with a keyset size of 100 and a rowset size of 10 When the cursor opens the driver depending on the implementation saves keys for the first 100 rows and retrieves data for the first 10 rows If another user deletes row 11 and the cursor then scrolls to row 11 the cursor detects a hole in the result set the key for row 11 is in the keyset but the data is no longer in the result set A keyset driven cursor behaves the same way However if another user deletes row 101 and the cursor then scrolls to row 101 the cursor does not detect a hole the key for the row 101 is not in the keyset Instead the cursor retrieves the data for the row that was originally row 102 A dynamic cursor behaves the same way Specifying the Cursor Type To specify the cursor type an application calls SOLSetStmtOption with the SQL_CURSOR_TYPE option The application can specify a cursor that scrolls forward a static cursor a dynamic cursor a keyset driven cursor or a mixed cursor If the application specifies a mixed cursor it also specifies the size of the keyset that the cursor uses To use the ODBC cursor library an application calls SQLSetConnectOption with the SQL_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
457. ourtrces Specifies a connection string that contains a driver description The driver manager 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 The driver manager displays a dialog box from which the user selects a data source name The driver manager then retrieves the full path of the driver shared library associated with the data source The driver manager then loads the driver shared library and passes the SQLDriverConnect arguments to it After the driver connects to the data source it returns the connection infor mation to the application The application might store this information for future use If the application specifies a data source name that is not in the odbc ini the driver manager 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 the driver manager returns an error Connecting to a Data Source 5 7 Connecting to a Data Source with SQLDriverConnect When the application calls SQLDriverConnect and requests that the user be prompted for information the driver manager displays the SQL Data Sources dialog box as Figure 5 1 illustrates Figure 5 1 The SQL Data
458. out of range 1004 SQL data type out of range 1009 Invalid argument value S1010 Function sequence error S1090 Invalid string or buffer length INFORMIX CLI Programmer s Manual Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The data value identified by the fCType argument cannot be converted to the data type identified by the fSq Type 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 The value specified by the argument fCType was not a valid data type or SQL_C_DEFAULT DM The value specified 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 DM The argument rgb Value 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 DM The value specified for the argument cbValueMax was less than 0 1 of 2 SQLSTATE 1093 1094 S1104 S1105 S1C
459. pacted A number of areas can slow performance This section aims to identify the impacted performance area and provide solutions to increase performance levels Performance Issue Action Network communication is slow The process of evaluating complex SQL queries on the DBMS server might be slow and might reduce concurrency Excessive calls from the application to the driver decrease performance Disk I O is slow 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 Designing Performance Oriented Applications 11 3 Connecting to a Data Source 11 4 Connecting to a Data Source Connection management is extremely important to application performance Connecting to a data source is very expensive and should be avoided after you establish an initial connection Designers should optimize applications by connecting once and using multiple statement handles instead of performing multiple connections Some ODBC applications are designed so that they call informational gathering routines that have no record of already attached connection handles For example some applications establish a connection and then call a routine in a separate DLL or shared library that re attaches and gathers up front information about the driver to be used later in the application Although gathering driver informatio
460. parameters or columns 2 of 3 INFORMIX CLI Function Reference 13 265 SQL PutData 13 266 SQLSTATE S1009 Error Invalid argument value Description DM The argument rgbValue was a null pointer and the argument cbValue was not 0 SQL_DEFAULT_PARAM or SQL_NULL_DATA S1010 Function sequence error 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 S1090 Invalid string or buffer length The argument rgbValue was not a null pointer and the argument cbValue was less than 0 but not equal to SQL_NTS or SQL_NULL_DATA S1T00 Usage of range Time out expired INFORMIX CLI Programmer s Manual 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 3 of 3 For an explanation of how data at execution parameter data passes when a statement executes see Passing Parameter Values on page 13 34 For an explanation of how data at execution column data is updated or added see SOLSetScrollOptions on page 13 285 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 c
461. pare Setting a cursor name SOQLSetCursorName Setting cursor scrolling options SQLSetScrollOptions 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 SQLGetData 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 SQL_LONGVARBINARY or SQL_LONGVARCHAR columns Syntax RETCODE SQLGetData hstmt icol fCType rgbValue cbValueMax pcbValue The SQLGetData 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 1 of 3 13 164 INFORMIX CLI Programmer s Manual Type SWORD PTR SDWORD Argument fCType rgbValue cbValueMax Use Input Output Input SQ_GetData Description The C data type of the result data This must be one of the following values SQL_C_BINARY SQL_C_BIT SQL_C_CHAR SQL_C_DATE SQL_C_DEFAULT SQL_C_DOUBLE SQL_C_FLOAT SQL_C_SLONG SQL_C_SSHORT SQL_C_STINYINT SQL_C_TIME SQL_C_TIMESTAMP SQL_C_ULONG SQL_C_USHORT SQL_C_UTINYINT SQL_C_DEFAULT specifies that
462. pe description SQL_ACCESSIBLE_PROCEDURES SQL_ACCESSIBLE_TABLES SQL_ACTIVE_CONNECTIONS SQL_ACTIVE_STATEMENTS 13 190 INFORMIX CLI Programmer s Manual Scalar Function Information The following values of fInfoType return information about the scalar functions supported by the data source and the driver 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 alphabetically lists each information type and its Returns A character string Y if the user can execute all procedures returned by SQLProcedures N if procedures might be returned that the user cannot execute A character string Y if the user is guaranteed SELECT privi leges to all tables returned by SOLTables N if tables might be returned that the user cannot access A 16 bit integer value that specifies the maximum number of active hdbcs that the driver can support This value can reflect a limitation imposed by either the driver or the data source If no limit is specified or the limit is unknown this value is set to 0 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 imposed by either the driver or the
463. pe Before the driver sends data to the data source it converts the data from the specified C data type For more information about data types see Appendix C 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 3 8 INFORMIX CLI Programmer s Manual Function Return Codes When the function returns SQL_SUCCESS_WITH_INFO or SQL_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 8 Retrieving Status and Error Information Guidelines for Calling INFORMIX CLI Functions 3 9 Basic Application Steps How an Application Uses the INFORMIX CLI Interface 4 3 4 2 INFORMIX CLI Programmer s Manual his chapter describes how an application uses the INFORMIX CLI interface to interact with a data source Chapters 5 through 9 discuss the individual actions that an application performs as it interacts with a data source and Chapter 10 Constructing an INFORMIX CLI Application provides code examples of such basic applications Chapter 11 Desig
464. pecified 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 combination of the current settings of the SQL_CONCURRENCY and SQL_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 requested result set The time out period is set through SQLSetStmtOption SQL_QUERY_TIMEOUT 3 of 3 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 SQLGetInfo 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 it is returned by SQLProcedures 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 13 258 INFORMIX CLI Programmer s Manual SQLProcedures The lengths of VARCHAR columns shown in the table are maximums the actual len
465. pendix C For infor mation on how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 217 SQL GetTypelnfo 13 218 INFORMIX CLI Programmer s Manual When SQLGetTypelnfo returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLGetTypelnfo 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 SQLSTATE value is 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 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 The value specified for the argument fSqlType was in the block of numbers reserved for ODBC SQL data type indicators but was not a va
466. propriate 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 autocommit or manual commit mode SQL_AUTOCOMMIT_OFF The driver uses manual commit mode and the application must explicitly commit or roll back transactions with SQOLTransact 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 hstmts on an hdbc each time a statement is committed autocommit mode can cause this to happen after each statement is executed For more information see the SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR on page 13 192 INFORMIX CLI does not support this option INFORMIX CLI does not support this option 1 of 4 13 276 INFORMIX CLI Programmer s Manual SQL SetConnectOption fOption vParam Contents SQL_ODBC_CURSORS A 32 bit option specifying how the driver manager uses the ODBC cursor library SQL_CUR_USE_IF_NEEDED The driver manag
467. ption 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 Can be returned from SQLGetFunctions SQLGetInfo SQLSpecialColumns SQLSpecialColumns SQLSpecialColumns SQLStatistics SolStatistics SQLDataSources SQLDrivers SQLBindParameter SQLBindParameter SQLExtendedFetch SQLExtendedFetch SQLParamOptions SQLSetScrollOptions SQLSetScrollOptions SQLExecute SQLExecDirect SQLGetData SQLGetStmtOption SQLDriverConnect 11 of 13 SQLSTATEs 1111 S1C00 Error Invalid bookmark value Driver not capable Can be returned from SQLExtendedFetch SQLBindCol SQLBindParameter SQLColAttributes SQLColumnPrivileges SQLColumns SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLGetConnectOption SQLGetData SQLGetInfo SQLGetStmtOption SQLGetTypelInfo SQLPrepare SQLPrimaryKeys SQLProcedures SQLSetConnectOption SQLSetScrollOptions SQLSetStmtOption SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables SQLTransact 12 of 13 INFORMIX CLI Error Codes A 13 A 14 SQLSTATEs S1T00 INFORMIX CLI Programmer s Manual Error Time out expired Can be returned from SQLBrowseConnect SQLColAttributes SQLColumnPrivileges SQLColumns SQLConnect SQLDescribeCol SQLDriverConnect SQLExecDirect SQLExecute SQLExtend
468. qlStr contained a CREATE INDEX statement and one or more of the column names specified in the column list did not exist The argument szSqlStr contained a GRANT or REVOKE statement and a specified column name did not exist The argument szSqlStr contained a SELECT DELETE INSERT or UPDATE statement and a specified column name did not exist The argument szSqlStr 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 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 3 of 4 INFORMIX CLI Function Reference 13 247 SQLPreoare SQLSTATE Error Description 1008 Operation The function was called but before it canceled completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application S1009 Invalid argument DM The argument szSqlStr was a null pointer value S1010 Function DM SQLExecute or SQLExecDirect was called sequence 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 argument cbSqlStr was le
469. quires a Data Source Specification section Use the following format for Data Source Specification entries data_source_name Driver driver_path Database database_name keyword attribute data_source_name is the name of the data source as specified in the ODBC Data Sources section of your odbc ini file driver_path is the full path to your driver database_name is the name of the OnLine or SE database that the data source accesses The name can include the Informix database server qualifier attribute specifies the value for the keyword Fora list of the keywords that the INFORMIX CLI driver for UNIX supports see Optional Data Source Config uration Information on page 2 6 INFORMIX CLI 2 9 Sample Data Source Entry for odbe ini The required fields in this section are data_source_name and driver_path Database is a keyword that is used to define optional connection information The database_name that you enter becomes the default data source connection When the database attribute is available on a database server different from the database server identified by the INFORMIXSERVER environment variable the database attribute can be specified as follows Database database_name server_name Important The section name for the Data Source Specification must match the data source name listed in the ODBC Data Sources section of your odbc ini file For example the entry for INFORMIX OnLine Dynamic Server Version
470. r 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 SQL_MAX_DSN_LENGTH characters 2 of 3 INFORMIX CLI Function Reference 13 41 SQL BrowseConnect SQLSTATE IM011 IM012 S1000 S1001 S1090 S1T00 Usage 13 42 Error Driver name too long DRIVER keyword syntax error General error Memory allocation failure Invalid string or buffer length Time out expired INFORMIX CLI Programmer s 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 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 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
471. r Manual describes how to invoke the DB Access utility to access modify and retrieve information from Informix database servers m When errors occur you can look them up by number and learn their cause and solution in the Informix Error Messages manual If you prefer you can look up the error messages in the on line message file that is described in Error Message Files later in this Introduction and in the Introduction to the Informix Error Messages manual On Line Documentation Several different types of on line documentation are available m On line error messages m Release notes and documentation notes Error Message Files Informix software products provide ASCII files that contain all of the Informix error messages and their corrective actions 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 See the Introduction to the Informix Error Messages manual for a detailed description of these scripts Introduction 13 Related Reading 14 On Line File Documentation notes Release notes INFORMIX CLI Programmer s Manual Release Notes and Documentation Notes In addition to the Informix set of manuals the following on line files located in the INFORMIXDIR release en_us 0333 directory might supplement the information in this manual Purpose Describes features that are not covered i
472. r an ODBC SQL data type that is not shown in the table for a given C data type then SQLBindParameter returns SQLSTATE 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 ODBC C data type to the driver specific SQL data type then SQLBindParameter returns SQLSTATE 1C00 Driver not capable If the rgb Value and pcbValue arguments specified in SQLBindParameter are both null pointers then that function returns SOLSTATE 1009 Invalid argument value Although it is not shown in the tables an application sets the value pointed to by the pcbValue argument of SQLBindParameter or the value of the cbValue argument to SQL_NULL_DATA to specify a NULL SQL data value The application sets these values to SQL_NTS to specify that the value in rgbValue is a null terminated string 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 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 C 8 m Number of digits is the number of characters that represent a number including the minus sign decimal point and exponent if needed m Wo
473. r rows in the keyset the driver does not save data outside the keyset and cannot compare the newly retrieved data to anything Important The Informix driver cannot detect changes to data The number of elements must equal the number of rows in the rowset as defined by the SQL_ROWSET_SIZE statement option 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 For keyset mixed and dynamic cursors if a key value is updated the row of data is considered to have been deleted and a new row is added INFORMIX CLI Function Reference 13 139 SQLExtendeaFetch 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 there is no need to request column wise binding with SQLSetStmtOption as in the row wise binding example However the application does call SQLSetStmtOption to specify the number of rows in the rowset 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
474. rams returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLNumParams 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 SQLSTATE value is SQL_ERROR unless noted otherwise INFORMIX CLI Function Reference 13 231 SQL NumParams 13 232 SQLSTATE Error 01000 General warning 1000 General error 1001 Memory allocation failure S1008 Operation canceled S1010 Function sequence error S1T00 Time out expired Usage Params sets pcpar to 0 INFORMIX CLI Programmer s Manual 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 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 The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application DM The function was called prior to calling SQLPrepare or SQLExecDirect for the hstmt DM SQLExecute orSQLExecDirect was called for the hstm
475. rds in italics represent elements of the ODBC SOL grammar For the syntax of grammar elements see Appendix B INFORMIX CLI Programmer s Manual C to SQL Character C to SQL Character The character ODBC C data type is SQL_C_CHAR The following table shows the ODBC SQL data types to which C character data can be converted For an explanation of the columns and terms in the table see Converting Data from C to SQL Data Types on page C 24 fSqlType SQL_CHAR SQL_VARCHAR SQL_LONGVARCHAR SQL_DECIMAL SQL_SMALLINT SQL_INTEGER SQL_REAL SQL_DOUBLE SQL_LONGVARBINARY Test Length of data lt Column length Length of data gt Column length Data converted without truncation Data converted with truncation of fractional digits Conversion of data would result in loss of whole as opposed to fractional digits Data value is not a numeric literal Data is within the range of the data type to which the number is being converted Data is outside the range of the data type to which the number is being converted Data value is not a numeric literal Length of data 2 lt Column length Length of data 2 gt Column length Data value is not a hexadecimal value SQLSTATE N A 01004 N A 01004 22003 22005 N A 22003 22005 N A 01004 22005 1 of 2 Data Types C 27 C to SQL Character C 28 fSqlType SQL_DATE SQL_TIMESTAMP INFORMIX CLI Programmer s Manual Test
476. re 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 SQLGetData 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 SQLGetData 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 SQLGetData 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 SQLGetInfo with the SQL_GETDATA_EXTENSIONS option Furthermore applications that use SQLExtendedFetch to retrieve data should call SQLGetData only when the rowset size is 1 13 172 INFORMIX CLI Programmer s Manual SQ_GetData 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 n ext row It calls SQLGetData to retrieve the fetched data the storage locations for the data and the returned number of bytes are specified in the call to SQLGetData Finally it prints each employee s name age and
477. rence 13 259 SQL Procedures Arguments on page 13 8 13 260 INFORMIX CLI Programmer s Manual Column Name Data Type Comments REMARKS VARCHAR 254 A description of the procedure PROCEDURE_TYPE SMALLINT Defines the procedure type SQL_PT_UNKNOWN It cannot be determined whether the procedure returns a value SQL_PT_PROCEDURZ2E The returned object is a procedure that is it does not have a return value SQL_PT_FUNCTION The returned object is a function that is it has a return value 2 of 2 The szProcOwner and szProcName arguments accept search patterns For more information about valid search patterns see Search Pattern 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 SQLBindParameter to specify the ODBC C data type and the SQL 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 SQL_SUCCESS_WITH_INEFO the r
478. res7 H0ST rainbow SERV sqlexec UID mary PWD secret In this example the service and password are also specified INFORMIX CLI Programmer s Manual GLS INFORMIX CLI for Windows INFORMIX CLI for Windows INFORMIX CLI for Windows conforms to the Microsoft ODBC Specification Version 2 5 INFORMIX CLI supports multiple connections to an OnLine or an SE database For Windows 3 1 the driver is called QEINF509 DLL For Windows NT and Windows 95 the driver is called IVINF709 DLL The following sections describe how to set up and configure INFORMIX CLI so that you can connect your Windows Windows 95 or Windows NT client application to a data source Setting Up INFORMIX CLI Perform the following setup activities before you use INFORMIX CLI m Confirm that your system has the appropriate software installed m Confirm that the INFORMIXDIR environment variable setting reflects the appropriate directory path Systm Requirements Depending on your Informix database configuration you must have a compatible Informix database server installed on your system or network The following list shows examples of compatible database servers m INFORMIX OnLine Version 5 x m INFORMIX OnLine Dynamic Server Version 7 x m INFORMIX SE Version 5x 7 x For information on these products refer to your Informix documentation set For a complete listing of compatible database servers see the release notes for INFORMIX CLI To take a
479. 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 an empty string it must contain a list of comma separated values for the types of interest each value must be enclosed in single quotes or unquoted For example TABLE VIEW or TABLE VIEW If the data source does not support a specified table type SOLTables does not return any results for that type INFORMIX CLI Function Reference 13 321 SQL Tables SQLTables returns 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 S tions can use any valid qualifier owner or table regardless of whether it is returned by SQLTables Column Name TABLE_QUALIFIER TABLE_OWNER TABLE_NAME TABLE_TYPE REMARKS 13 322 INFORMIX CLI Programmer s Manual Data Type VARCHAR 128 VARCHAR 128 VARCHAR 128 VARCHAR 128 VARCHAR 254 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 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
480. retcode SQL_SUCCESS Set login time out to 5 seconds SQLSetConnectOption hdbc SQL_LOGIN_TIMEOUT 5 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 INFORMIX CLI Function Reference 13 79 SQLConnect Process data after successful connection retcode SQLAllocStmt hdbc amp hstmt Statement handle if retcode SQL_SUCCESS Skt reed thi Cnetink SQL_DROP AEE E A E EN REES Related Functions For information about See Allocating a connection handle SQLAllocConnect Allocating a statement handle SQLAllocStmt Discovering and enumerating values SQLBrowseConnect required to connect to a data source Disconnecting from a data source SQLDisconnect Connecting to a data source using a SQLDriverConnect connection string or dialog box Returning the setting of a connection option SQLGetConnectOption Setting a connection option SQLSetConnectOption 13 80 INFORMIX CLI Programmer s Manual SQLDataSources SQLDataSources SQLDataSources lists data source names This function is implemented solely by the driver manager Syntax RETCODE SQLDataSources henv fDirection szDSN cbDSNMax pcbDSN szDescription cbDescriptionMax pcbDescription The SQLDataSources function accepts the following arguments Type Argument Use Description HENV henv Input
481. rgbValue 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 3 of 3 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_NO_DATA_FOUND SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE Diagnostics SQL GetData When SQLGetData returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLGetData 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 01004 07006 08S01 22002 Error General warning Data truncated Restricted data type attribute violation Communication link failure Indicator value required but not supplied Description 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 pcb Value contains the length of the data that remains in the specified column prior to the current call to SQLGetData function returns SQL_SUCCESS_WITH_INFO For more information on using multiple calls to SQLGetDat
482. ric 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 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 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 2 of 3 SQLSTATE 1002 S1008 S1010 S1C00 S1T00 Error Invalid column number Operation canceled Function sequence error Driver not capable Time out expired SQLFetch Description 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 before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application DM The specified hstmt was not in an executed state The function was called without first callin
483. river not capable 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 SQLGetInfo 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 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 icol was 0 and the driver does not support bookmarks 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 5 of 5 Usage With each call the driver sets pcbValue to the number of bytes that are available in the result column before the current call to SQLGetData If SOLSetStmtOption sets SQL_MAX_LENGTH and the total number of bytes that are available on the first call is greater than SQL MAX_LENGTH the available number of bytes is set to SQL_MAX_LENGTH 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 deter
484. rm on which the DBMS resides and the network if any used to access that platform Each data source requires that the driver provide connection information For a description of the connection information that the INFORMIX CLI driver provides see Adding a Data Source on page 2 6 for UNIX platforms or Adding a Data Source on page 2 16 for Windows environments The connection information for each data source is stored in the odbc ini file which is created during installation and maintained with a text editor or an administration program A section in this file lists the available data sources Additional sections describe each data source in detail specifying the driver name a description and any additional information the driver needs to connect to the data source For example suppose a user has two data sources Personnel which uses an INFORMIX SE database server and Payroll which uses an INFORMIX OnLine Dynamic Server database server The section that lists the data sources might appear as follows ODBC Data Sources Personnel Informix SE Payroll Informix OnLine The section that describes the Personnel data source might appear as follows Personnel Driver usr informix cli dlls qeinf 08 so Description Personnel database Database personnel Connecting to a DataSource 5 3 Initializing the Environment For more information about the odbc ini file see Understanding the odbc ini File on page 1 7
485. rned in pebDrorAttr Driver attribute keywords are added during the installation procedure For more information see Understanding the odbc ini File on page 1 7 An application can call SQLDrivers multiple times to retrieve all driver descriptions The driver manager retrieves this information from the odbcinst ini file When no more driver descriptions remain SQLDrivers returns SQL_NO_DATA_FOUND If SQLDrivers is called with SQL_FETCH_NEXT immediately after it returns SQL_NO_DATA_FOUND it returns the first driver description If SQL_FETCH_NEXT passes to SOLDrivers the first time it is called SQLDrivers returns the first data source name Because SQLDrivers is implemented in the driver manager it is supported for all drivers regardless of the conformance level of a particular driver Related Functions For information about See Discovering and listing values required to SQLBrowseConnect connect to a data source Connecting to a data source SOLConnect Returning data source names SQLDataSources Connecting to a data source using a SQOLDriverConnect connection string or dialog box INFORMIX CLI Function Reference 13 107 SQLError Type HENV HDBC HSTMT UCHAR FAR SDWORD FAR UCHAR FAR SWORD SWORD FAR SQLError SQLError returns error or status information Syntax RETCODE SOLError henv hdbc hstmt szSqlState pfNativeError szErrorMsg cbErrorMsgMax pcbErrorMsg The SQLError functi
486. rns SQL_SUCCESS However calling SQLTransact with SOL_ROLLBACK results in SQLSTATE S1C00 Driver not capable indicating that a rollback can never be performed INFORMIX CLI Function Reference 13 327 SQL Transact Related Functions For information about See Returning information about a driver or data source SQLGetInfo Freeing a statement handle SQLFreeStmt 13 328 INFORMIX CLI Programmer s Manual Setup Shared Library Function Reference Config DSN te 24 ss Sek eRe ew Bae et Be Bw eS 14 3 Config Translator 2 4 teow Sa se ale oe a me ed 14 7 14 2 INFORMIX CLI Programmer s Manual his chapter describes the syntax of the driver setup shared library API which consists of a single function ConfigDSN ConfigDSN 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 a single function Config Translator ConfigTranslator 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 13 4 ConfigDSN ConfigDSN adds modifies or deletes data sources from the odbc ini file It might prompt the user for connection information It can be in the driver shared library or a separate setup shared library ConfigDSN was introduced in ODBC 1 0 Syntax BOOL ConfigDSN hwndParent fReque
487. ror or status information Function Summary 12 7 Obtaining Information About Data Source System Tables Function Names SQLColumnPrivileges SQLColumns SQLPrimaryKeys SQLProcedures SQLSpecialColumns SQLStatistics SQLTablePrivileges SQLTables 12 8 INFORMIX CLI Programmer s Manual ODBC Conformance Level 2 Level 1 Level 2 Level 2 Level 1 Level 1 Level 2 Level 1 Obtaining Information About Data Source System Tables The following table describes functions that obtain information about data source system tables catalog functions Purpose Returns a list of columns and associated privileges for one or more tables Returns the list of column names in specified tables Returns the list of column name s that comprise the primary key for a table 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 any value in the row is updated by a transaction 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 Terminating a Statement Terminating a Statement The following table describes functions that terminate a statement
488. rrorMsg 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 13 237 SQL ParamData 13 238 SQLSTATE S1008 S1010 S1T00 Usage Error Operation canceled Function sequence error Time out expired Code Example See SQLPutData INFORMIX CLI Programmer s Manual Description The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application SQLExecute or SOLExecDirect was called for the hstmt and returned SQL_NEED_DATA SQLCancel 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 where the return code was SQL_NEED_DATA or a call to SQOLPutData 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
489. rsion number of the driver to interpret the information correctly In particular applications that use these features with ODBC 1 0 drivers need to check explicitly for these capabilities in ODBC 2 x drivers INFORMIX CLI Programmer s 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 batched submitted with arrays of parameters or in procedures they can return multiple result sets or counts To process a batch of statements statement with arrays of parameters or procedure that returns multiple result sets or row counts an application performs the following operations 1 Calls SQLExecute or SOQLExecDirect to execute the statement or procedure 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 Calls SQLMoreResults to determine if another result set or row count is available Repeats steps 2 and 3 until SQLMoreResults returns SQL_NO_DATA_FOUND Retrieving Results 7 15 Retrieving Status and Error Information Function Return Codes 2 2 2 ww ee eee en 8 3 Retrieving Error Messages 1 1 ww eee e 8 4 Error Messages 2 1
490. rsor behavior 2 of 2 Purpose Executes a prepared statement Executes a statement Returns the text of an SQL statement as translated by the driver 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 Retrieving Results and Information about Results Retrieving Results and Information about Results The following table describes functions that retrieve results and information about results Function Name SQLRowCount SQOLNumResultCols SQLDescribeCol SQLColAttributes SQLBindCol SQLFetch SQLExtendedFetch SQLGetData SQLMoreResultsr SQLError ODBC Conformance Core Core Core Core Core Core Level 2 Level 1 Level 2 Core Purpose Returns the number of rows affected by an insert update or delete request Returns the number of columns in the result set Describes a column in the result set Describes attributes of a column in the result set Assigns storage for a result column and specifies the data type Returns a result row Returns multiple result rows 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 er
491. rsor name in szCursor is truncated to cbCursorMax 1 bytes Return Codes SQL_SUCCESS SOQL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 161 SQL GetCursorName Diagnostics SQLSTATE Error 01000 General warning 01004 Data truncated 1000 General error S1001 Memory allocation failure 13 162 INFORMIX CLI Programmer s Manual When SQLGetCursorName returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLGetCursorName 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 SQOLSTATE value is SOL_ERROR unless noted otherwise Description 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 pcebCursor 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 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 exe
492. rted 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 SQL_FN_TSI_MINUTE SQL_FN_TSI HOUR SQL_FN_TSI_DAY SQL_FN_TSI_WEEK SOL_FN_TSLMONTH SQL_FN_TSI_QUARTER SQL_FN_TSI_YEAR 20 of 22 INFORMIX CLI Function Reference 13 209 SQL Getinfo InfoType SQL_TIMEDATE_FUNCTIONS SQL_TXN_CAPABLE 13 210 INFORMIX CLI Programmer s Manual Returns 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_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 A 16 bit integer value that describes the transaction support in the driver or data source SQL_TC_NONE Transactions not supported 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 SQL_TC_DDL_COMMIT Transactions can contain only DML st
493. ructure is the same as described in File Format for odbc ini on page 1 8 Before you can connect to a data source you must use the ODBC Administrator to add the connection information for the data source to the ODBC INI subkey Overview of INFORMIX CLI 1 7 File Format for odbe ini 1 8 ODBC DataSources Data Source Specification Default Data Source Specification ODBC Options ODBC Data Sources data_source_name driver_description INFORMIX CLI Programmer s Manual File Format for odbc ini The odbc ini file includes the following sections This section lists the name of each data source and describes its associated driver Each data source listed in the ODBC Data Sources section has a section that contains additional infor mation about that data source This section is optional and specifies the default data source to use when none is specified This section specifies the ODBC installation directory and the ODBC options that can be enabled or disabled Each entry in the ODBC Data Sources section lists a data source and a description of the driver it uses This section has the following format ODBC Data Sources data_source_namel driver_descriptionl data_source_name2 driver_description2 identifies the data source that the driver accesses You choose the data source name describes the database driver that accesses the data source This field is optional For example to define an Agencies
494. s SQLBindCol hstmt 1 SQL_C_CHAR szQualifier STR_LEN amp cbQualifier SQLBindCol hstmt 2 SQL_C_CHAR szOwner STR_LEN amp cbOwner SQLBindCol hstmt 3 SQL_C_CHAR szTableName STR_LEN amp cbTableName SQLBindCol hstmt 4 SQL_C_CHAR szColName STR_LEN amp cbColName SQLBindCol hstmt 5 SQL_C_SSHORT amp DataType 0 amp cbDataType SQLBindCol hstmt 6 SQL_C_CHAR szTypeName STR_LEN amp cbTypeName SQLBindCol hstmt 7 SQL_C_SLONG amp Precision 0 amp cbPrecision SQLBindCol hstmt 8 SQL_C_SLONG amp Length 0 amp cbLength SQLBindCol hstmt 9 SQL_C_SSHORT amp Scale 0 amp cbScale SQLBindCol hstmt 10 SQL_C_SSHORT amp Radix 0 amp cbRadix SQLBindCol hstmt 11 SQL_C_SSHORT amp Nullable 0 amp cbNullable 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 INFORMIX CLI Function Reference 13 73 SQLColumns 13 74 else break Process fetched data Related Functions INFORMIX CLI Programmer s Manual For information about See Assigning storage for a column in a result set SQLBindCol Canceling statement processing SQLCancel Returning privileges for a column or columns SQLColumnPrivileges Fetching a block of data or scrolling through a result set S
495. s A character string with the data source vendor name for an owner for example owner Authorization ID or Schema A 32 bit bitmask that enumerates the statements in which owners can be used 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 SQL_OU_PROCEDURE_INVOCATION Owners are supported in the ODBC procedure invocation statement SQL_OU_TABLE_DEFINITION Owners are supported in all table definition statements CREATE TABLE CREATE VIEW ALTER TABLE DROP TABLE and DROP VIEW SQL_OU_INDEX_DEFINITION Owners are supported in all index definition statements CREATE INDEX and DROP INDEX SQL_OU_PRIVILEGE_DEFINITION Owners are supported in all privilege definition statements GRANT and REVOKE 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 A character string with the data source vendor name for a procedure for example database procedure stored procedure or procedure A character string Y if the data source supports procedures and the driver supports the ODBC procedure invocation syntax N otherwise 15 of 22 InfoType SQL_Q
496. s See also Converting data SQL identifiers special characters 13 209 SQL quoted identifiers case sensitivity 13 208 SQL statements batch 13 229 B 11 direct execution 6 7 embedded D 1 D 5 ODBC function equivalents D 5 D 6 information types 13 190 interoperability B 1 keywords B 21 maximum length 13 202 native 13 230 qualifier usage in 13 207 query timeout 13 294 SQLCancel 13 52 SQLExecDirect 13 120 SQLExecute 13 127 SQLPrepare 13 250 SQLAIlocConnect allocating handles 5 5 function description 13 11 13 14 13 16 13 18 13 40 13 51 13 54 13 62 13 68 13 77 13 83 13 87 13 92 13 95 13 106 13 110 13 113 13 122 13 129 13 146 13 152 13 154 13 156 13 160 13 163 13 166 13 176 13 183 13 215 13 218 13 227 13 230 13 233 13 235 13 238 13 241 13 246 13 253 13 257 13 265 13 272 13 274 13 283 13 287 13 288 13 297 13 307 13 315 13 321 13 327 15 3 15 7 with SQLConnect 13 80 SQLAIocEnv function description 13 14 13 40 13 51 13 54 13 62 13 68 13 77 13 83 13 87 13 92 13 95 13 106 13 110 13 113 13 122 13 129 13 146 13 152 13 154 13 156 13 160 13 163 13 166 13 176 13 183 13 215 13 218 13 227 13 230 13 233 13 235 13 238 13 241 13 246 13 253 13 257 13 265 13 272 13 274 13 283 13 287 13 288 13 297 13 307 13 315 13 321 13 327 15 3 15 7 initializing handles 5 4 with SQLConnect 13 80 SQLAllocStmt 6 5 13 16 SQLBindCol binding columns 7 4 code exa
497. s 3 1 users should never modify the ODBC INI file directly The contents of this file are changed based on the data source setup and modification you make using the ODBC Administrator Modifying the ODBC INI file directly might result in data source configuration errors 2 16 INFORMIX CLI Programmer s Manual Windows NT Windows 95 Adding a Data Source In Windows NT ODBC INI is a subkey of the HKEY_CURRENT_USER key within the Registry When you access the Registry using this subkey the ODBC structure is the same as described in the File Format for odbc ini on page 1 8 Before you can connect to a data source you must use the ODBC Administrator to add the connection information for the data source to the Registry Required Data Source Configuration Information 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 Optional Data Source Configuration Information When you add a data source you can choose to define new connection infor mation defaults You can specify three types of options in your data source setup m Options that define name or location m Options that define cursor behavior m Options that define operation handling Options That Define Name or Location The following table lists the types of names and locations you can set as default connection options for a
498. s Manual SQLBindParameter 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 SQLBind Parameter m The fSqlType argument is SQL_LLONGVARBINARY or SQL_LONGVARCHAR m The data for the parameter is sent with SQLPutData In this case the cbCo Def argument contains the total number of bytes that are sent for the parameter For more information see Passing Parameter Values on page 13 34 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 the fCType argument If pcbValue is the result of the SQL_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 SOLParamOptions is called to specify multiple values for the parameter the application can use the
499. s Smith with the password Sesame and returns the following string in szConnStrOut DATABASE Database master model empdata 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 INFORMIX CLI Function Reference 13 47 SQL BrowseConnect itdefine BRWS_LEN 100 while retcode if retcode retcode if retcode SQLFreeConnect hdbc SQLFreeEnv henv 13 48 INFORMIX CLI Programmer s Manual SQL_SU Process data aft This is the final piece of information that the driver needs to connect to the data source SOLBrowseConnect returns SQL_SUCCESS and szConnStrOut contains the completed connection string DSN My Source HOST red UID Smi th PWD Sesame DATABASE empdata HENV henv HDBC hdbc HSTMT hstmt RETCODE retcode UCHAR szConnStrIn BRWS_LEN szConnStrOutLBRWS_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 a shown to build
500. s 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE Error Description 01000 General warning INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO 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 DM The driver manager could not allocate allocation failure memory for the connection handle The driver could not allocate memory for the connection handle S1009 Invalid argument DM The argument phdbc was a null pointer value 13 10 INFORMIX CLI Programmer s Manual 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 SQLAIlocConnect 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 requ
501. s that SOLBindCol commonly returns 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 S1000 S1001 S1002 S1003 S1010 S1090 S1C00 Error 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 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 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 value specified for the argument icol exceeded the maximum number of columns supported by the data source DM The argument fCType was not a valid data type or SQL_C_DEFAULT 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 specified for the argument cbVal ueMax was less than 0 The driver does not support the data typ
502. scribes 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 The function was called but before it completed execution SQLCancel was called on the hstmt from a different thread in a multi threaded application 1 of 2 SQLSTATE 1010 S1090 S1091 S1C00 S1T00 Error Function sequence error Invalid string or buffer length Descriptor type out of range Driver not capable Time out expired SQLColAttributes Description 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 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 descriptor 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
503. se 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 SQL 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 If SOLExecDirect encounters a data at execution parameter it returns SQL_NEED_DATA The application sends the data using SQLParamData and SOLPutData For more information see SOLBindParameter SOQLParamData SQLParamOptions and SQLPutData Code Example See SOLBindCol SOQLExtendedFetch SQLGetData and SOLProcedures Related Functions For information about See Assigning storage for a column ina result set SQLBindCol Canceling statement processing SOQLCancel Executing a prepared SQL statement SQLExecute 13 118 INFORMIX CLI Programmer s Manual For information about 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 SQLExecDirect See SQLExtendedFetch SQLFetch SQLGetCursorName SQLGet
504. ses from the data source to the driver The translation shared library might not translate some data depending on the data type and the purpose of the trans lation shared library For example a shared library that translates character data from one code page to another ignores all numeric and binary data The value of fOption is set to the specified value of vParam by calling SQLSet ConnectOption with the SQL_TRANSLATE_OPTION option It is a 32 bit value that has a specific meaning for a given translation shared library For example it might specify a certain character set translation If the same buffer is specified for rgbValueIn and rgbValueOut the translation of data in the buffer is performed in place Important Although cbValueIn cbValueOutMax and pebValueOut are the SDWORD type SQLDataSourceToDriver does not necessarily support huge pointers If SQLDataSourceToDriver returns FALSE data truncation might have occurred during translation If pcbValueOut the number of bytes available to return in the output buffer is greater than cbValueOutMax the length of the output buffer then truncation occurs The driver must determine whether the truncation is acceptable If truncation does not occur the SOLData SourceToDriver returned FALSE due to another error In either case a specific error message is returned in szErrorMsg INFORMIX CLI Programmer s Manual SQLDriverToDataSource Related Functions For information about
505. set size is 0 If the specified size exceeds the maximum keyset size the driver substitutes that size and returns SQLSTATE 01502 Option value changed SQLExtendedFetch returns an error if the keyset size is greater than 0 and less than the rowset size 3 of 5 INFORMIX CLI Function Reference 13 291 SQL SetStmtOption fOption SQL_MAX_LENGTH SQL_MAX_ROWS SQL_NOSCAN SQL_QUERY_TIMEOUT UNSUPPORTED vParam Contents 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 SQLFetch or SQLGetData 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 01S02 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 SQLLLONGVARCHAR and SQL_LONGVARBINARY c
506. sign and 10 digits or 10 if unsigned 10 digits 13 a sign 7 digits a decimal point the letter E a sign and 2 digits 22 a sign 15 digits a decimal point the letter E a sign and 3 digits 1 of 2 Converting Data from SQL to C Data Types fSqlType Display Size SQL_LONGVARBINARY The maximum length of the column times 2 SQL_DATE 10 a date in the format yyyy mm dd SQL_TIMESTAMP 19 if the scale of the time stamp is 0 or 20 plus the scale of the time stamp if the scale is greater than 0 This is the number of characters in the yyyy mm dd hh mm ss f format For example the display size of a column storing thousandths of a second is 23 the number of characters in yyyy mm dd hh mm ss fff a Tf the driver cannot determine the column or parameter length it returns SQL_NO_TOTAL 2 of 2 Converting Data from SQL to C Data Types When an application calls SQLExtendedFetch 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 fCType argument in SOLBindCol or SQLGetData Finally it stores the data in the location pointed to by the rgbValue argument in SQLBindCol or SQLGetData The word convert is used in this section in a broad sense and it includes the transfer of data without a conversion in data type from one storage location to another T
507. sion by zero 23000 Integrity constraint violation 24000 Invalid cursor state 40001 Serialization failure INFORMIX CLI Programmer s Manual 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 with 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 as
508. sociated with the hstmt belonged was terminated to prevent deadlock 2 of 4 SQLSTATE 42000 S1000 S1001 S1008 S1010 Error Syntax error or access violation General error Memory allocation failure Operation canceled Function sequence error SQLExecute Description The user did not have permission to execute the prepared statement associated with the hstmt 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 SQLCancel was called on the hstmt from a different thread in a multi threaded 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 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 SQLFetch or SQLExtendedFetch had not been called 3 of 4 INFORMIX CLI Function Reference 13 123 SQLExecute 1
509. source 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 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 SQLDescribeCol describe the columns in a result set and SQLNumResultCols returns the number of columns in a result set INFORMIX CLI Function Reference 13 69 SQLColumns Important SQLColumns 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 by SQLColumns 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 call SQLGetInfo with the SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_OWNER_NAME_LEN SQL_MAX_TABLE_NAME_LEN and SQL_MAX_COLUMN_NAME_LEN options Column Nam
510. source returned the requested information The time out period is set through SQLSetStmtOption 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 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 cbDescMax and pcbDesc When infor mation is returned in rgbDesc the driver ignores pfDesc INFORMIX CLI Function Reference 13 55 SQL ColAttributes Information fDescType Returned in This function is an extensible alternative to SOLDescribeCol SQLDescribeCol returns a fixed set of descriptor information based on ANSI 89 SQL SQLColAttributes allows access to the more extensive set of descriptor information available in ANSI SQL 92 and Informix extensions The following table shows the currently defined descriptor types and the arguments in which information is returned for them more descriptor types will probably be defined to take advantage of different data sources 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
511. ss than or buffer length equal to 0 but not equal to SQL_NTS S 1C00 Driver not capable The cursor concurrency combination is invalid 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 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 Q COMMIT or ROLLBACK statement it is not interoperable among DBMS products To commit or roll back a transaction call SQLTransact 13 248 INFORMIX CLI Programmer s Manual SQLPrepare The driver modifies the statement to use the form of SQL used by the data source 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 a description of SQL statement grammar see Appendix B For the driver an hstmt is similar to a statement identifier in embedded SQL code If the data source supports statement identifiers the driver can send a statement identifier and parameter values to the data source Once a statement is prepared the application uses hstmt to refer
512. ssociated table column The argument szSqlStr contained an SQL statement that contained a parameter or literal and the value was incompatible with the data type of the associated table column The argument szSqlStr contained an SQL statement that contained a date time or time stamp parameter or literal and the value was respectively an invalid date time or time stamp 2 of 6 INFORMIX CLI Function Reference 13 113 SQL ExecDirect 13 114 SQLSTATE 22012 23000 24000 34000 37000 40001 42000 S0001 Error Division by zero Integrity constraint violation Invalid cursor state Invalid cursor name Syntax error or access violation Serialization failure Syntax error or access violation Base table or view already exists INFORMIX CLI Programmer s Manual Description The argument szSqlStr contained an SQL statement that contained an arithmetic expression that caused division by zero The argument szSqlStr contained an SQL statement that contained a 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 A cursor was already opened on the statement handle The argument szSqlStr contained a positioned UPDATE or DELETE statement but the cursor was positioned before the start
513. st IpszDriver lpszAttributes Setup Shared Library Function Reference 14 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 lpszDriver Input Driver description usually the 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 used by ConfigDSN are the same as those used by SOLBrowseConnect and SQLDriverConnect except ConfigDSN does not accept the DRIVER keyword As in SQLBrowseConnect and SQLDriverConnect the keywords and their values should not contain the
514. string in rgbDesc Description SQL_COLUMN_AUTO_INCREMENT pfDesc SQL_COLUMN_CASE_SENSITIVE pfDesc SQL_COLUMN_COUNT pfDesc SQL_COLUMN_DISPLAY_SIZE pfDesc 13 56 INFORMIX CLI Programmer s Manual 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 TRUE if the column is treated as case sensitive for collations and comparisons FALSE if the column is not treated as case sensitive for collations and comparisons or is noncharacter Number of columns available in the result set The icol argument is ignored Maximum number of characters required to display data from the column For more infor mation on display size see Precision Scale Length and Display Size on page C 8 1 of 4 fDescType SQL_COLUMN_LABEL SQL_COLUMN_LENGTH SQL_COLUMN_MONEY SQL_COLUMN_NAME SQL_COLUMN_NULLABLE SQL_COLUMN_OWNER_NAME Information Returned in rgbDesc pfDesc pfDesc rgbDesc pfDesc rgbDesc SQLColAttributes Description The column label or title For example a column named EmpName might be labeled Employee Name If a column 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
515. suffix returned by SOLGetTypelInfo of a binary literal in an SQL statement For example the binary literal 0xFFAA has a length of 4 If there is no maximum length or the length is unknown this value is set to 0 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 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 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 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 A 16 bit integer value that specifies the maximum number of columns allowed in an ORDER BY clause If no limit is specified or the limit is unknown this value is set to 0 10 of 22 INFORMIX CLI Function Reference 13 199 SQL Getinfo InfoType SQL_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 SQL_MAX_QUALIFIER_NAME_LEN SQL_MAX_ROW_SIZE
516. symbol indicates the end of the product or platform specific information Example Code Conventions Examples of C and SQL code occur throughout this manual The code is not specific to any single Informix application development tool except where it is noted otherwise Note that an ellipsis in example code indicates that arguments can be repeated several times Also note that a column of three dots in an example indicates that additional code would be added in a full application but it is not necessary to show more code to describe the concept being discussed Screen Illustration 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 windowing environment a little differently than the way it appears on your screen Introduction 11 Additional Documentation Additional Documentation This section describes the following pieces of the documentation set m Printed documentation m On line documentation m Related reading Printed Documentation The following related Informix documents complement the information in this manual m You or whoever installs your Informix products should refer to the INFORMIX CLI Installation Guideto ensure that your Informix product is properly set up before you begin to work
517. szAttributes it uses information from the odbc ini file The user can modify the information before ConfigDSN stores it in the odbc ini file If the data source name was changed ConfigDSN first calls SQLRemove DSNFromIni in the installer shared library to remove the existing data source specification from the odbc ini file It then follows the steps in the previous section to add the new data source specification If the 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 checks that the data source name is in the odbc ini file It then calls SQLRemoveDSNFromIni in the installer shared library to remove the data source 14 6 INFORMIX CLI Programmer s Manual Config Translator ConfigTranslator ConfigTranslator returns a default translation option for a translator It can be in the translator shared library or a separate setup shared library Config Translator was introduced in ODBC 2 0 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 DWO
518. szErrorMsg is truncated to cbErrorMsgMax 1 bytes 2 of 2 The application returns TRUE if the translation succeeds FALSE if it fails Translation Shared Library Function Reference 15 9 SQL DriverToDataSource 15 10 Usage The driver calls SQLDriverToDataSource to translate all data SQL statements parameters and so on that passes from the driver to the data source The translation shared library might not translate some data depending on the data type and the purpose of the translation shared library For example a shared library that translates character data from one code page to another ignores all numeric and binary data The value of fOption is set to the value of vParam that is specified by calling SQLSetConnectOption with the SQL_TRANSLATE_OPTION option It is a 32 bit value that has a specific meaning for a given translation shared library For example it could specify a certain character set translation If the same buffer is specified for rgbValueIn and rgbValueOut the translation of data in the buffer is performed in place Important Although cbValueIn cbValueOutMax and pcbValueOut are the SDWORD type SQLDriverToDataSource does not necessarily support huge pointers If SQLDriverToDataSource returns FALSE data truncation might have occurred during translation If pcbValueOut the number of bytes available to return in the output buffer is greater than cbValueOutMax the length of the output buffer
519. szTableName String search pattern for column names Length of szColumnName SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 67 SQLColumns SQLSTATE 01000 08S01 24000 S1000 S1001 S1008 S1010 13 68 Diagnostics Error General warning Communication link failure Invalid cursor state General error Memory allocation failure Operation canceled Function sequence error INFORMIX CLI Programmer s Manual When SQLColumns returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLColumns 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 SQLSTATE value is SQL_ERROR unless noted otherwise 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 returned by SQLError in the argument szErrorMsg describes the error and its cause The
520. t sqlstr SQL_NTS return print_err hdbc hstmt See what kind of statement it was If there are no result Constructing an INFORMIX CLI Application t SQL_SUCCESS x 10 7 Interactive Ad Hoc Query Example if 10 8 columns the statementis not a SELECT number of affected rows is greater 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 Xi han 0 the statement was E statement so print the ement so print that the it printf 1ld rows affected n rowcount else printf Operation successful n SQLTransact hdbc SQL_COMMIT If the number of affected rows is 0 x K Ki ous A 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 collen i 1 SQLBindCol hstmt
521. t C Data Types fCType ODBC C Typedef C Type The value of the day field must be in the range from 1 to the number of days in the month The number of days in the month is determined from the values of the year and month fields and is 28 29 30 or 31 d The value of the hour field must be in the range from 0 to 23 e The value of the minute field must be in the range from 0 to 59 The value of the second field must be in the range from 0 to 59 8The value of the fraction field is the number of nanoseconds 10 seconds and ranges from 0 to 999 999 999 For example the value of the fraction field for a half second is 500 000 000 for a thousandth of a second one millisecond is 1 000 000 for a millionth of a second one microsecond is 1 000 and for a billionth of a second one nanosecond is 1 2 of 2 Default C Data Types If an application specifies SQL_C_DEFAULT for the fCType argument in SOLBindCol SQLGetData 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 ODBC SQL data type the following table shows the corresponding or default C data type For information about how Informix data types map to ODBC SQL data types see Mapping Data Types on page 1 15 Tip For maximum interoperability applications should specify a C data type other than SQL_C_DEFAULT This allows drivers
522. t 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 SQLNumParams can be called only after SQLPrepare has been called If the statement associated with hstmt does not contain parameters SQLNum SQLNumResultCols Related Functions For information about See Assigning storage for a parameter SQLBindParameter 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 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_STILL_EXECUTING SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference 13 233 SQLNumResultCols SQLSTATE 01000 S1000 S1001 S1008 S1010 S1T00 Diagnostics Error General warning General error Memory allocation failure Operation canceled Function sequence error Time out expired 13 234 INFORMIX CLI Programmer s Manual When SQLNumResultCols returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists t
523. t applicable SQL_VARCHAR SQL_LONGVARCHAR SQL_DECIMAL The defined number of digits to the right of the decimal point For example the scale of a column defined as NUMERIC 10 3 is 3 SQL_SMALLINT 0 SQL_INTEGER SQL_REAL Not applicable SQL_DOUBLE SQL_LONGVARBINARY Not applicable 1 of 2 C 10 INFORMIX CLI Programmer s Manual fSqlType SQL_DATE SQL_TIMESTAMP Length Scale Not applicable The number of digits to the right of the decimal point in the yyyy mm dd hh mm ss f format For example if the TIMESTAMP data type uses the yyyy mm dd hh mm ss fff format the scale is 3 a The ibScale argument of SQLBindParameter is ignored for this data type Length 2 of 2 The length of a column is the maximum number of bytes that are returned to the application when data is transferred to its default C data type For character data the length does not include the null termination byte The length of a column might be different than the number of bytes that are required to store the data on the data source For a list of default C data types see the Default C Data Types on page C 6 The following table defines the length for each ODBC SQL data type fSqlType SQL_CHAR SQL_VARCHAR SQL_LONGVARCHAR SQL_DECIMAL SQL_SMALLINT SQL_INTEGER SQL_REAL Length The defined length of the column For example the length of a column defined as CHAR 10 is 1
524. t specifies the data source connection How you connect to a data source depends on the connection method that your INFORMIX CLI application uses Using Dialog Boxes to Connect to a Data Source One common way of connecting to a data source is through the Data Source dialog box as Figure 2 1 illustrates If your INFORMIX CLI application is set up to use a dialog box the Data Sources dialog box appears and prompts you for the appropriate data source connection information Figure 2 1 The Data Sources Dialog Box User Data Sources Driver Close Stores7 Informix Help Setup Delete Add System DSN Drivers INFORMIX CLI 2 11 Using Dialog Boxes to Connect to a Data Source 2 12 To connect to a data source using a dialog box In the Data Sources dialog box select a data source Click OK The Informix ODBC Connect dialog box appears as Figure 2 6 illus trates The connection information that appears is the default information listed in your odbc ini file Figure 2 2 The Logon to Host Name User Name Password Database Name INFORMIX Dialog Sos E pe mickey Cancel Help To accept the default values and connect to the data source click OK or To modify the default values for this data source continue to step 4 In the Database Name text box type the name of the OnLine or SE database that contains the tables
525. t to a data source the driver manager looks at your odbc ini file for specific connection information This file contains information about each data source UNIX users are responsible for modifying their odbc ini file using a text editor Adding a Data Source Before you can connect to a data source you must add an entry for that data source in your odbc ini file For complete information on the format and contents of the odbc ini file refer to Understanding the odbc ini File on page 1 7 Required Data Source Configuration Information When you add a data source you must provide two pieces of information in the Data Source Specification section the name of the data source and the full path to your driver shared library All other connection information is optional Optional Data Source Configuration Information When you add a data source you can choose to define new connection defaults You can specify two types of connection options in the Data Source Specification section m Options that define names Options that define cursor behavior INFORMIX CLI Programmer s Manual Adding a Data Source Options That Define Names The following table lists the names that you can set as default connection options for a data source Keyword Attribute Description A longname that you choose to identify the data source Database The name of the OnLine or SE database that the data source accesses The name can include t
526. tch SQLGetData SQLGetInfo SQLPutData SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLGetData SQLPrepare SQLPutData SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLGetData SQLPutData SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLGetData SQLParamData SQLExecDirect SQLExecute 4 of 13 INFORMIX CLI Error Codes A 5 SQLSTATEs 24000 25000 28000 34000 37000 3C000 A 6 INFORMIX CLI Programmer s Manual 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 SQLColumns SQLDescribeCol SQLExecDirect SQLExecute SQLExtendedFetch SQLFetch SQLGetData SQLGetStmtOption SQLGetTypelnfo SQLPrepare SQLPrimaryKeys SQLProcedures SQOLSetCursorName SQLSetStmtOption SQLSpecialColumns So lStatistics SQLTablePrivileges SQLTables SQLDisconnect SQLBrowseConnect SQLConnect SQLDriverConnect SQLExecDirect SQLPrepare SQLSetCursorName SQLExecDirect SQLNativeSql SQLPrepare SQLSetCursorName 5 of 13 SQLSTATEs 40001 42000 70100 IM002 IM003 IM004 IM005 IM006 IM007 Error Serialization failure Syntax error or access violation Operation aborted Data source name not found and no default driver specified Specified driver could not be loaded Driver SQLAll
527. ter matches 0 or more of any character the underscore character _ matches 1 character INFORMIX CLI Programmer s Manual 6 of 11 Hements Used in SQL Statements Element SQL Conformance Level pattern value character string literal dynamic parameter USER In a character string literal the percent character matches 0 or more of any character the underscore character _ matches 1 character precision unsigned integer predicate comparison predicate like predicate null predicate predicate between predicate comparison predicate exists predicate in predicate like predicate null predicate quantified predicate primary column name dynamic parameter literal expression primary column name dynamic parameter literal set function reference USER expression primary column name dynamic parameter literal ODBC scalar function extension set function reference USER expression procedure procedure name procedure name procedure parameter list procedure identifier user defined name Core Core Minimum Core Minimum Core Extended Extended Extended 7 of 11 SQL Grammar B 17 Hements Used in SQL Statements B 18 Element SQL Conformance Level procedure name procedure identifier owner name procedure identifier qualifier name qualifier separator procedure identifier qualifier name quali
528. ter specified with SQLBindParameter is defined using an SQL data type the parameters in an SQL statement have no intrinsic data type Therefore parameter markers can be included in an SQL statement only if their data types can be inferred from another operand in the statement For example in an arithmetic expression such as COLUMN1 the data type of the parameter can be inferred from the data type of the named column repre sented by COLUMN1 An application cannot use a parameter marker if the data type cannot be determined The following table describes how a data type is determined for several types of parameters Location of Parameter Assumed Data Type One operand of a binary arithmetic or Same as the other operand comparison operator The first operand in a BETWEEN clause Same as the other operand The second or third operand in a BETWEEN Same as the first operand clause An expression used with IN Same as the first value or the result column of the subquery A value used with IN Same as the expression A pattern value used with LIKE VARCHAR An update value used with UPDATE Same as the update column B 2 INFORMIX CLI Programmer s Manual Parameter Markers Parameter Markers An application cannot place parameter markers in the following locations In a SELECT list As both expressions in a comparison predicate As both operands of a binary operator As both the first and second operands of a BETWEEN operation As both t
529. th and Display Size on page C 8 MAXIMUM_SCALE SMALLINT 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 infor mation see Precision Scale Length and Display Size on page C 8 4 of 4 Attribute information can apply to data types or to specific columns in a result set SQLGetTypeInfo returns information about attributes associated with data types SOLColAttributes returns information about attributes associated with columns in a result set INFORMIX CLI Function Reference 13 223 SQL GetTypelnfo Related Functions For information about See Assigning storage fora column ina result SQLBindCol set Canceling statement processing SQL1Cancel Returning information about a columnina SQLColAttributes result set Fetching a block of data or scrolling SQLExtendedFetch through a result set Fetching a row of data SQLFetch Returning information about a driver or SQLGetInfo data source 13 224 INFORMIX CLI Programmer s Manual SQLMoreResults SQLM oreResults SOQLMoreResults 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
530. that promote SQL data types and therefore cannot always determine default C data types to return data It also allows drivers that cannot determine whether an integer column is signed or unsigned to correctly return data Important ODBC 2 0 drivers use the ODBC 2 0 default C data types for ODBC 1 0 and ODBC 2 0 integer C data C 6 INFORMIX CLI Programmer s Manual Default C Data Types SQL Data Type Default C Data Type SQL_CHAR SQL_C_CHAR SQL_VARCHAR SQL_C_CHAR SQL_LONGVARCHAR SQL_C_CHAR SQL_DECIMAL SQL_C_CHAR SQL_SMALLINT SQL_C_SSHORT or SQL_C_USHORT SQL_INTEGER SQL_C_SLONG or SQL_C_ULONG SQL_REAL SQL_C_FLOAT SQL_DOUBLE SQL_C_DOUBLE SQL_LONGVARBINARY SQL_C_BINARY SQL_DATE SQL_C_DATE SQL_TIMESTAMP SQL_C_TIMESTAMP a Tf the driver can determine whether the column is signed or unsigned such as when the driver is fetching data from the data source or when the data source supports only a signed type or only an unsigned type but not both the driver uses the corresponding signed or unsigned C data type If the driver cannot determine whether the column is signed or unsigned it passes the data value without attempting to validate it numerically Data Types C 7 Transferring Data in its Binary Form C 8 Transferring Data in its Binary Form 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
531. that you want to access You can also click the down arrow to choose a name from a drop down list In the Host Name text box type the name of the computer on which your Informix database server resides In the User Name text box type your user name as specified on the database server In the Password text box type your password for the UNIX server to which you want to connect INFORMIX CLI Programmer s Manual Using a Connection String to Connect to a Data Source 8 To display the INFORMIX Server Options dialog box click Options This dialog box lets you specify options that are described in Optional Data Source Configuration Information on page 2 6 Figure 2 3 The INFORMIX Server Options Service Name OK Dialog Box INFORMIX Server Options Server Name Cancel Help 4 Protocol Type 9 Click OK to accept any changes you make and return to the Informix ODBC Connect dialog box 10 Click OK to complete the logon and to update these values in the odbc ini file 11 Once the connection information is verified your application can use the INFORMIX CLI driver to access the information that the data source contains Using a Connection String to Connect to a Data Source Some applications require that you connect to a data source by typing a connection string The connection string includes several attributes that specify how a driver connects to a dat
532. the following arguments Type Argument 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 SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or SQL_INVALID_HANDLE 13 286 INFORMIX CLI Programmer s Manual Diagnostics SQLSetStmtOption When SQOLSetStmtOption returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLSetStmtOption 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 01502 08S01 24000 S1000 S1001 S1009 Error General warning Option value changed Communication link failure Invalid cursor state General error Memory allocation failure Invalid argument value 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 communication l
533. the row is unchanged the driver or data source prevents other transactions from changing the row until the operation is complete If the row has changed the transaction that contains the update or delete operation fails To specify the concurrency used by a cursor an application calls SQLSetStmtOption with the SQL_CONCURRENCY option The application can specify that the cursor is read only locks the result set uses optimistic concurrency control and compares row versions to determine if a row has changed or uses optimistic concurrency control and compares data values to determine if a row has changed Modifying Result Set Data with 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 This 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 executing a SELECT statement to create a result set an application calls SQLFetch 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 UPDATE 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 Retrieving Results
534. the version of ODBC supported by the driver S 1C00 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 SQLSetStmtOption 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 SQLSTATE 01502 Option value changed For example if fOption is SQL_ CONCURRENCY vParam is SQL_CONCUR_ROWVER and the data source does not support this the driver substitutes SQL_CONCUR_VALUES To determine the substituted value an application calls SQLGetStmtOption The currently defined options are shown in the following table Options from 0 to 999 are reserved by ODBC 13 288 INFORMIX CLI Programmer s Manual fOption SQL_ASYNC_ENABLE UNSUPPORTED SQL_BIND_TYPE SQLSetStmtOption 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 a 32 bit integer value The format is noted in the option description This format applies to the i
535. tion is SQL_TRANSLATE_DLL 1 of 2 INFORMIX CLI Function Reference 13 273 SQL SetConnectOption SQLSTATE S1000 Error General error 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 S1001 Memory allocation failure The driver did not allocate memory required to support execution or completion of the function S1009 Invalid argument value Given the specified fOption value an invalid value was specified for the argument vParam The Driver Manager returns this SQLSTATE only for connection and statement options that accept a discrete set of values such as SQL_ACCESS_MODE For all other connection and statement options the driver must verify the value of the argument vParam S1010 Function sequence error DM SQLExecute or SQLExecDirect 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 SQL_NEED_DATA This function was called before SQLBrowseConnect returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS S1011 Operation invalid at this time The argument fOption was SQL_TXN_ISOLATION and a transaction was open S1092
536. tion 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 contained 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 SQLBindParameter 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 INFORMIX CLI Function Reference 13 121 SQL Execute 13 122 SQLSTATE Error 22003 Numeric value out of range 22005 Error in assignment 22008 Datetime field overflow 22012 Divi
537. to the statement in later function calls The prepared statement associated with the hstmt might be reexecuted by calling SQLExecute until the application frees the stmt with a call to SQLFreeStmt with the SOQL_DROP option or until the hstmt is used in a call to SOLPrepare SOLExecDirect or one of the catalog functions SQLColumns SQLTables 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 SQLPrepare 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 SOQLDescribeCol SOLColAttributes and SQLExecute Depending on the capabilities of the driver and data source and on whether the application has called SQLBindParameter 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 SQL 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
538. turns SQL_SUCCESS 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 the 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 fdefine MAX_DATA_LEN 1024 SDWORD cbNameParam cbID 0 cbPhotoParam cbData SWORD sID PTR pToken InitValue UCHAR DatalMAX_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 x parameter number in rgbValue instead of a buffer address E INFORMIX CLI Function Reference 13 267 SQL PutData 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 amp sID 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
539. turns 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 INFORMIX CLI Programmer s Manual SQLBrowseConnect 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 13 78 It might establish a connection with the data source during the browsing process If SQLBrowseConnect returns SQL_ERROR outstanding connections terminate and the hdbc returns to an unconnected state When SQLBrowseConnect 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 string contains the DSN keyword the driver manager locates a corresponding data source specification in the odbc ini file as the following list describes m If the driver manager finds the corresponding data source specifi cation it loads the associated driver shared library the driver can retrieve information about the data source from the odbc ini file m If the driver manager cannot find the corresponding data source specification it locates the default data source specification and loads the associated driver
540. ue points to an array of lengths Pointer to storage for the current row number As each row of parameter values is processed pirow is set to the number of that row No row number will be returned if pirow is set to a null pointer SQL_SUCCESS SOL_SUCCESS_WITH_INFO SQL_ERROR or Diagnostics SQLParamOptions When SQLParamOptions returns SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value may be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLParamOptions and explains each one 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 S1000 S1001 S1010 S1107 Error General warning General error Memory allocation failure Function sequence error Row value out of range 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 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 SQLExecute or SQLExecDirect was called for the hstmt and returned SQL_NEED
541. ue buffer is not guaranteed to be set until all the results have been fetched If the application calls SQLParamOptions to specify multiple values for each parameter pcbValue points to an array of SDWORD values These values can be any of the values listed earlier in this section and are processed with a single SOL statement 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 SQLPutData Parameters whose data is passed with SQLPutData are known as data at execution parameters These are commonly used to send data for SQL_LONGVARBINARY and SQL_LONGVARCHAR parameters and can be mixed with other parameters 13 34 INFORMIX CLI Programmer s Manual SQLBindParameter To pass 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 pebValue buffer m For data at execution parameters the application
542. ue to SQL_NULL_DATA m If the number of bytes available to return cannot be determined in advance the driver sets pcbValue to SQL_NO_TOTAL When an application uses SOLExtendedFetch to retrieve more than one row of data it needs to call SQLBindCol 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 rowset buffers For additional information about binding rowset buffers see Usage on page 13 131 An application can call SQLBindCol 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 SQLExtendedFetch is called To unbind a single bound column an application calls SQLBindCol and specifies a null pointer for rgbValue if rgbValue is a null pointer and the column is not bound SOLBindCol returns SQL_SUCCESS To unbind all bound columns an application calls SOLFreeStmt with the SQL_UNBIND option INFORMIX CLI Function Reference 13 21 SQLBindCol Code Example In the following example an application executes a SELECT statement to return a result set of the employee names ages and birthdays which is sorted by birthday It then calls SQLBindCol to bind the colu
543. um length value for the corresponding 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 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 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 13 8 SQL TablePrivileges 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 it is returned by SQLTablePrivileges 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 a
544. umn 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 if 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 SQLGetData after the driver attempts to convert the data The last column lists the SQLSTATE returned for each outcome by SQLExtendedFetch SQLFetch or SQLGetData INFORMIX CLI Programmer s Manual SQL to C Character If the fCType argument in SQLBindCol or SQLGetData contains a value for an ODBC C data type that is not shown in the table for a given ODBC SQL data type SOLExtendedFetch SQLFetch or SQLGetData returns SQLSTATE 07006 Restricted data type attribute violation If the fCType argument contains a value that specifies a conversion from a driver specific SQL data type to an ODBC C data type and this conversion is not supported by the driver SQLEx tendedFetch SQLFetch or SQLGetData returns SQLSTATE S1C00 Driver not capable Although itis not shown in the tables in this appendix the pcbValue argument contains SQL_NULL_DATA when the SQL data value is NULL For an expla nation of the use of pcbValue when multiple calls are made to retrieve data see Usage on page 13 163 When SQL data is converted to chara
545. uncating data maximum data length 13 294 output buffers 3 7 SQLBindCol 13 22 SQLBindParameter 13 34 SQLFetch 13 150 SQLGetData 13 174 translation shared libraries 15 6 15 10 See also Binary data See also Character data Two phase commit 13 329 Typographical Conventions Intro 8 U Unbinding columns 13 23 13 156 Unbinding parameters 13 156 Underscore _ 13 10 UNION clauses 13 213 Unloading drivers 13 81 UPDATE statements affected rows 13 272 bulk 13 241 privileges 13 67 qualifier usage in 13 207 See also SQLSetPos Updates positioned See Positioned UPDATE statements User names maximum length 13 203 retrieving 13 213 V Values procedure return 13 31 Version DBMS 13 195 driver number 13 197 ODBC version 13 197 driver manager 13 205 Version compatibility default C data types C 6 information types 13 187 number of input parameters 13 261 number of output parameters 13 261 number of result sets 13 261 parameter binding 13 287 positioned statements 7 14 Index 13 SQLBindParameter 13 179 13 287 SQLForeignKeys 13 151 SQLSetParam 13 179 13 287 Versioning isolation level 13 196 VIEW table type 13 325 Views 13 9 W Window handles null 14 5 parent ConfigDSN 14 5 quiet mode 13 280 See also SQLDriverConnect Windows 95 ODBC INI 1 7 2 17 Windows NT ODBC INI 1 7 2 17 Windows NT registry data sources adding 14 5 configuring 14 6 removing 14 7 Symbols Percent sign 13 10 13
546. unication link failure Invalid authori zation specification Data source not found and no default driver specified Specified driver could not be loaded Driver SQLAI locEnv failed Driver SQLAIlocCo nnect failed Driver SQLSetCon nectOption failed Unable to load translation shared library Data source name too long SQLBrowseConnect Description 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 DM INFORMIX CLI cannot find the odbc ini file DM The driver listed in the data source specification 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 SQLAllocEnv function and the driver returned an error DM During SOLBrowseConnect the driver manager called the driver SQLAllocConnect function and the driver returned an error DM During SOLBrowseConnect the driver manager called the driver SQLSetConnectOption function and the driver returned an erro
547. upported INFORMIX CLI Function Reference 13 211 SQL Getinfo 13 212 with the hdbc UDWORD fFuncs SQLGetInfo hdbc SQL_STRING_FUNCTIONS PTR amp fFuncs sizeof fFuncs NULL else 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 INFORMIX CLI Programmer s Manual For example an application could use the following code to determine whether the SUBSTRING scalar function is supported by the driver associated if fFuncs amp SQL_FN_STR_SUBSTRING SUBSTRING supported SUBSTRING not supported See SQLGetConnectOption SQLGetFunctions SOLGetStmtOption SQLGetTypelInfo SQL GetStmtOption SQLGetStmt Option SQLGetStmtOption returns the current setting of a statement option Syntax RETCODE SQLGetStmtOption hstmt fOption pvParam The SQLGetStmtOption function accepts the following arguments Type Argument Use Description HSTMT hstmt Input Statement handle UWORD fOption Input Option to retrieve PTR poParam 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 SQL_ERROR or SQL_INVALID_HANDLE INFORMIX CLI Function Reference
548. urred when the rows were first fetched However it is required to return SQLSTATE 01501 Error in row for each row in which an error originally occurred and to return SQL_SUCCESS_WITH_INFO For example a static cursor that maintains a cache might cache row status information so it can determine which rows contain errors but might not cache the SQLSTATE associated with those errors Error rows do not affect relative cursor movements For example suppose the result set size is 100 and the rowset size is 10 If the current rowset is rows 11 through 20 and the element in the rgfRowStatus array for row 11 is SQL_ROW_ERROR calling SQLExtendedFetch with the SQL_FETCH_NEXT fetch type still returns rows 21 through 30 If the driver returns any warnings such as SQLSTATE 01004 Data truncated it returns warnings that apply to the entire rowset or to unknown rows in the rowset 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 Important If an application specifies SQL_FETCH
549. used by the TIMESTAMP data type For example if a time stamp does not use seconds or fractional seconds the precision is 16 the number of characters in the yyyy mm dd hh mm format If a time stamp uses thousandths of a second the precision is 23 the number of characters in the yyyy mm dd hh mm ss fff format 1 of 2 Data Types C 9 Scale fSqlType Precision a For an ODBC 1 0 application calling SOLSetParam in an ODBC 2 0 driver when pebValue is SQL_DATA_AT_EXEC cbColDef must be set to the total length of the data to be sent not the precision as defined in this table gt Tf the driver cannot determine the column or parameter length it returns SQL_NO_TOTAL The cbColDef argument of SOLBindParameter is ignored for this data type 2 of 2 Scale The scale of anumeric column or parameter refers to the maximum number of digits to the right of the decimal point For approximate floating point number columns or parameters the scale is undefined because the number of digits to the right of the decimal point is not fixed For the SQL_DECIMAL and SQL_NUMERIC data types the maximum scale is generally the same as the maximum precision However some data sources impose a separate limit on the maximum scale To determine the minimum and maximum scales allowed for a data type an application calls SQLGetTypelInfo The following table defines the scale for each ODBC SQL data type fSqlType Scale SQL_CHAR No
550. ust specify a specific driver the Informix driver and data source INFORMIX CLI provides functions that allow different methods for connecting to a data source Connecting with SQLConnect Your INFORMIX CLI application passes the following information to the driver in a call to SQLConnect m Data source name is the name of the data source being requested by the application m UserID is the login ID or account name for access to the data source if appropriate optional m Passwords is a character string associated with the user ID that allows access to the data source optional Connecting to a DataSource 5 5 Connecting to a Data Source with SQLDriverConnect 5 6 When your application calls SQLConnect the driver manager uses the data source name to read the name of the driver shared library from the appro priate section of the odbc ini file It then loads the driver shared library and passes the SQLConnect arguments to it If the driver needs additional infor mation to connect to the data source it reads this information from the same section of the odbc ini file If the application specifies a data source name that is not in the odbc ini file or if the application does not specify a data source name the driver manager 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 def
551. 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 cbInfo ValueMax the information in rgbInfoValue is truncated to cbInfoValueMax 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 Diagnostics SQLGetInfo When SQLGetInfo returns either SQL_SUCCESS_WITH_INFO or SQL_ERROR an associated SQLSTATE value can be obtained by calling SQLError The following table lists the SQLSTATE values commonly returned by SQLGetInfo 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 SQLSTATE value is SQL_ERROR unless noted otherwise SQLSTATE 01000 01004 08003 22003 S1000 S1001 Error General warning Data truncated Connection not open Numeric value out of range General error Memory allocation failure Description INFORMIX CLI informational message Function returns SQL_SUCCESS_WITH_INFO The buffer rgbInfo Value was not large enough
552. value or current date can be used on columns of a result set and on columns that restrict rows of a result set The escape clause that ODBC uses for scalar functions is shown in the following example vendor Microsoft product ODBC fn scalar function The shorthand syntax for scalar functions is as follows fn scalar function INFORMIX CLI Programmer s Manual Using ODBC Extensions to SQL For example each of the following statements creates the same result set of uppercase employee names The first statement uses the escape clause syntax The second statement uses the shorthand syntax The third statement uses the native syntax for Informix for UNIX and is not interoperable among DBMSs SELECT vendor Microsoft product ODBC fn LENGTHCNAME FROM EMPLOYEE SELECT fn LENGTH NAME FROM EMPLOYEE SELECT length NAME FROM EMPLOYEE To determine which scalar functions are supported by a data source an appli cation calls SQLGetInfo with the SQL_NUMERIC_FUNCTIONS SQL_STRING_FUNCTIONS SQL_SYSTEM_FUNCTIONS and SQL_TIMEDATE_FUNCTIONS flags For more information on scalar functions that Informix database servers support refer to Informix Guide to SQL Syntax LIKE Predicate Escape Characters In a LIKE predicate the percent sign matches zero or more of any character and the underscore character _ matches any character The percent and underscore characters can be used as literals in a LIKE predicate by
553. vels 1 16 SQL conformance 1 14 supported ODBC extensions to SQL 1 14 Informix driver UNIX data source connection using connection string 2 13 2 28 Informix driver Windows adding data sources 2 16 INFORMIX CLI architecture 1 3 Data types 1 15 INFORMIX CLI driver data types supported 1 15 for UNIX adding data sources 2 6 Index 5 data source connection 2 11 PATH variable setting 2 4 setting INFORMIXDIR environment variable 2 4 for Windows modifying data sources 2 24 system requirements 2 15 INFORMIXDIR environment variable 2 4 Input buffers 3 5 Input parameters 13 30 Input output parameters 13 31 INSERT statements affected rows 13 272 privileges 13 67 qualifier usage in 13 207 SQLParamOptions 13 241 See also SQLSetPos Installation See odbcinst ini file Integer data converting to C C 18 converting to SQL C 29 specifying conversions SQLBindCol 13 19 SQLBindParameter 13 31 SQLGetData 13 167 Integrity enhancement facility IEF 13 205 B 1 Interoperability affected rows 7 4 buffer length 3 5 cursor names 13 285 default C data type C 6 functionality 13 188 functions 13 188 procedure parameters 6 17 pseudo columns 13 305 SQL statements ALTER TABLE 6 3 13 218 COMMIT 6 9 13 120 13 127 13 250 CREATE TABLE 6 3 13 218 ODBC extensions 6 12 ROLLBACK 13 120 13 127 13 250 syntax B 1 SQLGetData 7 7 7 9 13 174 transactions 6 9 transferring data C 8 6 INFORMIX CLI Programmer s Manual Intervals datetime 1
554. ver 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 INFORMIX CLI can convert character C data to date or time stamp SQL data as specified in the previous table C to SQL Numeric The numeric ODBC C data types are found in the following list SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_STINYINT SQL_C_SLONG SQL_C_SHORT SQL_C_SSHORT SQL_C_TINYINT SQL_C_UTINYIN SQL_C_ULONG SQL_C_USHORT Data Types C 29 C to SQL Numeric C 30 fSqlType SQL_CHAR SQL_VARCHAR SQL_LONGVARCHAR SQL_DECIMAL SQL_SMALLINT SQL_INTEGER SQL_REAL SQL_DOUBLE INFORMIX CLI Programmer s Manual Test Number of digits lt Column length Number of whole as opposed to fractional digits lt Column length Number of whole as opposed to fractional digits gt Column length Data converted without truncation Data converted with truncation of fractional digits Conversion of data would result in loss of whole as opposed to fractional digits Data is within the range of the data type to which the number is being converted Data is outside the range of the data type to which the number is being converted The following table shows the ODBC SQL data types to which numeric C data can be converted For an explanation o
555. view of the Initialization Files Understanding the odbcinst ini File Understanding the odbc ini File File Format for odbc ini ODBC Data Sources Data Source Specification Default Data Source Specification ODBC Options File Examples for odbc ini ODBC Conformance Levels API Conformance Level of INFORMIX CLI SQL Conformance Level of INFORMIX CLI Mapping Data Types Supported Isolation and Lock Levels 1 3 1 5 1 6 1 6 1 7 1 8 1 9 1 10 1 10 1 11 1 12 1 12 1 14 1 15 1 16 1 2 INFORMIX CLI Programmer s Manual his chapter introduces INFORMIX CLI and describes its relationship to ODBC describes the format of the initialization files lists the API and SQL grammar conformance levels and describes the error message format What Is INFORMIX CLI INFORMIX CLI is a call level interface CLI for SQL that provides a library of C language function calls that support SQL statements INFORMIX CLI is based on the Microsoft Open Database Connectivity ODBC 2 5 Specification INFORMIX CLI applications enable ODBC functionality through the use of the INFORMIX CLI library The member functions and constants definedin the INFORMIX CLI library correspond to specific ODBC functions and constants except where noted otherwise in this manual The INFORMIX CLI library includes two components the driver manager and the driver The driver manager provides information to an application lo
556. ws for specification of result storage before or after the results are available Results can be determined and appropriate action taken without being limited to a specific set of data structures that were defined prior to the request Deferral of storage specification is called late binding of variables Overview of INFORMIX CLI 1 5 Overview of the Initialization Files files ODBC Drivers Driver Specification Default Driver Specification ODBC Translators Translator Specification 1 6 INFORMIX CLI Programmer s Manual Overview of the Initialization Files The odbcinst ini and odbc ini initialization files are created when you install INFORMIX CLI The driver manager uses the odbcinst ini file to determine which drivers and translators are currently installed The odbc ini file is a template file that contains your data source configuration information The following sections describe the format and structure of these initialization Understanding the odbcinst ini File The odbcinst ini file contains the following sections This section lists the description the Informix driver This section lists the driver shared library and attribute keywords of the Informix driver This section specifies the default driver to be used when none is specified The default driver is the Informix driver This section lists the description of each available translator Each translator described in the ODBC Translators section
557. y allocation The prepared SQL string can contain any of the valid preparable functions as defined by the X Open specifi cation including ALTER CREATE cursor specification searched DELETE dynamic SQL positioned DELETE DROP GRANT INSERT REVOKE searched UPDATE or dynamic SQL positioned UPDATE Dynamic SQL ALLOCATE DESCRIPTOR and dynamic SQL SET DESCRIPTOR ALLOCATE DESCRIPTOR would normally be issued on the first call to SOLBindPa rameter for an hstmt Alternatively ALLOCATE DESCRIPTOR can be called during SOLAIlocStmt although this call would not be needed by SQL statements that do not contain embedded parameters The descriptor name is generated by the driver The specified cursor name is used in the DECLARE CURSOR statement generated by SQLExecute or SQLExecDirect Driver cursor name management 1 of 3 INFORMIX CLI Function SQLExecute SQLExecDirect SQLNumResultCols SQLColAttributes SQLDescribeCol SQLBindCol SQLFetch Statement EXECUTE or DECLARE CURSOR and OPEN CURSOR EXECUTE IMMEDIATE or DECLARE CURSOR and OPEN CURSOR GET DESCRIPTOR GET DESCRIPTOR GET DESCRIPTOR none FETCH Comparison Between INFORMIX CLI and Embedded SQL INFORMIX CLI to Embedded SQL Comments Dynamic SQL EXECUTE If the SQL statement requires a cursor then a dynamic SQL DECLARE CURSOR statement and a dynamic SQL OPEN are issued at this time The INFORMIX CLI function call provi
558. ype exact numeric type approximate numeric type bit type binary type date type time type timestamp type date separator Extended date type date types Extended For example DATE date value Extended years value date separator months value date separator days value days value digit digit Extended digit 0111213141516171819 Minimum distinct function Core AVG COUNT MAX MIN SUM DISTINCT column name dynamic parameter Minimum empty string Extended of 11 SQL Grammar B 13 Hements Used in SQL Statements B 14 Element SQL Conformance Level escape character character exact numeric literal unsigned integer unsigned integer unsigned integer unsigned integer exact numeric type exact numeric types For example DECIMAL SMALLINT or INTEGER exists predicate EXISTS sub query exponent unsigned integer expression term expression term factor primary hours value digit digit index identifier user defined name index name index qualifier index identifier index qualifier user defined name in predicate expression NOT IN value value sub query insert value dynamic parameter literal NULL USER keyword see list of reserved keywords length unsigned integer letter lower case letter upper case letter like predi
559. ytes of data are pertinent to the client While eliminating SQL_LLONGVARCHAR and SQL_LONGVARBINARY data from the result set is ideal in terms of performance many times long data must be retrieved Consider however that most users do not want to see 100 kilobytes or more of textual information on the screen What techniques if any are available to limit the amount of data retrieved Many application developers mistakenly assume that if they call SQLGetData with a container of size x that the ODBC driver only retrieves x bytes of information from the server Because SQLGetData can be called multiple times for any one column most drivers optimize their network use by retrieving long data in large chunks and then returning it to the user when requested Example char CaseContainer 1000 rc SQLExecDirect hstmt SELECT CaseHistory FROM Cases WHERE CaseNo 71164 SQL_NTS re SQLFetch hstmt re SQLGetData hstmt 1 CaseContainer SWORD sizeof CaseContainer At this point it is more likely that an ODBC driver retrieves 64 kilobytes of information from the server instead of 1000 bytes One 64 kilobytes retrieval is less expensive than sixty four 1000 byte retrievals in terms of network access Unfortunately the application might not call SQLGetData again thus the first and only retrieval of CaseHistory was slowed by the fact that 64 kilobytes of data had to be sent across the network Designing Performance Ori

Informix CLI Programmer`s Manual, Version 2.5

Contents

Download Pdf Manuals

Related Search

Related Contents