dbrpcparam
Adds a parameter to a stored procedure or a remote stored procedure.
Syntax
RETCODE dbrpcparam (
PDBPROCESS dbproc,
LPCSTR paramname,
BYTE status,
INT type,
DBINT maxlen,
DBINT datalen,
LPCBYTE value );
Arguments
dbproc
Is the DBPROCESS structure that is the handle for a particular workstation or Microsoft® SQL Server™ 2000 process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.
paramname
Is a pointer to the name of the parameter to be invoked. This name must begin with (@), as do all parameter names within stored procedures. As in the Transact-SQL EXECUTE statement, the name is optional. If no name is used, this parameter should be specified as NULL. In that case, the order of the dbrpcparam calls determines the parameter to which each call refers.
status
Is a 1-byte bitmask of parameter options for stored procedures. The only option currently available is DBRPCRETURN, which signifies that an application designates this parameter as a return parameter. Specify 0 to indicate no options.
type
Is the data type of the value parameter (such as SQLINT1, SQLCHAR, and so on).
maxlen
For variable-length return parameters (when type is SQLCHAR, SQLBINARY, SQLTEXT, or SQLIMAGE), maxlen is the maximum desired byte length for the value parameter returned from a stored procedure.
Set maxlen to -1 in any of these cases:
- For fixed-length return parameters (such as when type is SQLINT4).
- To pass a NULL fixed-length parameter value (such as when type is SQLINT4) to the stored procedure.
- For parameters that are not designated as return parameters.
Set maxlen to 0 to pass a NULL variable-length parameter value (when type is SQLCHAR, SQLBINARY, SQLTEXT, or SQLIMAGE) to the stored procedure.
datalen
For variable-length return parameters (where type is SQLCHAR, SQLBINARY, SQLTEXT, or SQLIMAGE), datalen is the actual byte length of the value parameter sent to the stored procedure. The byte length should not count any null terminator.
Set datalen to - 1 for non-NULL fixed-length parameters (such as when type is SQLINT4).
Set datalen to 0 to pass a NULL parameter value (fixed or variable length) to the stored procedure.
value
Is a pointer to the program variable containing the stored procedure parameter value itself.
The following table summarizes the required maxlen and datalen values for each type of parameter.
| Parameter | maxlen | datalen |
|---|---|---|
| Fixed-length | - 1 | - 1 |
| Variable-length | Maximum desired length of return value. | Length of input value not counting null terminator. |
| Fixed-length NULL | - 1 | 0 |
| Variable-length NULL | 0 | 0 |
When specifying a NULL parameter, the actual contents of value are not used, and a NULL parameter is added to the stored procedure. However, when type is SQLDECIMAL or SQLNUMERIC, value must still point to a valid DBDECIMAL or DBNUMERIC structure.
Returns
SUCCEED or FAIL.
Remarks
After initializing a stored procedure using dbrpcinit, you must call dbrpcparam once for each parameter of the stored procedure that does not have a default value. You specify default values for stored procedure parameters in the CREATE PROCEDURE statement. For more information about executing stored procedures using DB-Library functions, see dbrpcinit.