FreeTDS API
Loading...
Searching...
No Matches
Functions
Remote Procedure functions

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.
 
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 db_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

◆ dbhasretstat()

DBBOOL dbhasretstat ( DBPROCESS dbproc)

Determine if query generated a return status number.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
Return values
TRUEfetch return status with dbretstatus().
FALSEno return status.
See also
dbnextrow(), dbresults(), dbretdata(), dbretstatus(), dbrpcinit(), dbrpcparam(), dbrpcsend().

◆ dbnumrets()

int dbnumrets ( DBPROCESS dbproc)

Get count of output parameters filled by a stored procedure.

Parameters
dbproccontains 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:
Here is the caller graph for this function:

◆ dbretdata()

BYTE * dbretdata ( DBPROCESS dbproc,
int  retnum 
)

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

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
retnumNth 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
dbproccontains all information needed by db-lib to manage communications with the server.
retnumNth 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
dbproccontains all information needed by db-lib to manage communications with the server.
retnumNth 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
dbproccontains all information needed by db-lib to manage communications with the server.
Returns
return value
See also
dbhasretstat(), dbnextrow(), dbresults(), dbretdata(), dbrpcinit(), dbrpcparam(), dbrpcsend().

◆ dbrettype()

int dbrettype ( DBPROCESS dbproc,
int  retnum 
)

Get datatype of a stored procedure's return parameter.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
retnumNth 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().

◆ dbrpcinit()

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

Initialize a remote procedure call.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
rpcnamename of the stored procedure to be run.
optionsOnly 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
SUCCEEDnormal.
FAILon 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
dbproccontains all information needed by db-lib to manage communications with the server.
paramnameliteral 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.
statusmust be DBRPCRETURN, if this parameter is a return parameter, else 0.
typedatatype of the value parameter e.g., SYBINT4, SYBCHAR.
maxlenMaximum 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.
datalenFor 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.
valueAddress of your host variable.
Return values
SUCCEEDnormal.
FAILon 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
dbproccontains all information needed by db-lib to manage communications with the server.
Return values
SUCCEEDnormal.
FAILon error
See also
dbrpcinit(), dbrpcparam()
Here is the call graph for this function: