Recipe 2.14 Passing Null Values to Parameters

Problem

You need to pass a null value to a parameter.

Solution

Use the System.DbNull.Value static value.

The sample code, as shown in Example 2-18, uses a single stored procedure:

SP0214_NullParameter

Accepts a single parameter and a returns one-row result set containing a single value indicating whether that input parameter was null.

Example 2-18. Stored procedure: SP0214_NullParameter

CREATE PROCEDURE SP0214_NullParameter
    @ValueIn int
AS
    if @ValueIn is null
        select 1 as IsParameterNull
    else
        select 0 as IsParameterNull

    return 0

The sample code contains two event handlers:

Go Button.Click

Creates a stored procedure command for SP0214_NullParameter and defines its single input parameter. The input parameter is set to System.DbNull.Value if the user has checked the Null Parameter check box on the form; otherwise it is set to the value that the user has entered in the Parameter text box. The stored procedure is executed using the ExecuteScalar( ) method and the value returned indicates whether the input parameter for the stored procedure is null.

Null Parameter CheckBox.CheckedChange

Clears the value of the Parameter text box if checked and enables the Parameter text box if not checked.

The C# code is shown in Example 2-19.

Example 2-19. File: NullParameterForm.cs

// Namespaces, variables, and constants
using System;
using System.Configuration;
using System.Data;
using System.Data.SqlClient;

//  . . . 

private void goButton_Click(object sender, System.EventArgs e)
{
    // Create the connection.
    SqlConnection conn = new SqlConnection(
        ConfigurationSettings.AppSettings["Sql_ConnectString"]);
    
    // Create the stored procedure command.
    SqlCommand cmd = new SqlCommand("SP0214_NullParameter", conn);
    cmd.CommandType = CommandType.StoredProcedure;

    // Define the parameter.
    cmd.Parameters.Add("@ValueIn", SqlDbType.Int);
    // Set the value of the paramter.
    if (isNullCheckBox.Checked)
        cmd.Parameters[0].Value = System.DBNull.Value;
    else
        cmd.Parameters[0].Value = parameterTextBox.Text;

    // Retrieve whether parameter null from stored procedure.
    try
    {
        conn.Open( );
        bool isNullParm = Convert.ToBoolean(cmd.ExecuteScalar( ));
        resultTextBox.Text = "Null Parameter = " + isNullParm;
    }
    catch (Exception ex)
    {
        resultTextBox.Text = ex.Message;
    }
    finally
    {
        conn.Close( );
    }
}

private void isNullCheckBox_CheckedChanged(object sender,
    System.EventArgs e)
{
    if(isNullCheckBox.Checked)
        parameterTextBox.Text = "";

    parameterTextBox.Enabled = !isNullCheckBox.Checked;
}

Discussion

System.DBNull is not the same as null in C# or Nothing in VB.NET. System.DBNull indicates that the object represents missing or nonexistent data, typically in a database, while null and Nothing indicate that an object or variable has not yet been initialized.

Passing a null parameter value into a stored procedure is not very different than passing any other parameter value. Construct the parameter using either the Parameter constructor or the Add( ) method of the ParameterCollection for the Command object. The value is set by passing System.DBNull.Value for the value argument when constructing the parameter or by setting the Value property of the Parameter object to System.DBNull.Value.

To test for a null value, the IsDBNull( ) method returns a Boolean value that indicates whether an object expression evaluates to System.DBNull. This is the same as comparing an object to the System.DBNull.Value using an equality operator.

If the stored procedure accepts optional parameters—parameters for which a default value is specified—you can set these parameters to null in C# or Nothing in VB.NET. This is not the same as setting the parameter value to System.DBNull.Value. The parameter value is set to the default value specified for the parameter.