24 #define TDS_DONT_DEFINE_DEFAULT_FUNCTIONS    26 #include <freetds/thread.h>    27 #include <freetds/data.h>    29 #if defined(UNIXODBC) || defined(_WIN32) || defined(TDS_NO_DM)    32 #if defined(UNIXODBC) || defined(_WIN32)    38 #ifdef HAVE_IODBCINST_H    39 #include <iodbcinst.h>    49 #define SQLULEN SQLUINTEGER    52 #define SQLLEN SQLINTEGER    56 #ifndef HAVE_SQLSETPOSIROW    57 #define SQLSETPOSIROW SQLUSMALLINT    60 #ifndef HAVE_SQLROWOFFSET    61 #define SQLROWOFFSET SQLLEN    64 #ifndef HAVE_SQLROWSETSIZE    65 #define SQLROWSETSIZE SQLULEN    76 #include <freetds/pushvis.h>    77 #if defined(__GNUC__) && __GNUC__ >= 4 && !defined(__MINGW32__)    78 #define ODBC_API SQL_API __attribute__((externally_visible))    80 #define ODBC_API SQL_API    83 #if (defined(_WIN32) || defined(__CYGWIN__)) && defined(__GNUC__)    84 #  define ODBC_PUBLIC __attribute__((dllexport))    89 #define ODBC_MAX(a,b) ( (a) > (b) ? (a) : (b) )    90 #define ODBC_MIN(a,b) ( (a) < (b) ? (a) : (b) )   114 #if ENABLE_EXTRA_CHECKS   115 void odbc_check_struct_extra(
void *p);
   117 static inline void odbc_check_struct_extra(
void *p) {}
   120 #define ODBC_RETURN(handle, rc) \   121     do { odbc_check_struct_extra(handle); \   122     return handle->errs.lastrc = (rc); } while(0)   123 #define ODBC_RETURN_(handle) \   124     do { odbc_check_struct_extra(handle); \   125     return handle->errs.lastrc; } while(0)   127 #define ODBC_EXIT(handle, rc) \   128     do { SQLRETURN _odbc_rc = handle->errs.lastrc = (rc); \   129     odbc_check_struct_extra(handle); \   130     tds_mutex_unlock(&handle->mtx); \   131     return _odbc_rc; } while(0)   132 #define ODBC_EXIT_(handle) \   133     do { SQLRETURN _odbc_rc = handle->errs.lastrc; \   134     odbc_check_struct_extra(handle); \   135     tds_mutex_unlock(&handle->mtx); \   136     return _odbc_rc; } while(0)   143 void odbc_errs_add(
struct _sql_errors *errs, 
const char *sqlstate, 
const char *msg);
   146 void odbc_errs_add_rdbms(
struct _sql_errors *errs, TDS_UINT native, 
const char *sqlstate, 
const char *msg, 
int linenum,
   147              int msgstate, 
const char *server, 
int row);
   151     SQLSMALLINT sql_desc_alloc_type;
   152     SQLINTEGER sql_desc_bind_type;
   153     SQLULEN sql_desc_array_size;
   155     SQLSMALLINT sql_desc_count;
   156     SQLUSMALLINT *sql_desc_array_status_ptr;
   157     SQLULEN *sql_desc_rows_processed_ptr;
   158     SQLLEN *sql_desc_bind_offset_ptr;
   163     SQLUINTEGER sql_desc_auto_unique_value;
   164     DSTR sql_desc_base_column_name;
   165     DSTR sql_desc_base_table_name;
   166     SQLINTEGER sql_desc_case_sensitive;
   167     DSTR sql_desc_catalog_name;
   168     SQLSMALLINT sql_desc_concise_type;
   169     SQLPOINTER sql_desc_data_ptr;
   170     SQLSMALLINT sql_desc_datetime_interval_code;
   171     SQLINTEGER sql_desc_datetime_interval_precision;
   172     SQLLEN sql_desc_display_size;
   173     SQLSMALLINT sql_desc_fixed_prec_scale;
   174     SQLLEN *sql_desc_indicator_ptr;
   176     SQLULEN sql_desc_length;
   178     const char *sql_desc_literal_prefix;
   180     const char *sql_desc_literal_suffix;
   181     DSTR sql_desc_local_type_name;
   183     SQLSMALLINT sql_desc_nullable;
   184     SQLINTEGER sql_desc_num_prec_radix;
   185     SQLLEN sql_desc_octet_length;
   186     SQLLEN *sql_desc_octet_length_ptr;
   187     SQLSMALLINT sql_desc_parameter_type;
   188     SQLSMALLINT sql_desc_precision;
   189     SQLSMALLINT sql_desc_rowver;
   190     SQLSMALLINT sql_desc_scale;
   191     DSTR sql_desc_schema_name;
   192     SQLSMALLINT sql_desc_searchable;
   193     DSTR sql_desc_table_name;
   194     SQLSMALLINT sql_desc_type;
   196     const char *sql_desc_type_name;
   197     SQLSMALLINT sql_desc_unnamed;
   198     SQLSMALLINT sql_desc_unsigned;
   199     SQLSMALLINT sql_desc_updatable;
   213 typedef struct _hdesc TDS_DESC;
   222     SQLUINTEGER connection_pooling;
   223     SQLUINTEGER cp_match;
   224     SQLINTEGER odbc_version;
   225     SQLINTEGER output_nts;
   246     SQLUINTEGER access_mode;
   247     SQLUINTEGER async_enable;
   248     SQLUINTEGER auto_ipd;
   249     SQLUINTEGER autocommit;
   250     SQLUINTEGER connection_dead;
   251     SQLUINTEGER connection_timeout;
   252     DSTR current_catalog;
   253     SQLUINTEGER login_timeout;
   254     SQLUINTEGER metadata_id;
   255     SQLUINTEGER odbc_cursors;
   256     SQLUINTEGER packet_size;
   259     SQLUINTEGER translate_option;
   260     SQLUINTEGER txn_isolation;
   261     SQLUINTEGER mars_enabled;
   262     SQLUINTEGER cursor_type;
   263     SQLUINTEGER bulk_enabled;
   270 #define TDS_MAX_APP_DESC    100   282 #ifdef ENABLE_ODBC_WIDE   283     DSTR original_charset;
   297     TDS_DESC *uad[TDS_MAX_APP_DESC];
   299     unsigned int cursor_support:1;
   300     unsigned int use_oldpwd:1;
   301     TDS_INT default_query_timeout;
   312     SQLUINTEGER async_enable;
   313     SQLUINTEGER concurrency;
   314     SQLUINTEGER cursor_scrollable;
   315     SQLUINTEGER cursor_sensitivity;
   316     SQLUINTEGER cursor_type;
   317     SQLUINTEGER enable_auto_ipd;
   318     SQLPOINTER fetch_bookmark_ptr;
   322     SQLUINTEGER metadata_id;
   336     SQLUINTEGER query_timeout;
   337     SQLUINTEGER retrieve_data;
   351     SQLUINTEGER simulate_cursor;
   352     SQLUINTEGER use_bookmarks;
   358     SQLUINTEGER qn_timeout;
   368 } TDS_ODBC_ROW_STATUS;
   372     ODBC_SPECIAL_NONE = 0,
   373     ODBC_SPECIAL_GETTYPEINFO = 1,
   374     ODBC_SPECIAL_COLUMNS = 2,
   375     ODBC_SPECIAL_PROCEDURECOLUMNS = 3,
   376     ODBC_SPECIAL_SPECIALCOLUMNS = 4
   377 } TDS_ODBC_SPECIAL_ROWS;
   396     unsigned is_prepared_query:1;
   397     unsigned prepared_query_is_func:1;
   398     unsigned prepared_query_is_rpc:1;
   404     unsigned param_data_called:1;
   414     unsigned int curr_param_row, num_param_rows;
   425     TDS_DESC *ard, *ird, *apd, *ipd;
   426     TDS_DESC *orig_ard, *orig_apd;
   427     SQLULEN sql_rowset_size;
   430     TDS_ODBC_SPECIAL_ROWS special_row;
   443     void (*set_type_info)(
TDSCOLUMN *col, 
struct _drecord *drec, SQLINTEGER odbc_ver);
   446 #define IS_HENV(x) (((TDS_CHK *)x)->htype == SQL_HANDLE_ENV)   447 #define IS_HDBC(x) (((TDS_CHK *)x)->htype == SQL_HANDLE_DBC)   448 #define IS_HSTMT(x) (((TDS_CHK *)x)->htype == SQL_HANDLE_STMT)   449 #define IS_HDESC(x) (((TDS_CHK *)x)->htype == SQL_HANDLE_DESC)   453 #if SQL_INTERVAL_YEAR == (100 + SQL_CODE_SECOND)   455 #undef SQL_INTERVAL_YEAR   456 #undef SQL_INTERVAL_MONTH   457 #undef SQL_INTERVAL_DAY   458 #undef SQL_INTERVAL_HOUR   459 #undef SQL_INTERVAL_MINUTE   460 #undef SQL_INTERVAL_SECOND   461 #undef SQL_INTERVAL_YEAR_TO_MONTH   462 #undef SQL_INTERVAL_DAY_TO_HOUR   463 #undef SQL_INTERVAL_DAY_TO_MINUTE   464 #undef SQL_INTERVAL_DAY_TO_SECOND   465 #undef SQL_INTERVAL_HOUR_TO_MINUTE   466 #undef SQL_INTERVAL_HOUR_TO_SECOND   467 #undef SQL_INTERVAL_MINUTE_TO_SECOND   469 #define SQL_INTERVAL_YEAR                   (100 + SQL_CODE_YEAR)   470 #define SQL_INTERVAL_MONTH                  (100 + SQL_CODE_MONTH)   471 #define SQL_INTERVAL_DAY                    (100 + SQL_CODE_DAY)   472 #define SQL_INTERVAL_HOUR                   (100 + SQL_CODE_HOUR)   473 #define SQL_INTERVAL_MINUTE                 (100 + SQL_CODE_MINUTE)   474 #define SQL_INTERVAL_SECOND                 (100 + SQL_CODE_SECOND)   475 #define SQL_INTERVAL_YEAR_TO_MONTH          (100 + SQL_CODE_YEAR_TO_MONTH)   476 #define SQL_INTERVAL_DAY_TO_HOUR            (100 + SQL_CODE_DAY_TO_HOUR)   477 #define SQL_INTERVAL_DAY_TO_MINUTE          (100 + SQL_CODE_DAY_TO_MINUTE)   478 #define SQL_INTERVAL_DAY_TO_SECOND          (100 + SQL_CODE_DAY_TO_SECOND)   479 #define SQL_INTERVAL_HOUR_TO_MINUTE         (100 + SQL_CODE_HOUR_TO_MINUTE)   480 #define SQL_INTERVAL_HOUR_TO_SECOND         (100 + SQL_CODE_HOUR_TO_SECOND)   481 #define SQL_INTERVAL_MINUTE_TO_SECOND       (100 + SQL_CODE_MINUTE_TO_SECOND)   487 bool get_login_info(HWND hwndParent, 
TDSLOGIN * login);
   490 #define ODBC_PARAM_LIST \   491     ODBC_PARAM(Servername) \   496     ODBC_PARAM(Address) \   498     ODBC_PARAM(TDS_Version) \   499     ODBC_PARAM(Language) \   500     ODBC_PARAM(Database) \   501     ODBC_PARAM(TextSize) \   502     ODBC_PARAM(PacketSize) \   503     ODBC_PARAM(ClientCharset) \   504     ODBC_PARAM(DumpFile) \   505     ODBC_PARAM(DumpFileAppend) \   506     ODBC_PARAM(DebugFlags) \   507     ODBC_PARAM(Encryption) \   508     ODBC_PARAM(Trusted_Connection) \   511     ODBC_PARAM(UseNTLMv2) \   512     ODBC_PARAM(MARS_Connection) \   514     ODBC_PARAM(ServerSPN) \   515     ODBC_PARAM(AttachDbFilename) \   516     ODBC_PARAM(ApplicationIntent)   518 #define ODBC_PARAM(p) ODBC_PARAM_##p,   542 int odbc_parse_connect_string(TDS_ERRS *errs, 
const char *connect_string, 
const char *connect_string_end, 
TDSLOGIN * login, 
TDS_PARSED_PARAM *parsed_params);
   543 int odbc_get_dsn_info(TDS_ERRS *errs, 
const char *DSN, 
TDSLOGIN * login);
   545 int odbc_build_connect_string(TDS_ERRS *errs, 
TDS_PARSED_PARAM *params, 
char **out);
   551 SQLLEN odbc_tds2sql_col(
TDS_STMT * stmt, 
TDSCOLUMN *curcol, 
int desttype, TDS_CHAR * dest, SQLULEN destlen, 
const struct _drecord *drec_ixd);
   552 SQLLEN odbc_tds2sql_int4(
TDS_STMT * stmt, TDS_INT *src, 
int desttype, TDS_CHAR * dest, SQLULEN destlen);
   559 TDS_DESC *desc_alloc(SQLHANDLE parent, 
int desc_type, 
int alloc_type);
   560 SQLRETURN desc_free(TDS_DESC * desc);
   561 SQLRETURN desc_alloc_records(TDS_DESC * desc, 
unsigned count);
   562 SQLRETURN desc_copy(TDS_DESC * dest, TDS_DESC * src);
   563 SQLRETURN desc_free_records(TDS_DESC * desc);
   564 TDS_DBC *desc_get_dbc(TDS_DESC *desc);
   569 SQLRETURN _SQLRowCount(SQLHSTMT hstmt, SQLLEN FAR * pcrow);
   574 #if ENABLE_EXTRA_CHECKS   576 #define CHECK_ENV_EXTRA(env) odbc_check_env_extra(env)   577 #define CHECK_DBC_EXTRA(dbc) odbc_check_dbc_extra(dbc)   578 #define CHECK_STMT_EXTRA(stmt) odbc_check_stmt_extra(stmt)   579 #define CHECK_DESC_EXTRA(desc) odbc_check_desc_extra(desc)   581 void odbc_check_env_extra(
TDS_ENV * env);
   582 void odbc_check_dbc_extra(
TDS_DBC * dbc);
   583 void odbc_check_stmt_extra(
TDS_STMT * stmt);
   584 void odbc_check_desc_extra(TDS_DESC * desc);
   587 #define CHECK_ENV_EXTRA(env)   588 #define CHECK_DBC_EXTRA(dbc)   589 #define CHECK_STMT_EXTRA(stmt)   590 #define CHECK_DESC_EXTRA(desc)   600 #ifdef ENABLE_ODBC_WIDE   607 # define _WIDE ,int wide   612 # define ODBC_CHAR SQLCHAR   614 int odbc_set_stmt_query(
struct _hstmt *stmt, 
const ODBC_CHAR *sql, 
int sql_len _WIDE);
   615 void odbc_set_return_status(
struct _hstmt *stmt, 
unsigned int n_row);
   616 void odbc_set_return_params(
struct _hstmt *stmt, 
unsigned int n_row);
   618 void odbc_set_sql_type_info(
TDSCOLUMN * col, 
struct _drecord *drec, SQLINTEGER odbc_ver);
   620 int odbc_sql_to_c_type_default(
int sql_type);
   621 TDS_SERVER_TYPE odbc_sql_to_server_type(
TDSCONNECTION * conn, 
int sql_type, 
int sql_unsigned);
   624 unsigned int odbc_get_string_size(
int size, 
const ODBC_CHAR * str _WIDE);
   628 #ifdef ENABLE_ODBC_WIDE   629 DSTR* odbc_dstr_copy_flag(
TDS_DBC *dbc, 
DSTR *s, 
int size, 
const ODBC_CHAR * str, 
int flag);
   630 #define odbc_dstr_copy(dbc, s, len, out) \   631     odbc_dstr_copy_flag(dbc, s, len, sizeof((out)->mb) ? (out) : (out), wide)   632 #define odbc_dstr_copy_oct(dbc, s, len, out) \   633     odbc_dstr_copy_flag(dbc, s, len, out, wide|0x20)   635 DSTR* odbc_dstr_copy(
TDS_DBC *dbc, 
DSTR *s, 
int size, 
const ODBC_CHAR * str);
   636 #define odbc_dstr_copy_oct odbc_dstr_copy   640 SQLRETURN 
odbc_set_string_flag(
TDS_DBC *dbc, SQLPOINTER buffer, SQLINTEGER cbBuffer, 
void FAR * pcbBuffer, 
const char *s, 
int len, 
int flag);
   641 #ifdef ENABLE_ODBC_WIDE   642 #define odbc_set_string(dbc, buf, buf_len, out_len, s, s_len) \   643     odbc_set_string_flag(dbc, sizeof((buf)->mb) ? (buf) : (buf), buf_len, out_len, s, s_len, (wide) | (sizeof(*(out_len)) == sizeof(SQLSMALLINT)?0:0x10))   644 #define odbc_set_string_oct(dbc, buf, buf_len, out_len, s, s_len) \   645     odbc_set_string_flag(dbc, buf, buf_len, out_len, s, s_len, (wide) | (sizeof(*(out_len)) == sizeof(SQLSMALLINT)?0x20:0x30))   647 #define odbc_set_string(dbc, buf, buf_len, out_len, s, s_len) \   648     odbc_set_string_flag(dbc, buf, buf_len, out_len, s, s_len, (sizeof(*(out_len)) == sizeof(SQLSMALLINT)?0:0x10))   649 #define odbc_set_string_oct(dbc, buf, buf_len, out_len, s, s_len) \   650     odbc_set_string_flag(dbc, buf, buf_len, out_len, s, s_len, (sizeof(*(out_len)) == sizeof(SQLSMALLINT)?0x20:0x30))   653 #define odbc_set_dstr_oct(dbc, buf, buf_len, out_len, s) odbc_set_string_oct(dbc, buf, buf_len, out_len, tds_dstr_cstr(s), tds_dstr_len(s))   654 #define odbc_set_dstr(dbc, buf, buf_len, out_len, s) odbc_set_string(dbc, buf, buf_len, out_len, tds_dstr_cstr(s), tds_dstr_len(s))   656 SQLSMALLINT odbc_get_concise_sql_type(SQLSMALLINT type, SQLSMALLINT interval);
   658 SQLSMALLINT odbc_get_concise_c_type(SQLSMALLINT type, SQLSMALLINT interval);
   661 SQLLEN odbc_get_octet_len(
int c_type, 
const struct _drecord *drec);
   662 void odbc_convert_err_set(
struct _sql_errors *errs, TDS_INT err);
   667 SQLRETURN prepare_call(
struct _hstmt *stmt);
   668 SQLRETURN native_sql(
struct _hdbc *dbc, 
DSTR *s);
   669 int parse_prepared_query(
struct _hstmt *stmt, 
bool compute_row);
   670 int start_parse_prepared_query(
struct _hstmt *stmt, 
bool compute_row);
   671 int continue_parse_prepared_query(
struct _hstmt *stmt, SQLPOINTER DataPtr, SQLLEN StrLen_or_Ind);
   672 const char *parse_const_param(
const char * s, TDS_SERVER_TYPE *type);
   673 const char *odbc_skip_rpc_name(
const char *s);
   678 SQLRETURN odbc_sql2tds(
TDS_STMT * stmt, 
const struct _drecord *drec_ixd, 
const struct _drecord *drec_axd, 
TDSCOLUMN *curcol, 
bool compute_row, 
const TDS_DESC* axd, 
unsigned int n_row);
   679 TDS_INT convert_datetime2server(
int bindtype, 
const void *src, 
TDS_DATETIMEALL * dta);
   684 void odbc_bcp_free_storage(
TDS_DBC *dbc);
   685 void odbc_bcp_init(
TDS_DBC *dbc, 
const ODBC_CHAR *tblname, 
const ODBC_CHAR *hfile, 
const ODBC_CHAR *errfile, 
int direction _WIDE);
   686 void odbc_bcp_control(
TDS_DBC *dbc, 
int field, 
void *value);
   687 void odbc_bcp_colptr(
TDS_DBC *dbc, 
const void * colptr, 
int table_column);
   688 void odbc_bcp_sendrow(
TDS_DBC *dbc);
   689 int odbc_bcp_batch(
TDS_DBC *dbc);
   690 int odbc_bcp_done(
TDS_DBC *dbc);
   691 void odbc_bcp_bind(
TDS_DBC *dbc, 
const void * varaddr, 
int prefixlen, 
int varlen, 
const void * terminator, 
int termlen, 
int vartype, 
int table_column);
   696 #if SIZEOF_SQLWCHAR != SIZEOF_WCHAR_T   697 size_t sqlwcslen(
const SQLWCHAR * s);
   699 typedef struct sqlwstr_buf {
   700     struct sqlwstr_buf *next;
   703 const wchar_t *sqlwstr(
const SQLWCHAR * s, SQLWSTRBUF **bufs);
   704 void sqlwstr_free(SQLWSTRBUF *bufs);
   705 #define SQLWSTR_BUFS(n) SQLWSTRBUF *bufs = NULL   706 #define SQLWSTR(s) sqlwstr(s, &bufs)   707 #define SQLWSTR_FREE() sqlwstr_free(bufs)   709 #define sqlwcslen(s) wcslen(s)   711 #define SQLWSTR_BUFS(n) do {} while(0)   712 #define SQLWSTR(s) ((const wchar_t*)(s))   713 #define SQLWSTR_FREE() do {} while(0)   716 #if SIZEOF_SQLWCHAR == 2   718 #  define ODBC_WIDE_NAME "UCS-2BE"   719 #  define ODBC_WIDE_NAME_UTF "UTF-16BE"   721 #  define ODBC_WIDE_NAME "UCS-2LE"   722 #  define ODBC_WIDE_NAME_UTF "UTF-16LE"   725 #elif SIZEOF_SQLWCHAR == 4   727 #  define ODBC_WIDE_NAME "UCS-4BE"   729 #  define ODBC_WIDE_NAME "UCS-4LE"   731 static inline const char *
   734     return ODBC_WIDE_NAME;
   737 #error SIZEOF_SQLWCHAR not supported !!   740 #include <freetds/popvis.h> void odbc_rdbms_version(TDSSOCKET *tds_socket, char *pversion_string)
Returns the version of the RDBMS in the ODBC format. 
Definition: odbc_util.c:847
Information for a server connection. 
Definition: tds.h:1141
struct _hstmt * current_statement
Statement executing. 
Definition: odbc.h:292
TDSPARAMINFO * params
parameters saved 
Definition: odbc.h:408
char * prepared_pos
position in prepared query to check parameters, used only in RPC 
Definition: odbc.h:412
DSTR query
query to execute 
Definition: odbc.h:386
Structure to hold a string. 
Definition: string.h:36
Metadata about columns in regular and compute rows. 
Definition: tds.h:690
struct _hstmt * stmt_list
list of all statements allocated from this connection 
Definition: odbc.h:294
SQLRETURN odbc_set_concise_sql_type(SQLSMALLINT concise_type, struct _drecord *drec, int check_only)
Set concise type and all cascading field. 
Definition: odbc_util.c:971
Hold information for any results. 
Definition: tds.h:769
TDSSOCKET * tds
socket (only if active) 
Definition: odbc.h:388
SQLINTEGER odbc_get_param_len(const struct _drecord *drec_axd, const struct _drecord *drec_ixd, const TDS_DESC *axd, unsigned int n_row)
Return length of parameter from parameter information. 
Definition: odbc_util.c:856
unsigned need_reprepare
Prepared statement needs to be prepared again. 
Definition: odbc.h:403
SQLRETURN odbc_set_string_flag(TDS_DBC *dbc, SQLPOINTER buffer, SQLINTEGER cbBuffer, void FAR *pcbBuffer, const char *s, int len, int flag)
Copy a string to client setting size according to ODBC convenction. 
Definition: odbc_util.c:279
SQLRETURN odbc_set_concise_c_type(SQLSMALLINT concise_type, struct _drecord *drec, int check_only)
Set concise type and all cascading field. 
Definition: odbc_util.c:1093
TDS_INT8 row_count
row count to return 
Definition: odbc.h:420
struct _hstmt * next
next in list 
Definition: odbc.h:391
unsigned int param_count
number of parameter in current query 
Definition: odbc.h:417
struct _hstmt * prev
previous in list 
Definition: odbc.h:393
TDS_SERVER_TYPE odbc_c_to_server_type(int c_type)
Pass this an SQL_C_* type and get a SYB* type which most closely corresponds to the SQL_C_* type...
Definition: odbc_util.c:596
Holds informations about a cursor. 
Definition: tds.h:937
int param_num
last valid parameter in params, it's a ODBC index (from 1 relative to descriptor) ...
Definition: odbc.h:410
TDS_ODBC_ROW_STATUS row_status
status of row, it can happen that this flag mark that we are still parsing row, this it's normal ...
Definition: odbc.h:422
Main include file for libtds. 
this structure is not directed connected to a TDS protocol but keeps any DATE/TIME information...
Definition: tds.h:144
Holds information for a dynamic (also called prepared) query. 
Definition: tds.h:977