Add a parameter to a remote procedure call.
RETCODE dbrpcparam(dbproc, paramname, status, type,
maxlen, datalen, value)
DBPROCESS *dbproc;
char *paramname;
BYTE status;
int type;
DBINT maxlen;
DBINT datalen;
BYTE *value;
A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and the server.
A pointer to the name of the parameter to be invoked. This name must begin with the “@” character, which prefixes all stored procedure parameter names. As in the Transact-SQL execute statement, the name is optional. If it is not used, it should be specified as NULL. In that case, the order of the dbrpcparam calls determines the parameter to which each refers.
A 1-byte bitmask of RPC-parameter options. So far, the only option available is DBRPCRETURN, which signifies that the application program would like this parameter used as a return parameter.
A symbolic constant indicating the datatype of the parameter (for example, SYBINT1, SYBCHAR, and so on). Parameter values should be sent to the server in a datatype that matches the Adaptive Server datatype with which the corresponding stored procedure parameter was defined—see Types for a list of type constants and the corresponding Adaptive Server datatypes.
For return parameters, this is the maximum desired byte length for the RPC parameter value returned from the stored procedure. maxlen is relevant only for values whose datatypes are not fixed in length—that is, char, text, binary, and image values. If this parameter does not apply (that is, if the type is a fixed length datatype such as SYBINT2) or if you do not care about restricting the lengths of return parameters, set maxlen to -1. maxlen should also be set to -1 for parameters not designated as return parameters.
The length, in bytes, of the RPC parameter to pass to the stored procedure. This length should not count any null terminator.
If type is SYBCHAR, SYBVARCHAR, SYBBINARY, SYBVARBINARY, SYBBOUNDARY, or SYBSENSITIVITY, datalen must be specified. Passing datalen as -1 for any of these datatypes results in the DBPROCESS referenced by dbproc being marked as “dead,” or unusable.
If type is a fixed length datatype, for example, SYBINT2, pass datalen as -1.
If the value of the RPC parameter is NULL, pass datalen as 0, even if type is a fixed-length datatype.
A pointer to the RPC parameter itself. If datalen is 0, this pointer will be ignored and treated as NULL. Note that DB-Library does not copy *value into its internal buffer space until the application calls dbrpcsend. An application must not write over *value until after it has called dbrpcsend.
The value of type indicates the datatype of *value. See Types for more information. For types that have no C equivalent, such as SYBDATETIME, SYBMONEY, SYBNUMERIC, or SYBDECIMAL, use dbconvert_ps to initialize *value.
An application must not write over *value until
after it has called dbrpcsend to
send the remote procedure call to the server. This is a functional change
from previous versions of DB-Library.
SUCCEED or FAIL.
An application can call a stored procedure in two ways: by executing a command buffer containing a Transact-SQL execute statement or by making a remote procedure call (RPC). See the reference page for dbrpcinit for a discussion of the differences between these techniques.
To make a remote procedure call, first call dbrpcinit to specify the stored procedure that is to be invoked. Then call dbrpcparam once for each of the stored procedure’s parameters. Finally, call dbrpcsend to signify the end of the parameter list. This causes the server to begin executing the specified procedure. You can then call dbsqlok, dbresults, and dbnextrow to process the stored procedure’s results. (Note that you will need to call dbresults multiple times if the stored procedure contains more than one select statement.) After all of the stored procedure’s results have been processed, you can call the routines that process return parameters and status numbers, such as dbretdata and dbretstatus.
If type is SYBCHAR, SYBVARCHAR, SYBBINARY, SYBVARBINARY, SYBBOUNDARY, and SYBSENSITIVITY, datalen must be specified. Passing datalen as -1 for any of these datatypes results in the DBPROCESS referenced by dbproc being marked as “dead,” or unusable.
If type is SYBNUMERIC or SYBDECIMAL, use dbconvert_ps to initialize the DBNUMERIC or DBDECIMAL value in *value and specify its precision and scale.
If the procedure being executed resides on a server other than the one to which the application is directly connected, commands executed within the procedure cannot be rolled back.
For an example of a remote procedure call, see the sample program example8.c.
dbnextrow, dbresults, dbretdata, dbretstatus, dbrpcinit, dbrpcsend, dbsqlok
