DTS Example: Adding Properties and Icons in Visual C++

This example, shown in Microsoft® Visual C++®, displays a message when executed. The text of the message is provided by a property you add. To implement this example, do the following:

1. Create a framework for a custom task using the Active Template Library (ATL) custom task basic template.
   
   
2. Add a property for the message text.
   
   
3. Add an icon that appears when the task is used in Data Transformation Services (DTS) Designer.
   
   
4. Add code to implement the message and the property.
   
   
5. Build the project and run the custom task.

Creating the Task Framework

Create a custom task framework using the ATL custom task basic template provided with Microsoft SQL Server™ 2000. Name the component DTSTskPropIcon and the task class GenMessage. Change the Type field in ATL Object Wizard from GenMessage Class to Generate Message Task. For more information about using the basic template, see Building a Custom Task from the ATL Custom Task Basic Template.

Adding the Message Property

Add the Message property to the custom task.

To add the Message property

1. On the ClassView tab of the Workspace window, right-click the IGenMessage interface, and then click Add Property.
   
   
2. In the Add Property to Interface dialog box, in the Property Type list, select BSTR, and then in the Property Name box, enter Message.
   
   
3. Click Attributes, and then change the helpstring from property Message to Message to be displayed.

Adding an Icon

Select a suitable icon for the task for which you have an .ico file.

To add an icon

1. On the File menu, click Resources.
   
   
2. In the Insert Resource dialog box, under Resource Type, select Icon, and then click Import.
   
   
3. In the Import Resource dialog box, browse to find the .ico file.

   When you select a file, the icon editor is displayed. If you make changes to the icon, you must edit both the 16x16 and 32x32 bit images.

This procedure makes a local copy of the icon file in the project directory whether or not you made changes in the icon editor.

Adding Implementation Code

Add the following code segments to the framework files:

• A local variable to hold the value of the Message property
  
  
• Code to initialize and release the Message property value
  
  
• Code to retrieve and save the Message property value
  
  
• Code to display the message when the task is executed

Adding a Local Variable Declaration

The declaration goes in the private section for the CGenMessage class, in file GenMessage.h.

Immediately after the lines:

    BSTR    m_bstrName;
    BSTR    m_bstrDescription;

insert the line:

    BSTR    m_bstrMessage;

Initializing and Releasing the Message Property Value

The Message property must be initialized to a valid value. This is done in the task class constructor in GenMessage.cpp.

At the end of the task class constructor (before the right curly bracket):

CGenMessage::CGenMessage()

add this line:

        m_bstrMessage = SysAllocString( OLESTR("") );

The allocated string must be released before the custom task is removed from memory. This is done in the class destructor, also in GenMessage.cpp.

At the end of the destructor (before the right curly bracket):

CGenMessage::~CGenMessage()

add this line:

        if (m_bstrMessage) SysFreeString(m_bstrMessage);

Example

The property value must be retrieved in get_Message and saved in put_Message. These functions are in file GenMessage.cpp.

Replace the // TODO comment in CGenMessage::get_Message with the following code:

    if (!pVal)
        return E_POINTER;
    *pVal = SysAllocString(m_bstrMessage);
    if (!*pVal)
        return E_OUTOFMEMORY;

Replace the // TODO comment in CGenMessage::put_Message with the following code:

    if (m_bstrMessage)
        SysFreeString(m_bstrMessage);
    m_bstrMessage = SysAllocString(newVal);
    if (!m_bstrMessage)
        return E_OUTOFMEMORY;

    MessageBox( NULL, OLE2T( (LPOLESTR)m_bstrMessage ), 
                OLE2T( (LPOLESTR)m_bstrDescription ), MB_ICONINFORMATION );