Main Page   Modules   Compound List   File List   Compound Members   File Members   Related Pages  

tds.h File Reference

Main include file for libtds. More...

#include <stdio.h>
#include <stdarg.h>
#include <time.h>
#include "tdsver.h"
#include "tds_sysdep_public.h"

Go to the source code of this file.

Compounds

struct  _tds_cursor
struct  _tds_cursor_status
struct  BCP_COLINFO
struct  tds_answer
struct  _tds_compiletime_settings
 A structure to hold all the compile-time settings. More...

struct  _tds_encoding
 Information relevant to libiconv. More...

struct  DSTR_STRUCT
struct  TDS8_COLLATION
 TDS 8.0 collation information. More...

union  tds_align_struct
struct  tds_blob_info
 Information about blobs (e.g. More...

struct  tds_column_info
 Metadata about columns in regular and compute rows. More...

struct  tds_connect_info
struct  tds_context
struct  tds_dynamic
struct  tds_env_info
struct  tds_locale
struct  tds_login
struct  tds_msg_info
union  tds_option_arg
struct  tds_result_info
 Hold information for any results. More...

struct  tds_socket
struct  tds_upd_col
struct  tdsdaterec
 information on data, used by tds_datecrack More...

struct  tdsdatetime
struct  tdsdatetime4
union  tdsmoney
struct  tdsmoney4
struct  tdsnumeric
struct  tdsoldmoney
struct  tdsunique
struct  tdsvarbinary
struct  tdsvarchar

Defines

#define TDS_IS_SYBASE(x)   (!(x->product_version & 0x80000000u))
 Check if product is Sybase (such as Adaptive Server Enterrprice).

#define TDS_IS_MSSQL(x)   ((x->product_version & 0x80000000u)!=0)
 Check if product is Microsft SQL Server.

#define TDS_MS_VER(maj, min, x)   (0x80000000u|((maj)<<24)|((min)<<16)|(x))
 Calc a version number for mssql.

#define TDS_SYB_VER(maj, min, x)   (((maj)<<24)|((min)<<16)|(x)<<8)
 Calc a version number for Sybase.


Typedefs

typedef _tds_compiletime_settings TDS_COMPILETIME_SETTINGS
 A structure to hold all the compile-time settings.

typedef tdsdaterec TDSDATEREC
 information on data, used by tds_datecrack

typedef tds_blob_info TDSBLOBINFO
 Information about blobs (e.g.

typedef _tds_encoding TDS_ENCODING
 Information relevant to libiconv.

typedef tds_column_info TDSCOLINFO
 Metadata about columns in regular and compute rows.

typedef tds_result_info TDSRESULTINFO
 Hold information for any results.


Enumerations

enum  TDS_OPTION_CMD
 options that can be sent with a TDS_OPTIONCMD token

enum  TDS_DBG_LOG_STATE
 An attempt at better logging. More...


Functions

int tds_put_string (TDSSOCKET *tds, const char *buf, int len)
 Output a string to wire automatic translate string to unicode if needed.

const TDS_COMPILETIME_SETTINGStds_get_compiletime_settings (void)
 Return a structure capturing the compile-time settings provided to the configure script.

int tds_read_conf_section (FILE *in, const char *section, TDSCONFPARSE tds_conf_parse, void *parse_param)
 Read a section of configuration file (INI style file).

int tds_read_conf_file (TDSCONNECTINFO *connect_info, const char *server)
 Read configuration info for given server return 0 on error.

TDSCONNECTINFO * tds_read_config_info (TDSSOCKET *tds, TDSLOGIN *login, TDSLOCALE *locale)
 tds_read_config_info() will fill the tds connect_info structure based on configuration information gathered in the following order: 1) Program specified in TDSLOGIN structure 2) The environment variables TDSVER, TDSDUMP, TDSPORT, TDSQUERY, TDSHOST 3) A config file with the following search order: a) a readable file specified by environment variable FREETDSCONF b) a readable file in ~/.freetds.conf c) a readable file in $prefix/etc/freetds.conf 3) ~/.interfaces if exists 4) $SYBASE/interfaces if exists 5) TDS_DEF_* default values

void tds_fix_connect (TDSCONNECTINFO *connect_info)
 Fix configuration after reading it.

void tds_config_verstr (const char *tdsver, TDSCONNECTINFO *connect_info)
 Set TDS version from given string.

void tds_lookup_host (const char *servername, char *ip)
 Given a servername and port name or number, lookup the hostname and service.

int tds_set_interfaces_file_loc (const char *interfloc)
 Set the full name of interface file.

TDSLOCALE * tds_get_locale (void)
 Get locale information.

unsigned char * tds_alloc_row (TDSRESULTINFO *res_info)
 Allocate space for row store return NULL on out of memory.

int tds_alloc_get_string (TDSSOCKET *tds, char **string, int len)
 Read a string from wire in a new allocated buffer.

void tds_set_null (unsigned char *current_row, int column)
 set the null bit for the given column in the row buffer

void tds_clr_null (unsigned char *current_row, int column)
 clear the null bit for the given column in the row buffer

int tds_get_null (unsigned char *current_row, int column)
 Return the null bit for the given column in the row buffer.

unsigned char * tds7_crypt_pass (const unsigned char *clear_pass, int len, unsigned char *crypt_pass)
 tds7_crypt_pass() -- 'encrypt' TDS 7.0 style passwords.

TDSDYNAMIC * tds_lookup_dynamic (TDSSOCKET *tds, char *id)
 Find a dynamic given string id.

int tds_iconv_alloc (TDSSOCKET *tds)
 Allocate iconv stuff.

TDSICONVINFO * tds_iconv_from_lcid (TDSSOCKET *tds, int lcid)
 Get iconv information from a LCID (to support different column encoding under MSSQL2K).

char * tds_get_homedir (void)
 Get user home directory.

unsigned char * tds_alloc_param_row (TDSPARAMINFO *info, TDSCOLINFO *curparam)
 Add another field to row.

TDSCONNECTINFO * tds_alloc_connect (TDSLOCALE *locale)
 Allocate space for configure structure and initialize with default values.

int tds_connect (TDSSOCKET *tds, TDSCONNECTINFO *connect_info)
 Do a connection to socket.

int tds_submit_query (TDSSOCKET *tds, const char *query)
 tds_submit_query() sends a language string to the database server for processing.

int tds_submit_query_params (TDSSOCKET *tds, const char *query, TDSPARAMINFO *params)
 tds_submit_query_params() sends a language string to the database server for processing.

int tds_submit_prepare (TDSSOCKET *tds, const char *query, const char *id, TDSDYNAMIC **dyn_out, TDSPARAMINFO *params)
 tds_submit_prepare() creates a temporary stored procedure in the server.

int tds_submit_execdirect (TDSSOCKET *tds, const char *query, TDSPARAMINFO *params)
 Currently works with TDS 5.0 and TDS7+.

int tds_submit_execute (TDSSOCKET *tds, TDSDYNAMIC *dyn)
 tds_submit_execute() sends a previously prepared dynamic statement to the server.

int tds_send_cancel (TDSSOCKET *tds)
 tds_send_cancel() sends an empty packet (8 byte header only) tds_process_cancel should be called directly after this.

const char * tds_next_placeholders (const char *start)
 Get position of next placeholders.

int tds_count_placeholders (const char *query)
 Count the number of placeholders in query.

int tds_get_dynid (TDSSOCKET *tds, char **id)
 Get an id for dynamic query based on TDS information.

int tds_submit_unprepare (TDSSOCKET *tds, TDSDYNAMIC *dyn)
 Send a unprepare request for a prepared query.

int tds_submit_rpc (TDSSOCKET *tds, const char *rpc_name, TDSPARAMINFO *params)
 tds_submit_rpc() call a RPC from server.

int tds_quote_id (TDSSOCKET *tds, char *buffer, const char *id, int idlen)
 Quote an id.

int tds_quote_string (TDSSOCKET *tds, char *buffer, const char *str, int len)
 Quote a string.

const char * tds_skip_quoted (const char *s)
 Skip quoting string (like 'sfsf', "dflkdj" or [dfkjd]).

int tds_process_cancel (TDSSOCKET *tds)
 tds_process_cancel() processes the incoming token stream until it finds an end token (DONE, DONEPROC, DONEINPROC) with the cancel flag set.

int tds_get_token_size (int marker)
 tds_get_token_size() returns the size of a fixed length token used by tds_process_cancel() to determine how to read past a token

int tds_process_login_tokens (TDSSOCKET *tds)
 tds_process_login_tokens() is called after sending the login packet to the server.

void tds_add_row_column_size (TDSRESULTINFO *info, TDSCOLINFO *curcol)
 Add a column size to result info row size and calc offset into row.

int tds_process_simple_query (TDSSOCKET *tds)
 Process results for simple query as "SET TEXTSIZE" or "USE dbname" If the statement returns results, beware they are discarded.

int tds_process_result_tokens (TDSSOCKET *tds, TDS_INT *result_type, int *done_flags)
 process TDS result-type message streams.

int tds_process_row_tokens (TDSSOCKET *tds, TDS_INT *rowtype, TDS_INT *computeid)
 process TDS row-type message streams.

int tds_process_trailing_tokens (TDSSOCKET *tds)
 tds_process_trailing_tokens() is called to discard messages that may be left unprocessed at the end of a result "batch".

int tds_client_msg (TDSCONTEXT *tds_ctx, TDSSOCKET *tds, int msgnum, int level, int state, int line, const char *message)
 tds_client_msg() sends a message to the client application from the CLI or TDS layer.

int tds_do_until_done (TDSSOCKET *tds)
 simple flush function.

void tds_set_param_type (TDSSOCKET *tds, TDSCOLINFO *curcol, TDS_SERVER_TYPE type)
 Set type of column initializing all dependency.

void tds_set_column_type (TDSCOLINFO *curcol, int type)
 Set type of column initializing all dependency.

TDS_INT tds_datecrack (TDS_INT datetype, const void *di, TDSDATEREC *dr)
 Convert from db date format to a structured date format.

int tds_get_conversion_type (int srctype, int colsize)
 Return type suitable for conversions (convert all nullable types to fixed type).

int tds_flush_packet (TDSSOCKET *tds)
 Flush packet to server.

int tds7_put_bcpcol (TDSSOCKET *tds, const BCP_COLINFO *bcpcol)
 Write a column's data to the TDS bcp stream.

TDS_SMALLINT tds_get_smallint (TDSSOCKET *tds)
 Get an int16 from the server.

TDS_INT tds_get_int (TDSSOCKET *tds)
 Get an int32 from the server.

int tds_get_string (TDSSOCKET *tds, int string_len, char *dest, size_t dest_size)
 Fetch a string from the wire.

int tds_get_char_data (TDSSOCKET *tds, char *dest, size_t wire_size, TDSCOLINFO *curcol)
 Fetch character data the wire.

void * tds_get_n (TDSSOCKET *tds, void *dest, int n)
 Get N bytes from the buffer and return them in the already allocated space given to us.

int tds_get_size_by_type (int servertype)
 Return the number of bytes needed by specified type.

int tds_read_packet (TDSSOCKET *tds)
 Read in one 'packet' from the server.

int tds_version (TDSSOCKET *tds_socket, char *pversion_string)
 Returns the version of the TDS protocol in effect for the link as a decimal integer.

void tdsdump_off (void)
 Temporarily turn off logging.

void tdsdump_on (void)
 Turn logging back on.

int tdsdump_open (const char *filename)
 This creates and truncates a human readable dump file for the TDS traffic.

void tdsdump_close (void)
 Close the TDS dump log file.

void tdsdump_dump_buf (const void *buf, int length)
 Dump the contents of data into the log file in a human readable format.

void tds_answer_challenge (const char *passwd, const unsigned char *challenge, TDSANSWER *answer)
 Crypt a given password using schema required for NTLMv1 authentication.


Variables

const int tds_numeric_bytes_per_prec []
 The following little table is indexed by precision and will tell us the number of bytes required to store the specified precision.


Detailed Description

Main include file for libtds.


Define Documentation

#define is_end_token  
 

Value:

(x==TDS_DONE_TOKEN    || \
                        x==TDS_DONEPROC_TOKEN    || \
                        x==TDS_DONEINPROC_TOKEN)

#define is_fixed_type  
 

Value:

(x==SYBINT1    || \
                        x==SYBINT2      || \
                        x==SYBINT4      || \
                        x==SYBINT8      || \
                        x==SYBREAL       || \
                        x==SYBFLT8      || \
                        x==SYBDATETIME  || \
                        x==SYBDATETIME4 || \
                        x==SYBBIT       || \
                        x==SYBMONEY     || \
                        x==SYBMONEY4    || \
                        x==SYBUNIQUE)

#define is_hard_end_token  
 

Value:

(x==TDS_DONE_TOKEN    || \
                        x==TDS_DONEPROC_TOKEN)

#define is_msg_token  
 

Value:

(x==TDS_INFO_TOKEN    || \
                        x==TDS_ERROR_TOKEN    || \
                        x==TDS_EED_TOKEN)

#define is_nullable_type  
 

Value:

( \
                        x==SYBBITN      || \
                     x==SYBINTN      || \
                     x==SYBFLTN      || \
                     x==SYBMONEYN    || \
                     x==SYBDATETIMN  || \
                     x==SYBCHAR      || \
                     x==SYBVARCHAR   || \
                     x==SYBBINARY    || \
                     x==SYBVARBINARY || \
                     x==SYBTEXT      || \
                     x==SYBNTEXT     || \
                     x==SYBIMAGE)

#define is_result_token  
 

Value:

(x==TDS_RESULT_TOKEN    || \
                        x==TDS_ROWFMT2_TOKEN || \
                        x==TDS7_RESULT_TOKEN    || \
                        x==TDS_COLFMT_TOKEN    || \
                        x==TDS_COLNAME_TOKEN)

#define TDS_BYTE_SWAP16 value   
 

Value:

(((((unsigned short)value)<<8) & 0xFF00)   | \
          ((((unsigned short)value)>>8) & 0x00FF))

#define TDS_BYTE_SWAP32 value   
 

Value:

(((((unsigned long)value)<<24) & 0xFF000000)  | \
          ((((unsigned long)value)<< 8) & 0x00FF0000)  | \
          ((((unsigned long)value)>> 8) & 0x0000FF00)  | \
          ((((unsigned long)value)>>24) & 0x000000FF))

#define TDS_IS_MSSQL      ((x->product_version & 0x80000000u)!=0)
 

Check if product is Microsft SQL Server.

x should be a TDS_SOCKET*.

#define TDS_IS_SYBASE      (!(x->product_version & 0x80000000u))
 

Check if product is Sybase (such as Adaptive Server Enterrprice).

x should be a TDS_SOCKET*.

#define TDS_MS_VER maj,
min,
     (0x80000000u|((maj)<<24)|((min)<<16)|(x))
 

Calc a version number for mssql.

Use with TDS_MS_VER(7,0,842). For test for a range of version you can use check like if (tds->product_version >= TDS_MS_VER(7,0,0) && tds->product_version < TDS_MS_VER(8,0,0))


Typedef Documentation

typedef struct _tds_compiletime_settings TDS_COMPILETIME_SETTINGS
 

A structure to hold all the compile-time settings.

This structure is returned by tds_get_compiletime_settings

typedef struct _tds_encoding TDS_ENCODING
 

Information relevant to libiconv.

The name is an iconv name, not the same as found in master..syslanguages.

typedef struct tds_blob_info TDSBLOBINFO
 

Information about blobs (e.g.

text or image). current_row contains this structure.


Enumeration Type Documentation

enum TDS_DBG_LOG_STATE
 

An attempt at better logging.

Using these bitmapped values, various logging features can be turned on and off. It can be especially helpful to turn packet data on/off for security reasons.


Function Documentation

unsigned char* tds7_crypt_pass const unsigned char *    clear_pass,
int    len,
unsigned char *    crypt_pass
 

tds7_crypt_pass() -- 'encrypt' TDS 7.0 style passwords.

the calling function is responsible for ensuring crypt_pass is at least 'len' characters

int tds7_put_bcpcol TDSSOCKET *    tds,
const BCP_COLINFO *    bcpcol
 

Write a column's data to the TDS bcp stream.

Data may be null.

Return values:
TDS_SUCCEED  data written
TDS_FAIL  must not write null data non-null column
Remarks:
Most other write functions simply return zero.

void tds_add_row_column_size TDSRESULTINFO   info,
TDSCOLINFO   curcol
 

Add a column size to result info row size and calc offset into row.

Parameters:
info  result where to add column
curcol  column to add

TDSCONNECTINFO* tds_alloc_connect TDSLOCALE *    locale
 

Allocate space for configure structure and initialize with default values.

Parameters:
locale  locale information (copied to configuration information)
Returns:
allocated structure or NULL if out of memory

int tds_alloc_get_string TDSSOCKET *    tds,
char **    string,
int    len
 

Read a string from wire in a new allocated buffer.

Parameters:
len  length of string to read

unsigned char* tds_alloc_param_row TDSPARAMINFO *    info,
TDSCOLINFO   curparam
 

Add another field to row.

Is assumed that last TDSCOLINFO contain information about this. Update also info structure.

Parameters:
info  parameters info where is contained row
curparam  parameter to retrieve size information
Returns:
NULL on failure or new row

void tds_answer_challenge const char *    passwd,
const unsigned char *    challenge,
TDSANSWER *    answer
 

Crypt a given password using schema required for NTLMv1 authentication.

Parameters:
passwd  clear text domain password
challenge  challenge data given by server
answer  buffer where to store crypted password

int tds_client_msg TDSCONTEXT *    tds_ctx,
TDSSOCKET *    tds,
int    msgnum,
int    level,
int    state,
int    line,
const char *    message
 

tds_client_msg() sends a message to the client application from the CLI or TDS layer.

A client message is one that is generated from with the library and not from the server. The message is sent to the CLI (the err_handler) so that it may forward it to the client application or discard it if no msg handler has been by the application. tds->parent contains a void pointer to the parent of the tds socket. This can be cast back into DBPROCESS or CS_CONNECTION by the CLI and used to determine the proper recipient function for this message.

Todo:
This procedure is deprecated, because the client libraries use differing messages and message numbers. The general approach is to emit ct-lib error information and let db-lib and ODBC map that to their number and text.

void tds_config_verstr const char *    tdsver,
TDSCONNECTINFO *    connect_info
 

Set TDS version from given string.

Parameters:
tdsver  tds string version
connect_info  where to store information

int tds_connect TDSSOCKET *    tds,
TDSCONNECTINFO *    connect_info
 

Do a connection to socket.

Parameters:
tds  connection structure. This should be a non-connected connection. If the function fail connection is deleted
connect_info  info for connection
Returns:
TDS_FAIL or TDS_SUCCEED

TDS_INT tds_datecrack TDS_INT    datetype,
const void *    di,
TDSDATEREC   dr
 

Convert from db date format to a structured date format.

Parameters:
datetype  source date type. SYBDATETIME or SYBDATETIME4
di  source date
dr  destination date
Returns:
TDS_FAIL or TDS_SUCCEED

int tds_do_until_done TDSSOCKET *    tds
 

simple flush function.

maybe be superseded soon.

void tds_fix_connect TDSCONNECTINFO *    connect_info
 

Fix configuration after reading it.

Currently this read some environment variables and replace some options.

int tds_flush_packet TDSSOCKET *    tds
 

Flush packet to server.

Returns:
TDS_FAIL or TDS_SUCCEED

int tds_get_char_data TDSSOCKET *    tds,
char *    row_buffer,
size_t    wire_size,
TDSCOLINFO   curcol
 

Fetch character data the wire.

Output is NOT null terminated. If iconv_info is not NULL, convert data accordingly.

Parameters:
row_buffer  destination buffer in current_row. Can't be NULL
wire_size  size to read from wire (in bytes)
curcol  column information
Returns:
TDS_SUCCEED or TDS_FAIL (probably memory error on text data)
Todo:
put a TDSICONVINFO structure in every TDSCOLINFO

int tds_get_conversion_type int    srctype,
int    colsize
 

Return type suitable for conversions (convert all nullable types to fixed type).

Parameters:
srctype  type to convert
colsize  size of type
Returns:
type for conversion

int tds_get_dynid TDSSOCKET *    tds,
char **    id
 

Get an id for dynamic query based on TDS information.

Parameters:
tds  state information for the socket and the TDS protocol
Returns:
TDS_FAIL or TDS_SUCCEED

char* tds_get_homedir void   
 

Get user home directory.

Returns:
home directory or NULL if error. Should be freed with free

TDSLOCALE* tds_get_locale void   
 

Get locale information.

Returns:
allocated structure with all information or NULL if error

void* tds_get_n TDSSOCKET *    tds,
void *    dest,
int    need
 

Get N bytes from the buffer and return them in the already allocated space given to us.

We ASSUME that the person calling this function has done the bounds checking for us since they know how many bytes they want here. dest of NULL means we just want to eat the bytes. (tetherow@nol.org)

int tds_get_string TDSSOCKET *    tds,
int    string_len,
char *    dest,
size_t    dest_size
 

Fetch a string from the wire.

Output string is NOT null terminated. If TDS version is 7 or 8 read unicode string and convert it. This function should be use to read server default encoding strings like columns name, table names, etc, not for data (use tds_get_char_data instead)

Returns:
bytes written to dest
Parameters:
tds  connection information
string_len  length of string to read from wire (in server characters, bytes for tds4-tds5, ucs2 for tds7+)
dest  destination buffer, if NULL string is read and discarded
dest_size  destination buffer size, in bytes

int tds_iconv_alloc TDSSOCKET *    tds
 

Allocate iconv stuff.

Returns:
0 for success

TDSDYNAMIC* tds_lookup_dynamic TDSSOCKET *    tds,
char *    id
 

Find a dynamic given string id.

Returns:
dynamic or NULL is not found
Parameters:
id  dynamic id to search

void tds_lookup_host const char *    servername,
char *    ip
 

Given a servername and port name or number, lookup the hostname and service.

The server ip will be stored in the string 'servername' in dotted-decimal notation. The service port number will be stored in string form in the 'port' parameter.

If we can't determine both the IP address and port number then 'ip' and 'port' will be set to empty strings.

const char* tds_next_placeholders const char *    start
 

Get position of next placeholders.

Parameters:
start  pointer to part of query to search
Returns:
next placaholders or NULL if not found

int tds_process_cancel TDSSOCKET *    tds
 

tds_process_cancel() processes the incoming token stream until it finds an end token (DONE, DONEPROC, DONEINPROC) with the cancel flag set.

a that point the connetion should be ready to handle a new query.

int tds_process_login_tokens TDSSOCKET *    tds
 

tds_process_login_tokens() is called after sending the login packet to the server.

It returns the success or failure of the login dependent on the protocol version. 4.2 sends an ACK token only when successful, TDS 5.0 sends it always with a success byte within

int tds_process_result_tokens TDSSOCKET *    tds,
TDS_INT *    result_type,
int *    done_flags
 

process TDS result-type message streams.

tds_process_result_tokens() is called after submitting a query with tds_submit_query() and is responsible for calling the routines to populate tds->res_info if appropriate (some query have no result sets)

Parameters:
tds  A pointer to the TDSSOCKET structure managing a client/server operation.
result_type  A pointer to an integer variable which tds_process_result_tokens sets to indicate the current type of result.

Values that indicate command status
TDS_DONE_RESULTThe results of a command have been completely processed. This command return no rows.
TDS_DONEPROC_RESULTThe results of a command have been completely processed. This command return rows.
TDS_DONEINPROC_RESULTThe results of a command have been completely processed. This command return rows.
Values that indicate results information is available
TDS_ROWFMT_RESULTRegular Data format information tds->res_info now contains the result details ; tds->curr_resinfo now points to that data
TDS_COMPUTEFMT_ RESULTCompute data format information tds->comp_info now contains the result data; tds->curr_resinfo now points to that data
TDS_DESCRIBE_RESULT
Values that indicate data is available
ValueMeaningInformation returned
TDS_ROW_RESULTRegular row results 1 or more rows of regular data can now be retrieved
TDS_COMPUTE_RESULTCompute row results A single row of compute data can now be retrieved
TDS_PARAM_RESULTReturn parameter results param_info or cur_dyn->params contain returned parameters
TDS_STATUS_RESULTStored procedure status results tds->ret_status contain the returned code

Todo:
Complete TDS_DESCRIBE_RESULT description
Return values:
TDS_SUCCEED  if a result set is available for processing.
TDS_NO_MORE_RESULTS  if all results have been completely processed.
Examples
The following code is cut from ct_results(), the ct-library function
done = 0;

    /* see what "result" tokens we have. a "result" in ct-lib terms also  */
    /* includes row data. Some result types always get reported back  to  */
    /* the calling program, others are only reported back if the relevant */
    /* config flag is set.                                                */

while (!done) {

        tdsret = tds_process_result_tokens(tds, &res_type, NULL);

        switch (tdsret) {

        case TDS_SUCCEED:

                cmd->curr_result_type = res_type;

                switch (res_type) {
                case TDS_COMPUTEFMT_RESULT:
                case TDS_ROWFMT_RESULT:
                        if (context->config.cs_expose_formats) {
                                done = 1;
                                retcode = CS_SUCCEED;
                                *result_type = res_type;
                        }
                        break;

                case TDS_COMPUTE_RESULT:
                        /* we've hit a compute data row. We have to get hold of this */
                        /* data now, as it's necessary  to tie this data back to its */
                        /* result format...the user may call ct_res_info() & friends */
                        /* after getting back a compute "result".                    */

                        tdsret = tds_process_row_tokens(tds, &rowtype, &computeid);

                        if (tdsret == TDS_SUCCEED) {
                                if (rowtype == TDS_COMP_ROW) {
                                        cmd->row_prefetched = 1;
                                        retcode = CS_SUCCEED;
                                } else {
                                        /* this couldn't really happen, but... */
                                        retcode = CS_FAIL;
                                }
                        } else
                                retcode = CS_FAIL;
                        done = 1;
                        *result_type = res_type;
                        break;

                case TDS_DONE_RESULT:
                case TDS_DONEPROC_RESULT:
                case TDS_DONEINPROC_RESULT:

                        /* there's a distinction in ct-library     */
                        /* depending on whether a command returned */
                        /* results or not...                          */

                        if (tds->res_info)
                                *result_type = CS_CMD_DONE;
                        else
                                *result_type = CS_CMD_SUCCEED;

                        retcode = CS_SUCCEED;
                        done = 1;
                        break;


                default:
                        retcode = CS_SUCCEED;
                        *result_type = res_type;
                        done = 1;
                        break;
                }
                break;

        case TDS_NO_MORE_RESULTS:
                done = 1;
                retcode = CS_END_RESULTS;
                break;
        case TDS_FAIL:
                done = 1;
                retcode = CS_FAIL;
                break;
        }
}

int tds_process_row_tokens TDSSOCKET *    tds,
TDS_INT *    rowtype,
TDS_INT *    computeid
 

process TDS row-type message streams.

tds_process_row_tokens() is called once a result set has been obtained with tds_process_result_tokens(). It calls tds_process_row() to copy data into the row buffer.

Parameters:
tds  A pointer to the TDSSOCKET structure managing a client/server operation.
rowtype  A pointer to an integer variable which tds_process_row_tokens sets to indicate the current type of row
computeid  A pointer to an integer variable which tds_process_row_tokens sets to identify the compute_id of the row being returned. A compute row is a row that is generated by a compute clause. The compute_id matches the number of the compute row that was read; the first compute row is 1, the second is 2, and so forth.
Possible values of *rowtype
  • TDS_REG_ROW A regular data row
  • TDS_COMP_ROW A row of compute data
  • TDS_NO_MORE_ROWS There are no more rows of data in this result set
Return values:
TDS_SUCCEED  A row of data is available for processing.
TDS_NO_MORE_ROWS  All rows have been completely processed.
TDS_FAIL  An unexpected error occurred
Examples
The following code is cut from dbnextrow(), the db-library function
if ((ret = tds_process_row_tokens(dbproc->tds_socket, &rowtype, &computeid))
    == TDS_SUCCEED) {
        if (rowtype == TDS_REG_ROW) {
                /* Add the row to the row buffer */
                resinfo = tds->curr_resinfo;
                buffer_add_row(&(dbproc->row_buf), resinfo->current_row,
                                        resinfo->row_size);
                result = REG_ROW;
        } else if (rowtype == TDS_COMP_ROW) {
                /* Add the row to the row buffer */
                resinfo = tds->curr_resinfo;
                buffer_add_row(&(dbproc->row_buf), resinfo->current_row,
                                        resinfo->row_size);
                result = computeid;
        } else
                result = FAIL;
} else if (ret == TDS_NO_MORE_ROWS) {
        result = NO_MORE_ROWS;
} else
        result = FAIL;

int tds_process_simple_query TDSSOCKET *    tds
 

Process results for simple query as "SET TEXTSIZE" or "USE dbname" If the statement returns results, beware they are discarded.

This function was written to avoid direct calls to tds_process_default_tokens (which caused problems such as ignoring query errors). Results are read until idle state or severe failure (do not stop for statement failure).

Returns:
see tds_process_result_tokens for results (TDS_NO_MORE_RESULTS is never returned)

int tds_process_trailing_tokens TDSSOCKET *    tds
 

tds_process_trailing_tokens() is called to discard messages that may be left unprocessed at the end of a result "batch".

In dblibrary, it is valid to process all the data rows that a command may have returned but to leave end tokens etc. unprocessed (at least explicitly) This function is called to discard such tokens. If it comes across a token that does not fall into the category of valid "trailing" tokens, it will return TDS_FAIL, allowing the calling dblibrary function to return a "results pending" message. The valid "trailing" tokens are :

TDS_DONE_TOKEN TDS_DONEPROC_TOKEN TDS_DONEINPROC_TOKEN TDS_RETURNSTATUS_TOKEN TDS_PARAM_TOKEN TDS5_PARAMFMT_TOKEN TDS5_PARAMS_TOKEN

int tds_put_string TDSSOCKET *    tds,
const char *    s,
int    len
 

Output a string to wire automatic translate string to unicode if needed.

Parameters:
s  string to write
len  length of string in characters, or -1 for null terminated

int tds_quote_id TDSSOCKET *    tds,
char *    buffer,
const char *    id,
int    idlen
 

Quote an id.

Parameters:
tds  state information for the socket and the TDS protocol
buffer  buffer to store quoted id. If NULL do not write anything (useful to compute quote length)
id  id to quote
idlen  id length
Returns:
written chars (not including needed terminator)

int tds_quote_string TDSSOCKET *    tds,
char *    buffer,
const char *    str,
int    len
 

Quote a string.

Parameters:
tds  state information for the socket and the TDS protocol
buffer  buffer to store quoted id. If NULL do not write anything (useful to compute quote length)
str  string to quote (not necessary null-terminated)
len  length of string (-1 for null terminated)
Returns:
written chars (not including needed terminator)

int tds_read_conf_file TDSCONNECTINFO *    connect_info,
const char *    server
 

Read configuration info for given server return 0 on error.

Parameters:
connect_info  where to store configuration
server  section of file configuration that hold configuration for a server

int tds_read_conf_section FILE *    in,
const char *    section,
TDSCONFPARSE    tds_conf_parse,
void *    param
 

Read a section of configuration file (INI style file).

Parameters:
in  configuration file
section  section to read
tds_conf_parse  callback that receive every entry in section
param  parameter to pass to callback function

TDSCONNECTINFO* tds_read_config_info TDSSOCKET *    tds,
TDSLOGIN *    login,
TDSLOCALE *    locale
 

tds_read_config_info() will fill the tds connect_info structure based on configuration information gathered in the following order: 1) Program specified in TDSLOGIN structure 2) The environment variables TDSVER, TDSDUMP, TDSPORT, TDSQUERY, TDSHOST 3) A config file with the following search order: a) a readable file specified by environment variable FREETDSCONF b) a readable file in ~/.freetds.conf c) a readable file in $prefix/etc/freetds.conf 3) ~/.interfaces if exists 4) $SYBASE/interfaces if exists 5) TDS_DEF_* default values

.tdsrc and freetds.conf have been added to make the package easier to integration with various Linux and *BSD distributions.

int tds_read_packet TDSSOCKET *    tds
 

Read in one 'packet' from the server.

This is a wrapped outer packet of the protocol (they bundle result packets into chunks and wrap them at what appears to be 512 bytes regardless of how that breaks internal packet up. (tetherow@nol.org)

Returns:
bytes read or -1 on failure

int tds_send_cancel TDSSOCKET *    tds
 

tds_send_cancel() sends an empty packet (8 byte header only) tds_process_cancel should be called directly after this.

Parameters:
tds  state information for the socket and the TDS protocol

void tds_set_column_type TDSCOLINFO   curcol,
int    type
 

Set type of column initializing all dependency.

Parameters:
curcol  column to set
type  type to set

int tds_set_interfaces_file_loc const char *    interf
 

Set the full name of interface file.

Parameters:
interf  file name

void tds_set_param_type TDSSOCKET *    tds,
TDSCOLINFO   curcol,
TDS_SERVER_TYPE    type
 

Set type of column initializing all dependency.

Parameters:
curcol  column to set
type  type to set

const char* tds_skip_quoted const char *    s
 

Skip quoting string (like 'sfsf', "dflkdj" or [dfkjd]).

Parameters:
s  pointer to first quoting character (should be '," or [)
Returns:
character after quoting

int tds_submit_execdirect TDSSOCKET *    tds,
const char *    query,
TDSPARAMINFO *    params
 

Currently works with TDS 5.0 and TDS7+.

Parameters:
tds  state information for the socket and the TDS protocol
query  language query with given placeholders (?)
params  parameters to send
Returns:
TDS_FAIL or TDS_SUCCEED

int tds_submit_execute TDSSOCKET *    tds,
TDSDYNAMIC *    dyn
 

tds_submit_execute() sends a previously prepared dynamic statement to the server.

Currently works with TDS 5.0 or TDS7+

Parameters:
tds  state information for the socket and the TDS protocol
dyn  dynamic proc to execute. Must build from same tds.

int tds_submit_prepare TDSSOCKET *    tds,
const char *    query,
const char *    id,
TDSDYNAMIC **    dyn_out,
TDSPARAMINFO *    params
 

tds_submit_prepare() creates a temporary stored procedure in the server.

Under TDS 4.2 dynamic statements are emulated building sql command

Parameters:
tds  state information for the socket and the TDS protocol
query  language query with given placeholders (?)
id  string to identify the dynamic query. Pass NULL for automatic generation.
dyn_out  will receive allocated TDSDYNAMIC*. Any older allocated dynamic won't be freed, Can be NULL.
Returns:
TDS_FAIL or TDS_SUCCEED

int tds_submit_query TDSSOCKET *    tds,
const char *    query
 

tds_submit_query() sends a language string to the database server for processing.

TDS 4.2 is a plain text message with a packet type of 0x01, TDS 7.0 is a unicode string with packet type 0x01, and TDS 5.0 uses a TDS_LANGUAGE_TOKEN to encapsulate the query and a packet type of 0x0f.

Parameters:
tds  state information for the socket and the TDS protocol
query  language query to submit
Returns:
TDS_FAIL or TDS_SUCCEED

int tds_submit_query_params TDSSOCKET *    tds,
const char *    query,
TDSPARAMINFO *    params
 

tds_submit_query_params() sends a language string to the database server for processing.

TDS 4.2 is a plain text message with a packet type of 0x01, TDS 7.0 is a unicode string with packet type 0x01, and TDS 5.0 uses a TDS_LANGUAGE_TOKEN to encapsulate the query and a packet type of 0x0f.

Parameters:
tds  state information for the socket and the TDS protocol
query  language query to submit
params  parameters of query
Returns:
TDS_FAIL or TDS_SUCCEED

int tds_submit_rpc TDSSOCKET *    tds,
const char *    rpc_name,
TDSPARAMINFO *    params
 

tds_submit_rpc() call a RPC from server.

Output parameters will be stored in tds->param_info

Parameters:
tds  state information for the socket and the TDS protocol
rpc_name  name of RPC
params  parameters informations. NULL for no parameters

int tds_submit_unprepare TDSSOCKET *    tds,
TDSDYNAMIC *    dyn
 

Send a unprepare request for a prepared query.

Parameters:
tds  state information for the socket and the TDS protocol
dyn  dynamic query
Returns:
TDS_SUCCEED or TDS_FAIL

int tds_version TDSSOCKET *    tds_socket,
char *    pversion_string
 

Returns the version of the TDS protocol in effect for the link as a decimal integer.

Typical returned values are 42, 50, 70, 80. Also fills pversion_string unless it is null. Typical pversion_string values are "4.2" and "7.0".

void tdsdump_on void   
 

Turn logging back on.

You must call tdsdump_open() before calling this routine.

int tdsdump_open const char *    filename
 

This creates and truncates a human readable dump file for the TDS traffic.

The name of the file is specified by the filename parameter. If that is given as NULL or an empty string, any existing log file will be closed.

Returns:
true if the file was opened, false if it couldn't be opened.


Generated on Tue Jan 13 20:54:53 2004 for FreeTDS API by doxygen1.2.18