SQL server 2008 R2 : Creating and Managing Stored Procedures - Using Input Parameters

To increase the flexibility of stored procedures and perform more complex processing, you can pass parameters to procedures. The parameters can be used anywhere that local variables can be used within the procedure code.

The following example is a stored procedure that requires three parameters:

CREATE PROC myproc
 @parm1 int, @parm2 int, @parm3 int
AS
-- Processing goes here
RETURN

If you want to help identify the data values for which the parameters are defined, it is recommended that you give your parameters meaningful names. Parameter names, like local variables, can be up to 128 characters in length, including the @ sign, and they must follow SQL Server rules for identifiers. Up to 2,100 parameters can be defined for a stored procedure.

When you execute a procedure, you can pass the parameters by position or by name:

--Passing parameters by position
EXEC myproc 1, 2, 3
--Passing parameters by name
EXEC myproc @parm2 = 2, @parm2 = 1, @parm3 =3
--Passing parameters by position and name
EXEC myproc 1, @parm3 =3, @parm2 = 2

After you specify one parameter by name, you must pass all subsequent parameters for the procedure in that EXECUTE statement by name as well. You cannot pass any of the subsequent parameters by position. If you want to skip parameters that are not the last parameter(s) in the procedure and have them take default values (as described in the next section), you also need to pass parameters by name or use the DEFAULT keyword in place of the parameter value.

Input parameter values passed in can be only explicit constant values, local variables, parameters, or, new for SQL Server 2008, table-valued parameters. However, you cannot specify a function or another expression as an input parameter value. You would have to store a return value from the function or expression value in a local variable and pass the local variable as the input parameter. Likewise, you cannot use a function or another expression as a default value for a parameter.

Setting Default Values for Parameters

You can assign a default value to a parameter by specifying a value in the definition of the parameter, as shown in Listing 1.

Listing 1. Assigning a Default Value for a Parameter in a Stored Procedure

ALTER PROCEDURE title_authors @state char(2) = '%'
AS
SELECT a.au_lname, a.au_fname, t.title
   FROM titles t
   INNER JOIN titleauthor ta ON t.title_id = ta.title_id
   RIGHT OUTER JOIN authors a ON ta.au_id = a.au_id
    WHERE a.state like @state
RETURN
 GO

You can have SQL Server apply the default value for a parameter during execution by not specifying a value or by specifying the DEFAULT keyword in the position of the parameter, as shown in Listing 2.

Listing 2. Applying a Default Value for a Parameter When Executing a Stored Procedure

EXEC title_authors
EXEC title_authors DEFAULT
EXEC title_authors @state = DEFAULT

EXEC myproc


Server: Msg 201, Level 16, State 4, Procedure myproc, Line 0
Procedure 'myproc' expects parameter '@parm1', which was not
 supplied.

CREATE PROC MyProc2
 @parm1 int = NULL, @parm2 int = 32, @parm3 int = NULL
AS
IF (@parm1 IS NULL or @parm1 NOT BETWEEN 1 and 10) OR
   @parm3 IS NULL
PRINT 'Usage:
 EXEC MyProc2
 @parm1 int,   (Required: Can be between 1 and 10)
 @parm2 = 32,  (Optional: Default value of 32)
 @parm3 int,   (Required: Any number within range)'
-- Processing goes here
RETURN
GO

EXEC MyProc2
GO


Usage:
 EXEC MyProc2
 @parm1 int,   (Required: Can be between 1 and 10)
 @parm2 = 32,  (Optional: Default value of 32)
 @parm3 int,   (Required: Any number within range)

To display the parameters defined for a stored procedure, you can view them in the SSMS Object Explorer (see Figure 1) or by executing the sp_help stored procedure, as shown in Listing 3. (Note that the output has been edited to fit the page.)

Figure 1. Displaying stored procedure parameters in SSMS.

Listing 3. Displaying Stored Procedure Parameters by Using sp_help

exec sp_help title_authors
Name              Owner      Type              Created_datetime
-------------- ----- ------ ---- ------- ----------- ---------------------------
title_authors     dbo        stored procedure  2008-09-15 21:15:06.540




Parameter_name Type  Length Prec Scale Param_order Collation
-------------- ----- ------ ---- ------- ----------- ---------------------------
@state         char  2      2    NULL            1 SQL_Latin1_General_CP1_CI_AS


					  

You can also display the stored procedure parameters by running a query against the INFORMATION_SCHEMA view parameters:

select substring(Parameter_NAME,1, 30) as Parameter_name,
       substring (DATA_TYPE, 1, 20) as Data_Type,
       CHARACTER_MAXIMUM_LENGTH as Length,
       ordinal_position as param_order,
       Collation_name
from INFORMATION_SCHEMA.parameters
where specific_name = 'title_authors'
  and specific_schema = 'dbo'
order by ordinal_position

go

Parameter_name   Data_Type     Length  param_order Collation_name
---------------- ------------- ------- ----------- -----------------------------
@state           char                2           1 SQL_Latin1_General_CP1_CI_AS


					  

You can view parameter information for a stored procedure as well using the sys.parameters catalog view:

select substring(p.name,1, 30) as Parameter_name,
       substring (t.name, 1, 20) as Data_Type,
       p.max_length as Length,
       parameter_id as param_order,
       default_value
from sys.parameters p
inner join sys.types t
     on p.user_type_id = t.user_type_id
where p.object_id = object_id('title_authors')
order by parameter_id

go

Parameter_name  Data_Type  Length param_order default_value
--------------- ---------- ------ ------------ --------------
@state          char       2      1           NULL

Passing Object Names as Parameters

In SQL Server 2008, if you pass an object name as a parameter to a stored procedure, SQL Server attempts to treat it as a table-valued parameter unless the object name is used either as an argument in a WHERE clause or in a dynamic SQL query. For example, the code in Listing 4 generates an error message when you try to create the stored procedure.

Listing 4. Attempting to Create a Stored Procedure by Using a Parameter to Pass in a Table Name

CREATE  proc find_data @table varchar(128)
as

select * from @table

GO

Msg 1087, Level 16, State 1, Procedure find_data, Line 4
 Must declare the table variable "@table".

As you can see, when the parameter is used in the FROM clause, SQL Server expects it to be defined as a table variable. To use the value in the parameter as a table name, you can build a dynamic SQL query similar to the example shown in Listing 5.

Listing 5. Passing a Table as a Parameter to a Stored Procedure for Dynamic SQL Execution

CREATE  proc find_data @table varchar(128)
as

exec ('select * from ' + @table)
return
go

exec find_data @table = 'publishers'
go

pub_id pub_name                    city            state country
------ ------------------------ ---------------- ----- ---------
0736   New Moon Books              Boston          MA    USA
0877   Binnet & Hardley            Washington      DC    USA
1389   Algodata Infosystems        Berkeley        CA    USA
1622   Five Lakes Publishing       Chicago         IL    USA
1756   Ramona Publishers           Dallas          TX    USA
...
9952   Scootney Books              New   York      NY    USA
9999   Lucerne Publishing          Paris           NULL  France

Using Wildcards in Parameters

Wildcards can be included in varchar-based input parameters and used in a LIKE clause in a query to perform pattern matching. However, you should not use the char data type for parameters that will contain wildcard characters because SQL Server pads spaces onto the value passed in to the parameter to expand it to the specified size of the char data type. For example, if you declared an @lastname parameter as char(40) and passed in 'S%', SQL Server would search not for a string starting with 'S' but for a string starting with 'S', any characters, and ending with up to 38 spaces. This would likely not match any actual data values.

Also, to increase the flexibility of a stored procedure that searches for character strings, you can default the parameter to '%', as in the following example:

IF EXISTS ( SELECT * FROM sys.procedures
               WHERE schema_id = schema_id('dbo')
                 AND name = N'find_authors')
   DROP PROCEDURE dbo.find_authors
GO
 create proc find_authors @lastname varchar(40) = '%'
as
    select au_id, au_lname, au_fname
        from authors
        where au_lname like @lastname
        order by au_lname, au_fname

This procedure, if passed no parameter, returns data for all authors in the authors table. If passed a string containing wildcard characters, this procedure returns data for all authors matching the search pattern specified. If a string containing no wildcards is passed, the query performs a search for exact matches against the string value.

Unfortunately, wildcard searches can be performed only against character strings. If you want to have similar flexibility searching against a numeric value, such as an integer, you can default the value to NULL and when the parameter is NULL, compare the column with itself, as shown in the following example:

IF EXISTS ( SELECT * FROM sys.procedures
               WHERE schema_id = schema_id('dbo')
                 AND name = N'find_titles_by_sales')
   DROP PROCEDURE dbo.find_titles_by_sales
GO
create proc find_titles_by_sales @ytd_sales int = null
as
    select title_id, title, ytd_sales
        from titles
        where ytd_sales = isnull(@ytd_sales, ytd_sales)

However, the problem with this approach is that the procedure returns all rows from the titles table except those in which ytd_sales contains a NULL value. The reason is that NULL is never considered equal to NULL; you cannot compare an unknown value with another unknown value. To return all rows, including those in which ytd_sales is NULL, you need to implement a dual-query solution, as in the following example:

IF EXISTS ( SELECT * FROM sys.procedures
               WHERE schema_id = schema_id('dbo')
                 AND name = N'find_titles_by_sales')
   DROP PROCEDURE dbo.find_titles_by_sales
GO
create proc find_titles_by_sales @ytd_sales int = null
as
if @ytd_sales is null
    select title_id, title, ytd_sales
        from titles
else
    select title_id, title, ytd_sales
        from titles
        where ytd_sales= @ytd_sales

Using Table-Valued Parameters

In previous versions of SQL Server, it was not possible to share the contents of table variables between stored procedures. SQL Server 2008 changes that with the introduction of table-valued parameters, which allow you to pass table variables to stored procedures. Table-valued parameters provide more flexibility and, in many cases, better performance than temporary tables as a means to pass result sets between stored procedures.

Table-valued parameters provide many of the same performance advantages as table data types. Table-valued parameters also share some of the same restrictions as table variables, such as SQL Server not maintaining statistics on table-valued parameters and table-valued parameters not permitted as the target of a SELECT INTO or INSERT EXEC statement. In addition, table-valued parameters can be passed only as READONLY input parameters to stored procedures. DML operations, such as UPDATE, INSERT, and DELETE, cannot be performed on table-valued parameters within the body of a stored procedure.

To create and use table-valued parameters, you must first create a user-defined table type and define the table structure. You do so using the CREATE TYPE command, as in the following example:

if exists (select * from sys.systypes t where t.name = 'ytdsales_tabletype'
                and t.uid = USER_ID('dbo'))
     drop type ytdsales_tabletype
go
CREATE TYPE ytdsales_tabletype AS TABLE
(title_id char(6),
 title varchar(50),
 pubdate date,
 ytd_sales int)
go

After the table data type is created, you can use it for declaring local table variables and for stored procedure parameters. To use the table-valued parameter in a procedure, you create a procedure to receive and access data through a table-valued parameter:

/* Create a procedure to receive data for the table-valued parameter. */
if OBJECT_ID('tab_parm_test') is not null
    drop proc tab_parm_test
go
create proc tab_parm_test
        @pubdate datetime = null,
        @sales_minimum int = 0,
        @ytd_sales_tab ytdsales_tabletype READONLY
as
set nocount on

if @pubdate is null
    -- if no date is specified, set date to last year
    set @pubdate = dateadd(month, -12, getdate())

select * from @ytd_sales_tab
where pubdate > @pubdate
and ytd_sales >= @sales_minimum
return
go

Then, when calling that stored procedure, you declare a local table variable using the table data type defined previously, populate the table variable with data, and then pass the table variable to the stored procedure:

/* Declare a variable that references the type. */
declare @ytd_sales_tab ytdsales_tabletype

/* Add data to the table variable. */
insert @ytd_sales_tab
    select title_id, convert(varchar(50), title), pubdate, ytd_sales
      from titles

/* Pass the table variable populated with data to a stored procedure. */
exec tab_parm_test '6/1/2001', 10000, @ytd_sales_tab
go

title_id title                                              ytd_sales
-------- -------------------------------------------------- -----------
BU2075   You Can Combat Computer Stress!                    18722
MC3021   The Gourmet Microwave                              22246
TC4203   Fifty Years in Buckingham Palace Kitchens          15096