FreeTDS API: Results processing

FreeTDS API

Classes | Functions
Results processing
LibTDS API

Handle tokens in packets. More...

Collaboration diagram for Results processing:

## Classes
struct | namelist
| Holds list of names. More...

## Functions
static void | adjust_character_column_size (TDSSOCKET *tds, TDSCOLUMN *curcol)
| Adjust column size according to client's encoding. More...
static int | determine_adjusted_size (const TDSICONV *char_conv, int size)
| Allow for maximum possible size of converted data, while being careful about integer division truncation. More...
static TDSRET | tds5_process_dyn_result2 (TDSSOCKET *tds)
| Process new TDS 5.0 token for describing output parameters. More...
static TDSRET | tds5_process_optioncmd (TDSSOCKET *tds)
| Process option cmd results. More...
static TDSRET | tds5_process_result (TDSSOCKET *tds)
| tds5_process_result() is the TDS 5.0 result set processing routine. More...
static TDSRET | tds5_process_result2 (TDSSOCKET *tds)
| tds5_process_result2() is the new TDS 5.0 result set processing routine. More...
static int | tds71_read_table_names (TDSSOCKET *tds, int remainder, struct namelist **p_head)
| Reads table names for TDS 7.1+. More...
static TDSRET | tds7_get_data_info (TDSSOCKET *tds, TDSCOLUMN *curcol)
| Reads data information from wire. More...
static TDSRET | tds7_process_compute_result (TDSSOCKET *tds)
| tds7_process_compute_result() processes compute result sets for TDS 7/8. More...
static TDSRET | tds7_process_result (TDSSOCKET *tds)
| tds7_process_result() is the TDS 7.0 result set processing routine. More...
static int | tds_alloc_get_string (TDSSOCKET *tds, char **string, size_t len)
| Reads a string from wire in a new allocated buffer. More...
static void | tds_free_namelist (struct namelist *head)
| Frees list of names. More...
static TDSRET | tds_get_data_info (TDSSOCKET *tds, TDSCOLUMN *curcol, int is_param)
| Reads data metadata from wire. More...
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 More...
TDSDYNAMIC * | tds_lookup_dynamic (TDSCONNECTION *conn, const char *id)
| Finds a dynamic given string id. More...
static const char * | tds_pr_op (int op)
| Returns string representation for a given operation. More...
static TDSRET | tds_process_auth (TDSSOCKET *tds)
| Process authentication token. More...
TDSRET | tds_process_cancel (TDSSOCKET *tds)
static TDSRET | tds_process_col_fmt (TDSSOCKET *tds)
| tds_process_col_fmt() is the other half of result set processing under TDS 4.2. More...
static TDSRET | tds_process_col_name (TDSSOCKET *tds)
| tds_process_col_name() is one half of the result set under TDS 4.2 it contains all the column names, a TDS_COLFMT_TOKEN should immediately follow this token with the datatype/size information This is a 4.2 only function More...
static TDSRET | tds_process_colinfo (TDSSOCKET *tds, char **names, int num_names)
| Reads column information. More...
static TDSRET | tds_process_compute (TDSSOCKET *tds)
| tds_process_compute() processes compute rows and places them in the row buffer. More...
static TDSRET | tds_process_compute_names (TDSSOCKET *tds)
| tds_process_compute_names() processes compute result sets. More...
static TDSRET | tds_process_compute_result (TDSSOCKET *tds)
| tds_process_compute_result() processes compute result sets. More...
static TDSRET | tds_process_cursor_tokens (TDSSOCKET *tds)
| Reads cursor command results. More...
static TDSRET | tds_process_default_tokens (TDSSOCKET *tds, int marker)
| tds_process_default_tokens() is a catch all function that is called to process tokens not known to other tds_process_* routines More...
static TDSRET | tds_process_dyn_result (TDSSOCKET *tds)
| Process results from dynamic. More...
static TDSDYNAMIC * | tds_process_dynamic (TDSSOCKET *tds)
| tds_process_dynamic() finds the element of the dyns array for the id More...
static TDSRET | tds_process_end (TDSSOCKET *tds, int marker, int *flags_parm)
| tds_process_end() processes any of the DONE, DONEPROC, or DONEINPROC tokens. More...
static TDSRET | tds_process_env_chg (TDSSOCKET *tds)
| tds_process_env_chg() when ever certain things change on the server, such as database, character set, language, or block size. More...
static TDSRET | tds_process_env_routing (TDSSOCKET *tds)
static TDSRET | tds_process_featureextack (TDSSOCKET *tds)
static TDSRET | tds_process_info (TDSSOCKET *tds, int marker)
| tds_process_info() is called for INFO, ERR, or EED tokens and is responsible for calling the CLI's message handling routine More...
TDSRET | tds_process_login_tokens (TDSSOCKET *tds)
| tds_process_login_tokens() is called after sending the login packet to the server. More...
static TDSRET | tds_process_loginack (TDSSOCKET *tds, TDSRET *login_succeeded)
static TDSRET | tds_process_nbcrow (TDSSOCKET *tds)
| tds_process_nbcrow() processes rows and places them in the row buffer.
static TDSRET | tds_process_param_result (TDSSOCKET *tds, TDSPARAMINFO **pinfo)
| process output parameters of a stored procedure. More...
static TDSRET | tds_process_param_result_tokens (TDSSOCKET *tds)
| Process parameters from networks. More...
static TDSRET | tds_process_params_result_token (TDSSOCKET *tds)
| tds_process_params_result_token() processes params on TDS5. More...
static void | tds_process_pending_closes (TDSSOCKET *tds)
| Attempt to close all deferred closes (dynamics and cursors). More...
static TDSRET | tds_process_row (TDSSOCKET *tds)
| tds_process_row() processes rows and places them in the row buffer. More...
TDSRET | 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. More...
static TDSRET | tds_process_tabname (TDSSOCKET *tds)
| Process list of table from network. More...
TDSRET | tds_process_tokens (TDSSOCKET *tds, TDS_INT *result_type, int *done_flags, unsigned flag)
| process all streams. More...
const char * | tds_prtype (int type)
| Returns string representation of the given type. More...
static int | tds_read_namelist (TDSSOCKET *tds, int remainder, struct namelist **p_head, int large)
| Reads list of names (usually table names) More...
static const char * | tds_token_name (unsigned char marker)
| Returns string representation for a given token type. More...

## Detailed Description

Handle tokens in packets.

Many PDU (packets data unit) contain tokens. (like result description, rows, data, errors and many other).

## Function Documentation

## ◆ adjust_character_column_size()

static void adjust_character_column_size | ( | TDSSOCKET * | tds,
|  | TDSCOLUMN * | curcol
| ) |  |
| static

Adjust column size according to client's encoding.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  curcol | column to adjust

## ◆ determine_adjusted_size()

static int determine_adjusted_size | ( | const TDSICONV * | char_conv,
|  | int | size
| ) |  |
| static

Allow for maximum possible size of converted data, while being careful about integer division truncation.

All character data pass through iconv. It doesn't matter if the server side is Unicode or not; even Latin1 text need conversion if, for example, the client is UTF-8.

Parameters

  char_conv | conversion structure
  size | unconverted byte size

Returns
  maximum size for converted string

## ◆ tds5_process_dyn_result2()

static TDSRET tds5_process_dyn_result2 | ( | TDSSOCKET * | tds | ) |
| static

Process new TDS 5.0 token for describing output parameters.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds5_process_optioncmd()

static TDSRET tds5_process_optioncmd | ( | TDSSOCKET * | tds | ) |
| static

Process option cmd results.

This token is available only on TDS 5.0 (Sybase).

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds5_process_result()

static TDSRET tds5_process_result | ( | TDSSOCKET * | tds | ) |
| static

tds5_process_result() is the TDS 5.0 result set processing routine.

It is responsible for populating the tds->res_info structure. This is a TDS 5.0 only function

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds5_process_result2()

static TDSRET tds5_process_result2 | ( | TDSSOCKET * | tds | ) |
| static

tds5_process_result2() is the new TDS 5.0 result set processing routine.

It is responsible for populating the tds->res_info structure. This is a TDS 5.0 only function

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds71_read_table_names()

static int tds71_read_table_names | ( | TDSSOCKET * | tds,
|  | int | remainder,
|  | struct namelist ** | p_head
| ) |  |
| static

Reads table names for TDS 7.1+.

TDS 7.1+ return table names as an array of names (so database.schema.owner.name as separate names)

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  remainder | bytes left to read
  p_head | pointer to list head to return

Returns
  number of element returned or -1 on error

## ◆ tds7_get_data_info()

static TDSRET tds7_get_data_info | ( | TDSSOCKET * | tds,
|  | TDSCOLUMN * | curcol
| ) |  |
| static

Reads data information from wire.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  curcol | column where to store information

## ◆ tds7_process_compute_result()

static TDSRET tds7_process_compute_result | ( | TDSSOCKET * | tds | ) |
| static

tds7_process_compute_result() processes compute result sets for TDS 7/8.

They is are very similar to normal result sets.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds7_process_result()

static TDSRET tds7_process_result | ( | TDSSOCKET * | tds | ) |
| static

tds7_process_result() is the TDS 7.0 result set processing routine.

It is responsible for populating the tds->res_info structure. This is a TDS 7.0 only function

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_alloc_get_string()

static int tds_alloc_get_string | ( | TDSSOCKET * | tds,
|  | char ** | string,
|  | size_t | len
| ) |  |
| static

Reads a string from wire in a new allocated buffer.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  string | output string
  len | length of string to read

Returns
  0 for success, -1 on error.

## ◆ tds_free_namelist()

static void tds_free_namelist | ( | struct namelist * | head | ) |
| static

Frees list of names.

Parameters

  head | list head to free

## ◆ tds_get_data_info()

static TDSRET tds_get_data_info | ( | TDSSOCKET * | tds,
|  | TDSCOLUMN * | curcol,
|  | int | is_param
| ) |  |
| static

Reads data metadata from wire.

Parameters

  tds | state information for the socket and the TDS protocol
  curcol | column where to store information
  is_param | true if metadata are for a parameter (false for normal column)

Here is the call graph for this function:

## ◆ tds_get_token_size()

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

Parameters

  marker | token type.

## ◆ tds_lookup_dynamic()

TDSDYNAMIC* tds_lookup_dynamic | ( | TDSCONNECTION * | conn,
|  | const char * | id
| ) |  |

Finds a dynamic given string id.

Returns
  dynamic or NULL is not found

Parameters

  conn | state information for the socket and the TDS protocol
  id | dynamic id to search

Here is the caller graph for this function:

## ◆ tds_pr_op()

static const char * tds_pr_op | ( | int | op | ) |
| static

Returns string representation for a given operation.

Parameters

  op | operation code

Returns
  string representation. Empty if not found.

## ◆ tds_process_auth()

static TDSRET tds_process_auth | ( | TDSSOCKET * | tds | ) |
| static

Process authentication token.

This token is only TDS 7.0+.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_cancel()

TDSRET tds_process_cancel | ( | TDSSOCKET * | tds | ) |

Remarks
  Process the incoming token stream until it finds an end token (DONE, DONEPROC, DONEINPROC) with the cancel flag set. At that point the connection should be ready to handle a new query.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_col_fmt()

static TDSRET tds_process_col_fmt | ( | TDSSOCKET * | tds | ) |
| static

tds_process_col_fmt() is the other half of result set processing under TDS 4.2.

It follows tds_process_col_name(). It contains all the column type and size information. This is a 4.2 only function

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_col_name()

static TDSRET tds_process_col_name | ( | TDSSOCKET * | tds | ) |
| static

tds_process_col_name() is one half of the result set under TDS 4.2 it contains all the column names, a TDS_COLFMT_TOKEN should immediately follow this token with the datatype/size information This is a 4.2 only function

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_colinfo()

static TDSRET tds_process_colinfo | ( | TDSSOCKET * | tds,
|  | char ** | names,
|  | int | num_names
| ) |  |
| static

Reads column information.

This token is only TDS 4.2

Parameters

  | tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  [in] | names | table names
  [in] | num_names | number of table names

Here is the call graph for this function:

## ◆ tds_process_compute()

static TDSRET tds_process_compute | ( | TDSSOCKET * | tds | ) |
| static

tds_process_compute() processes compute rows and places them in the row buffer.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_compute_names()

static TDSRET tds_process_compute_names | ( | TDSSOCKET * | tds | ) |
| static

tds_process_compute_names() processes compute result sets.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_compute_result()

static TDSRET tds_process_compute_result | ( | TDSSOCKET * | tds | ) |
| static

tds_process_compute_result() processes compute result sets.

These functions need work but since they get little use, nobody has complained! It is very similar to normal result sets.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_cursor_tokens()

static TDSRET tds_process_cursor_tokens | ( | TDSSOCKET * | tds | ) |
| static

Reads cursor command results.

This contains status of cursors.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_default_tokens()

static TDSRET tds_process_default_tokens | ( | TDSSOCKET * | tds,
|  | int | marker
| ) |  |
| static

tds_process_default_tokens() is a catch all function that is called to process tokens not known to other tds_process_* routines

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  marker | Token type

Here is the call graph for this function:

## ◆ tds_process_dyn_result()

static TDSRET tds_process_dyn_result | ( | TDSSOCKET * | tds | ) |
| static

Process results from dynamic.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_dynamic()

static TDSDYNAMIC * tds_process_dynamic | ( | TDSSOCKET * | tds | ) |
| static

tds_process_dynamic() finds the element of the dyns array for the id

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Returns
  allocated dynamic or NULL on failure.

## ◆ tds_process_end()

static TDSRET tds_process_end | ( | TDSSOCKET * | tds,
|  | int | marker,
|  | int * | flags_parm
| ) |  |
| static

tds_process_end() processes any of the DONE, DONEPROC, or DONEINPROC tokens.

Parameters

  tds | state information for the socket and the TDS protocol
  marker | TDS token number
  flags_parm | filled with bit flags (see TDS_DONE_ constants). Is NULL nothing is returned

Here is the call graph for this function:

## ◆ tds_process_env_chg()

static TDSRET tds_process_env_chg | ( | TDSSOCKET * | tds | ) |
| static

tds_process_env_chg() when ever certain things change on the server, such as database, character set, language, or block size.

A environment change message is generated There is no action taken currently, but certain functions at the CLI level that return the name of the current database will need to use this.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_info()

static TDSRET tds_process_info | ( | TDSSOCKET * | tds,
|  | int | marker
| ) |  |
| static

tds_process_info() is called for INFO, ERR, or EED tokens and is responsible for calling the CLI's message handling routine

Returns
  TDS_SUCCESS if informational, TDS_FAIL if error.

## ◆ tds_process_login_tokens()

TDSRET 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

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_param_result()

static TDSRET tds_process_param_result | ( | TDSSOCKET * | tds,
|  | TDSPARAMINFO ** | pinfo
| ) |  |
| static

process output parameters of a stored procedure.

This differs from regular row/compute results in that there is no total number of parameters given, they just show up singly.

Parameters

  | tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  [out] | pinfo | output parameter. Should point to a not allocated structure

Here is the call graph for this function:

## ◆ tds_process_param_result_tokens()

static TDSRET tds_process_param_result_tokens | ( | TDSSOCKET * | tds | ) |
| static

Process parameters from networks.

Read all consecutives paramaters, not a single one. Parameters are then stored in tds->param_info or tds->cur_dyn->res_info depending if we are reading cursor results or normal parameters.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_params_result_token()

static TDSRET tds_process_params_result_token | ( | TDSSOCKET * | tds | ) |
| static

tds_process_params_result_token() processes params on TDS5.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_pending_closes()

static void tds_process_pending_closes | ( | TDSSOCKET * | tds | ) |
| static

Attempt to close all deferred closes (dynamics and cursors).

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_row()

static TDSRET tds_process_row | ( | TDSSOCKET * | tds | ) |
| static

tds_process_row() processes rows and places them in the row buffer.

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

## ◆ tds_process_simple_query()

TDSRET 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_tokens for results (TDS_NO_MORE_RESULTS is never returned)

## ◆ tds_process_tabname()

static TDSRET tds_process_tabname | ( | TDSSOCKET * | tds | ) |
| static

Process list of table from network.

This token is only TDS 4.2

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.

Here is the call graph for this function:

## ◆ tds_process_tokens()

TDSRET tds_process_tokens | ( | TDSSOCKET * | tds,
|  | TDS_INT * | result_type,
|  | int * | done_flags,
|  | unsigned | flag
| ) |  |

process all streams.

tds_process_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_tokens sets to indicate the current type of result.

  Values that indicate command status

  TDS_DONE_RESULT | The results of a command have been completely processed. This command returned no rows.
  TDS_DONEPROC_RESULT | The results of a command have been completely processed. This command returned rows.
  TDS_DONEINPROC_RESULT | The results of a command have been completely processed. This command returned rows.

  Values that indicate results information is available

  TDS_ROWFMT_RESULT | Regular Data format information | tds->res_info now contains the result details ; tds->current_results now points to that data
  TDS_COMPUTEFMT_ RESULT | Compute data format information | tds->comp_info now contains the result data; tds->current_results now points to that data
  TDS_DESCRIBE_RESULT |  |

  Values that indicate data is available

  Value | Meaning | Information returned
  TDS_ROW_RESULT | Regular row results | 1 or more rows of regular data can now be retrieved
  TDS_COMPUTE_RESULT | Compute row results | A single row of compute data can now be retrieved
  TDS_PARAM_RESULT | Return parameter results | param_info or cur_dyn->params contain returned parameters
  TDS_STATUS_RESULT | Stored procedure status results | tds->ret_status contain the returned code

Parameters

  done_flags | Flags contained in the TDS_DONE*_TOKEN readed
  flag | Flags to select token type to stop/return

Todo:
  Complete TDS_DESCRIBE_RESULT description

Return values

  TDS_SUCCESS | if a result set is available for processing.
  TDS_FAIL | on error.
  TDS_NO_MORE_RESULTS | if all results have been completely processed.
  anything | returned by one of the many functions it calls. :-(

Here is the call graph for this function:

## ◆ tds_prtype()

const char* tds_prtype | ( | int | type | ) |

Returns string representation of the given type.

Parameters

  type | data type

Returns
  type as string. Empty if not found.

## ◆ tds_read_namelist()

static int tds_read_namelist | ( | TDSSOCKET * | tds,
|  | int | remainder,
|  | struct namelist ** | p_head,
|  | int | large
| ) |  |
| static

Reads list of names (usually table names)

Parameters

  tds | A pointer to the TDSSOCKET structure managing a client/server operation.
  remainder | bytes left to read
  p_head | list head to return
  large | true if name length from network are 2 byte (usually 1)

Here is the caller graph for this function:

## ◆ tds_token_name()

static const char * tds_token_name | ( | unsigned char | marker | ) |
| static

Returns string representation for a given token type.

Parameters

  marker | token type

Returns
  string representation. Empty if not token not valid.