NCBI C++ ToolKit
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. More...
 
DBINT dbretstatus (DBPROCESS *dbproc)
 Fetch status value returned by query or remote procedure call. More...
 
int dbnumrets (DBPROCESS *dbproc)
 Get count of output parameters filled by a stored procedure. More...
 
char * dbretname (DBPROCESS *dbproc, int retnum)
 Get name of an output parameter filled by a stored procedure. More...
 
BYTEdbretdata (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...
 
int dbrettype (DBPROCESS *dbproc, int retnum)
 Get datatype of a stored procedure's return parameter. More...
 
RETCODE dbrpcinit (DBPROCESS *dbproc, char *rpcname, DBSMALLINT options)
 Initialize a remote procedure call. More...
 
RETCODE dbrpcparam (DBPROCESS *dbproc, char *paramname, BYTE status, int 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...
 
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 type, DBINT maxlen, DBINT datalen, BYTE *value)
 Add a parameter to a remote procedure call. 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

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

Definition at line 3887 of file dblib.c.

References CHECK_PARAMETER, dbnumrets(), FALSE, tds_socket::has_status, SYBENULL, tds, TDS_DBG_FUNC, tds_dblib_dbprocess::tds_socket, tdsdump_log, and TRUE.

Referenced by main(), CDBL_LangCmd::Result(), CDBL_RPCCmd::Result(), and CDBL_Connection::x_Results().

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

Definition at line 3928 of file dblib.c.

References CHECK_PARAMETER, NULL, tds_result_info::num_cols, tds_socket::param_info, SYBENULL, tds, TDS_DBG_FUNC, tds_process_tokens, tds_dblib_dbprocess::tds_socket, TDS_TOKEN_TRAILING, and tdsdump_log.

Referenced by check_state(), dbhasretstat(), dbretdata(), dbretlen(), dbretname(), dbretstatus(), main(), CDBL_LangCmd::Result(), CDBL_RPCCmd::Result(), and CDBL_Connection::x_Results().

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

Definition at line 3984 of file dblib.c.

References CHECK_PARAMETER, column, tds_column::column_data, tds_column::column_offset, tds_result_info::columns, tds_result_info::current_row, dbnumrets(), NULL, tds_result_info::num_cols, tds_socket::param_info, SYBENULL, tds, TDS_DBG_FUNC, tds_dblib_dbprocess::tds_socket, and tdsdump_log.

Referenced by main(), CDBL_ParamResult::ReadItem(), and CDBL_Result::RetGetItem().

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

Definition at line 4012 of file dblib.c.

References CHECK_PARAMETER, column, tds_column::column_cur_size, tds_result_info::columns, dbnumrets(), tds_result_info::num_cols, tds_socket::param_info, SYBENULL, tds, TDS_DBG_FUNC, tds_dblib_dbprocess::tds_socket, and tdsdump_log.

Referenced by main(), CDBL_ParamResult::ReadItem(), CDBL_Result::RetGetDataType(), and CDBL_Result::RetGetItem().

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

Definition at line 3957 of file dblib.c.

References assert, CHECK_PARAMETER, tds_column::column_name, tds_column::column_namelen, tds_result_info::columns, dbnumrets(), NULL, tds_result_info::num_cols, tds_socket::param_info, SYBENULL, TDS_DBG_FUNC, tds_dstr_buf, tds_dblib_dbprocess::tds_socket, and tdsdump_log.

Referenced by CDBL_ParamResult::CDBL_ParamResult(), and main().

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

Definition at line 3909 of file dblib.c.

References CHECK_PARAMETER, dbnumrets(), tds_socket::ret_status, SYBENULL, TDS_DBG_FUNC, tds_dblib_dbprocess::tds_socket, and tdsdump_log.

Referenced by CDBL_StatusResult::CDBL_StatusResult(), check_state(), and main().

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

Definition at line 5225 of file dblib.c.

References assert, CHECK_PARAMETER, tds_column::column_size, tds_column::column_type, tds_result_info::columns, tds_result_info::num_cols, tds_socket::param_info, SYBENULL, tds, TDS_DBG_FUNC, tds_get_conversion_type, tds_dblib_dbprocess::tds_socket, and tdsdump_log.

Referenced by main(), and CDBL_Result::RetGetDataType().

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

Definition at line 74 of file rpc.c.

References CHECK_CONN, CHECK_NULP, dbperror(), DBPERROR_RETURN3, DBRPCRECOMPILE, DBRPCRESET, errno, FAIL, _DBREMOTE_PROC::next, NULL, tds_dblib_dbprocess::rpc, rpc_clear(), util::strcmp(), strdup, SUCCEED, SYBEIPV, SYBEMEM, TDS_DBG_FUNC, TDS_DBG_INFO1, and tdsdump_log.

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

Definition at line 75 of file rpc.c.

References DBRPCRECOMPILE, DBRPCRESET, FAIL, _DBREMOTE_PROC::next, NULL, tds_dblib_dbprocess::rpc, rpc_clear(), util::strcmp(), strdup, SUCCEED, TDS_DBG_INFO1, and tdsdump_log.

Referenced by main(), CDBL_RPCCmd::Send(), and test().

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

Definition at line 155 of file rpc.c.

References _DBREMOTE_PROC_PARAM::datalen, DBRPCRETURN, FAIL, is_fixed_type, _DBREMOTE_PROC_PARAM::maxlen, _DBREMOTE_PROC_PARAM::name, _DBREMOTE_PROC_PARAM::next, _DBREMOTE_PROC::next, NULL, _DBREMOTE_PROC::param_list, tds_dblib_dbprocess::rpc, _DBREMOTE_PROC_PARAM::status, strdup, SUCCEED, TDS_DBG_INFO1, tdsdump_log, type, _DBREMOTE_PROC_PARAM::type, _DBREMOTE_PROC_PARAM::value, and value.

Referenced by main(), test(), and CDBL_RPCCmd::x_AssignParams().

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

Definition at line 157 of file rpc.c.

References CHECK_CONN, CHECK_PARAMETER, tds_socket::conn, _DBREMOTE_PROC_PARAM::datalen, dbperror(), DBPERROR_RETURN, DBPERROR_RETURN3, DBRPCRETURN, FAIL, is_fixed_type, is_nullable_type, IS_TDS7_PLUS, _DBREMOTE_PROC_PARAM::maxlen, _DBREMOTE_PROC_PARAM::name, _DBREMOTE_PROC_PARAM::next, _DBREMOTE_PROC::next, NULL, _DBREMOTE_PROC::param_list, tds_dblib_dbprocess::rpc, _DBREMOTE_PROC_PARAM::status, strdup, SUCCEED, SYBEIPV, SYBEMEM, SYBERPCS, SYBERPIL, SYBERPNULL, SYBERPUL, SYBVARCHAR, TDS_DBG_FUNC, TDS_DBG_INFO1, tds_dblib_dbprocess::tds_socket, tdsdump_log, type, _DBREMOTE_PROC_PARAM::type, _DBREMOTE_PROC_PARAM::value, value, and XSYBNVARCHAR.

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

Definition at line 262 of file rpc.c.

References _DB_RES_INIT, CHECK_CONN, CHECK_PARAMETER, tds_dblib_dbprocess::dbresults_state, FAIL, _DBREMOTE_PROC::name, _DBREMOTE_PROC::next, NULL, param_info_alloc(), _DBREMOTE_PROC::param_list, tds_dblib_dbprocess::rpc, rpc_clear(), SUCCEED, SYBERPCS, TDS_DBG_FUNC, TDS_DBG_INFO1, TDS_FAIL, TDS_FAILED, tds_free_param_results, tds_dblib_dbprocess::tds_socket, tds_submit_rpc, and tdsdump_log.

Referenced by main(), CDBL_RPCCmd::Send(), and test().

Modified on Tue Jul 25 19:51:33 2017 by modify_doxy.py rev. 533848