As mention before is the interface of the Erlang ODBC application is divided into four parts:
All functions described are synchronous.
The interface supports all ODBC defined SQL data types
except binaries.
They are all mapped on Erlang strings.
The type string()
is a list()
of integers
representing ASCII codes. The type
boolean()
is either the macro ?SQL_TRUE
or
the macro ?SQL_FALSE
.
The default Timeout for all functions is 5000 ms,
unless otherwise stated.
Most Erlang ODBC functions does have common arguments.
start_link(Args, Options) ->
start_link(ServerName, Args, Options) -> Result
Args = []
Options = [Opt]
Opt = This are options which are used by the gen_server module.
gen_server
and sys
.ServerName = {local, atom()} | {global, atom()}
Result = {ok, pid()} | {error, Reason}
Reason = {already_started, pid()} | timeout | {no_c_node, Info}
Info = string()
Starts a new ODBC server process, registers it with the supervisor, and links it to the calling process. Opens a port to a new C node on the local host, using the same cookie as is used by the node of the calling process. Links to the process on the C node.
There is no default timeout value. Not using the timeout
option is equivalent to having an infinite timeout value. |
stop(Server) ->
stop(Server, Timeout) -> ok
Server = pid() | Name | {global, Name} | {Name, Node}
Timeout = integer() | infinity
Stops the ODBC server process as soon as all already submitted requests have been processed. The C node is also stopped.
To use the Basic API it is necessary to gain a comprehensive
understanding of ODBC by studying [1].
Erlang ODBC application Basic API
function allocate and deallocate memory automatic and therefore
have the ODBC function which
allocate or deallocate memory been excluded.
sqlBindColumn(Server, ColNum, Ref) ->
sqlBindColumn(Server, ColNum, Ref, Timeout) ->
Result | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
ColNum = integer()
Ref = term()
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ErrMsg = string()
ErrCode = ?SQL_INVALID_HANDLE | ?SQL_ERROR
Assigns a reference to the column with the number ColNum.
Differences from the ODBC Function:
The parameters Server
and Timeout
have been added. The input parameters TargetType
,
TargetValuePtr
, BufferLength
, and
StrLen_or_IndPtr
of the ODBC function have
been replaced
with the Ref
parameter.
sqlCloseCursor(Server) ->
sqlCloseCursor(Server, Timeout) ->
Result | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ErrMsg = string()
ErrCode = ?SQL_INVALID_HANDLE | ?SQL_ERROR
Closes a cursor that has been opened on a statement
and discards pending results. See SQLCloseCursor in [1].
Differences from the ODBC Function:
The parameters Server
and Timeout
have
been added.
sqlConnect(Server, DSN, UID, Auth) ->
sqlConnect(Server, DSN, UID, Auth, Timeout) ->
Result | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
DSN = string()
UID = string()
Auth = string()
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Establishes a connection to a driver and a data source.
See SQLConnect in [1].
Differences from the ODBC Function:
Connection pooling is not supported.
The parameters Server
and Timeout
have been added.
The input parameters NameLength1
,
NameLength2
, and NameLength3
of the
ODBC function have been excluded.
sqlDescribeCol(Server, ColNum) ->
sqlDescribeCol(Server, ColNum, Timeout) ->
{Result, ColName, Nullable} | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
ColNum = integer()
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ColName = string()
Nullable = ?SQL_NO_NULLS |
?SQL_NULLABLE | ?SQL_NULLABLE_UNKNOWN
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Returns the result descriptor -- column name, and nullability
for one column
in the result set. See SQLDescribeCol in [1].
Differences from the ODBC Function:
The function does not support retrieval of bookmark
column data.
The parameters Server
and Timeout
have
been added. The output parameters ColumnName
and NullablePtr
of the ODBC function have
been changed into the returned values ColName
and
Nullable
.
The output parameters BufferLength
,
NameLengthPtr
, DataTypePtr
,
ColumnSizePtr
, and DecimalDigitsPtr
of the ODBC function hsve been excluded.
sqlDisConnect(Server) ->
sqlDisConnect(Server, Timeout) ->
Result | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Closes the connection associated with a specific
server. See SQLDisconnect in [1].
Differences from the ODBC Function:
Connection pooling is not supported.
The parameters Server
and Timeout
have been added.
sqlEndTran(Server, ComplType) ->
sqlEndTran(Server, ComplType, Timeout) ->
Result | {error, ErrorMsg, errCode}
Server = pid() | Name | {global, Name} | {Name, Node}
ComplType = ?SQL_COMMIT | ?SQL_ROLLBACK
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Requests a commit or rollback operation for all active operations on all statement handles associated with a connection. See SQLEndTran in [1].
Rollback of transactions may be unsupported by core level drivers. |
Differences from the ODBC Function:
The parameter HandleType and Handle of the ODBC function
has been excluded.
The parameters Server
and Timeout
have been added.
sqlExecDirect(Server, Stmt) ->
sqlExecDirect(Server, Stmt, Timeout) ->
Result | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Stmt = string()
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO |
?SQL_NEED_DATA | ?SQL_NO_DATA
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Executes a statement. See SQLExecDirect in [1].
Differences from the ODBC Function:
?SQL_NO_DATA
is returned only in connection with
positioned updates, which are not supported.
The parameters Server
and Timeout
have
been added. The input parameter StatementHandle and TextLength of
the ODBC function has been excluded.
sqlFetch(Server) ->
sqlFetch(Server, Timeout) ->
Result | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO |
?SQL_NO_DATA
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Fetches a row of data from a result set. The driver
returns data for all columns that were bound to storage
locations with sqlBindCol/[3, 4]
. See SQLFetch in [1].
Differences from the ODBC Function:
The parameter StatementHandle of the ODBC function has been
excluded.
The parameters Server
and Timeout
have
been added.
sqlNumResultCols(Server) ->
sqlNumResultCols(Server, Timeout) ->
{Result, ColCount} | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ColCount = integer()
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Returns the number of columns in a result set.
See SQLNumResultCols in [1].
Differences from the ODBC Function:
The parameter StatementHandle of the ODBC function has
been excluded.
The parameters Server
and Timeout
have
been added. The output parameter
ColumnCountPtr
of the ODBC function has been
changed into the returned
value ColCount
.
sqlRowCount(Server) ->
sqlRowCount(Server, Timeout) ->
{Result, RowCount} | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
RowCount = integer()
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Returns the number of rows affected by an UPDATE, INSERT,
or DELETE statement. See SQLRowCount in [1].
Differences from the ODBC Function:
The parameter StatementHandle has been excluded from ODBC function.
The parameters Server
and Timeout
have been added.
The output parameter RowCountPtr
of the ODBC
function has been changed into the returned value
RowCount
.
sqlSetConnectAttr(Server, Attr, Value) ->
sqlSetConnectAttr(Server, Attr, Value, Timeout) ->
Result | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Attr = integer()
Value = string() | integer()
Timeout = integer() | infinity
Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
ErrMsg -> string()
ErrCode -> ?SQL_INVALID_HANDLE | ?SQL_ERROR
Sets attributes that govern aspects of connections.
The following attributes, and their possible values,
are supported (through macros):
?SQL_ATTR_AUTOCOMMIT
?SQL_ATTR_TRACE
?SQL_ATTR_TRACEFILE
These attributes can only be set after a connection.
More information can be
found under SQLSetConnectAttr in [1]. Driver-specific
attributes are not supported through macros, but can be
retrieved, if they are of character or signed/unsigned
long integer types.
Differences from the ODBC Function:
Only character and signed/unsigned long
integer attribute types are supported.
The parameters Server
and Timeout
have been
added. The input parameter ConnectionHandle
and
StringLength
of
the ODBC function has been excluded.
readData(Server, Ref) ->
readData(Server, Ref, Timeout) ->
{ok, Value}
Server = pid() | Name | {global, Name} | {Name, Node}
Ref
Timeout = integer() | infinity
Value = string()
Ref
. Returns the contents of a deferred data buffer and its
associated length/indicator buffer. Used in connection
with sqlFetch/[1, 2]
.
Ref
Returns a reference. The reference is assigned to a column in
the function sqlBindColumn/[3,4]
.
Erlang ODBC application Utility API has a few easy-to-use function. The reported errors are tuples with arity 3.
erl_connect(Server, ConnectStr) ->
erl_connect(Server, ConnectStr, Timeout) ->
erl_connect(Server, DSN, UID, PWD) ->
erl_connect(Server, DSN, UID, PWD, Timeout) ->
ok, | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
ConnectStr = string()
DSN = string()
UID = string()
PWD = string()
Timeout = integer() | infinity
ErrMsg = string()
ErrCode = ?SQL_INVALID | ?SQL_ERROR
Opens a connection to a database. There can be only
one open connections to a database and per server.
connect/[2, 3]
is used when the information that can be
supplied through connect/[4, 5]
does not suffice.
The syntax to be used for |
erl_disconnect(Server) ->
erl_disconnect(Server, Timeout) ->
ok | {error, ErrMsg, ErrCode}
Server = pid() | Name | {global, Name} | {Name, Node}
Timeout = integer() | infinity
ErrMsg = string()
ErrCode = ?SQL_INVALID_HANDLE | ?SQL_ERROR
Closes the connection to a database.
erl_executeStmt(Server, Stmt) ->
erl_executeStmt(Server, Stmt, Timeout) ->
{updated, NRows} | {selected, [ColName], [Row]} |
{error, ErrMsg}
Server = pid() | Name | {global, Name} | {Name, Node}
Stmt = string()
Timeout = integer() | infinity
NRows = integer()
ColName = string()
Row = [Value]
Value = string() | null
ErrMsg = string()
Executes a single SQL statement. All changes to the data source are, by default, automatically committed if successful.
|
Depricated functions are only with for compatibility reason. Some of them do nothing and some are replaced by a function from above.
init_env(Server) ->
init_env(Server, Timeout) ->
{ok, void}
This function is deprecated and does nothing. It is included only for compatibility reason.
connect(Server, RefEnvHandle, ConnectStr) ->
connect(Server, RefEnvHandle, ConnectStr, Timeout) ->
connect(Server, RefEnvHandle, DSN, UID, PWD) ->
connect(Server, RefEnvHandle, DSN, UID, PWD, Timeout) ->
{ok, RefConnHandle} | {error, {Fcn, [Reason]}}
This function is deprecated and replaced by the function erl_Connect/[2, 3, 4, 5].
execute_stmt(Server, RefConnHandle, Stmt) ->
execute_stmt(Server, RefConnHandle, Stmt, Timeout) ->
{updated, NRows} | {selected, [ColName], [Row]}
{error, {Fcn, [Reason]}}
This function is deprecated and replaced by the function erl_executeStmt/[2, 3].
disconnect(Server, RefConnHandle) ->
disconnect(Server, RefConnHandle, Timeout) ->
ok | {error, {Fcn, [Reason]}}
This function is deprecated and replaced by the function erl_disconnect/[1, 2].
terminate_env(Server, RefEnvHandle) ->
terminate_env(Server, RefEnvHandle, Timeout) ->
ok
This function is deprecated and does nothing. It is included only for compatibility reason.
sql_alloc_handle(Server, HandleType, RefInputHandle) ->
sql_alloc_handle(Server, HandleType, RefInputHandle,
Timeout) ->
{0, void}
This function is deprecated and does nothing. It is included only for compatibility reason.
sql_bind_col(Server, RefStmtHandle, ColNum, RefBuf) ->
sql_bind_col(Server, RefStmtHandle, ColNum, RefBuf,
Timeout) ->
Result
This function is deprecated and replaced by the function sqlBindColumn/[3,4].
sql_close_cursor(Server, RefStmtHandle) ->
sql_close_cursor(Server, RefStmtHandle, Timeout) ->
Result
This function is deprecated and replaced by the function sqlCloseCursor/[1, 2].
sql_connect(Server, RefConnHandle, DSN, UID, Auth) ->
sql_connect(Server, RefConnHandle, DSN, UID, Auth,
Timeout) ->
Result
This function is deprecated and replaced by the function sqlConnect/[4, 5].
sql_describe_col(Server, RefStmtHandle, ColNum,
BufLenColName) ->
sql_describe_col(Server, RefStmtHandle, ColNum,
BufLenColName, Timeout) ->
{Result,{ColName, LenColName}, SqlType, ColSize, DecDigs,
Nullable}
This function is deprecated and replaced by the function sqlDescribeCol/[2, 3].
sql_disconnect(Server, RefConnHandle) ->
sql_disconnect(Server, RefConnHandle, Timeout) ->
Result
This function is deprecated and replaced by the function sqlDisConnect/[1, 2].
sql_driver_connect(Server, RefConnHandle, InConnStr,
BufLenOutConnStr, DrvCompletion) ->
sql_driver_connect(Server, RefConnHandle, InConnStr,
BufLenOutConnStr, DrvCompletion, Timeout) ->
{Result, {OutConnStr, LenOutConnStr}}
This function is deprecated and does nothing. It is included only for compatibility reason.
sql_end_tran(Server, HandleType, RefHandle,
ComplType) ->
sql_end_tran(Server, HandleType, RefHandle, ComplType,
Timeout) ->
Result
This function is deprecated and replaced by the function sqlEndTran/[2, 3].
sql_exec_direct(Server, RefStmtHandle, Stmt) ->
sql_exec_direct(Server, RefStmtHandle, Stmt, Timeout) ->
Result
This function is deprecated and replaced by the function sqlExecDirect/[1, 2].
sql_fetch(Server, RefStmtHandle) ->
sql_fetch(Server, RefStmtHandle, Timeout) ->
Result
This function is deprecated and replaced by the function sqlFetch/[1, 2].
sql_free_handle(Server, HandleType, RefHandle) ->
sql_free_handle(Server, HandleType, RefHandle, Timeout) ->
Result
This function is deprecated and does nothing. It is included only for compatibility reason.
sql_get_connect_attr(Server, RefConnHandle, Attr,
BufType) ->
sql_get_connect_attr(Server, RefConnHandle, Attr,
BufType, Timeout) ->
{Result, Value}
This function is deprecated and does nothing. It is included only for compatibility reason.
sql_get_diag_rec(Server, HandleType, RefHandle, RecNum,
BufLenErrMsg) ->
sql_get_diag_rec(Server, HandleType, RefHandle, RecNum,
BufLenErrMsg, Timeout) ->
{Result, SqlState, NativeErr, {ErrMsg, LenErrMsg}}
This function is deprecated and does nothing. It is included only for compatibility reason.
sql_num_result_cols(Server, RefStmtHandle) ->
sql_num_result_cols(Server, RefStmtHandle, Timeout) ->
{Result, ColCount}
This function is deprecated and replaced by the function sqlNumResultCol/[1, 2].
sql_row_count(Server, RefStmtHandle) ->
sql_row_count(Server, RefStmtHandle, Timeout) ->
{Result, RowCount}
This function is deprecated and replaced by the function sqlRowCount/[1, 2].
sql_set_connect_attr(Server, RefConnHandle, Attr, Value,
BufType) ->
sql_set_connect_attr(Server, RefConnHandle, Attr, Value,
BufType, Timeout) ->
Result
This function is deprecated and replaced by the function sqlSetConnectAttr/[2, 3].
sql_set_env_attr(Server, RefEnvHandle, Attr, Value, BufType)
->
sql_set_env_attr(Server, RefEnvHandle, Attr, Value, BufType,
Timeout) -> Result
This function is deprecated and does nothing. It is included only for compatibility reason.
alloc_buffer(Server, BufCType, Size) ->
alloc_buffer(Server, BufCType, Size, Timeout) ->
{ok, RefBuf}
This function is deprecated and replaced by the function columnRef/0.
dealloc_buffer(Server, RefBuf) ->
dealloc_buffer(Server, RefBuf, Timeout) ->
ok
This function is deprecated and does nothing. It is included only for compatibility reason.
read_buffer(Server, RefBuf) ->
read_buffer(Server, RefBuf, Timeout) ->
{ok, {Value, LenInd}}
This function is deprecated and replaced by the function readData/[2,3].
Errors caused by inability to contact the C node,
allocate memory, or otherwise call ODBC functions cause
exceptions. Exceptions are common to all functions.
Errors caused by ODBC not being able to execute calls are
reported through returned errors.
These exceptions terminate the client only.
gen_server
.These cause the ODBC server, and the C node, to terminate as well:
[1]: Microsoft ODBC 3.0, Programmer's Reference and SDK Guide