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/ Microsoft® SQL Server™ 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 is 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.

See Also