odbc
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指南
