1 Version 4.0 -- 5/1/89 dbrpcparam
______________________________________________________________________
NAME: dbrpcparam
FUNCTION:
Add a parameter to a remote procedure call.
SYNTAX:
RETCODE dbrpcparam(dbproc, paramname, status, type, maxlen,
datalen, value)
DBPROCESS *dbproc;
char *paramname;
BYTE status;
dbrpcparam Version 4.0 -- 5/1/89 2
______________________________________________________________________
int type;
DBINT maxlen;
DBINT datalen;
BYTE *value;
COMMENTS:
o An application can call a stored procedure in two ways: by exe-
cuting a command buffer containing a Transact-SQL EXECUTE
statement or by making a remote procedure call ("rpc"). See
the manual page for dbrpcinit() for a discussion of the differ-
ences between these techniques.
o To make a remote procedure call, first call dbrpcinit() to
specify the stored procedure that's to be invoked. Then call
dbrpcparam() once for each of the stored procedure's parame-
ters. Finally, call dbrpcsend() to signify the end of the
parameter list. This causes the server to begin executing the
3 Version 4.0 -- 5/1/89 dbrpcparam
______________________________________________________________________
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 pro-
cessed, you can call the routines that process return parame-
ters and status numbers, such as dbretdata() and dbretstatus().
o For an example of a remote procedure call, see Example 8 in the
DB-Library Reference Supplement.
PARAMETERS:
dbproc - 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.
paramname - A pointer to the name of the parameter to be
invoked. This name must begin with the "@" symbol, which
dbrpcparam Version 4.0 -- 5/1/89 4
______________________________________________________________________
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.
status - A one-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.
type - The datatype of the parameter (e.g., SYBINT1, SYBCHAR,
etc.).
maxlen - 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 data-
types are not fixed in length-that is, character, text,
binary, and image values. If this parameter doesn't apply
(i.e., if the type is a fixed length datatype such as
5 Version 4.0 -- 5/1/89 dbrpcparam
______________________________________________________________________
SYBINT2) or if you don't 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 parame-
ters.
datalen - The actual byte length of the rpc parameter value that
gets sent to the stored procedure. datalen must be used with
values whose datatypes are not fixed in length; that is,
character, text, binary, and image values. The byte length
should not count any null terminator. If this parameter
doesn't apply (i.e., if the type is a fixed length datatype
such as SYBINT2), set datalen to -1. If the value of the rpc
parameter is NULL, you must set datalen to 0, even if the
type is a fixed length datatype.
value - A pointer to the rpc parameter itself. If datalen is 0,
this pointer will be ignored and treated as NULL.
RETURNS:
dbrpcparam Version 4.0 -- 5/1/89 6
______________________________________________________________________
SUCCEED or FAIL.
SEE ALSO:
dbnextrow, dbresults, dbretdata, dbretstatus, dbrpcinit,
dbrpcsend, dbsqlok