odbc

模块

odbc

模块摘要

Erlang ODBC应用程序

描述

该应用程序提供了一个Erlang接口来与关系型SQL数据库进行通信。它建立在Microsofts ODBC接口的基础之上，因此要求您有一个要连接到的数据库的ODBC驱动程序。

注

功能first/[1,2]，last/[1,2]，next/[1,2]，prev[1,2]并且select/[3,4]假定有一起工作的连接关联的结果集。调用函数将select_count/[2,3]这样的结果集与连接相关联。再次调用select_count将删除当前结果集关联并创建一个新关联。调用不对相关结果集进行操作的函数（如sql_query/[2,3]，）将删除当前结果集关联。

一些驱动程序只支持结果集的顺序遍历，ei他们不支持ODBC世界中被称为可滚动游标的东西。这将有效果的功能，例如first/[1,2]，last/[1,2]，prev[1,2]等会返回{error, driver_does_not_support_function}

公共数据类型

下面是ODBC API中多个函数使用的类型定义。

注

类型TimeOut具有默认值infinity，例如：

commit（Ref，CommitMode）与commit（Ref，CommitMode，infinity）相同。如果超时到期，客户端将退出并显示原因超时。

connection_reference() - as returned by connect/2    

time_out() = milliseconds() | infinity    

milliseconds() = integer() >= 0     

common_reason（）= connection_closed | extended_error（）| term（） - 某种
解释出了什么问题    

extended_error（）= {string（），integer（），Reason}  - 使用ODBC扩展错误类型
和本地数据库错误代码，以及本来的原因
返回的没有启用extended_errors。 

string() = list of ASCII characters    

col_name（）= string（） - 结果集中列的名称    

col_names（） -  [col_name（）]  - 例如。的名称列表
          结果集中的所选列。     

row（）= {value（）}  - 列值的元组，例如行的一行
          结果集。     

value（）= null | term（） - 列值。     

rows（）= [row（）]  - 结果集中的行列表。    

result_tuple() =
     {updated, n_rows()} | {selected, col_names(), rows()}    

n_rows（）= integer（） -  UPDATE的受影响行数，
          INSERT或DELETE查询。对于其他查询类型的值
          是由驱动程序定义的，因此应该忽略。    

odbc_data_type() = sql_integer | sql_smallint | sql_tinyint |
     {sql_decimal, precision(), scale()} |
     {sql_numeric, precision(), scale()} |
     {sql_char, size()} |
     {sql_wchar, size()} |
     {sql_varchar, size()} |
     {sql_wvarchar, size()}|
     {sql_float, precision()} |
     {sql_wlongvarchar, size()} |
     {sql_float, precision()} |
     sql_real | sql_double | sql_bit | atom()
   

precision() = integer()    

scale() = integer()    

size() = integer()    

错误处理

错误处理策略和可能的错误源在Erlang ODBC中描述 User's Guide.

出口

commit(Ref, CommitMode) ->commit(Ref, CommitMode, TimeOut) -> ok | {error, Reason}

类型

提交或回滚事务。在自动提交关闭的连接上需要。

connect(ConnectStr, Options) -> {ok, Ref} | {error, Reason}

类型

连接字符串的一个示例："DSN=sql-server;UID=aladdin;PWD=sesame"其中，DSN是您的ODBC数据源名称，UID是数据库用户标识，PWD是该用户的密码。这些通常是连接字符串中所需的属性，但某些驱动程序具有其他驱动程序特定的属性，例如"DSN=Oracle8;DBQ=gandalf;UID=aladdin;PWD=sesame"DBQ是您的TNSNAMES.ORA条目名称，例如某些Oracle特定的配置属性。

所有选项都有默认值。

打开到数据库的连接。连接与创建它的进程相关联，并且只能通过它进行访问。该函数可能产生新的进程来处理连接。如果创建连接的进程死亡或者调用disconnect / 1，则这些进程将终止。

如果打开了自动提交模式，则每个查询将被视为一个单独的事务，并在执行后自动提交。如果希望多个查询成为同一事务的一部分，则应关闭自动提交模式。然后，您必须显式调用COMMIT/3来结束事务。

默认的超时为无穷大。

如果启用了binary_strings选项，则所有字符串将作为二进制文件返回，并且输入param_query的字符串将被视为二进制文件。用户需要确保二进制文件处于数据库期望的编码状态。默认情况下，该选项关闭。

由于默认结果集作为元组列表返回。该TupleMode选项仍然存在以保持一定程度的向后兼容性。如果该选项设置为关闭，则结果集将作为列表列表而不是元组列表返回。

可滚动游标很不错，但会导致一些开销。对于某些连接，速度可能比灵活的数据访问更重要，然后您可以禁用可滚动光标进行连接，从而限制API但获得速度。

注

关闭scrollable_cursors选项会使旧的odbc驱动程序能够连接，而其他的则会失败。

如果启用跟踪模式，则会通知ODBC驱动程序将跟踪日志写入位于erlang模拟器当前目录中的文件SQL.LOG。如果您怀疑erlang ODBC应用程序中可能存在错误，则此信息可能很有用，并且可能与将此文件发送给我们的支持人员相关。否则，你可能没有太多的用处。

注

有关详细信息，ConnectStr请参阅1中的函数SQLDriverConnect的说明。

该extended_errors选项在操作失败时启用扩展的ODBC错误信息。而不是返回{error, Reason}，失败的功能将会重新产生{error, {ODBCErrorCode, NativeErrorCode, Reason}}。请注意，在编写与数据库无关的代码时，这些信息可能没有多大用处，但在处理已知底层数据库时可以提供更复杂的错误处理。

• ODBCErrorCode 是由ODBC驱动程序返回的ODBC错误字符串。

• NativeErrorCode基础数据库返回的数字错误代码。可能的值及其含义取决于所使用的数据库。

• Reason根据Reason扩展错误未启用时的字段。

注

当前的实现产生了一个用C编写的端口程序，该程序利用了实际的ODBC驱动程序。该端口程序连接到Erlang ODBC应用程序的默认超时值为5000毫秒。可以通过为ODBC应用程序设置特定于应用程序的环境变量'port_timeout'以毫秒数来更改此超时。例如：[{odbc，{port_timeout，60000}}]将其设置为60秒。

disconnect(Ref) -> ok | {error, Reason}

类型

关闭与数据库的连接。这也将终止连接打开时可能产生的所有进程。此通话将始终成功。如果连接不能正常断开，它将被残忍地杀死。但是，如果尝试断开由另一个进程启动的连接，则可能会收到错误消息。

describe_table(Ref, Table) ->describe_table(Ref, Table, Timeout) -> {ok, Description} | {error, Reason}

类型

查询数据库以找出表中列的ODBC数据类型Table。

first(Ref) ->first(Ref, Timeout) -> {selected, ColNames, Rows} | {error, Reason}

类型

返回结果集的第一行，并将光标定位到该行。

last(Ref) ->last(Ref, TimeOut) -> {selected, ColNames, Rows} | {error, Reason}

类型

返回结果集的最后一行，并将光标定位到该行。

next(Ref) ->next(Ref, TimeOut) -> {selected, ColNames, Rows} | {error, Reason}

类型

返回结果集中与当前光标位置相关的下一行，并将光标定位在该行。如果在调用此函数时游标位于结果集的最后一行，则返回值将为{selected, ColNames,[]}ei，行值列表为空，表示没有更多数据要读取。

param_query(Ref, SQLQuery, Params) ->param_query(Ref, SQLQuery, Params, TimeOut) -> ResultTuple | {error, Reason}

类型

为存储过程定义IN、Out和Inout参数模式。

执行参数化的SQL查询。有关示例，请参阅"Using the Erlang API"Erlang ODBC用户指南。

注

使用函数describe_table / 2,3来找出该表的每一列的预期ODBC数据类型。如果某列的数据类型使用大写字母描述，那么param_query函数当前不支持该数据类型。要知道哪个Erlang数据类型对应于ODBC数据类型，请参阅mapping用户指南中的Erlang to ODBC数据类型。

prev(Ref) ->prev(ConnectionReference, TimeOut) -> {selected, ColNames, Rows} | {error, Reason}

类型

返回相对于当前光标位置的结果集的前一行，并将光标定位在该行。

start() ->start(Type) -> ok | {error, Reason}

类型

启动odbc应用程序。默认类型是临时的。See application(3)

stop() -> ok

停止ODBC应用程序。See application(3)

sql_query(Ref, SQLQuery) ->sql_query(Ref, SQLQuery, TimeOut) -> ResultTuple | [ResultTuple] |{error, Reason}

类型

执行SQL查询或一批SQL查询。如果是SELECT查询，则返回结果集，格式为{selected, ColNames, Rows}。对于其他查询类型，{updated, NRows}将返回元组，对于批量查询，如果驱动程序支持它们，则此函数也可以返回结果元组列表。

注

一些驱动程序可能没有可用的受影响行数的信息，然后返回值可能是{updated, undefined}。

列名的列表进行排序以同样的方式作为行的值的列表，如第一个ColName与第一个关联Value的Row。

select_count(Ref, SelectQuery) ->select_count(Ref, SelectQuery, TimeOut) -> {ok, NrRows} | {error, Reason}

类型

SQL选择查询。

执行SQL SELECT查询并将结果集与连接相关联。游标位于结果集的第一行之前，并{ok, NrRows}返回元组。

注

某些驱动程序可能没有结果集中行数的信息，NrRows则会得到该值undefined。

select(Ref, Position, N) ->select(Ref, Position, N, TimeOut) -> {selected, ColNames, Rows} | {error, Reason}

类型

选择策略，确定在结果集中的哪一行开始选择。

应该指示结果集中的行号。与选项一起使用时relative当与选项一起使用时，它将用作当前光标位置的偏移量。absolute它将被解释为行号。

选N结果集的连续行。如果Position是next它在语义上相当于调用next/[1,2]N时代。如果Position是{relative, Pos}，，，Pos将用作当前光标位置的偏移量，以确定第一个选定的行。如果Position是{absolute, Pos}，，，Pos将是选定的第一行的编号。在此函数返回后，光标定位在最后选定的行。如果有更少的N结果集的左边行长度为Rows会少于N如果要选择的第一行恰好超出了结果集的最后一行，则返回的值将为{selected, ColNames,[]}例如，行值列表为空，表示没有更多的数据要获取。

参考文献

一：microsoft odbc 3.0，程序员%27s参考资料和sdk指南

另见http：//msdn.microsoft.com/

	odbc
	1.介绍（odbc） | 1. Introduction (odbc)	详细
	2.开始 | 2. Getting started	详细
	3.数据库 | 3. Databases	详细
	4.错误处理 | 4. Error handling	详细
	odbc	详细