FreeTDS API

Functions
Remote Procedure functions
The db-lib API

Functions used with stored procedures. More...

Collaboration diagram for Remote Procedure functions:

## Functions
DBBOOL | dbhasretstat (DBPROCESS *dbproc)
| Determine if query generated a return status number. More...
int | dbnumrets (DBPROCESS *dbproc)
| Get count of output parameters filled by a stored procedure. More...
BYTE * | dbretdata (DBPROCESS *dbproc, int retnum)
| Get value of an output parameter filled by a stored procedure. More...
int | dbretlen (DBPROCESS *dbproc, int retnum)
| Get size of an output parameter filled by a stored procedure. More...
char * | dbretname (DBPROCESS *dbproc, int retnum)
| Get name of an output parameter filled by a stored procedure. More...
DBINT | dbretstatus (DBPROCESS *dbproc)
| Fetch status value returned by query or remote procedure call. More...
int | dbrettype (DBPROCESS *dbproc, int retnum)
| Get datatype of a stored procedure's return parameter. More...
RETCODE | dbrpcinit (DBPROCESS *dbproc, const char rpcname[], DBSMALLINT options)
| Initialize a remote procedure call. More...
RETCODE | dbrpcparam (DBPROCESS *dbproc, const char paramname[], BYTE status, int db_type, DBINT maxlen, DBINT datalen, BYTE *value)
| Add a parameter to a remote procedure call. More...
RETCODE | dbrpcsend (DBPROCESS *dbproc)
| Execute the procedure and free associated memory. More...

## Detailed Description

Functions used with stored procedures.

Especially useful for OUTPUT parameters, because modern Microsoft servers do not return output parameter data to the client unless the procedure was invoked with dbrpcsend().

## Function Documentation

## § dbhasretstat()

DBBOOL dbhasretstat | ( | DBPROCESS * | dbproc | ) |

Determine if query generated a return status number.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.

Return values

  TRUE | fetch return status with dbretstatus().
  FALSE | no return status.

See also
  dbnextrow(), dbresults(), dbretdata(), dbretstatus(), dbrpcinit(), dbrpcparam(), dbrpcsend().

Here is the call graph for this function:

## § dbnumrets()

int dbnumrets | ( | DBPROCESS * | dbproc | ) |

Get count of output parameters filled by a stored procedure.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.

Returns
  How many, possibly zero.

Remarks
  This name sounds funny.

See also

Here is the call graph for this function:

## § dbretdata()

BYTE* dbretdata | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |  |

Get value of an output parameter filled by a stored procedure.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth parameter between `1` and the return value from `dbnumrets()`.

Returns
  Address of a return parameter value, or `NULL` if no such retnum.

See also
  dbnextrow(), dbnumrets(), dbresults(), dbretlen(), dbretname(), dbrettype(), dbrpcinit(), dbrpcparam().

Todo:
  Handle blobs.

Here is the call graph for this function:

## § dbretlen()

int dbretlen | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |  |

Get size of an output parameter filled by a stored procedure.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth parameter between `1` and the return value from `dbnumrets()`.

Returns
  Size of a return parameter value, or `NULL` if no such retnum.

See also
  dbnextrow(), dbnumrets(), dbresults(), dbretdata(), dbretname(), dbrettype(), dbrpcinit(), dbrpcparam().

Here is the call graph for this function:

## § dbretname()

char* dbretname | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |  |

Get name of an output parameter filled by a stored procedure.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth parameter between `1` and the return value from `dbnumrets()`.

Returns
  ASCII null-terminated string, `NULL` if no such retnum.

See also
  dbnextrow(), dbnumrets(), dbresults(), dbretdata(), dbretlen(), dbrettype(), dbrpcinit(), dbrpcparam().

Here is the call graph for this function:

## § dbretstatus()

DBINT dbretstatus | ( | DBPROCESS * | dbproc | ) |

Fetch status value returned by query or remote procedure call.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.

Returns
  return value

See also
  dbhasretstat(), dbnextrow(), dbresults(), dbretdata(), dbrpcinit(), dbrpcparam(), dbrpcsend().

Here is the call graph for this function:

## § dbrettype()

int dbrettype | ( | DBPROCESS * | dbproc,
|  | int | retnum
| ) |  |

Get datatype of a stored procedure's return parameter.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  retnum | Nth return parameter, between 1 and `dbnumrets()`.

Returns
  SYB* datatype token, or -1 if retnum is out of range.

See also
  dbnextrow(), dbnumrets(), dbprtype(), dbresults(), dbretdata(), dbretlen(), dbretname(), dbrpcinit(), dbrpcparam().

Here is the call graph for this function:

## § dbrpcinit()

RETCODE dbrpcinit | ( | DBPROCESS * | dbproc,
|  | const char | rpcname[],
|  | DBSMALLINT | options
| ) |  |

Initialize a remote procedure call.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  rpcname | name of the stored procedure to be run.
  options | Only supported option would be DBRPCRECOMPILE, which causes the stored procedure to be recompiled before executing.

Remarks
  The RPC functions are the only way to get back OUTPUT parameter data with db-lib from modern Microsoft servers.

Return values

  SUCCEED | normal.
  FAIL | on error

See also
  dbrpcparam(), dbrpcsend()

Here is the call graph for this function:

## § dbrpcparam()

RETCODE dbrpcparam | ( | DBPROCESS * | dbproc,
|  | const char | paramname[],
|  | BYTE | status,
|  | int | db_type,
|  | DBINT | maxlen,
|  | DBINT | datalen,
|  | BYTE * | value
| ) |  |

Add a parameter to a remote procedure call.

Call between dbrpcinit() and dbrpcsend()

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  paramname | literal name of the parameter, according to the stored procedure (starts with '@'). Optional. If not used, parameters will be passed in order instead of by name.
  status | must be DBRPCRETURN, if this parameter is a return parameter, else 0.
  type | datatype of the value parameter e.g., SYBINT4, SYBCHAR.
  maxlen | Maximum output size of the parameter's value to be returned by the stored procedure, usually the size of your host variable. Fixed-length datatypes take -1 (NULL or not). Non-OUTPUT parameters also use -1. Use 0 to send a NULL value for a variable length datatype.
  datalen | For variable-length datatypes, the byte size of the data to be sent, exclusive of any null terminator. For fixed-length datatypes use -1. To send a NULL value, use 0.
  value | Address of your host variable.

Return values

  SUCCEED | normal.
  FAIL | on error

See also
  dbrpcinit(), dbrpcsend()

Here is the call graph for this function:

## § dbrpcsend()

RETCODE dbrpcsend | ( | DBPROCESS * | dbproc | ) |

Execute the procedure and free associated memory.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.

Return values

  SUCCEED | normal.
  FAIL | on error

See also
  dbrpcinit(), dbrpcparam()

Here is the call graph for this function: