# Remote Procedure functions
[The db-lib API]

Functions used with stored procedures. More...

## Functions

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

## 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

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().

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:

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.

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().

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().

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().

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().

RETCODE dbrpcinit | ( | DBPROCESS * | dbproc,
|  | 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.

Todo:
  I don't know the value for DBRPCRECOMPILE and have not added it to sybdb.h

Return values:

  | SUCCEED | normal.
  | FAIL | on error

See also:
  dbrpcparam(), dbrpcsend()

RETCODE dbrpcparam | ( | DBPROCESS * | dbproc,
|  | char * | paramname,
|  | BYTE | status,
|  | int | 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()

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()