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, const char rpcname[], DBSMALLINT options)
	Initialize a remote procedure call.
RETCODE	dbrpcparam (DBPROCESS *dbproc, const 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,
		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()

RETCODE dbrpcparam	(	DBPROCESS *	dbproc,
		const 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()