Microsoft BizTalk Server 2004 Readme SP1

February 4th, 2005

**********************************************************************

© 2005 Microsoft Corporation. All rights reserved.

**********************************************************************

Welcome to Microsoft® BizTalk® Server 2004, Service Pack 1. This Readme contains important information about this release of BizTalk Server 2004.

Review this document before installing BizTalk Server 2004, Service Pack 1.

To make sure that you are reading the most up-to-date information, download the latest version of BizTalk Server 2004 Readme SP1, from http://go.microsoft.com/fwlink/?linkid=39416. For a list of the fixes in BizTalk Server 2004, Service Pack 1, see http://go.microsoft.com/fwlink/?linkid=39415.

For information about current known issues in BizTalk Server 2004, see Knowledge Base article 834624 located at http://go.microsoft.com/fwlink/?LinkId=22784. For the most current version of the BizTalk Server 2004 documentation, see http://go.microsoft.com/fwlink/?linkid=20616.

Note  Service Pack 1 does not include updates to the BizTalk Server 2004 SDK. To download the most recent update, go to http://go.microsoft.com/fwlink/?LinkId=24723. The documentation for backing up databases (log shipping) has also been revised. For the most current log shipping documentation, see http://go.microsoft.com/fwlink/?LinkId=38236.

To guarantee satisfactory performance, verify that the computers on which you install BizTalk Server 2004 meet the recommended hardware requirements and that you have installed all required software in the correct order. For information about hardware and software requirements for BizTalk Server 2004, see "BizTalk Server 2004 Installation Guide" at http://go.microsoft.com/fwlink/?LinkId=22120.

This document contains the following sections:

• Before You Install Service Pack 1
• Installing Service Pack 1
• Uninstalling Service Pack 1
• What's New in Service Pack 1
• Known Issues
• Contacting Product Support

Before You Install Service Pack 1

Note the following requirements:

• Only install Service Pack 1 (SP 1) on computers already running BizTalk Server 2004.
• You must install SP1 on all servers in a farm or group. Mixing SP1 with other versions is not supported.
• Service Pack 1 supports GB18030 (simplified Chinese) characters. Using these characters requires a custom Microsoft® SQL Server™ Setup program. For more information, see the Knowledge Base article, "Using GB18030 Characters in BizTalk Server 2004, Service Pack 1" at http://go.microsoft.com/fwlink/?linkid=39417.
• Back up your BizTalk Server 2004 databases. For information about backing up your databases, see "Backing Up Your Databases" in Microsoft BizTalk Server 2004 Help.
• Microsoft Windows XP, Service Pack 2, changes how the system handles remote procedure calls (RPC). You must make changes to the registry for Enterprise Single Sign-On and other BizTalk Server 2004 services to work. For more information, see Knowledge Base article 841893, "The Enterprise Single Sign-On Service and associated BizTalk Server 2004 services fail after you install Windows XP Service Pack 2 (SP2)" at http://go.microsoft.com/fwlink/?linkid=39453.

You do not have to re-deploy applications you deployed before installing BizTalk Server 2004 SP1.

Software Requirements

You must install the following software before installing Service Pack 1:

• Microsoft .NET Framework 1.1 Service Pack 1:
  • Available for Windows 2000 or Windows XP at http://go.microsoft.com/fwlink/?LinkId=42110.
  • Available for Windows Server 2003 at http://go.microsoft.com/fwlink/?LinkId=42111.
• BizTalk Server 2004 SP1 Update for .NET Framework 1.1:
  • Available for Windows 2000 and Windows XP at http://go.microsoft.com/fwlink/?LinkId=41671.
  • Available for Windows Server 2003 at http://go.microsoft.com/fwlink/?LinkId=41672.

  For more information about BizTalk Server 2004 SP1 Update for .NET Framework 1.1, see Knowledge Base article 890673 at http://go.microsoft.com/fwlink/?linkid=39454.

• Microsoft® Windows® XP Service Pack 2, if you are installing on Windows XP, available at http://go.microsoft.com/fwlink/?linkid=39455.
• Microsoft .NET Framework 1.1, Service Pack 1 available at http://go.microsoft.com/fwlink/?linkid=39456.
• SQLXML 3.0, Service Pack 2 available at http://go.microsoft.com/fwlink/?linkid=39457.
• Microsoft XML 3.0, Service Pack 4 available at http://go.microsoft.com/fwlink/?linkid=39458.

Installing Service Pack 1

The files for Service Pack 1 are in a single executable file, BizTalk 2004 Service Pack 1 <language>.exe, for example BizTalk 2004 Service Pack 1 ENU.exe. Double-clicking this file unpacks the readme file and an executable file, BTS2004-SP1-<language>.exe, to the directory you indicate in the dialog box. When you open this second executable file, the files are extracted to the current folder, and Setup.exe runs automatically.

Note  Use only the Setup.exe program to install the product. Do not use the individual Windows Installer files.

For information about silent installation, see Silent Installation.

If you encounter a problem during installation and no error message appears, review the log file, Setup.log. The default location of the file is C:\Documents and Settings\All Users\Application Data\Microsoft\E-Business Servers Updates\BTS2004\SP1\. A link to this file also appears on the last page of the installation wizard.

Under certain conditions, you may be prompted to restart the computer after installing SP1. This is normal.

Note  SP1 installation removes any custom access control lists (ACL) applied to a file or folder that it updates.

Note  SP1 overwrites the Backup BizTalk Server job.

Note  SP1 installs Microsoft® Windows® Installer 3.0, if it is required.

To install Service Pack 1

1. If you are using the EDI adapter, shut down EDI and let the remaining messages finish processing.
2. Use the script provided later in this readme to disable the receive locations; see Script to Disable or Enable Receive Locations. To run the script and disable receive locations, copy the code contents into a file named enabledisableallrecloc.vbs and type the following from a command line:

   cscript enabledisableallrecloc.vbs disable

3. In the Computer Management snap in, stop all BizTalk Server services and set the Startup Type for the BizTalk Server services to Manual. Be sure to do this on all computers in the server farm or group.
4. Run Setup.exe on all of the computers in the group or server farm.

   Note  SQL Server services must be running when you run Setup. If SQL Server services are not running, you will have to rerun Setup.

5. Restart the BizTalk Server services, and change the Startup Type back to its previous setting.
6. To enable all receive locations, type the following command to run the script:

   cscript enabledisableallrecloc.vbs enable

   Important  Only restart your computers if you are prompted to do so. Otherwise, you only need restart your services as specified in step 5.

Click here for the script to disable or enable receive locations

'-------------------------------------------------------------------------
'
' WMI script to enable/disable the receive locations
'
'-------------------------------------------------------------------------
' This file is part of the Microsoft BizTalk Server 2004 SDK
'
' Copyright (c) Microsoft Corporation. All rights reserved.
'
' This source code is intended only as a supplement to Microsoft BizTalk
' Server 2004 release and/or on-line documentation. See these other
' materials for detailed information regarding Microsoft code samples.
'
' THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
' KIND, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
' IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR
' PURPOSE.
'-------------------------------------------------------------------------

Option Explicit

EnumRecLocs
Sub EnumRecLocs()

    'error handling is done by explicity checking the err object rather 
    'than using the VB ON ERROR construct, so set to resume next on error.
    On Error Resume Next
    


'Get the command line arguments entered for the script
    Dim objArgs: Set objArgs = WScript.Arguments

    
    'Make sure the expected number of arguments were provided 
    'on the command line.
    'if not, print usage text and exit.
    If (objArgs.Count < 1) Or (objArgs.Count >1) Then
        PrintUsage()
        WScript.Quit 0
    End If
    dim sEnable:set sEnable = "FALSE"
    
    
    If (objArgs(0) = "enable") then
        sEnable = "TRUE"
    elseif (objArgs(0) = "disable" ) then
        sEnable = "FALSE"
    else
        PrintUsage()
        WScript.Quit 0
    end if

    on error resume next
    Dim InstSet, Inst
    set InstSet = GetObject ("winmgmts:\root\MicrosoftBizTalkServer").InstancesOf("MSBTS_ReceiveLocation")

    'Check for error condition before continuing.
    If Err <> 0    Then
        PrintWMIErrorThenExit Err.Description, Err.Number
    End If

    'Report on number of receive locations found and list each one.
    wscript.echo "A Total of " & InstSet.Count & " Receive Locations were found."
    If InstSet.Count > 0 Then
        For Each Inst In InstSet
            wscript.echo
            if ( sEnable = "TRUE" ) then
                wscript.echo "Enabling Receive Location: " & Inst.Name
            else
                wscript.echo "disabling Receive Location: " & Inst.Name
            end if
            wscript.echo "  Receive Port Name  : " & Inst.ReceivePortName

            EnableReceiveLocation Inst.ReceivePortName, Inst.Name ,sEnable
            wscript.echo
        next
    End If 
            
End Sub 


Sub EnableReceiveLocation(strReceivePortName, strReceiveLocationName, sEnable)
    
    'error handling is done by explicity checking the err object rather than using
    'the VB ON ERROR construct, so set to resume next on error.
    On Error Resume Next
    
    
    Dim objInstSet, objInst, strQuery
    
            
    

    'set up a WMI query to acquire a list of receive locations with the given Name and 
    'ReceivePortName key values.  This should be a list of zero or one Receive Locations.
    strQuery = "SELECT * FROM MSBTS_ReceiveLocation WHERE  ReceivePortName =""" & strReceivePortName & """AND Name =""" & strReceiveLocationName & """"
    Set objInstSet = GetObject("Winmgmts:!root\MicrosoftBizTalkServer").ExecQuery(strQuery)
    
    'Check for error condition before continuing.
    If Err <> 0    Then
        PrintWMIErrorThenExit Err.Description, Err.Number
    End If

    'If Receive Location found, enable it, otherwise print error and end.
    If objInstSet.Count > 0 then
        For Each objInst in objInstSet
            
            
            'Now enable /disable  receive location
            if sEnable= "TRUE" then
                objInst.Enable
            else
                objInst.Disable
            end if
            If Err <> 0    Then
                PrintWMIErrorThenExit Err.Description, Err.Number
            End If
            if sEnable = "TRUE" then
                WScript.Echo "The Receive Location was successfully enabled"
            else
                WScript.Echo "The Receive Location was successfully disabled"
            end if
        Next
    Else
        WScript.Echo "No Receive Location was found matching that Name."
    End If
            
End Sub 



'This subroutine deals with all errors using the WbemScripting object.  Error descriptions
'are returned to the user by printing to the console.
Sub    PrintWMIErrorThenExit(strErrDesc, ErrNum)
    On Error Resume    Next
    Dim    objWMIError    : Set objWMIError =    CreateObject("WbemScripting.SwbemLastError")

    If ( TypeName(objWMIError) = "Empty" ) Then
        wscript.echo strErrDesc & " (HRESULT: "    & Hex(ErrNum) & ")."
    Else
        wscript.echo objWMIError.Description & "(HRESULT: "    & Hex(ErrNum) & ")."
        Set objWMIError    = nothing
    End    If
    
    'bail out
    wscript.quit 0
End    Sub

Sub PrintUsage()
    WScript.Echo "Usage:" + Chr(10) + Chr(10) + _
                 "cscript enabledisableallrecloc [enable/disable]" + _
                 Chr(10) + "       Example to enable all receive locations: enabledisableallreclo enable "+ Chr(10) + Chr(10) 
                
End Sub

Adding or Removing Features, or Upgrading After Installing SP1

You can add or remove product features without re-installing SP1.

If you want to upgrade your BizTalk 2004 edition after installing SP1 (for example, from Standard to Enterprise), you must uninstall SP1. Install the new version of BizTalk Server, and then re-install SP1.

Note  You can upgrade from Partner to Standard, Partner to Enterprise, Standard to Enterprise, and Evaluation to Enterprise. You cannot upgrade from Developer to Partner, Developer to Standard, or Developer to Enterprise. Downgrades are not supported.

Silent Installation

You can install Service Pack 1 by running Setup.exe from the command line. Installation does not delete the files after it finishes or if you cancel the automatic Setup. Begin by copying the unpacked files to a folder. You can control the behavior of Setup through several command-line switches.

Setup takes the following command line switches:

To use setup.exe from the command line to install Service Pack 1

1. Open a Command Prompt window. Navigate to the directory where you copied the unpacked files.
2. At the command prompt, type Setup.exe /s, and press ENTER.
3. The installation runs without messages or confirmation screens.

Uninstalling Service Pack 1

Before you uninstall SP1, you must remove the configuration of any product features configured after SP1 installation.

Also, if you uninstall SP1, you must uninstall it on all servers in the Web farm or group. Be sure to stop all BizTalk Server services before uninstalling SP1.

Updates applied after Service Pack 1 remain in place and are not removed if you uninstall SP1. You must re-install updates that were applied before you installed Service Pack 1.

To check details of the uninstall, you can view the uninstall log file, Microsoft BizTalk Server 2004 Service Pack - (SP1)_uninstall.log in the Temp directory of the account you are logged in under. For example, for a user CurrentUser this directory is c:\Documents and Settings\CurrentUser\Local Settings\Temp.

To uninstall Service Pack 1

1. If you are using the EDI adapter, shut down EDI and let the remaining messages finish processing.
2. Stop the BizTalk Server services and disable receive locations. In the Computer Management snap in, set the Startup Type for the BizTalk Server services to Manual. Be sure to do this on all computers in the server farm or group.
3. Use Add or Remove Programs to uninstall Service Pack 1 on all of the machines in the group or server farm.

   Note  SQL Server services must be running when you uninstall. If SQL Server services are not running, you will have to redo the uninstall.

4. Restart the BizTalk Server services, change the Startup Type back to its previous setting, and enable the receive locations.

   Important  Do not restart any of the computers in the farm until you have uninstalled SP1 on all of the computers.

To uninstall BizTalk Server 2004 and Service Pack 1

• In Add or Remove Programs, select Microsoft BizTalk Server 2004 to uninstall both the service pack and the base product.

What's New in Service Pack 1

Microsoft® BizTalk® Server 2004, Service Pack 1 provides new performance counters, enables you to throttle the FTP adapter, adds additional transaction handling for pipeline components, provides more information in SQL Adapter error messages, and supports the use of GB18030 (simplified Chinese) characters.

This section contains:

• Performance Counters
• FTP Throttling
• IPipelineContextEx Interface
• Improved SQL Adapter Error Messages
• Using GB18030 Characters

Performance Counters

Service Pack 1 provides new, additional performance counters. The counters are all of type long.

For more information about performance counters, see "Performance Counters" in BizTalk Server 2004 Help.

FTP Throttling

You can throttle the FTP adapter by creating or setting a registry key entry, FtpMaxConcurrentConnections. This entry establishes the maximum number of send ports the adapter can use on a specified server. To throttle the FTP adapter on multiple servers, you must edit the registry key entry on each server.

If the key FtpMaxConcurrentConnections is absent or zero (0), the adapter uses the default value of two (2).

Warning  Incorrect use of Registry Editor may cause problems requiring you to reinstall your operating system. Use Registry Editor at your own risk.

To throttle the FTP adapter on a server

1. Click Start and then click Run.
2. In the Run text box, type regedit.exe to start Registry Editor.
3. Navigate to [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\BTSSvcguid] where guid is a GUID unique to each installation of BizTalk Server.
4. If FtpMaxConcurrentConnections is not present, create it: right-click BTSSvcguid, and then click DWORD Value. Give the new value the name FtpMaxConcurrentConnections.
5. Right-click FtpMaxConcurrentConnections in the right pane, select Modify, and type the new value in the Edit DWORD Value dialog box. Click OK.
6. Exit Registry Edit.

IPipelineContextEx Interface

The IPipelineContextEx interface extends IPipelineContext. It provides a method for a receive pipeline component to retrieve a DTC transaction object from the BizTalk engine.

IPipelineContextEx Interface

For the only member, see IPipelineContextEx.GetTransaction Method.

[Visual Basic]
<Guid("05AC2000-2ED5-41F0-A961-2838A1836A22")>
<InterfaceType(ComInterfaceType.InterfaceIsIUnknown)>
Public Interface IPipelineContextEx

[C#]
[Guid("05AC2000-2ED5-41F0-A961-2838A1836A22")]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IPipelineContextEx

[C++]
[Guid("05AC2000-2ED5-41F0-A961-2838A1836A22")]
[InterfaceType(ComInterfaceType::InterfaceIsIUnknown)]
public __gc __interface IPipelineContextEx

[JScript]
public
   Guid("05AC2000-2ED5-41F0-A961-2838A1836A22")
   InterfaceType(ComInterfaceType.InterfaceIsIUnknown)
interface IPipelineContextEx

Name space: Microsoft.BizTalk.Component.Interop

Platforms: Windows 2000, Windows XP Professional, Windows Server 2003

Assembly: Microsoft.BizTalk.Pipeline.dll

IPipelineContextEx.GetTransaction Method

Returns a DTC transaction object from the BizTalk engine.

[Visual Basic]
Function GetTransaction() As Object

[C#]
object GetTransaction();

[C++]
object* GetTransaction();

[JScript]
function GetTransaction() : object;

Use the following syntax to invoke the method as a member of a COM interface:

HRESULT GetTransaction([out, retval] IUnknown** ppVal);

GetTransaction returns a null reference if there is no transaction.

Note  Use GetTransaction only in receive pipelines. In a send pipeline, the method throws an "Object was open" exception.

During receive pipeline execution, if the BizTalk Server engine has a transaction, it makes a pointer to the transaction available to the pipeline context. Any component within a pipeline in any pipeline stage can request a transaction.

When processing a message batch, the engine uses the same transaction object for all pipeline components processing the batch. If there is no transaction for a batch, the first request for a transaction object starts a new transaction. Within a batch, all subsequent requests for a transaction receive the same transaction object.

When the BizTalk Server engine publishes the message or batch to a MessageBox, the engine commits the transaction if it created the transaction. If a receive adapter created the transaction, it is responsible for committing it.

The following code shows how you might use GetTransaction in a receive pipeline to retrieve the transaction from the BizTalk Server engine and perform an update within that transaction. The code assumes that the BizTalk Server engine creates and commits the transaction.

public IBaseMessage Execute(IPipelineContext pc, IBaseMessage inMsg)
{
    string customerId;
    string companyName;

    //TODO: Add the code to read the customerId 
    //      and companyName from the input message inMsg

    IPipelineContextEx pcx = pc as IPipelineContextEx;

    if (pcx != null)
    {
        ITransaction trans = null;
        trans = (ITransaction)pcx.GetTransaction();

        if (trans != null)
        {
            SqlConnection nwindConn = 
                new SqlConnection(
                "Data Source=localhost;Integrated Security=SSPI;" +
                "Initial Catalog=Northwind;Enlist=false;");
            SqlCommand cmd = 
                new SqlCommand(
                "INSERT INTO Customers (CustomerID, CompanyName) " +
                "Values(@CustomerId, @CompanyName)", nwindConn);

            cmd.Parameters.Add("@CustomerId", SqlDbType.VarChar, 5).Value 
                = customerId;
            cmd.Parameters.Add("@CompanyName", SqlDbType.VarChar, 
                40).Value = companyName;

            nwindConn.Open();
            pc.ResourceTracker.AddResource(nwindConn);

            nwindConn.EnlistDistributedTransaction(trans);

            try
            {
                cmd.ExecuteNonQuery();
            }
            catch (SqlException e)
            {
                throw(e);
            }
        }
        else
            throw new
            ArgumentNullException("IPipelineContextEx:GetTransaction()");
    }

    return inMsg;
}

Improved SQL Adapter Error Messages

SQL Adapter error messages now provide more information. You may need to make modifications to handle the longer error messages.

Using GB18030 Characters

You can use GB18030 (simplified Chinese) characters in Service Pack 1. Using these characters requires a custom Microsoft® SQL Server™ Setup. For more information, see the Knowledge Base article, "Using GB18030 Characters in BizTalk Server 2004, Service Pack 1" at http://go.microsoft.com/fwlink/?linkid=39417.

Known Issues

This section describes known issues with BizTalk Server 2004, Service Pack 1 in the following product areas:

• Installation Issues
• Adapter Issues

Installation Issues

Custom action or post-installation action fails

If SP1 installation ends with an error message such as "Installation succeeded but some post-installation actions failed," or "One of the custom actions failed," it may be because the SQL Server service was unavailable during installation.

Check the file Setup.log for errors. "Failed to resolve database" or "Failed to patch one or more BizTalk databases" errors may indicate that the SQL Server service was unavailable.

The default location of Setup.log is C:\Documents and Settings\All Users\Application Data\Microsoft\E-Business Servers Updates\BTS2004\SP1\. A link to this file also appears on the last page of the installation wizard.

Restart after prompt fails

In some cases, selecting the Restart option at the end of installation or uninstall may not restart the computer. Restart the computer manually.

Adapter Issues

BizTalk Message Queuing Adapter (MSMQT) configuration

When configuring MSMQT to use multiple computers in the same BizTalk group, you should first configure Network Load Balancing (NLB) for load balancing MSMQT. Use the Virtual NLB Cluster Name as the Computer Name in the Configuration Wizard on all computers.

For more information about Network Load Balancing, see Knowledge Base Article 323437, "How To Configure Network Load Balancing Parameters in Windows Server 2003" available at http://go.microsoft.com/fwlink/?linkid=39509

Contacting Product Support

If you have technical questions about Service Pack 1 not answered in this document or in the Microsoft Knowledge Base articles, Microsoft offers technical support and services.

• Product name: Microsoft® BizTalk® Server 2004, Service Pack 1
• Support options: To obtain the latest information about your support options, see the Microsoft Product Support Services Web site at http://go.microsoft.com/fwlink/?LinkId=36792.
• Worldwide support: Options, hours, and cost in your country or region may differ from the United States; contact your local office for details.
• Conditions: Microsoft Product Support Services are subject to the then-current prices, terms, and conditions at Microsoft, which are subject to change without notice.

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, e-mail address, logo, person, place, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Microsoft, MS-DOS, BizTalk, Windows, and Windows NT, are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.