1 Version 4.0 -- 5/1/89 dbrpcinit
______________________________________________________________________
NAME: dbrpcinit
FUNCTION:
Initialize a remote procedure call.
SYNTAX:
RETCODE dbrpcinit(dbproc, rpcname, options)
DBPROCESS *dbproc;
char *rpcname;
DBSMALLINToptions;
dbrpcinit Version 4.0 -- 5/1/89 2
______________________________________________________________________
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").
o Remote procedure calls have a few advantages over EXECUTE
statements:
o An rpc passes the stored procedure's parameters in their
native datatypes, in contrast to the EXECUTE statement,
which passes parameters as ASCII characters. Therefore, the
rpc method is faster and usually more compact than the EXE-
CUTE statement, because it does not require either the
application program or the server to convert between native
datatypes and their ASCII equivalents.
o It is simpler and faster to accommodate stored procedure
3 Version 4.0 -- 5/1/89 dbrpcinit
______________________________________________________________________
return parameters with an rpc, instead of an EXECUTE state-
ment. With an rpc, the return parameters are automatically
available to the application. (Note, however, that a return
parameter must be specified as such when it's originally
added to the rpc via the dbrpcparam() routine.) If, on the
other hand, a stored procedure is called with an EXECUTE
statement, the return parameter values are available only if
the command batch containing the EXECUTE statement uses
local variables, not constants, as the return parameters.
This involves additional parsing each time the command batch
is executed.
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
specified procedure. You can then call dbsqlok(), dbresults(),
dbrpcinit Version 4.0 -- 5/1/89 4
______________________________________________________________________
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.
rpcname - A pointer to the name of the stored procedure to be
invoked.
options - A two-byte bitmask of rpc options. So far, the only
5 Version 4.0 -- 5/1/89 dbrpcinit
______________________________________________________________________
option available is DBRPCRECOMPILE, which causes the stored
procedure to be recompiled before it is executed.
RETURNS:
SUCCEED or FAIL.
SEE ALSO:
dbnextrow, dbresults, dbretdata, dbretstatus, dbrpcparam,
dbrpcsend, dbsqlok