odbc(3)

MODULE
odbc - Erlang ODBC application

DESCRIPTION

As mention before is the interface of the Erlang ODBC application is divided into four parts:

    *   Start and Stop
        Starts and stops a gen_server process.

    *   Basic API
        Gives access to basic ODBC functions.

    *   Utility API
        Consists of functions that are easier to use than the Basic API. These functions are on a higher level, do more of the job, but allow less control to the application programmer.

    *   Depricated functions
         are only with for compatibility reason. Some of them do nothing and some are replaced by a function from Basic or Utility API.

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 and Stop

EXPORTS

start_link(Args, Options) ->
start_link(ServerName, Args, Options) -> Result

    Types
        Args = []
        Options = [Opt]
        Opt = This are options which are used by the gen_server module.
           For information see the module documentation gen_server and sys.
        ServerName = {local, atom()} | {global, atom()}
           When supplied, causes the server to be registered locally or globally. If the server is started without a name it can only be called using the returned pid.
        Result = {ok, pid()} | {error, Reason}
           The pid of the server or an error tuple.
        Reason = {already_started, pid()} | timeout | {no_c_node, Info}
           The server was already started, a timeout has expired, or the C node could not be started (the program may not have been found or may not have been executable e.g.).
        Info = string()
          More information.

    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.

  Note:

There is no default timeout value. Not using the timeout option is equivalent to having an infinite timeout value.
 An expired timeout is reported as an error here, not an exception.
 The debug options are described in the sys module documentation.

stop(Server) ->
stop(Server, Timeout) -> ok

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Timeout = integer() | infinity
           Max time (ms) for serving the request.

    Stops the ODBC server process as soon as all already submitted requests have been processed. The C node is also stopped.

Basic API

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.

EXPORTS

sqlBindColumn(Server, ColNum, Ref) ->
sqlBindColumn(Server, ColNum, Ref, Timeout) -> Result | {error, ErrMsg, ErrCode}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        ColNum = integer()
           Column number from left to right starting at 1.
        Ref = term()
           A reference.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ErrMsg = string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ErrMsg = string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        DSN = string()
          The name of the database.
        UID = string()
           The user ID
        Auth = string()
           The user's password for the database.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        ColNum = integer()
           The column number from left to right, starting at 1.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ColName = string()
           The column name.
        Nullable = ?SQL_NO_NULLS | ?SQL_NULLABLE | ?SQL_NULLABLE_UNKNOWN
          Indicates whether the column allows null values or not.
        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        ComplType = ?SQL_COMMIT | ?SQL_ROLLBACK
          Commit operation or rollback operation.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ErrMsg -> string()
          Error message.
        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].

  Note:

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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Stmt = string()
           An SQL statement.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO | ?SQL_NEED_DATA | ?SQL_NO_DATA

        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO | ?SQL_NO_DATA

        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ColCount = integer()
          The number of columns in the result set.
        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO
           Result macro.
        RowCount = integer()
          The number of affected rows. If the number of affected rows is not available -1 is returned. For exceptions, see SQLRowCount in [1].
        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Attr = integer()
          One of the attributes described further down are supported. The attributes defined by ODBC are supplied through macros, but driver-specific attributes are not.
        Value = string() | integer()
          The new attribute value.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Result = ?SQL_SUCCESS | ?SQL_SUCCESS_WITH_INFO

        ErrMsg -> string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Ref
          A reference to the column.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        Value = string()
           Contents of the column associated with Ref.

    Returns the contents of a deferred data buffer and its associated length/indicator buffer. Used in connection with sqlFetch/[1, 2].

columnRef() -> {ok, Ref}

    Types
        Ref
          A reference.

    Returns a reference. The reference is assigned to a column in the function sqlBindColumn/[3, 4].

Utility API

Erlang ODBC application Utility API has a few easy-to-use function. The reported errors are tuples with arity 3.

EXPORTS

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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        ConnectStr = string()
           Connection string. For syntax see SQLDriverConnect in [1].
        DSN = string()
           Name of the database.
        UID = string()
           User ID.
        PWD = string()
           Password.
        Timeout = integer() | infinity
          Maximum time (ms) for serving the request.
        ErrMsg = string()
           Error message.
        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.

  Note:

The syntax to be used for ConnectStr is described under SQLDriverConnect in [1]. The ConnectStr must be complete.

erl_disconnect(Server) ->
erl_disconnect(Server, Timeout) -> ok | {error, ErrMsg, ErrCode}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
         ErrMsg = string()
          Error message.
        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}

    Types
        Server = pid() | Name | {global, Name} | {Name, Node}
          The pid of the server process, a registered name, a globally registered name, or a registered name on a remote node.
        Stmt = string()
           SQL statement to execute.
        Timeout = integer() | infinity
           Maximum time (ms) for serving the request.
        NRows = integer()
           The number of updated rows for UPDATE, INSERT, or DELETE statements, or -1 if the number is not available. For other statement types the value is driver defined, see [1].
        ColName = string()
          The name of a column in the resulting table.
        Row = [Value]
           One row of the resulting table.
        Value = string() | null
          One value in a row.
        ErrMsg = string()
          Error message.

    Executes a single SQL statement. All changes to the data source are, by default, automatically committed if successful.

  Note:

{updated, 0} or {updated, -1} is returned when a statement that does not select or update any rows is successfully executed.
 The ColNames are ordered the same way as the Values in the Rows (the first ColName is associated with the first Value of each Row etc.). The Rows have no defined order since they represent a set.

Depricated functions

Depricated functions are only with for compatibility reason. Some of them do nothing and some are replaced by a function from above.

EXPORTS

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].

Error Messages and Exceptions

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.

    *   {'EXIT', {badarg, F, ArgNo, Info}}
         The argument is of wrong type or out of range.

    *   {'EXIT', GenServerSpecificInfo}
         Error detected by gen_server.

These cause the ODBC server, and the C node, to terminate as well:

    *   {'EXIT', {timeout, Info}}
         Timeout expired.

    *   {'EXIT', {stopped, Reason}}
         The ODBC server died.

References

[1]: Microsoft ODBC 3.0, Programmer's Reference and SDK Guide

AUTHOR
Ingvar Meyer - support@erlang.ericsson.se