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

---