File: prguide6.htm

package info (click to toggle)
solid-doc 2.2-1
links: PTS
area: non-free
in suites: potato, slink
size: 3,436 kB
ctags: 11,371
sloc: makefile: 58; sh: 2
file content (902 lines) | stat: -rw-r--r-- 49,387 bytes
parent folder | download | duplicates (2)
<HTML>
<HEAD>
<TITLE>prguide.htm</TITLE>
<LINK REL="ToC" HREF="httoc.htm">
<LINK REL="Index" HREF="htindex.htm">
<LINK REL="Next" HREF="prguide7.htm">
<LINK REL="Previous" HREF="prguide5.htm"></HEAD>
<BODY BGCOLOR="#FFFFFF">
<P ALIGN=CENTER>
<A HREF="prguide5.htm" TARGET="_self"><IMG SRC="graprev.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Previous Page"></A>
<A HREF="httoc.htm" TARGET="_self"><IMG SRC="gratoc.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="TOC"></A>
<A HREF="htindex.htm" TARGET="_self"><IMG SRC="graindex.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Index"></A>
<A HREF="prguide7.htm" TARGET="_self"><IMG SRC="granext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>
<HR ALIGN=CENTER>
<P>
<UL>
<LI>
<A HREF="#E9E7" >Executing SQL Statements</A>
<UL>
<LI>
<A HREF="#E10E23" >Allocating a Statement Handle</A>
<LI>
<A HREF="#E10E24" >Executing an SQL Statement</A>
<UL>
<LI>
<A HREF="#E11E21" >Prepared Execution</A>
<LI>
<A HREF="#E11E22" >Direct Execution</A></UL>
<LI>
<A HREF="#E10E25" >Setting Parameter Values</A>
<LI>
<A HREF="#E10E26" >Performing Transactions</A>
<LI>
<A HREF="#E10E27" >ODBC Extensions for SQL Statements</A>
<UL>
<LI>
<A HREF="#E11E23" >Retrieving Information About the Data Source&#146;s Catalog</A>
<LI>
<A HREF="#E11E24" >Sending Parameter Data at Execution Time</A>
<LI>
<A HREF="#E11E25" >Specifying Arrays of Parameter Values</A>
<LI>
<A HREF="#E11E26" >Executing Functions Asynchronously</A>
<LI>
<A HREF="#E11E27" >Using ODBC Extensions to SQL</A>
<UL>
<LI>
<A HREF="#E12E9" >Date, Time, and Timestamp Data</A>
<LI>
<A HREF="#E12E10" >Scalar Functions</A>
<LI>
<A HREF="#E12E11" >LIKE Predicate Escape Characters</A>
<LI>
<A HREF="#E12E12" >Outer Joins</A>
<LI>
<A HREF="#E12E13" >Procedures</A></UL>
<LI>
<A HREF="#E11E28" >Additional Extension Functions</A></UL></UL></UL>
<HR ALIGN=CENTER>
<A NAME="E9E7"></A>
<H1>
<FONT FACE="Arial"><B>EXECUTING SQL STATEMENTS</B><A NAME="I2"></A><A NAME="I3"></A></FONT></H1>
<BR>
<BLOCKQUOTE>
<P>An application can submit any SQL statement supported by a data source. ODBC defines a standard syntax for SQL statements. For maximum interoperability, an application should only submit SQL statements that use this syntax; the driver will translate these statements 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.<A NAME="I4"></A><A NAME="I5"></A><A NAME="I6"></A><A NAME="I7"></A><A NAME="I8"></A><A NAME="I9"></A><A NAME="I10"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note For <B>CREATE TABLE</B> and <B>ALTER TABLE</B> statements, applications should use the data type name returned by <B>SQLGetTypeInfo</B> in the TYPE_NAME column, rather than the data type name defined in the SQL grammar.<A NAME="I11"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Note that statements can be executed a single time with <B>SQLExecDirect</B> or prepared with <B>SQLPrepare</B> and executed multiple times with <B>SQLExecute</B>. Note also that an application calls <B>SQLTransact</B> to commit or roll back a transaction.
</BLOCKQUOTE>
<A NAME="E10E23"></A>
<H2>
<FONT FACE="Arial"><B>Allocating a Statement Handle</B><A NAME="I12"></A><A NAME="I13"></A></FONT></H2>
<BLOCKQUOTE>
<P>Before an application can submit an SQL statement, it must allocate a statement handle for the statement. To allocate a statement handle, an application:<A NAME="I14"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Declares a variable of type HSTMT. For example, the application could use the declaration:
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<PRE>   HSTMT hstmt1;<A NAME="I15"></A></PRE></BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>2. Calls <B>SQLAllocStmt</B> and passes it the address of the variable and the connected <I>hdbc</I> with which to associate the statement. The driver allocates memory to store information about the statement, associates the statement handle with the <I>hdbc</I>, and returns the statement handle in the variable.
</BLOCKQUOTE></UL>
<A NAME="E10E24"></A>
<H2>
<FONT FACE="Arial"><B>Executing an SQL Statement</B><A NAME="I16"></A><A NAME="I17"></A><A NAME="I18"></A><A NAME="I19"></A><A NAME="I20"></A></FONT></H2>
<BLOCKQUOTE>
<P>An application can submit an SQL statement for execution in two ways:<A NAME="I21"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI><B>Prepared    </B><B> </B>Call <B>SQLPrepare</B> and then call <B>SQLExecute</B>.<A NAME="I22"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>Direct    </B><B> </B>Call <B>SQLExecDirect</B>.<A NAME="I23"></A><A NAME="I24"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>These options are similar, though not identical to, the prepared and immediate options in embedded SQL. For a comparison of the ODBC functions and embedded SQL, see Appendix E, &quot;Comparison Between Embedded SQL and ODBC.&quot;
</BLOCKQUOTE>
<A NAME="E11E21"></A>
<H3>
<FONT FACE="Arial">Prepared Execution<A NAME="I25"></A></FONT></H3>
<BLOCKQUOTE>
<P>An application should prepare a statement before executing it if either of the following is true:<A NAME="I26"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>The application will execute the statement more than once, possibly with intermediate changes to parameter values.<A NAME="I27"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The application needs information about the result set prior to execution.<A NAME="I28"></A><A NAME="I29"></A><A NAME="I30"></A><A NAME="I31"></A><A NAME="I32"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>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 as 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 to the data source instead of the entire statement.<A NAME="I33"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Important Committing or rolling back a transaction, either by calling <B>SQLTransact</B> or by using the SQL_AUTOCOMMIT connection option, can cause the data source to delete the access plans for all <I>hstmts</I> on an <I>hdbc</I>. For more information, see the SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR information types in <B>SQLGetInfo</B>.<A NAME="I34"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To prepare and execute an SQL statement, an application:<A NAME="I35"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Calls <B>SQLPrepare</B> to prepare the statement.<A NAME="I36"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>2. Sets the values of any statement parameters. For more information, see &quot;Setting Parameter Values&quot; later in this chapter.<A NAME="I37"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>3. Retrieves information about the result set, if necessary. For more information, see &quot;Determining the Characteristics of a Result Set&quot; in Chapter 7, &quot;Retrieving Results.&quot;<A NAME="I38"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>4. Calls <B>SQLExecute</B> to execute the statement.<A NAME="I39"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>5. Repeats steps 2 through 4 as necessary.
</BLOCKQUOTE></UL>
<A NAME="E11E22"></A>
<H3>
<FONT FACE="Arial">Direct Execution<A NAME="I40"></A></FONT></H3>
<BLOCKQUOTE>
<P>An application should execute a statement directly if both of the following are true:<A NAME="I41"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>The application will execute the statement only once.<A NAME="I42"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The application does not need information about the result set prior to execution.<A NAME="I43"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>To execute an SQL statement directly, an application:<A NAME="I44"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Sets the values of any statement parameters. For more information, see &quot;Setting Parameter Values&quot; later in this chapter.<A NAME="I45"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>2. Calls <B>SQLExecDirect</B> to execute the statement.
</BLOCKQUOTE></UL>
<A NAME="E10E25"></A>
<H2>
<FONT FACE="Arial"><B>Setting Parameter Values</B><A NAME="I46"></A><A NAME="I47"></A></FONT></H2>
<BLOCKQUOTE>
<P>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:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>INSERT INTO EMPLOYEE (NAME, AGE, HIREDATE) 
<BR>   VALUES (?, ?, ?)<A NAME="I48"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application uses parameter markers instead of literal values if:<A NAME="I49"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>It needs to execute the same prepared statement several times with different parameter values.<A NAME="I50"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The parameter values are not known when the statement is prepared.<A NAME="I51"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>The parameter values need to be converted from one data type to another.<A NAME="I52"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>To set a parameter value, an application performs the following steps in any order:<A NAME="I53"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Calls <B>SQLBindParameter</B> to bind a storage location to a parameter marker and 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.<A NAME="I54"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Places the parameter&#146;s value in the storage location.<A NAME="I55"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>These steps can be performed before or after a statement is prepared, but must be performed before a statement is executed.<A NAME="I56"></A><A NAME="I57"></A><A NAME="I58"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Parameter values must be placed in storage locations in the C data types specified in <B>SQLBindParameter</B>. For example:
</BLOCKQUOTE>
<TABLE WIDTH=600 >
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P><B>Parameter Value</B>
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E24"></A>
<P>SQL Data Type
</TD><TD WIDTH=120 VALIGN=top >
<A NAME="E7E24"></A>
<P>C Data Type
</TD><TD WIDTH=96 VALIGN=top >
<A NAME="E7E24"></A>
<P>Stored Value</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>ABC
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E25"></A>
<P>SQL_CHAR
</TD><TD WIDTH=120 VALIGN=top >
<A NAME="E7E25"></A>
<P>SQL_C_CHAR
</TD><TD WIDTH=96 VALIGN=top >
<A NAME="E7E25"></A>
<P>ABC\0 <SUP>a</SUP></TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>10
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E26"></A>
<P>SQL_INTEGER
</TD><TD WIDTH=120 VALIGN=top >
<A NAME="E7E26"></A>
<P>SQL_C_SLONG
</TD><TD WIDTH=96 VALIGN=top >
<A NAME="E7E26"></A>
<P>10</TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>10
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E27"></A>
<P>SQL_INTEGER
</TD><TD WIDTH=120 VALIGN=top >
<A NAME="E7E27"></A>
<P>SQL_C_CHAR
</TD><TD WIDTH=96 VALIGN=top >
<A NAME="E7E27"></A>
<P>10\0 <SUP>a</SUP></TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>1 p.m.
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E28"></A>
<P>SQL_TIME
</TD><TD WIDTH=120 VALIGN=top >
<A NAME="E7E28"></A>
<P>SQL_C_TIME
</TD><TD WIDTH=96 VALIGN=top >
<A NAME="E7E28"></A>
<P>13,0,0 <SUP>b</SUP></TD>
</TR>
<TR>
<TD WIDTH=120 VALIGN=top >
<BLOCKQUOTE>
<P>1 p.m.
</BLOCKQUOTE></TD>
<TD WIDTH=120 VALIGN=top >
<A NAME="E7E29"></A>
<P>SQL_TIME
</TD><TD WIDTH=120 VALIGN=top >
<A NAME="E7E29"></A>
<P>SQL_C_CHAR
</TD><TD WIDTH=96 VALIGN=top >
<A NAME="E7E29"></A>
<P>{t '13:00:00'}\0<SUP>a,c</SUP></TD>
</TR>
<TR>
<TD COLSPAN=4 WIDTH=456 VALIGN=top >
<BLOCKQUOTE>
<P>a &quot;\0&quot; represents a null-termination byte; the null termination byte is required only if the parameter length is SQL_NTS.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>b The numbers in this list are the numbers stored in the fields of the TIME_STRUCT structure.
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>c The string uses the ODBC date escape clause. For more information, see &quot;Date, Time, and Timestamp Data&quot; later in this chapter.
</BLOCKQUOTE></TD></TR></TABLE><A NAME="I59"></A><A NAME="I60"></A>
<BLOCKQUOTE>
<P>Storage locations remain bound to parameter markers until the application calls <B>SQLFreeStmt</B> 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 <B>SQLBindParameter</B>. 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.
</BLOCKQUOTE>
<A NAME="E10E26"></A>
<H2>
<FONT FACE="Arial"><B>Performing Transactions</B><A NAME="I61"></A><A NAME="I62"></A><A NAME="I63"></A><A NAME="I64"></A><A NAME="I65"></A><A NAME="I66"></A><A NAME="I67"></A><A NAME="I68"></A><A NAME="I69"></A><A NAME="I70"></A></FONT></H2>
<BLOCKQUOTE>
<P>In <I>auto-commit</I> mode, every SQL statement is a complete transaction, which is automatically committed. In <I>manual-commit</I> 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 <B>SQLTransact</B>.<A NAME="I71"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If a driver supports the SQL_AUTOCOMMIT connection option, the default transaction mode is auto-commit; otherwise, it is manual-commit. An application calls <B>SQLSetConnectOption</B> to switch between manual-commit and auto-commit mode. Note that if an application switches from manual-commit to auto-commit mode, the driver commits any open transactions on the connection.<A NAME="I72"></A><A NAME="I73"></A><A NAME="I74"></A><A NAME="I75"></A><A NAME="I76"></A><A NAME="I77"></A><A NAME="I78"></A><A NAME="I79"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Applications should call <B>SQLTransact</B>, rather than submitting a <B>COMMIT</B> or <B>ROLLBACK</B> statement, to commit or roll back a transaction. The result of a <B>COMMIT</B> or <B>ROLLBACK</B> statement depends on the driver and its associated data source.<A NAME="I80"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Important Committing or rolling back a transaction, either by calling <B>SQLTransact</B> or by using the SQL_AUTOCOMMIT connection option, can cause the data source to close the cursors and delete the access plans for all <I>hstmts</I> on an <I>hdbc</I>. For more information, see the SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR information types in <B>SQLGetInfo</B>.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<A NAME="E10E27"></A>
<H2>
<FONT FACE="Arial"><B>ODBC Extensions for SQL Statements</B><A NAME="I81"></A></FONT></H2>
<BLOCKQUOTE>
<P>ODBC extends the X/Open and SQL Access Group Call Level Interface to provide additional functions related to SQL statements. ODBC also extends the X/Open and SQL Access Group SQL CAE specification (1992) to provide common extensions to SQL. The remainder of this chapter describes these functions and SQL extensions.<A NAME="I82"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To determine if a driver supports a specific function, an application calls <B>SQLGetFunctions</B>. To determine if a driver supports a specific ODBC extension to SQL, such as outer joins or procedure invocation, an application calls <B>SQLGetInfo</B>.
</BLOCKQUOTE>
<A NAME="E11E23"></A>
<H3>
<FONT FACE="Arial">Retrieving Information About the Data Source&#146;s Catalog<A NAME="I83"></A></FONT></H3>
<BLOCKQUOTE>
<P>The following functions, known as catalog functions, return information about a data source&#146;s catalog:<A NAME="I84"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI><B>SQLTables </B>returns the names of tables stored in a data source.<A NAME="I85"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLTablePrivileges </B>returns the privileges associated with one or more tables.<A NAME="I86"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLColumns</B> returns the names of columns in one or more tables.<A NAME="I87"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLColumnPrivileges</B> returns the privileges associated with each column in a single table.<A NAME="I88"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLPrimaryKeys</B> returns the names of columns that comprise the primary key of a single table.<A NAME="I89"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLForeignKeys</B> returns the names of columns in a single table that are foreign keys. It also returns the names of columns in other tables that refer to the primary key of the specified table.<A NAME="I90"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLSpecialColumns</B> returns information about the optimal set of columns that uniquely identify a row in a single table or the columns in that table that are automatically updated when any value in the row is updated by a transaction.<A NAME="I91"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLStatistics</B> returns statistics about a single table and the indexes associated with that table.<A NAME="I92"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLProcedures</B> returns the names of procedures stored in a data source.<A NAME="I93"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLProcedureColumns</B> returns a list of the input and output parameters, as well as the names of columns in the result set, for one or more procedures.<A NAME="I94"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>Each function returns the information as a result set. An application retrieves these results by calling <B>SQLBindCol</B> and <B>SQLFetch</B>.
</BLOCKQUOTE>
<A NAME="E11E24"></A>
<H3>
<FONT FACE="Arial">Sending Parameter Data at Execution Time<A NAME="I95"></A><A NAME="I96"></A><A NAME="I97"></A><A NAME="I98"></A><A NAME="I99"></A></FONT></H3>
<BLOCKQUOTE>
<P>To send parameter data at statement execution time, such as for parameters of the SQL_LONGVARCHAR or SQL_LONGVARBINARY types, an application uses the following three functions:<A NAME="I100"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI><B>SQLBindParameter</B><A NAME="I101"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLParamData</B><A NAME="I102"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>SQLPutData</B><A NAME="I103"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>To indicate that it plans to send parameter data at statement execution time, an application calls <B>SQLBindParameter</B> and sets the <I>pcbValue</I> buffer for the parameter to the result of the SQL_LEN_DATA_AT_EXEC(<I>length</I>) macro. If the <I>fSqlType</I> argument is SQL_LONGVARBINARY or SQL_LONGVARCHAR and the driver returns &quot;Y&quot; for the SQL_NEED_LONG_DATA_LEN information type in <B>SQLGetInfo</B>, <I>length</I> is the total number of bytes of data to be sent for the parameter; otherwise, it is ignored.<A NAME="I104"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The application sets the <I>rgbValue</I> argument to a value that, at run time, can be used to retrieve the data. For example, <I>rgbValue</I> might point to a storage location that will contain the data at statement execution time or to a file that contains the data. The driver returns the value to the application at statement execution time.<A NAME="I105"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>When the driver processes a call to <B>SQLExecute</B> or <B>SQLExecDirect</B> and the statement being executed includes a data-at-execution parameter, the driver returns SQL_NEED_DATA. To send the parameter data, the application:<A NAME="I106"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Calls <B>SQLParamData</B>, which returns <I>rgbValue</I> (as set with <B>SQLBindParameter</B>) for the first data-at-execution parameter.<A NAME="I107"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>2. Calls <B>SQLPutData</B> one or more times to send data for the parameter. (More than one call will be 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&#150;specific.)<A NAME="I108"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>3. Calls <B>SQLParamData</B> again to indicate that all data has been sent for the parameter. If there is another data-at-execution parameter, the driver returns <I>rgbValue</I> for that parameter and SQL_NEED_DATA for the function return code. Otherwise, it returns SQL_SUCCESS for the function return code.<A NAME="I109"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>4. Repeats steps 2 and 3 for the remaining data-at-execution parameters.<A NAME="I110"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>For additional information, see the description of <B>SQLBindParameter</B> Chapter 13, &quot;Function Reference.&quot;
</BLOCKQUOTE>
<A NAME="E11E25"></A>
<H3>
<FONT FACE="Arial">Specifying Arrays of Parameter Values<A NAME="I111"></A><A NAME="I112"></A><A NAME="I113"></A><A NAME="I114"></A></FONT></H3>
<BLOCKQUOTE>
<P>To specify multiple sets of parameter values for a single SQL statement, an application calls <B>SQLParamOptions</B>. For example, if there are ten sets of column values to insert into a table &#151; and the same SQL statement can be used for all ten operations &#151; the application can set up an array of values, then submit a single <B>INSERT</B> statement.<A NAME="I115"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If an application uses <B>SQLParamOptions</B>, it must allocate enough memory to handle the arrays of values.
</BLOCKQUOTE>
<A NAME="E11E26"></A>
<H3>
<FONT FACE="Arial">Executing Functions Asynchronously<A NAME="I116"></A><A NAME="I117"></A><A NAME="I118"></A><A NAME="I119"></A><A NAME="I120"></A></FONT></H3>
<BLOCKQUOTE>
<P>By default, a driver executes ODBC functions synchronously; the driver does not return control to an application until a function call completes. If a driver supports asynchronous execution, however, an application can request asynchronous execution for the functions listed below. (All of these functions either submit requests to a data source or retrieve data. These operations may require extensive processing.)
</BLOCKQUOTE>
<TABLE WIDTH=600>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLColAttributes
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E30"></A>
<P>SQLForeignKeys
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E30"></A>
<P>SQLProcedureColumns</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLColumnPrivileges
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E31"></A>
<P>SQLGetData
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E31"></A>
<P>SQLProcedures</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLColumns
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E32"></A>
<P>SQLGetTypeInfo
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E32"></A>
<P>SQLPutData</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLDescribeCol
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E33"></A>
<P>SQLMoreResults
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E33"></A>
<P>SQLSetPos</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLDescribeParam
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E34"></A>
<P>SQLNumParams
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E34"></A>
<P>SQLSpecialColumns</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLExecDirect
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E35"></A>
<P>SQLNumResultCols
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E35"></A>
<P>SQLStatistics</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLExecute
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E36"></A>
<P>SQLParamData
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E36"></A>
<P>SQLTablePrivileges</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLExtendedFetch
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E37"></A>
<P>SQLPrepare
</TD><TD WIDTH=160 VALIGN=top >
<A NAME="E7E37"></A>
<P>SQLTables</TD>
</TR>
<TR>
<TD WIDTH=142 VALIGN=top >
<BLOCKQUOTE>
<P>SQLFetch
</BLOCKQUOTE></TD>
<TD WIDTH=153 VALIGN=top >
<A NAME="E7E38"></A>
<P>SQLPrimaryKeys
</TD><TD WIDTH=160 VALIGN=top ><A NAME="I121"></A><A NAME="I122"></A><BR></TD></TR></TABLE>
<BLOCKQUOTE>
<P>Asynchronous execution is performed on a statement-by-statement basis. To execute a statement asynchronously, an application:<A NAME="I123"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>1. Calls <B>SQLSetStmtOption</B> with the SQL_ASYNC_ENABLE option to enable asynchronous execution for an <I>hstmt</I>. (To enable asynchronous execution for all <I>hstmts</I> associated with an <I>hdbc</I>, an application calls <B>SQLSetConnectOption</B> with the SQL_ASYNC_ENABLE option.)<A NAME="I124"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>2. Calls one of the functions listed earlier in this section and passes it the <I>hstmt</I>. The driver begins asynchronous execution of the function and returns SQL_STILL_EXECUTING.
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note If the application calls a function that cannot be executed asynchronously, the driver executes the function synchronously.<A NAME="I125"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>3. Performs other operations while the function is executing asynchronously. The application can call any function with a different <I>hstmt</I> or an <I>hdbc</I> not associated with the original <I>hstmt</I>. With the original <I>hstmt</I> and the <I>hdbc</I> associated with that <I>hstmt</I>, the application can only call the original function, <B>SQLAllocStmt</B>, <B>SQLCancel</B>, or <B>SQLGetFunctions</B>.<A NAME="I126"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>4. Calls the asynchronously executing function to check if it has finished. While the arguments must be valid, the driver ignores all of them except the <I>hstmt</I> argument. For example, suppose an application called <B>SQLExecDirect</B> to execute a <B>SELECT</B> statement asynchronously. When the application calls <B>SQLExecDirect</B> again, the return value indicates the status of the <B>SELECT</B> statement, even if the <I>szSqlStr</I> argument contains an <B>INSERT</B> statement.<A NAME="I127"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI> If the function is still executing, the driver returns SQL_STILL_EXECUTING and the application must repeat steps 3 and 4. If the function has finished, the driver returns a different code, such as SQL_SUCCESS or SQL_ERROR. For information about canceling a function executing asynchronously, see &quot;Terminating Statement Processing&quot; in Chapter 9, &quot;Terminating Transactions and Connections.&quot;<A NAME="I128"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>5. Repeats steps 2 through 4 as needed.<A NAME="I129"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>To disable asynchronous execution for an <I>hstmt</I>, an application calls <B>SQLSetStmtOption</B> with the SQL_ASYNC_ENABLE option. To disable asynchronous execution for all <I>hstmts</I> associated with an <I>hdbc</I>, an application calls <B>SQLSetConnectOption</B> with the SQL_ASYNC_ENABLE option.
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>ODBC drivers for SOLID <I>Server</I> do not support asynchronous execution.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<A NAME="E11E27"></A>
<H3>
<FONT FACE="Arial">Using ODBC Extensions to SQL<A NAME="I130"></A><A NAME="I131"></A></FONT></H3>
<BLOCKQUOTE>
<P>ODBC defines the following extensions to SQL, which are common to most DBMS&#146;s:<A NAME="I132"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Date, time, and timestamp data<A NAME="I133"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Scalar functions such as numeric, string, and data type conversion functions<A NAME="I134"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI><B>LIKE</B> predicate escape characters<A NAME="I135"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Outer joins<A NAME="I136"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Procedures<A NAME="I137"></A><A NAME="I138"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>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:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>--(*vendor(</B><I>vendor-name</I><B>), product(</B><I>product-name</I><B>) </B>
<BR><B>   </B><I>extension</I><B> *)--</B><A NAME="I139"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>For the ODBC extensions to SQL, <I>product-name</I> is always &quot;ODBC&quot;, since the product defining them is ODBC. <I>Vendor-name</I> is always &quot;Microsoft&quot;, since ODBC is a Microsoft product. ODBC also defines a shorthand syntax for these extensions:
</BLOCKQUOTE>
<BLOCKQUOTE>
<P><B>{</B><I>extension</I><B>}</B><A NAME="I140"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Most DBMS&#146;s provide the same extensions to SQL as does ODBC. Because of this, an application may be able to submit an SQL statement using one of these extensions in either of two ways:<A NAME="I141"></A>
</BLOCKQUOTE>
<UL>
<BLOCKQUOTE>
<LI>Use the syntax defined by ODBC. An application that uses the ODBC syntax will be interoperable among DBMS&#146;s.<A NAME="I142"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<LI>Use the syntax defined by the DBMS. An application that uses DBMS-specific syntax will not be interoperable among DBMS&#146;s.<A NAME="I143"></A>
</BLOCKQUOTE></UL>
<BLOCKQUOTE>
<P>Due to the difficulty in implementing some ODBC extensions to SQL, such as outer joins, a driver might only implement those ODBC extensions that are supported by its associated DBMS. To determine whether the driver and data source support all the ODBC extensions to SQL, an application calls <B>SQLGetInfo</B> with the SQL_ODBC_SQL_CONFORMANCE flag. For information about how an application determines whether a specific extension is supported, see the section that describes the extension.<A NAME="I144"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note Many DBMS&#146;s provide extensions to SQL other than those defined by ODBC. To use one of these extensions, an application uses the DBMS-specific syntax. The application will not be interoperable among DBMS&#146;s.</NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E9"></A>
<H4>
<FONT>Date, Time, and Timestamp Data<A NAME="I145"></A><A NAME="I146"></A><A NAME="I147"></A><A NAME="I148"></A><A NAME="I149"></A><A NAME="I150"></A><A NAME="I151"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>The escape clauses ODBC uses for date, time, and timestamp data are:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>--(*vendor(Microsoft),product(ODBC) d '</B><I>value</I><B>' *)--</B>
<BR><B>--(*vendor(Microsoft),product(ODBC) t '</B><I>value</I><B>' *)--</B>
<BR><B>--(*vendor(Microsoft),product(ODBC) ts '</B><I>value</I><B>' *)--</B><A NAME="I152"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <B>d</B> indicates <I>value</I> is a date in the &quot;yyyy-mm-dd&quot; format, <B>t</B> indicates <I>value</I> is a time in the &quot;hh:mm:ss&quot; format, and <B>ts</B> indicates <I>value</I> is a timestamp in the &quot;yyyy-mm-dd hh:mm:ss[.f<I>...</I>]&quot; format. The shorthand syntax for date, time, and timestamp data is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>{d '</B><I>value</I><B>'}</B>
<BR><B>{t '</B><I>value</I><B>'}</B>
<BR><B>{ts '</B><I>value</I><B>'}</B><A NAME="I153"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>For example, each of the following statements updates the birthday of John Smith 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 a DATE column in DEC&#146;s Rdb and is not interoperable among DBMS&#146;s.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>UPDATE EMPLOYEE 
<BR>   SET BIRTHDAY=--(*vendor(Microsoft),product(ODBC) 
<BR>      d '1967-01-15' *)-- 
<BR>   WHERE NAME='Smith, John'
UPDATE EMPLOYEE SET BIRTHDAY={d '1967-01-15'} 
<BR>   WHERE NAME='Smith, John'
UPDATE EMPLOYEE SET BIRTHDAY='15-Jan-1967' 
<BR>   WHERE NAME='Smith, John'<A NAME="I154"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P><A NAME="I155"></A>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 John Smith in the EMPLOYEE table:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>UPDATE EMPLOYEE SET BIRTHDAY=? WHERE NAME='Smith, John'<A NAME="I156"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>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 a DATE column in DEC&#146;s Rdb and is not interoperable among DBMS&#146;s.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>&quot;--(*vendor(Microsoft),product(ODBC) 
<BR>   d '1967-01-15' *)--&quot;
&quot;{d '1967-01-15'}&quot;
&quot;'15-Jan-1967'&quot;<A NAME="I157"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can also send date, time, or timestamp values as parameters using the C structures defined by the C data types SQL_C_DATE, SQL_C_TIME, and SQL_C_TIMESTAMP.<A NAME="I158"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>To determine if a data source supports date, time, or timestamp data, an application calls <B>SQLGetTypeInfo</B>. If a driver supports date, time, or timestamp data, it must also support the escape clauses for date, time, or timestamp literals.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E10"></A>
<H4>
<FONT>Scalar Functions<A NAME="I159"></A><A NAME="I160"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>Scalar functions &#151; such as string length, absolute value, or current date &#151; can be used on columns of a result set and on columns that restrict rows of a result set. The escape clause ODBC uses for scalar functions is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>--(*vendor(Microsoft),product(ODBC) </B>
<BR><B>fn </B><I>scalar-function</I> <B>*)--</B><A NAME="I161"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <I>scalar-function</I> is one of the functions listed in Appendix F, &quot;Scalar Functions.&quot; The shorthand syntax for scalar functions is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>{fn </B><I>scalar-function</I><B>}</B><A NAME="I162"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>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 SOLID <I>Server</I> and is not interoperable among DBMS&#146;s.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SELECT --(*vendor(Microsoft),product(ODBC) 
<BR>   fn UCASE(NAME) *)-- FROM EMPLOYEE
SELECT {fn UCASE(NAME)} FROM EMPLOYEE
SELECT UCASE(NAME) FROM EMPLOYEE<A NAME="I163"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can mix scalar functions that use native syntax and scalar functions that use ODBC syntax. For example, the following statement creates a result set of last names of employees in the EMPLOYEE table. (Names in the EMPLOYEE table are stored as a last name, a comma, and a first name.) The statement uses the ODBC scalar function <B>SUBSTRING</B> and the SQL Server scalar function <B>CHARINDEX</B> and will only execute correctly on SQL Server.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SELECT {fn SUBSTRING(NAME, 1, CHARINDEX(',', NAME) &#150; 1)}    FROM EMPLOYEE<A NAME="I164"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>To determine which scalar functions are supported by a data source, an application calls <B>SQLGetInfo</B> with the SQL_NUMERIC_FUNCTIONS, SQL_STRING_FUNCTIONS, SQL_SYSTEM_FUNCTIONS, and SQL_TIMEDATE_FUNCTIONS flags.
</BLOCKQUOTE>
<BLOCKQUOTE>
<H5><B>Data Type Conversion Function</B><A NAME="I165"></A><A NAME="I166"></A><A NAME="I167"></A></H5>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>ODBC defines a special scalar function, <B>CONVERT</B>, that requests that the data source convert data from one SQL data type to another SQL data type. The escape clause ODBC uses for the <B>CONVERT</B> function is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>--(*vendor(Microsoft),product(ODBC) </B>
<BR><B>   </B><B>fn CONVERT(</B><I>value_exp</I><B>,</B> <I>data_type</I><B>) *)--</B><A NAME="I168"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <I>value_exp</I> is a column name, the result of another scalar function, or a literal value, and <I>data_type</I> is a keyword that matches the <B>#define</B> name used by an ODBC SQL data type (as defined in Appendix D, &quot;Data Types&quot;). The shorthand syntax for the <B>CONVERT</B> function is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>{fn CONVERT(</B><I>value_exp</I><B>,</B> <I>data_type</I><B>)}</B><A NAME="I169"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>For example, the following statement creates a result set of the names and ages of all employees in their twenties. It uses the <B>CONVERT</B> function to convert each employee&#146;s age from type SQL_SMALLINT to type SQL_CHAR. Each resulting character string is compared to the pattern &quot;2%&quot; to determine if the employee&#146;s age is in the twenties.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SELECT NAME, AGE FROM EMPLOYEE WHERE 
<BR>   {fn CONVERT(AGE,SQL_CHAR)} LIKE '2%'<A NAME="I170"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>To determine if the <B>CONVERT</B> function is supported by a data source, an application calls <B>SQLGetInfo</B> with the SQL_CONVERT_FUNCTIONS flag. For more information about the <B>CONVERT</B> function, see Appendix F, &quot;Scalar Functions.&quot;
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E11"></A>
<H4>
<FONT>LIKE Predicate Escape Characters<A NAME="I171"></A><A NAME="I172"></A><A NAME="I173"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>In a <B>LIKE</B> predicate, the percent character (%) matches zero or more of any character and the underscore character (_) matches any one character. The percent and underscore characters can be used as literals in a <B>LIKE</B> predicate by preceding them with an escape character. The escape clause ODBC uses to define the <B>LIKE</B> predicate escape character is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>--(*vendor(Microsoft),product(ODBC) </B>
<BR><B>   </B><B>escape '</B><I>escape-character</I><B>'</B> <B>*)--</B><A NAME="I174"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <I>escape-character</I> is any character supported by the data source. The shorthand syntax for the <B>LIKE</B> predicate escape character is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>{escape '</B><I>escape-character</I><B>'}</B><A NAME="I175"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>For example, each of the following statements creates the same result set of department names that start with the characters &quot;%AAA&quot;. The first statement uses the escape clause syntax. The second statement uses the shorthand syntax. The third statement uses the native syntax for Ingres and is not interoperable among DBMS&#146;s. Note that the second percent character in each <B>LIKE</B> predicate is a wild-card character that matches zero or more of any character.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SELECT NAME FROM DEPT WHERE NAME LIKE '\%AAA%' 
<BR>   --(*vendor(Microsoft),product(ODBC) escape '\'*)--
SELECT NAME FROM DEPT WHERE NAME LIKE '\%AAA%' 
<BR>   {escape '\'}
SELECT NAME FROM DEPT WHERE NAME LIKE '\%AAA%' 
<BR>   ESCAPE '\'<A NAME="I176"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>To determine whether <B>LIKE</B> predicate escape characters are supported by a data source, an application calls <B>SQLGetInfo</B> with the SQL_LIKE_ESCAPE_CLAUSE information type.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E12"></A>
<H4>
<FONT>Outer Joins<A NAME="I177"></A><A NAME="I178"></A><A NAME="I179"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>ODBC supports the ANSI SQL-92 left outer join syntax. The escape clause ODBC uses for outer joins is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>--(*vendor(Microsoft),product(ODBC) oj </B><I>outer-join</I><B> *)--</B><A NAME="I180"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <I>outer-join</I> is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><I>table-reference</I> <B>LEFT OUTER JOIN</B> {<I>table-reference</I> |    <I>outer-join</I>} <B>ON</B> <I>search-condition</I><A NAME="I181"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P><I>table-reference</I> specifies a table name, and <I>search-condition</I> specifies the join condition between the <I>table-references</I>. The shorthand syntax for outer joins is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>{oj</B> <I>outer-join</I><B>}</B><A NAME="I182"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>An outer join request must appear after the <B>FROM</B> keyword and before the <B>WHERE</B> clause (if one exists). For complete syntax information, see Appendix C, &quot;SQL Grammar.&quot;<A NAME="I183"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>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 Oracle and is not interoperable among DBMS&#146;s.
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>SELECT EMPLOYEE.NAME, DEPT.DEPTNAME FROM 
<BR>   --(*vendor(Microsoft),product(ODBC) oj EMPLOYEE       LEFT OUTER JOIN DEPT ON                EMPLOYEE.DEPTID=DEPT.DEPTID*)-- 
<BR>   WHERE EMPLOYEE.PROJID=544
SELECT EMPLOYEE.NAME, DEPT.DEPTNAME FROM 
<BR>   {oj EMPLOYEE LEFT OUTER JOIN DEPT ON             EMPLOYEE.DEPTID=DEPT.DEPTID} 
<BR>   WHERE EMPLOYEE.PROJID=544
SELECT EMPLOYEE.NAME, DEPT.DEPTNAME FROM EMPLOYEE, DEPT    WHERE (EMPLOYEE.PROJID=544) AND 
<BR>      (EMPLOYEE.DEPTID = DEPT.DEPTID (+))<A NAME="I184"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>To determine the level of outer joins a data source supports, an application calls <B>SQLGetInfo</B> with the SQL_OUTER_JOINS flag. Data sources can support two-table outer joins, partially support multi-table outer joins, fully support multi-table outer joins, or not support outer joins.
</BLOCKQUOTE>
<BLOCKQUOTE>
<A NAME="E12E13"></A>
<H4>
<FONT>Procedures<A NAME="I185"></A><A NAME="I186"></A><A NAME="I187"></A><A NAME="I188"></A><A NAME="I189"></A><A NAME="I190"></A><A NAME="I191"></A></FONT></H4>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>An application can call a procedure in place of an SQL statement. The escape clause ODBC uses for calling a procedure is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>--(*vendor(Microsoft),product(ODBC) </B>
<BR><B>   </B>[<B>?=</B>] <B>call</B> <I>procedure-name</I>
<BR><I>   </I><I>   </I>[<B>(</B>[<I>parameter</I>][<B>,</B>[<I>parameter</I>]]...<B>)</B>]<B> *)--</B><A NAME="I192"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>where <I>procedure-name</I> specifies the name of a procedure stored on the data source and <I>parameter</I> specifies a procedure parameter. A procedure can have zero or more parameters and can return a value. The shorthand syntax for procedure invocation is:
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE><B>{</B>[<B>?=</B>]<B>call</B> <I>procedure-name</I><I>   </I>[<B>(</B>[<I>parameter</I>][<B>,</B>[<I>parameter</I>]]...<B>)</B>]<B>}</B><A NAME="I193"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>For output parameters, <I>parameter</I> must be a parameter marker. For input and input/output parameters, <I>parameter</I> can be a literal, a parameter marker, or not specified. If <I>parameter</I> is a literal or is not specified for an input/output parameter, the driver discards the output value. If <I>parameter</I> 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 <I>parameter</I> is a parameter marker and the <I>pcbValue</I> argument in <B>SQLBindParameter</B> is SQL_DEFAULT_PARAM. If a procedure call includes parameter markers (including the &quot;?=&quot; parameter marker for the return value), the application must bind each marker by calling <B>SQLBindParameter</B> prior to calling the procedure.<A NAME="I194"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<HR ALIGN=CENTER>
<NOTE>Note For some data sources, <I>parameter</I> 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 <I>parameter</I>.<A NAME="I195"></A><A NAME="I196"></A></NOTE>
<HR ALIGN=CENTER>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>If an application specifies a return value parameter for a procedure that does not return a value, the driver sets the <I>pcbValue</I> buffer specified in <B>SQLBindParameter</B> for the parameter to SQL_NULL_DATA. If the application omits the return value parameter for a procedure returns a value, the driver ignores the value returned by the procedure.<A NAME="I197"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>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.<A NAME="I198"></A>
</BLOCKQUOTE>
<BLOCKQUOTE>
<P>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. For an example of code that calls a procedure, see <B>SQLProcedures</B> in Chapter 13, &quot;Function Reference.&quot;
</BLOCKQUOTE>
<BLOCKQUOTE>
<PRE>--(*vendor(Microsoft),product(ODBC) 
<BR>   call EMPS_IN_PROJ(?)*)--
{call EMPS_IN_PROJ(?)}<A NAME="I199"></A><A NAME="I200"></A></PRE></BLOCKQUOTE>
<BLOCKQUOTE>
<P>To determine if a data source supports procedures, an application calls <B>SQLGetInfo</B> with the SQL_PROCEDURES information type. To retrieve a list of the procedures stored in a data source, an application calls <B>SQLProcedures</B>. To retrieve a list of the input, input/output, and output parameters, as well as the return value and the columns that make up the result set (if any) returned by a procedure, an application calls <B>SQLProcedureColumns</B>.
</BLOCKQUOTE>
<A NAME="E11E28"></A>
<H3>
<FONT FACE="Arial">Additional Extension Functions<A NAME="I201"></A></FONT></H3>
<BLOCKQUOTE>
<P>ODBC also provides the following functions related to SQL statements. For more information about these functions, see Chapter 13, &quot;Function Reference.&quot;
</BLOCKQUOTE>
<TABLE WIDTH=600>
<TR>
<TD WIDTH=162 VALIGN=top >
<BLOCKQUOTE>
<P><B>Function</B>
</BLOCKQUOTE></TD>
<TD WIDTH=293 VALIGN=top >
<A NAME="E7E39"></A>
<P><B>Description</B></TD>
</TR>
<TR>
<TD WIDTH=162 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLDescribeParam</B>
</BLOCKQUOTE></TD>
<TD WIDTH=293 VALIGN=top >
<A NAME="E7E40"></A>
<P>Retrieves information about prepared parameters.</TD>
</TR>
<TR>
<TD WIDTH=162 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLNativeSql</B>
</BLOCKQUOTE></TD>
<TD WIDTH=293 VALIGN=top >
<A NAME="E7E41"></A>
<P>Retrieves the SQL statement as processed by the data source, with escape sequences translated to SQL code used by the data source.</TD>
</TR>
<TR>
<TD WIDTH=162 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLNumParams</B>
</BLOCKQUOTE></TD>
<TD WIDTH=293 VALIGN=top >
<A NAME="E7E42"></A>
<P>Retrieves the number of parameters in an SQL statement.</TD>
</TR>
<TR>
<TD WIDTH=162 VALIGN=top >
<BLOCKQUOTE>
<P><B>SQLSetStmtOption</B>
<BR><B>SQLSetConnectOption</B>
<BR><B>SQLGetStmtOption</B>
</BLOCKQUOTE></TD>
<TD WIDTH=293 VALIGN=top >
<A NAME="E7E43"></A>
<P>These functions set or retrieve statement options, such as asynchronous processing, orientation for binding rowsets, maximum amount of variable length data to return, maximum number of result set rows to return, and query timeout value. Note that <B>SQLSetConnectOption</B> sets options for all statements in a connection.</TD></TR></TABLE>
<P ALIGN=CENTER>
<A HREF="prguide5.htm" TARGET="_self"><IMG SRC="graprev.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Previous Page"></A>
<A HREF="httoc.htm" TARGET="_self"><IMG SRC="gratoc.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="TOC"></A>
<A HREF="htindex.htm" TARGET="_self"><IMG SRC="graindex.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Index"></A>
<A HREF="prguide7.htm" TARGET="_self"><IMG SRC="granext.gif" WIDTH = 32 HEIGHT = 32 BORDER = 0 ALT="Next Page"></A>

<center><p><font SIZE=-2>Copyright &copy; 1992-1997 Solid Information Technology Ltd All rights reserved.</font></p></center>
</BODY></HTML>