Task (cid:9)
`Obtaining (cid:9)
`information about
`the data source's
`system tables (cid:9)
`(catalog functions)
`
`Function Name (cid:9)
`SQLColumnPrivileges (cid:9)
`
`Conformance (cid:9)
`
`Level 2
`
`SQLColumns (cid:9)
`
`Level 1
`
`SQLForeignKeys (cid:9)
`
`Level 2 (cid:9)
`
`SQLPrimaryKeys (cid:9)
`
`Level 2 (cid:9)
`
`SQLProcedureColumns
`
`Level 2 (cid:9)
`
`SQLProcedures (cid:9)
`
`Level 2 (cid:9)
`
`SQLSpecialColumns (cid:9)
`
`Level 1 (cid:9)
`
`SQLStatistics (cid:9)
`
`Level 1 (cid:9)
`
`SQLTablePrivileges (cid:9)
`
`Level 2 (cid:9)
`
`SQLTables (cid:9)
`
`Level 1 (cid:9)
`
`Terminating a (cid:9)
`Statement (cid:9)
`
`SQLFreeStmt (cid:9)
`
`Core (cid:9)
`
`Terminating a (cid:9)
`Connection (cid:9)
`
`SQLCancel (cid:9)
`SQLTransact (cid:9)
`SQLDisconnect (cid:9)
`SQLFreeConnect (cid:9)
`SQLFreeEnv (cid:9)
`
`Core (cid:9)
`Core (cid:9)
`Core (cid:9)
`Core (cid:9)
`Core (cid:9)
`
`Chapter 21 Function Summary (cid:9)
`
`185
`
`Purpose
`Returns a list of columns and
`associated privileges for one or more
`tables.
`Returns the list of column names in
`specified tables.
`Returns a list of column names that
`comprise foreign keys, if they exist
`for a specified table.
`Returns the list of column name(s)
`that comprise the primary key for a
`table.
`Returns the list of input and output
`parameters, as well as the columns
`that make up the result set for the
`specified procedures.
`Returns the list of procedure names
`stored in .a specific data source.
`Returns information about the optimal
`set of columns that uniquely identifies
`a row in a 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.
`
`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.
`
`Closes the connection.
`Releases the connection handle.
`Releases the environment handle.
`
`Page 101 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`186 (cid:9)
`
`Part 5 API Reference
`
`Setup DLL Function Summary
`
`The following table describes setup DLL functions. For more information about
`the syntax and semantics for each function, see Chapter 23, "Setup DLL Function
`Reference."
`
`Task
`
`Setting up data sources and (cid:9)
`translators (cid:9)
`
`Function Name (cid:9)
`ConfigDSN (cid:9)
`ConfigTranslator (cid:9)
`
`Purpose
`Adds, modifies, or deletes a data source.
`Returns a default translation option.
`
`Installer DLL Function Summary
`
`The following table describes the functions in the Installer DLL. For more
`information about the syntax and semantics for each function, see Chapter 24,
`"Installer DLL Function Reference."
`
`Task
`
`Installing ODBC
`
`Function Name (cid:9)
`SQLGetAvailableDrivers (cid:9)
`
`Configuring data sources (cid:9)
`
`SQLGetlnstalledDrivers (cid:9)
`SQLlnstallDriver
`
`SQLlnstallDriverManager
`
`SQLInstallODBC
`
`SQLConfigDataSource (cid:9)
`SQLCreateDataSource (cid:9)
`SQLGetPrivateProfileString (cid:9)
`
`SQLGetTranslator (cid:9)
`SQLManageDataSources (cid:9)
`
`SQLRemoveDefaultDataSource (cid:9)
`SQLRemoveDSNFromIni (cid:9)
`SQLWriteDSNToIni (cid:9)
`SQL WritePrivateProfileString (cid:9)
`
`Purpose
`Returns a list of drivers in the ODBC.INF
`file.
`Returns a list of installed drivers.
`Adds a driver to the ODBCINST.INI file
`(or registry).
`Returns the target directory for the Driver
`Manager.
`Installs the ODBC software interactively or
`silently.
`
`Calls the driver-specific setup DLL.
`Displays a dialog box to add a data source.
`Writing a value to the ODBC.lNI file or the
`registry
`Displays a dialog box to select a translator.
`Displays a dialog box to configure data
`sources and drivers
`Removes the default data source.
`Removes a data source.
`Adds a data source.
`Getting a value from the ODBC.INI file or
`the registry
`
`Page 102 of 434
`
`RA v. AMS
`Ex. 1020
`
`(cid:9)
`(cid:9)
`(cid:9)
`

`
`Chapter 21 Function Summary (cid:9)
`
`187
`
`Translation DLL Function Summary
`
`Task
`Translating data
`
`The following table describes translation DLL functions. For more information
`about the syntax and semantics for each function, see Chapter 25, "Translation
`DLL Function Reference."
`
`Function Name
`
`Purpose
`
`SQLDriverToDataSource
`
`SQLDataSourceToDriver
`
`Translates all data flowing from the driver
`to the data source.
`Translates all data flowing from the data
`source to the driver.
`
`Page 103 of 434
`
`RA v. AMS
`Ex. 1020
`
`(cid:9)
`(cid:9)
`

`
`CHAPTER 22
`
`ODBC Function Reference
`
`189
`
`The following pages describe each ODBC function in alphabetic order. Each
`function is defined as a C programming language function. Descriptions include
`the following:
`
`n Purpose
`n ODBC version
`n Conformance level
`n Syntax
`n Arguments
`n Return values
`n Diagnostics
`n Comments about usage and implementation
`n Code example
`n References to related functions
`
`Error handling is described in the SQLError function description. The text
`associated with SQLSTATE values is included to provide a description of the
`condition, but is not intended to prescribe specific text.
`
`Arguments
`
`All function arguments use a naming convention of the following form:
`
`[[prefix]...]tag[qualifier][suffix]
`
`Page 104 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`190 (cid:9)
`
`Part 5 API Reference
`
`Optional elements are enclosed in square brackets (ED. The following prefixes are
`used:
`
`Prefix Description
`
`c (cid:9)
`h (cid:9)
`i (cid:9)
`p (cid:9)
`rg (cid:9)
`
`Count of
`Handle of
`Index of
`Pointer to
`Range (array) of
`
`The following tags are used:
`
`Tag (cid:9)
`
`Description
`
`b (cid:9)
`col (cid:9)
`dbc (cid:9)
`env (cid:9)
`f (cid:9)
`par (cid:9)
`
`TOW (cid:9)
`stmt (cid:9)
`sz (cid:9)
`v (cid:9)
`
`Byte
`Column (of a result set)
`Database connection
`Environment
`Flag (enumerated type)
`Parameter (of an SQL statement)
`Row (of a result set)
`Statement
`Character string (array of characters, terminated by zero)
`Value of unspecified type
`
`Prefixes and tags combine to correspond roughly to the ODBC C types listed
`below. Flags (f) and byte counts (cb) do not distinguish between SWORD,
`UWORD, SDWORD, and UDWORD.
`
`Combined
`
`Prefix
`
`Tag
`
`ODBC C Type(s)
`
`Description
`
`cb
`
`crow
`
`f
`hdbc
`henv
`hstmt
`hwnd
`ib
`
`c
`
`c
`
`—
`h
`h
`h
`h
`i
`
`b
`
`row
`
`f
`dbc
`env
`stmt
`wnd
`b
`
`SWORD,
`SDWORD,
`UDWORD
`SDWORD,
`UDWORD,
`UWORD
`SWORD, UWORD
`HDBC
`HENV
`HSTMT
`HWND
`SWORD
`
`Count of bytes
`
`Count of rows
`
`Flag
`Connection handle
`Environment handle
`Statement handle
`Window handle
`Byte index
`
`Page 105 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`Combined
`
`Prefix (cid:9)
`
`Chapter 22 ODBC Function Reference (cid:9)
`
`191
`
`ODBC C Type(s) (cid:9)
`
`Description
`
`Tag (cid:9)
`
`col
`par
`row
`
`col (cid:9)
`
`TOW
`
`f
`
`dbc
`
`env
`
`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 *
`
`stmt
`
`HSTMT FAR *
`
`SWORD FAR *
`
`pi
`prg
`
`row
`b
`
`UDWORD FAR *
`PTR FAR *
`
`rg
`
`rg
`
`PTR
`
`PTR
`
`f
`
`sz
`
`UWORD FAR *
`
`UCHAR FAR *
`
`UDWORD
`
`i (cid:9)
`
`i (cid:9)
`
`pc
`
`pc
`
`pc
`
`pc (cid:9)
`
`P
`
`ph (cid:9)
`
`ph (cid:9)
`
`ph (cid:9)
`
`pi
`
`icol
`ipar
`irow
`
`pcb
`
`pccol
`
`pcpar
`
`perow
`
`pf
`
`phdbc
`
`phenv
`
`phstmt
`
`pib
`
`pirow
`prgb
`
`pv
`
`rgb
`
`rgf
`
`sz
`
`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
`Pointer to statement
`handle
`Pointer to byte
`index
`Pointer to row index
`Pointer to range
`(array) of bytes
`Pointer to value of
`unspecified type
`Range (array) of
`bytes
`Range (array) of
`flags
`String, zero
`terminated
`Value of
`unspecified type
`
`type. Qualifiers
`Qualifiers are used to distinguish specific variables of the same
`words or
`consist of the concatenation of one or more capitalized English
`abbreviations.
`
`Page 106 of 434
`
`RA v. AMS
`Ex. 1020
`
`(cid:9)
`(cid:9)
`(cid:9)
`(cid:9)
`

`
`192 (cid:9)
`
`Part 5 API Reference
`
`ODBC defines one value for the suffix Max, which denotes that the variable
`represents the largest value of its type for a given situation.
`
`For example, 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.
`
`ODBC include Files
`
`The files SQL.H and SQLEXT.H contain function prototypes for all of the ODBC
`functions. They also contain all type definitions and #define names used by
`ODBC.
`
`Diagnostics
`
`The diagnostics provided with each function list the SQLSTATEs that may be
`returned for the function by the Driver Manager or a driver. Drivers can, however,
`return additional SQLSTATEs arising out of 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 an error and are accompanied by a return code of SQL ERROR.
`The class "IM" is specific to warnings and errors that derive from the
`implementation of ODBC itself. 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 ODBC functions, tables and views are interchangeable. The term table is used
`for both tables and views, except where view is used explicitly.
`
`Catalog Functions
`
`ODBC supports a set of functions that return information about the data source's
`system tables or catalog. These are sometimes referred to collectively as the
`catalog functions. For more information about catalog functions, see "Retrieving
`Information About the Data Source's Catalog" in Chapter 6, "Executing SQL
`
`Page 107 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`Chapter 22 ODBC Function Reference (cid:9)
`
`193
`
`Statements," and "Returning Information About the Data Source's Catalog" in
`Chapter 14, "Processing an SQL Statement." The catalog functions are:
`
`SQLColumnPrivileges (cid:9)
`SQLColumns (cid:9)
`SQLForeignKeys (cid:9)
`SQLPrimaryKeys (cid:9)
`SQLProcedureColumns (cid:9)
`
`SQLProcedures
`SQLSpecialColumns
`SQLStatistics
`SQLTablePrivileges
`SQLTables
`
`Search Pattern Arguments
`
`Each catalog function returns information in the form of a result set. The
`information returned by a function may be constrained by a search pattern passed
`as an argument to that function. These search patterns can contain the
`metacharacters underscore () and percent (%) and a driver-defined escape
`character as follows:
`
`The underscore character represents any single character.
`n The percent character represents any sequence of zero or more characters.
`n The escape character 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. To
`obtain the escape character for a driver, an application must call SQLGetInfo
`with the SQL_SEARCH_PATTERN_ESCAPE option.
`n All other characters represent themselves.
`
`For example, if the search pattern for a table name is "%A%", the function will
`return 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 will
`return 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 will
`return all tables.
`
`Suppose the search pattern escape character for a driver is a backslash (\). If the
`search pattern for a table name is "ABC\%", the function will return the table
`named "ABC%." If the search pattern for a table name is "\\%", the function will
`return all tables with names that start with a backslash. Failing to precede a
`metacharacter used as a literal with an escape character may return more results
`than expected. For example, if a table identifier, "MY_TABLE" was returned as
`the result of a call to SQLTables and an application wanted to retrieve a list of
`columns for "MY_TABLE" using SQLColumns, SQLColumns would return all
`of the tables that matched MY_TABLE, such as MY_TABLE, MY1TABLE,
`MY2TABLE, and so on, unless the escape character precedes the underscore.
`
`Page 108 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`194 (cid:9)
`
`Part 5 API Reference
`
`Note A zero-length search pattern matches the empty string. A search pattern
`argument that is a null pointer means the search will not be constrained for that
`argument. (A null pointer and a search string of "%" should return the same
`values.)
`
`Page 109 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`SQLAllocConnect
`
`SQLAllocConnect (cid:9)
`
`195
`
`ODBC 1.o
`
`Core (cid:9)
`
`Syntax (cid:9)
`
`SQLAllocConnect allocates memory for a connection handle within the
`environment identified by henv.
`
`RETCODE SQLAllocConnect(henv, phdbc)
`
`The SQLAllocConnect function accepts the following arguments.
`
`Type (cid:9)
`HENV (cid:9)
`HDBC FAR * (cid:9)
`
`Argument (cid:9)
`henv (cid:9)
`phdbc (cid:9)
`
`Use (cid:9)
`Input (cid:9)
`Output (cid:9)
`
`Description
`Environment handle.
`Pointer to storage for the
`connection handle.
`
`Returns (cid:9)
`
`SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or
`SQL_INVALID_HANDLE.
`
`Diagnostics (cid:9)
`
`If SQLAllocConnect returns SQL_ERROR, it will set 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.
`
`When SQLAllocConnect returns SQL_ERROR or
`SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained
`by calling SQLError. The following table lists the SQLSTATE values commonly
`returned by SQLAllocConnect and explains each one in the context of this
`function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned
`by the Driver Manager. The return code associated with each SQLSTATE value is
`SQL_ERROR, unless noted otherwise.
`
`SQLSTATE (cid:9)
`01000 (cid:9)
`
`S1000 (cid:9)
`
`General error (cid:9)
`
`S1001 (cid:9)
`
`S1009 (cid:9)
`
`Memory allocation (cid:9)
`failure (cid:9)
`
`Invalid argument (cid:9)
`value (cid:9)
`
`Error
`
`Description
`
`General warning (cid:9)
`
`Driver-specific informational message.
`(Function returns
`SQL_SUCCESS_WITH_INFO.)
`An error occurred for which there was no
`specific SQLSTATE and for which no
`implementation-specific SQLSTATE was
`defined. The error message returned by
`SQLError in the argument szErrorMsg
`describes the error and its cause.
`(DM) The Driver Manager was unable to
`allocate memory for the connection handle.
`The driver was unable to allocate memory
`for the connection handle.
`(DM) The argument phdbc was a null
`pointer.
`
`Page 110 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`196 (cid:9)
`
`SQLAllocConnect
`
`Comments (cid:9)
`
`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
`SQLAllocConnect. The driver allocates memory for the connection information
`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 and drivers must therefore support safe, multithreaded access to this
`information: The application passes the hdbc value in all subsequent calls that
`require an hdbc.
`
`The Driver Manager processes the SQLAllocConnect function and calls the
`driver's SQLAllocConnect function when the application calls SQLConnect,
`SQLBrowseConnect, or SQLDriverConnect. (For more information, see the
`description of the SQLConnect function.)
`
`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 (cid:9)
`
`See SQLBrowseConnect and SQLConnect.
`
`Related Functions For information about (cid:9)
`Connecting to a data source
`Freeing a connection handle
`
`See
`SQLConnect
`SQLFreeConnect
`
`Page 111 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`SQLAllocEnv
`
`SQLAllocEnv (cid:9)
`
`197
`
`ODBC 1.0
`
`Core (cid:9)
`
`SQLA11ocEnv allocates memory for an environment handle and initializes the
`ODBC call level interface for use by an application. An application must call
`SQLA11ocEnv prior to calling any other ODBC function.
`
`Syntax (cid:9)
`
`RETCODE SQLAllocEnv(phenv)
`
`The SQLA11ocEnv function accepts the following argument.
`
`Type (cid:9)
`HENV FAR *
`
`Argument (cid:9)
`phenv (cid:9)
`
`Use (cid:9)
`Output (cid:9)
`
`Description
`Pointer to storage for the
`environment handle.
`
`Returns (cid:9)
`
`SQL_SUCCESS or SQL_ERROR.
`
`If SQLA11ocEnv returns SQL_ERROR, it will set the henv referenced by phenv
`to SQL_NULL_HENV. In this case, the application can assume that the error was
`a memory allocation error.
`
`Diagnostics (cid:9)
`
`A driver cannot return SQLSTATE values directly after the call to SQLA11ocEnv,
`since no valid handle will exist with which to call SQLError.
`
`There are two levels of SQLA11ocEnv functions, one within the Driver Manager
`and one within each 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 SQLA11ocEnv
`function, then the Driver Manager—level SQLConnect, SQLBrowseConnect, or
`SQLDriverConnect function returns SQL_ERROR. A subsequent call to
`SQLError with henv, SQL_NULL_HDBC, and SQL_NULL_HSTMT returns
`SQLSTATE IM004 (Driver's SQLA11ocEnv failed), followed by one of the
`following errors from the driver:
`
`n SQLSTATE S1000 (General error).
`n A driver-specific SQLSTATE value, ranging from S1000 to S19ZZ. For
`example, SQLSTATE S1001 (Memory allocation failure) indicates that the
`Driver Manager's call to the driver-level SQLA11ocEnv returned
`SQL_ERROR, and the Driver Manager's henv was set to SQL_NULL_HENV.
`
`For additional information about the flow of function calls between the Driver
`Manager and a driver, see the SQLConnect function description.
`
`An environment handle references global information such as valid connection
`handles and fictive connection handles. To request an environment handle, an
`application passes the address of an henv to SQLA11ocEnv. The driver allocates
`memory for the environment information and stores the value of the associated
`handle in the henv. On operating systems that support multiple threads,
`
`Comments
`
`Page 112 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`198 (cid:9)
`
`SQLAllocEnv
`
`applications can use the same henv on different threads and drivers must therefore
`support safe, multithreaded access to this informatioti. The application passes the
`henv value in all subsequent calls that require an henv.
`
`There should never be more than one henv allocated at one time and the
`application should not call SQLAllocEnv when there is a current valid henv. If
`the application calls SQLAllocEnv with a pointer to a valid henv, the driver
`overwrites the henv without regard to its previous contents.
`
`When the Driver Manager processes the SQLAllocEnv function, it checks the
`Trace keyword in the [ODBC] section of the ODBC.INI file or the ODBC subkey
`in the registry. If it is set to 1, the Driver Manager enables tracing for all
`applications on Windows 3.1 or for the current application on Windows NT.
`
`Code Example (cid:9)
`
`See SQLBrowseConnect and SQLConnect.
`
`Related Functions
`
`For information about
`Allocating a connection handle (cid:9)
`Connecting to a data source (cid:9)
`Freeing an environment handle (cid:9)
`
`See
`SQLAllocConnect
`SQLConnect
`SQLFreeEnv
`
`Page 113 of 434
`
`RA v. AMS
`Ex. 1020
`
`(cid:9)
`

`
`SQLAllocStmt
`
`SQLAllocStmt (cid:9)
`
`199
`
`ODBC 1.0
`
`Core
`
`SQLAllocStmt allocates memory for a statement handle and associates the
`statement handle with the connection specified by hdbc.
`
`An application must call SQLAllocStmt prior to submitting SQL statements.
`
`Syntax
`
`RETCODE SQLAllocStmt(hdbc, phstmt)
`
`The SQLAllocStmt function accepts the following arguments.
`
`Type
`HDBC (cid:9)
`HSTMT FAR * (cid:9)
`
`Argument (cid:9)
`
`hdbc (cid:9)
`phstmt (cid:9)
`
`Use (cid:9)
`Input (cid:9)
`Output (cid:9)
`
`Description
`Connection handle.
`Pointer to storage for the
`statement handle.
`
`Returns (cid:9)
`
`SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE, or
`SQL_ERROR.
`
`Diagnostics (cid:9)
`
`If SQLAllocStmt returns SQL_ERROR, it will set the hstmt referenced by phstmt
`to SQL_NULL_HSTMT. The application can then obtain additional information
`by calling SQLError with the hdbc and SQL_NULL_HSTMT.
`
`When SQLAllocStmt returns SQL_ERROR or SQL_SUCCESS_WITH_INFO,
`an associated SQLSTATE value may be obtained by calling SQLError. The
`following table lists the SQLSTATE values commonly returned by
`SQLAllocStmt and explains each one in the context of this function; the notation
`"(DM)" precedes the descriptions of SQLSTATEs returned by the Driver
`Manager. The return code associated with each SQLSTATE value is
`SQL_ERROR, unless noted otherwise.
`
`SQLSTATE (cid:9)
`01000 (cid:9)
`
`Error
`General warning (cid:9)
`
`08003 (cid:9)
`
`IM001 (cid:9)
`
`Connection not (cid:9)
`open (cid:9)
`
`Driver does not (cid:9)
`support this (cid:9)
`function
`
`Description
`Driver-specific informational message.
`(Function returns
`SQL_SUCCESS_WITH_INFO.)
`(DM) The connection specified by the hdbc
`argument was not open. The connection
`process must be completed successfully
`(and the connection must be open) for the
`driver to allocate an hstmt.
`(DM) The driver associated with the hdbc
`does not support the function.
`
`Page 114 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`200 (cid:9)
`
`SQLAllocStmt
`
`SQLSTATE
`S1000 (cid:9)
`
`Error (cid:9)
`General error (cid:9)
`
`S1001 (cid:9)
`
`S1009 (cid:9)
`
`Memory allocation (cid:9)
`failure (cid:9)
`
`Invalid argument (cid:9)
`value (cid:9)
`
`Description
`An error occurred for which there was no
`specific SQLSTATE and for which no
`implementation-specific SQLSTATE was
`defined. The error message returned by
`SQLError in the argument szErrorMsg
`describes the error and its cause.
`(DM) The Driver Manager was unable to
`allocate memory for the statement handle.
`The driver was unable to allocate memory
`for the statement handle.
`(DM) The argument phstmt was a null
`pointer.
`
`Comments (cid:9)
`
`A statement handle references statement information, such as network
`information, SQLSTATE values and error messages, cursor name, number of
`result set columns, and status information for SQL statement processing.
`
`To request a statement handle, an application connects to a data source and then
`passes the address of an hstmt to SQLAllocStmt. 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 hstmt on different threads and drivers must therefore support safe,
`multithreaded access to this information. The application passes the hstmt value in
`all subsequent calls that require an hstmt.
`
`If the application calls SQLAllocStmt with a pointer to a valid hstmt, the driver
`overwrites the hstmt without regard to its previous contents.
`See SQLBrowseConnect, SQLConnect, and SQLSetCursorName.
`
`For information about (cid:9)
`Executing an SQL statement (cid:9)
`Executing a prepared SQL statement. (cid:9)
`Freeing a statement handle (cid:9)
`Preparing a statement for execution (cid:9)
`
`See
`SQLExecDirect
`SQLExecute
`SQLFreeStmt
`SQLPrepare
`
`Code Example (cid:9)
`
`Related Functions
`
`Page 115 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`SQLBindCol
`
`SQLBindCol (cid:9)
`
`201
`
`ODBC 1.0
`
`Core (cid:9)
`
`SQLBindCol assigns the storage and data type for a column in a result set,
`including:
`
`n A storage buffer that will receive the contents of a column of data
`n The length of the storage buffer
`n A storage location that will receive the actual length of the column of data
`returned by the fetch operation
`n Data type conversion
`
`Syntax (cid:9)
`
`RETCODE SQLBindCol(hstmt, icol, fCType, rgbValue, cbValueMax, pcbValue)
`
`The SQLBindCol function accepts the following arguments.
`
`Type (cid:9)
`
`HSTMT (cid:9)
`UWORD (cid:9)
`
`Argument (cid:9)
`
`hstmt (cid:9)
`icol (cid:9)
`
`Use (cid:9)
`Input (cid:9)
`Input (cid:9)
`
`Description
`Statement handle.
`Column number of result data,
`ordered sequentially left to
`right, starting at 1. A column
`number of 0 is used to retrieve a
`bookmark for the row;
`bookmarks are not supported by
`ODBC 1.0 drivers or by
`SQLFetch.
`
`Page 116 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`202 (cid:9)
`
`SQLBindCol
`
`Type (cid:9)
`SWORD (cid:9)
`
`Argument (cid:9)
`fCType (cid:9)
`
`Use (cid:9)
`Input (cid:9)
`
`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_BOOKMARK
`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 data be transferred to its
`default C data type.
`
`Note Drivers must also
`support the following values of
`fCType from ODBC 1.0.
`Applications must use these
`values, rather than the ODBC
`2.0 values, when calling an
`ODBC 1.0 driver:
`
`SQL_C_LONG
`SQL_C_SHORT
`SQL_C_TINYINT
`
`For more information, see
`"ODBC 1.0 C Data Types" in
`Appendix D, "Data Types."
`
`For information about how data
`is converted, see "Converting
`Data from. SQL to C Data
`Types" in Appendix D, "Data
`Types."
`
`Page 117 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`Type (cid:9)
`PTR (cid:9)
`
`Argument (cid:9)
`
`rgbValue (cid:9)
`
`Use (cid:9)
`
`Input (cid:9)
`
`SDWORD (cid:9)
`
`cbValueMax (cid:9)
`
`Input (cid:9)
`
`SiaBindCol (cid:9)
`
`203
`
`Description
`
`Pointer to storage for the data.
`If rgbValue is a null pointer, the
`driver unbinds the column. (To
`unbind all columns, an
`application calls SQLFreeStmt
`with the SQL_UNBIND
`option.)
`
`Note If a null pointer was
`passed for rgbValue in ODBC
`1.0, the driver returned
`SQLSTATE S1009 (Invalid
`argument value); individual
`columns could not be unbound.
`
`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" in Appendix D,
`"Data Types."
`
`Page 118 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`204 (cid:9)
`
`SQLBindCol
`
`Type (cid:9)
`SDWORD FAR *
`
`Argument (cid:9)
`
`pcbValue
`
`Use (cid:9)
`
`Input (cid:9)
`
`Description
`
`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 determined.
`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" in Appendix D, "Data
`Types."
`
`Returns
`
`Diagnostics
`
`SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or
`SQL_INVALID_HANDLE.
`
`When SQLBindCol returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an
`associated SQLSTATE value may be obtained by calling SQLError. The
`following table lists the SQLSTATE values commonly returned by SQLBindCol
`and explains each one in the context of this function; the notation "(DM)"
`precedes the descriptions of SQLSTATEs returned by the Driver Manager. The
`return code associated with each SQLSTATE value is SQL_ERROR, unless noted
`otherwise.
`
`Page 119 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`SQLSTATE (cid:9)
`
`Error (cid:9)
`
`Description
`
`SQLBindCol (cid:9)
`
`205
`
`01000
`
`IM001
`
`51000
`
`51001
`
`51002
`
`51003
`
`51009
`
`51010
`
`General warning
`
`Driver does not
`support this
`function
`General error
`
`Memory allocation
`failure
`
`Invalid column
`number
`
`Program type out of
`range
`
`Invalid argument
`value
`Function sequence
`error
`
`S1090
`
`Invalid string or
`buffer length
`
`Driver-specific informational message.
`(Function returns
`SQL_SUCCESS_WITH_INFO.)
`(DM) The driver associated with the hstmt
`does not support the function.
`
`An error occurred for which there was no
`specific SQLSTATE and for which no
`implementation-specific SQLSTATE was
`defined. The error message returned by
`SQLError in the argument szErrorMsg
`describes the error and its cause.
`The driver was unable to allocate memory
`required to support execution or completion
`of the function.
`The value specified for the argument icol
`was 0 and the driver was an ODBC 1.0
`driver.
`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.
`The argument icol was 0 and the argument
`fCType was not SQL_C_BOOKMARK.
`The driver supported ODBC 1.0 and the
`argument rgbValue was a null pointer.
`(DM) An asynchronously executing
`function was called for the hstmt and was
`still executing when this function was
`called.
`(DM) SQLExecute, SQLExecDirect, or
`SQLSetPos was called for the hstmt and
`returned SQL_NEED_DATA. This
`function was called before data was sent for
`all data-at-execution parameters or
`columns.
`(DM) The value specified for the argument
`cbValueMax was less than 0.
`
`Page 120 of 434
`
`RA v. AMS
`Ex. 1020
`
`

`
`206 (cid:9)
`
`SQLBindCol
`
`SQLSTATE (cid:9)
`S 1C00 (cid:9)
`
`Error (cid:9)
`Driver not capable (cid:9)
`
`Description
`The driver does not support the data type
`specified in the argument fCType.
`The argument icol was 0 and the driver
`does not support bookmarks.
`The driver only supports ODBC 1.0 and the
`argument fCType was one of the following:
`SQL C_STINYINT
`SQL1C_UTINYINT
`SQL_C SSHORT
`SQL_CIUSHORT
`SQL_C_SLONG
`SQL_C_ULONG
`
`Comments (cid:9)
`
`The ODBC interface provides two ways to retrieve a column of data:
`
`• SQLBindCol assigns the storage location for a column of data before the data
`is retrieved. When SQLFetch or SQLExtendedFetch is called, the driver
`places the data for all bound columns in the assigned locations.
`• SQLGetData (an extended function) assigns a storage location for a column
`of data after SQLFetch or SQLExtendedFetch has been called. It also places
`the data for the requested column in the assigned location. Because it can
`retrieve data from a column in parts, SQLGetData can be used to retrieve
`long data values.
`
`An application may choose to bind every column with SQLBindCol, to do no
`binding and retrieve data only with SQLGetData, or to use a combination of the
`two. However, unless the driver provides extended functionality, SQLGetData
`can only be used 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 the data will be converted. It
`is the application's responsibility to allocate enough storage for the data. If the
`buffer will contain variable length data, the application must allocate as much
`storage as the maximum length of the bound column or the data may be truncated.
`For a list of valid data conversion types, see "Converting Data from SQL to C
`Data Types" in Appendix D, "Data Types."
`
`At fetch time, the driver processes the data for each bound column according to
`the arguments specified in SQLBindCol. First, it converts the data according to
`the argument fCType. Next, it fills the buffer pointed to by rgbValue. Finally, it
`stores the available number of bytes in pcb