package freetds

  1. Overview
  2. Docs

Module Freetds.DblibSource

Low level binding to the DB-lib part of freetds. These bindings mimic the C API and therefore some functions must be used in the right order. Look at the FreeTDS User Guide and Sybase documentation for fine points. Use OCamlDBI with the freetds driver for an easier interaction with such databases.

Sourcetype dbprocess

Value that contains all information needed by Freetds.Dblib to manage communications with the server.

Sourcetype version =
  1. | V42
    (*

    Works with all products, subject to limitations.

    *)
  2. | V46
  3. | V70
    (*

    Includes support for the extended datatypes in SQL Server 7.0 (such as char/varchar fields of more than 255 characters), and support for Unicode.

    *)
  4. | V71
    (*

    Include support for bigint (64 bit integers), variant and collation on all fields. Collation is not widely used.

    *)
  5. | V72
    (*

    Includes support for varchar(max), varbinary(max), xml datatypes and MARS.

    *)
  6. | V73
    (*

    Includes support for time, date, datetime2, datetimeoffset.

    *)
  7. | V74
    (*

    Includes support for session recovery.

    *)

Protocol version. Note that the protocol version is chosen in your freetds.conf file or via the environment variable TDSVER (which supersedes the configuration file). See Choosing a TDS protocol version to help you choose. Be warned that 4.x versions of the protcol do not allow empty strings which will be returned as strings of length 1.

Sourceval connect : ?user:string -> ?password:string -> ?charset:string -> ?language:string -> ?application:string -> ?version:version -> string -> dbprocess

connect server: open a connection to the given database server.

  • parameter charset

    The name of the character set the client will use. Default values include "iso_1" for ISO-8859-1 (most platforms), "cp850" for Code Page 850 (IBM RS/6000), and "roman8" for the Roman8 character set (HP platforms). Note that, if the chosen charset is not completely compatible with the one of the database, Error(CONVERSION, msg) will be raised with msg being something like "Some character(s) could not be converted into client’s character set. Unconverted bytes were changed to question marks (‘?’)". Set an err_handler to tread these errors differently.

  • parameter application

    If given, the server uses this name in its sysprocesses table to help identify your process. If you set the application name, you will see it if you query the sysprocesses table in the master database.

  • parameter language

    The name of the national language to use. If language support is installed in the server, error messages are returned in the designated national language. Set this only if you do not wish to use the server's default national language.

  • parameter version

    protocol version for this connection. Be warned that, even if set, this is superseded by the value of the environment variable TDSVER.

  • raises Dblib.Error

    if the connection to the database could not be established. Note that if server cannot be converted to an IP address, the error message "Server name not found in configuration files" is returned in Error.

Sourceval close : dbprocess -> unit

close conn close the connection conn to the server.

Sourceval use : dbprocess -> string -> unit

use conn name change the current database to name.

Sourceval name : dbprocess -> string

name conn returns the name of the current database.

Executing SQL queries and getting the results

Sourceval sqlexec : dbprocess -> string -> unit

Send the SQL command to the server and wait for an answer.

  • raises Dblib.Error

    if the SQL query is incorrect or another problem occurs.

Warning: There is one absolutely crucial, inflexible, unalterable requirement: the application must process all rows produced by the query. Before the dbprocess can be used for another query, the application must either fetch all rows, or cancel the results and receive an acknowledgement from the server.

Sourceval cancel : dbprocess -> unit

Cancel the current command batch.

Sourceval canquery : dbprocess -> unit

Cancel the query currently being retrieved, (retriving and) discarding all pending rows.

Sourceval results : dbprocess -> bool

results conn returns true if some results are available and false if the query produced no results. There may be several results if COMPUTE clauses are used. One MUST CALL this function before trying to retrieve any rows.

  • raises Dblib.Error

    if the query was not processed successfully by the server.

Sourceval numcols : dbprocess -> int

Return number of regular columns in a result set.

Sourceval colname : dbprocess -> int -> string

colname conn c returns the name of a regular result column c. The first column has number 1.

Sourcetype col_type =
  1. | SYBCHAR
  2. | SYBVARCHAR
  3. | SYBINTN
  4. | SYBINT1
  5. | SYBINT2
  6. | SYBINT4
  7. | SYBINT8
  8. | SYBFLT8
  9. | SYBFLTN
  10. | SYBNUMERIC
  11. | SYBDECIMAL
  12. | SYBDATETIME
  13. | SYBDATETIME4
  14. | SYBDATETIMN
  15. | SYBBIT
  16. | SYBTEXT
  17. | SYBIMAGE
  18. | SYBMONEY4
  19. | SYBMONEY
  20. | SYBMONEYN
  21. | SYBREAL
  22. | SYBBINARY
  23. | SYBVARBINARY
Sourceval string_of_col_type : col_type -> string

Returns a string description of the column type.

Sourceval coltype : dbprocess -> int -> col_type

Get the datatype of a regular result set column.

Sourcetype data =
  1. | NULL
  2. | STRING of string
  3. | TINY of int
  4. | SMALL of int
  5. | INT of int
  6. | INT32 of int32
  7. | INT64 of int64
  8. | FLOAT of float
  9. | DATETIME of int * int * int * int * int * int * int * int
    (*

    (year, month, day, hour, minute, second, millisecond, zone)

    *)
  10. | MONEY of float
  11. | BIT of bool
  12. | BINARY of string
  13. | NUMERIC of string
  14. | DECIMAL of string
Sourceval string_of_data : data -> string
Sourceval nextrow : dbprocess -> data list

Retrieve the next row.

  • raises Not_found

    if no more rows are available.

Sourceval count : dbprocess -> int

Get count of rows processed.

  • for insert/update/delete, count of rows affected.
  • for select, count of rows returned, after all rows have been fetched.

Error handling

Sourcetype severity =
  1. | INFO
    (*

    Informational, non-error.

    *)
  2. | USER
    (*

    User error.

    *)
  3. | NONFATAL
    (*

    Non-fatal error.

    *)
  4. | CONVERSION
    (*

    Error in DB-Library data conversion.

    *)
  5. | SERVER
    (*

    The Server has returned an error flag.

    *)
  6. | TIME
    (*

    We have exceeded our timeout period while waiting for a response from the Server—the dbprocess is still alive.

    *)
  7. | PROGRAM
    (*

    Coding error in user program.

    *)
  8. | RESOURCE
    (*

    Running out of resources—the dbprocess may be dead.

    *)
  9. | COMM
    (*

    Failure in communication with Server—the dbprocess is dead.

    *)
  10. | FATAL
    (*

    Fatal error—the dbprocess is dead.

    *)
  11. | CONSISTENCY
    (*

    Internal software error—please open an issue.

    *)
Sourceexception Error of severity * string

Error(severity, message) is raised on dblib errors. You can change the reaction to some errors by installing your own handler with err_handler.

Sourceval err_handler : (severity -> int -> string -> unit) -> unit

err_handler f installs f as the default error handler for non-OS related errors and errors not coming from the server. f is given the severity, the number of the error (see the 400 or so error numbers sybdb.h, macros SYBE...) and the message.

Sourceval msg_handler : (severity -> int -> string -> unit) -> unit

msg_handler f installs f as the default message handler for messages coming from the server. f is given the severity, the line number, and the message.

Sourceval settime : int -> unit

settime seconds Set the number of seconds that DB-Library will wait for a server response to a SQL command. If not response is obtained within that period, raise Error(TIME, _).